SDK for Java 3.2 Start Page

Microsoft SDK for Java

Getting Started for First-Time Users
Introduces the Microsoft® SDK for Java to first-time users and explains its contents and features.

Release Notes
Describes what's new in this release, documents known issues and deprecated classes, and identifies the files that you may redistribute with your applications.

End-User License Agreement
Read the EULA before using the SDK for Java.

Developer Support This link takes you to a site on microsoft.com
Provides information on the developer support choices available to you. For additional support options, see Support Phone Numbers and Options. This link takes you to a site on microsoft.com

Microsoft Technologies for Java Web Site This link takes you to a site on microsoft.com
Provides product news updates, technical articles, and links to useful resources.

Is the documentation helpful? We'd like to know. Please send any comments and suggestions you have to: sdk_docs@microsoft.com. Thank you.

Highlights

Read about the latest features and enhancements in What's New.

Use the Samples Overview as a roadmap to over 90 samples in the SDK.

Check out some White Papers.

See the expanded information about Java/COM Integration and J/Direct, including the updated Compiler Directives Reference and Attributes Reference.

Find out more about the Microsoft virtual machine.


Getting Started for First-Time Users

The following topics introduce the Microsoft SDK for Java (SDK) to first-time users and explain its contents and features:

What is the SDK?

What can I do with the SDK?

What is covered in the SDK documentation?

What is not covered by the SDK?

How can I start using the SDK?

What special things do I need to know?

How do I find information in the SDK documentation?

What is the SDK?

Microsoft SDK for Java stands for Microsoft Software Development Kit for Java. The SDK contains a collection of Java tools for compiling source code and executing commands, samples that demonstrate the use of Java with other technologies, Java packages, which are collections of classes that share a common namespace, and extensive documentation on the most important SDK features.

What can I do with the SDK?

Here are some of the ways that you can use the SDK's components.

Java Packages

A Java package is a collection of classes that share a common namespace. The Microsoft SDK for Java contains over 20 packages that let you work with different features of the Java language. The com.ms.com package, for example, covers the Component Object Model (COM) services from Java. The com.ms.security package provides access to classes that control the security system. The com.ms.wfc package enables you to write full-featured Microsoft® Windows®-based applications with the Java programming language, and so on. The Microsoft packages provide access to features that are not included in the standard Java packages. For example, the com.ms.awt package gives you access to Microsoft® Win32® system-level features.

For information on all packages that are included in the SDK, see the Microsoft Packages Reference.

SDK Tools

The tools in the %SDKDIR%\Bin directory help you can compile your own source code or sample source code (jvc.exe). You can then execute it from the command line (Jview.exe) or view it in the appletviewer (Appletviewer.exe). You can also sign cabinet files (Signcode.exe), check files for their validity (Chktrust.exe), register Java classes as COM components (Setreg.exe), and much more. Some of the SDK tools are also available in versions that run on Compaq DIGITAL Alpha machines. These tools are located in the %SDKDIR%\BinAlpha directory.

For more detailed information on the tools, see the Tools Reference.

SDK Samples

The Microsoft SDK for Java includes over 90 samples that can be used as a reference for Java application development. When you download the SDK, these samples are installed in the %SDKDIR%\Samples folder and its subfolders. A description of each sample, installation, and usage instructions are provided. The Start page in the Samples folder contains an overview of the samples and links to each sample’s description.

What is covered in the SDK Documentation?

The Microsoft SDK for Java documentation, which is located in the %SDKDIR%\Docs directory, provides information for both the experienced Java developer and the beginner:

  • The Programmer’s Guide provides information on the Microsoft virtual machine (Microsoft VM), integrating Java and COM, security, integrating Java and Microsoft® Win32®, Windows Foundation Classes (WFC), and many more subjects.

  • The White Papers include either technical background articles that offer a general introduction to a technology or tutorials with how-to information. They also include sample code that addresses more specific programming solutions.

  • The Microsoft Packages Reference contains detailed reference information on all packages that are included in the SDK.

  • The Debugger Interfaces Reference describes the debugger interfaces and their methods.

  • The Profiler Interfaces Reference describes the Java profiler interfaces, which assist in the analysis of code for speed, memory use, redundancy, and other performance factors.

  • The Raw Native Interface Reference describes the functions and structures defined in the Native.h and Nativcom.h header files. These functions are used by the Raw Native Interface (RNI) defined by the Microsoft VM for efficiently interfacing Java code with native code.

  • The Invocation Interfaces Reference describes the invocation interfaces that are used to launch applications in the Microsoft VM.

  • The Compiler Directives Reference explains the syntax and attributes of the Microsoft Java compiler directives, lists their related attributes and directives, and gives usage examples. Microsoft Java compiler directives are optional special comments inserted in source code to aid in Java/COM integration and development.

  • The Windows Foundation Classes for Java section of the Programmer's Guide briefly describes the Windows Foundation Classes (WFC) and introduces additional WFC topics. The Microsoft Packages Reference lists all WFC packages that are included in the Microsoft SDK for Java and provides links to reference information on each package.

  • The Tools Reference describes all the SDK tools.

  • The Samples Overview briefly describes all the SDK samples.

What is not covered by the SDK for Java?

The Microsoft SDK for Java is not a GUI development environment with menus, buttons, toolbars, and so on. Most of the tools in the SDK are run from the MS-DOS® command line or with executable applications.

The Microsoft SDK for Java assumes some knowledge of command-line–driven compilers and other tools. You can become familiar with these tools by studying a beginner’s Java book, and then compiling and executing its source code with the tools in the Microsoft SDK for Java.

Scripting is not covered in the Microsoft SDK for Java. For detailed information on scripting and Microsoft® JScript® (Microsoft's implementation of the ECMA 262 language specification), visit the JScript home page at http://msdn.microsoft.com/scripting This link takes you to a site on microsoft.com.

If you want to work with a Java development tool and develop your own Java applications or applets, Microsoft® Visual J++® version 6.0 is the best application. With Visual J++ 6.0, developers can rapidly construct Microsoft® Windows®-based applications and components using two-way rapid application development (RAD) tools and WFC, an object-oriented framework that encapsulates and simplifies the Microsoft® Win32® API. For more information or to download Visual J++, see the Visual J++ home page at http://msdn.microsoft.com/visualj/default.asp This link takes you to a site on microsoft.com.

How can I start using the SDK?

Visit the Microsoft® Technologies for Java home page frequently at http://www.microsoft.com/java/ This link takes you to a site on microsoft.com. Here you can find the latest news and updates to the SDK and the Microsoft virtual machine (Microsoft VM).

To download the SDK, choose Downloads, and then SDK for Java from the menu bar on the Microsoft Technologies for Java home page.

Important If you have Visual J++ installed, you must replace three files in Visual J++ with their SDK versions:

  1. Back up the current Visual J++ versions of Jvc.exe, Jps.dll, and Msjvc.dll.

  2. Copy Jvc.exe, Jps.dll, and Msjvc.dll from %SDKDIR%\Bin to your Visual J++ directory. Projects will then build using the new compiler.

The Finding Information section of the Microsoft SDK for Java documentation contains important information on how to use the documentation's Help Viewer, including using the toolbar buttons, using full text search, finding a Help topic, and much more.

What special things do I need to know?

There are a few additional procedures you might need to perform after installing the SDK. All the procedures are performed in the MS-DOS® Command Prompt window.

To open the Command Prompt window

From the Start menu, select Programs, and then select MS-DOS® Command Prompt.

Including the \Bin Directory in Your Path

To ensure error-free functioning of the SDK, you should add the \Bin directory to your path.

To check if Setup has automatically added \Bin to your path

In the MS-DOS® Command Prompt window, type Path and press ENTER. If you see %SDKDIR%\Bin on your path, continue as normal.

To set your path manually

In the Command Prompt window, type:

set path=%path%;c:\<directory where SDK is installed>\bin

Displaying Help on Tools

To view information on the different options of a tool

  1. In the Command Prompt window, change to the \Bin directory.

  2. Type the following:

    <tool name> /?

    For example, to display help on jview, type:

    jview /?

Installing the Java Classes

The Microsoft SDK for Java contains two versions of the Java classes: the debug version (ClassD) and the retail version (ClassR).

To install either version of the Java classes

  1. In the MS-DOS® Command Prompt window, change to the \Bin directory.

  2. Type ClassD or ClassR and press ENTER.

Note You must install the Microsoft VM for Java before you install the classes.

Turning on the Microsoft Java Compiler Directives

The Microsoft Java compiler directives are optional special comments inserted in source code to aid in Java/COM integration and development. These compiler directives are turned off by default.

To turn on the compiler directives

  1. In the Command Prompt window, change to the \Bin directory.

  2. Type jvc /x- and press ENTER.

© 1999 Microsoft Corporation. All rights reserved. Terms of use.


Finding Information

The documentation set for the Microsoft® SDK for Java is organized to make finding information easy. It includes a Table of Contents that lists classes, methods, fields, an Index, and so on.

The topics in the Programmer's Guide contain overview and how-to information on using the APIs, packages, and samples that the Microsoft SDK for Java provides to help you develop Java programs and applets. These topics link to their appropriate Reference topics.

The Tools Reference is now a separate topic rather than being included in the Programmer’s Guide.

The Reference topics provide detailed coverage of packages and their members including all major classes, constructors, methods, interfaces, and fields.

This release also includes Document Conventions and a Glossary.

Using the Help Viewer

The Help Viewer has an easy to use, straightforward interface. The following topics show how to take advantage of its many features:

Using the Toolbar Buttons
Finding a Help Topic
Full-Text Search
Highlighting Words in Searched Topics
Using Favorites
Using Accessibility Shortcut Keys in the Help Viewer

Using the Toolbar Buttons

The Help Viewer toolbar usually contains the following buttons:

Hide/Show expands or collapses the left pane (table of contents).

Locate synchronizes the displayed topic with its corresponding title in the table of contents.

Previous opens the previous help topic.

Next opens the next help topic.

Back opens the last viewed help topic.

Forward displays the next help topic in a previously displayed sequence of topics.

Stop terminates a download from an external site.

Refresh repeats a download from an external site.

Home opens the Home page topic for the Help file you are viewing.

Font increases or decreases the font size of the topic you are viewing.

Print opens the Print dialog box.

Options opens a menu of customization settings.

Finding a Help Topic

HTML Viewer has three tabs to help you find the topic you're looking for.

Contents

Use the Contents tab to browse through a table of contents, an expandable list of important topics.

Index

Use the Index tab to see a list of index entries; topics are often indexed under more than one entry.

Search

Use the Search tab to locate every occurrence of a word or phrase.

Click the Contents entry, Index entry, or Search results entry to display the corresponding topic. To see the topic’s location in the table of contents, click Locate on the toolbar.

Full-Text Search

  1. Click the Search tab.

  2. Type the word you want to find.
    If you need to locate a phrase, enclose it in double quotes.
    For example, when searching for the phrase Java/COM integration, use "Java/COM integration." If you search for phrases without using double quotes, your results will display separate word occurrences. That is, you’ll get results for "Java," "COM," and "Integration" rather than occurrences of the entire phrase.

    If you have other search requirements, click the right arrow at the end of the search’s text box. Add between the words you are searching for, such as "Java" AND "COM" NOT Native.

  3. Click List Topics.

  4. Select the topic you want, and then click Display.

Highlighting Words in Searched Topics

  1. Click Options.

  2. Click Search Highlight On.

To turn this option off, click Options, and then click Search Highlight Off.

Using Favorites

The Favorites tab conveniently stores your frequently used Help Viewer topics.

  1. Navigate to a topic.

  2. Click the Favorites tab.

  3. Click Add.

Topics can be as quickly removed from Favorites.

  1. Select the topic to be removed.

  2. Click Remove.

Using Accessibility Shortcut Keys in the Help Viewer

Use the keyboard shortcuts shown in the following table to navigate the Help Viewer.

Help Viewer

To do this | Press
Close the Help Viewer. | ALT+F4
Switch between the Help Viewer and other open windows. | ALT+TAB
Display the Options menu (if your Viewer has an Options menu). | ALT+O
Hide or show the Navigation pane. | ALT+O, and then press T
Print a topic. | ALT+O, and then press P
Refresh the topic that appears in the Topic pane. | ALT+O, and then press R
Move back to the previous topic. | ALT+O, and then press B
Move forward to the next topic (provided you have viewed it just previously). | ALT+O, and then press F
Switch focus between the Navigation pane and the Topic pane. | F6
Scroll through a topic. | UP ARROW or DOWN ARROW (or, to move to the end or beginning of a topic, END or HOME, respectively)
Scroll through the links in a topic, or through all the options on a Navigation pane tab. | TAB

Contents Tab

To do this | Press
Display the Contents tab. | ALT+C
Open a book or folder. | RIGHT ARROW
Close a book or folder. | LEFT ARROW
Select a topic. | DOWN ARROW or UP ARROW
Display the selected topic. | ENTER

Index Tab

To do this | Press
Display the Index tab. | ALT+N
Select a keyword in the list. | UP ARROW or DOWN ARROW
Display the associated topic. | ALT+D

Search tab

To do this | Press
Display the Search tab. | ALT+S
Start a search. | ALT+L
Select a topic in the results list. | ALT+T, and then UP ARROW or DOWN ARROW
Display the selected topic. | ALT+D

For more information about accessibility features and services, visit the Microsoft Accessibility and Disabilities Web site at http://www.microsoft.com/enable/default-u.htm This link takes you to a site on microsoft.com.


Release Notes - Microsoft SDK for Java Version 4.0

Welcome to the Microsoft® SDK for Java, version 4.0. The SDK for Java is designed to work with the award-winning Microsoft® virtual machine (Microsoft VM) as well as packages, tools, samples, and documentation. See the What's New section for details and for information about the new features and enhancements in this SDK release.

Note Microsoft Application Foundation Classes (AFC) are not included in the SDK for Java. Versions 1.0.2 and 1.1 of AFC, the AWT2AFC tool, and all AFC documentation (in HTML Help format) are now available in the new Microsoft SDK for AFC This link takes you to a site on microsoft.com. AFC samples are included in both the SDK for Java and SDK for AFC. To run the AFC 1.0.2 samples, you must install the SDK for AFC and run AFC 1.0.2.

These release notes include the following topics:

What's New
Known Issues
Deprecated Classes
Microsoft VM Updates
Documentation Updates
End User License Agreement
Redistributable Files
Internationalization Support
Microsoft DirectX
Microsoft DirectAnimation
Microsoft JDBC-ODBC Bridge

Note on product names used in this release:

  • When "Microsoft SDK for Java" is used, it refers to version 4.0 unless otherwise specified.

  • When "Microsoft® Internet Explorer" is used, it refers to version 4.0 or later unless otherwise specified.

  • When "Microsoft virtual machine" or "Microsoft VM" is used, it refers to the build of the VM that is shipped with the Microsoft SDK for Java version 4.0.

  • When "Microsoft® Visual J++® Compiler," "Java Language Compiler," or "jvc" is used, it refers to the build of the jvc that is shipped with the Microsoft SDK for Java version 4.0.

  • When "Microsoft® Windows NT®" is used, it refers to Windows NT 4.0 or earlier. The version beyond Windows NT 4.0 is called "Microsoft® Windows® 2000."


What's New

 Microsoft SDK for Java

Release Notes - What's New

This topic covers new features and other enhancements that come with the SDK for Java, version 4.0.

Note The build numbers of the Microsoft VM and jvc for this SDK release can be found in Build.txt, located in the SDK's Relnotes folder.

Microsoft VM Enhancements
New Development Tools and Utilities
New Classes, Interfaces, and Methods
New Samples
New Documentation

Microsoft VM Enhancements

For information on Microsoft VM issues that have been fixed, see Microsoft VM Updates. Information on fixes to the Microsoft VM after the SDK for Java 4.0 release will be posted to http://www.microsoft.com/java/download.htm This link takes you to a site on microsoft.com.

The current release of the Microsoft VM continues its performance leadership and includes:

JDK 1.1 support

  • JDK 1.1 is supported (with the exception of RMI, which is freely available from our ftp site This link takes you to a site on microsoft.com).

Expanded Compaq DIGITAL Alpha Support

  • Vjreg, a command-line tool that registers Java classes as COM components in the Microsoft® Windows® registry, is now available for the Compaq DIGITAL Alpha platform and is located in the SDK for Java Binalpha folder.

    Be sure to have the CLASSPATH environment variable set correctly. Include the Bin folder for x86 architectures and the Binalpha folder for Compaq DIGITAL Alpha architectures. For more information on this and other tools, see the Tools Reference topic.

Year 2000 (Y2K) Compliance

  • For information about Microsoft VM Y2K compliance, see http://www.microsoft.com/technet/year2k/product/product.asp This link takes you to a site on microsoft.com and select Microsoft Virtual Machine under Technology in the Select Products list.

Java/COM Integration

  • A new way has been provided to express limited iid_is and size_is support in @com directives using existing compiler syntax. For details, see the @com.method and @com.parameters documentation.

  • The topic Creating a Custom Class Object describes how to extend the Microsoft VM's default class object (class factory).

  • The topic iid_is and size_is Support describes the mapping of Interface Definition Language (IDL) iid_is and size_is information to @com.parameters declarations.

    There are several new samples that demonstrate this and other aspects of Java/COM integration. See the New Samples section.

Miscellaneous

  • The problem of superfluous QueryInterface calls has been addressed. The Microsoft VM now quickly recognizes interface pointers without first attempting to unwrap them as Java-implemented objects.

  • JIT bugs and other miscellaneous bugs have been fixed.

  • Debugger fixes and enhancements and Profiler fixes.

  • Support for marshaling Delegates as IDispatch function pointers, used by clients such as the Microsoft® Internet Explorer scripting engines. Delegates can be used as a script function pointer, which are used in HTML for things like document and window events. The COM wrapper for a delegate supports IDispatch where DISPID_VALUE causes the delegate's invoke( ) method to be called.

For more documentation on the Microsoft VM, see Microsoft Virtual Machine.

New Development Tools and Utilities

Tools and utilities are located in the Bin folder (for x86 architectures) and the Binalpha folder (for Compaq DIGITAL Alpha architectures). Be sure to have the CLASSPATH environment variable set correctly.

Expanded Compaq DIGITAL Alpha Support

  • Vjreg, a command-line tool that registers Java classes as COM components in the Microsoft® Windows® registry, is now available for the Compaq DIGITAL Alpha platform and is located in the SDK for Java Binalpha folder.

Microsoft Compiler for Java

The Microsoft Compiler for Java (jvc) supports JDK 1.1 (with the exception of RMI, which is freely available from our ftp site This link takes you to a site on microsoft.com).

In this version of jvc, the /x option that disables Microsoft extensions is the default setting. For more information about jvc command-line options and error messages, see Jvc.

Note For users of Microsoft® Visual J++®, the Samples contained within the Microsoft SDK for Java support newer features supported by the Microsoft Compiler for Java (Jvc.exe).

To use these new language features with Microsoft® Visual J++® and the Microsoft SDK for Java Samples, you must replace three files in Visual J++ with their respective SDK versions:

  1. Back up the current Visual J++ versions of Jvc.exe, Jps.dll, and Msjvc.dll.

  2. Copy Jvc.exe, Jps.dll, and Msjvc.dll from %SDKDIR%\Bin to your Visual J++ directory. Projects and samples will then build using the new compiler.

VM Uninstaller

Uninstaller.exe removes the Microsoft virtual machine from the computer.

IntegrationClasses.exe

IntegrationClasses.exe installs additional com.ms packages for integration purposes. IntegrationClasses2000.exe is for use on computers running Microsoft® Windows® 2000. It installs packages such as com.ms.iis.asp, which is required for running the ASP Java Component Framework Samples. It also installs com.ms.ie, which contains 47 class files that are hooks for Java into Microsoft® Internet Explorer.

New Classes, Interfaces, and Methods

This section organizes the additions according to the version of the Microsoft VM to which they apply.

Microsoft VM versions 2436 through 2925
Microsoft VM versions 2925 through 3167
Microsoft VM versions 3167 through 3234

Microsoft VM versions 2436 through 2925

  • The following methods were added to the com.ms.lang.SystemX class:

    blockcopy
    compareString
    exitProcessAfterMainThreadReturns

  • The following methods were added to the com.ms.security.PermissionUtils class, but are not documented (by design):

    unescapeChars
    requiresQuotes
    escapeString
    escapeChars
    unescapeString

  • The following AFC methods were added, and are documented in the Microsoft® SDK for Application Foundation Classes:

    com.ms.ui.IUIComponent com.ms.ui.AwtUIChoice.add(java.lang.String)
    com.ms.fx.FxGraphics.drawFocusRect(int,int,int,int)
    com.ms.fx.IFxSystemInterface.callRootOnEventThread(com.ms.ui.UIRoot)
    com.ms.fx.FxComponentImage.getImage(int, int, int,
    java.awt.Color, java.awt.Color)

  • The following method and constructor were added to the com.ms.com.Variant class:

    toScriptObject
    Variant(Object value, boolean unwrapScriptObjects)

  • The following methods were added to the com.ms.com.ComLib class:

    unknownToPtr
    ptrRelease
    ptrToUnknown
    makeProxyRef
    executeOnContext

  • The following methods were added to the com.ms.dll.DllLib class:

    stringToHGlobalAnsi
    copyUni
    propagateStructFields
    stringToCoTaskMemAnsi
    stringToHGlobalAnsi

  • The following classes were added to the com.ms.win32 package:

    EnumFontFamExProc
    NEWTEXTMETRIC
    NEWTEXTMETRICEX
    REBARBANDINFO_IE4
    win
    Win32Lib
    windynamic

Note By design, individual members of the com.ms.win32 package are not documented.

  • The following RNI functions were added:

    PrepareThreadForJavaEx
    execute_java_constructor_method
    execute_java_constructor_methodV
    do_execute_java_methodV
    javaStringLengthAsCString
    Class_GetConstantPoolCount
    Class_CopyConstantPoolItem
    ClassObjectToClassClass
    ClassClassToClassObject
    Thread_IsInterrupted
    AddPathClassSource
    AddModuleResourceClassSource
    GetCurrentJavaTimeMillis

  • The ThreadLocalStorage class was added to the com.ms.util package.

  • The Debugger class was added to the com.ms.debug package.

Microsoft VM versions 2925 through 3167

  • The following methods were added to the com.ms.awt.GraphicsX class:

    drawNativeEdge
    drawNativeFocusRect

  • The setPeriod method was added to the com.ms.util.Timer class, but is not documented. This is by design.

  • The following AFC methods were added to the com.ms.ui.UIEdit class, and are documented in the Microsoft SDK for Application Foundation Classes:

    isUndoAllowed
    allowUndo

  • The following methods were added to the com.ms.com.ComLib class:

    startMTAThread
    getGuidOf
    ptrToStruct

  • The following methods were added to the com.ms.com.STATSTG class:

    getCLSID
    setCLSID

  • The following method was added to the com.ms.dll.DllLib class:

    ptrToStruct

  • The following interfaces were added to the com.ms.com package:

    IBindCtx
    IClassFactory
    IConnectionPoint
    IConnectionPointContainer
    IEnumConnectionPoints
    IEnumConnections
    IEnumMoniker
    IEnumSTATSTG
    IEnumString
    IEnumUnknown
    ILockBytes
    IMarshal
    IMoniker
    IParseDisplayName
    IPersist
    IPersistFile
    IPersistStorage
    IPeristStream
    IPersistStreamInit
    IROTData
    IRunningObjectTable
    ISequentialStream
    IStorage

  • The following classes were added to the com.ms.com package:

    BIND_OPTS
    CONNECTDATA
    COAUTHINFO
    COAUTHIDENTITY
    COSERVERINFO
    MULTI_QI

  • The following classes were added to the com.ms.win32 package:

    Ole32
    oleacc

  • The following method and two constructors were added to the com.ms.win32.FILETIME class:

    getTimeLong()
    FILETIME(int, int)
    FILETIME(long)

  • New constants were added to these classes:

    com.ms.win32.winb
    com.ms.win32.winc
    com.ms.win32.winl
    com.ms.win32.winm
    com.ms.win32.winr
    com.ms.win32.wins

Note By design, individual members of the com.ms.win32 package are not documented.

  • The following RNI methods were added:

    FindClassFromClass
    ClassArrayAlloc2
    GetNativeMethodsClass
    GetNativeMethodsMethodInfo

Microsoft VM versions 3167 through 3234

  • The following methods were added to the Ole32 class of the com.ms.win32 package:

    CoSetProxyBlanket( )
    CoQueryProxyBlanket( )

Note By design, individual members of the com.ms.win32 package are not documented.

  • The following method and fields were added to the com.ms.com.ComLib class:

    freeUnusedLibraries( )
    IID_IUnknown
    IID_IDispatch

  • The following classes were added to the com.ms.com package:

    LICINFO
    StdCOMClassObject

  • The following interfaces were added to the com.ms.com package:

    IClassFactory2
    ICreateErrorInfo
    IErrorInfo

  • Added the com.ms.ie package to the Microsoft Packages Reference.

New Samples

The following samples are new and are located in subdirectories of %SDKDIR%\Samples:

COM

Location: Samples\com\jexegen\stub
Location: Samples\com\custommarshal\vardate
Location: Samples\com\COMClassObject
Location: Samples\com\iid_is_size_is

Java Media Player

Location: Samples\jdirect\mediaplayer

Heap Monitor

Location: Samples\profiler\heapmon

ASP Java Component Framework Samples

Location: Samples\ASP

For more information on samples, see the Samples Overview.

New Documentation

For a list of revisions made to the documentation since the last SDK release, see Documentation Updates.

Locations for the Available Documentation

Part | Location | Description
SDKdocs | %SDKDIR%\Docs\Sdkdocs.chm www.microsoft.com/java/sdk/40/Start.htm | Microsoft SDK for Java
Integration | %SDKDIR%\Docs\Integration.chm | White papers and Java package reference information for integrating Java with Microsoft technologies
Javadocs | %SDKDIR%\Docs\Javadocs.chm | Java 1.1 Core API
Samples | %SDKDIR%\Samples\Start.htm | Samples included in the SDK for Java


Known Issues

 Microsoft SDK for Java

Release Notes - Known Issues

This topic documents the following known issues for this release:

Unexpected Stepping Behavior
Using Package-Managed Classes with Existing Tools
Calling the ActiveXControl Class
XML Issues

Note The build numbers of the Microsoft virtual machine (Microsoft VM) and jvc for this SDK release can be found in the file Build.txt, located in the Relnotes folder of the SDK.

For information on Microsoft VM issues that have been fixed, see Microsoft VM Updates. Information on fixes to the Microsoft VM after the SDK for Java 4.0 release will be posted to http://www.microsoft.com/java/download.htm This link takes you to a site on microsoft.com.

Unexpected Stepping Behavior

Using the latest Microsoft VM with an older version of Microsoft® Visual J++® may result in unexpected stepping behavior because of optimizations done by the Just-In-Time (JIT) compiler.

Using Package-Managed Classes with Existing Tools

If you are using package-managed classes with existing tools, note the following updates:

A tool called clspack creates all the .zip files that are usually included in %Windir%\Java\Classes, and are now stored in the package manager. The clspack tool is provided in the SDK\Bin directory. You can use clspack by setting the path to the SDK\Bin (set path=C:\%SDKDIR%\Bin;%path%) or copying it into %Windir% directory.

In addition, the value of the CLASSPATH environment variable registry setting is prepended with a reference to this generated Classes.zip file (if one is not currently there). The compiler provided with the SDK (Jvc.exe) checks this location by default for classes; there is no need to set the CLASSPATH environment variable.

For other compilers that do not check this location by default, set the CLASSPATH environment variable before running the compiler as follows: set CLASSPATH=%Windir%\Java\Classes\Classes.zip. For easy use, consider placing this command in a batch file.

Calling the ActiveXControl Class

Any class calling the ActiveXControl class needs to be trusted. If an applet intends to host a Microsoft® ActiveX® Control using the ActiveXControl class, it needs to be signed with the Fully Trusted permission. Any class calling the ActiveXControl class needs to be on the class path or have the right permissions ascribed to it through package management. If the jactivex tool is used to host an ActiveX Control, the classes output by the tool will use the ActiveXControl class. Any code using the classes output by jactivex, therefore, needs to be trusted.

XML Issues

The Microsoft XML functionality provided by the classes in the com.ms.xml package and subpackages, including the Microsoft® XML Data Source Object (DSO), is not fully compliant with the W3C specification. These classes, first shipped with Microsoft® Internet Explorer 4, are deprecated and have not been updated to reflect W3C activities or other more current Microsoft XML technologies. It is recommended that developers use the newer Microsoft® XML parser, msxml.dll.

For more information about using this newer XML parser, see the XML Faq http://msdn.microsoft.com/xml/general/xmlfaq.asp on the Microsoft® MSDN™ Web Site. This link takes you to a site on microsoft.com.


Deprecated Classes

 Microsoft SDK for Java

Release Notes - Deprecated Classes

The following are deprecated:

  • IJavaEventMonitorIDInfo2::GetProfilingCapabilities
    IJavaEventMonitor::NotifyEvent

    JVM_EVENT_TYPE_RESERVED_14 This event type, formerly called JVM_EVENT_TYPE_SHUTDOWN_ERROR, is deprecated and no longer dispatched by the Microsoft VM.

    JVM_EVENT_TYPE_RESERVED_15 This event type, formerly called JVM_EVENT_TYPE_SHUTDOWN_INTERRUPTED, is deprecated and no longer dispatched by the Microsoft VM.

  • com.ms.com.ComLib.threadStartMTA( ) initializes a thread without initializing COM. This method is deprecated. It is replaced by startMTAThread.

  • The IRemoteProcess interface TraceMethods method is deprecated.

  • The IRemoteProcessCallbackEx2 interface ExceptionEvent method is deprecated.

  • The following Java Language Debug Interface methods are deprecated: The functionality of these methods can be achieved through other means (or is generally not useful to a debugger):

    IRemoteThreadEx::IsStartBlock

    IRemoteThreadEx::WatchForStep

    IRemoteThreadEx::WithdrawFromThreadBank

  • com.ms.util.xml - Use com.ms.xml.util instead.

  • The following methods of com.ms.dll.DllLib are deprecated:

    getPinnedHandle

    addrOfPinnedObject

    freePinnedHandle

    getPinnedObject


Microsoft VM Updates

This topic covers the following updates to the Microsoft virtual machine (Microsoft VM), build 3167 through build 3234:

Fixes since VM Build 3188 and included in VM Build 3234 (SDK for Java 4.0)
Fixes since VM Build 3186 and included in VM Build 3188
Fixes since VM Build 3182 and included in VM Build 3186
Fixes since VM Build 3181 and included in VM Build 3182
Fixes since VM Build 3177 and included in VM Build 3181
Fixes since VM Build 3167 (SDK for Java 3.2) and included in VM Build 3177

Note for Alpha Microsoft® Windows® Foundation Classes (WFC), JIT and profiler fixes do not apply to the Microsoft VM for Alpha architectures, as these features are not available on the Compaq DIGITAL Alpha architectures. Basic VM and debugger fixes do apply to the Alpha platform.

Fixes since VM Build 3188 and included in VM Build 3234 (SDK for Java 4.0)
Fixed a NullPointerException bug when calling java/awt/Graphics.clearRect( ) on a java/awt/PrintGraphics that did not have a background color selected.
Using the Clipboard accelerator keys in a java/awt/TextComponent no longer throws a SecurityException in some scenarios.
Fixed an AWT bug where the Graphics object passed to a lightweight component's update method would not have the correct clipping applied.
Fixed an AWT bug where, after reshaping a lightweight component, the parent's component may not properly repaint.
Fixed a java/awt/image/PixelGrabber bug where off-screen images would not return the correct RGB values when running on some video drivers.
java/lang/Class.forName(null) correctly throws a ClassNotFoundException, not a StringIndexOutOfBoundsException.
The localization data returned by the java.text classes has been updated to more closely match Microsoft® Win32® and later JDKs.
java/text/Collator.setStrength(Collator.IDENTICAL) no longer throws an IllegalArgumentException.
Fixed a bug where java/text/ChoiceFormat.parse(String, ParsePosition) would not start at the correct position.
Fixed a bug where java/text/MessageFormat.parse(String, ParsePosition) would not accept the same input as later JDKs.
Fixed the Java to native marshaling of the @com.struct com/ms/com/COAUTHIDENTITY when the class is used as a top-level structure (such as a call to CoSetProxyBlanket).
The string getter and setter methods of com/ms/lang/RegKey use the Unicode registry APIs on Microsoft® Windows NT® instead of truncating the data to ANSI.
Fixed an access violation in the native implementation of the java/util/zip classes when dealing with some corrupt .zip files.
Fixed the automatic dispatch marshaling of byref VARIANTs to java/lang/Object to behave like non-byref VARIANTs to java/lang/Object (previous versions would coerce the byref VARIANT to a VT_R8 value).
Fixed a bug where IJavaEventMonitorIDInfo2::GetObjectField would return non-existent fields in some variable-size classes, and IJavaEventMonitorIDInfo2::GetArrayElement would return non-existent elements past the end of the array for arrays of objects and for any array if object aging was enabled.
Fixed the RNI API Class_CopyConstantPoolItem to work correctly for CP_MethodRef, CP_FieldRef, and CP_ClassRef entry types.
The wininet-based HTTP URLConnection now recognizes the Microsoft® Internet Explorer version 5 autoproxy settings, and handles proxy authentication.

Fixes since VM Build 3186 and included in VM Build 3188
Fixed a problem where FontMetrics.charWidth() could return incorrect values, notably when the GulimChe font (a Korean language font) was in use.
Fixed an issue with the implementation of the IDispatch interface that the VM automatically exposes for Java objects. Under some circumstances, this issue caused the method IDispatch::GetIdsOfNames to return the wrong DISPID for class members with long names (more than 15 characters).
Fixed a GDI leak in java.awt.PrintJob.
Security fix.

Fixes since VM Build 3182 and included in VM Build 3186
Fixed issues with the just-in-time (JIT) compiler.
For AWT-based ActiveX controls, the implementation of IOleInPlaceActiveObject::TranslateAccelerator now consumes WM_CHAR messages.
Fixed a memory leak related to ThreadGroups when debugging Java code.
Security fix.

Fixes since VM Build 3181 and included in VM Build 3182
Fixed issues with the Just-In-Time (JIT) compiler.
Fixed issues related to debugging Java code on multiple processor systems.
Fixed a hang when calling java/applet/AppletContext.showDocument from script code running on the browser thread.

Fixes since VM Build 3177 and included in VM Build 3181
Fixed issues with the Just-In-Time (JIT) compiler.
Fixed a memory leak on thread detach when debugging is enabled.
Updated WFC (build 8475).
Fixed issues related to debugging Java code on multiple processor systems.
Fixed issue related to COM interface pointers that are aggregated with the free-threaded marshaler (FTM) or are marshaled into the virtual machine with threading=NONE are marked as needing to be cleaned up on the thread that originally received the pointer. This behavior matches that of build 2925 and earlier. Prior to this change, build 3154 and later would release the interface pointer on the virtual machine's single STA host thread. With this change, the "FTMChecksDisabledForADO" registry switch should no longer be required.
Fixed a problem where a class registered as a COM class could be loaded twice if the class is located in a package and another class from the same DLL or class loader had previously referenced the class.
Fixed a memory leak on thread detach if the thread had called java/lang/Double.valueOf or java/lang/Float.valueOf.
JNI's DeleteLocalRef will add the deleted reference to a free list for future calls to CreateLocalRef instead of waiting until the JNI method returned before freeing the references.
java/awt/Window.toFront now brings the window to the top of the z-order list.
The peer for java/awt/Scrollbar now correctly detects a down click in a "tiny" scrollbar where there is not enough space to render the scrollbar thumb.
When the drop-down window is visible, the peer for java/awt/Choice now consumes the KeyEvent.VK_ESCAPE and KeyEvent.VK_ENTER keys before the java/awt/Choice object can see the key press. This behavior matches that of build 2925 and earlier. This change makes implementing Win32 style dialogs easier.
java/text/SimpleDateFormat's constructor now defaults to the system's current time zone instead of the first time zone of the system's locale (for US English, the default would always be PST/PDT).

Fixes since VM Build 3167 (SDK for Java 3.2) and included in VM Build 3177
Fixed issues with the garbage collector when dealing with very large heaps.
Fixed issues with the Just-In-Time (JIT) compiler.
Updated WFC (build 8443).
Added support to print applets using a metafile surface instead of a bitmap surface by checking for the existence of a "__PrintUsingMetafile" <param> tag.
Fixed a crash when using the VM's profiling support to with Java serialization.
Fixed the IDispatch marshaling of VT_CY to be consistent with vtable marshaling. The IDispatch marshaler would coerce the VARIANT to VT_I4 instead of VT_CY while the vtable marshaler would preserve the full 64-bit value.
On jview shutdown, the VM now calls CoFreeUnusedLibraries on it host STA thread to avoid crashing inside a Microsoft® Visual Basic® COM DLL.
Added support for the "MS932" and "ASCII" byte/character encoders.
Fixed a deadlock in java/awt/List's and java/awt/Choice's peer when adding items from one thread while the event dispatch thread is painting the control's items.
Component.setForeground did not repaint the control as was done in earlier versions of the Microsoft VM and other Java virtual machines.
The applet image cache could generate security exceptions when the cache contained images from different base URLs.
java/awt/Dialog.toFront now brings the dialog to the top of the z-order list.
Fixed an AWT problem where showing a modal java/awt/Dialog that had previously been hidden could result in the dialog being disabled.


Documentation Updates

This section shows which topics have been updated as opposed to the addition of new topics. (New topics are covered in Release Notes - What's New.) Both the updates and the new topics were added since the Microsoft SDK for Java 3.2 release on 3/18/99. The updates are as follows:

Programmer's Guide

  • Added two profiler initialization options in the Profiler Programmer's Guide:

    JVM_INIT_OPT_DONT_NEED_ALLOCATION_CALLBACK
    JVM_INIT_OPT_DONT_NEED_ALLOCATION_COUNTS

  • Added a topic dealing with dcomcnfg.exe in the Debugger Programmer's Guide.

  • Added detail to the GCNewHandle and GCFreeHandle method descriptions in Protecting Objects in Allocated Memory.

  • Made Integrating JavaBeans and ActiveX a section of Integrating Java and COM.

  • Added detail to Custom Marshaling Structures and Parameters.

Samples

  • See the New Samples section.

Tools Reference

  • Revised documentation for the makecert, cert2spc, and certmgr tools.

  • Added documentation for the makectl tool.

  • Added new options to Jexegen: /special:tlb[-], /special:pe[-], and /special:all [-].

  • Added new options to jntsvc: /hookdll:hookdllname and /w.

  • Added new options to jactivex: /ao[+|-], /G4, /G5, /is[+|-], and /udi[+|-].

Microsoft Packages Reference

  • Removed the WFC Reference node and moved the WFC packages to the Microsoft Packages Reference.

  • Updated the com.ms.xml.dso, com.ms.xml.om, com.ms.xml.parser, and com.ms.xml.util packages to version 1.8.

  • Fixed documentation of various classes in the com.ms.util package.

  • Made the com.ms.wfc.data package part of the Microsoft Packages Reference.

Raw Native Interface Reference

  • Fixed the description of the FindClass RNI function.

  • Updated the following RNI functions:

    jio_snprintf
    MonitorEnter
    MonitorExit
    MonitorNotifyAll
    MonitorNotify
    MonitorWait
    PrepareThreadForJava
    PrepareThreadForJavaEx
    UnprepareThreadForJava

Invocation Interfaces Reference

  • Revised and corrected the Invocation Interfaces Reference

Compiler Directives Reference

  • Completely revised the Compiler Directives Reference, and made the Attributes Reference a section of it.

Integration Technologies

  • Reformatted the com.ms.asp and com.ms.iis.asp package references and added links.

  • Added the Microsoft® Visual Basic® Object Model.


End-User License Agreement

 Microsoft SDK for Java

END-USER LICENSE AGREEMENT FOR MICROSOFT SOFTWARE

IMPORTANT—READ CAREFULLY: This Microsoft End-User License Agreement ("EULA") is a legal agreement between you (either an individual or a single entity) and Microsoft Corporation ("Microsoft") for the Microsoft software product identified above, which includes computer software and may include associated media, printed materials, and "online" or electronic documentation ("SOFTWARE PRODUCT"). By installing, copying, or otherwise using the SOFTWARE PRODUCT, you agree to be bound by the terms of this EULA. If you do not agree to the terms of this EULA, do not install or use the SOFTWARE PRODUCT.

MICROSOFT SOFTWARE DEVELOPMENT KIT FOR JAVA VERSION 4.0

The SOFTWARE PRODUCT is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The SOFTWARE PRODUCT is licensed, not sold.

1. GRANT OF LICENSE. This EULA grants you the following rights

a. Software Product. Microsoft grants to you as an individual, a personal, nonexclusive license to make and use copies of the SOFTWARE PRODUCT for the sole purposes of designing, developing, and testing your software product(s). You may install copies of the SOFTWARE PRODUCT on an unlimited number of computers provided that you are the only individual using the SOFTWARE PRODUCT. If you are an entity, Microsoft grants you the right to designate one individual within your organization to have the right to use the SOFTWARE PRODUCT in the manner provided above.

b. Electronic Documents. Solely with respect to electronic documents included with the SOFTWARE PRODUCT, you may make an unlimited number of copies (either in hardcopy or electronic form), provided that such copies shall be used only for internal purposes and are not republished or distributed to any third party.

c. Storage/Network Use. You may also store or install a copy of the SOFTWARE PRODUCT on a storage device, such as a network server, used only to install or run the SOFTWARE PRODUCT on your other computers over an internal network; however, you must acquire and dedicate a license for each separate computer on which the SOFTWARE PRODUCT is installed or run from the storage device. A license for the SOFTWARE PRODUCT may not be shared or used concurrently on different computers.

d. Sample Code. In addition to the rights granted in Section 1(a), Microsoft grants you a non-exclusive, royalty-free right to modify the source code version of those portions of the SOFTWARE PRODUCT that are identified as sample code in the REDIST.HTM file in the SOFTWARE PRODUCT ("SAMPLE CODE"), for the sole purposes of designing, developing, and testing your software product(s), provided that you comply with Section 1(f), below.

e. Redistributable Files. In addition to the rights granted in Section 1(a), Microsoft grants you a nonexclusive, royalty-free right to reproduce and distribute in object code form only the SAMPLE CODE and all the other files identified in the REDIST.HTM file located in the SOFTWARE PRODUCT (the "REDISTRIBUTABLES"), provided that you comply with Section 1(f), below.

f. Redistribution Requirements. If you wish to distribute the REDISTRIBUTABLES, you agree to: (i) distribute the REDISTRIBUTABLES in object code only in conjunction with and as a part of a software product developed by you that adds significant and primary functionality to the REDISTRIBUTABLES ("Licensed Product"); (ii) not use Microsoft’s name, logo, or trademarks to market your Licensed Product; (iii) include a valid copyright notice on your Licensed Product; (iv) indemnify, hold harmless, and defend Microsoft from and against any claims or lawsuits, including attorney’s fees, that arise or result from the use or distribution of your Licensed Product; (v) distribute all of the files listed under each of the headings in the REDIST.HTM file (for example, "Tool Files"); (vi) not permit further distribution of the REDISTRIBUTABLES.

The following exceptions apply to subsection (f)(vi), above:

(A) you may permit further redistribution of the REDISTRIBUTABLES by your distributors to your end-user customers if your distributors only distribute the REDISTRIBUTABLES in conjunction with, and as part of, your Licensed Product and you and your distributors comply with all other terms of this EULA;

(B) you may permit your end users to reproduce and distribute the object code version of the files listed below ("Limited-Use Redistributable Files") for use in development of an application created by your end user ("End User Application"), provided that your end user agrees to: (i) distribute the Limited-Use Redistributable Files in object code only in conjunction with and as a part of a software application product developed by them that adds significant and primary functionality to the Limited-Use Redistributable Files ("End User Application"); (ii) not use Microsoft’s name, logo, or trademarks to market the End User Application; (iii) include a valid copyright notice on the End User Application; (iv) indemnify, hold harmless, and defend Microsoft from and against any claims or lawsuits, including attorney’s fees, that arise or result from the use or distribution of the End User Application; (v) not distribute less than all of the files listed under each of the headings in the REDIST. HTM file if your end user distributes any one or more of such files in an End User Application; and (vi) not permit further distribution of the Limited-Use Redistributable Files by the user of the End User Application. Limited-Use Redistributable Files: the Limited-Use Redistributable Files are all of the files listed in the REDIST.HTM file of the SOFTWARE PRODUCT, except those in Section 3.

2. UPGRADES. If the SOFTWARE PRODUCT is labeled as an upgrade, you must be properly licensed to use a product identified by Microsoft as being eligible for the upgrade in order to use the SOFTWARE PRODUCT. A SOFTWARE PRODUCT labeled as an upgrade replaces and/or supplements the product that formed the basis for your eligibility for the upgrade. You may use the resulting upgraded product only in accordance with the terms of this EULA. If the SOFTWARE PRODUCT is an upgrade of a component of a package of software programs that you licensed as a single product, the SOFTWARE PRODUCT may be used and transferred only as part of that single product package and may not be separated for use on more than one computer.

3. COPYRIGHT. All title and copyrights in and to the SOFTWARE PRODUCT (including but not limited to any images, photographs, animations, video, audio, music, text, and "applets" incorporated into the SOFTWARE PRODUCT), the accompanying printed materials, and any copies of the SOFTWARE PRODUCT are owned by Microsoft or its suppliers. The SOFTWARE PRODUCT is protected by copyright laws and international treaty provisions. Therefore, you must treat the SOFTWARE PRODUCT like any other copyrighted material except that you may install the SOFTWARE PRODUCT on a single computer provided you keep the original solely for backup or archival purposes. You may not copy the printed materials accompanying the SOFTWARE PRODUCT.

4. PRERELEASE CODE. The SOFTWARE PRODUCT may contain PRERELEASE CODE that is not at the level of performance and compatibility of the final, generally available, product offering. These portions of the SOFTWARE PRODUCT may not operate correctly and may be substantially modified prior to first commercial shipment. Microsoft is not obligated to make this or any later version of the SOFTWARE PRODUCT commercially available. Microsoft grants you the right to distribute test versions of your Licensed Product created using the PRERELEASE CODE provided you comply with the license terms described in Section 1 and the following additional provisions: (a) you must mark the test version of your Licensed Product "BETA" and (b) you are solely responsible for updating your customers with versions of your Licensed Product that operate satisfactorily with the final commercial release of the PRERELEASE CODE. In order to determine what constitutes PRERELEASE CODE, consult the REDIST.HTM file located in the SOFTWARE PRODUCT.

5. DESCRIPTION OF OTHER RIGHTS AND LIMITATIONS

a. Limitations on Reverse Engineering, Decompilation, and Disassembly. You may not reverse engineer, decompile, or disassemble the SOFTWARE PRODUCT, except and only to the extent that such activity is expressly permitted by applicable law notwithstanding this limitation.

b. Separation of Components. The SOFTWARE PRODUCT is licensed as a single product. Its component parts may not be separated for use on more than one computer.

c. Rental. You may not rent, lease, or lend the SOFTWARE PRODUCT.

d. Support Services. Microsoft may provide you with support services related to the SOFTWARE PRODUCT ("Support Services"). Use of Support Services is governed by the Microsoft policies and programs described in the user manual, "online" documentation, and/or other Microsoft-provided materials. Any supplemental software code provided to you as part of the Support Services shall be considered part of the SOFTWARE PRODUCT and subject to the terms and conditions of this EULA. With respect to technical information you provide to Microsoft as part of the Support Services, Microsoft may use such information for its business purposes, including for product support and development. Microsoft will not utilize such technical information in a form that personally identifies you.

e. Software Transfer. You may permanently transfer all of your rights under this EULA, provided you retain no copies, you transfer all of the SOFTWARE PRODUCT (including all component parts, the media and printed materials, any upgrades, this EULA, and, if applicable, the Certificate of Authenticity), and the recipient agrees to the terms of this EULA. If the SOFTWARE PRODUCT is an upgrade, any transfer must include all prior versions of the SOFTWARE PRODUCT.

f. Termination. Without prejudice to any other rights, Microsoft may terminate this EULA if you fail to comply with the terms and conditions of this EULA. In such event, you must destroy all copies of the SOFTWARE PRODUCT and all of its component parts.

6. U.S. GOVERNMENT RESTRICTED RIGHTS. The SOFTWARE PRODUCT and documentation are provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software—Restricted Rights at 48 CFR 52.227-19, as applicable. Manufacturer is Microsoft Corporation/One Microsoft Way/Redmond, WA 98052-6399.

7. EXPORT RESTRICTIONS. You agree that neither you nor your customers intend to or will, directly or indirectly, export or transmit (i) the SOFTWARE or related documentation and technical data or (ii) your software product as described in Section 1(f) of this License (or any part thereof), or process, or service that is the direct product of the SOFTWARE, to any country to which such export or transmission is restricted by any applicable U.S. regulation or statute, without the prior written consent, if required, of the Bureau of Export Administration of the U.S. Department of Commerce, or such other governmental entity as may have jurisdiction over such export or transmission.

8. NOTE ON JAVA SUPPORT. THE SOFTWARE PRODUCT CONTAINS SUPPORT FOR PROGRAMS WRITTEN IN JAVA. JAVA TECHNOLOGY IS NOT FAULT TOLERANT AND IS NOT DESIGNED, MANUFACTURED OR INTENDED FOR USE OR RESALE AS ONLINE CONTROL EQUIPMENT IN HAZARDOUS ENVIRONMENTS REQUIRING FAIL-SAFE PERFORMANCE, SUCH AS IN THE OPERATION OF NUCLEAR FACILITIES, AIRCRAFT NAVIGATION OR COMMUNICATIONS SYSTEMS, AIR TRAFFIC CONTROL, DIRECT LIFE SUPPORT MACHINES, OR WEAPONS SYSTEMS, IN WHICH THE FAILURE OF JAVA TECHNOLOGY COULD LEAD DIRECTLY TO DEATH, PERSONAL INJURY, OR SEVERE PHYSICAL OR ENVIRONMENTAL DAMAGE. Sun Microsystems, Inc. has contractually obligated Microsoft to make this disclaimer.

MISCELLANEOUS

If you acquired this product in the United States, this EULA is governed by the laws of the State of Washington.

If you acquired this product in Canada, this EULA is governed by the laws of the Province of Ontario, Canada. Each of the parties hereto irrevocably attorns to the jurisdiction of the courts of the Province of Ontario and further agrees to commence any litigation which may arise hereunder in the courts located in the Judicial District of York, Province of Ontario.

If this product was acquired outside the United States, then local law may apply.

Should you have any questions concerning this EULA, or if you desire to contact Microsoft for any reason, please contact the Microsoft subsidiary serving your country, or write: Microsoft Sales Information Center/One Microsoft Way/Redmond, WA 98052-6399.

If you have a specific question regarding the licensing of redistributables, you may call the Microsoft Technical Sales Information Team at (800) 426-9400 (United States only) or send inquiries via fax to Microsoft SDK for Java Licensing Administrator, (425) 936-7329 (United States only).

LIMITED WARRANTY

LIMITED WARRANTY. To the maximum extent permitted by applicable law, Microsoft and its suppliers disclaim all other warranties, either express or implied, including, but not limited to, implied warranties of merchantability AND fitness for a particular purpose, with regard to the SOFTWARE PRODUCT, and any accompanying hardware. This limited warranty gives you specific legal rights. You may have others, which vary from state/jurisdiction to state/jurisdiction. NOTWITHSTANDING THE FOREGOING, MICROSOFT WARRANTS THAT IT HAS ALL THIRD PARTY LICENSE RIGHTS THAT ARE NECESSARY TO GRANT THE LICENSE RIGHTS SET FORTH HEREIN.

LIMITATION OF LIABILITY. EXCEPT WITH RESPECT TO THE WARRANTY SET FORTH IN THE LAST SENTENCE OF THE "LIMITED WARRANTY" SECTION ABOVE, MICROSOFT’S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY UNDER THIS EULA SHALL NOT EXCEED ONE HUNDRED DOLLARS (U.S. $100.00).

NO LIABILITY FOR CONSEQUENTIAL DAMAGES. To the maximum extent permitted by applicable law, in no event shall Microsoft or its suppliers be liable for any special, incidental, indirect, or consequential damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or any other pecuniary loss) arising out of the use of or inability to use the software product, even if Microsoft has been advised of the possibility of such damages. Because some states and jurisdictions do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply to you.

Si vous avez acquis votre produit Microsoft au CANADA, la garantie limitée suivante vous concerne :

GARANTIE LIMITEE

GARANTIE LIMITEE — Sauf pour celles du REDISTRIBUTABLES, qui sont fournies "comme telles", sans aucune garantie quelle qu’elle soit, Microsoft garantit que (a) la performance du LOGICIEL sera substantiellement en conformité avec le(s) manuel(s) de produits qui accompagne(nt) le LOGICIEL pour une période de quatre-vingt-dix (90) jours à compter de la date de réception ; et (b) tout matériel fourni par Microsoft accompagnant le LOGICIEL sera exempt de défaut de matière première ou de vice de fabrication dans des conditions normales d’utilisation et d’entretien pour une période d’un an à compter de la date de réception. Toute garantie implicite concernant le LOGICIEL et le matériel est limitée à quatre-vingt-dix (90) jours et un (1) an, respectivement.

RECOURS DU CLIENT — La seule obligation de Microsoft et votre recours exclusif seront, au choix de Microsoft, soit (a) le remboursement du prix payé ou (b) la réparation ou le remplacement du LOGICIEL ou du matériel qui n’est pas conforme à la Garantie Limitée de Microsoft et qui est retourné à Microsoft avec une copie de votre reçu. Cette Garantie Limitée est nulle si le défaut du LOGICIEL ou du matériel est causé par un accident, un traitement abusif ou une mauvaise application. Tout LOGICIEL de remplacement sera garanti pour le reste de la période de garantie initiale ou pour trente (30) jours, selon laquelle de ces deux périodes est la plus longue.

AUCUNE AUTRE GARANTIE — MICROSOFT DESAVOUE TOUTE AUTRE GARANTIE, EXPRESSE OU IMPLICITE, Y COMPRIS MAIS NE SE LIMITANT PAS AUX GARANTIES IMPLICITES DU CARACTERE ADEQUAT POUR LA COMMERCIALISATION OU UN USAGE PARTICULIER EN CE QUI CONCERNE LE LOGICIEL, LE(S) MANUEL(S) DE PRODUITS, LA DOCUMENTATION ECRITE ET TOUT MATERIEL QUI L’ACCOMPAGNENT. CETTE GARANTIE LIMITEE VOUS ACCORDE DES DROITS JURIDIQUES SPECIFIQUES.

PAS D’OBLIGATION POUR LES DOMMAGES INDIRECTS — MICROSOFT OU SES FOURNISSEURS N’AURONT D’OBLIGATION EN AUCUNE CIRCONSTANCE POUR TOUT AUTRE DOMMAGE QUEL QU’IL SOIT (Y COMPRIS, SANS LIMITATION, LES DOMMAGES ENTRAINES PAR LA PERTE DE BENEFICES, L’INTERRUPTION DES AFFAIRES, LA PERTE D’INFORMATION COMMERCIALE OU TOUTE AUTRE PERTE PECUNIAIRE) DECOULANT DE L’UTILISATION OU DE L’IMPOSSIBILITE D’UTILISATION DE CE PRODUIT MICROSOFT, ET CE, MEME SI MICROSOFT A ETE AVISE DE LA POSSIBILITE DE TELS DOMMAGES. EN TOUT CAS, LA SEULE OBLIGATION DE MICROSOFT EN VERTU DE TOUTE DISPOSITION DE CETTE CONVENTION SE LIMITERA AU MONTANT EN FAIT PAYE PAR VOUS POUR LE LOGICIEL.

La présente Convention est régie par les lois de la province d’Ontario, Canada. Chacune des parties à la présente reconnaît irrévocablement la compétence des tribunaux de la province d’Ontario et consent à instituer tout litige qui pourrait découler de la présente auprès des tribunaux situés dans le district judiciaire de York, province d’Ontario.

Au cas où vous auriez des questions concernant cette licence ou que vous désiriez vous mettre en rapport avec Microsoft pour quelque raison que ce soit, veuillez contacter la succursale Microsoft desservant votre pays, dont l’adresse est fournie dans ce produit, ou écrire à : Microsoft Sales Information Center, One Microsoft Way, Redmond, Washington 98052-6399.


Redistributable Files

This topic identifies the files that you can redistribute with applications developed using the Microsoft SDK for Java. Conditions for doing so are described in section f. Redistribution Requirements in the End-User License Agreement.

The redistributable files are located inside SDK folders unless otherwise noted. When you redistribute any of these files, you must ensure that you are doing so with the correct version of the files.

The Microsoft SDK for Java no longer has a stand-alone redistributable Microsoft® Win32® API package. It is now part of the default classes installed with the Microsoft virtual machine (Microsoft VM).

Note The build numbers of the Microsoft VM and jvc for this SDK release can be found in the file Build.txt, located in the SDK's Relnotes folder.

Redistribution information is in two sections:

Categories of Redistributable Files
Files that are Not Redistributable

Categories of Redistributable Files

The categories of redistributable files are as follows:

  • Microsoft VM for x86 and Compaq DIGITAL Alpha Systems

  • SDK Tools, Header, and Library Files (x86 and Compaq DIGITAL Alpha)

  • Internet Explorer Classes for Java

  • SDK Sample Files

  • SDK Documentation

  • Microsoft DirectX

  • Microsoft DirectAnimation Package and Runtime

  • General Redistribution Information

  • JNI Files

Microsoft VM for x86 and Compaq DIGITAL Alpha Systems

You can redistribute MSJavx86.exe (a self-extracting executable for x86 systems) and MSJavAxP.exe (a self-extracting executable for Compaq DIGITAL Alpha systems) with the SDK for Java, version 4.0.

  • The Microsoft VM for x86 systems, MSJavx86.exe, can be downloaded. Go to the Microsoft Technologies for Java Web site This link takes you to a site on microsoft.com. Select the Microsoft virtual machine option from the Downloads menu and follow the Microsoft VM links to download the appropriate VM.

  • The Microsoft VM for Compaq DIGITAL Alpha systems, MSJavAxP.exe, can also be obtained from the Downloads page of the Microsoft Technologies for Java Web site This link takes you to a site on microsoft.com.

Individual files in the redistributable executables cannot be separately redistributed. The retail version of the stand-alone VM for x86 (MSJavx86.exe) can be used with retail versions of Microsoft® Internet Explorer (versions 3.02 or later); pre-release versions of Internet Explorer are not supported.

For information on the most recent version of the Microsoft VM, go to http://www.microsoft.com/java/ This link takes you to a site on microsoft.com.

SDK Tools, Header, and Library Files (x86 and Compaq DIGITAL Alpha)

Most of the files provided with the SDK in the Bin and Binalpha folders are redistributable. This section shows the location of redistributable components.

\Bin

Classd.exe, Classr.exe, Jexegen.exe, JView.exe, Guidgen.exe, JActiveX.exe, IntegrationClasses.exe, IntegrationClasses2000.exe, MSJavah.exe, Resmerge.exe, Clspack.exe, Cabarc.exe, DuBuild.exe, Javasrc.exe, Javareg.exe, Qvue.exe, Classvue.exe, Appletviewer.exe, Wjview.exe, and Vjreg.exe

\Binalpha

Qvue.exe, Jactivex.exe, Jexegen.exe, Javareg.exe, and Vjreg.exe

\Jntsvc

Jntsvc.exe, Service.zip, TestService.java, and makefile

\Include

Javaax.h, JavaDbg.h, Javaexec.h, Jclshook.h, Jevmon.h, Jevmon.idl, Nativcom.h, Jni.h, Jexefmt.h and Native.h

\Lib\i386

Javadbg.lib and Msjava.lib

\Lib\AXP

Javadbg.lib and Msjava.lib

\Readmes

Javasrc.txt and Master.inf

Internet Explorer Classes for Java

The IntegrationClasses.exe and IntegrationClasses2000.exe tools in the Bin folder install the com.ms.ie package, which contains class files that are hooks for Java into Microsoft® Internet Explorer.

SDK Sample Files

The files in the Samples folder and its subfolders containing sample code are redistributable. See the terms and conditions defined by the End-User License Agreement in section 1(d) Sample Code.

SDK Documentation Download Executable

SDKDocs40.exe is used to download the SDK documentation without having to download the entire SDK for Java. SDKDocs40.exe is located in the Docs folder and can be redistributed with the Microsoft VM and SDK components redistribution.

Microsoft DirectX Runtime

The Microsoft® DirectX® runtime can be redistributed with the Microsoft VM, which includes the DirectX package in the system class library. You can download the DirectX runtime from http://www.microsoft.com/directx This link takes you to a site on microsoft.com.

Microsoft DirectAnimation Package and Runtime

Enduser.exe is a self-extracting executable that provides the Microsoft® DirectAnimation® runtime. This file can be downloaded from http://www.microsoft.com/directx/overview/danim/default.asp This link takes to you a site on microsoft.com. The DirectAnimation runtime also comes with Internet Explorer 4.0 or later. This file can be redistributed with the Microsoft VM.

General Redistribution Information

Correct versions are extremely important. Be sure that you provide the correct version, checking in your setup program for any redistributed file that may be updated, including the Microsoft VM. To manually verify the Microsoft VM version that you are running, check the version of Msjava.dll under your Microsoft® Windows® System[32] folder.

JNI Files

The following JNI files may only be redistributed with Microsoft SDK for Java, version 4.0, in its entirety. They are not for individual redistribution.

  • Javah.exe

  • Jni.h

Files that are Not Redistributable

The Java compiler: The following jvc files in the Bin folder are not redistributable with this SDK:

  • Jvc.exe

  • Msjvc.dll

  • Jps.dll

Nmake.exe was released with Microsoft® Visual C++® and cannot be redistributed with this SDK.

The following security or signing tools (or both) are not for redistribution with this SDK:

JavaSign.dll, ChkJava.exe, MakeCert.exe, Cert2SPC.exe, ChkTrust.exe, Setreg.exe, CertMgr.exe, SignCode.exe, Signer.dll, CPrmEdit.exe, CPrmEdit.txt, Javazone.hlp, PIniEdit.exe, and PIniEdit.txt.

Uninstaller.exe cannot be redistributed.


Internationalization Support

 Microsoft SDK for Java

Release Notes - Internationalization Support

This topic has information about internationalization support for Java. The following sections are included:

Unicode
Resource Format
Multilingual Input Method APIs
Multilingual Virtual Machine
Vertical Writing Support

See Also Internationalization Support

Unicode

Unlike most other virtual machines, Unicode support was implemented correctly in previous releases of the Microsoft VM and SDK. The getLocalizedInput and getOutputStream calls are still valid. All UI methods and paths are Unicode-enabled. Due to size of the JDK 1.1 Unicode code pages (over 4 megabytes), only the Microsoft® Windows® local code pages data (classes) have been included in this release.

Resource Format

The Microsoft Application Foundation Classes (AFC) includes a set of resource decoder classes that enable users to load Microsoft® Win32® resources. These resources are used to:

  1. Leverage existing Win32 resources in Java in a cross-platform manner.

  2. Allow easy, safe business application non-compile localization.

  3. Offer a solution for software globalization on the Web without reinventing the internationalization process.

  4. Support multilingual resource handling for Java development using existing Win32 programming tools.

The Win32 Resource Loading sample in the \Samples\Windows\Win32ResSupport directory of the SDK for Java demonstrates the use of the supported Win32 resource styles and controls included with the com.ms.ui.resource.Win32ResourceDecoder class. The Win32 Resource Loading sample is described in Win32Resource.htm (located in the same directory).

Multilingual Input Method APIs

Java IME support is provided for use with Java applications and applets written for Chinese, Japanese, and Korean users. APIs and sample code are included in the SDK to allow developers to:

  1. Create pure Java IMEs with self-defined UIs.

  2. Enable a Java applet or application to access any system IMEs as a Java IME on any Chinese/Japanese/Korean (CJK) systems. Switch the system IME to direct input mode or disable your system IME before you use Java IMEs.

Multilingual Virtual Machine

Microsoft provides the first multilingual virtual machine on the market today, including 29 languages for both runtime messages and system class library resources to meet the global demand. Dialogs, strings, and other resources are loaded and displayed based on the default system locale using system default fonts.

Vertical Writing Support

Vertical writing is supported as part of the continuing effort to meet the special requirements of international developers and Web publishers. For those who like to use vertical writing for text displays, Microsoft AFC includes vertical writing APIs that can be used in Java applet/application development. This feature enhances programming for CJK languages that uses vertical writing in text, in addition to all degree text rotation features in AFC.


Microsoft DirectX

This topic contains information about Microsoft® DirectX® and includes the following sections:

What is DirectX?
DirectX APIs Supported by Java Classes
DirectX Runtime Installation
Redistribution Components
DirectX Support

What is DirectX?

Microsoft DirectX is a group of technologies designed by Microsoft to make Windows-based computers an ideal platform for running and displaying applications rich in multimedia elements such as full-color graphics, video, 3-D animation, and surround sound. Built directly into the Microsoft® Windows® family of operating systems, DirectX is an integral part of Windows 98 and Windows 2000, as well as Microsoft® Internet Explorer. DirectX components may also be automatically installed on your system by advanced multimedia games and applications written for Microsoft® Windows® 95.

DirectX provides software developers with quick access to a broad range of peripherals, for example graphics cards, audio adapters and input devices. With DirectX, developers can get access to specialized hardware and multimedia functionality, allowing them to concentrate on building creative multimedia applications without worrying about writing hardware-specific code.

DirectX APIs Supported by Java Classes

DirectX contains Java classes for the following DirectX multimedia APIs:

  • Microsoft® DirectDraw® provides 2-D graphics services and bitmap composition.

  • Microsoft® Direct3D® Retained Mode and Immediate Mode have high and low-level 3D graphics APIs that provide comprehensive 3-D graphics services.

  • Microsoft® DirectSound® provides sound-mixing and playback services.

  • Microsoft® DirectPlay® provides multiplayer game connectivity over the Internet.

  • Microsoft® DirectInput® provides services for joysticks and other input devices.

For more information about the DirectX multimedia APIs, see http://www.microsoft.com/directx This link takes you to a site on microsoft.com.

DirectX Runtime Installation

A DirectX class library containing the classes referenced in the previous section ships with the Microsoft® virtual machine. Additionally, the Microsoft® SDK for Java includes DirectX samples. You must install the DirectX runtime to use the class library and samples.

The latest version of the DirectX runtime is available for download from the DirectX Home page at http://www.microsoft.com/directx This link takes you to a site on microsoft.com.

Redistribution Components

For information about redistribution of the DirectX runtime, see the release notes for Redistributable Files and the section on Redistribution Requirements in the End-User License Agreement. Read the End User License Agreement before using the SDK. The DirectX class library ships with the Microsoft VM.

DirectX Support

You can submit comments using the public forum news:msnews.microsoft.com/microsoft.public.java.sdk or news:msnews.microsoft.com/microsoft.public.java.directxj. Send bug reports and the steps to reproduce the bug to the Java Feedback Page This link takes you to a site on microsoft.com.

A variety of additional support options are available from the DirectX Home page This link takes you to a site on microsoft.com, including FAQs, news groups, troubleshooting wizards, and so on.


Microsoft DirectAnimation

 Microsoft SDK for Java

Release Notes - Microsoft DirectAnimation

Microsoft® DirectAnimation® is a Java API that enables different types of multimedia content to be tightly integrated and deployed, associating the media pieces with a timeline and user events. This topic provides late-breaking or other information that supplements the Microsoft® DirectAnimation® documentation and includes the following sections:

Overview
Requirements and Dependencies
Additional Information
Known Bugs
General Information
Graphics
Contact Information

Overview

DirectAnimation is released as an integrated component of the Microsoft® Internet Explorer 4.0 and later minimal install. This provides unprecedented animation and multimedia capabilities built into a major Internet browser (no special download is needed). Furthermore, DirectAnimation is integrated with Dynamic HTML (DHTML), and hence is especially suitable for adding compact and lightweight animation effects to Web pages.

DirectAnimation is the component of the Microsoft® DirectX® family of APIs that provides rich animation and integrated media support for Web pages, CD-ROM titles, and multimedia applications. DirectAnimation provides a unified and comprehensive support for the different media types, including: 2-D vector graphics, 3-D graphics, sprites, audio, video, and a rich time and event model that applies uniformly across the different media types. DirectAnimation is a COM API and an underlying engine/runtime whose functionally can be accessed in different ways by different user groups:

  • HTML authors can integrate animation using the DirectAnimation controls.

  • Microsoft® Visual Basic® Scripting Edition (VBScript), Microsoft® JScript® users, and Java applet writers can program animation for Web pages with DHTML integration.

  • Finally, Java, Visual Basic, and C++ programmers can develop Microsoft® ActiveX® Controls or full applications with rich media and interactivity.

The supported media types are as follows:

  • 2-D images (.bmp, .gif, .png, and .jpeg files)

  • 3-D models (.x and VRML files)

  • Sounds (.wav and .midi files)

  • Movies (.avi, .mpeg, and .mov files)

  • Text

In the case of movies and sounds, additional media formats can be supported by supplying Microsoft® DirectShow® CODECs for those formats.

One of the key DirectAnimation classes is the Behavior class. Different types of media are incorporated into the animation by encapsulating them as DirectAnimation Behavior objects. Behavior objects can be used interchangeably, and have a number of methods applied to them, independent of the media type they are encapsulating. Of course, you can still access methods that are specific to the different types of behaviors based on the type of media.

Back to the Top

Requirements and Dependencies

The minimum requirements to run Microsoft® DirectAnimation® applications and content are as follows:

  • Pentium-based computer.

  • Microsoft® Windows® 95, Microsoft® Windows® 98, Microsoft® Windows NT® 4.0, or Microsoft® Windows® 2000.

  • Microsoft® DirectX®, including Microsoft® Direct3D® (for Windows NT users, the latest service pack is recommended).

  • Microsoft® Internet Explorer 4.0 or later (Netscape Navigator can also be used for Java applets; see Additional Information).

The DirectAnimation runtime comes as part of IE4 minimal install This link takes you to a site on microsoft.com. DirectAnimation is also part of Windows 98 and future releases of Windows NT; the upcoming release will be called Microsoft® Windows® 2000.

The DirectAnimation SDK includes an extensive set of documents and samples that illustrate the breadth and depth of functionality. For more information, see http://www.microsoft.com/directx/dxm/ This link takes you to a site on microsoft.com.

Additional Information

Significant enhancements since the prerelease version have been the addition of support for scripting languages (JScript and VBScript), as well as the integration of the multimedia controls (in Internet Explorer 4.0) with the DirectAnimation runtime. In addition to the multimedia controls, a windowed control is provided, which can be used with Microsoft® Internet Explorer 3.02 and with Visual Basic. With the addition of the multimedia controls, content developers can now access DirectAnimation functionality through different levels, from PARAM tags at the control level, to scripting, to raw COM.

The DirectAnimation Java classes are dependent on the version of the Microsoft virtual machine that ships with the Microsoft SDK for Java and Internet Explorer 4.0. Microsoft® Visual J++® 1.1 was used to author the Java samples.

Back to the Top

Known Bugs

The following is a list of current known problems. Microsoft strongly encourages you to send mail if you find a problem (dxmbug@microsoft.com). There are newsgroups set up to allow DirectAnimation content developers to discuss issues and ideas. However, mailing a bug description is the only sure way to get a fix for a bug.

General Information

  • There are some small memory leaks, most notably when using 3-D, sounds, or notifiers. To fix this in Java, implement public void cleanup( ) to the class that extends Model. In this method, call super.cleanup( ) and set all behaviors that are suspected of leaking memory to NULL. If you have other classes that contain DirectAnimation behaviors, implement public void cleanup( ) and only set suspect behaviors to NULL. Also, add the public void destroy( ) to the class that extends DXMApplet. In this method, call super.destroy( ) and set the model to null.

  • For Java content, sometimes the LeftButtonPress events miss.

  • The cursor is considered to be in the middle of the window when DirectAnimation first comes up.

  • TextPath and TextImage are now obsolete. Use StringPath and StringImage instead.

  • Notifiers can only be implemented in Java.

  • AnimateControlPosition takes parameters in meters, even if you are using the pixel library.

  • Only Microsoft® DirectDraw® surfaces created through DirectDrawEx can be imported.

Graphics

  • Shearing movies and lines doesn't work properly.

  • Color palette is not correct for 256-color displays under Windows NT.

  • SubstituteTime does not work right when applied to Splines.

  • FollowPathAngleUpright isn't doing the uprightness.

  • Although class browsers or Visual Basic show the parameters to arc and roundedrect as radius, they are really the diameter.

  • Using Java, time-varying opacity may cause the whole object to become solid after some time.

  • TextMatte doesn't allow enough of the image to be drawn through.

  • Knot duplicity for splines isn't handled.

  • Bounding box of a sheared behavior is incorrect.

  • Overlaying an image on a solidColorImage, cropping it, and then adding a rotation transform, results in the solidColorImage disappearing. To work around this problem, crop the solidColorImage into a matte.

  • Underline and strikethrough don't work on Windows NT.

Audio

  • Sound doesn't turn off all the time.

  • SinSynth plays at 440Hz no matter what rate is specified.

  • Dynamic phasing isn't enabled.

  • Loop causes the leaf sounds to loop, not the combined sound behavior (this is the intended behavior).

  • SinSynth mixed with static sound gives a choppy sin sound.

  • Audio time substitutions do not accumulate.

3-D

  • Textures do not propagate down the leaf geometries for 3-D objects that are based on .x files.

Movies

  • To use a movie as a texture, use the following work-around (code snippet in JScript):
    movieImport = m.ImportMovie("http://movie.avi");
movieImg = movieImport .Image;

// This is the work-around.
movieBBox = movieImg.BoundingBox;
solidImg = m.SolidColorImage(m.White);
solidImg = solidImg.Crop(movieBBox.Min,movieBBox.Max);

movieImg = m.Overlay(movieImg,solidImg);

Controls

  • When using the Sprite multimedia control, source .bmp images over 2048 pixels long have to be broken into arrays of images (rows and columns of images instead of just one long row or column).

  • Under some video drivers, filtered transparent pixels render as black.

  • For the Path control, TimeMarker persistence parameter -1 works like FALSE in JScript.
Back to the Top

Contact Information

Microsoft has set public news groups on the msnews-gw NNTP server as a forum for the DirectAnimation user community. We encourage you to post all questions related to the use of DirectAnimation on the appropriate news group. To access the Microsoft.public newsgroups, go through the msnews.microsoft.com server. If you use Outlook Express as your news reader, add this server to your list from the Tools menu, and choose Accounts.

  • microsoft.public.multimedia.directx.danimation.controls is for users of the DirectAnimation controls.

  • microsoft.public.multimedia.directx.danimation.programming is for programmers of the DirectAnimation API.

    For reporting bugs against the preview version, send mail to dxmbug@microsoft.com. When you do so, make sure to be specific about the operating system, PC/graphics card, version of Microsoft® Internet Explorer, and the host language/control that you're using to access DirectAnimation.

    For other issues or comments that are not appropriate for the forums previously mentioned, send mail to dxmbeta@microsoft.com.

Back to the Top


Microsoft JDBC-ODBC Bridge

 Microsoft SDK for Java

Release Notes - Microsoft JDBC-ODBC Bridge

The Microsoft JDBC-ODBC bridge is part of the core set of classes that come with the Microsoft virtual machine.

Requirements

To use the JDBC/ODBC bridge, the following items are required:

  1. ODBC 3.0 or later.

  2. At least one ODBC driver for the type of data you need. For example, if you want to get to Microsoft® SQL Server® data, the appropriate ODBC SQL Server driver must be installed.

Running the JDBC Sample

To run the JDBC samples, follow the instructions in the \Samples folder of the SDK.


Programmer's Guide

This Programmer's Guide for the Microsoft® SDK for Java covers the following subjects:

Microsoft Virtual Machine describes the Microsoft® virtual machine object model and the compilers included with this SDK, and supplies information on the debugging, profiler, and invocation interfaces provided by the virtual machine.

Integrating Java and COM shows how to combine Java with COM to develop language- and platform-independent components.

Integrating Java and Win32 using J/Direct shows how to access Microsoft® Win32® APIs from Java processes. With Microsoft® J/Direct™, you can also directly call unmodified dynamic-link libraries (DLLs) and custom third-party DLLs without writing intermediate wrapper DLLs.

Integrating Java and Microsoft® Windows® using Raw Native Interface describes a set of functions and structures for traversing between Java and native code, and manipulating objects while in native code.

Windows Foundation Classes for Java (WFC) describes the WFC classes. WFC supports components that are targeted for the Microsoft® Windows® operating system and the Dynamic HTML (DHTML) object model.

Security provides an overview of the trust-based security model for Java classes. This security model is supported by Microsoft® Internet Explorer 4.0.

Internationalization provides an overview of the enhanced internationalization support in this SDK.

Packaging and Distributing Software describes how to archive, download, and install packages using tools provided by the SDK.


Microsoft Virtual Machine

The Microsoft® virtual machine (Microsoft VM) is a platform-independent software engine that runs Java applets, applications, and COM objects. The Microsoft VM is an interpreter and a runtime system: As an interpreter, the Microsoft VM interprets architecture-neutral instructions, or bytecode. It is machine-independent code generated by Java compilers such as jvc.exe, the Microsoft compiler, and executed by the Java interpreter or compiled at the last minute by a JIT compiler.

Bytecode resembles machine code but is not specific to any one processor. Bytecode is executable on any operating system that supports the Java runtime system. The bytecode (compiled code) is stored in a binary, platform-independent class file, which is a stream of bytes. As a runtime system, the Microsoft VM loads, links, initializes, and executes Java classes.

The Microsoft VM automatically performs garbage collection. The Microsoft VM supports debugging and profiling of running Java code. The following figure and descriptions outline the Microsoft VM's execution of Java software.

The Microsoft virtual machine

Java Software

The Microsoft VM works with many forms of Java software, including the following:

  • A Java applet is typically hosted in a Web browser or another applet viewer application. The Microsoft VM creates an instance of the applet's class, and supports the interaction between the hosting application and the applet.

  • A Java application is a Java program that typically runs independently of other applications, unlike Java applets, which are typically run within other applications. The Microsoft VM runs a Java application by creating an instance of the application's class, and invoking its main method.

  • A Java COM object is an instance of a Java class exposed as a component object model (COM) object by the Microsoft VM. Java classes may contain information describing their COM representations. With appropriate COM registration information, any COM client can use a Java-implemented COM object transparently.

Java APIs

The Microsoft VM includes support for several Java application programming interface (API) sets, including the following:

  • Microsoft Application Foundation Classes (AFC) provide user-interface controls, event handling, graphics and effects, access to Microsoft® Win32® resource files, and cabinet (.cab) file creation and extractions. The classes of the AFC API are cross-platform and browser-independent.

Note AFC and its documentation has moved to the Microsoft® SDK for Application Foundation Classes, which can be downloaded from http://www.microsoft.com/java/download.htm This link takes you to a site on microsoft.com.

  • Windows Foundation Classes for Java (WFC) use Microsoft® J/Direct™ to access the Microsoft® Windows® API. WFC also wraps the Dynamic HTML (DHTML) object model. The WFC API takes care of details such as window message-handling procedures, message pumps, messages, window handles, and so on. WFC also provides data access through the Microsoft® ActiveX® Data Objects (ADO) and Remote Data Service (RDS) APIs. The ADO and RDS APIs are exposed in the com.ms.wfc.data package.

  • Generic Java constructs make up most Java applets and applications. This includes classes from the java.io.*, java.net.*, java.lang.*, java.util.* , java.lang.reflect.*, java.awt.* packages, along with primitive types.

Microsoft VM Components

Class Loader

A class loader retrieves the class file data that describes Java classes. Common class loaders can read class files from a uniform resource locator (URL), a file, a compressed .zip file, a class file database, or a Win32 resource.

Class Resolver

Class resolution is part of the linking process. After the class loader obtains the class file data, it calls a Microsoft VM method to resolve the class file data into a an internal representation of the class. The class resolver creates this internal representation by extracting constant pool entries, methods, fields, and other attributes, and laying them out in memory. From this internal class structure, the Microsoft VM creates and manipulates instances of the Java class.

Bytecode Verifier

The bytecode verifier of the Microsoft VM scrutinizes Java class methods for correctness. The set of required checks includes the following:

  • All instructions must have valid opcodes (a one-byte code that specifies a Microsoft VM operation).

  • All instruction branches must go to the start, and not the middle, of another instruction.

  • All instructions must obey Java semantics and type constraints.

  • No instruction may violate the integrity of the Microsoft VM.

Garbage Collector

If the Microsoft VM can verify that a given Java object will not be accessed again during the execution of the Java program, the garbage collector can free the memory consumed by that object for reuse. This contrasts with other languages that require the programmer to explicitly track runtime memory usage and deallocate memory that is no longer in use.

JIT Compiler

To improve performance, the bytecodes that define a Java method can be translated into machine code that is specific to the host computer. When such translation occurs immediately before a Java method is first executed, it is referred to as a Just-In-Time (JIT) compilation.

The Compilers topic describes the Microsoft VM Java compiler (jvc), the Microsoft® Visual J++® compiler, and the Microsoft VM JIT compiler.

Execution Engine

Most generally, execution includes all the Microsoft VM's actions from startup through exit. More specifically, the execution engine's tasks could be thought of as beginning when the Microsoft VM has finished loading and linking. These tasks are as follows:

  • Classes are initialized by running class static initializers. Class static initializers are executed for a superclass before being executed for a derived class. Class static initializers may initialize class static fields. Each interface is initialized by executing any class static initializer declared in the interface.

  • Creation of new class instances.

  • Execution of Java methods.

  • Finalization and unloading of classes and interfaces.

  • Exit.

Debugging

The Microsoft VM's debugging support provides hooks into the Microsoft VM that enable a debugger to step through executing Java code and examine object data, threads, methods, classes, and method call stacks. Debuggers aid in detecting and investigating logical errors in Java applications. The debugging support is exposed by COM interfaces on COM objects implemented by the Microsoft VM.

The Debugger Interfaces Overview describes the debugging interfaces provided by the Microsoft VM. Use these to implement your debugger.

Profiling

The Microsoft VM's profiling support provides data about the runtime behavior of Java programs, including execution time and memory usage. The profiling support is exposed by COM interfaces on COM objects implemented by the Microsoft VM.

The Profiler Interfaces Overview describes the profiling interfaces provided by the Microsoft VM. Use these to implement your profiler.

Native Code Interfaces

JNI

The Java Native Interface (JNI) is an interface for writing Java methods in native code. JNI exposes all Java objects from the Microsoft VM to the native code, and allows manipulation of these objects through handles rather than direct object references. JNI automatically takes care of reference tracking for garbage collection. See the following table for a comparison of native code interfaces.

RNI

The Raw Native Interface (RNI) is also an interface for writing Java methods in native code. RNI is more efficient than JNI. In contrast with JNI, RNI requires explicit starting and stopping of the garbage collector as appropriate. RNI also requires you to ensure that any references to Java objects are correctly handled while garbage collection is enabled. Also, unlike JNI, RNI exposes direct references to Java objects. See the following table for a comparison of native code interfaces.

J/Direct

J/Direct allows you to directly call any function exported by a dynamic-link library (DLL) without having to write an RNI or COM wrapper DLL. The Microsoft VM automatically maps data types for you. This mapping of data types is called marshaling. See the following table for a comparison of native code interfaces.

COM

The Microsoft VM can automatically treat COM objects as Java objects. The Java developer, therefore, is already in effect a COM developer, because the Microsoft VM allows the Java developer to manipulate Java objects and COM objects the same way. Java/COM integration allows Java software to take advantage of COM applications and services written in any language, and provides Java access to distributed COM (DCOM) functionality. For details, see the white papers Using COM Objects from Java and Integrating Java and COM. See the following table for a comparison of native code interfaces.

Note The Microsoft VM implements COM classes. Instances of the Microsoft VM's COM classes, like other COM classes, can be created through a CoCreateInstance call. JView is a C++ application that invokes the Microsoft VM in this way to run Java applications.

Native Code Interfaces and the Microsoft VM

Native code interface | Mechanism for calling Java native methods? | Garbage collection implicitly disabled during call? | Java objects manipulated using handles? | Marshaling of method parameters and return value?
JNI | yes | no | yes | no
RNI | yes | yes | no | no
J/Direct | no | no | no | yes
COM | no | no | no | yes

There are several APIs that give independent software vendors (ISVs) access to the Microsoft VM's underlying features. This information is especially useful if you are creating Java development tools for use with the Microsoft VM.

Determining the VM Version Number describes how to determine which version of the Microsoft VM is running on your machine.

Microsoft VM Object Model describes the object model as it applies to object decomposition and performance.

Compilers describes Microsoft's Java compilers.

Exegen Format describes the data format that must be used for Java resources stored within a portable executable (PE) image so that the Microsoft VM can locate those resources.

Debugger Interfaces Overview provides an overview of the debugger interfaces, including enabling debugging in the Microsoft VM, registering with the debugger manager, implementing callback notification interfaces, and so on.

Profiler Interfaces Overview provides an overview of the profiler interfaces, including enabling profiling in the Microsoft VM, registering for event notification, implementing event monitor information interfaces, and so on.

Invocation Interfaces Reference describes the invocation APIs provided by the Microsoft VM.

Compiler Directives Reference examines the optional special comments inserted in source code to aid in Java/COM integration and development when using the Microsoft compiler, jvc.exe.


Determining the VM Version Number

The availability of some features documented in the Microsoft SDK for Java depends on which version of the Microsoft VM you are running. There are four ways to determine the version number of the Microsoft VM.

  1. Open %Windir%\System[32], view the properties of msjava.dll and choose the Version tab. The four-digit number in the File Version box is the Microsoft VM version. For example, if 5.0.3167.1 is displayed, 3167 is the version number.

  2. View the contents of the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\
    {08B0E5C0-4FCB-11CF-AAA5-00401C608500}\InstalledVersion    .

  3. From the command line, run jview.

  4. Use the com.ms.util.SystemVersionManager class to determine the Microsoft VM version programmatically. This sample code will give the version number:
public class vers {
  public static void main(String[] args) {
System.out.println(com.ms.util.SystemVersionManager.getVMVersion());
  }
}


Microsoft VM Object Model

The following sections describe the benefits of the Microsoft virtual machine object model as it applies to object decomposition and performance.

Goals of the Object Model

Object Components


Goals of the Object Model

The Microsoft virtual machine (VM) object model facilitates efficient decomposition of objects into their member components. It enhances operational performance by providing very fast and deterministic access to multiply inherited interface members (abstract members and constant fields) and singly inherited virtual methods, while conforming to the current Java language and VM specification.

The Microsoft VM object model also provides very low per-object overhead while still containing information required for distinguishing between objects and arrays, synchronizing objects through monitors, and Wait and Notify functionality. This additional information is allocated in a "lazy" fashion, requiring additional overhead only as necessary.

Operations that this model optimizes include:

  • Fast resolution of an object's interface vtables, which you can use to access interface methods quickly and efficiently.

  • Accessing data fields in the object.

  • Accessing virtual methods of the class or interface hierarchy.

  • Entering an object's monitor.

  • Blocking a thread on an object until that object has been "notified."


Object Components

In the Microsoft virtual machine (Microsoft VM), a class is a description of an object type that includes declarations of data and method members. Classes can inherit all types of members from parent classes, including constants (static final fields), static fields and methods that exist once for all instances of a class in one namespace and are shared between instances, dynamic fields that exist separately in every instance of the class type, and dynamic methods that operate on specific instances of a class through a this pointer.

Interfaces declare only abstract, dynamic methods, constants fields, and properties (which you can think of as "virtual fields"). The methods declared in an interface can be implemented only in a class, not in an interface. When a class implements an interface, it is guaranteed to contain an implementation for every method in that interface and all interfaces that the interface extends.

This object model specifies layout of the following object components.

  • Synchronization block

  • Methods

  • Interfaces

  • Dynamic fields

When a base interface is loaded, vtables are created for its member methods, fields, and interfaces that it extends. The field tables are simply arrays of the field description structures; methods also are described by arrays of methods descriptions, but have vtables associated with them that can be accessed by indexes that remain constant throughout the hierarchy of a class.

When a base class is loaded, the Microsoft VM creates tables just as with interfaces for its member fields and methods. The class vtable differs from an interface vtable only in that its header contains the number of interface slots found below the object, and a pointer to the actual class descriptor that owns the vtable. These elements are followed by interface vtables and then by method pointers which are not declared in any of the implemented interfaces. Method pointers are pointers to the native Just-In-Time (JIT) code entry points or to a native interpreter stub (call compatible with JIT code) of methods implemented in the class or its superclasses. An interface vtable consists simply of an array of methods.

Now that you know what a vtable looks like, look at how it is used in the context of creating an object—treating it as an instance of one of its superclasses, or treating it as an instance of one of its implemented interfaces.

The following example class contains one field and one method. The class, MyClass, looks like the following:

public class MyClass {

public int Field1;

  void Method1()  {}
}

Normally, a Java-compatible compiler will create a constructor for this class, and the object will inherit methods from the Object class. For the purpose of this example, pretend that all you get is one field, Field1, and one method, Method1. The vtable for this class would look like:

An object of the type MyClass would contain space for Field1, a main vtable pointer, and a pointer to the synchronization block. Note that the synchronization block for an object is not really present unless it is used. It is created "lazily" to conserve space in non-synchronized objects. The vtable exists only once per class and is shared among objects of that class type, but the synchronization block is per instance.

The following illustration shows an object of type MyClass.

If you declare two interfaces, IFCA and IFCB, IFCA contains one method, Method2; IFCB contains two methods, Method3 and Method4. If you then declare another class, MyNextClass, which extends MyClass and implements IFCA and IFCB, you get an object that looks like the following illustration.

An interface's vtable is simply an array of Just-In-Time–compiled, code-callable methods. If an interface extends other interfaces, it has those interface vtables inside it. When the Microsoft VM resolves an object that implements an interface, that interface vtable is copied to the main vtable when it is encountered. The nested interface offsets are calculated by adding their offsets in the implemented interface to the current position in the new vtable.

Since some aspects of the object model used internally in the Microsoft VM are subject to change, all data structures besides the object data itself should be considered abstract and accessed only through functions available in Java.


Compilers

This section discusses the following compilers:

Microsoft Compiler for Java (jvc)
Microsoft Visual J++ Compiler
Microsoft JIT Compiler


Microsoft Compiler for Java (jvc)

 Microsoft SDK for Java

Microsoft Compiler for Java

The Microsoft compiler for Java (jvc) produces interpreted (.class) files that will run on any virtual machine.

For jvc compiler syntax, command-line options, and error messages, see the jvc section of the Tools Reference.


Microsoft Visual J++ Compiler

This release of the Microsoft compiler for Java (jvc) is compatible with the language enhancements specified in JDK 1.1. It supports new language features specified in JDK 1.1, including inner classes, anonymous classes, instance initializers, anonymous array expressions, class literals, blank finals and final locals, and the @deprecated tag.

It also supports delegates and additional @com tags for Java/COM integration. For more information see the Java/COM Attributes Reference.

To use these new language features with Microsoft® Visual J++®, you must replace three files in Visual J++ with their respective SDK versions:

  1. Back up the current Visual J++ versions of Jvc.exe, Jps.dll, and Msjvc.dll.

  2. Copy Jvc.exe, Jps.dll, and Msjvc.dll from %SDKDIR%\Bin to your Visual J++ directory. Projects will then build using the new compiler.

Due to more strict error and security checking in this release of jvc, some illegal code that compiled without errors using Visual J++ may now (correctly) fail to compile. One common cause is more careful checking of class member access across package boundaries. The Java Language Specification by Gosling, Joy, and Steele, discusses this in "Example: Protected Fields, Methods, and Constructors."

Here is an example of a typical error message for this type of code:

error J0204: Cannot access protected member 'x' in class
'Point' via a qualifier of type 'Point3d'

This information is subject to change. For the latest information on Visual J++, see http://msdn.microsoft.com/visualj This link takes you to a site on microsoft.com.


Microsoft JIT Compiler

The following sections describe the Microsoft Just-In-Time (JIT) compiler.

JIT Compiler Background
JIT Structure
The JIT Compiler/VM Interface


JIT Compiler Background

The standard model of a virtual machine continually interprets a sequence of bytecodes that describe the intent of a Java applet or application. Each time the VM encounters a bytecode, whether it has interpreted it many times before, there is a (relatively) lengthy translation process. Even though various approaches exist for speeding up this approach somewhat, this interpretation process accounts for significantly slower execution performance compared to equivalent compiled native code.

To improve this performance, JIT compilers interact with the VM and compile appropriate bytecode sequences into an equivalent piece of native machine code. This process occurs at runtime (that is, as the particular piece of code is going to be executed) rather than at compile time, as is traditionally the case with compiled languages such as C and C++. Rather than interpret the same bytecodes repeatedly, the hardware (the CPU) can run ("interpret") the native code. This can allow quite dramatic performance gains in the execution speed. There is, however, a tradeoff.

The time that the JIT compiler takes to compile the bytecodes is added to the overall execution time. For example, when a method executes only once and does not contain any loops, the overall performance might be reduced when JIT compilation occurs.

Note that JIT compilation has potential advantages over traditional code compilation techniques in some aspects: for example, it can target the specific machine on which the program is actually running (for example, 486 versus Pentium), rather than for a general CPU (or "the most likely" one), which is the best that traditional approaches (such as targeting a generic x86 platform) can achieve.


JIT Structure

The following diagram gives an overview of the JIT compiler's internal structure. The structure is similar to that used in typical static compiler environments. Bytecodes, together with requested symbol and other information, are converted into an internal representation. The internal representation is then used to generate code, which is optimized appropriately. There is also a linker component that resolves references for the in-memory generated code, which is then ready to run.


The JIT Compiler/VM Interface

The following diagram illustrates the relationship between the JIT compiler and the Microsoft VM.

The JIT compiler & Microsoft VM relationship

The JIT compiler and the VM provide interfaces that both use to enable effective JIT code compilation. The "compilation unit" for the JIT compiler is a single method. The VM alone decides which method to compile. Tools vendors might want to provide facilities in their tools (for example, through language constructs or user interface) to augment .class files so that they indicate which methods to JIT (the precise format of such .class file attributes is to be determined).

These interfaces are designed to allow clean separation and independence between the VM and the JIT compiler. This will enable other vendors to replace one JIT compiler with another, as appropriate.

A JIT compiler (vendor) can make the following assumptions.

  • Code and data blocks allocated through the respective VM helper functions will stay in place. Most references to methods and data members, therefore, can be resolved at compilation time.

  • The first element in every object contains the reference to the respective class's vtable (method-pointer table).

  • For arrays, which are also Java objects, the offset for the element count and the offset for the first array element are always at the same fixed offset relative to the beginning of the object (array).

  • Every loaded interface is assigned a unique handle, which allows quick access at runtime.

  • The vtable offsets of interface methods are always the same across all implementations of the interface. Therefore, all vtable offsets for methods can be resolved at compile time.

At the same time, the code and data that a JIT compiler generates for the Microsoft VM must meet the following criteria.

  • All methods must have a local stack frame.

  • For the x86 platform, the calling convention is basically "__pascal": parameters must be pushed from left to right ("this" is pushed before any user arguments), the callee pops arguments, EBX/ESI/EDI are the callee-saved registers, and the FP stack is always empty on entry to methods, return values in EAX (32-bit scalars), EDX:EAX (64-bit integers), or on the FP stack (floats and doubles).

  • The JIT compiler must provide an API that enumerates all live references in a method while it calls a method (stack crawling support for garbage collection).

  • Optionally, the JIT compiler may provide an API that enumerates all live references in a method at any time, which allows garbage collection to occur at any time.

  • Currently only "base" pointers can be live at points where garbage collection might occur. For example, the code might not have a pointer to the interior of an object/array that is live across a method call.

  • Code sharing across multiple namespaces is supported (optional).

The JIT compiler decides whether to allow interruption by the garbage collector at any time or just while a method calls another method. The latter is certainly easier to implement and needs less information at runtime, but in some scenarios it could disable the garbage collection process for an extended period of time (for example, a method executes a loop that does not contain a method call). In those cases, the JIT compiler must insert code that (conditionally) invokes the garbage collector directly unless it can be determined that the code will execute method calls frequently enough. To give the JIT maximal flexibility, it can make this decision for every method individually.

Beyond just generating code for a method, the JIT must provide additional information to enable proper execution and debugging of Java applications. Depending on the type of information, that is done in two ways:

  • Information defined by the VM: The JIT compiler provides this information at compile time to the VM, and the VM records and interprets it (for example, exception handler tables and line number information).

  • Private JIT information: The JIT compiler can store any private information along with each method so that it can provide the requested information to the VM at runtime; the VM saves the information (to the VM it is just a single block of opaque data) and passes it back to the JIT compiler at runtime (for example, enumeration of live object references in a stack frame, decision if a method is "garbage-collection safe" at the current offset, and so on).


The Exegen Format

The Microsoft virtual machine (Microsoft VM) can load .class files and other Java visible resource files (such as images, audio clips, and so on) from Microsoft® Win32® portable executable (PE) image files (.exe and .dll files). To be found by the VM, Java resources must be stored within the PE as Win32 resources. This section describes the data format, called the exegen format, that must be used for Java resources stored within a PE image so that those resources can be located by the VM. This is the format produced by the jexegen tool and defined in the header file jexefmt.h.

This section contains the following topics:

How the VM Finds Java Resources in Win32 Modules
Exegen Format Versions


How the VM Finds Java Resources in Win32 Modules

The Microsoft VM can be directed to look for Java resources within a Win32 PE image in the following ways:

  • If the resources are bound into a DLL, the DLL can be placed on the class path. Use the same syntax for adding a .zip file to the class path, but specify a .dll extension. A restriction exists on how a DLL must be built to be placed on the class path. Specifically, the resource containing the file directory must be stored with a specific resource ID (for more information, see Exegen Format Versions).

  • The COM interface IJavaExecute2::SetClassSource can be used to add a Win32 module to the list of locations where the VM searches for Java resources. See Javaexec.h in the \Include subdirectory of the Microsoft SDK for Java installation.

  • The RNI method AddModuleResourceClassSource can also be used to add a Win32 module to the list of locations where the VM searches for Java resources. See Native.h in the \Include subdirectory of the Microsoft SDK for Java installation.


Exegen Format Versions

The exegen format has the following two versions:

  • Version 1 format

    This format supports only .class files and cannot store arbitrarily named resources. This format also requires that all the data be stored within a single Win32 resource. Version 1 exegen format is supported only by the Microsoft VM version 4.79.2582 and earlier.

  • Version 2 format

    The Version 2 format, supported by newer Microsoft VMs, includes the ability to store non-class resources (such as image files). Additionally, the Version 2 format does not require that all the data be stored within a single Win32 resource.

For additional information, see Jexefmt.h in the \Include subdirectory of the Microsoft SDK for Java installation.

Version 1 Exegen Format

The Version 1 format stores all classes in a single Win32 binary resource within the PE. This resource begins with a table that lists the names of the files contained in the resource and indicates where the raw bits for those files are located. The actual data for the contained files follows this table.

Version 1 Resource IDs

If you use IJavaExecute2::SetClassSource or AddModuleResourceClassSource to tell the Microsoft VM about the module, this resource can be stored with any resource ID because those APIs allow you to specify the resource ID. The resource type must be RT_RCDATA.

If you build a DLL to place on the class path, this resource must be stored with a resource ID of 1000 (JEX_DEFAULT_CLASS_RESOURCE_ID) and the resource type must be RT_RCDATA.

Version 1 Resource Layout

The resource is laid out in three sections and are in the following order:

[JEXHEADER]

The resource starts with a header whose layout is defined in the JEXHEADER structure. The header contains a signature, a format version, flags, and a count of the number of class files contained in the resource. The dwFormatVersion of the JEXHEADER structure must be set to 1 for the Version 1 exegen format.

[FILEINFO SECTION]

Immediately following the header is an array of file information structures. The number of elements in this list is equal to the cNumFiles field in the header. The layout of each of these file information structures is defined in the JEXFILEINFOV1 structure. Each of these structures specifies the name and location of a class file contained in the resource.

The dwNameOffset field points to the name of the class file that must be in UTF8 form. Forward slashes (/) must be used as package separators. The name is the class name, not the name of a class file. Do not include the .class extension. For example, the following is correct:

java/lang/Class

But these are not:

java\lang\Class
java.lang.Class
java/lang/Class.class

[RAW DATA SECTION]

The string data for the class names and the raw binary data of the class files follows the list of JEXFILEINFOV1 structures. This data has no implied order. The only requirement is that the resource offsets in the JEXFILEINFOV1 structures must point to the proper data. The jexegen tool places all the string data immediately after the file information list followed by the raw binary data of the class files, but other generation tools do not need to follow this layout.

Version 2 Exegen Format

The Version 2 exegen format adds two features that the Version 1 format does not support:

  • The ability to store arbitrarily named resources within the module.
    This allows image files, audio clips, and so on to be stored as well as class files. These named resources can be retrieved from the Java side with any APIs that can load class path relative data (such as java.lang.Class.getResourceAsStream).

  • The ability to store the class/resource data in multiple Win32 resources.
    The Version 1 format requires that all class data be contained within the exegen resource. In the Version 2 format, the class/resource can be stored in Win32 resources other than the primary exegen resource. This allows individual Java resources to be stored as individual Win32 resources. This makes it possible to use Win32 internationalization on Java resources.

In the Version 2 format, a primary exegen resource contains the JEXHEADER and file information blocks. The structure of these file information blocks is different from the Version 1 format, but the rules for how the Microsoft VM locates this information is the same.

Version 2 Resource IDs

The resource identifier specified with either IJavaExecute2::SetClassSource or AddModuleResourceClassSource refers to the primary exegen resource. As in the Version 1 format, this resource can be stored with any resource ID and the resource type must be RT_RCDATA.

This primary resource must be stored with a resource ID of 1000 (JEX_DEFAULT_CLASS_RESOURCE_ID) in DLLs intended for the class path, and the resource type must be RT_RCDATA.

Version 2 Resource Layout

The layout of the main resource is essentially the same as in the Version 1 format: a header, followed by a list of file information structures, followed by string data, and possibly file data.

[JEXHEADER]

The dwFormatVersion field must be set to 2. Otherwise, the JEXHEADER structure remains unchanged.

[FILEINFO SECTION]

Following the header is a list of JEXFILEINFOV2 structures. The number of elements in this list is determined by the cNumFiles field in the header. These are similar to the JEXFILEINFOV1 structures with the addition of two fields, ResourceID and ResourceType. These fields specify the Win32 resource that contains the bits for each Java resource.

ResourceID and ResourceType do not contain Win32 resource IDs. For details on mapping these values to Win32 resource IDs, see the JEXRESID type.

As in the Version 1 format, the dwNameOffset field in the JEXFILEINFOV2 structure is an offset to the name of the Java resource in UTF8 form. Unlike the Version 1 format, this name is a file name not a class name. Class files must be stored with the .class extension. Forward slashes (/) are used as package separators. For example, the following is correct:

java/lang/Class.class

But these are not:

java\lang\Class.class
java.lang.Class.class
java/lang/Class

The Version 2 format provides the following flexibility in laying out Java resources within an .exe or .dll file:

  • The files can exist in the main resource.
    The ResourceID and ResourceType fields of the corresponding JEXFILEINFOV2 structures must be set to JEX_MAINRESOURCE_MARKER. The cbFileSize and dwDataOffset fields must specify the location of the resource file within the main resource.

  • You can have a one-to-one mapping between a Java resource file and the Win32 resource that contains it.
    ResourceID and ResourceType must point to the Win32 resource (either by name or by integer IDs). The cbFileSize should be set to JEX_USE_RESOURCE_LENGTH to indicate that the size of the Java resource is the same as the Win32 resource that contains it. The dwDataOffset should be 0 (zero).

  • You can have external Win32 resources (that is, not the main resource) that contain multiple Java resources.
    The ResourceID and ResourceType point to the Win32 resource, and the dwDataOffset and cbFileSize specify which portion of that Win32 resource contains the data for the Java resource.

[RAW DATA SECTION]

The string data for the file names and the resource names (if any) follow the list of JEXFILEINFOV2 structures. Some of the Java resource files may be found here as well, although all the file data may be found in other resources.


Debugger Interfaces Overview

The debugger interfaces assist in the detection, location, and correction of logical or syntactical errors in Java applications, applets, and COM objects that are run in the Microsoft virtual machine (Microsoft VM). These interfaces can also be used for debugging Java code that mixes Java classes with native Microsoft® Win32® code.

This overview contains the following topics:

Enabling Debugging in the Microsoft VM describes the ways to enable debugging by means of registry settings and environment variables.

Enumerating Debuggable Service Processes describes how to allow enumeration of all debuggable Java service processes.

Registering with the Debugger Manager provides the basics of registration interface methods.

Implementing Callback Notification Interfaces introduces the concept of notification interfaces, pointers to which the debugger passes to the debugger manager.

Retrieving Static Information discusses the cacheable class and class member information available through the IRemoteField hierarchy of interfaces.

Retrieving Dynamic Information discusses the non-cacheable information available through the IRemoteObject hierarchy of interfaces.

Controlling Execution explains the interfaces that provide access to the Java method call stacks of the threads executing in the Java process being debugged.

The debugger interfaces are Component Object Model (COM) objects and interfaces. A debugger application communicates with the Microsoft VM and controls the Java execution environment by accessing these COM objects and interfaces. You can extend debugger programs to allow remote debugging using Distributed COM (DCOM). You can write debugger programs in Java by using the classes in the com.ms.debug package. These classes provide wrapped COM interfaces.

The debugger requests information and communicates with the Microsoft VM by calling methods on COM objects implemented by the VM. Similarly, the Microsoft VM runtime notifies the debugger program of events, and provides requested information to the debugger by calling methods on COM objects that the debugger implements. The debugger registers its callbacks by calling register callback methods IRemoteDebugManagerCallbackEx and IRemoteProcessCallbackEx2.

The COM objects implemented by the Microsoft VM use a consistent method pattern to handle lists of similar objects. Various Getxx methods (GetContainer, GetSuperClass, and so on) allow the debugger program to move up the object hierarchy. Many of the Getxx methods return an enumerator object. These different enumerator objects (for processes, threads, fields, and so on) implement a nearly identical set of methods, based on the common COM IEnumXXXX enumerator paradigm. The enumeration methods allow the debugger program to move down the object hierarchy. The IEnumXXXX methods return an array of objects, skip some number of objects, reset the enumerator to the beginning of the list, or create a copy (clone) of the current enumerator.

Any memory that the Microsoft VM allocates as an output parameter from a debug interface method (an [out] parameter as documented in the reference section on the debugger interfaces) is allocated using the CoTaskMemAlloc function. When this memory is no longer needed by the debugger, it must be released using the CoTaskMemFree function.

If the debugger program continues to use a COM object that was created as output parameters from a method, the reference count for that object may need to be incremented to ensure that the object remains viable for the duration of the debugger’s use. This can be accomplished by calling the object's AddRef method. The debugger program decrements the reference count on the object using the Release method when the object is no longer needed.

The debugger interfaces use the apartment-threading model. The Microsoft VM uses a single apartment thread to dispatch all debugger events

The examples in the following topics use C++ and local COM objects to illustrate the use of the debugger interfaces. One sample is written in C++ using these debugger interfaces. A second example is written in Java using the com.ms.debug package, which consists of a set of Java-wrapped classes for these COM interfaces. These samples are installed under the %SDKDIR%\Samples\Debugger subdirectory of the Microsoft SDK for Java. For more information about other samples in this SDK, see the Samples Overview.

To use these debugger interfaces, enable debugging in the Microsoft VM through environment variables or Win32 registry settings.

The debugger interfaces are categorized as shown in the following table.

Category | Purpose
Registration Interfaces | Register the debugger program with the Microsoft VM and request to be notified when specific events occur.
Notification Interfaces | Notify the debugger of various events and return requested information.
Static Information Interfaces | Gather static information about the Java code.
Dynamic Information Interfaces | Gather dynamic information about a Java process when it is executing.
Execution Control Interfaces | Control the execution of a Java process.

See Also

Debugger Interfaces Reference

Debugging and Profiling Java Applications


Enabling Debugging in the Microsoft VM

For the debugger interfaces to be used, debugging must be enabled in the Microsoft VM before it begins execution. You can enable debugging in the Microsoft VM by setting environment variables or by creating Win32 registry settings.


Enabling Debugging with Environment Variables

The preferred method for enabling debugging is to set special environment variables before starting the Microsoft VM (before launching Microsoft® Internet Explorer, for example), and then executing the Java code to be debugged. Note that the value of an environment variable (when set) overrides the equivalent registry setting. The environment variables that may be used by a debugger are shown in the following table.

Debugger Environment Variables

Environment variable | Description and value
MSJAVA_DEBUGGING_FLAGS | Specifies options for debugging. Most modern debuggers would set all the bits from MSJDBG_DEBUGGER_NATIVE_METHODS on up.
MSJAVA_ENABLE_DEBUGGING | Enables debugging when set to some value other than 0 (zero).
MSJAVA_ENABLE_FI | Enables the fast interpreter when set to some value other than 0 (zero). If this environment variable is not set and the equivalent registry value is not set, the fast interpreter is enabled by default.
MSJAVA_ENABLE_JIT | Enables the Just-In-Time (JIT) compiler when set to some value other than 0 (zero). If this environment variable is not set and the equivalent registry value is not set, the JIT compiler is enabled by default.

If the MSJAVA_ENABLE_DEBUGGING variable exists in the Win32 environment space and is set to some value other than 0 (zero), debugging is enabled in any Microsoft VM that subsequently begins executing within this process.

Java Debugger Flags

If the MSJAVA_DEBUGGING_FLAGS variable exists in the Win32 environment space, its value specifies a bitmask of flags that control special features of the Microsoft VM. It can be any combination of the flags in the following table.

MSJDBG_FL_REQUIRE_BYTE_CODE_EXECUTION

Disables the JIT compiler so that bytecode execution may be profiled.

 0x01
MSJDBG_FL_ENABLE_PROFILING

Enables profiling.

 0x02
MSJDBG_NO_HARDWARE_BREAKPOINTS

Notifies the Microsoft VM that hardware breakpoints should not be used on Microsoft® Windows NT® being run on Intel processors. If this value and the following value are set, data breakpoints are not available. When using a native debugger, such as Microsoft® Visual C++®, this value may need to be set to allow the native debugger to function properly. This option is ignored on Compaq DIGITAL Alpha systems running Windows NT. Hardware breakpoints are not used on Microsoft® Windows® 95.

 0x04
MSJDBG_NO_PAGE_BREAKPOINTS

Notifies the Microsoft VM that memory page faults for data breakpoints should not be used (applies to both Windows 95 and Windows NT being run on Intel processors). If this value and the previous value are set, data breakpoints are not available. When using a native debugger, such as Microsoft® Visual C++®, this value may need to be set to allow the native debugger to function properly. This option is ignored on Compaq DIGITAL Alpha systems running Windows NT.

 0x08
MSJDBG_DISABLE_JIT_COMPILED_CODE_DEBUGGING

Notifies the Microsoft VM that JIT-compiled code debugging is disabled.

 0x10
MSJDBG_DEBUG_NATIVE_METHODS

Notifies the Microsoft VM that it should return native, COM, and delegate stack frames in call stacks, and allow stepping into these frames.

 0x20
MSJDBG_SEND_START_CLASS_EVENTS

Notifies the Microsoft VM that it should send StartClassEvents when a Java application, applet, or COM object is loaded by the Microsoft VM.

 0x40
MSJDBG_SEND_CAN_STOP_EVENT_ON_STEP_OUT

Notifies the Microsoft VM that it should send a CanStopEvent on leaving the stepping frame. Otherwise, a StepEvent will be sent.

 0x80
MSJDBG_EXCEPTIONS_REQUIRE_EXPLICIT_CATCHER

Allows last-chance exceptions to be discovered earlier.

 0x100
MSJDBG_IGNORE_METHODS_WITHOUT_DEBUG_INFO

Notifies the Microsoft VM that it should ignore Java methods without source line mapping information while stepping.

 0x200
MSJDBG_STEP_AT_THREAD_REENTRY

Notifies the Microsoft VM that it should, when stepping out of a topmost Java stack frame, send a CanStopEvent or StepEvent on entry to the next debuggable stack frame. The default behavior is to stop stepping when exiting a topmost stack frame.

 0x400
MSJDBG_CREATE_NULL_OBJECTS

Notifies the Microsoft VM that it should never return E_NULLOBJECTREF from GetFieldObject. Instead, return an IRemoteObject representing the null object reference. This is necessary to enable a debugger to set data breakpoints on object references that are currently null.

 0x800
MSJDBG_STRICT_TYPE_CHECKS

Notifies the Microsoft VM that it should never return an interface that may be used in a type-unsafe way. The default behavior is to allow QueryInterface to succeed for any IRemoteXXXXObject on any primitive data location. For example, setting this flag prevents the debugger from reading an integer location as a double.

 0x1000
MSJDBG_REGULAR_DEBUG_STRING_EVENT

Notifies the Microsoft VM that it should disable compatibility modes for DebugStringEvent.

Implement DebugStringEvent as follows:

  • Sensibly interpret control characters in the string. The Microsoft VM automatically converts isolated \r and \n characters to \r\n pairs.

  • Convert, if necessary, and display the Unicode characters in the string appropriately.

  • Display the string in a timely manner. A debugger should not wait until a \r\n to display the output.

  • Permit multiple lines in the string.

  • Permit empty strings (blank lines).
 0x2000
MSJDBG_STACK_FRAME_IDENTITY

Turns on identity for the frame returned from IRemoteThread::GetCurrentFrame. Without this flag, a new IRemoteStackFrame is provided after execution has possibly occurred, and the old one will become invalid.

 0x4000


Enabling Debugging with Win32 Registry Settings

You can also enable debugging and configure debug options with registry settings. The registry keys connected with the Microsoft VM debugging interfaces are HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM and HKEY_CURRENT_USER\Software\Microsoft\Java VM.

HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM

Note the space between Java and VM in the name of this registry key.

Under this key, you can enter or modify the following entries and values:

Debug

When this key exists before the Microsoft VM begins execution, debugging will be enabled.

DebuggingFlags

Set this value to a DWORD that indicates the value of the debug options.

HKEY_CURRENT_USER\Software\Microsoft\Java VM

Note the space between Java and VM in the name of this registry key.

Under this key, you can enter or modify the following entries and values:

EnableFI

Set this value to a DWORD that indicates whether the fast interpreter is enabled. A non-zero value enables the fast interpreter, while a value of 0 (zero) disables it. The fast interpreter is enabled by default.

EnableJIT

Set this value to a DWORD that indicates whether the JIT compiler is enabled. A non-zero value enables the JIT compiler, while a value of 0 (zero) disables it. The JIT compiler is enabled by default.

You can set registry values in code similar to the following:

const char s_cszDebugKey[] = "Software\\Microsoft\\Java VM\\Debug";
// Create the Microsoft VM Debug key.
// Return TRUE on success; FALSE on failure.
BOOL CreateDebugKey(void)
{
    BOOL bResult = FALSE;
    HKEY hkeyDebug;
    DWORD dwDisposition;
    If (RegCreateKeyEx(HKEY_LOCAL_MACHINE, s_cszDebugKey, 0,
                       NULL, 0, KEY_WRITE, NULL, &hkeyDebug,
                       &dwDisposition)
        == ERROR_SUCCESS)
    {
        bResult = TRUE;
        RegCloseKey(hkeyDebug);
    }
    return(bResult);
}

Use these registry settings carefully. These settings affect all Java applications, applets, and COM objects started under the Microsoft VM. Enabling debugging disables certain optimizations in the Microsoft VM, invokes a slower than usual version of the Java bytecode interpreter, and requires more resources. If the Debug registry entry is not explicitly removed when debugging is no longer needed, performance of all Java applications, applets, and COM objects will be slower.

Remove registry settings with code such as the following:

// Delete the Microsoft VM Debug key.
// Return TRUE on success; FALSE on failure.
BOOL DeleteDebugKey(void)
{
    return(RegDeleteKey(HKEY_LOCAL_MACHINE, s_cszDebugKey)
      == ERROR_SUCCESS ? TRUE : FALSE);
}

You can also add, remove, or modify registry settings with the Regedit.exe utility that is included with Windows 95 and Windows NT.


Enumerating Debuggable Service Processes

You obtain an IJavaEnumRemoteProcess enumerator for the active Java processes by calling GetActiveProcesses. However, if you are logged on to Microsoft® Windows NT® under the system account, GetActiveProcesses may not enumerate all debuggable Java service processes.

Use dcomcnfg.exe (in your %Windir%\System[32] directory) to set the default access permissions. Dcomcnfg.exe manipulates some registry values under HKEY_LOCAL_MACHINE\Software\Microsoft\OLE.

To allow enumeration of all debuggable Java service processes

  1. Run dcomcnfg.exe to display the Distributed COM Configuration Properties dialog box.

  2. Click the Default Security tab.

  3. In the Default Launch Permissions group box, click the Edit Default button.

  4. Make sure that Interactive and System are allowed to launch applications. If they're not listed, add them. This modifies the DefaultLaunchPermission REG_BINARY ACL value under the OLE registry key.

  5. Click OK to close the Registry Value Permissions dialog box.

  6. In the Default Access Permissions group box, click the Edit Default button.

  7. Make sure that Interactive and System are allowed to access applications. If they're not listed, add them. This modifies the DefaultAccessPermission REG_BINARY ACL value under the OLE registry key.

  8. Click OK to close the Default Access Permissions dialog box.

This can also be accomplished programmatically. Each registry value is an access control list (ACL). The DCOMPERM.CPP sample in MSDN demonstrates how to manipulate DCOM permissions. See especially the ChangeDefaultAccessACL( ) and ChangeDefaultLaunchACL( ) methods in DCOMPERM.CPP.


Registering with the Debugger Manager

To use the debugger interfaces, a debugger program must call specific methods of the registration interfaces implemented by the Microsoft VM. See the Registration Debugger Interfaces reference for details.

An application registers with the Microsoft VM

  1. Call the COM library function CoCreateInstance or CoCreateInstanceEx.

  2. Pass in CLSID_RemoteJavaDebugManager, which is the class identifier (CLSID) of the debug manager.

  3. Pass in IID_IRemoteDebugManager, which is the interface identifier (IID) of the IRemoteDebugManager interface.

    CLSID_IRemoteDebugManager, IID_IRemoteDebugManager, and the other debugger GUIDs are defined in the JavaDbg.h file that is installed in the Include directory of the SDK for Java. The JavaDbg.h include file also contains definitions of the debugger interfaces.

    The following sample code illustrates how to obtain an IRemoteDebugManager interface pointer to start debugging.

    #include <JavaDbg.h>
    // Initialize OLE on this thread.
    HRESULT hr = CoInitialize(NULL);
    if (SUCCEEDED(hr))
    {
        IRemoteDebugManager *pirdm;
        // Create a RemoteJavaDebugManager to initiate debugging.
        hr = CoCreateInstance(CLSID_RemoteJavaDebugManager, NULL,
                              CLSCTX_LOCAL_SERVERALL,
                              IID_IRemoteDebugManager,
                              (PVOID *)&pirdm);
        if (SUCCEEDED(hr))
        {
            // Begin debugging.
        }
        // Uninitialize OLE on this thread when done.
        CoUninitialize();
  4. Register with the Microsoft VM's debugger manager, passing in its callback interface pointer, through which the VM will communicate with the debugger.

    The debugger implements COM interfaces that receive callback notifications from the VM.

  5. Call the RegisterCallback method on this interface to register for Java process startup notification.

  6. Call RequestCreateEvent to request being informed when a Microsoft VM starts a new Java process.

    Use the RequestCreateEvent method to achieve any of the following results:

    • Register to receive notification for the next Java process that starts.

    • Register to receive notification for a specific Win32 process.

    • Register to receive notification as soon as the Microsoft VM starts in that process.

    • Register to receive notification for a specific Java class.
  7. Obtain an IJavaEnumRemoteProcess enumerator for the active Java processes by calling GetActiveProcesses.

    Note If you are logged on to Microsoft® Windows NT® under the system account, GetActiveProcesses may not enumerate all debuggable Java service processes. This is a DCOM security configuration issue, and is addressed in Enumerating Debuggable Service Processes.

  8. Debug a specific process using IRemoteProcess to register a callback to receive notifications and information from the Microsoft VM regarding that process.

    When a debugger has obtained an IRemoteProcess for an active Java process (either through enumeration or from receiving a ProcessCreateEvent method call), it can attach to and debug the Java process.

The following sample code illustrates registering to receive a ProcessCreateEvent when a particular Win32 process starts up the Microsoft VM.

// Request notification when the Microsoft VM starts up in Win32 process
// dwProcessID.
HRESULT hr = m_pirdm->RequestCreateEvent("", dwProcessID);

If the Java application, applet, or COM object was previously started using the Win32 CreateProcess function and was subsequently suspended, it can now be resumed.


Implementing Callback Notification Interfaces

For the Microsoft VM to communicate with a debugger, the debugger registers with the debugger manager and passes in pointers to its notification interfaces. The Java debugger implements two COM interfaces for this callback mechanism:

  • IRemoteDebugManagerCallbackEx provides notification of a new process creation.

  • IRemoteProcessCallbackEx2 is used for debugging that Java process.

See the Notification Debugger Interfaces reference for details.

The debugger is notified through its ProcessCreateEvent method that a new Java process has been created. If the debugger decides to, it can register to receive notifications regarding this specific Java process. The IRemoteProcessCallbackEx2 interface is the primary way the Microsoft VM communicates with the debugger about a specific Java process. This callback has a large number of event notification methods that are implemented by the debugger.

Objects underlying the COM objects are obtained by a debugger application from the Microsoft VM. These underlying objects are obtained through an event callback notification or by calling VM-implemented methods. Certain VM-implemented methods will fail once the associated object's lifetime is over. For example, calling the Step method will fail on an IRemoteThread whose associated Java thread has already terminated.

After a debugger registers an interest in a particular Java process (IRemoteProcess), it will receive calls to its ClassLoadEvent method for each class that was loaded before the debugger was attached. After notifications are made for all the currently loaded classes, a LoadCompleteEvent is received. After this notification, any other ClassLoadEvent notifications are sent synchronously for the thread that caused the class to be loaded.

Java process execution is suspended during IRemoteProcessCallbackEx2 method calls. If the debugger returns S_OK from an IRemoteProcessCallbackEx2 method, the Java process remains suspended. Execution of the Java process is resumed when the debugger calls Go. If the debugger returns S_FALSE from an IRemoteProcessCallbackEx2 method, the Java process resumes execution immediately.

IRemoteProcess::FindClass can be used to force a class to be loaded into the Microsoft VM if it is not already loaded. This method has the side effect of causing the debugger to receive ClassLoadEvent method calls. The initializer for the Java class may also run and the debugger will receive events during execution of the initializer. For example, if an exception occurs in the initializer, the debugger will receive an ExceptionEventEx method call.

Thread groups have special meaning for security purposes. Each Java applet is given its own thread group, and the applet can only manipulate threads within that group. These thread groups may be used to differentiate threads among multiple applets.

The debugger is notified when thread groups and individual threads are created and destroyed. Threads are used extensively to get dynamic information when debugging Java code.

The debugger receives notifications on breakpoint and step events. The debugger sets breakpoints and controls execution by calling methods on the execution control interfaces. The execution control interfaces are based on threads.


Retrieving Static Information

Static information on the classes used in a Java process is available through the IRemoteField hierarchy of interfaces. Because many attributes of a class are constant while the class is loaded, this information can be cached by the debugger across execution of the process being debugged. See the Static Information Debugger Interfaces reference for details.

Global classes (classes not defined within other classes) can be thought of as fields of a global class. Access to static information in a Java process is based on using the IRemoteClassField passed on each ClassLoadEvent notification to the debugger. The GetGlobalContainerObject method (one of the interfaces used for retrieving dynamic information) can also be used indirectly to access the root of this object hierarchy and descend it to retrieve IRemoteClassField objects.

The IRemoteContainerField interface includes a GetFields method that returns an enumerator (IJavaEnumRemoteField) for the fields contained by this container. By calling GetFields, a debugger can obtain an enumerator for the fields in a class, or for the local variables in a method, for example.

Line number information entries describe the mapping between Java source code line numbers and bytecode offsets in a compiled method. This information is represented as a list of LINEINFO structures maintained for each method, when available. The IJavaEnumLINEINFO interface provides access to this information.

The LINEINFO structure is defined as follows:

typedef struct lineinfo
{
    USHORT offPC;    // The bytecode offset in a method.
    USHORT iLine;    // The line number, the first line is line 1.
}
LINEINFO;


Retrieving Dynamic Information

Dynamic information on a Java process is available through the IRemoteObject hierarchy of interfaces. These interfaces provide bound access to objects of different types. An object does not necessarily refer to an instance of a class, but represents an instance of any data type. The information obtained from an IRemoteObject is only valid during the lifetime of the actual object that it represents. Consequently, dynamic information cannot be cached by the debugger across execution of the process being debugged.

See the Dynamic Information Debugger Interfaces reference for details.

Java uses a number of built-in types that can be represented as C or C++ typedefs as follows:

// JAVA built-in types.
typedef unsigned char   JAVA_BOOLEAN;
typedef signed char     JAVA_BYTE;
typedef unsigned short  JAVA_CHAR;
typedef double          JAVA_DOUBLE;
typedef float           JAVA_FLOAT;
typedef signed long     JAVA_INT;
typedef hyper           JAVA_LONG;
typedef short int       JAVA_SHORT;
typedef wchar_t         JAVA_STRING;

The IRemoteObject interface implements a set of methods used to get the type of an object, and set or clear data breakpoints on the object. A data breakpoint will fire when the value of the associated object changes. For classes, a data breakpoint will fire when the object references a different instance of that class. For arrays, a data breakpoint will fire when the object references a different instance of the array. GetFieldObject provides a way for a debugger to access fields in a container.

A Java array object is represented by an IRemoteArrayObject interface. The debugger can call GetSize to determine the number of elements in an array. Enumerators for the elements of an array can be obtained by calling GetElementObjects for an array of objects or GetElementValues for an array of primitive data types.


Controlling Execution

Monitoring execution of a Java process is possible through the IRemoteThread and IRemoteStackFrame interfaces. These interfaces provide access to the Java method call stacks of the threads executing in the Java process being debugged. Each stack frame represents a method's state of execution. Consequently, execution state information cannot be cached by the debugger across execution of the process being debugged. See the Execution Control Debugger Interfaces reference for details.

The execution monitoring interfaces consist primarily of the IRemoteThreadGroup, IRemoteThread, and IRemoteStackFrame interfaces and a collection of enumeration interfaces.

The IRemoteThreadGroup and IRemoteThreadGroupEx interfaces implement a set of methods that get the name of a thread group and enumerate the other thread groups and threads in a thread group.

Execution of a Java process is controlled through methods implemented by the IRemoteThread and IRemoteThreadEx interfaces. Methods on these interfaces allow a debugger to suspend or resume execution of a thread, step within a method, step into, over, or out of a call to a method, and get the current stack frame on a thread. Other methods return the name of the thread and the thread group containing this thread.

For notification, many of these methods generate a StepEvent or CanStopEvent call to the debugger on its IRemoteProcessCallbackEx2 interface. If StepEvent or any other debugger event notification callback method returns S_FALSE, Java execution of the process being debugged resumes. If StepEvent or any other debugger event notification callback method returns S_OK, Java execution of the process being debugged remains suspended until Go or some other execution stepping method is called.

The IRemoteThread execution stepping methods all return immediately. While a thread is executing in any stepping mode, the Microsoft VM calls stepping event notification methods on the debugger's IRemoteProcessCallbackEx2 interface to notify the debugger of the thread's changing execution state. A stepping frame is the current stack frame of a thread when one of the thread's stepping methods is called.

The following three tables describe the execution notification events dispatched to the debugger in the three different stepping modes.

Step over mode invoked by Step or RangeStep

Thread execution event | IRemoteProcessCallbackEx2 event notification
Execution about to occur outside stepping range in stepping frame. | StepEvent.
Stepping frame calls method. | None.
Stepping frame returns to caller. | MSJDBG_SEND_CAN_STOP_EVENT_ON_STEP_OUT set: CanStopEvent. MSJDBG_SEND_CAN_STOP_EVENT_ON_STEP_OUT clear: StepEvent.

Step in mode invoked by StepIn or RangeStepIn

Thread execution event | IRemoteProcessCallbackEx2 event notification
Execution about to occur outside stepping range in stepping frame. | StepEvent.
Stepping frame calls method. | CanStopEvent.
Stepping frame returns to caller. | MSJDBG_SEND_CAN_STOP_EVENT_ON_STEP_OUT set: CanStopEvent. MSJDBG_SEND_CAN_STOP_EVENT_ON_STEP_OUT clear: StepEvent.

Step out mode invoked by StepOut

Thread execution event | IRemoteProcessCallbackEx2 event notification
Execution about to occur outside stepping range in stepping frame. | Not applicable (no stepping range).
Stepping frame calls method. | None.
Stepping frame returns to caller. | MSJDBG_SEND_CAN_STOP_EVENT_ON_STEP_OUT set: CanStopEvent. MSJDBG_SEND_CAN_STOP_EVENT_ON_STEP_OUT clear: StepEvent.

Call stacks are accessed through methods implemented by the IRemoteThread, IRemoteThreadEx, and IRemoteStackFrame interfaces. The current stack frame can be returned by calling GetCurrentFrame. An enumerator (IEnumRemoteStackFrames) for a thread's entire call stack can be obtained by calling GetStackFrames.

GetKind returns the execution model of the associated stack frame as one of the values from the FRAMEKIND enumeration.

The IMethodLocation interface represents a location within a method where code can execute. The IMethodLocation interface allows a debugger to set a code breakpoint at interpreted bytecode locations within a source line. This differs from the static information interface method IRemoteMethodField::SetBreakpoint, which always sets a code breakpoint at the first JIT-compiled opcode for the containing source line. The debugger can obtain an enumerator (IEnumCodeBreakpoints) for all IMethodLocation code breakpoints set in a method by calling IRemoteMethodFieldEx::GetCodeBreakpoints.

In some cases, the Microsoft VM may use multiple execution models for a single method (both interpreted and JIT-compiled, for example) executing in different stack frames. Using the IMethodLocation interface for setting code breakpoints yields consistent behavior across these execution models.


Profiler Interfaces Overview

The Java profiler interfaces assist in the analysis of Java code for speed, memory use, redundancy, and other performance factors. The profiler interfaces are Component Object Model (COM) objects and interfaces implemented by the Microsoft VM. The profiler interfaces support any number of concurrently operating event monitors, thus profiling both execution time and memory usage. These interfaces can also profile components that mix Java classes with Microsoft® Win32® native code.

The profiler interfaces are organized into the following categories.

Category | Purpose
Event Monitor Information | Interfaces called by the profiler to request event notification from the Microsoft VM and request information when specific events occur.
Event Notification | Callback interfaces implemented by the profiler through which the Microsoft VM notifies the profiler of various events as they occur.
Heap Monitor Information | The interface called by the profiler to gather information from the Microsoft VM regarding heap memory usage of the Java code being profiled.
Heap Monitor Notification | Callback interfaces implemented by the profiler through which the Microsoft VM notifies the profiler of memory and object allocation information.

This section contains the following topics:

Enabling Profiling in the Microsoft VM discusses the two ways to enable profiling.

Registering with the Microsoft VM for Event Notification shows how to register and initialize an event monitor.

Implementing Event Monitor Information Interfaces gives an overview of the interfaces and methods a profiler must call to use the other optional interfaces.

Implementing Event Notification Interfaces describes the callback interfaces through which the Microsoft VM communicates with the profiler.

Using the Heap Monitor Interfaces gives an overview of those interfaces that allow a memory profiler to collect detailed information on heap memory usage and garbage collection activity for a Java process.

The profiler sets event notification masks and communicates with the Microsoft VM by calling methods on COM objects implemented by the VM. These event masks are passed to the Microsoft VM, indicating the events for which the profiler wants to receive notifications.

The Microsoft VM runtime notifies the profiler about events, and provides requested information in response to method calls made by the profiler on COM objects implemented by the VM.

Under the profiler interfaces, the Microsoft VM uses event types and unique identifiers (UniqueIDs) for notification. These identifiers or handles are specific to the Microsoft VM. In contrast to the VM's debugger interfaces, the profiler interfaces use UniqueIDs rather than COM objects to speed up event notification callbacks, which pass these UniqueIDs as parameters.

The profiler interfaces implemented by the Microsoft VM contain methods that query and set event masks for event notification. These methods return method, class, and object information based on UniqueIDs. The COM objects and interfaces implemented by a profiler use similar methods that notify the profiler of various events, such as class loading and unloading and method entry and exit.

To use the profiler interfaces, you must enable profiling in the Microsoft VM before the Java application or applet begins its execution. You enable profiling by setting environment variables or by creating specific Win32 registry keys before the Java application or applet begins.

A profiler program or event monitor must register itself on the local computer so it can be started by the Microsoft VM when a Java process begins execution.

Using Distributed COM (DCOM) to support remote profiling is not suggested for the following reasons:

  • Remote profiling increases execution time.

  • Profiler and memory monitor programs that use these interfaces cannot be easily extended.

  • Event monitors or profilers must be registered on a local computer with the Microsoft VM. This limits the ability to create a remote profiler using these interfaces with DCOM.

Because the profiler interfaces are based on COM, some general considerations apply when calling the interfaces that are implemented by the Microsoft VM.

When a profiler receives [out] parameters from a method that are pointers to non-primitive data types, the profiler needs to call the CoTaskMemFree function when done with these pointers to free the memory allocated for them by the Microsoft VM.

If the profiler continues to use any COM objects that are created as parameters to a method, the reference count for that object may need to be incremented to ensure that the object remains viable for the duration of the method call. This can be accomplished by calling the AddRef method on the COM interface. The profiler decrements the reference count on the object using the Release method when this object is no longer needed.

The profiler COM interfaces implemented by the Microsoft VM use the free-threading model. Events are dispatched from within the VM or on a thread that is making a profiler method call. Interface methods implemented by the VM can be called any time from any thread that has been CoInitialized.

The examples in this section illustrate the use of the profiler interfaces. They are written in C++ and use local COM objects.

The Microsoft SDK for Java includes samples that illustrate how to use these profiler interfaces. The samples are in C++, and are installed under the %SDKDIR%\Samples\Profiler subdirectory of the Microsoft SDK for Java. For more information, see the Profiler Samples Overview. For information about other samples in this SDK, see the Samples Overview.

See Also

Profiler Interfaces Reference

Debugging and Profiling Java Applications


Enabling Profiling in the Microsoft VM

For the profiler interfaces to be used, profiling must be enabled in the Microsoft VM before it is loaded. You can enable profiling in the Microsoft VM by setting environment variables or by creating Win32 registry settings.


Enabling Profiling with Environment Variables

The preferred method for enabling profiling is to set special environment variables in the Win32 process to be profiled before starting the Microsoft VM (before launching Microsoft® Internet Explorer, for example), and then executing the Java application or applet. Note that the value of these environment variables (when set) override the equivalent settings in the registry.

Profiler Environment Variables

Environment variable | Description and values
MSJAVA_ENABLE_MONITORS | Enables event monitors when set to a non-zero value before the Microsoft VM begins execution. This value defaults to off.
MSJAVA_EVENT_MONITORS | A semicolon-separated list of CLSIDs of event monitors that should be connected to the Microsoft VM in this Win32 process. The Microsoft VM will load all the monitors listed in this environment variable in addition to all the event monitors listed in the registry as subkeys of the HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\Monitors registry key.
MSJAVA_DEBUGGING_FLAGS | A hexadecimal bitmask of debugging flags that primarily affect debugging with the Microsoft VM. One of the bit flags in this mask, MSJDBG_FL_ENABLE_PROFILING (0x02), enables event monitors when it is set before the Microsoft VM begins execution. However, the preferred technique for enabling event monitors in a Win32 process is using the MSJAVA_ENABLE_MONITORS environment variable.
MSJAVA_ENABLE_FI | Enables the fast interpreter when set to a non-zero value. If this environment variable is not set and the equivalent registry value is not set, the fast interpreter is enabled by default.
MSJAVA_ENABLE_JIT | Enables the JIT compiler when set to a non-zero value. If this environment variable is not set and the equivalent registry value is not set, the JIT compiler is enabled by default.

If the MSJAVA_ENABLE_MONITORS string exists in the environment space of a Win32 process and is set to some non-zero value, profiling is enabled in any Microsoft VM that subsequently begins executing within the process.


Enabling Profiling with Win32 Registry Settings

Profiling can also be enabled and configured through the use of registry settings on Microsoft® Windows® 95 and Microsoft® Windows NT®. The registry settings that affect the Microsoft VM when used with the profiler interfaces are located under the keys

HKEY_CURRENT_USER\Software\Microsoft\Java VM

HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM

Note the space between Java and VM.

In the HKEY_CURRENT_USER\Software\Microsoft\Java VM key, you may enter the following values:

EnableEventMonitors

Set this value to a DWORD that indicates whether event monitors (profiling) is enabled. A non-zero value enables event monitors, while a value of zero disables this feature. The default value for this option is disabled if this registry value and the associated environment variable are not set.

EnableFI

Set this value to a DWORD that indicates whether the x86 fast interpreter loop is enabled. A non-zero value enables the fast interpreter, while a value of 0 (zero) disables this feature. The default value for this option is enabled if this registry value and the associated environment variable are not set.

EnableJIT

Set this value to a DWORD that indicates whether the JIT compiler is enabled. A non-zero value enables the JIT compiler, while a value of zero disables this feature. The default value for this option is enabled if this registry value and the associated environment variable are not set.

In the HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM key, you may enter the following value:

DebuggingFlags

Set this value to a DWORD bitmask of flags indicating the state of the various debug options. One of the bit flags in this DWORD, MSJDBG_FL_ENABLE_PROFILING (0x02), enables event monitors when it is set before the Microsoft VM begins execution.

These registry entries are not created by default when you install the Microsoft VM. Set registry settings with code like the following.

const char s_cszJavaVMKey[] = "Software\\Microsoft\\Java VM";
const char s_cszProfilerValue[] = "EnableEventMonitors";
// Create the Microsoft VM profiler (event monitor) value.
// Return TRUE on success; FALSE on failure.
BOOL CreateEventMonitorValue(void)
{
    BOOL bResult = FALSE;
    DWORD dwDisposition;
    HKEY hkeyJavaVM;
    if (RegCreateKeyEx(HKEY_CURRENT_USER, s_cszJavaVMKey, 0, NULL, 0,
                       KEY_SET_VALUE, NULL, &hkeyJavaVM, &dwDisposition)
        == ERROR_SUCCESS)
    {
        DWORD dwEnableEventMonitorsValue = 1;
        if (RegSetValueEx(hkeyJavaVM, s_cszProfilerValue, 0, REG_DWORD,
                          (CONST BYTE *)&dwEnableEventMonitorsValue,
                          sizeof(dwEnableEventMonitorsValue))
            == ERROR_SUCCESS)
            bResult = TRUE;
        RegCloseKey(hkeyJavaVM);
    }
    return(bResult);
}

CAUTION These settings affect all Java applications and applets started under the Microsoft VM. Enabling the event monitors will affect all Java applications by forcing more resources to be used and requiring the Microsoft VM to execute code to handle event monitors.

You can remove or modify registry entries with the Regedit.exe utility that is included with Windows 95 and Windows NT.

You can also remove registry settings using code similar to the following example.

// Delete the Microsoft VM profiler (event monitor) value.
// Return TRUE on success; FALSE on failure.
BOOL DeleteEventMonitorValue(void)
{
    BOOL bResult = FALSE;
    HKEY hkeyJavaVM;
    if (RegOpenKeyEx(HKEY_CURRENT_USER, s_cszJavaVMKey, 0,
        KEY_SET_VALUE, &hkeyJavaVM) == ERROR_SUCCESS)
    {
        if (RegDeleteValue(hkeyJavaVM, s_cszProfilerValue)
            == ERROR_SUCCESS)
            bResult = TRUE;
        RegCloseKey(hkeyJavaVM);
    }
    return(bResult);
}


Registering with the Microsoft VM for Event Notification

To register an event monitor using the registry, a profiler program must create registry settings under the key:

HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\Monitors\<monitor key name>

Replace <monitor name> with the monitor that is being registered. Note the space between Java and VM.

You can set the following values the monitor key name:

default value

A REG_SZ entry containing a text description of the event monitor.

CLSID

A REG_SZ entry containing the CLSID of the class that implements the callback interface of the event monitor (profiler). Event monitors can also be registered by setting an environment variable before the Microsoft VM starts execution. A profiler program may set the MSJAVA_EVENT_MONITORS environment variable to a semicolon-separated list of CLSIDs of event monitors that should be connected to the Microsoft VM in this Win32 process. These CLSIDs are specified as ASCII strings with braces ({}) in the same format used in the registry. The Microsoft VM will load all the monitors listed in this environment variable in addition to all the event monitors listed in the registry as subkeys of the HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\Monitors registry key.

CAUTION When setting this environment variable, be careful not to overwrite an existing CLSID from another event monitoring program. If this environment variable already exists, the profiler application should append a semicolon followed by its own CLSID.


Initializing Event Monitors

Once a profiler is registered, the Microsoft VM attempts to load the profiler whenever a new Java process is started with profiling enabled. Whenever the Microsoft VM is first loaded in a Win32 process, it checks the registry for any event monitor entries under the HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\Monitors key and checks for the existence of the MSJAVA_EVENT_MONITORS environment variable. If profiling is enabled, the Microsoft VM calls CoCreateInstance on each event monitor's CLSID and calls the object's Initialize method.

Note The event monitor lists are not checked for duplicates. If a CLSID is specified multiple times in the registry, the environment variable, or both, the associated profiler is loaded multiple times.

As one of the parameters to the Initialize method, the profiler is passed a pointer to the event monitor information interface, IJavaEventMonitorIDInfo, implemented by the Microsoft VM. This interface can then used by the profiler to communicate with the Microsoft VM. The Initialize method is also passed a bitmask of flags that represent the Microsoft VM's execution state. The profiler returns another bitmask of flags indicating the list of events for which it wants to receive notification. The profiler can also later call SetEventMask to change the list of events that will trigger notification to the profiler.

After all registered monitors have been instantiated, the Microsoft VM initializes the monitors. Certain APIs are only functional during the monitor's Initialize callback; after this time, they will either not function at all or will not have their full effect.

The following lists the settings that must be enabled or disabled during the Initialize callback, and the effects of attempting to modify the settings after this time.

  • JVM_MONITOR_SAMPLING

    Enabling or disabling this event category has no effect. This category may be enabled by returning it through the prerequested_events out parameter of the monitor's Initialize callback, or by calling SetEventMask during the Initialize callback.

  • JVM_HEAPMON_OBJECT_AGE

    Attempting to modify this setting through ModifyHeapMonitorCapabilities will return E_FAIL.

  • Any of the JAVA_MONITOR_INIT_OPTIONS

    Attempting to modify these settings through SetMonitorInitializationOptions will return E_FAIL.

After the Initialize callback returns, the monitor will later receive a NotifyEvent2 callback for the JVM_EVENT_TYPE2_MONITORS_INITIALIZED event. This event provides the number of attached event monitors and the maximum set of event categories that all attached event monitors have indicated that they may ever enable. Monitors may use this information to adjust the accuracy of profiling information. The monitor may call GetFinalInitializationOptions to determine which of the JAVA_MONITOR_INIT_OPTIONS initialization options were able to be used.

JAVA_MONITOR_INIT_OPTIONS

Constant | Value | Description
JVM_INIT_OPT_DONT_NEED_ ALLOCATION_CALLBACK | N/A | Indicates the profiler will not register an IObjectAllocationCallback via IJavaHeapMonitor::NotifyOnObjectAllocations. If this option is enabled and IJavaHeapMonitor::NotifyOnObjectAllocations is called with a non-NULL callback interface, it will return E_FAIL. Setting this and the JVM_INIT_OPT_DONT_NEED_ALLOCATION_COUNTS flag allows the Microsoft VM to use the normal uninstrumented JIT allocation helpers.
JVM_INIT_OPT_DONT_NEED_ ALLOCATION_COUNTS | N/A | Indicates that allocation counts aren't needed from IJavaEventMonitorIDInfo::ClassInformation. If the pobjects_created parameters is specified, its output value is indeterminate. Setting this and the JVM_INIT_OPT_DONT_NEED_ALLOCATION_CALLBACK flag allows the Microsoft VM to use the normal uninstrumented JIT allocation helpers.
JVM_INIT_OPT_FP_SAFE_ METHOD_CALLS | 0x1 | The monitor agrees to preserve floating point state during MethodEntry, MethodExit, and MethodExit2 callbacks. If the monitor modifies floating point state, operation of the profilee may be adversely affected.
JVM_INIT_OPT_GC_SAFE_ METHOD_CALLS | 0x2 | The monitor will not enable garbage collection during MethodEntry and MethodExit2 callbacks. Operations that enable garbage collection include calling any VM APIs, and directly or indirectly causing Java code to execute. IJavaEventMonitorIDInfo APIs may be called, except for those that are explicitly noted as enabling garbage collection. (Currently, none of these APIs enable garbage collection.) Performing a garbage collection-enabling operation may have unpredictable effects. A monitor should only enable this option if it intends to perform a small amount of work during method call events and will not make use of externally implemented components.
JVM_INIT_OPT_RETURN_ VALUE_NOT_NEEDED | 0x4 | The monitor will not call GetMethodExitReturnValue. If the monitor calls this method, it will return E_FAIL.
JVM_INIT_OPT_WONT_TOGGLE _METHOD_CALL_EVENTS | 0x8 | The monitor will not toggle JVM_MONITOR_METHOD_CALLS or JVM_MONITOR_SPECIFIC_METHOD_CALLS after initialization by calling SetEventMask. If this is attempted, SetEventMask will return E_FAIL.

Use the settings of JAVA_MONITOR_INIT_OPTIONS during initialization of the Microsoft VM to optimize profiling overhead. Without these options, the VM selects the most general profiling mechanism. By enabling these options, the monitor agrees not to perform certain operations that this general procedure permits, so that a better profiling mechanism may be selected. These options are enabled or disabled by calling SetMonitorInitializationOptions during the monitor's Initialize callback.

Enabling both JVM_INIT_OPT_GC_SAFE_METHOD_CALLS and JVM_INIT_OPT_WONT_TOGGLE_METHOD_CALL_EVENTS produces a substantial improvement in JIT-compiled method call event overhead. Additionally enabling JVM_INIT_OPT_FP_SAFE_METHOD_CALLS and JVM_INIT_OPT_RETURN_VALUE_NOT_NEEDED produces small improvements.

Older event monitor implementations may not be aware of these new initialization options, but may not perform the associated actions and could benefit from the performance improvement. To force an older event monitor to make use of these options, a DWORD value, InitOptions, may be added under the event monitor's registry key. The Microsoft VM will use this value as though the monitor called SetMonitorInitializationOptions.


Implementing Event Monitor Information Interfaces

A profiler must call specific methods of the event monitor information interfaces to use the other optional interfaces.

The event monitor information interfaces implemented by the Microsoft VM derive from IJavaEventMonitorIDInfo. IJavaEventMonitorIDInfo enables the profiler to communicate with the Microsoft VM to control event monitoring and information requests. IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 add several new methods.

A profiler can call QueryInterface on the IJavaEventMonitorIDInfo interface object passed to its Initialize method to determine if the Microsoft VM supports the IJavaEventMonitorIDInfo2 or IJavaEventMonitorIDInfo3 interfaces.

IID_IJavaEventMonitorIDInfo, IID_IJavaEventMonitorIDInfo2, IID_IJavaEventMonitorIDInfo3, and IIDs for all the other profiler interfaces are defined in the Jevmon.h file that is installed in the \Include directory of the Microsoft SDK for Java. Jevmon.h also contains definitions of the profiler interfaces.

This section contains the following topics:

Collecting Sampling Data discusses data sampling as a way to profile a Java application or applet.

Controlling Method Call Events shows how to control whether method notifications are received for all method calls or only specific ones.

For specific event monitor interfaces and their methods, see the Event Monitor Information Profiler Interfaces Reference.


Collecting Sampling Data

The profiler interfaces support the ability to collect sampling information as a way to profile a Java application or applet. To collect sample data, a profiler must arrange a way to call SampleThreadLocation at periodic intervals.

A profiler is free to use a variety of methods to make periodic calls to SampleThreadLocation. The profiler can call this method in a loop followed by Win32 Sleep function calls. The profiler can set a short timer and call this method when the timer expires. The profiler can use other schemes (waiting for other events) to trigger when to call this method.


Controlling Method Call Events

The profiler interfaces allow a profiler to control whether Java method call events (notifications) are received on a global basis (for all method calls) or only for specific methods. To control method call events for a specific method, the profiler must have set the bitmask for event type categories for which the Microsoft VM will send event notifications to include JVM_MONITOR_SPECIFIC_METHODS.

The EnableMethodCallEvents method can be used to query the current settings, enable method notification callbacks, or disable method notification callbacks (MethodEntry, MethodExit, or MethodExit2 calls) for a specific method. The profiler passes in a UniqueID of the method or class that it is concerned with, a JVM_ID_TYPE enumeration value that represents the type of the UniqueID, and a JVM_METHOD_CALL_EVENTS_DISPOSITION enumeration value that represents the disposition requested for the given UniqueID.


Implementing Event Notification Interfaces

The profiler must implement a COM object for the profiler event notification mechanism. When events occur for which the profiler has indicated it wants to be notified, COM interface methods implemented by the profiler are called by the Microsoft VM.

The two notification interfaces are IJavaEventMonitor and IJavaEventMonitor2. IJavaEventMonitor is the primary callback interface through which the Microsoft VM communicates with the profiler. For details on these interfaces and their methods, see the Event Notification Profiler Interfaces Reference.

A profiler will normally implement the IJavaEventMonitor2 interface. All these interface methods return S_OK on success and E_FAIL on failure. The Microsoft VM will call QueryInterface on the profiler object's IJavaEventMonitor interface to determine if the IJavaEventMonitor2 interface is supported. If IJavaEventMonitor2 is supported by the profiler, the Microsoft VM will call methods on that interface instead of IJavaEventMonitor.

This section contains the following topics:

Profiler UniqueIDs discusses the handles used by the Microsoft VM to refer to classes, methods, fields, instances, threads, and so on.

Event Types Used for Notification discusses the enumerated event types that determine UniqueIDs.

Retrieving Static Class Information gives an overview of those methods that allow a profiler to retrieve static information about active Java processes.

Retrieving Dynamic Information with the Profiler gives an overview of those methods that allow a profiler to dynamic static information about active Java processes.


Profiler UniqueIDs

UniqueIDs are opaque handles to items inside the Microsoft VM. The profiler interfaces use UniqueIDs to refer to classes (ClassIDs), class methods (MethodIDs), class fields (FieldIDs), instances of Java objects (ObjectIDs), threads (ThreadIDs), and other objects.

Note that ClassIDs and MethodIDs for a class are not valid after a class is unloaded. An expired UniqueID may be reused by the VM to identify objects of other types. Except for ObjectIDs and StackIDs, the expiration of a UniqueID is indicated by the appropriate event type. For example, a ClassID and all its MethodIDs and FieldIDs expire when a CLASS_UNLOAD event is received.

No UniqueIDs expire during profiler callbacks. All UniqueIDs except ObjectIDs are valid across event callbacks until the profiler returns from the corresponding expiration event callback.

StackIDs become invalid when the identified stack frame returns. StackIDs also become invalid when the ThreadID for the thread the StackID was executing becomes invalid, as indicated by the JVM_EVENT_TYPE_THREAD_DESTROY value of the JVM_EVENT_TYPE enumeration.

UniqueID | Expiration
ThreadID | JVM_EVENT_TYPE_THREAD_DESTROY.
StackID | JVM_EVENT_TYPE2_EXCEPTION_UNWIND, or MethodExit or MethodExit2 callbacks.
ObjectID | Immediate or during heap enumeration upon receipt of the C_END container event.
ObjectHandleID | Never. Must be explicitly freed by the profiler by using FreeHandlesToObjects, or implicitly by GetObjectsFromHandles.
MethodID | JVM_EVENT_TYPE_CLASS_UNLOAD for containing class.
FieldID | JVM_EVENT_TYPE_CLASS_UNLOAD for containing class.
ClassID | JVM_EVENT_TYPE_CLASS_UNLOAD.

ObjectIDs are only valid between garbage collections; a different ObjectID may be used for the same object after garbage collection. Consequently, ObjectIDs should only be used during the event callback in which they were provided. Persistent handles obtained using the GetHandlesToObjects method must be used for long-term tracking of objects in memory. The GetObjectFromHandles method may be used to obtain the current ObjectIDs for the objects represented by the handles. Note that owning a persistent handle to an object will not prevent the object from being garbage collected.

The Microsoft VM does not perform parameter validation of any UniqueIDs to improve performance of the profiler and reduce profiling overhead. Profilers should use only IDs that were successfully obtained through callbacks or profiler interfaces.

NULL is a valid ObjectID because it may be successfully provided by a callback method. NULL is not valid for any other type of ID, except where noted. For example, SampleThreadLocation and GetStackTrace allow NULL for an ID parameter to avoid having to always first call GetCurrentThread.


Event Types Used for Notification

The profiler receives method calls (event notifications from the Microsoft VM) on its Java event notification interface when various events occur. The NotifyEvent method receives an event type passed as its first parameter along with a UniqueID for the second parameter. The type of the UniqueID passed to NotifyEvent is determined by the event type. See NotifyEvent for the possible event types from the JVM_EVENT_TYPE enumeration and the associated UniqueIDs passed to the NotifyEvent method.

Certain events may require special synchronization with the use of methods that operate on the event's parameters. For example, the ThreadInformation method should not be called on a ThreadID that a profiler has received a JVM_EVENT_TYPE_THREAD_DESTROY event for. The Microsoft VM does not verify that the thread associated with the given ThreadID is still valid. Profilers should take care to synchronize destruction event notifications with uses of UniqueIDs to ensure that the last use of a UniqueID occurs before returning from handling the associated destruction event. Those Events and UniqueIDs that need to be synchronized are also described in the NotifyEvent topic of the Java Profiler Interfaces Reference.

NotifyEvent2 receives an event type passed as its first parameter along with two UniqueIDs. The types of the UniqueIDs passed to NotifyEvent2 are determined by the event type.


Retrieving Static Class Information

The profiler interfaces include a number of methods that allow a profiler to retrieve static information regarding the Java process being executed. Static information on Java classes can also be retrieved by a program that uses the debugger interfaces. While the profiler interfaces are not as numerous as the debugger interfaces, the overhead incurred on the Microsoft VM by using the profiler interfaces is significantly lower than that incurred by using the debugger interfaces. Consequently, it is recommended that profilers use the profiler interfaces to retrieve static information on Java classes.

The starting point for retrieving static information on Java classes is based on using the UniqueIDs passed to the event notification methods that are implemented by a profiler. The methods that receive UniqueIDs of various types include NotifyEvent, MethodEntry, NotifyEvent2, and MethodExit2. Using these UniqueIDs (ClassIDs and MethodIDs, for example), a profiler can call methods implemented by the Microsoft VM to gather detailed static information on all the classes, class methods, and class fields used by a Java application or applet.

If event notification is enabled for class loads (JVM_MONITOR_CLASS_LOADS), a profiler will be notified when Java classes are loaded and unloaded. The UniqueID passed to the NotifyEvent method when a class load is finished (JVM_EVENT_TYPE_CLASS_LOAD_FINISHED) is the ClassID of the class that was loaded. The UniqueID passed to the NotifyEvent method when a class is unloaded (JVM_EVENT_TYPE_CLASS_UNLOAD) is the ClassID of the class that was unloaded. Note that the ClassID and MethodIDs from a class become invalid after the class has been unloaded. Once a class is unloaded, the profiler must not make calls to the Microsoft VM with a ClassID or MethodIDs for the unloaded class.

The following table indicates some event notification methods and associated UniqueIDs that can be used for gathering static information.

Method | Event type | UniqueID | Comments
NotifyEvent | JVM_EVENT_TYPE_ CLASS_LOAD_STARTED | None | Passes class name as a UTF-8 string. Notification on class loads (JVM_MONITOR_CLASS_ LOADS) must be enabled.
NotifyEvent | JVM_EVENT_TYPE_ CLASS_LOAD_FINISHED | ClassID | Notification on class loads (JVM_MONITOR_CLASS_ LOADS) must be enabled.
NotifyEvent | JVM_EVENT_TYPE_ CLASS_UNLOAD | ClassID | Notification on class loads (JVM_MONITOR_CLASS_ LOADS) must be enabled.
NotifyEvent | JVM_EVENT_TYPE_JIT_ COMPILE_STARTED | MethodID | Notification on JIT compilation (JVM_MONITOR_JIT_ COMPILATION) must be enabled.
NotifyEvent | JVM_EVENT_TYPE_JIT_ COMPILE_FINISHED | MethodID | Notification on JIT compilation (JVM_MONITOR_JIT_ COMPILATION) must be enabled.
MethodEntry | Method entered | MethodID | Notification on method calls (JVM_MONITOR_METHOD_CALLS or JVM_MONITOR_SPECIFIC_METHOD_CALLS) must be enabled.
MethodExit2 | Method exited | MethodID | Notification on method calls (JVM_MONITOR_METHOD_CALLS or JVM_MONITOR_SPECIFIC_METHOD_CALLS) must be enabled.

Using ClassIDs, a profiler can call methods implemented by the Microsoft VM to navigate the hierarchy of a class and gather static information on class methods and fields. Some of the methods that can be used for this purpose are as follows.

Use ClassInformation and MethodInformation to retrieve basic information on a class and its methods. Most of this information parallels the information available with the Java Reflection APIs.

Use FieldInformation, GetClassFields, and StaticClassInformation to retrieve additional static information on a class and its methods and fields.

Use GetSpecialClassProperties to return a list of classes with special properties. Classes for which special information is available include instances of java.lang.Class, java.lang.reflect.Method, java.lang.reflect.Field, java.lang.String, and java.lang.StringBuffer. Use DescribeObject to retrieve this additional descriptive information.

Use ClassInformation2 to retrieve more detailed information about a class, its methods, its interfaces, and its superclass. An interface may appear in the returned interface list more than once. Base interfaces of explicitly implemented interfaces will be in the list. Consequently, it is not necessary to call ClassInformation2 again for each listed interface to retrieve the interfaces implemented by a superclass.


Retrieving Dynamic Information with the Profiler

The profiler interfaces include a number of methods that allow a profiler to retrieve dynamic information regarding the Java process being executed. Dynamic information on Java processes can also be retrieved by a program that uses the debugger interfaces. While the profiler interfaces do not have as many and varied features as the debugger interfaces, the overhead incurred on the Microsoft VM by using the profiler interfaces is significantly lower than that incurred by using the debugger interfaces. Consequently, it is recommended that profilers use the profiler interfaces to retrieve dynamic information on a Java process.

The starting point for retrieving dynamic information on a Java process is based on using the UniqueIDs passed to the event notification methods that are implemented by a profiler. The methods that receive UniqueIDs of various types include NotifyEvent, NotifyEvent2, MethodEntry, and MethodExit2. Using these UniqueIDs (ClassIDs and MethodIDs, for example), a profiler can call methods implemented by the Microsoft VM to gather detailed dynamic information on all threads, stack frames, class instances, and class fields that are used by a Java process.

If event notification is enabled for class loads (JVM_MONITOR_CLASS_LOADS), a profiler will be notified when Java classes are loaded and unloaded. The UniqueID passed to the NotifyEvent method when a class load is finished (JVM_EVENT_TYPE_CLASS_LOAD_FINISHED) is the ClassID of the class that was loaded.

If event notification is enabled for method calls (JVM_MONITOR_METHOD_CALLS or JVM_MONITOR_SPECIFIC_METHOD_CALLS), a profiler will be notified when a Java method is entered and exited. The MethodEntry method is passed the StackID and MethodID of the method about to be entered. The MethodExit2 method is passed the StackID and MethodID of the method that is about to be exited to. If event notification is enabled for JVM_MONITOR_SPECIFIC_METHOD_CALLS, the profiler can enable and disable whether it will receive method event calls on a method-by-method basis.

After gathering static information (as noted in the section on Retrieving Static Class Information), a profiler can retrieve dynamic information on these objects.

The following table indicates some event notification methods and associated UniqueIDs that can be used for gathering dynamic information.

Method | Event Type | ObjectID | Comments
NotifyEvent | JVM_EVENT_TYPE_ EXCEPTION_OCCURRED. | StackID | Notification on exceptions (JVM_MONITOR_ EXCEPTIONS) must be enabled.
NotifyEvent | JVM_EVENT_TYPE_ THREAD_CREATE. | ThreadID | Notification on threads (JVM_MONITOR_THREADS) must be enabled.
NotifyEvent | JVM_EVENT_TYPE_ THREAD_DESTROY. | ThreadID. | Notification on threads (JVM_MONITOR_THREADS) must be enabled.
NotifyEvent | JVM_EVENT_TYPE_GC_ STARTED. | None | Notification on garbage collections (JVM_MONITOR_GARBAGE_ COLLECTIONS) must be enabled.
NotifyEvent | JVM_EVENT_TYPE_GC_ FINISHED. | None | Notification on garbage collections (JVM_MONITOR_GARBAGE_ COLLECTIONS) must be enabled.

Using ClassIDs, a profiler can call methods implemented by the Microsoft VM to navigate the hierarchy of a class and gather static information on class methods and fields. Using ClassIDs, FieldIDs, ObjectIDs, ThreadIDs, StackIDs, and other UniqueIDs, a profiler can determine dynamic information regarding the executing Java process.

Use GetMethodEntryParameters to retrieve the parameters that were passed to a method before execution of the method begins. The calling convention for the method about to be executed can be any of the values defined in the JVM_CALLING_CONVENTION enumeration. A profiler can only call GetMethodEntryParameters during a MethodEntry callback notification. The Microsoft VM returns a pointer to the base of the array of parameters that are passed to the current method, a bitmask of call flags, and a value that represents the calling convention for the method.

Use GetMethodExitReturnValue to retrieve the return value from the method call that just returned. The profiler can only call GetMethodExitReturnValue during a MethodExit or MethodExit2 callback notification. The Microsoft VM returns the MethodID of the method that is exiting and its return value. To properly interpret the return value (its type and value), a profiler would need to parse the signature for this method. Retrieve this parameter signature by calling MethodInformation.


Using the Heap Monitor Interfaces

The heap monitoring interfaces allow a memory profiler to collect detailed information on heap memory usage and garbage collection activity for a Java process. The heap monitoring interfaces allow a memory profiler to receive notification on each object allocation, to track when garbage collections occur, and to retrieve a detailed heap dump after garbage collection.

The heap monitoring interfaces are COM interfaces implemented by the Microsoft VM and a memory profiler (callback routines).

Heap monitoring follows a conceptual model similar to the other profiler interfaces. A memory monitoring application must register with the Microsoft VM, indicating an interest in receiving notifications for heap monitoring and its heap information callback interface. The Microsoft VM will communicate with the profiler through this callback interface. The profiler must register separate callbacks to receive notification when objects are created and for receiving a heap dump after garbage collection.

The heap monitoring interfaces make extensive use of the concept of containers for representing heap usage. Through these containers, a memory profiler can completely rebuild the containment hierarchy for heap memory starting from root containers. Container types are defined for threads, static class references, objects awaiting finalization, internal VM objects, and various stack frames such as native garbage collection and the JIT-compiled, native, COM, interpreted, and fast interpreted methods.

The following sections describe in detail how to use the Java heap monitor interfaces. They include discussion of the following topics:

Registering with the Heap Monitor shows how to determine if the Microsoft VM supports heap monitoring.

Implementing HeapInfo and Object Allocation Callback Interfaces discusses how the Microsoft VM communicates with a memory profiler.


Registering with the Heap Monitor

To use the heap monitoring interfaces, a memory profiler must first determine if the Microsoft VM supports heap monitoring. A profiler can determine if heap monitoring is supported by calling QueryInterface on the IJavaEventMonitorIDInfo interface for the IJavaHeapMonitor interface (IID_IJavaHeapMonitor). For specific interfaces and their methods, see the Heap Monitor Information Profiler Interface Reference.

The IID for the IJavaHeapMonitor interface and the other Java heap monitoring interfaces are defined in Jevmon.h, which is installed in the \Include directory of the Microsoft SDK for Java. Jevmon.h also contains definitions of the heap monitoring interfaces.

IJavaHeapMonitor is used by a memory profiler to communicate with the Microsoft VM. The profiler must call GetHeapInfo to provide a callback through which the Microsoft VM communicates with the profiler regarding heap enumeration after garbage collection.

The profiler must call NotifyOnObjectAllocations to provide a callback through which the Microsoft VM communicates with the profiler for notification on individual Java object allocations.

A memory profiler must register its heap monitoring callback interfaces with the Microsoft VM. To register with the Microsoft VM, a memory profiler must call methods of the IJavaHeapMonitor interface to install callback routines. A memory profiler can register a callback to receive notifications of individual object allocations and a separate callback that can be used to obtain a detailed heap dump after garbage collection.


Implementing HeapInfo and Object Allocation Callback Interfaces

For the Microsoft VM to communicate with a memory profiler, the profiler must register heap monitoring callback interfaces with the Microsoft VM. When events occur for which the profiler has indicated it wants to be notified, methods implemented by the profiler are called by the Microsoft VM. For specific interfaces and their methods, see the Heap Monitor Notification Profiler Interfaces Reference.

The profiler can use the ObjectID and ClassID returned from the OnObjectAllocated method and call any of the profiler methods that take an ObjectID or ClassID to get more information on this object. For example, calling ClassInformation with the ClassID can be used to determine if this object is an instance of a class or an array. If the class name begins with a left bracket ([), this object is an array.

The ObjectID for an object on the heap can change after garbage collection. This can occur at any time, even immediately after returning from the OnObjectAllocated method. If ObjectIDs are to be reused, use GetHandlesToObjects to get persistent handles to the objects.

A profiler registers IHeapInfoCallBack to be informed by the VM that garbage collection has completed, and then receive a heap dump.


Integrating Java and COM

Java/COM integration lets you combine Java's advantages with COM and develop components that can interact with operating systems, applications, and services written in any COM-compliant language on any platform.

Most of the Microsoft® Windows® functionality is exposed through COM, and most Microsoft applications provide COM interfaces to their object models. At the same time, Java offers automatic garbage collection and replaces pointers with references, while the Microsoft virtual machine (Microsoft VM) automatically handles object references, cleanup, and interface queries for any COM object used in Java, whether the component was written in Java or another COM-compliant language. The VM also provides automatic mapping, allowing a Java object to be a COM object, and allowing any COM object to be accessible as a Java object.

This topic covers the following information:

Using COM Objects in Java describes how COM objects are exposed as if they were Java objects by using Java-Callable Wrappers (JCWs) and compiler directives.

Using Java Objects in COM describes how Java objects are exposed as COM components by using COM-Callable Wrappers (CCWs).

Using Jactivex with COM shows how to use jactivex to generate .java files for the classes and interfaces of a type library.

Type Mappings between Java and COM shows the correspondence of non-Java data types with Java data types.

Handling COM Errors in Java discusses HRESULTs and try-catch error-handling blocks.

Apartment Model and Threading Issues describes how the Microsoft VM instantiates COM objects and creates marshaling proxies.

Standard Java/COM Marshaling describes how dissimilar data types are handled and wrapped by the Microsoft VM.

Custom Java/COM Marshaling discusses the marshaling of complex COM library data types with user-defined Java types and hook classes.

Integrating JavaBeans and ActiveX describes how a JavaBean can be hosted by a Microsoft® ActiveX® container, and an ActiveX Control can be hosted by a JavaBean container.

The Java/COM integration features in the Microsoft VM provide access to COM objects from a Java application or exposes Java classes as COM objects. COM objects can be ActiveX Controls or Automation objects that are exposed by an application such as Microsoft® Excel. ActiveX controls are Automation-enabled controls that support the IDispatch COM interface, enabling the control to be scripted.

The Microsoft VM hosts ActiveX Controls in Java. Automation objects (a local application or COM server) may also be accessed from a Java process. The Java/COM integration features in the Microsoft VM and the Microsoft SDK for Java facilitate exposure of Java classes as COM objects for use by other Microsoft® Win32® processes.

The jactivex tool (in this SDK) emits Java source code wrappers for the interfaces implemented by a COM object when used on an ActiveX control, an Automation DLL, an Automation server, or a type library. For ActiveX controls, the emitted Java code includes JavaBean-like code for adding and removing listeners for the events originating from the ActiveX control. It also includes code to appropriately manage the control for its lifetime. For a jactivex overview, see Using Jactivex with COM. For all jactivex command-line arguments, see Jactivex in the Tools Reference.

See Also

Compiler Directives and Attributes Reference
Using COM Objects in Java (Programmer's Guide)
Using COM Objects from Java (White Paper)
Integrating Java and COM (White Paper)


Using COM Objects in Java

This topic addresses the basics of using COM objects in Java and covers the following information:

Object Allocation compares C++ and Java object allocation.

Reference Counting compares C++ and Java reference counting.

Supporting Multiple Interfaces compares C++ and Java multiple interface support.

Implementing IDispatch discusses automatic IDispatch when implementing Automation objects.

Implementing COM Interfaces discusses importing COM interfaces into Java.

Parameters Passed by Reference shows how to retrieve a reference with Java.

To use a COM object as if it were a Java object, each COM object must have a Java-Callable Wrapper (JCW) for exposing its functionality. A JCW is a Java class that has some Microsoft-specific attributes that tell the Microsoft VM how to map the Java object to the COM component that it represents. Jactivex automatically generates JCW Java classes from any dynamic-link library (DLL) containing COM objects, or from any type library produced from a compiled COM object's Microsoft Interface Definition Language (MIDL) definition. Jactivex provides a way to generate classes that you can quickly and easily integrate with your project to leverage existing COM facilities.

To create a JCW, you insert special comments called @com directives in Java source code. Similar @dll directives give Java access to the Microsoft® Win32® APIs using Microsoft® J/Direct™.

Note By default, jvc disables the @com and @dll directives. To enable these, use the jvc /x- option.

The @com directives specify how the Java object maps to the COM equivalent and vice versa. These mappings allow you to customize the Java representation of the COM object to suit a particular application. When these source files are compiled, the @com directives generate Java class attributes, which the Microsoft VM uses to map the COM object to the Java object.

The following table lists the COM-specific directives that the Microsoft Java compiler uses to create a JCW. For a complete description of the directive parameters available for each directive and how to use them, see the Compiler Directives Reference.

Directives | Description
@com.class(GUID, security, casting) | Specifies that this Java object represents a COM coclass with the given GUID, casting support, and Java security requirements.
@com.interface(GUID, thread, type) | Indicates that this Java interface represents a COM interface with the specified GUID, threading model, and types.
@com.method(dispid, vtable, and so on) | Marks the Java method as a COM interface method, which should be exposed in the object's vtable, dispatch table, or neither.
@com.parameters | Used to specify which parameters are in, out, or a return value and how they should be mapped to COM and from COM to Java.
@com.register | Used by the Microsoft® Visual J++® vjreg tool to register the compiled Java class as a COM object in the system registry.
@com.typeinfo | Specifies that additional information from the type library represents this COM object.
@com.transaction | Indicates various transaction situations in which the Microsoft Transaction Server can host COM objects.
@com.struct | Specifies that the Java class will be a Java-Callable Data Wrapper (JCDW).
@com.structmap | Indicates how the field in a JCDW should map to COM and from COM back to this field in Java. This directive can also be used to custom marshal the data between Java and COM and to specify the data's offset from the beginning of the JCDW.

Create a new instance of a COM object in Java by instantiating a JCW Java class. The Microsoft VM creates the COM object that it refers to in addition to tracking its references. A QueryInterface is performed when a JCW is cast to an implemented COM interface using the Java cast operation. When the Microsoft VM sees this operation, it queries the underlying COM object for the interface represented by the JCW being cast to. The resulting interface is returned from the operation. The Java object can then call any methods on the second COM interface as it would any other Java object. The Microsoft VM caches the queried interfaces so that subsequent cast operations are fast.

The key to integrating Java and COM, while maintaining consistency with the Java programming model, is for the Microsoft VM to handle all garbage collection of COM objects, and to map the QueryInterface calls to simple casting operations. This functionality is directly related to how the COM IUnknown interface behaves in Java. The Microsoft VM accomplishes integration by not exposing any of the IUnknown methods to the Java developer and by internally tracking the reference counts. As a result, the developer is freed from possible bugs related to unbalanced reference counts, and avoids the redundant operation of implementing each of the IUnknown methods for each Java/COM object.

The Microsoft VM contains JCDW classes for the COM VARIANT and SAFEARRAY data types. Variants are objects that hold primitive data types, IUnknown, or IDispatch references. Variants can be used as parameters where multiple data types may be passed as parameters, and the actual data type will be determined at runtime. Variants are commonly used in Visual Basic and in COM components for passing data of variable type through Automation interfaces.

A SafeArray object is a COM data type that allows Visual Basic to interact with COM components to pass around variable sized arrays. SafeArrays contain Variant-compatible types and information that describes the type of Variant contained, the starting position of the first element, and the overall length of the SafeArray. The Variant and SafeArray JCDWs contain Java methods that wrap the COM functions used to access the native data types. This makes using Java Variants and SafeArrays intuitive for developers and allows for easy interaction with Visual Basic through COM.

Note When passing an array of JCDW's between COM/Microsoft® Win32® APIs and Java, in either direction, if the JCDW contains complex types such as Strings, then these complex types may not be properly propagated to memory that is not garbage collected. For normal JCDW parameters, the marshaling engine always attempts to propagate structs, but this code is missing from the case of marshaling arrays.


Object Allocation

The following Java statement is identical to Java's syntax for allocating ordinary Java objects. Behind the scenes, the COM API function CoCreateInstance is called instead of allocating space in the runtime heap. However, this call is invisible to the Java programmer.

In C++, you allocate a new COM object using the following syntax:

IDrawable pDrawable;
CoCreateInstance(CLSID_MyCircle, NULL, CLSCTX_SERVER,
                  IID_IDrawable, (void**)&pDrawable);

In Java, the equivalent code looks like this:

IDrawable drawable = (IDrawable)new MyCircle();


Reference Counting

Reference counting is handled automatically in Java. As a result, you can create object references without calling IUnknown::AddRef. In addition, calling IUnknown::Release isn’t required when you're finished using a reference to an object. The Java garbage collector automatically keeps track of how many references there are to an object. In practice, however, you may need to ensure a timely release of shared resources. You can use the com.ms.com.ComLib.release method to force Java to release all of its reference counts on a COM object.

In C++, you release a COM object using the following syntax:

pDrawable->Release();

In Java, the equivalent code looks like this:

import com.ms.com.*;
ComLib.release(drawable);

Calling the release method causes the drawable object to release all of its references to the COM object that it wraps. Because drawable may have cached one or more of the object's interfaces, this call may result in more than one release.

Note If you do not call the com.ms.com.ComLib.release method, normal garbage collection will attempt to perform the release for you. This mechanism is not guaranteed, however, due to the threading limitations of many COM objects. That is, many COM objects can only be called on the thread that they were created on. Because garbage collection occurs at unpredictable times, the required thread may have expired or may no longer be responding to messages by the time garbage collection reclaims the object. In addition, this unpredictability can obscure true memory leaks, tie up important system resources, or both. As a result, use explicit releases to free COM objects quickly and predictably.


Supporting Multiple Interfaces

COM objects support multiple interfaces. Java supports multiple interfaces on objects. This support is probably the most important reason that Java/COM integration works so well.

The following C++ code uses both types of interfaces. The IRobot interface is used to control what the robot does and IRobotDiagnostics determines the status of the robot. First, the robot is instructed to move forward 10 units, and then turn left 90 degrees using the IRobot interface. QueryInterface is used for IRobotDiagnostics, using it to tell the robot to display a status message.

The IRobot interface example written in C++ is as follows:

//  Error handling has been omitted for brevity.
IRobot* probbie = NULL;
IRobotDiagnostics* probbieDiag = NULL;
CoCreateInstance(CLSID_Robot, NULL, CLSCTX_SERVER, IID_IRobot, (void**)&probbie);
probbie->GoForward(10);
probbie->Turn(-90);
probbie->QueryInterface(IID_IRobotDiagnostics, (void**)&probbieDiag);
probbie->OutputStatusMessage();
probbieDiag->Release();
probbie->Release();

The same code, written in Java, looks like this:

import robocorp.bots.*;
Robot robbie = new Robot();
IRobotDiagnostics robbieDiag = null;
robbie.GoForward(10);
robbie.Turn(-90);
robbieDiag = (IRobotDiagnostics)robbie;
robbieDiag.OutputStatusMessage();

Because the Microsoft VM provides the implementation of IUnknown, implementing QueryInterface isn't necessary. The assignment statement does the implicit QueryInterface for IRobotDiagnostics (this is very similar to how QueryInterface is supported in Microsoft® Visual Basic® version 4.0).

COM objects must implement the IUnknown::QueryInterface function to allow clients access to the object's supported interfaces. In Java, the details are handled by the virtual machine. As a result, your source code needs only a typecast.

In C++, you might write code like the following to access the IPrintable interface of the object that pDrawable points to:

// pDrawable points to an object that supports
// both IDrawable and IPrintable.
IPrintable *pPrintable;
pDrawable->QueryInterface( IID_IPrintable,
                           (void **)&pPrintable );

In Java, the equivalent code would look like this:

// drawable refers to an object that supports
// both IDrawable and IPrintable.
IPrintable printable;
printable = (IPrintable)drawable;

Notice that you use the same syntax normally used to cast between Java object types. If the object does not implement the requested interface, a ClassCastException is thrown when you attempt the cast. Alternatively, you can use the instanceof operator to determine whether the object implements the requested interface before the cast is attempted.

An explicit cast to the interface is necessary as it is in normal Java interfaces. If the object does not support the interface you want, an exception is thrown. The standard Java instanceof operator can be used to determine whether a given interface is supported.


Implementing IDispatch

The Microsoft virtual machine implements IDispatch automatically for almost all Java objects. This means that a tool, such as jactivex, is no longer necessary simply to script a Java object from an Automation controller such as Visual Basic or Microsoft® Visual Basic® Scripting Edition (VBScript). The Microsoft VM also provides an implementation of IDispatchEx, which is required for COM object interoperability with some Microsoft scripting technologies.

To implement a simple Automation object in Java

  1. Implement the Java object and compile it.

  2. Register it using javareg.

  3. Ensure that the Java class is visible in the CLASSPATH environment variable.


Implementing COM Interfaces

The interface being implemented is either declared within the code module (file) where implementation occurs, or in an external .class file, which is imported through the import statement. This all usually takes place in the absence of COM.

You cannot define an interface using the interface declaration and import the same interface's declaration from a .class file. This rule is also true for COM interfaces: they are not defined by Java. Instead, a COM interface is defined in a .idl file, compiled into a type library, and then imported into Java as though it were a standard Java .class file.

To implement COM interfaces on a Java class, use the implements modifier in the class declaration with a list of interface names, and provide method bodies for each method in the interfaces (excluding QueryInterface, AddRef, and Release).

The following example shows the IRobot COM interface described in a .idl file:

[ object, uuid(6C6971D5-8E69-11cf-A54F-080036F12502)]
interface IRobot : IUnknown
{
...
         HRESULT OutputStatusMessage([out, retval]BOOL* pRetVal);
...
};

If the .idl file was compiled into the robocorp/bots.tlb type library, the following Java code could be written to implement a Robot object:

import robocorp.bots.*;
class RogerRobot implements IRobot
{
      ...
      boolean OutputStatusMessage(void)
      {
               return VoiceBox.Speak(CurrentStatus());
      }
      ...
}

Every Java class automatically implements IUnknown and IDispatch. The dispinterface implemented by the IDispatch interface, which Java provides, contains the public methods that are on the default interface for the class. For example, the following Java class implements an IDispatch interface, which supports MethodA and MethodB:

class Example
{
         public void MethodA(void)
         { ... }

         public void MethodB(int x)
         { ... }
}

At runtime, the Microsoft VM automatically provides type information for this IDispatch implementation (using IDispatch::GetTypeInfo), so clients can avoid the overhead of using IDispatch::GetIDsOfNames to do late binding. Because all Java objects are COM objects, nothing else is required.


Parameters Passed by Reference

COM interface methods can have parameters that pass simple types by reference, such as integers, floating point values, and characters. In most cases, these parameters are out parameters. For example, the COM method MySample has the following signature:

HRESULT MySample([in] long l, [out] long* Out1, [out, retval] long* retval);

Java does not support parameters that are references to the intrinsic data types, and it does not support pointers. But you can still call MySample from Java. Reference types are mapped to one-element arrays by the Microsoft VM. Therefore, you can retrieve a reference as shown in the following example:

int A;
int B[] = new int[1];
A = MySample(42, B);
System.out.println("A = " + A + " and B = " + B[0]);

Use the jactivex tool to load and invoke COM and Automation objects directly from your Java source. Custom marshaling provides some support for types not supported by Automation.


Using Java Objects in COM

Exposing a Java object as a COM component requires that the Java object be contained inside a COM-Callable Wrapper (CCW). The CCW is a generic COM object that has its virtual table (vtable) of function pointers dynamically constructed to support some default COM interfaces as well as any COM interfaces implemented by the Java object. This neutrally presents the Java object for all other COM components and COM-compliant languages to use.

The Microsoft VM dynamically creates a CCW for the Java object when a COM object is required. The default COM interfaces exposed for every Java/COM object by the CCW allow Java objects to be used as functional COM objects. The CCW exposed for a Java object is capable of being aggregated, but cannot aggregate other COM objects. The Microsoft VM takes care of storing the pointer to the outer COM object's IUnknown interface in the CCW.

The CCW provides the following default COM interfaces for Java objects:

  • IUnknown

  • IDispatch

  • IDispatchEx

  • IProvideClassInfo

  • IProvideClassInfo2

  • ISupportErrorInfo

  • IMarshal

  • IConnectionPointContainer

  • IExternalConnection

Override most of these interfaces by implementing them. The Java object's COM interface method implementations are added to the vtable instead of the CCW's COM interface method implementations. Although IUnknown, IExternalConnection, and ISupportErrorInfo cannot be overridden, the Microsoft VM automatically deals with these interfaces. Therefore, you don't have to track reference counts, query for interfaces, or propagate exceptions for Automation objects.

The CCW implements the appropriate COM interfaces under the following circumstances:

  • When a Java object implements java.io.Serializable, java.io.Externalizable or com.ms.wfc.core.IComponent, the CCW implements the IPersist, IPersistStreamInit, and IPersistStorage interfaces.

  • When a Java class has been registered as a COM object and specified as a control, thus implying the object is an ActiveX Control, the CCW implements IOleControl, IOleInPlaceActiveObject, IOleInPlaceObject, IOleObject, IOleWindow, IPerPropertyBrowsing, IViewObject, and IViewObject2 interfaces.

  • When any class registered as a control extends an AWT component that contains java.awt.Component superclasses, com.ms.ui.IUIComponent, and com.ms.object.ISiteable, the CCW implements the IObjectSafety interface.

  • When any class registered as a control contains com.ms.wfc.core.IComponent, the CCW implements the IDataObject interface.

For details on the specific COM interfaces that are implemented, see the Integrating Java and COM white paper.


Using Jactivex with COM

The jactivex utility is mainly used for hosting Automation-enabled Microsoft® ActiveX® Controls in Java. However, you can also use jactivex to generate .java files for the classes and interfaces described in a type library. These .java files, once compiled into .class files, allow Java programs to use Component Object Model (COM) services.

Note Jactivex replaces javatlb and jcom.

To use a COM class from Java, you must first import it; this means creating a Java class that represents the COM class in the context of Java. The jactivex tool uses the COM type library information to create Java classes that represent COM interfaces.

A type library is a mechanism defined by COM to define type information. Each type library contains complete type information about one or more COM entities, including classes, interfaces, and dispinterfaces. For more information about type libraries, see the MSDN™ Library. To find out how to use the interfaces available from a particular programmable control or Automation server, see the documentation provided by that vendor.

Note The jactivex tool is virtually identical to the jcom tool and similar to the javatlb tool. Jactivex generates Java source code (.java) rather than the .class files that javatlb generates. The generated Java source requires new functionality not present in older versions of the compiler in Microsoft® Visual J++®. For more information, see Configuring Jactivex.

To use the jactivex tool for low-level Java/COM integration (that is, enabling the javatlb behavior), use the /javatlb switch and provide the name of a type library as follows:

jactivex /javatlb <file name>

Where <file name> is the file name of the type library (*.tlb, *.olb, *.ocx, *.dll or *.exe) to import.

Note If you specify an .ocx file without the /javatlb switch, the jactivex tool will generate a JavaBean wrapper for the ActiveX control (its default operation).

This command generates .java files for the classes and interfaces described by a type library. These .java files, once compiled into .class files, allow Java programs to use COM services.

For example, the following command line creates a \Widgets subdirectory underneath the trusted library directory (specified by the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\TrustedLibsDirectory):

jactivex /javatlb widgets.tlb

If the trusted library directory is \%Windir%\Java\Trustlib, the preceding command creates the directory \%Windir%\Java\Trustlib\Widgets, and fills it with .java files. A separate .java file is created for each class, structure, enumeration, and interface described by the widgets.tlb type library. The names of packages and directories created by jactivex contain only lowercase letters.

If the type library contains an importlib statement, jactivex creates a separate Java package in a separate directory for the imported type library.

Configuring Jactivex addresses backward-compatibility issues with javatlb.

Generating COM Interfaces from Type Libraries discusses the use of Jactivex with the /javatlb /c2j command-line option.

Example of Using COM objects in Java Code shows how to use COM objects in Java code.


Configuring Jactivex

Jactivex is designed for backward compatibility with the javatlb tool. In most cases, upgrading to jactivex should require only the following three modifications to your makefiles or build scripts.

  1. Replace references to javatlb with references to jactivex.

  2. Add the appropriate command-line switch (/javatlb) in any scripts to access jactivex features.

  3. Upgrade to a compiler for Java that recognizes the new @com directives generated by jactivex. If you are using the Visual J++ compiler, use version 1.02.3920 or later to compile the output from jactivex. Earlier versions of jvc will not issue a compile-time error, but the class files they generate will not work. For the version number of jvc included in the \Relnotes directory of this SDK, see build.txt. For more information about the @com directives, see the Java/COM Attributes Reference.

Note By default, jvc disables the @com and @dll directives. To enable these, use the jvc /x- option.

Correspondence between Jactivex and Javatlb Command-Line Options

Javatlb | Jactivex | Notes
/d dir | /javatlb /d dir | Work identically.
/p package | /javatlb /p package | Work identically.
/p:b- | /javatlb /p:b- | Work identically.
/X:m- | /javatlb /X:m- | Work identically.
/U | N/A | Not supported in jactivex.*
/U:T | N/A | Not supported in jactivex.*

*Jactivex does not support the generation of summary.txt files as did javatlb because jactivex generates human-readable .java source.


Generating COM Interfaces from Type Libraries

Jactivex with the /javatlb command-line option generates COM interfaces from type libraries. This requires more work, but it ensures that the exposed interface exactly matches the typelib description.

This approach requires an interface definition language (.idl) file describing your interface and a coclass, which uses the [default] attribute to define the default interface. The following example shows a simple .idl file for the IWidget interface:

[
      object,
      uuid(...),
      helpstring("IWidget"),
      pointer_default(unique)
           ]
           interface IWidget : IUnknown
           {
       HRESULT add([in] long x, [in] long y, [out,retval] long*pz);
           };

   [
      uuid(...),
      helpstring("CWidget")
   ]
   coclass CWidget
   {
      [default] interface IWidget;
   };

When you invoke jactivex on the type library using /javatlb, jactivex generates an extra file named CWidgetImpl.java:

public class CWidgetImpl implements IWidgetDefault,com.ms.com.NoAutoScripting
   {
       public int add(int x, int y)
                {
          throw new com.ms.com.ComFailException(0x80004001);  //E_NOTIMPL
                }
   }

To create a Java implementation of CWidget, you can either extend the class or use CWidgetImpl as a template for MyWidget (this is preferable as it eliminates a superclass). The following code shows the superclass implementation:

public class MyWidget extends CWidgetImpl
   {
       public int add(int x, int y)
        {
           return x+y;
       }
    }


Example of Using COM Objects in Java Code

The following example shows how to use COM objects in Java code. Suppose comserver.dll, which defines a CComBeeper class and an IComBeeper interface, is registered as having type library information. Running jactivex /javatlb on Comserver.dll creates a package named comserver, containing the Java class CComBeeper and the Java interface IComBeeper.

When you've run jactivex on comserver.dll, you can use the import statement in your Java source code to easily refer to classes in the comserver package. For example:

import comserver.*;   // import comserver package

This statement is identical to Java's syntax for importing an entire package. It is not strictly necessary, however. In Java, any class can be referenced using its fully qualified name (for example, java.awt.Canvas), as long as that class name is found when searching the class path. The import statement allows you to refer to the class using its short name (for example, Canvas).

The same is true for importing COM classes. The import statement is not required to use the COM class. It simply allows the class to be referenced using its short name. Any COM class can always be referenced using its fully qualified name.

Instead of importing the entire package, you could explicitly import individual classes within a type library. To import individual classes, use the following syntax, which is identical to Java's syntax for importing a single class.

import comserver.IComBeeper;
import comserver.CComBeeper;

The Java classes that wrap COM classes can be used the same way you use other Java classes. For example, the following code declares a reference of type IComBeeper, initializes it by creating an instance of the COM class CComBeeper, gets and sets the value of a property of the object, and then calls two methods on the object.

IComBeeper testBeep = (IComBeeper)new CComBeeper();
int myTone = testBeep.getSound();
testBeep.putSound(64);
testBeep.Beep();

Because CComBeeper is a COM class, you must use one of its interfaces to manipulate an instance of the class. COM does not support accessing properties or methods on a class independently from its interfaces. For example, the following statements would be legal Java code, but will cause errors when used with a COM class.

CComBeeper testBeep = new CComBeeper(); // Don't do this with a COM class.
int myTone = testBeep.getSound();       // Causes runtime errors with COM classes.

Caution An important restriction on using Java classes that wrap COM classes: an instance of the class cannot be directly used. Use the instance through an interface. However, if you generate the .java files by using the jactivex tool with its /javatlb /xi option, you can call methods on the object directly without first casting to an interface pointer. For more information on using the jactivex tool, see Jactivex.


Type Mappings between Java and COM

The Microsoft virtual machine allows most constructs that can be specified in a type library to be accessed from Java. However, only Automation-compatible types are fully supported. Most other types will require Java/COM custom marshaling. COM constructs that cannot be described in a type library are inaccessible from Java.

IID_IS and SIZE_IS Support
Element Types Defined in Type Libraries
Interface Methods
Types Supported as Parameters
Sample IDL Declarations


iid_is and size_is Support

This section describes the mapping of Interface Definition Language (IDL) iid_is and size_is information to @com.parameters declarations.

The following sample code demonstrates this mapping and the use of the JTLBATTR_IID_IS and JTLBATTR_SIZE_IS macros defined in %SDKDIR%\include\javaax.h. These are custom data attribute macros for use in IDL parameter attribute lists.

JTLBATTR_IID_IS and JTLBATTR_SIZE_IS in javaax.h cause iid_is and size_is information to be propagated to type libraries generated by the Microsoft IDL compiler (MIDL). The Jactivex tool can then generate Java classes that carry the iid_is and size_is information.

In the sample code, note the use of type=CUSTOM and customMarshal= in the @com.parameters declarations.

Restrictions

JTLBATTR_SIZE_IS is the analog of IDL size_is. It can be specified only for parameters that will be Java arrays (generally, pointers).

JTLBATTR_IID_IS is the analog of IDL iid_is. It can be specified only for interface pointers and by-reference interface pointers that are also return values.

The dependent iid or size parameter must be the parameter before the size_is or iid_is parameter.

#include <javaax.h>

//IDL Code
[
uuid(AB16555B-F794-4de5-BA85-8326A40C6300),
]
interface IAttributed : IUnknown
{
HRESULT _stdcall CreateInstance(
  [in] REFIID riid,
  [out, retval, iid_is(riid), JTLBATTR_IID_IS("riid")] IUnknown **ppunk);

HRESULT _stdcall In(
  [in] REFIID riid,
  [in, iid_is(riid), JTLBATTR_IID_IS("riid")] IUnknown *punk);

HRESULT _stdcall Next(
  [in] ULONG celt,
  [out, size_is(celt), JTLBATTR_SIZE_IS("celt")] int *rgelt,
  [out] ULONG *pceltFetched);
}

//Mapping of IDL code to @com Declarations
/** @com.interface(iid=AB16555B-F794-4DE5-BA85-8326A40C6300, thread=AUTO)
*/
public interface IAttributed extends com.ms.com.IUnknown
{
  /** @com.method(vtoffset=0)
      @com.parameters([in,type=PTR] riid, [customMarshal="com.ms.com.IIDIsMarshaler",type=CUSTOM] return) */
  public com.ms.com.IUnknown CreateInstance(com.ms.com._Guid riid);

  /** @com.method(vtoffset=1)
      @com.parameters([in,type=PTR] riid, [in,customMarshal="com.ms.com.IIDIsMarshaler",type=CUSTOM] punk) */
  public void In(com.ms.com._Guid riid, com.ms.com.IUnknown punk);

  /** @com.method(vtoffset=2)
      @com.parameters([in,type=U4] celt,
[out,customMarshal="com.ms.com.SizeIsMarshaler",type=CUSTOM] rgelt,
[out,size=1,type=ARRAY] pceltFetched) */
  public void Next(int celt, int[] rgelt, int[] pceltFetched);
}

See Also

%SDKDIR%\Samples\COM\iid_is_size_is


Element Types Defined in Type Libraries

There are five basic types of elements that can be defined in Interface Description Language (IDL), and thus in a type library. These elements are mapped to Java as shown in the following table.

IDL element | Java element
Coclass | Public class.
Interface | Public interface.
Dispinterface | Public interface.
Typedef (struct, enum or union) | Public final class.
Module | Public final interface with public static final member.

The interface keyword in IDL is used to define custom (that is, vtable-based) interfaces.

The dispinterface keyword in IDL is used to define dispatch interfaces. Properties in the dispatch interface are accessible in Java through get and put methods in the Java interface.


Interface Methods

The methods generated for an interface do not include those it inherits from IUnknown or IDispatch. Methods declared with the propget or propput attributes are exposed with get or put prepended to their names.


Types Supported as Parameters

The following table lists the IDL types that are supported and the Java type that each IDL type maps to.

IDL type | Java type
boolean | boolean
char | char
double | double
int | int
int64 | long
float | float
long | int
short | short
UCHAR | byte
BSTR | java.lang.String class
LPCOLESTR | java.lang.String class
CURRENCY/CY | long (divide by 10,000 to get the original value as a fixed-point number)
DATE | double
SCODE/HRESULT | int (see the com.ms.com.ComException class)
VARIANT | com.ms.com.Variant class
IUnknown* | com.ms.com.IUnknown interface
IDispatch* | java.lang.Object class
SAFEARRAY (typename) | com.ms.com.SafeArray class
Typename* | single-element array of typename on [out], error on [in]
void | void

For information on accessing the contents of a VARIANT structure, see the Variant class.

IUnknown is the interface from which all COM interfaces are derived. The Java versions of COM interfaces are derived from com.ms.com.IUnknown. Because IUnknown is simply a placeholder for COM interfaces, you never have to call any methods on com.ms.com.IUnknown. If your Java program calls a COM method that takes a parameter of type com.ms.com.IUnknown, you can pass any COM interface. If your Java program calls a COM method that has com.ms.com.IUnknown as its return type, you can cast the return value to the COM interface you're expecting.

Certain IDL attributes cause parameters to be treated in the following ways:

  • VARIANT parameters marked with the optional attribute in IDL are exposed as ordinary parameters in Java. To omit a parameter when calling the method, call the noParam method on a Variant object and pass that as a placeholder.

  • A parameter marked with the retval attribute in IDL is treated as the return value in the corresponding Java method.

The following example passes an array object to a COM server and references its elements from the COM server. This may seem difficult because the elements don't have property names. Moreover, because it is an object reference, you cannot use subscript notation.

Assume you create an array object

var myarray = new Array(10);

and pass it to a COM server.

You can wrap each of your objects in a com.ms.com.Variant and put them into a com.ms.com.SafeArray, shown as follows:

hub.Hub_Dispatch mess = new hub.Hub();
Variant[] vars = new Variant[3];
vars[0]=new Variant(new Integer(99));
Vector datum = new Vector();
datum.addElement(new Date());
datum.addElement(new Vector());
vars[1]=new Variant(datum);
vars[2]=new Variant(new StringBuffer("Howdy"));
SafeArray safe = new SafeArray(Variant.VariantVariant,3);
safe.setVariants(0,3,vars,0);
Variant sender = new Variant(safe,false);
mess.sendObjects(sender);

where Hub has a method with the following prototype:

public void sendObjects(Object[] data);


Sample IDL Declarations

This section shows some IDL declarations and their corresponding Java declarations.

Declarations with Simple Parameters

HRESULT Func([in] int x);                        void Func(int x);
HRESULT Func([in,out] int* x);                  void Func(int[] x);
HRESULT Func([out,retval] int* x);               int Func();

Declarations with String Parameters

HRESULT Func([in] BSTR x);            void Func(java.lang.String x);
HRESULT Func([in,out] BSTR* x);      void Func(java.lang.String[] x);
HRESULT Func([out,retval] BSTR* x);   java.lang.String Func();

Declarations with VARIANT Parameters

HRESULT Func([in] VARIANT x);            void Func(com.ms.com.Variant x);
HRESULT Func([in] VARIANT* x);         void Func(com.ms.com.Variant x);
HRESULT Func([in,out] VARIANT* x);      void Func(com.ms.com.Variant x);
HRESULT Func([out,retval] VARIANT* x);   com.ms.com.Variant Func();
HRESULT Func([in,out] VARIANT** x);      void Func(com.ms.com.Variant[] x);

Declarations with Interface Pointer Parameters

HRESULT Func([in] IBar* x);         void Func(IBar x);
HRESULT Func([in,out] IBar** x);      void Func(IBar[] x);
HRESULT Func([out,retval] IBar** x);IBar Func();

For more information on HRESULTs returned by COM functions, see Handling COM Errors in Java.


Handling COM Errors in Java

This section discusses HRESULTs in connection with ComFailException objects and try-catch blocks. An error handling example is included.

HRESULTs

HRESULTs are 32-bit error codes returned by every COM interface method to indicate success or failure of a method call. Usually, only the success code (S_OK) is defined, but many other failure codes can be defined. For a list of the values of common system-defined HRESULTs, see the ComFailException class. For domain-specific errors, see the documentation for the component you are using.

The documentation for many components describe errors in terms of Visual Basic Err.Number values rather than HRESULTs. However, some components use a convention in which the returned HRESULT corresponds with the Err.Number value. For example, if you are using Data Access Objects (DAO) or Remote Data Objects (RDO), you can call the getHResult method on the ComFailException object, take the lower 16 bits of the returned HRESULT, convert that value to decimal, and check it against the errors described in the DAO or RDO documentation.

The ComException class wraps the HRESULT error code and is used to communicate error information from COM back to Java whenever a COM method fails. The ComException class defines a getHResult method that returns the error code as a Java integer. You can also use java.lang.Throwable.getMessage( ) to retrieve the error message associated with the exception or error.

Try-Catch Blocks

The Microsoft VM throws an exception when a call to a COM interface method returns an HRESULT containing an error code. Try-catch blocks handle these errors or exceptions. Because the ComException class is derived from java.lang.RuntimeException, the compiler does not strictly require a throws clause in the method declaration, nor does it require try-catch blocks. Because runtime exceptions are unchecked by the compiler, you can use try-catch blocks when you need them.

Because ComException is an abstract class, a ComException object cannot be constructed directly. However, a ComFailException object or a ComSuccessException object can be constructed. Typically, catch ComFailException objects so it's obvious that something has gone wrong during a call to a COM method. The following example demonstrates the use of a try-catch block.

try
{
   // Call COM method.
}
catch (com.ms.com.ComFailException e)
{
   System.out.println( "COM Exception:" );
   System.out.println( e.getHResult() );
   System.out.println( e.getMessage() );
}

An Error Handling Example

The following Java code is similar to the code in Implementing COM Interfaces; however, error handling has been added.

import robocorp.bots.*;
...
try
{
         Robot robbie = new Robot();
         robbie.GoForward(10);
         robbie.Turn(-90);
}
catch(Throwable e)
{
         System.out.println("Something bad happened!");
}


Apartment Model and Threading Issues

Most existing COM objects are not thread-safe. That is, clients are required to make all calls to the COM object from a single thread. This thread is also regularly required to process Microsoft® Windows® messages. This allows other threads to marshal calls to objects on that thread. It also ensures that system message broadcasts do not get blocked. (A thread that regularly processes Windows messages is said to have a message "pump.")

Furthermore, some COM objects are not even apartment-aware. These objects are not only restricted to a single thread, but are restricted to a specific thread known as the main apartment thread. The first thread that calls CoInitialize becomes the main apartment thread for the process.

The following sections describe how the Microsoft VM instantiates COM objects and creates marshaling proxies while hiding the details from the Java programmer.

Instantiating New COM Objects compares how new objects are instantiated, depending on their threading model.


Instantiating New COM Objects

When a Java class representing a COM object is instantiated using new, the Microsoft VM obtains the COM object's threading model from the registry. What happens next depends on which threading model is in effect.

For the Both or Free threading models, the object is assumed to be thread-safe and is instantiated on the calling thread. Any method call on this object will translate directly to a method call on the underlying COM object on the calling thread.

For the single threading model, the Microsoft VM automatically marshals to the process's main apartment thread to create the object. Furthermore, it marshals all method calls on this object back to the main apartment thread. This represents the @com directive's additional overhead, but this is required for non–thread-safe objects.

For the apartment threading model, the Microsoft VM similarly marshals the object creation and method calls. If the creating thread is considered apartment-hostable, the object is created on that thread. Otherwise, the Microsoft VM automatically creates an apartment thread, and the object is created on that thread. All objects created this way share one special apartment thread. The Microsoft VM does not create a new thread for every object.


Standard Java/COM Marshaling

Whenever a program spans languages, the difference between the languages' data types must be handled by marshaling. The Microsoft VM uses marshaling to wrap COM libraries as Java classes.

A COM library uses various data types as parameters and return values for its methods. For these methods to be callable from Java, the data types must be converted from COM types to Java types. For some primitive types, the Microsoft VM provides automatic marshaling and type conversion.

The Microsoft virtual machine automatically converts a Java object to a COM component complete with interfaces like IUnknown, IDispatch, IMarshal, and others used for implementing Microsoft® ActiveX® Controls and COM components. The Microsoft VM automatically handles object references, cleanup, and interface queries for any COM object used in Java, whether the component was written in Java or another COM-compliant language.

The following table lists the default COM interfaces provided by the CCW for Java objects.

Interface | Description
IUnknown | The Microsoft VM handles the QueryInterface and reference counts for all COM objects (Java implemented or not); there is no need to expose any IUnknown functions to Java developers.
IDispatch | Provides Automation support. IDispatch assumes that the underlying object is static.
IDispatchEx | Extends IDispatch; provides Automation support for dynamic languages such as scripting languages. IDispatchEx was developed to support dynamic objects.
IProvideClassInfo | Provides a single method for accessing the type information for an object's coclass entry in its type library.
IProvideClassInfo2 | Extends IProvideClassInfo with GetGUID, which returns the object's outgoing IID for its default event set.
ISupportErrorInfo | Ensures that error information can be correctly propagated up the call chain. Automation objects that use the error handling interfaces must implement this interface.
IMarshal | Specifies how a COM object can be marshaled between processes and remote computers.
IConnectionPointContainer | Supports connection points for connection objects. Used to locate a specific connection point.
IExternalConnection | Manages a served object's count of marshaled (external) connections. The COM object that implements such a count can detect when it has no external connections and correctly shuts itself down. This interface is used by the Microsoft VM for handling the reference counts of COM objects.

In addition to conversion, the COM types must be represented as Java types to be callable from Java. This requires a Java .class file with type declarations in Java format. This class file is usually created by running a type-conversion tool such as jactivex on the type library of the COM server. These conversion tools generate the correct type mappings for all types that are supported by the intrinsic marshaling of the Microsoft VM.

Note Jactivex replaces jcom or javatlb in older versions of the SDK.

Java proxies are not created only when a COM object is instantiated using the new keyword. They are also created whenever a Java method is passed an object from COM and whenever Java receives an object from a COM method through a return value. In both cases, no registry entry provides the threading model of the object. The Microsoft VM must be told explicitly whether the interface is thread-safe. If the interface is not thread-safe, the Microsoft VM must marshal all calls to the thread on which the interface was received. Jactivex marks all interface parameters as requiring marshaling.

Even when the interface parameter is marked as requiring marshaling, the Microsoft VM produces a non-marshaling proxy if the COM object indicates that it is thread-safe by aggregating the free-threaded marshaler (using CoCreateFreeThreadedMarshaler).

The virtual machine creates marshaling proxies only on apartment-hostable threads. If a call is made to a Java proxy that is hosted on an apartment thread, proxies for the parameters to that call are made on that apartment thread. As a result, this requirement is automatically satisfied. If the thread is not apartment-hostable, the proxy creation throws a ClassCastException.


Custom Java/COM Marshaling

Fields in Java-Callable Data Wrappers (JCDWs) and parameters in vtable interfaces of type TD_CUSTOM, TD_CUSTOMBYREF, or TD_CUSTOMBYVAL are custom marshaled. Custom marshaling means that code external to the Microsoft VM converts Java values and objects so they are understood by COM methods, and vice versa. Associated with custom marshaled fields and parameters is a hook class.

Note When passing an array of JCDW's between COM/Microsoft® Win32® APIs and Java, in either direction, if the JCDW contains complex types such as Strings, then these complex types may not be properly propagated to memory that is not garbage collected. For normal JCDW parameters, the marshaling engine always attempts to propagate structs, but this code is missing from the case of marshaling arrays.

This section includes the following topics:

Creating a Custom Class Object describes how to extend the Microsoft VM's default class object (class factory).

Creating a Custom Interface discusses COM interfaces in connection with the kind of marshaling support you choose.

Custom Marshaling Structures and Parameters describes using the @com.parameters and @com.structmap compiler directives and other issues related to custom marshaling structures and parameters.

Example of Custom Marshaling demonstrates how to marshal a simple structure type between a COM type library and Java.

Hook Class Overview introduces how the Microsoft VM uses JTYPEs and ETYPEs to call the appropriate hook method.

Hook Class Examples conclude this section.

Because jactivex cannot automatically create type mappings that work for user-defined types, Jactivex needs information on how to generate the Java type declarations. Do this by creating a Java type library information file (.jnf) file, which describes your custom data types. Passing the .jnf to Jactivex creates the COM library class header file.

The .jnf file has the following format:

[Custom]
<TypeLib Type>= <Java Type>, <Hook Class>

Where:

  • TypeLib Type is a user-defined type declared in the COM type library.

  • Java Type is the Java type to map to the COM type.

  • Hook Class is the class that does the translation.

This section explains how to implement custom marshaling of user-defined types between Java and COM. This involves writing a hook class to do the marshaling, and using jactivex /javatlb to create a Java type library information file (.jnf). This file describes the custom interface.

You write a hook class for each user-defined type you want to marshal from COM to Java. The class contains the code that actually does the marshaling and translates the COM type to a Java type and the Java type to a COM type. Much of this discussion addresses what a hook class is and how to author one.

Jactivex creates Java libraries from existing COM interfaces. COM interfaces are based on type libraries, so a Java type library is a file that maps user-defined types in existing COM type libraries to hook classes.


Creating a Custom Class Object

This section describes how to extend the Microsoft VM's default class object (class factory) exposed for Java-implemented COM objects.

For a given Java class, <JavaClass>, that implements a COM coclass, when the Microsoft VM creates a class object for the Java/COM coclass, it will attempt to load the inner class <JavaClass>.COMClassObject. The inner class must extend com.ms.com.StdCOMClassObject and must have a default constructor.

If a valid inner class is found, a new instance of the class is created and aggregated into the Microsoft VM's class object. Autodispatch and autoserialization are turned off on the COMClassObject's COM-Callable Wrapper (CCW). More importantly, the free-threaded marshaler (FTM) is turned off, because the class object should be pinned to the current context/apartment.

Although the FTM is disabled on the COMClassObject instance, there is still only one global instance of the Microsoft VM's class object and COMClassObject instance per class ID (CLSID). This means that the COMClassObject must be thread-safe.

Although only one COMClassObject instance will be created per CLSID, an implementation should not expect that only one instance of the COMClassObject will ever be created. If multiple threads invoke the Microsoft VM's DllGetClassObject, all threads may create an instance of the COMClassObject, but only one will be returned to COM. Thus, do not treat your default constructor as a class initializer. For example, don't allocate a lot of worker threads in your default constructor. Instead, wait for the first CreateInstance call.

For aggregation to work, it is necessary to know at the time the Microsoft VM's class object is created whether or not the COMClassObject class exists. Therefore, all the class loading takes place during the Microsoft VM's DllGetClassObject call.

The COMClassObject can implement IClassFactory itself in order to implement custom activation, such as singletons or the use of pooled threads. The createInstanceImpl and createControlImpl methods of com.ms.com.StdCOMClassObject facilitate such an implementation.

The Microsoft VM's default class object will still expose the IPersistJavaTypeLib interface used by vjreg and javareg to create the class's typelib. The COMClassObject cannot override this.

See Also

%SDKDIR%\Samples\COM\COMClassObject
@com.method
@com.parameters


Creating a Custom Interface

In order for COM to correctly marshal and unmarshal parameters, it must know the exact method signature, including all data types, types of structure members, and sizes of any arrays in the parameter list. Java can implement custom interfaces that contain methods for passing standard Automation data types, as well as structures, custom data types, and COM objects. You implement custom interfaces in a COM object by defining the object and all of its interfaces using IDL, and then compiling it with a MIDL compiler. The Microsoft-provided MIDL compiler is Midl.exe, available in the Platform SDK on the MSDN™ Library and with Microsoft® Visual C++®.

The MIDL compiler takes the .idl file as input and generates a type library (.tlb file) and some C code that implements a proxy and a stub for the custom object.

Java classes that represent the custom interfaces and the custom object can be generated using Jactivex. Jactivex takes any standard type library file and generates corresponding .java files for the COM objects, interfaces, and structures defined in the type library. These Java files contain the correct @com directives for specifying the .java files as Java-Callable Wrappers (JCWs). Clients can use the COM object remotely through the IDispatch interface with only the type library installed on the client and server machines. In this case, no proxy/stub is required.

A simple .tlb file can be generated for Java developed COM components using javareg. In order to customize the type library, or to generate the proxy/stub code required for using custom interfaces from the Java COM object remotely, an IDL-defined interface is required. Once a type library file has been created (either through using MIDL to compile an IDL file, or from javareg) jactivex tool can be run on the type library to generate Java COM wrapper classes that represent the interfaces and the COM object. These classes can simply be imported into a Java project and used like any other Java class.

To create a COM interface

  1. Decide how you want to provide marshaling support for your interface—either with type library-driven marshaling or with a proxy/stub DLL. Even in-process interfaces must be marshaled if they are to be used across apartment boundaries. You should build marshaling support into every COM interface, even if you don't think you will need it.

  2. Describe the interface or interfaces in an interface definition (.idl) file In addition, you can specify certain local aspects of your interface in an application configuration (ACF) file. If you are using type library-driven marshaling, add a library statement that references the interfaces for which you want to generate type information.

  3. Use the MIDL compiler to generate a type library file and header file, or C-language proxy/stub files, interface identifier file, DLL data file and header file.

  4. Depending on the marshaling method you chose, write a module definition (.def) file, compile and link all the MIDL-generated files into a single proxy DLL, and register the interface in the system registry, or register the type library.

Use ComLib.ptrRelease to release a reference on the interface, given a raw COM interface pointer.

Use ComLib.ptrToUnknown to map a raw pointer to a Java-callable wrapper.

Finally, explicitly call ComLib.release to release all outstanding reference counts on the com.IStream objects before returning from the com.IMarshal methods that have an IStream parameter.


Custom Marshaling Structures and Parameters

When specifying a structure or a parameter in a COM interface, it is sometimes necessary to indicate to the Microsoft VM exactly how the parameter or structure should be represented in native code. The @com.structmap directive is used to specify how fields in a Java structure are represented in native code. The @com.parameters directive is used to specify how parameters are represented in native code. These directives can indicate that the Java type should be marshaled by means of user-defined methods when creating the native code representation, and the Java representation from native code. To accomplish this task, the custom marshaler must implement two methods, toExternal and toJava. For example, the JCW representing the IPersistFile interface needs to specify the String parameter in the Load method as custom marshaled. The custom marshaler will be indicated in the parameter as a fully qualified Java class. This is shown in the following example:

@com.parameters([in, type=CUSTOM,
customMarshal="com.ms.com.UniStringMarshaller"] pszFileName,
[in, type=u4] dwMode)

The Microsoft VM uses com.ms.com.UniStringMarshaller to marshal the string that is passed as the pszFileName parameter. com.ms.com.UniStringMarshaller must implement the toExternal and toJava methods for performing the actual data marshaling. The Microsoft VM calls toExternal and passes the memory address that should be filled in with a native memory pointer to where the actual bytes representing the string are located. The Microsoft VM also calls toJava and passes the address in native memory where the bytes representing the string are located. The toJava method is called to construct the Java equivalent string from those bytes. The return value of toJava is assigned to the parameter that was specified to have the custom marshaler.

Some of the compiler directives have parameters that aid in custom marshaling. For instance, the @com.parameters and the @dll.structmap (and @com.structmap) directives have the CUSTOM, CUSTOMBYVAL, and CUSTOMBYREF parameters.

Use CUSTOM when one struct contains a pointer to another struct:

struct MyStruct {
int a;
struct PointerReferredStruct {
    float b;
} *c;
}

and when one of the parameters in a COM call is:

[in] struct* (HRESULT m([in]struct MyStruct *s);)

The parameter will be custom marshaled by the class specified by customMarshal in @com.parameters or @dll.structmap.

Use CUSTOMBYVAL when one struct is embedded inside another struct:

struct MyStruct {
int a;
struct EmbeddedStruct {
    float b;
} c;
}

and when a struct is passed by value in a COM call:

(HRESULT m([in]struct MyStruct s);)

The parameter will be custom marshaled as a by-value parameter. The custom marshaler class is specified by customMarshal in @com.parameters or @dll.structmap. The custom marshaler's copyToExternal method will be called to marshal the parameter to native code, and its copyToJava method will be called to marshal the value from native code to Java.

Use CUSTOMBYREF in COM calls where a struct is passed as:

[out] struct** (HRESULT m([out]struct MyStruct **s);).

The parameter will be custom marshaled as a by-reference value. The custom marshaler class is specified by customMarshal in @com.parameters or @dll.structmap. The custom marshaler's toExternal method will be called to marshal the parameter to native code, and its toJava method will be called to marshal the value from native code to Java.


Example of Custom Marshaling

This section shows how to marshal a simple structure type between a COM type library and Java. The following example uses a simple COM library, represented by a pseudo-IDL (Interface Description Language) file.

typedef struct POINT
  { long  x;
    long  y;
  } POINT;

interface IPlotter : IUnknown
  {
    HRESULT DrawLine([in] POINT *start, [in] POINT *end);
  }

coclass CPlotter
  {
    [default] interface IPlotter;
  }

To implement or access this library with Java

  1. Write a plotter.idl file for the COM library and pass it to the mktyplib tool (in Microsoft® Visual C++®) to generate a type library file called plotter.tlb.

  2. Write a .jnf file that describes all the user-defined types. The .jnf file would look like this for the POINT type:

    Plotter.jnf

    [Custom]
POINT = java.awt.Point, PointMarshaler

    This declaration instructs jactivex to substitute the Java type java.awt.Point when it encounters a reference to the type named POINT in the type library. It also tells the Microsoft VM to use the PointMarshaler class as the hook class for the POINT type.

           typedef struct _MyStruct
       {
         ...
       } MyStruct;
  3. Pass the names of the type library file (.tlb) and the Java type library information file (.jnf) file to jactivex using the following command:
    Jactivex /javatlb /n plotter.jnf plotter.tlb

    (For jactivex—like its predecessor javatlb—the default output directory is in your TrustLib directory. You may want to use the /d switch to specify a base directory.)

    Note By default, jvc disables the @com and @dll directives. To enable these, use the jvc /x- option.

    Jactivex creates two .java files that include special @com javadoc syntax. This syntax is required for the jvc compiler to generate the extra bits needed by the Microsoft VM to treat these files as Java/COM classes. For example, the name of the PointMarshaler class is part of these bits.

    For this example, jactivex generates two files: CPlotter.java (representing the coclass), and IPlotter.java (representing the interface). Excluding the @com javadoc syntax emitted by jactivex and used by the jvc compiler, the generated source for IPlotter.java looks like the following:

    // In the actual file, you will see extra syntax that
// represents the extra bits needed for the Microsoft VM
// Java/COM marshaling layer.

interface IPlotter
  {
     public DrawLine(java.awt.Point start, java.awt.Point end);
  }
  4. Compile CPlotter.java and IPlotter.java using jvc. You must use jvc version 1.02.3920 or later, which interprets the extra @com syntax that jactivex generates. For the version number of jvc that is included in the \Relnotes directory of this SDK, see build.txt.

  5. A Java application can now load and use an installed Plotter library by invoking the following code:
    IPlotter plotter = (IPlotter)(new CPlotter());
plotter.DrawLine(new Point(x1,y1), new Point(x2,y2));

    A Java class can also implement the Plotter library by using IPlotter as shown in the following example:

    class MyPlotterImp implements IPlotter
{
   void DrawLine(Point start, Point end)
   {
      ...
   }
}

The sample files for this section are in the Microsoft SDK for Java. The sources for the previous example are in %SDKDIR%\Samples\Com\CustomMarshal\plotter. The sources for point are in %SDKDIR%\Samples\Com\CustomMarshal\point. To execute the sample, change the current directory to %SDKDIR%\Samples\Com\CustomMarshal\prundir. Run the Go.bat file. For more information, see the COM Samples Overview. For information about other samples in this SDK, see the Samples Overview.

The Microsoft VM marshals the call from Java to Plotter by using IPlotter.class. It has special bits associated with the start and end parameters that indicate they are a user-defined class and the hook class is PointMarshaler.class. These bits are all generated by jactivex.exe.

When a Java application invokes the DrawLine method, the Microsoft VM loads the PointMarshaler class (if it hasn't already). It then looks for a public static field named cbByValSize. Its presence indicates that the COM type is fixed size. In the previous example, PointMarshaler exposes this field. It is equal to 8, the size (in bytes) of a POINT structure.

The Microsoft VM, therefore, allocates 8 bytes on the stack. The VM also invokes another public static method on PointMarshaler called copyToExternal. The Microsoft VM passes copyToExternal a pointer to this 8-byte space and a reference to the end parameter, java.awt.Point. Be aware that the pointer to the 8-byte space is passed as an integer value.

With this information, copyToExternal translates java.awt.Point to a POINT structure in that 8-byte space. The same routine is repeated for the end argument. The COM DrawLine method ultimately receives a pointer to the two stack buffers as its start and end parameters. Because both parameters were marked [in], there is no further action for this simple type.

Note The previous explanation was simplified for brevity. Much of the hook class analysis implied here is done prior to any method calls and does not actually occur at method call time.


Hook Class

 Microsoft SDK for Java

Hook Class Overview

Custom marshaling, except for the extra step of writing a hook class and listing your data types in the .jnf file, is the same as integrating any other COM library with Java.

A hook class is a Java class whose methods are used to marshal fields or parameters. The hook class must be installed and visible to the class path on any system where the user-defined types are used. Otherwise, hook classes remain mostly hidden. The Microsoft VM loads the hook class as part of loading a jactivex-created interface file that references the user-defined types, and invokes methods on the hook class to marshal them.

The wiHookClass field of the MCTypeDesc attribute information structure associated with the field or parameter designates the hook class. The value of wiHookClass is an index into the constant pool of the containing class. The constant pool entry must be of type CONSTANT_Class (directly references the hook class) or CONSTANT_Utf8 (names the hook class, loaded relative to containing class).

The Java/COM integration layer of the Microsoft VM never creates an instance of a hook class. There are around 10 fields and methods recognized as hook class members. They are all either optional or have reasonable defaults, so most hook classes need to implement only a subset of the members.

A hook class has the following responsibilities:

  • Specifying the Java type (generically referred to as JTYPE). JTYPE can be a primitive type (int, double, and so on) or a reference type (objects and arrays).

  • Specifying the size (in bytes) of the COM type (generically referred to as ETYPE). ETYPE can be variably sized. If it is, the hook class indicates this by not offering a size.

  • Providing code (methods) to translate JTYPEs to ETYPEs and back.

  • (Optional): Providing destructor code for ETYPEs to release embedded resources.

  • (Optional): Providing code to allocate and free ETYPEs.

In turn, the Microsoft VM is responsible for calling the appropriate hook methods at the right time whenever ETYPEs are passed to or from COM methods. Once the hook class is written, the VM automatically supports passing ETYPEs (if it is fixed-size), ETYPE*, and ETYPE**, as well as returning ETYPE*. The VM also implements the correct semantics for [in], [out], [in,out], and [out,retval] type library attributes, which jactivex passes along using the extra bits in the .class file. An [out] attribute or double indirection is mapped to a one-element array of JTYPE rather than to JTYPE itself.

Hook Class Implementation

Although hook classes are packaged as Java classes, they cannot be written in Java. Hook classes must receive and pass memory addresses (pointers). Java methods can receive pointers as integers, but Java cannot dereference, allocate, destroy, or otherwise manipulate pointers. Therefore, use the Raw Native Interface (RNI) to write hook classes. RNI allows Java methods to be implemented as C functions inside a DLL. RNI also offers a small set of APIs that can be called from C to create, manipulate, and destroy Java objects.

Using Template Files to Write a Hook Class

The Microsoft SDK for Java contains samples showing how to write hook classes to achieve custom marshaling. The sample files for this section are in the Microsoft SDK for Java. The sources for a working copy of this example are in %SDKDIR%\Samples\Com\CustomMarshal\Template. For more information, see the COM Samples Overview. For information about other samples in this SDK, see the Samples Overview.

The easiest way to start is by copying the files under the template subdirectory to a new directory. The key files here are:

  • TemplateMarshaler.java — a skeleton hook class.

  • TemplateMarshaler.c — contains a blank C function for each method.

  • TemplateMarshaler.def — exports the C functions in template.c.

To compile the files, follow the instructions in each of the comments marked TODO in TemplateMarshaler.java and TemplateMarshaler.c. This involves replacing ETYPE and JTYPE with your particular type, and uncommenting some optional methods.

The template contains C functions for eight hook methods. The comments inside each function describe what that hook function does. Details are provided in the examples. Note the following information about hook functions:

  • Each C function starts with an unused parameter OBJECT*x. This is an artifact of RNI and will always be NULL for a static method. This parameter can be ignored.

  • Several C functions have parameters "JTYPE javaval". Replace "JTYPE" throughout with the C type that represents your Java type. To find out what C type to use,see the table in TemplateMarshaler.c or use msjavah.

  • Several C functions have parameters "PPETYPE ppetype" (a pointer to a pointer to an ETYPE). These parameters are represented as int types in the Java method, but they are true pointers.

    Important All pointers passed to hook methods are double-indirect ETYPE (PPETYPE). For many methods (such as releaseExternal), this will seem like an unnecessary level of indirection. The reason ETYPE is always double-indirected has to do with an obscure feature of hook classes that allows you to redefine the size and nature of A POINTER to ETYPE.

  • Except for the functions that return Java types, hook methods return VOID or return a native pointer through an output buffer. To indicate failures, hook methods should use SignalError or SignalErrorPrintf. They cause RNI to throw a Java exception when a C function exits. SignalError and SignalErrorPrintf return to their callers: You must arrange to exit from your C function immediately after calling these APIs.


Hook Class Examples

The source code and build and run instructions for all custom marshaling and hook class samples are in %SDKDIR%\Samples\Com\CustomMarshal. (For more information, see the COM Samples Overview. For information about other samples in this SDK, see the Samples Overview.)

Running and Building the Sample Client

The %SDKDIR%\Samples\Com\CustomMarshal\client directory contains the sources for a sample Java client and a C++ inproc COM server that exchange all the various types implemented by the example. For more information, see the COM Samples Overview. For information about other samples in this SDK, see the Samples Overview.

To run the example, change the current directory to the run location and type GO.

To build the sample client

Use Nmake.exe to compile the makefile in the \Samples\Com\CustomMarshal directory.


Integrating JavaBeans and ActiveX

An ActiveX Control is a COM server exposing predefined, required interfaces. A JavaBean is a Java class that is compliant with a specific programming style. Another benefit of Java/COM integration is ActiveX/Beans integration, by which a JavaBean can be hosted by an ActiveX container, and an ActiveX Control can be hosted by a JavaBean container. The Microsoft virtual machine takes care of the details just as it does in Java/COM integration. This enables you to work in your most familiar environment while exploiting the available components and controls on the platform, no matter what language was used to develop the control or component.

The two main features of ActiveX/JavaBeans integration are as follows.

Hosting a Bean in an ActiveX Container
Hosting an ActiveX Control in Java

Most of the public methods and variables of a Java applet are available to any language that supports the ActiveX scripting protocol. For details, see Controlling an Applet Using Scripting.

Note Returning a long data type from a Java applet to a web page script causes an overflow error. This is due to rounding of the maximum and minimum values of the long integer. Specifically, when placed in a com.ms.com.Variant, a Java long integer becomes a VT_R8, or a Variant.VariantDouble. When the upper and lower limits for a Java long integer are returned to the script with a Variant, the resultant value's last four digits are rounded from 5808 and 5807 to 6000.


Hosting a Bean in an ActiveX Container

In JavaBeans architecture, a Bean is a reusable Java component, which is usually meant to be used in the context of other Beans or components in some container. The Microsoft VM provides the bridge necessary to host a Bean in an ActiveX container. The ActiveX container cannot differentiate the Bean from an ActiveX control; it treats it like any other ActiveX control. So, for example, Microsoft® Visual Basic® 5.0 can use the Bean exactly as it would use a control.

Hosting a Bean in an ActiveX container is essentially a two-step process:

  1. Write the Bean.

  2. Run a tool called javareg.

The following example shows a typical javareg command line registering a Bean called JChart:

javareg /register /control /class:JChart /codebase:.
/clsid:{177cf4a0-e7e0-11d0-b8e7-0000f81ecce7} /typelib:JChart.tlb

The javareg tool introspects the JavaBeans component to gather information about its properties, events, and methods, then outputs this information in the form of a type library. A type library is the file that an ActiveX container uses to find information about an ActiveX control. The tool also registers the Bean, which allows an ActiveX container to find the Bean as it would any other ActiveX control.

For more information about the javareg tool, see the javareg section of the Tools Reference. The Microsoft SDK for Java also provides samples of this technique in %SDKDIR%\Samples\Activex. For more information, see the ActiveX Samples Overview. For information about other samples in this SDK, see the Samples Overview.

After running javareg, the Bean can be hosted in any ActiveX container, appearing there as an ActiveX control. When the JavaBeans component is invoked as an ActiveX control, the Microsoft VM is loaded and makes the appropriate mapping between the methods, properties, and events of the JavaBeans and the interfaces, methods, properties, and events of the ActiveX control. Examples of some popular ActiveX containers include Visual Basic, Microsoft® Office, Borland Delphi, and Corel WordPerfect, among others.

Microsoft® Internet Explorer is itself an ActiveX container, and when a JavaBeans component is wrapped as an ActiveX control by the VM in Internet Explorer, the component exposes the same COM interfaces as any ActiveX control in the browser. To enable this mode of use, however, you must use the OBJECT tag to load your Java applet. When you use the OBJECT tag, you do not need to run javareg. See Using the HTML 4.0 OBJECT Tag for more information on using this tag.


Java Monikers

ActiveX containers, such as Visual Basic 5.0, are able to find a Bean through a Java Moniker, which uses a URL syntax similar to the one used in the HTML OBJECT tag. For example, in Visual Basic 5.0, you can use the command GetObject("java:java.util.Date") to create an instance of the Date object, and then invoke methods on it.

This is possible because DCOM introduced an extensible moniker namespace, so if you pass a string like "java:some.class" to MkParseDisplayName, OLE32 will load the Microsoft VM and let it provide the class moniker to bind to the object (it looks up "java" as a progid in the registry and gets the CLSID of a handler implemented by the VM).

Furthermore, ActiveX containers that host a Bean can find information about the Bean through a COM interface called ITypeInfo. This allows access to interfaces such as IDispatch and permits all the usual operations represented through ActiveX interfaces, such as calling QueryInterface, and so on.

To help illustrate how moniker binding works, the following is a sample C++ program that uses monikers to bind to a simple Java object called TestObject. (Its source code is shown after this example.)

TEST.CPP

#include <windows.h>
#include <olectl.h>
#include <stdio.h>

HRESULT BindToObject(LPOLESTR pwszDisplayName, REFIID riid, LPVOID *ppunk)
{
    HRESULT hr;
    IBindCtx *pbc;
    ULONG chEaten;
    IMoniker *pmk;

    *ppunk = NULL;
    hr = CreateBindCtx(0, &pbc);
    if (hr == S_OK) {
        hr = MkParseDisplayName(pbc, pwszDisplayName, &chEaten, &pmk);
        if (hr == S_OK) {
            hr = pmk->BindToObject(pbc, NULL, riid, ppunk);
            pmk->Release();
        }
        pbc->Release();
    }
    return hr;
}
void main(int argc, char *argv[])
{
    HRESULT hr;
    IUnknown *punk;
    hr = CoInitialize(NULL);
    if (hr == S_OK) {
        hr = BindToObject(L"java:TestObject", IID_IUnknown, (LPVOID *) &punk);
        if (hr == S_OK) {
            punk->Release();
        } else {
            printf("failed to bind to java object (hr=%08x)\n", hr);
        }
        CoUninitialize();
    }
}

TestObject.java

import java.io.*;
import java.net.*;
import com.ms.com.*;
public class TestObject
{
    public TestObject() {
        System.out.println("created java object!");
    }
}


Using the HTML 4.0 OBJECT Tag

If you want to treat the Bean as an ActiveX control in Microsoft® Internet Explorer 4.0 (for example, to gain access to COM interfaces on that object), skip the javareg process and just use the HTML 4.0 OBJECT tag. Internet Explorer 4.0 queries the object directly for its Typeinfo data rather than having to rely on the Typelib information generated by javareg.

The HTML 4.0 OBJECT tag specification is supported by the Microsoft VM in Internet Explorer 4.0 so that you can use the OBJECT tag instead of the APPLET tag to run Java applets from a local or remote codebase. For example, the following code fragment could be used to load the Java class myprogram.one from http://www.one.come/two/three/.

<OBJECT classid="java:myprogram.one">
        codebase="http://www.one.come/two/three/">
</OBJECT>

Note The Microsoft VM only provides access to COM interfaces for Java classes loaded using the OBJECT tag. The APPLET tag is handled in a different manner internally. For more information on HTML 4.0 and the OBJECT tag, go to the World Wide Web Consortium's Web site This link takes you to a site outside of microsoft.com and see the HTML Specification.


Exposing JavaBeans Methods through IDispatch

By default, the Microsoft VM uses JavaBeans introspection to enumerate the methods and properties that are exposed through IDispatch. Unless a Bean provides its own BeanInfo, all public methods are exposed, as well as properties discovered using standard design patterns (such as setText and getText).

Mapping JavaBeans Events to ActiveX

In addition to exposing event interfaces, ActiveX controls have the concept of a default, outgoing set of events. A control developer defines this default event set, which is often the only event source connected to by ActiveX containers. To provide the greatest flexibility to Java developers, the ActiveX control framework allows use of design patterns to define this default event interface.

Since the JavaBeans eventing model is sufficient for many eventing needs and maps well to the ActiveX IConnectionPointContainer model, Microsoft recommends that events be exposed using the JavaBeans eventing specification.

When an ActiveX component attempts to connect to the default event interface of an ActiveX control for Java, the Microsoft VM introspects that control and looks for event listener interfaces. Unless a Bean provides its own BeanInfo, all outgoing events are in the default event set. For example, a developer could define the following interfaces in Java to define its outgoing default event set.

interface mouseListener
{
        public void mouseEvent( int ButtonState, int x, int y );
}

interface buttonListener
{
        public void clickEvent( Object ButtonSource );
}

interface keyListener
{
        public void keyEvent( int shiftState, int key );
}

These interfaces define events that could be sourced from three different JavaBeans event connections in a Java control. The Microsoft VM will combine them into one interface that is exposed through ActiveX. Be aware that the methods in the interface freely define parameters that are not event objects. The JavaBeans specification states that this free-form method specification is fully supported, but not necessary. It can improve performance in passing events in and out of Java.

To attach an event sink to the Java control, the Microsoft VM calls the addListener methods of the outgoing event sources and passes the instance of an object, which implements the appropriate interface.

Mapping JavaBeans Properties to ActiveX

Properties allow control developers to expose state variables that can be queried, set, and monitored by other controls or control containers. Again, the JavaBeans model provides a one-for-one mapping with ActiveX property concepts and change notifications. The Microsoft VM exposes ActiveX properties based on design patterns and BeanInfo information as detailed in the JavaBeans specification.

To source property change events (equivalent to ActiveX OnChanged events) a developer can simply support the JavaBeans addPropertyChangeListener and removePropertyChangeListener methods, which accept the propertyChangeListener interface as a parameter. Likewise, to source vetoable property change events (equivalent to OnRequestEdit events), a developer just supports addVetoableChangeListener and removeVetoableChangeListener methods, which accept the vetoableChangeListener interface as parameters. The Microsoft VM will automatically connect to these property change event sources and handle them appropriately. To ActiveX clients of the object, these events will map to IPropertySinkNotify and IPropertySinkNotify::OnRequestEdit.


Hosting an ActiveX Control in Java

Microsoft® ActiveX® Controls are Automation-enabled controls that support the IDispatch COM interface, which enables the control to be scripted. These controls can also be dropped into containers, such as Visual Basic.

Hosting an ActiveX control in Java is a four-step process:

  1. Develop or obtain an ActiveX control and its associated type library.

  2. Run a tool called jactivex on the ActiveX control or its type library.

    This tool will emit Java source code wrappers for the IDispatch interface implemented by the ActiveX control. The emitted Java code will include Bean-like code for adding and removing listeners for the events originating from the ActiveX control. Also, the tool produces code to appropriately manage the lifetime of the ActiveX control.

    The source code will contain compiler directive code, similar to that used by J/Direct, of the form:

    /** @com */
  3. Compile this Java source code using a compiler, such as jvc, that can interpret the @com syntax. The compiler will add some attributes to the class file.

  4. Import these classes and use the ActiveX control like any other Bean in Java code. The Microsoft VM will use these attributes in the class file to expose the ActiveX control as a Bean to any Java code. The Microsoft VM provides the necessary bridge between the invoking Java code and the corresponding IDispatch interface in the ActiveX control. Note that this only works with virtual machines that understand these attributes.

    This is best illustrated with an example. The following sample uses the Microsoft Calendar ActiveX control that ships with Microsoft Office. Running the tool jactivex on the Calendar control produces Java source classes, which are then compiled into the calendar classes imported below. A Java programmer would use the control with code similar to the following:

    import java.awt.*;
import com.ms.activex.*;
import calendar.*;  // Classes from JActiveX when run on Calendar control or typelib

public class UseCalendar extends Frame implements ActiveXControlListener
{
       Calendar c;
       public UseCalendar()
       {
        c = new Calendar();

        c.addActiveXControlListener(this);
        add(c);
       }

       // Implementation of ActiveXControlListener interface method(s)
       public void controlCreated(Object o);
       {
        if (o instanceof Calendar)
        {
                c.today();
        }
       }
}

Notice that the control is manipulated like any other Bean. The constructor code creates the Bean, registers a listener (in this case, one defined by the ActiveXControlListener interface), and then adds itself to the layout. The single method of the ActiveXControlListener interface is controlCreated. When the control is created, the Microsoft VM fires an event defined by the ActiveXControlListener interface and, if the ActiveX control supports events as this example does, the corresponding listener method on the Bean is called. The code necessary to sink the event to the corresponding listener is provided automatically by the Microsoft VM.

The result is that when the Calendar control is created, and the controlCreated method is called, which displays the month corresponding to the current date.


Controlling an Applet Using Scripting

Web developers can embed Microsoft® ActiveX® Controls into their Web pages and drive them using Microsoft® Visual Basic® Scripting Edition (VBScript). The Microsoft virtual machine (Microsoft VM) offers developers another option by making Java applets scriptable, too. When a Java applet is running in a browser, such as Microsoft® Internet Explorer, most of the public methods and variables of the applet automatically become available to VBScript or any other language supporting the ActiveX scripting protocol.

Note Returning a long data type from a Java applet to a web page script causes an overflow error. This is due to rounding of the maximum and minimum values of the long integer. Specifically, when placed in a com.ms.com.Variant, a Java long integer becomes a VT_R8, or a Variant.VariantDouble. When the upper and lower limits for a Java long integer are returned to the script with a Variant, the resultant value's last four digits are rounded from 5808 and 5807 to 6000.


A Java Applet Example Showing Scripting Control

Consider the following fragment from a Java applet:

class Buzzer extends Applet

{
public int pitch;
public void buzz()
  {

   //Play a sound at the specified pitch.
   ...

  }
 ...
}

To include this applet in your HTML page, use the <APPLET> tag, specifying the ID attribute. This enables you to refer to the applet from the scripting language, as shown in the following example:

        <APPLET CODE="Buzzer.class" ID=doorbell>

You can then define buttons that enable the user to control the applet, as shown in the following example:

        <INPUT TYPE=button VALUE="Higher" NAME="BtnHigher">

        <INPUT TYPE=button VALUE="Lower"  NAME="BtnLower">

        <INPUT TYPE=button VALUE="Play"   NAME="BtnPlay">

The NAME attribute lets you refer to each button from the scripting language.

In the scripting portion of your HTML page, you can define OnClick handlers for each button, making them manipulate the applet, as follows:

        <SCRIPT language = "VBScript">
        Sub BtnHigher_OnClick
                document.doorbell.pitch = 880
        End Sub
        Sub BtnLower_OnClick
                document.doorbell.pitch = 440
        End Sub
        Sub BtnPlay_OnClick
                document.doorbell.buzz
        End Sub
        </SCRIPT>

Now, when a user clicks a button on the Web page, the appropriate VBScript handler is invoked, which in turn manipulates the Java applet. Note that when the applet is referenced from VBScript, its name has the identifier document attached to it.

Using scripting, Java applets can be driven just like ActiveX controls. The script can read and write most of the public variables of the applet, as well as call its public methods (including passing parameters and reading return values). However, only classes derived from java.Applet class are directly accessible from the scripting language. If your Java applet includes other classes that you want to make available to the scripting language, you must define public methods in your Applet subclass that delegate to those classes.

Note Returning a long data type from a Java applet to a web page script causes an overflow error. This is due to rounding of the maximum and minimum values of the long integer. Specifically, when placed in a com.ms.com.Variant, a Java long integer becomes a VT_R8, or a Variant.VariantDouble. When the upper and lower limits for a Java long integer are returned to the script with a Variant, the resultant value's last four digits are rounded from 5808 and 5807 to 6000.

You can also embed both Java applets and ActiveX controls in the same Web page and use VBScript handlers to connect them. For example, you can read values from an ActiveX control and pass them to a Java applet, or vice versa. You can even fire events from a Java applet. This automatic scripting capability is provided by the Microsoft VM. As a result, your script code can manipulate Java applets developed with any tool, not just ones developed with Microsoft® Visual J++®.


Firing Events from a Java Applet

Applets in Microsoft® Internet Explorer 4.0 can fire events to scripts. To do so, use the <applet> tag and specify a <param name=FireScriptEvents value=True> tag, as shown in the following example:

A look at an example taken from the AFCBean sample in the Microsoft SDK for AFC may help to demonstrate how this works.

The AFCBean class in AFCBean.java contains a handleEvent method that fires an event called itemSelected.

    /**
     *  When a item is selected, an action is performed. The LIST_SELECT
     *  event is parsed and an event called itemSelected is fired.
     */
     public boolean handleEvent(Event e)
     {
        if ((e.target instanceof UIList) && (e.id == Event.LIST_SELECT))
        {
            AFCBeanListener listener[];
            synchronized (m_listeners)
            {
                listener = new AFCBeanListener[m_listeners.size()];
                m_listeners.copyInto(listener);
            }
            for (int i=0; i<listener.length; i++)
                listener[i].itemSelected(getSelectedItem());
        }
        return super.handleEvent(e);
    }

In the AFCBean.html file, the following <applet> tag declares that the applet can fire events that will be handled by the script:

    <applet code="AFCBean.class" name="AFCBean" width="300" height="300">
        <param name="FiresScriptEvents" value="true">
    </applet>

The following JavaScript then sinks the event:

<script language="JavaScript" for="AFCBean" event="itemSelected(s)">
    txtSelectedText.value = s;
</script>

Finally, the selected string is displayed in the table on the HTML page:

    <tr>
        <td>Sinks the event itemSelected and displays the string.</td>
        <td><input name="txtSelectedText"></td>
 </tr>
</e>

When the <object> tag is supported by the Microsoft VM, it will assume the JDK 1.1 event model, so the FireScriptEvents parameter will not be required when using this tag.

For more information about VBScript, see the VBScript Web site at http://msdn.microsoft.com/scripting/ This link takes you to a site on microsoft.com.


Integrating Java and Win32 using J/Direct

Microsoft® J/Direct™ allows you to directly call an unmodified dynamic-link library (DLL) without having to write an intermediate wrapper DLL. J/Direct provides seamless and automatic type conversion of a large set of commonly used data types, eliminating most manual type conversion.

One specific use of J/Direct is to provide Java processes with access to the Microsoft® Win32® APIs. Another use of J/Direct is to call custom APIs provided in third-party DLLs. The Microsoft virtual machine (Microsoft VM) automatically translates common Java data types to those expected by C functions.

To use J/Direct, you must install the latest versions of the Microsoft compiler for Java (jvc) and the Microsoft VM. These are available with the latest version of the Microsoft SDK for Java. To display the version number, execute jvc with no arguments on the command line. If you are manually copying the compiler, be aware that the Microsoft compiler includes one executable and two .dll files: Jvc.exe, Jps.dll, and Msjvc.dll.

To find out what version of jvc.exe is installed using Microsoft® Windows® Explorer, find the Msjava.dll file, which is normally installed in your %Windir%\System[32] directory.

Note If the file doesn't appear, make sure Windows Explorer is configured to show all files. To do this, open the %Windir%\System[32] folder. On the View menu, select Options. Click the View tab, and then click Show all Files. Click Apply, and then click OK.

Right-click Msjava.dll. On the pop-up menu, select Properties, and then select the Version tab. The version number is displayed next to File Version.

Code samples that use J/Direct are in the %SDKDIR%\Samples\JDirect\ subdirectory of the Microsoft SDK for Java. For more information, see the J/Direct Samples Overview. For more information about other samples in this SDK, see the Samples Overview.

The com.ms.dll package helps you link your Java code with DLLs. Use the methods in these classes along with J/Direct technology to call functions located in Win32 DLLs, OLE API functions, and third-party DLLs.

This section contains the following topics:

Comparison of J/Direct, RNI, and Java/COM discusses the advantages and drawbacks of the major ways to integrate Java and native code.

Compiler Directives for J/Direct introduces the @dll.import, @dll.struct, and @dll.structmap compiler directives.

The J/Direct Message Box Example demonstrates a message box application that uses @dll.import.

Accessing the Win32 API briefly introduces the com.ms.win32 package, all or parts of which you can import to access Win32 DLL functions.

How Data Types are Marshaled discusses data type mapping between Java and C or C++, and related issues.

Invoking OLE API Functions discusses the ole modifier of the @dll.import directive.

Aliasing, or method renaming, shows how to use @dll.import with the entrypoint modifier, which allows you to use a name for a Java method that is different from the name that the DLL uses when it exports the function.

Linking by Ordinal shows how to use @dll.import with the entrypoint modifier so you can call DLLs that export functions by ordinal (a 16-bit integer).

Specifying @dll.import for an Entire Class shows how to use @dll.import prior to the class definition to set a library name for all native methods declared in that class.

Obtaining the Error Code Set By a DLL Function describes the setLastError modifier of @dll.import so you can reliably access a DLL function's error code.

Dynamically Loading and Invoking DLLs shows how to use @dll.import modifiers for more control over the loading and linking process.

J/Direct Security Issues describes how J/Direct works with the security system of the Microsoft VM.

J/Direct Error Messages lists the error and exception messages that may be thrown when you use J/Direct.

J/Direct Troubleshooting Tips offers solutions to typical problems arising in connection with J/Direct.

See Also

Compiler Directives Reference

Attributes Reference

com.ms.win32 package


Comparison of J/Direct, RNI, and Java/COM

To understand the uses and benefits of Microsoft® J/Direct™, compare it to the two other major ways of integrating Java and native code, Raw Native Interface and Java/COM integration.

RNI

With the Raw Native Interface (RNI), you have to remember to lock pointers, turn garbage collection on and off, and so on. Dynamic-link libraries (DLLs) you call through RNI need to be specially written to work with RNI. You can't use RNI to call arbitrary DLLs, although you can write wrapper DLLs.

In exchange for this complexity, you get fast performance and full access to all the fields in every object. But RNI is more complex than most programmers need, so it's better reserved for systems-level programming tasks such as extending the capabilities of the Microsoft VM.

Java/COM Integration

The Microsoft VM adds the ability to treat COM objects as special Java classes. Java/COM integration allows any JavaBean to be a Microsoft® ActiveX® Control and any ActiveX Control to be a JavaBean—all nearly automatically. Java/COM integration is best for calling APIs that are wrapped in COM objects or for ActiveX Controls.

A disadvantage to Java/COM integration is that there's a translation layer between Java and COM: the performance won't be as fast as if you were using C++ (and therefore had one less translation layer). This integration is very powerful, but if you just want to call into a C DLL (such as the Microsoft® Windows® API), you'd still have to write a wrapper COM object just to call your DLL.

J/Direct

With J/Direct, the Windows APIs are accessed with DLL calls, not by means of COM. Although RNI also provides access to DLLs, the RNI technology assumes that you started with a Java class, generated a C header file using Msjavah.exe, and then added functionality to the C DLL. But Win32 DLLs aren't callable by RNI in this way. Because Win32 API names don't conform to RNI naming conventions and because RNI expects data types (like strings) to be Java-format types (the Win32 API uses C-format types), RNI cannot be used to access Win32 or third-party DLLs. In other words, a single API cannot follow both the RNI conventions and the Windows conventions required by existing Windows-based applications.

The VM takes care of issues such as mapping of data types for you. J/Direct is best for calling APIs (in Windows or your own DLLs) that are not wrapped in COM objects. This allows you to access almost the entire Windows API, for instance—and enables a new class of Java programs: Microsoft® Windows® programs written in Java.

J/Direct is simpler to use than RNI, which requires you to write a specialized wrapper DLL and perform all non-trivial data type translations yourself. It is also faster than Java/COM integration. With J/Direct, the majority of pre-existing DLL functions can be invoked simply by declaring the function and calling it. J/Direct uses the @dll.import directive, which is similar in usage to the Microsoft® Visual Basic® DECLARE facility.

J/Direct links Java with existing code such as the Win32 API functions, which were not designed to deal with the Java garbage collector and the other subtleties of the virtual machine environment. However, J/Direct automatically calls GCEnable on your behalf so that you can call functions that block or perform UI without having a detrimental effect on the garbage collector. J/Direct also automatically translates common data types such as strings and structures to the forms expected by C functions.

The tradeoff is that DLL functions cannot access fields and methods of arbitrary Java objects. They can only access fields and methods of objects that are declared using the @dll.struct directive. Another limitation of J/Direct is that RNI functions cannot be invoked from DLL functions that have been called using J/Direct. The reason for this restriction is that garbage collection can run concurrently with your DLL functions. Therefore, any object handles returned by RNI functions or manipulated by DLL functions are inherently unstable.

Summary

J/Direct and RNI are complementary technologies. Using RNI requires that DLL functions adhere to a strict naming convention, and it requires that the DLL functions work harmoniously with the Java garbage collector. That is, RNI functions must be sure to call GCEnable and GCDisable around code that is time-consuming, code that could yield, code that could block on another thread, and code that blocks while waiting for user input. RNI functions must be specially designed to operate in the Java environment. In return, RNI functions benefit from fast access to Java object internals and the Java class loader.

Fortunately, you can use either RNI or J/Direct (or both). The compiler and the Microsoft VM allow you to mix and match J/Direct and RNI within the same class as your needs dictate.


Compiler Directives for J/Direct

Compiler directives are special comments in source code that aid in various aspects of J/Direct and COM development. There are three directives that specifically pertain to J/Direct:

@dll.import maps a C function from the specified DLL file to a Java method.

@dll.struct marks the class declaration as equivalent to a C structure definition.

@dll.structmap specifies information about how a field is to be exposed to native memory.


J/Direct Message Box Example

Using Microsoft® J/Direct™ to call Win32 DLLs from Java code is straightforward. A short Java application that displays a message box using the @dll.import compiler directive demonstrates this.

class ShowMsgBox {
   public static void main(String args[])
   {
     MessageBox(0, "It worked!",
         "This message box from Java", 0);
   }

   /** @dll.import("USER32") */
   private static native int
   MessageBox(int hwndOwner, String
     text, String title, int MyStyle);
}

This class has a function declaration (MessageBox) and a function definition (main). The main function is the standard entry point for Java applications (not applets). It calls the Windows API MessageBox directly and easily.

The declaration of MessageBox is just a standard Java native method declaration, preceded by a special comment called a directive that tells the compiler what DLL it'll find the MessageBox entry point in. The @dll.import directive tells the compiler that the MessageBox method will link to the Win32 USER32.DLL using the J/Direct protocol rather than the RNI protocol.

Note @dll.import and the other compiler directives are Microsoft extensions to the compiler and are disabled by default. When compiling source code that contains compiler directives, use the /x- option.

For example, to compile ShowMsgBox.java, type the following compiler command:

jvc /x- ShowMsgBox

In addition, the Microsoft VM provides automatic type marshaling from String objects to the null-terminated strings expected by C.

Note Any method in any class can call ShowMsgBox.MessageBox, as does the code in main( ) previously mentioned.

Because code that uses J/Direct can do anything, it's considered untrusted. Therefore, applications can run it, but not applets. It is possible, however, to wrap code that calls J/Direct in a Java wrapper object that you sign as safe in one or more categories.

It is not necessary to indicate whether the ANSI MessageBox (MessageBoxA) function or the Unicode MessageBox function (MessageBoxW) should be called. In the previous example, the ANSI version is always called. Calling Different Versions of DLL Functions explains how to use the auto modifier to call the optimal version of the function, depending on the version of Microsoft® Windows® that is hosting the application.

Using RNI is more powerful and generates faster code, but it is considerably more complex. This power and complexity are demonstrated by the RNI Message Box example.


Accessing the Win32 API with J/Direct

 Microsoft SDK for Java

Accessing the Win32 API

You need not declare the entire Microsoft® Win32® API yourself. The com.ms.win32 package provides classes that contain these declarations. All you have to do is import the correct class or classes. The J/Direct Message Box example could be simplified to the following:

import com.ms.win32.*;

class ShowMsgBox {
  public static void main(String
   args[])
  {
    MessageBox(0, "It worked!",
        "This message box from Java", 0);
  }
}

The available APIs are declared in a set of classes, one for each Windows DLL, as shown in the following table.

Import | DLL Name | Contains
Kernel32.class | KERNEL32.DLL | Base API
Gdi32.class | GDI32.DLL | Graphics
Ole32.class | OLE32.DLL | J/Direct methods
User32.class | USER32.DLL | User interface
Advapi32.class | ADVAPI32.DLL | Crypto API, event logging
Shell32.class | SHELL32.DLL | Interface to Microsoft® Windows® Explorer
Winmm.class | WINMM.DLL | Multimedia
Spoolss.class | SPOOLSS.DLL | Spooling

For instance, MessageBox is contained in USER32.DLL and therefore declared in User32.class; import this class (or the whole package) and you can call MessageBox directly.

Windows constants are in the com.ms.win32.wina-winz classes. To access these, import com.ms.win32.win and use win.[CONSTANT_NAME], shown as follows. Don't try to take a shortcut by extending or implementing com.ms.win32.win in your class; doing so will require that the entire class be loaded each time you load your class. Write out "win.xxx" instead.

System.out.println("MAX_PATH = " + win.MAX_PATH);

Finally, the supported Windows structures are declared in a set of class files that have the structure name as the class name, such as com.ms.win32.RECT.class. Just import these and you can use the Windows structures as though they were Java classes.

The com.ms.win32 classes are an optional part of the Microsoft SDK for Java. if you don't have them, just reinstall the VM. (The Java sources are in the \Src\Win32API subdirectory of the Microsoft SDK for Java.)

Because the classes contain only declarations, your users won't need to have them installed on their computers, but you'll need them to compile.

For importing the ANSI or Unicode DLL version, or the optimal version depending on the platform, see Calling Different Versions of DLL Functions.

Many Windows functions (in particular, the USER32 functions) require the application instance handle as a parameter. In Win32, an instance handle is defined the same as a module handle. Thus, the instance handle can be obtained by passing NULL to the GetModuleHandle function.

  /** @dll.import("KERNEL32") */
  private static native int GetModuleHandle(String modName);

  int hInst = GetModuleHandle(null);

Windows applications written in C have a WinMain function where execution begins. Java applications written in C have a main function instead.

The Microsoft® Windows® operating system passes four parameters to WinMain. The following table shows how to obtain these values from Java.

The application instance handle | Pass NULL to the GetModuleHandle function.
The previous instance handle | In Win32, this value is always NULL.
The command line | Passed as the String args[] parameter to main.
The default value to pass to ShowWindow | Can be obtained by GetStartupInfo. However, it is recommended that Microsoft® Win32® applications pass SW_SHOWDEFAULT to ShowWindow rather than using the value passed to WinMain.

Use the jexegen tool to create an .exe file that can be launched like a Windows application. When using jexegen, you can select whether to build a GUI executable or a console executable. The default is console, but you can select GUI by specifying the /W option. For example, consider the following Java application:

public class app
{
  public static void main(String args[])
  {
    int hInst = GetModuleHandle(null);
    MessageBox(0,"Instance handle is " +
               Integer.toHexString(hInst),"",0);
  }

  /** @dll.import("KERNEL32") */
  private static native int GetModuleHandle(String modName);

  /** @dll.import("USER32") */
  private static native int MessageBox(int hWndOwner,String text,
                                       String title,int MyStyle);
}

This class can be converted to a GUI executable by executing the following command lines:

  jvc app
  jexegen /W /out:app.exe /main:app *.class

For more details on jexegen, see the jexegen section of the Tools Reference.


Calling Different Versions of DLL Functions

The J/Direct Message Box example didn't mention a subtle but important fact: USER32 does not export a function named MessageBox. Because the MessageBox function takes a String, it deals with Strings like all other Win32 functions do: by calling either the ANSI version or the Unicode version (named MessageBoxA and MessageBoxW, respectively). When you call MessageBox in C or C++, you actually are calling a macro that expands to either MessageBoxA or MessageBoxW, depending on whether the Unicode macro is defined.

By excluding or including modifiers to @dll.import, call the ANSI, Unicode, or optimal version of a DLL function.

The com.ms.dll package includes several classes (especially DllLib) that contain useful methods for extracting strings from native memory blocks, mapping raw pointers onto @dll.struct classes, copying bytes between various types, and other tasks.

Calling the ANSI Version of a DLL Function

By default, the Microsoft VM assumes that the ANSI version of MessageBox is the one needed. If you import the MessageBox function using @dll.import without a modifier as follows:

  /** @dll.import("USER32") */
  static native int MessageBox(int hwnd, String text,
                               String title, int style);

The Microsoft VM goes through the following steps.

  1. The strings "text" and "title" are converted to ANSI null-terminated strings.

  2. The VM attempts to find an export named MessageBox in USER32.DLL.

  3. This attempt fails. The VM then appends an "A" onto the name and looks for an export named MessageBoxA.

  4. This attempt succeeds, and the VM invokes the MessageBoxA function.

Calling the Unicode Version of a DLL Function

If you want to call the Unicode version of MessageBox, use the unicode modifier with the @dll.import directive:

  /** @dll.import("USER32",unicode) */
  static native int MessageBox(int hwnd, String text, String title,
                               int style);

Because the unicode modifier is present, the Microsoft VM will go through the following steps.

  1. The strings "text" and "title" are converted to Unicode null-terminated strings.

  2. The VM attempts to find an export named MessageBox in USER32.DLL.

  3. This attempt fails. The VM appends a "W" onto the name and looks for an export named MessageBoxW.

  4. This attempt succeeds, and the VM invokes the MessageBoxW function.

Calling the Optimal Version of a DLL Function

You might not always know in advance whether the ANSI or Unicode version is the best in a particular situation. Both have advantages and disadvantages. The default ANSI mode allows your code to run on any Win32 platform, but this causes unnecessary performance penalties on fully Unicode systems such as Microsoft® Windows NT®. The unicode modifier removes the performance penalty, but this restricts you to running on systems that implement the Unicode API.

The auto modifier lets the Microsoft VM decide which version of a DLL function is optimal based on the host operating system. The following example shows how to call the optimal version of the MessageBox function.

  /** @dll.import("USER32",auto) */
  static native int MessageBox(int hwnd, String text, String title,
                               int style);

When the auto modifier is present, the Microsoft VM determines at runtime whether the underlying platform supports the Unicode APIs. If Unicode is supported, the Microsoft VM acts as if the unicode modifier had been specified. Otherwise, the Microsoft VM behaves as if the ansi modifier had been specified. Thus, the auto modifier allows you to generate a single binary that runs well on both ANSI and Unicode Windows systems using the optimal API set available on the particular platform.

You can programmatically learn whether the auto modifier will select Unicode or ANSI on a particular platform by inspecting the system class com.ms.dll.DllLib. This class has a public integer field named systemDefaultCharSize. Its value is set to 1 (for ANSI) or 2 (for Unicode).

In general, the auto modifier should be used whenever you call Windows API functions. If you are calling your own DLLs, select either ansi (the default) or unicode depending on your needs.

The following shows how the Microsoft VM decides whether to use ANSI or Unicode when you use the auto modifier.

  1. The VM opens the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM and looks for the DWORD-named value DllImportDefaultType. This value can be one of the following:

    2 - ANSI: Always uses the ANSI version.

    3 - Unicode: Always uses the Unicode version.

    4 - Platform: Uses ANSI or Unicode depending on the platform.

  2. If the key does not exist or if it is set to 4 (indicating the platform), the VM calls the Win32 GetVersion function. The VM examines the high bit to determine whether the underlying platform is Microsoft® Windows® 95 or Microsoft® Windows NT®. If the platform is Windows 95, ANSI mode is used. Otherwise, Unicode mode is used.

It is not necessary to set the DllImportDefaultType registry key yourself. That key's main purpose is to allow the installation program to set the appropriate choice on future Windows platforms. You can programmatically query the preferred mode on your platform by reading the com.ms.dll.DllLib.systemDefaultCharSize field. This field will be set to 1 on ANSI systems, 2 on Unicode systems.

The ansi, unicode, and auto modifiers can also be used with the @dll.struct directive.


How Data Types are Marshaled

The Microsoft virtual machine (Microsoft VM) infers the native type of each parameter and the return value from the declared (compile-time) Java type of the parameter. For example, a parameter declared as a Java integer is passed as a 32-bit integer; a parameter declared as a Java String object is passed as a null-terminated string, and so forth. There are no invisible attributes that provide information about the native types.

Some Java data types don't map exactly to C/C++. Built-in data types map closely, but there are some differences depending on whether the data element is a parameter to a function or a field embedded in a structure.

Strings, structures, and pointers all require special handling. Polymorphic callbacks and parameters require special handling as well. (Polymorphic types are those that are interpreted as different types depending on the situation.)

The following sections describe in detail how the Java data types map to native data types.

Marshaling Basic Scalar Types describes the mappings for int, byte, short, long, float, and double.

Marshaling Chars explains the mapping of the char data type.

Marshaling Booleans explains the mapping of the boolean data type.

Marshaling Strings explains how to pass and receive strings.

Marshaling Arrays explains how to pass arrays of scalars.

Structures and J/Direct explains how to use the @dll.struct directive to pass and receive structures and how to use @dll.structmap to embed fixed-sized arrays within structures.

Pointers and Java explains how to handle DLLs that have multiple return values and how to read and write data through raw pointers.

Polymorphic Parameters explains how to simulate polymorphic parameters.

Callbacks explains how to declare and invoke a DLL function that takes a Callback parameter and how to embed a Callback inside a structure.

The following two tables list the native type that corresponds to each Java type. The first table describes the mappings for parameters and return values in J/Direct methods. The second table shows the mappings used for fields within @dll.struct classes.

Mappings for Parameter and Return Values

Java | Native | Notes/Restrictions
byte | BYTE or CHAR |
short | SHORT or WORD
int | INT, UINT, LONG, ULONG, or DWORD
char | TCHAR
long | __int64, DWORDLONG | A C or C++ long is 32 bits; a Java long is 64 bits.
float | float |
double | double
boolean | BOOL
String | LPCTSTR | Not allowed as return value, except in ole mode. In ole mode, String maps to LPWSTR. The Microsoft VM frees the string by using CoTaskMemFree.
StringBuffer | LPTSTR | Not allowed as return value. Set the StringBuffer capacity large enough to hold the largest string that the DLL function can generate.
byte[] | BYTE* |
short[] | WORD*
char[] | TCHAR*
int[] | DWORD*
float[] | float*
double[] | double*
long[] | __int64*
boolean[] | BOOL[]
Interface[], where Interface has an @com.interface directive. | Interface ** | Use jactivex or a similar tool to generate an interface file.
String[] | BSTR * |
Array of @dll.struct or @com.struct classes | Array of pointers to the struct
Object | pointer to struct | In ole mode, an IUnknown* is passed instead.
Interface, where Interface has an @com.interface directive. | Interface * | Use jactivex or a similar tool to generate an interface file.
com.ms.com.SafeArray | SAFEARRAY* | Not allowed as a return value.
com.ms.com._Guid | GUID,IID,CLSID |
com.ms.com.Variant | VARIANT*
@dll.struct classes | pointer to struct
@com.struct classes | pointer to struct
void | VOID | As a return value only.
com.ms.dll.Callback | function pointer | As a parameter only.

Most of the data type mappings are what you'd expect—byte to char, int to int, long to _int64, boolean to BOOL, and so on. But a few are different depending on whether the data is a parameter or a member of a structure declared with @dll.struct, as shown in the following table.

There are no unsigned data types (except char) in Java, so be careful when operating on unsigned values. Note that long is 64 bits in Java, not 32 as in C/C++.

When passed as parameters, arrays map to pointers to the element type. For instance, byte [] in Java maps to CHAR* in C/C++. There are restrictions on return values, especially Strings and StringBuffers.

Mappings Used with @dll.struct

Java | Native
byte | BYTE or CHAR.
char | TCHAR.
short | SHORT or WORD.
int | INT, UINT, LONG, ULONG or DWORD.
long | __int64.
float | float.
double | double.
boolean | BOOL.
boolean[] | Nested array of BOOL.
String | Pointer to a string, or an embedded fixed-size string.
Class marked with @dll.struct | Nested structure.
Class marked with @dll.struct and @dll.structmap that declares type=PTR | Pointer to struct.
char[] | Nested array of TCHAR.
byte[] | Nested array of BYTE.
short[] | Nested array of SHORT.
int[] | Nested array of LONG.
long[] | Nested array of __int64.
float[] | Nested array of floats.
double [] | Nested array of doubles.


Marshaling Basic Scalar Types

The basic scalar types are mapped straightforwardly.

Basic Scalar Types

Java type | DLL
int | Signed 32-bit integer.
byte | Signed 8-bit integer.
short | Signed 16-bit integer.
long | Signed 64-bit integer.
float | 32-bit float.
double | 64-bit double.
DWORD | Unsigned 32-bit integer.
LPDWORD | Maps to a Java type integer array (int[]).

Java represents unsigned integer types by using the signed types as a two's complement. For example, the integer type can be used without loss of representation for the common DWORD (unsigned 32-bit) type.


Marshaling Chars

The Java char type becomes a CHAR (an 8-bit ANSI character) unless the unicode or ole modifier is in effect, in which case it becomes a WCHAR (a 16-bit Unicode character).


Marshaling Booleans

The Java boolean type maps to the Win32 BOOL type, which is a 32-bit type. As a parameter, the Java true maps to 1, and false maps to 0 (zero). As a return value, all non-zero values map to true.

Note BOOL and VARIANT_BOOL (the internal boolean type in Microsoft® Visual Basic®) are not interchangeable. To pass a VARIANT_BOOL to a Visual Basic DLL, you must use the Java short type and use -1 for VARIANT_TRUE, and 0 for VARIANT_FALSE.


Marshaling Strings

This section explains how you can pass a String in ANSI or Unicode format to a DLL function. It also discusses two ways to return a String from a DLL function.

Passing a String to a DLL Function

To pass a standard null-terminated string to a DLL function, pass a Java String.

For example, to change the current directory, access the Kernel32 function CopyFile function as follows:

class ShowCopyFile
{
  public static void main(String args[])
  {
    CopyFile("old.txt", "new.txt", true);
  }
  /** @dll.import("KERNEL32") */
  private native static boolean CopyFile(String existingFile,
                                  String newFile, boolean f);
}

Strings are read-only in Java; the Microsoft VM will only convert the String object as an input. To allow virtual machine implementations to marshal strings without copying the characters, string object parameters should not be passed to DLL functions that can modify the string. If the DLL function might modify the string, pass a StringBuffer object.

Strings are converted to ANSI unless the unicode or ole modifier is used, in which case the String is passed in Unicode format.

Strings cannot be declared as return types of a DLL function except in ole mode, where the native return type is assumed to be a LPWSTR allocated using the CoTaskMemAlloc function.

Receiving a String From a DLL Function

There are two common ways of passing a String back from a function: either the caller allocates a buffer that is filled in by the function, or the function allocates the String and returns it to the caller. Most Win32 functions use the first method, but OLE functions use the second method. (See Invoking OLE API Functions to learn about the special support that Microsoft® J/Direct™ provides for calling OLE functions.) One function that uses the first method is the Kernel32 function GetTempPath, which has the following prototype:

  DWORD GetTempPath(DWORD sizeofbuffer, LPTSTR buffer);

This function simply returns the path of the system temporary file directory (such as C:\Tmp\). The buffer argument points to a caller-allocated buffer that receives the path, and sizeofbuffer indicates the number of characters that can be written to the buffer. (This is different from the number of bytes in the Unicode version.) In Java, Strings are read-only; you cannot pass a String object as the buffer. Instead, use Java's StringBuffer class to create a writable StringBuffer object. The following example shows invoking the GetTempPath function:

class ShowGetTempPath
{
  static final int MAX_PATH = 260;
  public static void main(String args[])
  {
    StringBuffer temppath = new StringBuffer(MAX_PATH);
    GetTempPath(temppath.capacity()+1, temppath);
    System.out.println("Temppath = " + temppath);
  }

  /** @dll.import("KERNEL32") */
  private static native int GetTempPath(int sizeofbuffer,
                                        StringBuffer buffer);
}

To understand this example, it is important to distinguish between a StringBuffer's length and its capacity. The length is the number of characters logically in the string currently stored in the StringBuffer. The capacity is the actual amount of storage currently allocated to that StringBuffer. After the following statement executes,

  StringBuffer sb = new StringBuffer(259);

the value of sb.length is 0 (zero), and the value of sb.capacity is 259. When you invoke a DLL method passing a StringBuffer, the Microsoft VM examines the capacity of the StringBuffer, adds 1 for the null terminator, multiplies by 2 if Unicode is the default character size, and then allocates that many bytes of memory for the buffer that is passed to the DLL function. In other words, you use the capacity, not the length, to set the size of the buffer. Be careful not to make the following mistake:

  StringBuffer sb = new StringBuffer();  //Wrong!
  GetTempPath(MAX_PATH, sb);

Invoking the StringBuffer constructor with no arguments creates a StringBuffer object with a capacity of 16, which is probably too small. MAX_PATH was passed to the GetTempPath method, indicating that there was enough room in the buffer to hold 260 characters. Thus, GetTempPath will probably overrun the buffer. If you were planning to use GetTempPath extensively, you should wrap it in the following manner:

public static String GetTempPath()
{
  StringBuffer temppath = new StringBuffer(MAX_PATH-1);
  int res = GetTempPath(MAX_PATH, temppath);
  if (res == 0 || res > MAX_PATH) {
    throw new RuntimeException("GetTempPath error!");
  }
  return temppath.toString(); // can't return a StringBuffer
}

This method offers both convenience and safety, and it maps the error return value of the function to a Java exception. Notice that you cannot return StringBuffer objects.


Marshaling Arrays

J/Direct automatically handles arrays of scalars. The following Java array types translate directly into native pointer types as shown in the following table.

Java Array Types

Java | Native | Number of bytes per element
byte[] | BYTE* | 1
short[] | SHORT* | 2
int[] | DWORD* | 4
float[] | FLOAT* | 4
double[] | DOUBLE* | 8
long[] | __int64* | 8
boolean[] | BOOL* | 4

The char[] array type maps to CHAR* unless the unicode modifier is in effect, in which case it maps to WCHAR*.

All scalar array parameters can be modified by the caller (like [in,out] parameters).

Array types cannot be used as return types. There is no support for arrays of objects or strings.

Typically, this facility is used by OLE functions to return values. (OLE functions reserve the function return value to return the HRESULT error code.) To learn how to obtain the return value for OLE functions, see Invoking OLE API Functions.


Structures and J/Direct

The Java language does not directly support the concept of a structure. Although Java classes containing fields can be used to emulate the concept of a structure within the Java language, ordinary Java objects cannot be used to simulate structures in native DLL calls. This is because the Java language does not guarantee the layout of the fields and because the garbage collector is free to move the object around in memory.

To pass and receive structures from DLL methods, use the @dll.struct compiler directive. When applied to a Java class definition, this directive causes all instances of the class to be allocated in a memory block that will not move during garbage collection. In addition, the layout of the fields in memory can be controlled using the pack modifier (see Structure Packing). For example, the Win32 SYSTEMTIME structure has the following definition in the C programming language:

typedef struct {
  WORD wYear;
  WORD wMonth;
  WORD wDayOfWeek;
  WORD wDay;
  WORD wHour;
  WORD wMinute;
  WORD wSecond;
  WORD wMilliseconds;
} SYSTEMTIME;

The correct declaration of this structure in Java is as follows:

/** @dll.struct() */
class SYSTEMTIME {
  public short wYear;
  public short wMonth;
  public short wDayOfWeek;
  public short wDay;
  public short wHour;
  public short wMinute;
  public short wSecond;
  public short wMilliseconds;
}

The following example uses the SYSTEMTIME structure in a DLL method call:

class ShowStruct {
    /** @dll.import("KERNEL32") */
    static native void GetSystemTime(SYSTEMTIME pst);
    public static void main(String args[])
    {
      SYSTEMTIME systemtime = new SYSTEMTIME();
      GetSystemTime(systemtime);
      System.out.println("Year is " + systemtime.wYear);
      System.out.println("Month is " + systemtime.wMonth);
      // and so on.
    }
}

Note Classes declared with @dll.struct are untrusted and therefore cannot be used by untrusted applets.

Correspondence Between Types Inside Structures

The following table describes how scalar types map inside structures.

How Scalar Types Map Inside Structures

Java

Native
byte | BYTE
char | TCHAR (CHAR or WCHAR depending on @dll.struct definition)
short | SHORT
int | LONG
long | __int64
float | float
double | double
boolean | BOOL (32-bit boolean)

Reference types (Java objects and classes) normally map to embedded structures and arrays. Each supported mapping is described in the following table.

Supported Mapping of Reference Types

Java

Native
String | Pointer to a String, or an embedded fixed-size String
Class marked with @dll.struct | Nested structure
char[] | Nested array of TCHAR (CHAR/WCHAR)
byte[] | Nested array of BYTE
short[] | Nested array of SHORT
int[] | Nested array of LONG
long[] | Nested array of __int64
float[] | Nested array of floats
double [] | Nested array of doubles

There is no direct support for pointers inside structures due to the large number of possible ways referenced objects could be allocated and disposed of. To represent a structure with an embedded pointer, declare the pointer field as type int. Make explicit DLL calls to the appropriate allocation functions and initialize the memory blocks yourself. (You could use DllLib.ptrToStruct to map the blocks onto @dll.struct classes.)

Nested Structures

A structure can embed another structure simply by naming the other structure as the field type. For example, the Windows MSG structure embeds a POINT structure as follows:

   typedef struct {
      LONG x;
      LONG y;
   } POINT;

   typedef struct {
      int hwnd;
      int message;
      int wParam;
      int lParam;
      int time;
      POINT pt;
   } MSG;

This translates directly into Java as follows:

   /** @dll.struct() */
   class POINT {
      int x;
      int y;
   }
   /** @dll.struct() */
   class MSG {
      public int hwnd;
      public int message;
      public int wParam;
      public int lParam;
      public int time;
      public POINT pt;
   }

Performance tip Although embedding structures is handy, Java does not truly support embedded objects—only embedded references to objects. The Microsoft VM must translate between these two formats each time a nested structure is passed. Therefore, in a critical code path, you can improve performance by manually nesting structures (by copying the fields of the nested structure into the containing structure). For example, the pt field in the MSG structure could easily be declared as two integer fields, pt_x and pt_y.

Fixed-Size Strings Embedded within Structures

Some structures have fixed-size Strings embedded in them. The LOGFONT structure is defined as follows.

   typedef struct {
     LONG lfHeight;
     LONG lfWidth;
     /* <Many other fields deleted for brevity.> */
     TCHAR lfFaceName[32];
   } LOGFONT;

This structure can be expressed in Java using an extension syntax to specify the size.

   /** @dll.struct() */
   class LOGFONT {
     int lfHeight;
     int lfWidth;
     /* <Many other fields deleted for brevity.> */
     /** @dll.structmap([type=TCHAR[32]]) */
     String   lfFaceName;
   }

The @dll.structmap directive indicates the size of the fixed String as measured in characters (including space for the null terminator).

Fixed-Size Scalar Arrays Embedded within Structures

Fixed-size arrays of scalars embedded in structures can be specified using the @dll.structmap directive. The following is a C language structure that contains fixed-size scalar arrays:

struct EmbeddedArrays
{
  BYTE     b[4];
  CHAR     c[4];
  SHORT    s[4];
  INT      i[4];
  __int64  l[4];
  float    f[4];
  doubl    d[4];
};

You can specify the EmbeddedArrays structure by using @dll.structmap in the following way:

/** @dll.struct() */
class EmbeddedArrays
{
    /** @dll.structmap([type=FIXEDARRAY, size=4]) */
    byte b[];

    /** @dll.structmap([type=FIXEDARRAY, size=4]) */
    char c[];

    /** @dll.structmap([type=FIXEDARRAY, size=4]) */
    short s[];

    /** @dll.structmap([type=FIXEDARRAY, size=4]) */
    int i[];

    /** @dll.structmap([type=FIXEDARRAY, size=4]) */
    long l[];

    /** @dll.structmap([type=FIXEDARRAY, size=4]) */
    float f[];

    /** @dll.structmap([type=FIXEDARRAY, size=4]) */
    double d[];

}

Structure Packing

Structure fields are padded and aligned according to ANSI 3.5.2.1. The packing size can be set using the pack modifier:

   /** @dll.struct(pack=n) */

where n can be 1, 2, 4 or 8. The default is 8. For users of the Microsoft® Visual C++® compilers, pack=n is equivalent to #pragma pack(n).

The Relationship Between @dll.struct and @com.struct

The @dll.struct directive is very similar to the @com.struct directive emitted by jactivex and implicitly emitted by javatlb. (The javatlb tool has been replaced by jactivex.) The main difference is that the default type mappings are suited for Microsoft® Windows® function calling instead of COM object calling. As a result, you can also generate @dll.struct classes by describing the structure in a type library and using jactivex to generate the Java class. However, it's usually faster to manually generate the classes.


Pointers and Java

Java does not support a pointer data type. However, if you just need a pointer to a single data object, pass a one-element array. For other uses, store pointers in Java integers and, if needed, use those integers (which really are pointers) to access the data they need by using various methods of com.ms.dll.DllLib such as ptrToStruct and ptrToString.

Return Value Pointers

Microsoft® Win32® functions that have multiple return values typically handle them by having the caller pass a pointer to a variable to be updated. For example, the GetDiskFreeSpace function has the following prototype:

   BOOL GetDiskFreeSpace(LPCTSTR szRootPathName,
                         DWORD  *lpSectorsPerCluster,
                         DWORD  *lpBytesPerCluster,
                         DWORD  *lpFreeClusters,
                         DWORD  *lpClusters);

GetDiskFreeSpace is typically called as follows:

DWORD sectorsPerCluster, bytesPerCluster, freeClusters, clusters;
GetDiskFreeSpace(rootname, &sectorsPerCluster,
                 &bytesPerCluster, &freeClusters, &clusters);

In Java, this is a special case of passing scalar arrays where the array size is one element. The following example shows how to call the GetDiskFreeSpace function:

class ShowGetDiskFreeSpace
{
  public static void main(String args[])
  {
    int sectorsPerCluster[] = {0};
    int bytesPerCluster[] = {0};
    int freeClusters[] = {0};
    int clusters[] = {0};
    GetDiskFreeSpace("c:\\", sectorsPerCluster, bytesPerCluster,
                     freeClusters, clusters);
    System.out.println("sectors/cluster  = " + sectorsPerCluster[0]);
    System.out.println("bytes/cluster = " + bytesPerCluster[0]);
    System.out.println("free clusters = " + freeClusters[0]);
    System.out.println("clusters = " + clusters[0]);
  }

  /** @dll.import("KERNEL32") */
  private native static boolean GetDiskFreeSpace(String rootname,
                   int pSectorsPerCluster[], int pBytesPerCluster[],
                   int pFreeClusters[], int pClusters[]);
}

Raw Pointers

A pointer to an unknown or particularly difficult structure can be stored in a plain Java integer. This is the simplest (and most efficient) approach if your application needs only to store the pointer and not dereference it. Consider using this technique to store a pointer returned by a DLL function that allocates a memory block. You can use this technique to store a pointer returned by any DLL function. Using raw pointers eliminates many of the safety advantages of Java. An alternative approach should be used whenever possible. However, there are situations when you might choose to use raw pointers. The following sections detail the two ways to read and write data from raw pointers.

Casting to a Reference to an @dll.struct Class

Data can be read and written through a raw pointer by casting the raw pointer to an @dll.struct class reference. Then, you can read and write the data using normal field access syntax. For example, you need to access a raw pointer as a RECT. Use the system method DllLib.ptrToStruct as follows:

  /** @dll.struct() */
  class RECT {
    int left;
    int top;
    int right;
    int bottom;
  }

  import com.ms.dll.*;

  int  rawptr = ...;
  RECT rect = (RECT)DllLib.ptrToStruct(RECT.class, rawptr);
  rect.left = 0;
  rect.top = 0;
  rect.right = 10;
  rect.bottom = 10;

The ptrToStruct method wraps the raw pointer in a RECT instance. Unlike instances created by the new operator, this RECT instance will not attempt to free the raw pointer upon reclamation by the garbage collector. This is because the RECT object has no way of knowing how the pointer was allocated. In addition, because the native memory was already constructed at the time ptrToStruct was called, the RECT class constructor is not called.

Using the DllLib Copy Methods

Another method for reading and writing data through a raw pointer is to use the overloaded copy methods in DllLib. These methods copy data between Java arrays of various types and raw pointers. If you need to treat a raw pointer as a pointer to a String (LPTSTR), use one of the DllLib methods ptrToStringAnsi, ptrToStringUni, or ptrToString to parse the String and convert it into a java.lang.String object.

  import com.ms.dll.*;

  int rawptr = ...;
  String s = DllLib.ptrToStringAnsi(rawptr);

!WARNING All Java objects are subject to movement in memory or reclamation by the garbage collector. Therefore, do not attempt to obtain a pointer to a Java array by calling a DLL function that does generic casting. The following example shows an incorrect way to obtain the pointer.

  // Do not do this!
  /** @dll.import("MYDLL") */
  private native static int Cast(int javaarray[]);

  // Inside MYDLL.DLL.
  LPVOID Cast(LPVOID ptr)
  {
    // Do not do this!
    return ptr; // Comes in as a Java array; goes out as a Java int.
  }

The value of ptr is guaranteed to be valid for only the duration of the call to the Cast function. This is because VM implementations are allowed to implement passing of arrays by copying rather than pinning and because garbage collection may cause the physical location of the array to be different after the call to the Cast function returns.


Polymorphic Parameters

Some Microsoft® Win32® functions declare a parameter whose type depends on the value of another parameter. For example, the WinHelp function is declared as follows:

  BOOL WinHelp(int hwnd, LPCTSTR szHelpFile, UINT cmd, DWORD dwData);

The dwData parameter can be any one of the following, depending on the value of the cmd parameter: a pointer to a String, a pointer to a MULTIKEYHELP structure, a pointer to a HELPWININFO, or a plain integer.

J/Direct offers two ways to declare such a parameter:

  • Declare the parameter to be type Object. This can be useful when there is more than one polymorphic parameter. You might also choose this method when you want to access a service that acts generically on a wide variety of types, such as a function that can accept any object declared with @dll.struct.

  • Use overloading to declare a separate method for each possible type. This is the usual approach because it offers superior runtime performance as well as better type checking. Overloading also avoids the need to wrap integer arguments inside an Integer object.

Declaring the Parameter as Type Object

This section shows how to declare WinHelp by declaring dwData as type Object.

  /** @dll.import("USER32") */
  static native boolean WinHelp(int hwnd, String szHelpFile,
                                int cmd, Object dwData);

When WinHelp is invoked, J/Direct will use the runtime type to determine how to translate dwData. The following table describes how the types are translated.

Translating dwData

Type

Translated as
java.lang.Integer | 4-byte integer.
java.lang.Boolean | 4-byte BOOL.
java.lang.Char | CHAR (or WCHAR if the unicode or ole modifiers are in effect).
java.lang.Short | 2-byte SHORT.
java.lang.Float | 4-byte FLOAT.
java.lang.String | LPCSTR (or LPCWSTR if the unicode or ole modifier is in effect).
java.lang.StringBuffer | LPSTR (or LPWSTR if the unicode or ole modifier is in effect).
byte[] | BYTE*.
char[] | CHAR* (or WCHAR* if the unicode or ole modifier is in effect).
short[] | SHORT*.
int[] | INT*.
long[] | __int64.
float[] | float*.
double[] | double*.
@dll.struct | pointer to structure.

Overloading the Function

Another way to declare the WinHelp function is to overload the function for each possible type as shown in the following example.

/** @dll.import("USER32") */
static native boolean WinHelp(int hwnd, String szHelpFile,
                              int cmd, int dwData);

/** @dll.import("USER32") */
static native boolean WinHelp(int hwnd, String szHelpFile,
                              int cmd, String dwData);

/** @dll.import("USER32") */
static native boolean WinHelp(int hwnd, String szHelpFile,
                              int cmd, MULTIKEYHELP dwData);

/** @dll.import("USER32") */
static native boolean WinHelp(int hwnd, String szHelpFile,
                              int cmd, HELPWININFO dwData);

A polymorphic return value cannot be handled using overloading because Java methods cannot be overloaded only on their return values. Therefore, give each variant of the function a different Java name and use the entrypoint modifier to link them all to the same DLL method. To learn more about renaming DLL methods, see Aliasing (Method Renaming).


Callbacks in Java

Write callbacks in Java by extending the system class com.ms.dll.Callback.

Declaring a Method that Takes a Callback

To represent a callback parameter in Java, declare the Java type to be either type com.ms.dll.Callback or a class that derives from Callback. For example, the Microsoft® Win32® EnumWindows function is prototyped as follows.

  BOOL EnumWindows(WNDENUMPROC wndenumproc, LPARAM lparam);

The corresponding Java prototype is shown in the following example.

  import com.ms.dll.Callback;
  /** @dll.import("USER32") */
  static native boolean EnumWindows(Callback wndenumproc,
                                    int lparam);

Invoking a Function that Takes a Callback

To invoke a function that takes a callback, you need to define a class that extends Callback. The derived class must expose one non-static method, callback (all lowercase). Continuing with the EnumWindows previous example, the C language definition of WNDENUMPROC looks like this:

  BOOL CALLBACK EnumWindowsProc(HWND hwnd, LPARAM lparam);

To author an EnumWindowsProc in Java, declare a class that extends Callback as follows.

  class EnumWindowsProc extends Callback
  {
    public boolean callback(int hwnd, int lparam)
    {
      StringBuffer text = new StringBuffer(50);
      GetWindowText(hwnd, text, text.capacity()+1);

      if (text.length() != 0) {
        System.out.println("hwnd = " + Integer.toHexString(hwnd) +
                           "h: Text = " + text);
      }
      return true;  // Return TRUE to continue enumeration.
    }

  /** @dll.import("USER32") */
  private static native int GetWindowText(int hwnd, StringBuffer text,
                                          int cch);
  }

Invoke EnumWindows with this callback as follows.

  boolean result = EnumWindows(new EnumWindowsProc(), 0);

Restrictions on Types Accepted by the Callback Method

The return type of the Callback method must be void, int, boolean, char, or short. The only parameter type currently allowed is the int type. Fortunately, this is not as restrictive as it sounds. You can use the DllLib methods ptrToStringAnsi, ptrToStringUni, and ptrToString to treat a parameter as an LPTSTR. You can use the ptrToStruct method to treat a parameter as a pointer to an @dll.struct class.

Associating Data with a Callback

Passing data from the caller of the function to the callback is frequently necessary. This explains why EnumWindows takes an extra lparam argument. Most Win32 functions that take callbacks accept one extra 32-bit parameter passed to the callback without interpretation. With the callback mechanism, it is unnecessary to pass data using the lparam argument. Because the callback method is non-static, you can store your data as fields in the EnumWindowsProc object.

The Lifetime of a Callback

Ensure that the callback is not reclaimed by garbage collection before the native function is finished with it. If the callback is short-term (callable for only the duration of one function call), no special action is required because a Callback passed to a DLL function is guaranteed to be ignored by garbage collection while the call is in progress.

If a callback is long-term (used across function calls), protect the callback from being reclaimed by storing a reference to it in a Java data structure. You can also store references to callbacks within native data structures by using the com.ms.dll.Root class to wrap the callback inside a root handle. The root handle is a 32-bit handle that prevents the callback from being reclaimed until the handle is explicitly freed. For example, a root handle to a WndProc can be stored in the application data area of an HWND structure, and then explicitly freed on the WM_NCDESTROY message.

Embedding a Callback Inside a Structure

To embed a callback inside a structure, you can first call the com.ms.dll.Root.alloc method to wrap the callback in a root handle. Then pass the root handle to the com.ms.DllLib.addrOf method to obtain the actual (native) address of the callback. Then, store this address as an integer.

For example, the WNDCLASS structure can be declared in Java as follows.

  /** @dll.struct() */
  class WNDCLASS {
    int style;
    int   lpfnWndProc; // CALLBACK
    ... /* <Other fields deleted for brevity.> */
  }

Callback has been extended as follows.

  class WNDPROC extends Callback
  {
    public int callback(int hwnd, int msg, int wparam, int lparam)
    {
   ...
    }
  }

To store a pointer to the Callback inside the WNDCLASS object, use the following sequence.

  import com.ms.dll.*;

  WNDCLASS wc = new WNDCLASS();
  int callbackroot = Root.alloc(new WNDPROC());
  wc.lpfnWndProc = DllLib.addrOf(callbackroot);


Invoking OLE API Functions

The @dll.import directive includes a special mode tailored for importing OLE API functions. To use this mode, simply include the ole modifier as in the following example.

  /** @dll.import("OLE32", ole) */
  public class OLE32 {
    ...
  }

Because of the ole modifier, the Microsoft virtual machine (Microsoft VM) automatically assumes that the native Add function returns an HRESULT. The Microsoft VM notices that the Add function returns an integer. When invoking Add, the VM automatically allocates a temporary variable of type int and inserts a pointer to it as a third parameter. After the native Add function returns, the VM automatically checks the HRESULT and if it indicates a failure (high-bit on), a Java exception of type com.ms.com.ComFailException is thrown. If the HRESULT does not indicate a failure, the VM retrieves the Add function's true return value from the temporary variable it created, and it returns that value.

Unlike Java/COM integration, a return value of S_FALSE does not cause a ComSuccessException to be thrown. If you need to distinguish between success results, you need to use normal DLL calling mode and treat the HRESULT as an integer return value.

To summarize, the ole mode alters the semantics of DLL calling as follows:

  • All Strings and characters are assumed to be Unicode.

  • The function return value of the native function is presumed to be an HRESULT. The Microsoft VM throws a ComFailException if the returned HRESULT indicates failure.

  • If the Java method return type is not void, the Microsoft VM will assume that the native function returns an additional result through a pointer, which is the final argument to the function. The VM will supply this pointer argument and dereference it after the call to obtain the additional return value. This value will be returned as the value of the Java method.


Comparing Win32 and OLE

The following topics briefly compare Microsoft® Win32® and OLE functions and code.

Using the ole attribute of the @dll.import directive, you can do the following:

  • Pass and receive strings from OLE functions.

  • Pass GUIDs, IIDs, and CLSIDs.

  • Pass VARIANTs. (This operation need not involve @dll.struct).

  • Pass COM interface pointers.

Win32 Functions and OLE Functions

In theory, the functions exported from Ole32.dll and Oleaut32.dll are no different from any other DLL function. In practice, the OLE functions follow a consistent calling style of their own. OLE functions differ from Win32 functions in the following ways:

  • OLE functions are only Unicode. There are no ANSI OLE functions.

  • Virtually all OLE functions return a 32-bit status code, HRESULT, through the normal function's return value. The high bit indicates whether the function succeeded (high bit off) or failed (high bit on). A few functions return multiple success values (typically S_OK and S_FALSE), but most return only one success value (S_OK).

  • If an OLE function returns some value other than the status code, it does so by having the caller supply a pointer to a variable that will receive the value upon exit. This return value pointer is, by convention, the last parameter.

  • The Win32 style of returning Strings is to fill in a caller-allocated buffer. OLE functions typically return Strings by allocating them using CoTaskMemAlloc and expecting the caller to free them using CoTaskMemFree.

Win32 Code and OLE Code

In the Win32 style of coding, a simple Add function looks like this:

  int sum;
  sum = Add(10, 20);

In OLE style, the Add function looks like this:

  HRESULT hr;
  int sum;
  hr = Add(10, 20, &sum);
  if (FAILED(hr)) {
    ...handle error..
  }

The OLE mode takes advantage of this consistent coding style to provide an easy way to call OLE functions from Java. Invoking an OLE-style Add function from Java looks much like invoking a more traditional Win32-style function.

  /** dll.import("OLELIKEMATHDLL", ole) */
  private native static int Add(int x, int y);
  int sum = Add(10, 20);
  // If we got here, Add succeeded.

Passing and Receiving Strings from OLE Functions

Declaring a parameter as type String on an OLE mode function passes a LPCOLESTR. The Microsoft VM also includes a preceding length prefix so the String can also be treated as a BSTR.

Declaring a return value as type String in OLE mode causes the Microsoft VM to pass a pointer to an uninitialized LPCOLESTR*. When the native function returns, the Microsoft VM will convert the returned LPCOLESTR to a Java String, and then call CoTaskMemFree to free the String.

Passing GUIDs, IIDs, and CLSIDs

The system class com.ms.com._Guid is used to represent GUIDs. Passing a _Guid object as a parameter passes a pointer to a GUID to the native function. Declaring a return type of _Guid causes the Microsoft VM to pass a pointer to an uninitialized GUID that the function fills in (in OLE mode only).

For example, OLE32 exports the functions CLSIDFromProgID and ProgIDFromCLSID to map between CLSIDs and the human-readable names used by the Microsoft® Visual Basic® function CreateObject. These functions have the following prototypes.

HRESULT CLSIDFromProgID(LPCOLESTR szProgID, LPCLSID pclsid);
HRESULT ProgIDFromCLSID(REFCLSID clsid, LPOLESTR *lpszProgId);

In Java, you would declare these methods in the following way.

  import com.ms.com._Guid;
  class OLE {
    /** @dll.import("OLE32", ole) */
    public static native _Guid CLSIDFromProgID(String szProgID);

    /** @dll.import("OLE32", ole) */
    public static native String ProgIDFromCLSID(_Guid clsid);
  }

Caution Do not confuse com.ms.com._Guid with the obsolete com.ms.com.Guid (with no underscore).

Passing VARIANTs

Declaring a parameter to be type com.ms.com.Variant passes a pointer to a VARIANT to the native function. Declaring a return value to be type com.ms.com.Variant (OLE mode only) passes a pointer to an uninitialized Variant for the native function to fill in.

Passing COM Interface Pointers

To pass a COM interface pointer, you must generate a Java/COM interface class using a tool such as Jactivex.exe. You can then pass or receive COM interfaces by declaring a parameter to be of that interface type.

For example, the system class com.ms.com.IStream is a Java/COM interface that represents the Structured Storage IStream* interface. The OLE32 function CreateStreamOnHGlobal could be declared as follows.

import com.ms.com.*;
/** @dll.import("OLE32", ole) */
public static native IStream CreateStreamOnHGlobal(int hGlobal,
                                     boolean fDeleteOnRelease);

For more information about COM interface pointers, see Integrating Java and COM.


Aliasing (Method Renaming)

Aliasing is using a name for a Java method that is different from the name used by the DLL when it exports the function. For example, you might want the Java name to start with a lowercase letter to conform to Java naming conventions. To do so, use @dll.import with the entrypoint modifier as in the following example.

  /** @dll.import("USER32", entrypoint="GetSysColor") */
  static native int getSysColor(int nIndex);

Aliasing isn't necessary to do ANSI/Unicode Win32 API suffixing. The Microsoft VM automatically takes care of this (see Calling Different Versions of DLL Functions). Aliasing is also unnecessary when accessing functions that have been exported by a .def file. Such names are typically exported using __stdcall mangling, which changes the names by prepending "_" and appending "@xxx", where xxx is the number of parameter bytes accepted by the function. For example, a method such as the following sample method would be renamed to _sample@8.

  extern "C"
  __declspec(dllexport)
  VOID sample(int x, int y){
    ...
  }

Microsoft® J/Direct™ automatically binds to __stdcall-mangled names without an explicit entry point.

The Microsoft VM automatically provides aliases for the following KERNEL32 API functions.

  CopyMemory   (becomes RtlMoveMemory)
  MoveMemory   (becomes RtlMoveMemory)
  FillMemory   (becomes RtlFillMemory)
  ZeroMemory   (becomes RtlZeroMemory)


Linking by Ordinal

Some DLLs export functions by ordinal (16-bit integer) rather than by name. To call such DLLs, use a method-level @dll.import directive to specify the ordinal. The syntax for ordinal linking is as follows.

  /** @dll.import("Libname", entrypoint="#ordinal") */

Note that ordinal is specified in decimal.

For example, to link a function exported as ordinal 82 in DLL "MyDll.DLL", you would write the following code.

  /** @dll.import("MyDll", entrypoint="#82") */
  public static native void MySample();


Specifying @dll.import for an Entire Class

The @dll.import directive can also be used prior to the class definition to set a library name for all native methods declared in that class. The following declaration uses @dll.import for an entire class.

/** @dll.import("KERNEL32") */ class EnvironmentStrings
{
  public static native int GetEnvironmentStrings();
  public static native int GetEnvironmentVariable(String name,
                            StringBuffer value, int ccbValue);
  public static native boolean SetEnvironmentVariable(String name,
                                                    String value);
}

It is equivalent to specifying @dll.import for each method, as in the following example.

class EnvironmentStrings
{
  /** @dll.import("KERNEL32") */
  public static native int GetEnvironmentStrings();

  /** @dll.import("KERNEL32") */
  public static native int GetEnvironmentVariable(String name,
                              StringBuffer value, int ccbValue);

  /** @dll.import("KERNEL32") */
  public static native boolean SetEnvironmentVariable(String name,
                                                    String value);
}

Using the @dll.import directive at the class level saves space in the .class file and eliminates redundant information. However, class-level @dll.import directives are not inherited by subclasses.


Obtaining the Error Code Set By a DLL Function

To reliably access the error code set by a DLL function, you must use the setLastError modifier to instruct the Microsoft virtual machine (Microsoft VM) to capture the error code immediately after invoking that method. For performance reasons, this is not done by default. You can then invoke the com.ms.dll.DllLib.getLastWin32Error method to retrieve the error code. Each Java thread maintains separate storage for this value.

For example, the FindNextFile function returns status information through the error code. FindNextFile would be declared as follows.

  /** @dll.import("KERNEL32",setLastError) */
  static native boolean FindNextFile(int hFindFile,
                              WIN32_FIND_DATA wfd);

A typical call would look like the following.

import com.ms.dll.DllLib;

boolean f = FindNextFile(hFindFile, wfd);
if (!f) {
  int errorcode = DllLib.getLastWin32Error();
}

Do not invoke the Win32 function GetLastError to obtain an error code set by another DLL call. Because the Microsoft VM may execute function calls of its own in the process of executing Java code, the error code may have been overwritten by the time you get to it.


Dynamically Loading and Invoking DLLs

The Microsoft® Win32® APIs provide control over loading and linking. The LoadLibrary, LoadLibraryEx, and FreeLibrary functions provide explicit control over the loading and freeing of DLLs. The GetProcAddress function allows you to link to a specific export. The GetProcAddress function returns a function pointer, so any language that can call through a function pointer can implement dynamic invocation without a problem.

These functions provide more control over the loading and linking process than the @dll.import directive. For instance, your requirements might include the following:

  • Loading a library whose name or path must be computed at runtime or generated from user input.

  • Freeing a library prior to process termination.

  • Executing a function whose name or ordinal must be computed at runtime.

Microsoft® J/Direct™ allows you to declare the requisite functions as follows. (If you are using the com.ms.win32 package, these declarations also appear in the Kernel32 class.)

/** @dll.import("KERNEL32",auto) */
public native static int LoadLibrary(String lpLibFileName);

/** @dll.import("KERNEL32",auto) */
public native static int LoadLibraryEx(String lpLibFileName,
                                       int hFile, int dwFlags);

/** @dll.import("KERNEL32",auto) */
public native static boolean FreeLibrary(int hLibModule);

/** @dll.import("KERNEL32",ansi) */
public native static int GetProcAddress(int hModule, String lpProcName);

Note GetProcAddress is declared with the ansi modifier, not auto. This is because GetProcAddress is one of the few Microsoft® Windows® functions without a Unicode equivalent. If the auto modifier was used, this function would have failed on Microsoft® Windows NT® systems.

Msjava.dll (the DLL that implements the Microsoft VM) exports a special call function so you can invoke a function obtained by GetProcAddress. The call function's first argument is a pointer to a second function. Call only invokes the second function, passing it the remaining arguments.

For example, the following shows how an application could load a DLL and call a function exported by the DLL.

  BOOL AFunction(LPCSTR argument);

  /** @dll.import("msjava") */
  static native boolean call(int funcptr,String argument);

  int hmod = LoadLibrary("...");
  int funcaddr = GetProcAddress(hmod, "AFunction");
  boolean result = call(funcaddr, "Hello");
  FreeLibrary(hmod);


J/Direct Security Issues

This section describes how Microsoft® J/Direct™ works with the security system of the Microsoft virtual machine (Microsoft VM) to prevent possible problems caused by untrusted code.

Trusted versus Untrusted Classes

J/Direct divides all loaded Java classes into trusted and untrusted. Only fully trusted classes are allowed to use J/Direct. A Java class is considered fully trusted if one of the following statements is true:

  • The class is digitally signed indicating full trust. For example, a signed applet is fully trusted.

  • The class is installed in a location specified by the target computer's CLASSPATH environment variable or installed by the Java Package Manager. A downloadable digitally signed library designed to be shared among multiple applets is an example.

  • The class is running as a non-browser application using the jview or the wjview application.

An unsigned applet on the Web, on the other hand, constitutes untrusted Java code.

Security Checkpoints for J/Direct Method Calls

The Microsoft VM applies security checks to J/Direct methods at three different times:

  • At link time.

  • Upon first invocation.

  • Upon every invocation.

An attempted J/Direct call takes place only if each of the three security checks passes or is explicitly disabled.

Security Checks at Link Time

Linking is what occurs when one Java class invokes or accesses (using the Reflection API) a member of another class. At link time, the Microsoft VM checks whether the class being referenced is accessible and whether the arguments being passed are of the correct type and number. The class is considered accessible if it is in the same package or declared public.

With the standard Java language, you are limited to a choice of two options for class accessibility: You can either declare a class public (anyone can link to it) or non-public (only classes in the same package can link to it). However, with Microsoft® Internet Explorer 4.0, there is now a third option. You can declare the class as public for only fully trusted callers. You can declare any class with this type of accessibility, even if the class does not use J/Direct. To declare the class, place the following directive at the beginning of the class as shown in the following example.

  /** @security(checkClassLinking=on) */

Note This security check only prevents untrusted callers from directly calling the protected class. It does not prevent indirect calls. A third (fully trusted) class can forward a call from an untrusted caller to the protected class. However, a safeguard exists. The intermediate class must either be installed on the target computer's class path or it must be digitally signed for maximum trust and installed using the browser.

Security Checks upon First Invocation

The first invocation of a method is the first time the method is invoked from any caller. At this time, for each method marked with the native keyword, the Microsoft VM determines whether the method is a member of a fully trusted class. If not, a SecurityException is thrown that includes the message Only Fully Trusted Classes Can Have Native Methods as Members. Because this security check does not depend on the calling context, it needs to be performed only once. If it passes, the check does not take place on future invocations. There is no way to disable this security check.

Security Checks upon Every Invocation

Security checks upon every invocation is the most stringent check available. On every call, the entire call stack is examined. If even one caller that is not fully trusted is discovered on the call stack, a SecurityException is thrown. By default, all J/Direct methods perform this check.

Raw Native Interface (RNI) methods do not perform this check upon every invocation because of backward compatibility requirements. RNI was designed to allow easy porting from the original JDK 1.0 native interface, which did not offer this security check.

Although this security check offers maximum safety, it has two important side effects as shown in the following table. Therefore, Microsoft offers a way to disable security checks upon every invocation.

Side Effects of the Security Check

Possible Performance Degradation | This security check requires a scan of the entire call stack each time a J/Direct method is called. The performance degradation is most noticeable on trusted applets, which generally run with a security manager present. Applications, however, usually do not see a significant performance drop because J/Direct omits the call stack scan for applications that run without a security manager.
Inflexibility | This security mechanism forces the use of maximum permissions, even in cases where only one specific permission is required. For example, a trusted library uses J/Direct to expose a single permission to untrusted applets in a safe way. It would be appropriate for this library to turn the call time security check off and perform its own security check for the specific permission.

The @security directive disables the per-invocation security check. The syntax for this directive is as follows.

  /** @security(checkDllCalls=off) */

The @security directive applies to the entire class. Individual methods within a class cannot be tagged. The following example shows the placement of the @security directive.

  /** @security(checkDllCalls=off) */
  class FastJDirectMethods{
    /** @dll.import(...) */
    static native void func();
  }

Note Disabling this security check transfers responsibility for security from the Microsoft VM to you. Remember that even with this security check disabled, you will still have to digitally sign the class for maximum trust. If you decide to use this directive, be sure to take the following precautions:

  • All J/Direct methods should be declared private.

  • Any publicly accessible methods should never blindly pass caller arguments to J/Direct. You must take responsibility for ensuring that only valid arguments are passed to native code.

  • Your class should expose no more capability than is required, and it should guard all access to these capabilities with the appropriate security checks.

Important Note Regarding Trusted Applets Calls from within an applet's init, start, stop, or destroy methods may trigger a SecurityExceptionEx, even if the applet is trusted. To avoid this situation, assert permissions by executing the following code:

  import com.ms.security.*;
    ...
  PolicyEngine.assertPermission(PermissionID.SYSTEM);

Security Checkpoints for J/Direct Structures

J/Direct also imposes security restrictions on classes that are marked using the @dll.struct compiler directive. Because structures only become unsafe when they are instantiated, these security checks are more efficient than the checks used for J/Direct methods. The following two security checks are performed on @dll.struct classes.

Security Checks on @dll.struct Classes

Load time | Classes marked with @dll.struct will only load if the context indicates full trust.
Link time | Code that is not fully trusted cannot link to classes declared using @dll.struct. If such an attempt is made, the Microsoft VM will throw a NoClassDefFoundError.

Security and the com.ms.win32 Classes

For maximum security, the J/Direct methods defined in the com.ms.win32 package perform the call stack check on each invocation. If you are using these classes for a Java application (running under jview or wjview), the performance overhead will be negligible. If you are using com.ms.win32 classes from a trusted class and require maximum performance, copy the required J/Direct declarations into your own classes and disable the per-invocation security check. For more information on disabling the per-invocation security check, see the Security Checks upon Every Invocation section.


J/Direct Error Messages

There are several types of exceptions that might be thrown by the Microsoft virtual machine (Microsoft VM) when you are using Microsoft® J/Direct™.

For each of the following errors, possible causes and solutions are explained:

java.lang.SecurityException [class.method]: Only fully trusted classes can have native methods as members.

java.lang.IllegalAccessError: Class has been marked as nonpublic to untrusted code.

java.lang.SecurityException: J/Direct method has not been authorized for use on behalf of an untrusted caller.

java.lang.NoClassDefFoundError.

com.ms.security.SecurityExceptionEx: [host] J/direct method has not been authorized for use on behalf of an untrusted caller.

java.lang.SecurityException

Exception class | java.lang.SecurityException
Message | class.method: Only fully trusted classes can have native methods as members.
Possible Causes | The native keyword has been used on a method that is a member of a class not loaded with full permissions (for example, an unsigned applet). This exception is only thrown if an attempt is made to invoke the native method.
Possible Solutions | Digitally sign your applet requesting full permissions. For more information on signing applets, see Signing Cabinet Files with Java Permissions

java.lang.IllegalAccessError

Exception class | java.lang.IllegalAccessError
Message | The class has been marked as nonpublic to untrusted code.
Possible Causes | An untrusted class has attempted to refer to a field or method of another class marked only for trusted use. Many of the system classes in the com.ms.com and com.ms.dll packages have been marked this way. A class can be marked as nonpublic to untrusted code using the @security directive as follows. /** @security(checkClassLinking=on) */ public class ForTrustedUseOnly{ ... }
Possible Solutions | Digitally sign your applet requesting full permissions. For more information on signing applets, see Signing Cabinet Files with Java Permissions

java.lang.SecurityException

Exception class | java.lang.SecurityException
Message | The J/Direct method has not been authorized for use on behalf of an untrusted caller.
Possible Causes | An untrusted class has invoked a trusted method that attempts to make a J/Direct call. Even if the class making the actual J/Direct call is trusted, the security manager will throw a SecurityException if any of the methods in the call stack belong to an untrusted class.
Possible Solutions Digitally sign your applet requesting full permissions. For more information on signing applets, see Signing Cabinet Files with Java Permissions.

You may also disable the security check by marking the class that attempts the J/Direct call with the @security directive as shown in the following example.

  /** @security(checkDllCalls=off) */
  public class SafeDllCalls{
   ...
  }

Note Disabling this security check transfers responsibility for security from the Microsoft virtual machine to you. Remember that even with this security check disabled, you will still have to digitally sign the class for maximum trust. If you use the @security directive, ensure that the following statements are true:

  • All J/Direct methods are declared private.

  • Your class exposes only the functionality needed by the client.

  • Your class guards all access to these capabilities with appropriate security checks.

java.lang.NoClassDefFoundError

Exception Class | java.lang.NoClassDefFoundError
Message | None.
Possible Causes | An untrusted class has attempted to load either a class marked with @dll.struct or a class generated using the jactivex tool. Although this is really a security violation (not a class loader error), a NoClassDefFoundError is thrown for backward compatibility purposes.
Possible Solutions | Digitally sign your applet requesting full permissions. For more information on signing applets, see Signing Cabinet Files with Java Permissions.

com.ms.security.SecurityExceptionEx

Exception Class | com.ms.security.SecurityExceptionEx
Message | [Host] J/Direct method has not been authorized for use on behalf of an untrusted caller.
Possible Causes | A J/Direct call was attempted from the init, start, stop, or destroy method of an applet. To make J/Direct calls during these methods, the applet must assert permissions even if the applet has been signed.
Possible Solutions Execute the following code to assert permissions.
  import com.ms.security.*;
    ...
  PolicyEngine.assertPermission(PermissionID.SYSTEM);


J/Direct Troubleshooting Tips

The following topics describe problems that you might encounter when using Microsoft® J/Direct™. For each situation, possible solutions are provided.

UnsatisfiedLinkError When Calling a Method

Getting SecurityException When Calling a DLL Method or Using an @dll.struct Class

StringBuffers Truncated on Return From DLL Function

Mysterious Syntax Errors Within @dll Directives

Compiler Cannot Find Basic System Packages Like java.lang

Compiler Cannot Find the com.ms.dll Package

Syntax Errors When Using J/Direct with Inner Classes

@dll Directives Do Not Work on Applets (or Only Works Within the Microsoft Visual J++ Environment)

Using J/Direct Makes Class Unusable

J/Direct Throws a ParameterCountMismatchError After Calling a Native Function

J/Direct Does Not Unload a DLL

UnsatisfiedLinkError When Calling a Method

  • Check the version of your compiler to see that you have a compatible compiler. (To display the version number, execute jvc with no arguments on the command line.) The Microsoft SDK for Java supplies a version of the compiler that supports J/Direct. If your compiler does not support J/Direct, the Microsoft virtual machine (Microsoft VM) will attempt to link native methods using the Raw Native Interface (RNI) and will not succeed.

  • Make sure your DLL is visible on the system path. DLLs are searched for in the following locations (do so in the order shown):
    1. The directory that the application (typically jview) loaded from.

    2. The current directory.

    3. The Microsoft® Windows® \System[32] directory.

    4. The \%Windir% directory.

    5. The directories listed in the CLASSPATH environment variable.

The Microsoft VM will not attempt to load the DLL until a method requiring it is actually called. Therefore, do not assume that the DLL load was successful simply because the Java class loaded successfully.

  • Check the method qualifiers. Methods declared with the @dll.import directive must be native and static. They can have any level of access (public, private, and so on) supported by the Java language.

  • Make sure that your method name exactly matches the DLL export name, including capitalization. The DLL linking mechanism in Win32 is case-sensitive.

  • If you still have trouble linking to a method, use a utility such as dumpbin/exports (Microsoft® Visual C++®) to verify that the DLL exports the method by the name you are using. Some DLLs may require you to link to exports by ordinal (an integer) rather than a name. In such a case, use the entrypoint override on the method using the #ordinal syntax as in the following example.
  // This method is exported as ordinal #34.
  /** @dll.import("MyDll",entrypoint="#34") */
  public static native void MySample();
  • Be aware that some so-called functions are actually C macros and the actual DLL export name may be quite different from the name of the macro.

Getting SecurityException When Calling a DLL Method or Using an @dll.struct Class

DLL calling and the use of @dll.struct classes is restricted to Java applications and signed Java applets. For more information about signing applets, see Signing Cabinet Files with Java Permissions.

StringBuffers Truncated on Return From DLL Function

Ensure that the StringBuffer's capacity is sufficient to contain the String you need before invoking the DLL function. Specify the capacity in the StringBuffer's constructor and use the StringBuffer.ensureCapacity method to guarantee a minimum capacity prior to the DLL call.

Mysterious Syntax Errors Within @dll Directives

Extra white space within @dll.import and @dll.struct directives can cause syntax errors. Avoid using white space inside @dll constructs.

Compiler Cannot Find Basic System Packages Like java.lang

The compiler shipped with the Microsoft SDK for Java looks for system packages in the Classes.zip file. This conflicts with the new Java Package Management scheme used by the Microsoft VM. This scheme stores system packages as .zip files with obfuscated names under the %Windir%\Java\Packages directory. Unfortunately, the Java Language Compiler has not yet been updated to recognize this new scheme. To compile Java programs against the new VM, you must create an old-style .zip file and ensure that it is included in the class path.

The SDK installation program normally does this for you. If, however, you installed the SDK by some other method or if your configuration has been corrupted since the installation, you may need to re-create Classes.zip. The easiest way to do this is to type the following at the command prompt.

clspack -auto

This creates a single Classes.zip in your %WINDIR%\Java\Classes directory, which contains all classes stored in the Java Package Manager. The Microsoft compiler for Java looks for classes in this location by default, so there's no need to set your CLASSPATH environment variable.

Compiler Cannot Find the com.ms.dll Package

An older version of Classes.zip is being used. Try renaming all older versions of Classes.zip on your hard disk and follow the instructions under Compiler Cannot Find Basic System Packages Like java.lang for creating a new Classes.zip file.

Syntax Errors When Using J/Direct with Inner Classes

The version of the Java compiler that ships with the SDK for Java does not correctly handle @dll directives on inner classes or classes that contain inner class declarations.

@dll Directives Do Not Work on Applets (or Only Works Within the Microsoft Visual J++ Environment)

Because the use of J/Direct can compromise security, its use is restricted to Java applications and signed Java applets. For more information about signing applets, see Signing Cabinet Files with Java Permissions.

Using J/Direct Makes Class Unusable

Any use of J/Direct within a class marks that class as unsafe and unusable by untrusted code, even if the J/Direct methods are not actually invoked.

J/Direct Throws a ParameterCountMismatchError After Calling a Native Function

The ParameterCountMismatchError exception alerts you when the called function consumed more or fewer numbers of parameters than were passed by J/Direct. This error normally indicates that the parameters in the Java method declaration do not match the number of parameters expected by the DLL function.

If the function consumed no arguments, it is assumed to be using the __cdecl calling convention. An exception is not thrown, even if the Java method declares a non-zero number of arguments.

CAUTION Do not attempt to catch and deal with the ParameterCountMismatchError exception. This exception was designed to assist developers in catching bugs during the development stage. For performance reasons, parameter count checking is performed only when the application is running under a Java debugger. It is also important to note that J/Direct performs this check after the function call has been completed. Because this exception indicates that one or more invalid parameters might have been passed to the function call, it cannot be guaranteed that the process can recover.

J/Direct Does Not Unload a DLL

J/Direct unloads a DLL when the Microsoft VM discards the Java class that imported the DLL. For a Java application running under jview, this does not occur until the process exits. For a trusted Java applet, this happens at some undetermined time after the browser has left the page containing the applet. The Microsoft VM attempts to keep Java classes loaded for several pages afterward to optimize applet refresh time in case the page is revisited.

If you need explicit control over the loading and unloading of DLLs, call the Windows loader explicitly and use the call entrypoint to invoke functions dynamically. For more information on how to do this, see Dynamically Loading and Invoking DLLs.


Integrating Java and Windows using Raw Native Interface (RNI)

The Raw Native Interface (RNI) is a set of functions and structures defined in native.h and nativcom.h. RNI provides an efficient way of both traversing between Java and native code, and manipulating objects while in native code.

Using RNI requires knowledge of garbage collection, pointer locking, and other issues. Dynamic-link libraries (DLLs) you call through RNI need to be specially written to work with RNI. You can't use RNI to call arbitrary DLLs, although you can write wrapper DLLs.

To work with RNI, native code must follow naming conventions, adapt to Java data representations, and deal with the garbage collection process of the Java environment.

For example, if the native code is going to be in a long loop, the garbage collector should be called periodically. Similarly, if the code is going to block on user input or call a thread that will block, it should call the garbage collector around the code that can block. Furthermore, objects need to be protected by garbage collection frames when calling back into Java.

All this increases programming complexity. In exchange for this complexity, you get greater speed and full access to all objects' fields. A good use of RNI is systems-level programming tasks, such as extending the capabilities of the Microsoft virtual machine (Microsoft VM).

The following topics describe the mechanism of calling between Java and native code (typically C or C++) using the Microsoft VM. This includes the native code DLL interface as well as implications in the mechanism for garbage collection.

Raw Native Interface Enhancements
RNI Message Box Example
Accessing Fields
Garbage Collection Issues
Calling Java Methods
Object Creation
Throwing Java Exceptions from Native Code
Synchronization
Overview of the Garbage Collection Architecture


Raw Native Interface Enhancements

RNI has been extended as a result of feedback and performance enhancements that have been made to the following primary areas:

Reflection APIs
Future Garbage Collection Performance Enhancements
RNIGetCompatibleVersion Requirement
RNI Invocation APIs

Reflection APIs

A number of native reflection APIs have been added to improve accessibility to an object's methods and fields. Using these APIs insulates DLLs from changes to the underlying object model or changes in the class hierarchy.

Users of RNI should use the new write barrier support functions to set an object field inside another object. These APIs are GCSetObjectReferenceForObject and GCSetObjectReferenceForHandle. Also, Field_SetValue, already in Microsoft® Internet Explorer 3.x (the virtual machine version in the Microsoft SDK for Java version 1.5.1), will support the write barrier. RNI developers are encouraged to use the Field_ reflection APIs added in Internet Explorer 3.x because these APIs abstract the object layout. Because these APIs are available on Internet Explorer 3.x, it should be possible to make a single DLL that will work on Internet Explorer 3.x and Internet Explorer 4.0.

Future Garbage Collection Performance Enhancements

To support future garbage collection enhancements, the internal object model was changed to enable more effective garbage collection, and enable future write-barrier support in the garbage collector. To insulate code from these or future changes to the object model, developers are encouraged to use the reflection APIs previously described. A Java object may still be accessed as a C structure, but code must be recompiled using the updated msjavah tool provided in this SDK.

Value layout order in objects has changed. Previously, if class A with a string, an int, and a string, followed by class B with an int and a string, the object layout in memory was as follows:

From A string (can be garbage collected)
    int (atomic non-collectable)
    string
From B int
    String

In the previous example, there are three garbage collection roots. The new object layout coalesces collectable objects within a class, thus reducing the number of garbage collection roots shown as follows:

From A int (atomic non-collectable)
    string (can be garbage collected)
    string
From B string
    Int

Because of this model change, all code that uses RNI must be rebuilt and recompiled with the new msjavah tool. Existing code that hasn't been recompiled will not run on existing virtual machines. Also, existing code that relies on accessing strings directly, rather than using a provided API, will not function.

RNIGetCompatibleVersion Requirement

Due to the object model changes previously described, many RNI DLLs designed for earlier versions of the Microsoft VM need to be recompiled. To identify whether an RNI DLL is compatible with the current version of the virtual machine, it will call the RNI DLL's RNIGetCompatibleVersion export. RNI DLLs that do not export this API will not be loaded by the current virtual machine.

RNI Invocation APIs

The Microsoft VM supports two new invocation APIs, PrepareThreadForJava and UnprepareThreadForJava, which can be used to execute RNI APIs on any Microsoft® Win32® thread. The Microsoft SDK for Java has an invocation sample provided in %SDKDIR%\Samples\Native\Invocation. For more information, see the Native Code Samples Overview. For information about other samples in this SDK, see the Samples Overview.


RNI Message Box Example

Here is the Message Box example using RNI. Compare it with the J/Direct Message Box example.

class ShowMsgBox {
  public static void main(String [] args) {
    ShowMsgBox app = new ShowMsgBox();
    app.ShowMessage("Generated with RNI");
  }
  private native void ShowMessage(String msg);
  static {
    System.loadLibrary("USER32");
  }
}

Here, ShowMessage is declared native and the loadLibrary call is added in a static block to make sure the DLL that implements the API (USER32.DLL) will be loaded.

Compile this Java source into a class file shown as follows:

jvc ShowMsgBox

Next, use msjavah to produce a header file used by the native code:

msjavah ShowMsgBox

The result is shown as follows:

/*  DO NOT EDIT - automatically generated by msjavah  */
#include <native.h>
#pragma warning(disable:4510)
#pragma warning(disable:4512)
#pragma warning(disable:4610)

struct Classjava_lang_String;
#define Hjava_lang_String Classjava_lang_String

/*  Header for class ShowMsgBox  */

#ifndef _Included_ShowMsgBox
#define _Included_ShowMsgBox

#define HShowMsgBox ClassShowMsgBox
typedef struct ClassShowMsgBox {
#include <pshpack4.h>
    const long MSReserved;
#include <poppack.h>
} ClassShowMsgBox;

typedef struct ClassArrayOfShowMsgBox {
    const int32_t MSReserved;
    const unsigned long length;
    HShowMsgBox * const body[1];
} ClassArrayOfShowMsgBox;
#define HArrayOfShowMsgBox ClassArrayOfShowMsgBox
#define ArrayOfShowMsgBox ClassArrayOfShowMsgBox

#ifdef __cplusplus
extern "C" {
#endif
__declspec(dllexport) void __cdecl ShowMsgBox_ShowMessage
  (struct HShowMsgBox *, struct Hjava_lang_String *);
#ifdef __cplusplus
}
#endif

#endif  /* _Included_ShowMsgBox */

#pragma warning(default:4510)
#pragma warning(default:4512)
#pragma warning(default:4610)

This header file defines a structure ClassShowMsgBox that represents data members and a declaration for the native API that is implemented. RNI reveals the binary layout of the objects; JNI does not. As a result, RNI allows you to directly access information without a field or method identifier. However, because binary layout of objects is VM-specific, RNI code may not be totally portable to non-Microsoft virtual machines.

As you can see by the #ifdef __cplusplus preprocessor directive, this file can be compiled either by a C or a C++ compiler.

In RNI, the functions for controlling virtual machine operations are directly available. They are defined in native.h and documented in the Raw Native Interface Reference.

One of the most unique and complex things about RNI is the garbage collection model. In Java Native Interface (JNI), garbage collection basically follows the same rules during native method execution that it follows for the Java code execution. In RNI, you must start and stop garbage collection during native method activity. By default, garbage collection is disabled upon entering the native method. You can assume that the objects being used will not be garbage-collected during that time. But if the native method is going to take a long time, you may enable garbage collection by calling the GCEnable RNI function.

To ensure that specific objects will not be garbage-collected when garbage collection is enabled, use the RNI functions and structures provided for this purpose. See GCFramePop, GCFramePush, and GCFrame for details. These are analogous to global handles.

Note One useful feature of msjavah is that primitive types (int, boolean, long, and so on) marked static and final become #defines in the resulting header file, making it much easier to share constants.

Write a C or C++ source file that includes the header file generated by msjavah and implements the native method, then compile it and generate a dynamic-link library (DLL). This part is platform-dependent, and assumes that you know how to create a DLL. Remember to use the following include statements in the C or C++ source file:

#include <varargs.h>
#include <native.h>
#include "ShowMsgBox.h"

Export the RNIGetCompatibleVersion method from your DLL. All RNI DLLs must export this method; otherwise, an UnsatisfiedLinkError exception is thrown when the method is called. Export this method in native code shown as follows:

DWORD __declspec(dllexport) __cdecl RNIGetCompatibleVersion() {
return RNIVER;
}


Accessing Fields

In many real-world examples, the Java class will have fields that you want to modify from native code; this is fairly straightforward. The following simple class demonstrates this:

    class FieldDemo
    {
        int x;
        int y;
        int z;

        public native void SetFields();
    }

Msjavah generates header files as follows:

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <native.h>
/* Header for class FieldDemo */

#ifndef _Included_FieldDemo
#define _Included_FieldDemo

typedef struct ClassFieldDemo {
#pragma pack(push,1)
    int32_t MSReserved;
    long x;
    long y;
    long z;
#pragma pack(pop)
} ClassFieldDemo;
#define HFieldDemo ClassFieldDemo

#ifdef __cplusplus
extern "C" {
#endif
__declspec(dllexport) void __cdecl FieldDemo_SetFields(struct HFieldDemo *);
#ifdef __cplusplus
}
#endif
#endif

The ClassFieldDemo structure defines fields for modifying x, y, and z. If you wanted to set x, y, z to 42, 43, and 44 respectively, you would call the following function:

    void cdecl FieldDemo_SetFields(struct HFieldDemo *phThis)
    {
        phThis->x = 42;
        phThis->y = 43;
        phThis->z = 44;
    }

Notice how the Java int type maps to a long type on the native side. The following table shows how all the types map from Java to C.

Java

C
boolean | long
byte | long
char | long
double | double
float | float
int | long
long | int64_t
short | long


Garbage Collection Issues

The following topics describe the issues associated with garbage collection:

Protecting Objects on the Stack
Protecting Objects in Allocated Memory
Calling Back To Java

Protecting Objects on the Stack

By default, garbage collection cannot occur while native code is executing. Other threads that try to do any garbage collection will block until the thread in native code returns to Java. This allows the virtual machine to avoid conservative scanning of native stacks, which is often unreliable and can slow down performance.

A lot of native code does some quick calculation and returns, so this isn't a problem. However, if the native code is going to perform an operation that takes some time, explicitly enable and disable garbage collection around the slow code.

Of course, enabling garbage collection means that any object could move at any time, invalidating any pointers to those objects in native code. The simplest way to handle this is to inform the garbage collector of objects you're interested in before enabling garbage collection using a GCFrame with GCFramePush. Object pointers kept in a GCFrame will be automatically updated if the object gets moved. When you're done, inform the garbage collector using GCFramePop. The following is a typical example:

void some_java_method(HObject *phobj1Unsafe, HObject *phobj2Unsafe)
{
// Keep a structure with all the objects we're interested in.
struct
{
HObject *phobj1Safe;
HObject *phobj2Safe;
} gc;

// Declare a GCFrame;
GCFrame gcf;

// Tell the garbage collector about our structure.
// It will initialize this structure to null.
GCFramePush(&gcf, &gc, sizeof(gc));

// Set the object ptr.
gc.phobj1Safe = phobj1Unsafe;
gc.phobj2Safe = phobj2Unsafe;

// It's now safe to enable garbage collection.
GCEnable();

// ...time passes...garbage collection occurs...objects move...

// Disable gargbage collection so we can access objects safely.
GCDisable();

// If garbage collection moved our object,
// then gc.hobjSafe will have been automatically updated.

gc.phobj1Safe->x = 42;
gc.phobj2Safe->y = 33;

// We're done.
GCFramePop(&gcf);
}

Note

  • You must enable garbage collection as many times as you disabled it.

  • Call GCFramePop before returning from native code back in to Java.

  • Call GCFramePop before pushing a second GCFrame within the same method.

  • GCFrames are "strong" in that having an object in GCFrame is considered equivalent to having a reference to that object so it won't be released by the garbage collector.

Protecting Objects in Allocated Memory

GCFrames are ideal for protecting objects on the stack, but not in situations where you want to keep an object pointer longer than the lifetime of the function in global memory. For situations like this, use GCNewHandle and GCFreeHandle instead as follows:

    HObject **pphobjSafe = NULL;

    void some_java_methodA(HObject *phobjUnsafe)
    {
        // Allocate a strong ptr that we want to use later.
        pphobjSafe = GCNewHandle(phobjUnsafe);
    }

    void some_java_methodB()
    {
        // Use the strong ptr we saved previously.
        *pphobjSafe->x = 42;
        GCFreeHandle(pphobjSafe);
    }

You can also create "weak" pointers to track an object’s movement by calling GCGetPtr. A weak pointer allows the tracked object to be freed by the garbage collector if no more references to that object exist. After the tracked object is freed by the garbage collector, the contained pointer will be NULL. Do not call GCFreePtr on a weak pointer to a freed object. If you know the tracked object has not been freed by the garbage collector, call GCFreePtr when you no longer need to keep track of it.

Calling Back To Java

If you call back to Java from native code, garbage collection may automatically be enabled by the Microsoft VM if memory needs to be allocated. This means that any object pointer you want to use after the call must be protected, either in a GCFrame or tracked by a strong pointer.


Calling Java Methods

The most common method for calling a Java API from native code is execute_java_dynamic_method (see also execute_java_dynamic_method64 and execute_java_dynamic_methodV). The following example shows how to call the move method on a Rectangle object:

    execute_java_dynamic_method(NULL, phRectangle, "move", "(II)V", x, y);

The first parameter must be NULL, the second parameter is the object whose method you want to call, the third parameter is the method name, and the fourth parameter is the method signature.

Pass the parameters. The signature specifies the parameter types, surrounded by parentheses, followed by the return type. In this case, "(II)V" translates to "param 1 is an integer, parameter 2 is an integer, and the return type is void."

The following is a table of how each type maps to its signature character.

Parameter

Signature Char
array [
boolean | Z
byte | B
char | C
double | D
float | F
int | I
long | J
object | L
short | S
void | V

For arrays, the signature char is followed by the signature char of the type of the array. For example, an array of bytes would be "[B".

For objects, the signature is followed by the object class name and ends with a semicolon(;). For example, the signature for a Rectangle is "Ljava/awt/Rectangle;".

To call a static method, you can use execute_java_static_method (execute_java_static_method64 or execute_java_static_methodV). For example, to call System.gc( ), write the following:

    ClassClass* pcc = FindClass(NULL, "java/lang/System", FALSE);
    execute_java_static_method(NULL, pcc, "gc", "()V");

FindClass( ) is used to get a pointer to the class object. The first parameter should be NULL, the second is the class name, and the third should be FALSE. You can call execute_java_static_method with the returned class pointer. The first parameter should be NULL, the second is the class pointer, the third is the method name, the fourth is the method signature. Finally, call any arguments (in this case, there aren't any).

Repeated Calls

For performing repeated calls to the same method of a particular object, you can use the more low-level do_execute_java_method API to avoid repeated name lookups. The following is an example of moving a rectangle 10 times:

    struct methodblock *pmb = get_methodblock(phRectangle, "move", "(II)V");

    for (i = 0; i < 10; i++)
    {
        do_execute_java_method(NULL, phRectangle, NULL, NULL, pmb, FALSE, x, y);
    }

To get a pointer to a cached data structure that represents the object and the method, use get_methodblock. The first parameter is the object pointer, the second is the method name, and the third is the method signature. You can call do_execute_java_method with the returned methodblock pointer. The first parameter should be NULL, the second is the object pointer, the third and fourth parameters should also be NULL, the fifth is the methodblock pointer, the sixth should be TRUE for a static call and FALSE for a non-static call. Finally, pass any arguments.


Object Creation

These sections describe the creation of objects, arrays, and strings.

Basic Objects

Creating Java objects from native code is simple using the execute_java_constructor API. For example, to effectively create a "new Rectangle(0, 0, 10, 10)", write the following:

    HObject *phobj = execute_java_constructor(NULL, "java/awt/Rectangle", NULL,
   "(IIII)", 0, 0, 10, 10);

The first parameter should always be NULL, the second parameter is the full class name, but uses "/" instead of "." as the package delimiter. The third parameter should be NULL. The fourth parameter is the signature of the particular constructor to call (because there may be many), but without the return type (because constructors can't return values). Finally, pass any arguments. The return value will either be a pointer to the newly constructed Java object or NULL if an error has occurred.

Creating Arrays

To allocate an array, you can use ClassArrayAlloc. For example, to create an array of 200 bytes, you would use the following:

    HObject *phobj = ClassArrayAlloc(T_BYTE, 200, NULL);

The first parameter is the type of array to allocate, the second is the number of elements to allocate, and the third is only used when allocating arrays of non-primitive objects. For example, to allocate an array of 200 Rectangles, use the following:

    HObject *phobj = ClassArrayAlloc(T_CLASS, 200, "java/awt/Rectangle");

Note This just allocates space for the array itself. Each object in the array needs to be individually allocated.

The following list shows all the types supported by ClassArrayAlloc:

T_BOOLEAN

T_BYTE

T_CHAR

T_CLASS

T_DOUBLE

T_FLOAT

T_INT

T_LONG

T_SHORT

Creating Strings

Because Java string creation is such a common operation in native code, some string-specific functions exist to help you do so. For example, use the following to create a Java string of "Hello":

    HJava_lang_String *phString = makeJavaString("Hello", 5);

The first parameter is the C character array to use and the second parameter is the number of characters in the string (not including the terminating NULL).

Be aware that the JDK makeCString function is not supported in the Microsoft RNI API. It is recommended that you use the javaString2CString function instead of makeCString.


Throwing Java Exceptions from Native Code

To throw Java exceptions from native code, you can use the SignalError API. This creates a Java exception object that will be thrown upon return from the native code (the normal execution of the native code is not interrupted). This is shown in the following example:

    if (makeJavaString("Hello", 5) == NULL)
    {
        SignalError(NULL, "java/lang/OutOfMemoryError", "Failed to create string.");
        return;
    }

The first parameter is the environment (which should always be NULL), the second is the class name of the Java exception you want to throw (this must be a Java Throwable or a subclass of Throwable), and the third is the "detail string" (which can be NULL).

If you call into Java using something like execute_java_dynamic_method, it's possible that an uncaught exception was thrown during its execution. To test for this case, you can use the exceptionOccurred API. It takes NULL as its only parameter and returns TRUE if an exception was thrown and FALSE otherwise. You can produce a stack trace of the exception (to the System.err PrintStream) using exceptionDescribe. You can destroy the exception using exceptionClear.

For example:

    // Make sure there isn't already a pending exception.
    exceptionClear(NULL);

    // Call method.
    execute_java_dynamic_method(...);

    // Check if something bad happened.
    if (exceptionOccurred(NULL))
    {
        // Make sure people are aware of the problem.
        exceptionDescribe(NULL);

        // Stop the exception from being propagated.
        exceptionClear(NULL);
    }


Synchronization

Native methods that are synchronized don't automatically lock or unlock the object. As a result, you must do any necessary synchronization on the native side.

  • ObjectMonitorEnter takes an object monitor.

  • ObjectMonitorExit leaves an object monitor.

  • ObjectMonitorNotify is analogous to Object.notify().

  • ObjectMonitorNotifyAll is analogous to Object.notifyAll().

For example, a typical synchronized method will look like the following:

    long cdecl Some_Java_SynchronizedMethod(struct HSomeJava *phThisUnsafe)
    {
        // Normal garbage collection protection stuff.
        HSomeJava *phThisSafe;
        GCFrame gcf;

        GCFramePush(&gcf, &phThisSafe, sizeof(phThisSafe));
        phThisSafe = phThisUnsafe;

        ObjectMonitorEnter(phThisSafe);

        // Code here executes synchronized on this object.

        ObjectMonitorExit(phThisSafe);

        GCFramePop(&gcf);
   }

To check if an object is of a particular type, you can use isInstanceOf, shown in the following example:

    if (isInstanceOf(phSomeObject, "java/awt/Rectangle"))
    {
        // Object is a Rectangle...
    }

The first parameter is an object pointer and the second parameter is the full class name you want to test against.

Given a Java String type, you can query the number of Java characters it contains with javaStringLength( ). For example:

    int cchString = javaStringLength(phString);

You can copy a Java String type to a C string buffer (converting from Unicode to multi-byte characters) using the javaString2Cstring function. This is shown in the following example:

    char szMBCS[256];

    javaString2CString(phString, szMBCS, sizeof(szMBCS);

The first parameter is the String object, the second is the destination buffer, and the third is the size of the buffer (in bytes), including the terminating NULL.

You can copy from one array to the other using the ArrayCopy function. The following is an example of copying 10 elements from one array (starting at position 3) to another (starting at position 5).

    ArrayCopy(phabSrc, 3, phabDst, 5, 10);

The first parameter is the source array, the second parameter is the source offset, the third is the destination array, the fourth is destination offset, and the fifth is the number of elements to copy.


Overview of the Garbage Collection Architecture

The goals of the garbage collection architecture are as follows:

  • Garbage collection should be transparent for replacing malloc-based C programs.

  • Garbage collection overhead should be minimal (in terms of time and percentage execution) for most Java applets and applications.

Efficient memory allocation is the key to countering the overhead that occurs while determining the difference between live and dead pointers. Most modern, high-performance garbage collectors start with a simple way of allocating memory. To allocate, a current block of memory exists with a part that's used and a part that's free. The new object is added on the end of the used block, and the pointer in the used block is moved. Another block is dynamically allocated when the current block becomes full. The blocks are a fixed size. If you need a larger block ("large" is dependent on tuning; this will typically be between 4K and 8K), a custom block is allocated that has only that object. All the blocks are linked together. The decision about the size of the block is the same trade-off as page size within the operating system.

To distinguish live pointers from dead pointers, we start from a root set where we know there are live pointers. These pointers are followed by copying them into new blocks. Each object that these pointers point to in these roots is worked through recursively. When all new objects in the new copy have been scanned, every live object is copied. This scheme can be fairly expensive if you always copy many objects that are very stable. This is improved by taking a snapshot of the last point that was garbage collected and the new point that is garbage collected and copy only the objects that are in between, leaving old objects alone. This is called generational garbage collection, using two generations, in this case.

The large blocks are not copied—they're just logically moved from the old set to the new. Further improvements may be made by considering only roots between the phases, the part of memory that has been modified.

Garbage collection is called on allocation of new objects. When a new object is allocated, the garbage collector detects memory threshold (a heuristic is used to decide if it needs to garbage collect and, if so, sets a flag). The Microsoft VM looks at the flag and initiates the process of checking the block count.

Mark and compact are not used as garbage collection methods because they are inherently less efficient in situations where you have lots of garbage, which will be typical in Java programs.


Windows Foundation Classes for Java

Windows Foundation Classes for Java (WFC) is a new application framework that accesses the Microsoft® Windows® API, enabling you to write full-featured Windows applications with the Java programming language. WFC also wraps the Dynamic HTML (DHTML) object model implemented in Microsoft® Internet Explorer 4.0, which allows you to dynamically manipulate HTML on both the client and the server. You must install the latest Microsoft virtual machine or Microsoft® Visual J++® for WFC support.

This section includes the following topics:

WFC Fundamental Programming Concepts provides a conceptual framework for the WFC packages and classes, and explains some of the fundamental WFC models.

Graphical Services describes how to use the WFC Graphics object to produce graphical output.

Programming DHTML in Java describes how to use the com.ms.wfc.html package to access the DHTML object model from Java classes.

Data Binding in WFC describes how to access data from Java programs using ActiveX Data Objects (ADO) components.


WFC Programming Concepts

Windows Foundation Classes for Java (WFC) provides a framework of Java packages that support components targeted for the Windows operating system and the Dynamic HTML (DHTML) object model. The purpose of this section is to provide a conceptual framework for the WFC packages and classes and to explain some of the fundamental WFC models.

The following topics are covered:

WFC Packages provides a high-level overview of the main packages that make up WFC.

Working with the WFC Visual Components describes the controls, forms, and graphical objects in WFC.

Handling Events in WFC describes the use of delegates for handling events.

Using WFC Application Services describes some of the core application features.

Using Java Threads with WFC describes the threading model for WFC.


WFC Packages

The basic foundation blocks of WFC are Windows and Dynamic HTML. WFC is rooted firmly in the Microsoft® Win32® programming model, enabling you to use Java to write applications based on Microsoft® Windows® that take advantage of its user-interface controls, events, and system services. WFC is also rooted in the DHTML object model, which enables you to create both client and server HTML pages that use the power of DHTML directly from Java.

Central to these technologies are native dynamic-link libraries (DLLs) that provide the core API of the WFC infrastructure. These libraries are made available to the Java language by two different technologies: the jactivex tool and Microsoft® J/Direct™. If the DLL represents a COM/Microsoft® ActiveX® component, jactivex creates wrapper classes that map the COM objects to Java objects. If the DLL is not COM-based, J/Direct is used to call directly into the DLL and to marshal the data types between Java and the native language of the DLL (such as C or C++). Both these technologies take advantage of the built-in support and synergy of the jvc compiler and the Microsoft virtual machine (Microsoft VM).

This is important to know because several WFC packages are composed entirely of either COM wrapper classes (produced by jactivex) or J/Direct classes. These classes have methods that map directly to the underlying API; they are not documented in the WFC reference because they are not typically called directly. They are, however, discussed as support classes for other packages.

Not including the native API support packages, the following table shows the main packages in WFC.

Package | Description
com.ms.wfc.app | Base classes that encapsulate Windows application operations. In addition to the basic Windows message handling structure, there is support for Windows features such as the Clipboard, the registry, threads, window handles, system information, and so on.
com.ms.wfc.core | Base classes for the component model. This package includes support for containers, events, exceptions, and properties.
com.ms.wfc.data | Active Data Objects (ADO) classes that enable data access and data binding in Java. This package also includes com.ms.wfc.data.ui, the package that provides the base classes for the data-bound controls in WFC.
com.ms.wfc.html | Classes for implementing Dynamic HTML in Java. These classes provide both client- and server-side support.
com.ms.wfc.io | Classes for accessing data streams, implementing a complete package for reading and writing serial streams, file access, and for mapping between differing types of data streams.
com.ms.wfc.ui | Core classes for the controls that ship with WFC. These classes also provide access to the Windows Graphics API.
com.ms.wfc.util | Utility classes for various forms of sorting, implementing hash tables, and so on.

The following are the core native API support classes in WFC:

Package | Description
com.ms.wfc.ax | Provides Java wrapper classes for the Microsoft® ActiveX® interfaces.
com.ms.wfc.html.om | Provides Java wrapper classes for the Dynamic HTML object model.
com.ms.wfc.ole32 | Provides Java wrapper classes for OLE services.
com.ms.wfc.win32 | Provides Java wrapper classes for Win32 API.


Working with the WFC Visual Components

Although there are some differences in the WFC visual components of Win32 and DHTML applications, many more similarities exist. These similarities enable the WFC component model to easily serve both types of applications. For example, both the Win32 and DHTML models include basic control types, such as edit boxes, check boxes, buttons, radio buttons, and combo boxes. For the most commonly used controls in Win32, there is usually a DHTML control with the same name prefaced by the letters "Dh" (for example, the com.ms.wfc.ui.Edit class has a corresponding com.ms.wfc.html.DhEdit class). Fonts, color constants, and most event types are also shared between the Win32 and DHTML models.

There are also components that are specific to each model, such as tables for DHTML or list view controls for Win32 components.

This section describes both the Win32 and DHTML visual components of WFC.


Windows Visual Components

The main package in WFC that supports the visible components is com.ms.wfc.ui and the base class for most visual elements in WFC is com.ms.wfc.ui.Control. Most of the WFC controls extend this class, including the Form class, which is the visual container for controls.

This section describes the Microsoft® Windows® visual components of WFC, including the following topics:

com.ms.wfc.ui.Control class

com.ms.wfc.ui.Form class

WFC Controls Overview

Accessing Graphical Services

com.ms.wfc.ui.Control Class

The Control class contains all the essential base properties, methods, and logic for manipulating a Win32 window. These methods can be categorized as follows:

  • Methods for setting and retrieving the control's properties, such as the size of the display and client rectangles, the foreground color, background color, associated brush, cursor, text, font, position, and so on. These methods have names that start with set or get (for example, setBrush and getBrush).

  • Event methods. For every event that a control generates, there are three methods implemented in the control. For example, for the move event, there is an onMove method, which triggers the event, an addOnMove method, which assigns an event handler to the move event, and a removeOnMove method, which removes the event handler. The Control object handles most basic control events.

  • Methods dealing with parent/child relationships of controls. For example, the add method adds a child control, and assignParent and getParent assign and retrieve the parent control. There are also methods for handling arrays of child controls.

  • Methods affecting the layout, z-order, painting, and input focus of the control, such as bringToFront, sendToBack, updateZOrder, performLayout, focus, show, hide, update, invalidate, createGraphics, and createWindowGraphics.

  • Low level event-processing methods. At the Win32 level, Windows receives messages from the system. In the Control class, every input message to a control has a protected process method (for example, processCmdKey, processCmdKeyEvent, or processDialogKey). These methods are important only if a control extending this base class wants to override them to do special processing.

  • Methods relating to window handles, messages, and thread invocation. These are available for programmers experienced with the Win32 programming model. For example, createHandle, destroyHandle, getRecreatingHandle, fromHandle, fromChildHandle all deal with window handles, and sendMessage and reflectMessage allow the control access to the underlying window messages. For descriptions of the thread invocation methods, see Using Java Threads with WFC.

The Control class extends com.ms.wfc.core.Component class, which is the base class for all WFC components.

com.ms.wfc.ui.Form Class

A form is the main visual element of an application or a custom dialog box associated with an application. The com.ms.wfc.ui.Form class serves as the foundation for forms in WFC. The Form class extends com.ms.wfc.ui.Control, so it has all the Control methods plus many of its own for handling its role as a container for controls and as a window. These include methods used to:

  • Add and remove handlers for the active, closed, closing, deactivate, inputLangChange, inputLangChangeRequest, MDIChildActivate, menuComplete, menuStart, and ownedForm events.

  • Set the form's window properties. For example, to set the form's initial maximized or visible state, start position and border style; or to determine whether the form has an automatic scroll bar, a control box, or a minimize box, and whether the form's icon is in the task bar.

  • Determine the relationship of menus, controls, or other forms placed on the form, such as setting the main menu, arranging controls, supporting multiple document interface (MDI) forms, or determining whether the form receives all the control's key events.

  • Set properties when the form is used as a modal dialog box and to run and retrieve results from a dialog box when the form is an application. This includes methods to set the Accept, Cancel, and Help buttons on a dialog box, to start a dialog box, and to set and retrieve the dialog result values returned by a modal dialog box.

This list is not comprehensive but provides a general description of a form.

WFC Controls Overview

All visible WFC controls reside in the com.ms.wfc.ui package. With over 240 classes in this package, it can be difficult to immediately determine which classes you want to use. Fortunately, the classes fall into several major categories, as follows:

  • Classes that are controls, directly extending the com.ms.wfc.ui.Control class or ultimately derive from the Control class.

  • Classes that are controls, using CommonDialog as a base class (this includes the CommonDialog class itself). CommonDialog wraps the Win32 CommonDialog API.

  • Classes that contain constant values used by controls. All these classes extend com.ms.wfc.core.Enum.

  • Classes that represent events and extend com.ms.wfc.core.Event or are event handler classes (delegates).

  • Classes that represent intrinsic Windows graphical objects such as brushes, bitmaps, colors, cursors, fonts, pens, palettes, icons, regions, and images. For pointers to detailed information on using these objects, see Accessing Graphical Services

  • Classes that, like Control, extend com.ms.wfc.core.Component but do not require the visual run-time overhead of Control. Some examples are ColumnHeader, Menu (and MainMenu, ContextMenu, and MenuItem, which extend it), RebarBand, StatusBarPanel, ToolTip, and ImageList (and ImageListStreamer, which extends it).

  • Miscellaneous classes that wrap other Windows interfaces; these include Help, which wraps the Windows Help engine, HTMLControl, which wraps a browser, and MessageBox, which wraps the Windows message box, among others.

The com.ms.wfc.ui classes in the following table directly extend Control. Controls that extend these classes are listed in the description.

Class | Description
Animation | Encapsulates a Windows animation control, a rectangular control that plays an Audio-Video Interleaved (AVI) animation file.
AxHost | Wraps an ActiveX control and exposes the control as a WFC control.
Button | Encapsulates a Windows button control.
Checkbox | Encapsulates a Windows check box control, which is a labeled box that is checked or unchecked to select or clear an option.
ComboBox | Encapsulates the Windows combo box control.
DateTimePicker | Encapsulates a Windows date and time picker control, which allows users to specify date and time information.
Edit | Encapsulates a Windows edit control, which is a rectangular control that the user can enter text into.
Form | Represents the basic top-level window.
GroupBox | Encapsulates a group box control, which is a rectangle that contains other controls.
Label | Encapsulates the Windows label control, which displays a string of text that the user cannot edit.
ListBox | Encapsulates the Windows list box control, which displays a list from which the user can select one or more items. ListItem is used with this class. The CheckedListBox control extends this class.
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.
MDIClient | Represents a window that contains MDI child windows.
MonthCalendar | Encapsulates a Windows month calendar control, which provides a simple calendar interface from which the user can select a date.
Panel | Represents a container you can use to parent other controls visually. The TabPage class extends Panel.
PictureBox | Encapsulates a Windows PictureBox control used to contain bitmaps.
ProgressBar | Encapsulates the Windows ProgressBar control, which dynamically tracks the progress of an operation by moving a bar.
RadioButton | Encapsulates a Windows radio button (or option button) control, which displays an option that can be selected or cleared.
Rebar | Encapsulates a rebar control, which contains other controls within moveable, resizable bands. RebarBand is used with this class.
RichEdit | Encapsulates a Windows RichEdit control.
ScrollBar | Represents the base class for scroll bar controls. HScrollBar and VScrollBar extend ScrollBar.
Splitter | Encapsulates the splitter control, which allows the user to resize docked controls at run time.
StatusBar | Encapsulates the Windows status bar control. StatusBarPanel is used with this class.
TabBase | Defines the base class that contains common functionality for Tab classes controls. TabControl (which uses TabPage) and TabStrip (which uses TabItem) extend this class.
ToolBar | Encapsulates the ToolBar custom control. ToolbarButton is used with this class.
TrackBar | Encapsulates a Windows trackbar control (also known as a slider control), which contains a slider for selecting a value in a range.
TreeView | Encapsulates a Windows tree view control. TreeNode is used with this class.
UpDown | Encapsulates the up-down control (sometimes called a spinner control).

Accessing Graphical Services

Applications in the WFC environment perform graphical operations by using the Graphics object, which encapsulates the native drawing capabilities of the Windows operating system. This object provides flexible support for the most commonly used drawing operations, including displaying images and icons and drawing lines, polygons, and text.

The Graphics object performs its work by wrapping a Windows device context, a system data structure that defines system graphical objects, their associated attributes, and the graphic modes affecting output to a device. Because you can retrieve the device context that underlies a Graphics object, you can use the Graphics object seamlessly with native Win32 drawing routines.

All WFC objects that extend the Control object support creating a Graphics object through the createGraphics method. In addition, all objects that extend the Image object, such as Bitmap, Icon, and Metafile, support the creation and retrieval of their associated Graphics object through the getGraphics method.

For more information on how to use this object, see Graphical Services.


Dynamic HTML Visual Components

Dynamic HTML elements make up the second set of visual components in WFC. The controls in com.ms.wfc.html are based on the Dynamic HTML object model. The classes in com.ms.wfc.html are used to create new elements and also to bind to existing elements on an HTML page. These components can be created and manipulated on a client browser or on a server, which sends them to a client browser. This object model exists on several platforms. Therefore, it is not fundamentally rooted in Win32, although user interface controls tend to be similar because the standard set of buttons, list boxes, radio buttons, and so on, are present on both.

Both sets of WFC controls (Win32 and Dynamic HTML) have a similar base because they both ultimately derive from com.ms.wfc.core.Component. Components are elements that can be hosted in a container and support the IComponent interface, which has methods for siting the component. How components and containers are hooked up is of little concern to most programmers using WFC; however, because elements from both com.ms.wfc.html and com.ms.wfc.ui are based on components, they exhibit similar characteristics. For example, all components are added to their parent containers using the add method.

For a better understanding of how to use the com.ms.wfc.html package, see Programming Dynamic HTML in Java.


Handling Events in WFC

The Control base class and classes that extend it, such as buttons and edit boxes, expose standard Windows events such as click, keyPress, mouseMove, dragDrop, and others. You can work with an event in your application using delegates. You do not have to understand delegates in great detail to write event handlers in an application. However, understanding how to create and use delegates is useful if you are building controls, working with other applications that trigger events, or are using threads with WFC components. This section provides some background on delegates, and then addresses the practical aspects of handling events.

A delegate declaration defines a class that extends com.ms.lang.Delegate. The jvc compiler also recognizes delegate as a keyword, providing a shortcut for creating a delegate-based class. A delegate instance can call a method on an object and pass data to that method. Most importantly, the delegate is isolated from the object it refers to and needs to know nothing about it. Therefore, it is ideal for anonymous invocation. In other languages, this functionality is implemented as a function pointer. However, unlike function pointers, delegates are object-oriented, type-safe, and secure.

In WFC, delegates are most often used to bind events to handler methods, such as a click event on a button control to a handler method in your class. When the event occurs, the control invokes the delegate, passing it any event information. The delegate, in turn, calls the registered handler method and passes the event data. You can also use delegates to bind one event to more than one method (called multicasting); when the event occurs, each delegate in the list is called in the order in which they were added. Conversely, delegates from different events can be assigned the same handler method (for example, a toolbar button and a menu item can both call the same handler).

To work with events in your application, you use a delegate to register for notification when that event occurs for a specific control. To register, call the addOn<event> method of a control, where <event> is the name of the event you want to handle. For example, to register for the click event of a button, you call the button object's addOnClick method.

The addOn<event> method takes as a parameter an instance of a delegate, typically an existing WFC delegate that is associated with specific event data. In the addOn<event> call, the delegate instance is created with a reference to the method you want to bind the event to. The following code shows how you would bind the event handler "btnOK_Click" (in the current class) to the click event of a button called btnOK.

   Button btnOK = new Button();
   btnOk.addOnMouseClick( new EventHandler( this.btnOK_Click ));

For most events, you can create and pass an instance of the generic EventHandler delegate, which passes a generic Event object. However, some events use special event handler classes when they include extra, event-specific information. For example, mouse movement events typically include information such as the mouse cursor location. To get this type of information, you create and pass an instance of the MouseEventHandler class, which passes a MouseEvent object to the handler. Keyboard events require the KeyEventHandler to get information about the status of SHIFT keys, and so on (this handler passes a KeyEvent object).

All WFC event handler delegate classes extend com.ms.lang.Delegate. Most of them are in the com.ms.wfc.ui package with names that end in EventHandler. All WFC events extend com.ms.wfc.core.Event, have names that end in Event, and can be found in the com.ms.wfc.ui package.

When the delegate calls your handler, it passes two parameters. The first parameter is a reference to the object that originated the event. The second is an event object that can contain information about the event. A handler for the delegate from the preceding code sample might look like the following example:

   private void btnOK_Click(Object source, Event e)  {
      if (source instanceof Button) {
         String buttonName = ((Button)source).getText();
         MessageBox.show("You clicked button " + buttonName);
      }
}

If you used the generic EventHandler class to bind the event to your method, the Event object in your handler will not contain any extra, event-specific information. But if this information is available for the event, you can extract it from the specific event object. The following example shows what the delegate and handler might look like for a mouse movement event. The MouseEvent object exposes properties that allow you to get the mouse position.

Example

   // This is the request for notification.
   Button btnTest = new Button();
   // Note that the addOn<event> method uses the MouseEventHandler class.
   btnTest.addOnMouseMove( new MouseEventHandler(this.btnTestMouseMove));

   // This is the handler for the mouse movement event.
   private void btnTestMouseMove(Object source, MouseEvent e){
      edit1.setText( e.x + ", " + e.y);
   }

If you want to handle events for multiple controls or multiple events for the same control, request a separate notification for each control/event combination. Multiple notifications can specify the same handler; for example, all the buttons on a toolbar might call the same handler for their click event. You can use the source object passed to the event handler to get details about which button was clicked. (Typically, you cast the object passed to the handler into the appropriate class to be able to invoke methods from the appropriate class.)

The following example shows code that defines buttons for a toolbar and requests notification for their click events, along with the method used to handle them.

Example

   private void initEventHandlers() {
      Button buttonNew = new Button();
      Button buttonSave = new Button();
      Button buttonExit = new Button();
      // All events are routed to the same handler.
      buttonNew.addOnClick( new MouseEventHandler( this.toolbarClick) );
      buttonSave.addOnClick( new MouseEventHandler( this.toolbarClick) );
      buttonExit.addOnClick( new MouseEventHandler( this.toolbarClick) );
   }
   // This is the common event handler for all buttons.
   private void toolbarClick( Object source, Event e){
      String buttonName;
      if (source instanceof Button) {
         buttonName = new String((Button)source).getText());
         MessageBox.show("You clicked button " + buttonName);
      }
   }


Using WFC Application Services

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, Using Java Threads with WFC.

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 Application.run 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 example 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 Application.exitThread method when the form is closed. If no form is passed, the application runs until Application.exit 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

Use the Application object to assign event handlers for five different events that occur in the context of the application: ApplicationExit, OnIdle, SettingChange, SystemShutdown, and ThreadException. The following addOn methods can be called to define event handlers for these events.

Application Method | Description
addOnApplicationExit | Specifies a handler that is called when the application quits. You can clean up application resources here that will not be released by garbage collection. (To force the application not to quit, specify a handler for the form’s closing event.)
addOnIdle | Specifies a handler that is called when the application’s message queue is idle; for example, to perform background operations or application cleanup.
addOnSettingChange | Specifies a handler that is called when the user changes window settings.
addOnSystemShutdown | Specifies a handler that is called immediately before a system shutdown is initiated by a user. This provides an opportunity to save data.
addOnThreadException | Specifies a handler that is called when an untrapped Java exception has been thrown, allowing the application to correctly handle the exception. This event handler takes a com.ms.wfc.app.ThreadExceptionEvent object, which has one field that represents the exception thrown.

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 RegistryKey and Registry 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 com.ms.wfc.app.SystemInformation class. System time is available using the com.ms.wfc.app.Time 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 com.ms.wfc.app.Registry class contains fields holding RegistryKey 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. 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 com.ms.wfc.app.Locale class and through the many subclasses of Locale that contain field constants pertaining 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 com.ms.wfc.app.Time 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 on.

The Time object in WFC stores time as the number of hundred-nanosecond units since A.D. 100, beginning Jan 1. The maximum value that can be stored in a WFC Time object is A.D. 10,000, ending Dec 31. 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. 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 com.ms.wfc.app.DataFormats class contains fields pertaining to each of the Clipboard formats. These field names (such as CF_TEXT) originate directly from the Win32 constant names.

The data for Clipboard and drag-and-drop operations is stored in a com.ms.wfc.app class called DataObject, which implements the IDataObject 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 com.ms.wfc.app.Clipboard. Clipboard.setDataObject takes an IDataObject and places it on the Windows Clipboard; Clipboard.getDataObject returns an IDataObject from the Clipboard. The target must ensure that the data format on the Clipboard is one that it can use. To do this, it should query the data object with the IDataObject.getDataPresent 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 Control.doDragDrop 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 MouseEvent object is checked to see if the left button is down, indicating the start of a drag operation. For example, the following code is an event handler for a list box control containing filenames.

Example

   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 com.ms.wfc.ui.DragDropEffect 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.

DragDropEffect Method | Description
COPY | Specifies that data will not be removed from the source after the transfer.
MOVE | Specifies that data will be removed from the source after the transfer.
SCROLL | Specifies that data will be scrolled in the target after the transfer.
ALL | Specifies that data will be removed from the source after the transfer and scrolled into the target (essentially COPY | MOVE | SCROLL).
NONE | Specifies that no operation is performed.

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.

Control Method | Description
addOnDragDrop | Specifies a handler for data that is dropped into your control or window (when the left mouse button is released).
addOnDragEnter | Specifies a handler for drop data as the cursor first enters the window.
addOnDragLeave | Specifies a handler for drop data as the cursor leaves the window.
addOnDragOver | Specifies a handler for drop data as the cursor is dragged across the window.

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, DragEventHandler) 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 DragEvent event. This contains, among other fields, a data field and an effect field. The DragEvent.data field contains an object that supports IDataObject that has methods to retrieve the data and the data formats to query for the existence of a specific format. Therefore, the handler must first call DragEvent.data.getDataPresent method with a format it will accept, and then determine whether it holds that data type. If so, it can then call the DragEvent.data.getData method (passing in that data type) and retrieve the data. How the data is displayed is determined by that control. The following example illustrates an edit control dragDrop event handler that displays text data dropped to it.

Example

    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);
      }
   }


Using Java Threads with WFC

Java is a free-threaded environment. This means that any object can call any other object, at any time, from any thread. Special care must be taken when writing objects so that their methods are atomic and thread safe.

There are several classes that benefit from being free-threaded, and WFC has provided the locking code to make these objects thread-safe. These classes are as follows:

  • com.ms.wfc.core.Component

  • com.ms.wfc.core.Container

  • com.ms.wfc.core.ComponentManager

  • com.ms.wfc.ui.Brush

  • com.ms.wfc.ui.Font

  • com.ms.wfc.ui.Pen

Comparatively, any object that derives from com.ms.wfc.ui.Control is apartment-threaded because of the Win32 window that is linked to each control. Additionally, most other objects in the com.ms.wfc.ui package are not synchronized; they should also be considered to be apartment threaded. Likewise, the com.ms.wfc.io, com.ms.wfc.html, and com.ms.wfc.util packages are not thread-safe.


Mixing Java and Win32 Threading Models

WFC accesses native Win32 components (such as windows) from Java objects. The Win32 window manager is apartment-threaded, and Windows automatically marshals calls from one thread to another as needed. When a free-threaded object calls into an apartment-threaded object, the call must marshal to the object's apartment. This means that the free thread is blocked for a period of time while the apartment thread handles the request. Any other calls from free-threaded objects to the apartment call will block until the apartment call is free. Consequently, this can lead to deadlock situations.

WFC controls work with free-threaded Java objects by requiring the programmer to request thread transitions (rather than hiding them). The programmer can then design an algorithm to prevent deadlocks. This can be done by invoking a delegate on the control's thread, which in turn calls the method specified in the delegate.

To execute a given delegate on the thread that created the control's window handle and contains the message loop, use the Control.invoke or Control.invokeAsync methods from the desired control. It is important to use the control's own thread in case (for any reason) the control needs to re-create its window handle. The invoke method causes the thread to call the specified callback method and wait for a return. The invokeAsync method causes the thread to call the callback method without waiting for reply. All exceptions on the invoked thread are passed on to the owning control in both cases.

You can also use the Control.createGraphics object to perform background painting and animation techniques on a ui.Graphics object. Whereas the Graphics object is apartment-threaded, the createGraphics call is entirely free-threaded. This allows one thread to create a graphics object for a control in another thread.


Creating and Exiting a Thread

Free-threaded threads can be created using the standard Java method of implementing the java.lang.Runnable interface.

The following example shows a class that implements Runnable and takes two controls (a trackbar and a label) as parameters to its constructor. From the thread's run method, it transitions to the trackbar's thread by calling the trackbar's invokeAsync method. InvokeAsync passes a delegate called tDelegate (an instance of com.ms.wfc.app.MethodInvoker) that specifies a callback method called tCallBack. Inside that method, the control's thread can safely manipulate the control's properties, in this case, changing the trackbar's tick style. This causes the trackbar's window handle to be re-created. If the thread was not transitioned as demonstrated here, the trackbar would be re-created on the new thread rather than on the thread containing the message loop; in this case, the control trackbar wouldn't receive any new messages and would fail to respond.

Example

import com.ms.wfc.app.*;
import com.ms.wfc.core.*;
import com.ms.wfc.ui.*;

//
// Runnable is the interface you need to implement to make a new
// java thread.
//
public class RunnableClass implements Runnable
{
   final int SLEEP = 500;
   Label l;
   TrackBar tb;

//
// This is the thread for our class.
//
   Thread thread;

//
// Makes a special delegate so WFC can call it from the control's
// thread.
//
   MethodInvoker tDelegate = new MethodInvoker(tCallback);

//
// Make a new Java thread; tell it to begin running via the
// start() method.
//
   public RunnableClass (TrackBar tb, Label l)
   {
      this.l  = l;
      this.tb = tb;
      thread  = new Thread(this, "RunnableClass thread");
      thread.start();
   }

   public void run()
   {
      while (true)
      {
//
// Call the specified method from the label's thread.
//
         tb.invokeAsync (tDelegate);
         try
         {
            Thread.sleep (SLEEP);
         }
         catch (InterruptedException e)
         {
         }
      }
   }

   int nCount = 0;
   int nTickStyles[] = {TickStyle.BOTH,
                        TickStyle.BOTTOMRIGHT,
                        TickStyle.NONE,
                        TickStyle.TOPLEFT};
//
// This code is executed on the trackbar's thread.
//
   private void tCallback()
   {
      int nIndex = nCount % (nTickStyles.length);
      l.setText ("hello from tCallBack: " + nCount);
      tb.setTickStyle (nTickStyles [nIndex]);
      nCount++;

      int nValue = tb.getValue();
      if (nValue >= tb.getMaximum())
         tb.setValue(0);
      else
         tb.setValue (nValue + 1);
   }

   public void stopThread()
   {
      thread.stop();
   }
}

Exiting a thread in this case is just a matter of running the thread's stop method. In this example, the Form class that creates the RunnableClass object calls that object's stopThread method when it is disposed. The following code fragment demonstrates this.

...
import RunnableClass;

public class SimpleRunnable extends Form
{

// This is the class that implements the Runnable interface.

   RunnableClass runnableClass;

   public SimpleRunnable()
   {

      initForm();
      runnableClass = new RunnableClass (tb, l);
   }

   public void dispose()
   {
      runnableClass.stopThread();
      super.dispose();
      components.dispose();
   }
   Container components = new Container();
   Edit eDescription = new Edit();
   TrackBar tb = new TrackBar();
   Label l = new Label();

   private void initForm()
   {
     // Code to initialize the controls omitted...
   }

   public static void main(String args[])
   {
      Application.run(new SimpleRunnable());
   }
}

Alternately, to create a new application thread without having to implement the Java Runnable interface or extend java.lang.Thread, you can use the Application.createThread method. The createThread method takes a delegate as a parameter (MethodInvoker is often used, but any delegate can be used). In this case, all logic can be contained in one class, typically the Form-based class of the application. The following example code fragment shows how this works.

Example

import com.ms.wfc.app.*;
import com.ms.wfc.core.*;
import com.ms.wfc.ui.*;

public class SimpleAppThread extends Form
{
   final int SLEEP = 700;
   Thread thread;

    // Specify the thread context to run a method on.
   MethodInvoker cbDelegate = new MethodInvoker( cbThrdCallback );

   public SimpleAppThread()
   {
      initForm();
//
//  Creates a new thread and runs the methodInvoker method
//  on the new thread. The returned thread object is needed
//  so we can stop the thread when this form is closed (disposed).
//  Note that thread.start() is called automatically.
//
       thread = Application.createThread (new MethodInvoker (this.methodInvoker));
   }

   private void methodInvoker()
   {
      while (true)
      {
         // cbThrdCallback is called on the check box's thread.
         cb.invoke (cbDelegate);
         try
         {
            Thread.sleep (SLEEP);
         }
         catch (InterruptedException e)
         {
         }
      }
   }

   int nCount = 0;
//
// Thread callback that sets check box alignment property.
// This code is to be executed on the check box's thread.
//
   private void cbThrdCallback()
   {
      cb.setText ("threadCallback loop: " + nCount++);
      if (nCount % 2 == 0)
         cb.setTextAlign (LeftRightAlignment.LEFT);
      else
         cb.setTextAlign (LeftRightAlignment.RIGHT);
   }

   public void dispose()
   {
      thread.stop();
      super.dispose();
      components.dispose();
   }

   private void cbSuspend_click(Object sender, Event e)
   {
      if (cbSuspend.getChecked())
      {
         cbSuspend.setText ("press to resume thread");
         thread.suspend();
      }
      else
      {
         cbSuspend.setText ("press to suspend thread");
         thread.resume();
      }
   }

   Container components = new Container();
   CheckBox cbSuspend = new CheckBox();
   CheckBox cb = new CheckBox();

   private void initForm()
   {
     // Code to initialize the controls here.
   }

   public static void main(String args[])
   {
      Application.run(new SimpleAppThread());
   }
}

Here the thread is stopped by calling the thread’s stop method from the form's dispose method. The thread is not in a separate class; its methods can be called directly from the Form-based class.

The Application class also contains the Application.exitThread method, which closes the thread's message loop and shuts down all windows on the thread (note that it does not stop or exit the thread itself). In comparison, Application.exit closes message loops on all threads and closes all windows.


Using Thread Storage

The WFC Application class provides support for Thread Local Storage (TLS). Each thread can allocate a slot of memory for storing data that is specific to the thread. Calling Application.allocThreadStorage returns an index to that slot. To set a value in TLS, call the Application.setThreadStorage with the index and a value you want to set. To retrieve that value, call Application.getThreadStorage. You must free any allocated thread storage with a call to Application.freeThreadStorage.


Working with Thread Exceptions

The com.ms.wfc.app class provides a ThreadExceptionDialog class, which is automatically displayed whenever an unhandled exception occurs in a thread. You can gain control of exceptions by using the Application.addOnThreadException method to specify your own thread exception handler. The addOnThreadException method takes a ThreadExceptionEventHandler delegate, which is constructed with your event handler method and the ThreadExceptionEvent class.

A thread exception event handler typically queries the exception field of the ThreadExceptionEvent object passed to it to determine the next course of action. From this thread exception handler, you can run the ThreadExceptionDialog and retrieve the dialog results in the same way as any other WFC dialog box: Use the Form.showDialog method to launch the dialog box, and compare the returned results with the com.ms.wfc.ui.DialogResult class fields.


delegate

The delegate keyword is used as part of a delegate declaration to define a class that extends com.ms.lang.Delegate, or com.ms.lang.MulticastDelegate. Delegates are commonly used within the Microsoft Windows Foundation Classes (WFC) library to build event-handling mechanisms.

Delegates roughly equate to function pointers, commonly used in C++ and other object-oriented languages. Unlike function pointers however, delegates are object-oriented, type-safe, and secure. In addition, where a function pointer contains only a reference to a particular function, a delegate consists of a reference to an object, and references to one or more methods within the object.

Either "regular" or multicast delegates may be declared, depending on the presence or absence of the multicast keyword. A "regular" delegate encapsulates a reference to a single method within an instance. When this type of delegate is invoked, the underlying method is called.

A multicast delegate differs from a regular delegate in that it may contain references to more than just one method. Methods in a multicast delegate are executed synchronously when the delegate is invoked, and in the order which they appear. If one of the called methods raises an exception, then the delegate ceases, and the exception is propagated to the delegate caller.

Note The delegate keyword is an extension to the Java language, provided by Microsoft.


multicast

The multicast keyword is used in a delegate declaration to define a class that extends com.ms.lang.MulticastDelegate. For more information on multicast delegates, see the delegate keyword.

Note The multicast keyword is an extension to the Java language, provided by Microsoft.


Graphical Services

The display of graphical objects in Microsoft® Windows® occurs through the graphics device interface (GDI), a device-independent graphics output model that processes graphical function calls from a Windows-based application and passes those calls to the appropriate device driver. The driver performs the hardware-specific functions that generate output. By acting as a buffer between applications and output devices, the GDI presents a device-independent view for the application while interacting in a device-dependent format with the device.

Application developers use the functionality of the GDI to display images, to draw controls, shapes, and text, and to create and use pens, brushes, and fonts. The Windows Foundation Classes for Java (WFC) Graphics object coordinates with other WFC objects, such as the Pen, Font, and Brush objects, to encapsulate these capabilities as Java-based objects.

In the WFC environment, graphical output occurs through the Graphics object. After creating or retrieving a Graphics object, you associate other graphics-based objects, such as fonts, pens, and brushes with the object, and then use the object's numerous drawing methods to render output to the display. For example, to draw lines with a specific appearance, you use the Graphics object's setPen method to specify the pen that the object will use for drawing, and then use the object’s drawLine method to render the lines. You can modify these associations as often as you want.

This topic contains the following sections:

Creating a Graphics Object

Retrieving a Graphics Object

Graphics Object Scope

Maintaining the Bounding Rectangle

Performing Handle-Based Operations

The Graphics Object Coordinate System

Drawing Text

Using the Font Object

Using Pens

Using Brushes

Drawing Bitmaps

Raster Operations

Drawing Shapes


Creating a Graphics Object

WFC provides the following ways to create a Graphics object:

  • Explicit object creation. You can create a Graphics object explicitly by calling the createGraphics method on any object that extends the Control class.

  • Implicit object creation. The Bitmap and Metafile objects support implicit Graphics object creation through a getGraphics method.


Explicit Graphics Object Creation

All classes that extend the Control class support the createGraphics method, which you can use to create a Graphics object instance. The following code fragment demonstrates how to call this method from within a Form-derived class.

Graphics g = this.createGraphics();

Another approach to explicit Graphics object creation involves using a handle to a Microsoft® Win32® device context (HDC). Generally, the only case in which you create a Graphics object in this way is when you have called a Win32 method that returns an HDC.

If you simply need graphical capabilities that are not supported natively in the Graphics object, you can use the object’s getHandle method to retrieve the handle to a Win32 device context and can pass that handle transparently to the appropriate Win32 method.

If you create a Graphics object based on a previously existing handle, the Graphics object doesn't assume ownership of the handle; after you have used the object, you are responsible for freeing the handle using the appropriate Win32 function. If you use the Graphics object’s getHandle method to retrieve the object’s underlying handle, the object retains ownership of that handle and you should not try to free it.

For more information on Win32 handles and the Graphics object, see Handle-Based Operations.


Implicit Graphics Object Creation

The Bitmap and Metafile objects support implicit Graphics object creation through their getGraphics method. In the following code fragment, the Bitmap object’s getGraphics method is used to create a Graphics object that can be used to draw to the bitmap’s surface.

Bitmap bmp = new Bitmap("c:\\MyImage.bmp");
Graphics gr = bmp.getGraphics();

The first time that you call getGraphics through an object, the object creates a new Graphics object instance and returns it. Subsequent calls to getGraphics through the same object results in the return of the object created through the original call.

Additionally, when you call drawing methods through a Graphics object created through an object’s getGraphics method, the methods apply to the object through which they were created.


Retrieving a Graphics Object

Within a form or control’s paint event, you can retrieve and use a Graphics object instance. The paint event handler takes a PaintEvent object as a parameter, and this object contains a public graphics member. This member is a valid Graphics object instance, which you call as follows:

protected void onPaint(PaintEvent e){
   e.graphics.drawString("Hello, World", new Point(10, 10));
}

For information on how to create a Graphics object outside the paint event, see Explicit Graphics Object Creation and Implicit Graphics Object Creation.


Graphics Object Scope

The Graphics object has method scope. This means that when a method in which you use the Graphics object returns, the object’s dispose method is called automatically, freeing all resources that the object has allocated. After dispose has been called, attempts to use the object result in a run-time exception.

If you declare an instance of the Graphics object at the class level, you should use the Form object’s createGraphics method to initialize that object in every method that uses it.

Example

Public class Form1 extends Form{

   Graphics g  = new Graphics();

   Private void Form1_resize(Object sender, Event e){

         // Initialize object instance.
         g = this.createGraphics();

         // Dispose automatically called.
   }

   private void Form1_click(Object sender, Event e){

         // Initialize object instance.

         g = this.createGraphics();

         // Dispose method automatically called.
   }

}

Although the dispose method is called automatically, it is good practice to call it explicitly at the end of routines that use the Graphics object. This is particularly important on the Microsoft® Windows® 95 platform because of a system limitation on the number of device contexts that can be allocated.


Maintaining the Bounding Rectangle

The area of a window in which you can draw is referred to as the window’s client area. Within this area, a bounding rectangle defines the invisible rectangular region in which the Graphics object draws, and can include the window’s entire client area.

When a window loses, and then regains focus, the part of the bounding rectangle covered by some other object does not automatically redisplay the items that were previously rendered to it.

To ensure correct display, you must manage the repainting of your form or control. The paint event handler is the place in your Form class code in which such management typically takes place. Within this handler, you restore the bounding rectangle to its proper state.

The following example creates a Bitmap object at the class level, then it uses the paint event handler to redraw the Bitmap. Each time the client area of the form becomes invalid, Windows invokes this handler, and the image is repainted to the form.

Example

Bitmap bmp = new Bitmap("c:\\MyImage.bmp");

protected void onPaint(PaintEvent e){
    e.graphics.drawImage(bmp, new Point(0, 0));
}

When your form is initially displayed, and each time it regains focus, the paint event handler is automatically invoked. However, if your form supports resizing, a change in the form’s dimensions does not automatically trigger a repaint. Instead, you must add a resize handler to the Form-derived class and then call the object’s invalidate method from within this handler. A call to invalidate triggers the form’s paint event handler.

protected void onResize(Event e){
    this.invalidate();
}


Performing Handle-Based Operations

A handle is a unique number with which some element of the operating system is identified to the computer. For example, every window on your desktop has a unique handle that enables the computer to distinguish it from other windows. Every device context, brush, pen, and font also has a unique handle.

To maintain optimal compatibility with the Win32 API, the Graphics, Pen, Brush, and Font objects support handle-based operations. For example, if you use the Win32 CreatePen function to create a pen, this function returns a handle. You can then pass this handle to the Pen object constructor, and the object is created based on the characteristics of that Win32 pen.

Even if you do not create a Pen, Brush, or Font object based on a handle that you allocate, you can retrieve the handle on which a Pen, Brush, or Font object is based. Each of these objects supports both a copyHandle and a getHandle method, and once you’ve used these methods to duplicate or retrieve the object’s handle, you can pass that handle to any Win32 function that is intended to take such a handle as a parameter.

A few important rules to keep in mind when performing handle-based operations with the Graphics object are as follows:

  • If you create an object based on a handle that you have previously allocated using a Win32 method, the object does not assume ownership of that handle. For example, if you use the Win32 GetDC method to retrieve a form’s device context handle (HDC), then create a Graphics object based on that HDC, then you own the handle. This means that when the Graphics object’s dispose method is called, the handle is not freed in memory. Instead, you must use the appropriate Win32 routine to destroy the handle.

    The following example illustrates appropriate handle management. This example uses the Win32 GetDC to retrieve the handle to the form’s device context, and then creates a Graphics object based on that handle. After using the Graphics object to draw a line on the form, the Graphics object’s dispose method is used to destroy the Graphics object, and the Win32 ReleaseDC routine is used to free the device context handle allocated by GetDC.

    Example

    // Import the com.ms.wfc.Win32.Windows package.
import com.ms.wfc.win32.Windows;

int hDC = Windows.GetDC(this.getHandle());
Graphics g = new Graphics(hDC);

g.drawLine(new Point(0,0), new Point(100, 0));
g.dispose();

Windows.ReleaseDC(hDC);

Note that while this example uses the handle to a device context, the principle illustrated here applies to pens, brushes, fonts, and bitmaps.

  • Most graphical objects support a copyHandle method through which you can duplicate the handle on which the object is based. If you use the copyHandle method to duplicate an object’s handle, you are responsible for freeing the handle.

    •

  • Most graphical objects also support a getHandle method, which returns the handle that the object is based on (as opposed to a copy of that handle). This method is intended to enable support compatibility between Graphics object methods and Win32 graphics routines.

    Handles retrieved through the getHandle method are not copies of an object’s underlying handle. You should therefore never attempt to free handles retrieved through getHandle. Such handles are freed when the object is disposed.
    •


The Graphics Object Coordinate System

A large number of the methods supported by the Graphics object depend on numerical coordinates. Such coordinates can be specified in a Rectangle object, which specifies the area in which an operation is to occur, or in a Point object, which specifies the x- and y- coordinates at which the operation occurs.

The term coordinate system identifies how the coordinates specified in such objects map to the display or to 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 that you can associate a Graphics object with 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 object increase, the text (or bitmap or control) proceeds to the right (horizontally) and down (vertically).

To associate a coordinate system with the Graphics object, use the setCoordinateSystem method, as follows:

Graphics gr = this.createGraphics();
gr.setCoordinateSystem(CoordinateSystem.ANISOTROPIC);

The following table lists the coordinate systems that you can associate with the Graphics object and describes the direction in which drawing proceeds as the x and y axes defined in a Point object increase.

Coordinate System | Increasing x-axis | Increasing y-axis
CoordinateSystem.TEXT | Right. | Down.
CoordinateSystem.LOMETRIC | Right. | Up.
CoordinateSystem.HIMETRIC | Right. | Up.
CoordinateSystem.LOENGLISH | Right. | Up.
CoordinateSystem.HIENGLISH | Right. | Up.
CoordinateSystem.TWIPS | Right. | Up.
CoordinateSystem.ISOTROPIC | User-defined. | User-defined.
CoordinateSystem.ANISOTROPIC | User-defined. | User-defined.

For more information, see:

Setting the Coordinate Origin

Mapping Logical Coordinates to Device Coordinates


Setting the Coordinate Origin

The coordinate origin identifies the location that coordinates are measured from.

For example, if you create a Graphics object through your application’s main form, the Graphics object’s coordinate system is CoordinateSystem.TEXT and graphical coordinates are measured from the upper-left corner (0,0) of the form.

However, if you use a user-defined coordinate system, such as CoordinateSystem.ANISOTROPIC or CoordinateSystem.ISOTROPIC, you can specify the point from which coordinates are measured (both for the page and the device), using the Graphics object’s setCoordinateOrigin method. The following example sets the coordinate system to CoordinateSystem.ANISOTROPIC, and then sets the coordinate origin for both the page and device at (20,20). The call to drawLine that appears later in the code measures from the coordinate origin. Thus, the line will end at (100,100) from the coordinate origin (10,10).

Example

   private void Form1_paint(Object source, PaintEvent e)
   {
   // Set the coordinate system.

   e.graphics.setCoordinateSystem(CoordinateSystem.ANISOTROPIC);
   e.graphics.setCoordinateOrigin(new Point(20,20), new Point(20,20));
   e.graphics.setCoordinateScale(new Point(1,1), new Point(1,1));
   e.graphics.drawLine(new Point(0,0), new Point(100,100));

   }


Mapping Logical Coordinates to Device Coordinates

Microsoft® Windows® provides built-in support for mapping page coordinates to a device, such as a printer or display.

For most of the coordinate systems defined by Windows, the system itself performs the conversion. For example, if you associate a Graphics object with the CooordinateSystem.HIMETRIC coordinate system, each logical unit on the object translates to .001 of an inch on the device.

However, when using the user-defined ANISOTROPIC and ISOTROPIC coordinate systems, you must use the setCoordinateScale method to tell the system how to perform the conversion, as in the following example:

Graphics g = this.createGraphics();
g.setCoordinateSystem(CoordinateSystem.ANISOTROPIC);
g.setCoordinateScale(new Point(1,1), new Point(2,2));

The call to setCoordinateScale in this example instructs the system to convert a single logical horizontal and vertical unit to two horizontal and vertical device units.


Drawing Text

The Graphics object’s drawString method supports the output of text to the control to which the object belongs. This method writes the text to the location that you specify, as in the following example.

Graphics g = this.createGraphics();
g.drawString("Hello, World", new Point(0, 0));

The visual result of this call depends upon many factors, including the Graphics object’s current text color, background color, font settings, and coordinate systems.

For information on how to set the text color, see Setting Text Color. For information on associating fonts with the Graphics object, see Using the Font Object. For information about coordinate systems, see The Graphics Object Coordinate System.


Setting Text Color

To set the text and background color of the text, call the Graphics object's setBackColor and setTextColor before calling drawString.

Example

// Set the text to white, the background to black.

g.setTextColor(new Color(0, 0, 0));

g.setBackColor(new Color(255, 255, 255));

// Draw the text.

The setBackColor method affects only the background color of text. To set the background or fill color for other objects, such as polygons and lines, use the setBrush and setPen methods, respectively.


Using the Font Object

A font is a collection of characters and symbols that share a common design. The major elements of a font include its typeface, style, and size.

In WFC, Windows fonts are encapsulated in the Font object. You can use this object in combination with other font-related objects to define a limitless variety of fonts for display on a Graphics object.

The following table lists the font-related classes supported by WFC.

Class | Description
FontDescriptor | Provides information about the font that underlies a Font object.
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 | Defines a font’s pitch.
FontSize | Defines a group of constants that represent the units in which font sizes can be specified.
FontType | Defines a group of constants that represent the devices to which the font will be rendered.
FontWeight | Defines constants that represent the different weights that you can associate with a font.

For more information, see:

Creating a Font Object

Setting the Font on a Graphics Object

Enumerating Fonts


Creating a Font Object

Creating a Font object can be very simple or complex, depending on the granularity with which you want to define the font. The following code fragment illustrates one of the simple approaches to Font object creation:

Font font = new Font("Times New Roman", 26);

This example uses a Font object constructor that requires only two items of information: the font name and size. When creating a Font object, you can also specify the font’s family, its type, its weight, its orientation, and whether the font is boldfaced, italicized, underlined, or strikeout. However, once you’ve created a Font object, you cannot modify the object’s attributes.


Setting the Font on a Graphics Object

The Graphics object supports the setFont method, which associates a font with the object. After you associate a Font object with the Graphics object, all text drawn within the Graphics object’s bounding rectangle is drawn using that font.

The following example illustrates the process of setting the background color of the Graphics object to white, the text color to black, and the font to 26-point Times New Roman. The text is drawn to the display at a specified position.

Example

Graphics g = this.createGraphics();

g.setFont(new Font("Times New Roman", 26));
g.setBackColor(new Color(255, 255, 255));
g.setTextColor(new Color(0, 0, 0));
g.drawString("Hello, World", 0, 0);


Enumerating Fonts

In some instances, an application must be able to enumerate and retrieve detailed information about the available fonts, and to select the font most appropriate for a particular operation.

The WFC FontDescriptor object describes a font, including the font's name, height, orientation, and so on. For a detailed description of all the fonts available on your system, use the Graphics object's getFontDescriptors method. This method returns an array of FontDescriptor objects, in which each element in the array describes a font.

The following example illustrates how to use the getFontDescriptors method. This example retrieves an array of available fonts, and then inserts a unique list of the font names into a list box.

Example

Graphics g = this.createGraphics();

// Create the array.
FontDescriptor rgFonts[] = g.getFontDescriptors();

for(int i = 0; i < rgFonts.length; i++){

    if(listBox1.findString(rgFonts[i].fullName == -1){

        listBox1.addItem(rgFonts[i].fullName);
    }
}


Using Pens

A pen is a graphics tool that an application for Microsoft Windows uses to draw lines and curves. Applications that draw use pens to draw freehand lines, straight lines, and curves. Computer-aided design (CAD) applications use pens to draw visible lines, hidden lines, section lines, center lines, and so on. Word processing and desktop publishing applications use pens to draw borders and rules. Spreadsheet applications use pens to designate trends in graphs and to outline bar graphs and pie charts.

Each pen consists of three attributes: style, width, and color. While no limits are imposed on the width and color of a pen, the pen's style must be supported by the operating system.

For more information, see:

WFC Pen Object

Setting the Pen on a Graphics Object


WFC Pen Object

The capabilities of Win32 pens are encapsulated in the WFC Pen and PenStyle objects. The following code fragment demonstrates how to create a Pen object.

Pen p = new Pen(PenStyle.DASH);

The constant that you pass to the Pen object constructor is a pen style. The seven built-in pen styles supported on Windows are each represented by a constant defined in the PenStyle class. The PenStyle class is an enumeration class, which means that it defines a method (valid) that determines whether a value that you specify is a valid member of the PenStyle class.

The following table lists the PenStyle constants.

Constant | Description
PenStyle.DASH | Represents a dashed pen.
PenStyle.DOT | Represents a dotted pen.
PenStyle.DASHDOT | Represents a pen of alternating dashes and dots.
PenStyle.DASHDOTDOT | Represents a pen of alternating dashes and double dots.
PenStyle.INSIDEFRAME | Represents a pen that draws a line inside the frame of closed shapes produced by the Graphics object’s output functions that specify a bounding rectangle (for example, drawRect, drawPie, and drawChord).
PenStyle.NULL | Represents a null pen.
PenStyle.SOLID | Represents a solid pen.

In addition, the Pen object includes a group of public members that you can use to specify the kind of pen you want to create. Each of these members is a Pen object, and is designed to enable you to simulate various native features of the Windows user-interface.

For example, the Pen class defines a WINDOWFRAME member. When you create a Pen of type WINDOWFRAME, the lines that you draw using this pen look identical to the frame of an active window.

Pen pen = Pen.WINDOWFRAME;

The following table lists the Pen objects defined as public members of the Pen class.

Object | Description
Pen.ACTIVECAPTIONTEXT | Creates a pen the color of the active window's caption text.
Pen.CONTROLTEXT | Represents a pen the color of the text on a control.
Pen.GRAYTEXT | Represents a pen the color of disabled text.
Pen.HIGHLIGHTTEXT | Represents a pen the color of highlighted text.
Pen.INACTIVECAPTIONTEXT | Represents a pen the color of the caption text of an inactive window.
Pen.INFOTEXT | Represents a pen the color of the information ToolTip’s text.
Pen.MENUTEXT | Represents a pen the color of menu text.
Pen.NULL | Represents a null pen. A null pen does nothing.
Pen.WINDOWFRAME | Represents a pen the color of an active window’s frame.
Pen.WINDOWTEXT | Represents a pen the color of an active window’s text.

Note that when you use a Pen based on a system constant, such as the color of an active window’s text, a change in the system setting that the Pen reflects results in a change to the pen.


Setting the Pen on a Graphics Object

The Pen object itself contains no coloring or drawing capability. It only describes a subset of the capabilities of the GDI. Before you use a Pen to draw on a form, you associate the Pen with a Graphics object using the Graphics object's setPen method.

Graphics g = this.createGraphics();
g.setPen(new Pen(PenStyle.DASH));

After you associate a Pen with a Graphics object, all lines drawn within the Graphics object's bounding rectangle are drawn using that pen. In addition, you can call the setPen method any number of times on the same Graphics object.

The following example demonstrates how the Pen object works with the line-drawing capabilities of the Graphics object. In this example, the Pen styles defined in the Pen object are stored in an array of integers. Within the class's paint event handler, a for loop is used to iterate through this array of pen styles, drawing a single line using each style.

Example

public class Form1 extends Form
{

int [] rgStyles = { PenStyle.DASH, PenStyle.DASHDOT, PenStyle.DASHDOTDOT,
                  PenStyle.DOT, PenStyle.INSIDEFRAME, PenStyle.SOLID };

   protected void onPaint(PaintEvent e)
   {
      Rectangle rc = this.getClientRect();

      rc.y += 10;

      for(int i = 0; i < rgStyles.length; i++){

         e.graphics.setPen(new Pen(Color.BLACK, i));
         e.graphics.drawLine(new Point(0, rc.y),
                        new Point(rc.width, rc.y));

         rc.y += 10;
      }
   }

// The remainder of the Form1 class would follow.


Using Brushes

A brush is a graphics tool that a Win32-based application uses to paint the interior of polygons, ellipses, and paths. Drawing applications use brushes to paint shapes; word processing applications use brushes to paint rules; computer-aided design (CAD) applications use brushes to paint the interiors of cross-section views; and spreadsheet applications use brushes to paint the sections of pie charts and the bars in bar graphs.

There are two types of brushes: logical and physical. A logical brush is one that you define in code as the ideal combination of colors, patterns (or both) that an application should use to paint shapes. A physical brush is one that a device driver creates based on your logical-brush definition.

For more information, see:

Brush Origin

Logical Brush Types

WFC Brush Object

Creating a Brush Object

Setting the Brush on the Graphics Object

A Brush Object Example


Brush Origin

When an application calls a drawing function to paint a shape, Windows positions a brush at the start of the paint operation and maps a pixel in the brush bitmap to the window origin of the client area. (The window origin is the upper-left corner of the window's client area.) The coordinates of the pixel that Windows maps are called the brush origin.

The default brush origin is located in the upper-left corner of the brush bitmap at the coordinates (0,0). Windows then copies the brush across the client area, forming a pattern that is as tall as the bitmap. The copy operation continues, row by row, until the entire client area is filled. However, the brush pattern is visible only within the boundaries of the specified shape. (Here, the term bitmap is used in its most literal sense—as an arrangement of bits—and does not refer exclusively to bits stored in an image file).

There are instances when the default brush origin should not be used. For example, it may be necessary for an application to use the same brush to paint the backgrounds of its parent and child windows and blend a child window's background with that of the parent window.


Logical Brush Types

Logical brushes come in three varieties: solid, pattern, and hatched.

A solid brush consists of a color or pattern defined by some element of the Windows user interface (for example, you can paint a shape with the color and pattern conventionally used by Windows to display disabled buttons).

A hatched brush consists of a combination of a color and of one of the six patterns defined by Win32.

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.


WFC Brush Object

The capabilities of Win32 brushes are encapsulated in the WFC Brush and BrushStyle objects, objects that you coordinate to create solid, pattern, and hatched brushes.

The Brush object defines a group of public final members, each of which is a Brush object representing a solid brush. The BrushStyle class represents hatched brushes as a group of integer constants, each of which represents a different brush style.

The following table lists the Brush object constants that represent solid brushes.

Constant | Description
Brush.ACTIVEBORDER | Represents a Brush object the color of the active window border.
Brush.ACTIVECAPTION | Represents a Brush object the color of the active caption bar.
Brush.APPWORKSPACE | Represents a Brush object that is the color of the application workspace window.
Brush.CONTROL | Represents a Brush object that is the color of controls.
Brush.CONTROLDARK | Represents a Brush object that is the color of the shadow portion of a 3-D element.
Brush.CONTROLDARKDARK | Represents a Brush object that is the color of the darkest portion of a 3-D element.
Brush.CONTROLLIGHT | Represents a Brush object that is the color of the highlighted portion of a 3-D element.
Brush.CONTROLLIGHTLIGHT | Represents a Brush object that is the color of the lightest part of a 3-D element.
Brush.DESKTOP | Represents a Brush object that is the current color of the desktop.
Brush.HALFTONE | Represents a Brush object that is the color of a standard halftone brush.
Brush.HIGHLIGHT | Represents a Brush object that is the color of the background of highlighted elements.
Brush.HOLLOW | Represents a null brush, which paints nothing.
Brush.HOTTRACK | Represents a Brush object that is the color used to indicate hot-tracking.
Brush.INACTIVEBORDER | Represents a Brush object that is the color of an inactive window border.
Brush.INACTIVECAPTION | Represents a Brush object that is the color of an inactive caption bar.
Brush.INFO | Represents a Brush object that is the color of the background of an information ToolTip.
Brush.MENU | Represents a Brush object that is the color of the menu background.
Brush.NULL | Represents a null brush.
Brush.SCROLLBAR | Represents a Brush object that is the color of a scrollbar background.
Brush.WINDOW | Represents a Brush object that is the color of the window background.

The following table lists the BrushStyle constants that represent hatched brushes.

Constant | Description
BrushStyle.BACKWARDDIAGONAL | Represents a backward diagonal brush. Parallel lines run from the lower-left corner of the brush origin to the upper-right corner.
BrushStyle.DIAGONALCROSS | Represents a cross-hatched brush.
BrushStyle.FORWARDDIAGONAL | Represents a forward diagonal brush. Parallel lines run from the lower-right corner of the brush origin to the upper-left corner.
BrushStyle.HOLLOW | Represents a hollow brush. A hollow brush is identical to a null brush.
BrushStyle.HORIZONTAL | Represents pattern consisting of evenly spaced horizontal lines.
BrushStyle.PATTERN | Represents a pattern brush.
BrushStyle.SOLID | Represents a solid brush.
BrushStyle.VERTICAL | Represents pattern consisting of evenly spaced vertical lines.


Creating a Brush Object

How you create a Brush object depends on the type of brush needed. Because solid brushes are Brush objects, you create a solid brush as follows:

Brush br = Brush.BLACK;

A pattern brush is represented by the Brush object as an integer constant and is created as follows:

Brush br = new Brush(Color.BLACK, BrushStyle.FORWARDDIAGONAL);

The following code fragment demonstrates one way to create a brush based on a bitmap.

Brush bmpBrush = new Brush(new Bitmap("c:\\myBitmap.bmp"));

This example assumes that the bitmap on which you want to base your brush pattern is stored in a file on disk. However, you can also use the Bitmap object’s createBitmap method to define bitmaps at run time, and can use the bitmap you define as the basis for the brush pattern.


Setting the Brush on the Graphics Object

Like the Pen and Font objects, the Brush object contains no coloring or drawing capability. It expresses a subset of the capabilities of the GDI. Before a brush can be used to fill surfaces, it must be associated with a Graphics object using the setBrush method.

Example

protected void onPaint(PaintEvent e)
{

 // Create a forward diagonal brush, and associate it with the
    // object.
    Brush br = new Brush(Color.BLACK, BrushStyle.FORWARDDIAGONAL);
    e.graphics.setBrush(br);

}

After you associate a Brush object with the Graphics object, all polygons that you draw using that Graphics object instance are filled with the associated brush. You can call setBrush as often as you want to associate a new brush with the Graphics object.


A Brush Object Example

A custom brush is one based on a bitmap that you load from a file or create in memory. The CustomBrush sample application demonstrates how to create and use custom brushes.

The CustomBrush application consists of two panels and two buttons. The first of the panels (panelGrid) consists of 64 squares. When the user clicks on one of these squares, the application registers the fact that the square has been clicked, paints the square black, and performs a bitwise operation on one of the members of an array of short integers. The integer that is modified depends on which square was clicked.

When the user clicks the Test button, the CustomBrush application creates a bitmap based on the array of short integers, creates a brush based on that bitmap, and then uses that brush to paint the panel (panelRect) that appears above the Test button.

Upon application startup, the CustomBrush application performs the following tasks:

  • Calls the user-defined getRects method to create an array of 64 Rectangle objects, and draws these rectangles to the application’s grid panel (panelGrid).

  • Declares an array of short integers (bBrushBits). The value of the integers stored in this array will eventually form the basis on which a bitmap is created. When the user clicks the Test button, this bitmap is used to create the brush that paints the panel that appears above the Test button.

  • Declares and initializes an array of boolean variables (rgStates) to false. This array is intended to track the state of each of the rectangles in the panelGrid. When the user clicks on one of the rectangles in the panelGrid, the corresponding variable in this array is set to true.

Example

public class Form1 extends Form
{

// Rectangles into which to divide the panel.
Rectangle [] rgRects = new Rectangle[64];

// Tracks the state of the rectangles.
boolean [] rgStates = new boolean[64];
int [] bBrushBits = new int[8];

public Form1()
{
   // Set the state array to an initial value of false.

   for(int i = 0; i < rgStates.length; i++){

      rgStates[i] = false;

   }

   // Initialize the form.

   initForm();

   // Divide the panel into 64 rectangles and paint the form.

   rgRects = getRects(panelGrid.getClientRect(), 8, 8);
   this.invalidate();

}

//
// This method divides a specified rectangular area into the specified
// number of subrectangles (down and across), and returns an array
// containing the subrectangles.
//

private Rectangle [] getRects(Rectangle rcClient, int nAcross, int nDown){

int deltaX, deltaY;
int x, y, right, bottom;
int i;

Rectangle rgRects[] = new Rectangle[nAcross * nDown];

// Store the right and bottom of the rectangle.

right = rcClient.getRight();
bottom = rcClient.getBottom();

// Determine the height and width of each rectangle.

deltaX = (right - rcClient.x) / nAcross;
deltaY = (bottom - rcClient.y) / nDown;

// Initialize the array of cell rectangles.

for(y = rcClient.y, i = 0; y < bottom; y += deltaY){

   for(x = rcClient.x; x < (right - nAcross) && i < (nAcross * nDown);
      x += deltaX, i++){

      rgRects[i] = new Rectangle(x, y, deltaX, deltaY);

   }
}

return rgRects;

}

When the grid panel’s paint event handler is invoked, it uses the dimensions stored in the application’s Rectangle array (rgRects) and the states stored in the class-level boolean array (rgStates) to draw a grid. If the boolean value corresponding to a given rectangle is true, the rectangle is painted black. Otherwise, it is painted with a null brush. This enables the user to determine the appearance of the brush that is eventually created based on the pattern of the rectangles in the grid panel:

private void panelGrid_paint(Object source, PaintEvent e)
{

e.graphics.setPen(new Pen(Color.BLACK, PenStyle.SOLID, 1));

// Draw the grid to reflect the current state of the
// squares.

for(int i = 0; i < rgRects.length; i++){

   if(rgStates[i] == true){

      // If the square has been previously clicked, fill it.

      e.graphics.setBrush(new Brush(Color.BLACK));

   }else{

      e.graphics.setBrush(Brush.NULL);

   }

   e.graphics.drawRect(rgRects[i]);

   }

}

Each time the user clicks on one of the rectangles in the grid panel, the panel’s click event is fired. Within the grid panel’s click event handler, the application determines which rectangle was clicked, sets the corresponding boolean state variable to true, and calls panelGrid.invalidate to force a repaint. Additionally, the application performs a bitwise operation on the appropriate member of the array of bits stored in the class-level bBrushBits variable.

private void panelGrid_mouseDown(Object source, MouseEvent e)
{

   Graphics gr = this.createGraphics();
   gr.setBrush(new Brush(Color.BLACK));
   Integer nBit = new Integer(0);

   // Determine which cell was clicked.

   for(int i = 0; i < 64; i++){

      Rectangle rc = new Rectangle(rgRects[i].x,
                              rgRects[i].y, rgRects[i].height,
                              rgRects[i].width);

      if(rc.contains(new Point(e.x, e.y))){

         // Set the appropriate boolean state variable.

         rgStates[i] = true;

         // Perform a bitwise NOT operation on the appropriate
         // integer in the array of shorts on which we’ll base
         // our bitmap.

         if(i % 8 == 0)
            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x80;
         if(i % 8 == 1)
            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x40;
         if(i % 8 == 2)
            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x20;
         if(i % 8 == 3)
            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x10;
         if(i % 8 == 4)
            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x08;
         if(i % 8 == 5)
            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x04;
         if(i % 8 == 6)
            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x02;
         if(i % 8 == 7)
            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x01;

         break;

         }
      }

      // Repaint the grid.

      panelGrid.invalidate();

   }

Finally, when the user clicks the Test button, the test button’s click event handler forces a repaint of the panel (panelRect) that appears above the Test button by calling panelRect.invalidate:

private void btnTest_click(Object source, Event e)
{
   panelRect.invalidate();
}

Within the panelRect paint handler, the application creates a bitmap based on the array of short integers (bBrushBits), creates a brush based on the bitmap, and paints the panel (panelRect) that appears above the Test button.

private void panelRect_paint(Object source, PaintEvent e)
{
   short [] rgShorts = new short[8];

   for(int i = 0; i < bBrushBits.length; i++){
      rgShorts[i] = (short) bBrushBits[i];
   }

   e.graphics.setBrush(new Brush(new Bitmap(8,8,1,1,rgShorts)));
   e.graphics.fill(panelRect.getClientRect());

}


Drawing Bitmaps

A bitmap is a drawable surface. This surface can be used to display pens, brushes, or images, including Windows bitmaps, metafiles, .gif, and .jpg images.

The Bitmap object supports creating and loading bitmaps. You can use this object to load bitmap images from files, streams, or resources, or you can use it to create bitmaps in memory. In addition, the Bitmap object supports defining transparent colors within a bitmap.

After creating a Bitmap object, you use the Graphics object's drawImage method to render a Bitmap object to the display.

The following code fragment creates a new Bitmap object, and then uses the Form class's createGraphics method to create the Graphics object for drawing the image.

Example

Bitmap bmp = new Bitmap("c:\\MyImage.bmp");
Graphics g = this.createGraphics();

g.drawImage(bmp, new Point(10, 10));

For more information, see:

Shrinking and Expanding Images

Rendering Images Transparently


Shrinking and Expanding Images

All the image objects supported by WFC (Metafile, Icon, Bitmap, and Cursor) support the drawStretchTo and drawTo methods. All image rendering performed by the Graphics object occurs through these methods. When you call the Graphics object’s drawImage method, the object determines whether to call the drawStretchTo or the drawTo method on the image object that you pass the method.

The drawStretchTo method expands or shrinks an image to fit within a specified rectangular area. The drawTo method renders an image to a specified area also, but if the image is too large for the target area, the drawTo method clips it. In addition, both of these methods support drawing sections of an image to a specified section of the Graphics object’s bounding rectangle.

You cannot call the drawStretchTo or drawTo methods directly; they are always defined as protected methods in WFC image classes. To determine which of these methods is called, you call a version of the drawImage method that takes a Boolean scale parameter. The following is one such method defined by the Graphics object.

public final void drawImage( Image i, Rectangle r, boolean scale )

If the scale parameter is true, the image is stretched or shrunk to fit the clipping rectangle; otherwise, the image is clipped.


Rendering Images Transparently

The Bitmap object supports the transparent rendering of one or more colors in an image.

If you need to render a single color transparently, use the setTransparentColor and setTransparent methods. The setTransparentColor method takes a Color object parameter that specifies the bitmap color to be rendered transparently. The setTransparent method takes a Boolean value that specifies whether the designated transparent color should be rendered.

For example, the following code fragment designates black as the transparent color. When the Graphics object’s drawImage method is called to draw the image, the black pixels in the image are not rendered.

Example

   protected void onPaint(PaintEvent e)
   {

      Bitmap bmp = new Bitmap("c:\\MyImage.bmp");
      Bmp.setTransparentColor(Color.BLACK);
      Bmp.setTransparent(false);
      e.graphics.drawImage(bmp, new Point(0,0));

   }

You can also achieve transparency by creating a Bitmap object based on two bitmasks, one of which is color and the other monochrome. In the color mask, each part of the bitmap to be drawn transparently should be black. In the monochrome mask, each part to be drawn transparently should be white.


Raster Operations

A raster operation applies a logical operation to the display of a GDI primitive, such as a pen, brush, image, or shape to achieve a visual effect. Raster operations that you can perform using the Graphics object are defined in the RasterOp object. When you review the methods supported by the Graphics object, you'll see that for each basic operation, such as the drawing of lines or the display of images, there's a method that takes a RasterOp as a parameter.

In their simplest incarnations, the drawing methods the Graphics object supports merely writes or copies pixels to some area of the display, overwriting what's currently displayed. Add raster operations to the equation and this overwrite becomes more complex.

Suppose, for example, that you want to draw a black rectangle to an area currently covered by an image, but you want to logically combine the black pixels with their corresponding pixels in the target image and to write the result to the display. Raster operations make such combinations possible.

The variations on the logic that the RasterOps object supports are too numerous to be covered thoroughly in this document. The following statements, however, demonstrate the basic syntax of a call using a RasterOps object. These statements set the background color of a form, and then draw a line that represents a color inversion of the background color.

Example

protected void onPaint(PaintEvent e)
{
this.setBackColor(new Color(255, 255, 255);

e.graphics.drawLine(new Point(10, 10), new Point(100, 10),

RasterOp.TARGET.invert());
}


Drawing Shapes

The Graphics object supports the drawing of lines, rectangles, chords, arcs, arc angles, and Bezier splines.

For more information, see:

Lines

Rectangles

Chords

Arcs

Arc Angles

Bezier Splines


Lines

A line is a set of highlighted pixels on a display, identified by two points: a starting point and an ending point. In Windows, the pixel located at the starting point is always included in the line, and the pixel located at the ending point is always excluded (these lines are sometimes called inclusive-exclusive).

An application can draw a single line by calling the Graphics object’s drawLine method. This method takes two Point parameters, which specify the start and end of the line.

Example

protected void onPaint(PaintEvent e){

   Rectangle rcClient = this.getClientRect();

   // Draw lines that divide the screen area equally into four squares.

   e.graphics.drawLine(new Point(rcClient.x, rcClient.height / 2),
                     new Point(rcClient.width, rcClient.height / 2));

   e.graphics.drawLine(new Point(rcClient.width / 2, rcClient.y),
                     new Point(rcClient.width / 2, rcClient.height));
}


Rectangles

Applications written for Microsoft® Windows® use rectangles to specify rectangular areas on the screen or in a window. Rectangles are used to describe the client area of a window, areas of the screen that need repaints, and areas for displaying formatted text. Your applications can also use rectangles to fill, frame, or invert a portion of the client area with a given brush, and to retrieve the coordinates of a window or the window's client area.

The dimensions of rectangular regions are described in the WFC Rectangle object. This object consists of x, y, height, and width integers that describe the Rectangle's screen position and dimensions. In addition, you can use the object's getRight and getBottom methods to retrieve the screen position of its right and bottom sides.

For more information, see Rectangle Operations and A Rectangle Example.

Rectangle Operations

The Rectangle object provides a number of methods for working with rectangles. The object's equals method determines whether two Rectangle objects are identical—that is, whether they have the same coordinates.

The inflateRect method increases or decreases the width or height of a rectangle, or both. It can add or remove width from both ends of the rectangle; it can add or remove height from both the top and bottom of the rectangle.

The overloaded contains method enables you to determine whether the area described by one rectangle exists within the area described by another, or to determine whether a given point exists within a rectangle.

The intersects and intersectsWith methods determine whether two Rectangle object’s intersect.

A Rectangle Example

The example in this section illustrates how to divide areas of an application’s client area into subrectangles, and how to work within these regions.

When the application starts, it divides the main form’s client area into 16-by-16 subregions, and displays every shade of a given color within those rectangular regions. To modify the number of rectangles displayed across and down the display, you use the Dimensions menu item to display a dialog box in which you specify the new number of rectangles you’d like to see displayed.

The method that divides the screen into Rectangle objects is given in the following example. This method, getRects, takes three parameters: a rectangle that specifies the area to be divided, and two integers, which identify the number of cells to draw across and down, respectively. The method returns an array of rectangles that contain the appropriate coordinates.

Example

private Rectangle[] getRects(Rectangle rcClient, int nDown, int nAcross){

   int deltaX, deltaY;   // The height and width of each cell.
   int x, y;
   int i;

   Rectangle rgRects[] = new Rectangle[nDown * nAcross];

   // Determine the height and width of each Rectangle.

   deltaX = (rcClient.getRight() – rcClient.x) / nAcross;
   deltaY = (rcClient.getBottom() – rcClient.y) / nDown;

   // Create and initialize the Rectangle array.

   for(y = rcClient.y, i = 0; y < rcClient.getBottom(); y += deltaY){
      for(x = rcClient.x; x < (rcClient.getRight() – nAcross) &&
            i < (nAcross * nDown); x += deltaX, i++){

         rgRects[i] = new Rectangle(x, y, deltaX, deltaY);
      }
   }

   // Return the initialized array.

   return rgRects;
}

When the application starts, its Form class constructor initializes two class-level integers, nAcross and nDown, to 16, and calls the getRects method previously listed:

public Form1(){

   initForm();
   nAcross = 16;
   nDown = 16;

   // Initialize class-level array.

   rgRects = getRects(this.getClientRect(), nAcross, nDown);
}

After the class constructor returns, the class’ paint event handler is automatically called. This event handler loops through the class-level rgRects array, uses the Graphics object’s setBrush method to set a new color, and then calls the drawRect method to draw the array’s rectangle:

protected void onPaint(PaintEvent e){

   for(int i = 0; i < rgRects.length; i++){

      e.graphics.setBrush(new Brush(new Color(0,0,i)));
      e.graphics.drawRect(rgRects[i]);
   }
}

Finally, the Form class’ resize handler simply reinitializes the array and forces a repaint of the form’s client area:

protected void onResize(Event e){

   Rectangle rcClient = this.getClientRect();
   rgRects = getRects(rcClient, nDown, nAcross);
   this.invalidate();
}


Chords

A chord is a region bounded by the intersection of an ellipse and a line segment, called a secant. The chord is outlined by using the current pen and filled by using the current brush. The part of the ellipse on one side of the secant is clipped.

To draw a chord, use the Graphics object's drawChord method, which has the following syntax.

drawChord(Rectangle p1, Point p2, point p3 )

The drawChord method's Rectangle parameter designates the area into which the ellipse will be drawn. The two Point parameters identify the points at which the two ends of the secant intersect the ellipse.

The following example makes two calls to drawChord. The first call draws a chord in the lower-left corner of the display, and the second draws a chord in the upper-right corner. Prior to each call to drawChord, a different brush is associated with the Graphics object to ensure that the two chords, which combine to form a circle, are painted black and white, respectively.

Example

protected void onPaint(PaintEvent e){

Rectangle rcClient = this.getClientRect();

// Associate a black brush with the object and draw a chord.

e.graphics.setBrush(new Brush(new Color(0,0,0)));
e.graphics.drawChord(rcClient, new Point(rcClient.x, rcClient.y),
new Point(rcClient.getRight(), rcClient.getBottom());

// Associate a white brush with the object and draw a chord.

e.graphics.setBrush(new Brush(new Color(255,255,255)));
e.graphics.drawChord(rcClient, new Point(rcClient.getRight(),
rcClient.getBottom()), new Point(rcClient.x, rcClient.y));
}


Arcs

An application can draw an ellipse or part of an ellipse by calling the drawArc method. This method draws a curve within the perimeter of an invisible rectangle called a bounding rectangle. The size of the ellipse is specified by two invisible radials extending from the center of the rectangle to the sides of the rectangle.

When calling the drawArc method, an application specifies the coordinates of the bounding rectangle and radials.

The following example draws an arc that fills the client area of a form, and then uses the Graphics object’s drawLine method to draw a line from the top of the arc to its radius, and then from its radius to the rightmost side of the ellipse.

Example

protected void onPaint(PaintEvent e){

   Rectangle rcClient = this.getClientRect();

e.graphics.drawArc(rcClient, new Point(rcClient.width /2,rcClient.y),
   new Point(rcClient.width, rcClient.height / 2));
   e.graphics.drawLine(new Point(rcClient.width / 2, rcClient.y),
      new Point(rcClient.width / 2, rcClient.height / 2));
   e.graphics.drawLine(new Point(rcClient.width, rcClient.height / 2),
      new Point(rcClient.width / 2, rcClient.height / 2));
}


Arc Angles

An arc angle is similar to an arc. The primary practical difference between the two is that when an application uses drawArc to draw an arc, it specifies the x and y locations of the arc’s radials.

In contrast, to draw an arc angle the application uses the drawArcAngle method and specifies the degrees of the angle; the method itself takes care of locating the coordinates at which drawing starts and stops.

The drawArcAngle method has the following syntax:

public final void drawAngleArc(Point center, int radius, float startAngle, float endAngle)

The Point parameter identifies the screen location at which to place the radius, specified in the radius parameter. The startAngle parameter specifies the number, in degrees, where the angle starts, and the endAngle parameter specifies how many degrees to draw, beginning at the startAngle parameter.

The following example shows how to use this method. This method draws an arc angle, beginning at a start angle of 30 degrees, and extending 300 degrees from the start angle.

Example

protected void onPaint(PaintEvent e){

      Rectangle rcClient = this.getClientRect();
      int x = rcClient.width / 2;
      int y = rcClient.height / 2;
      int radius = 100;
      float startAngle = 30;
      float endAngle = 300;

      e.graphics.drawAngleArc(new Point(x,y), radius, startAngle, endAngle);

}


Bezier Splines

A Bezier spline is defined by four points, which include two endpoints and two controlling points. Combined, these points define a curve. The two endpoints define the start and end of the curve. The control points serve to "pull" the curve away from the line segment formed by the start and end points.

To draw Bezier splines, use the drawBezier curve method. This method takes an array of Point objects as a parameter. The first four elements of this array define the starting point, two control points, and the end point of the spline.

To draw multiple splines, include three array elements for each spline after the first one. The end point of the first spline serves as the starting point for the next one, and the three array elements define the control points and the end point.

The following example uses the drawBezier method to draw a Bezier curve every time the window is resized.

Example

   protected void onPaint(PaintEvent e)
   {
      Point [] pt = new Point[4];
      Rectangle rc = this.getClientRect();
      int right = rc.getRight();
      int bottom = rc.getBottom();

      pt[0] = new Point(right / 4, bottom / 2);
      pt[1] = new Point(right / 2, bottom / 4);
      pt[2] = new Point(right / 2, 3 * bottom / 4);
      pt[3] = new Point(3 * right / 4, bottom / 2);

      e.graphics.drawBezier(pt);
   }

   protected void onResize(Event e)

   {
      this.invalidate();
   }


Programming Dynamic HTML in Java

With Microsoft® Internet Explorer 4.0, Microsoft introduced its implementation of a revolutionary HTML object model that content providers can use to dynamically manipulate HTML properties. Until now, this object model has primarily been accessed using script technology. The com.ms.wfc.html package of the Windows Foundation Classes for Java (WFC) framework now lets you access the power of Dynamic HTML (DHTML) on a Web page directly from a Java class.

The following topics are covered in this section:

Creating a DHTML Document
Using the initForm Method
Understanding the DhElement Class
Working with Containers
Handling Events
Using Dynamic Styles
Working with Dynamic Tables
Using the com.ms.wfc.html Package on a Server


Creating a DHTML Document

This section covers the basic steps for creating a simple DHTML document and adding your own dynamic behavior to it by using the com.ms.wfc.html package to implement Java and DHTML. Although this section doesn't cover all the details, it introduces the remainder of this topic and the samples. The following five basic steps are required for using the com.ms.wfc.html package.

  1. Create a class called Class1 that extends DhDocument. This class represents the dynamic HTML document. Add initialization code to its initForm method to control the document’s contents and behavior.

    (Extend the behavior of your document by going to step 2.)

  2. Create new elements (such as DhButton) or create element objects that represent existing elements in the document (on the HTML page).

  3. Hook event handlers into some of your elements.

  4. In your Class1.initForm method, add the new elements using the setNewElements method, and bind any existing elements using the setBoundElements method.

  5. Write the event handler methods you hooked up in step 3.

Your document class will look something like the following example.

Example

import com.ms.wfc.html.*;
import com.ms.wfc.core.*;
import com.ms.wfc.ui.*;

public class Class1 extends DhDocument
{
   public Class1()
   {
       initForm();
   }

   // Step 2: Create objects to represent a new elements
   // as well as elements that already exist in the HTML page.
   DhButton newElem = new DhButton();
   DhText existElem = new DhText();

   private void initForm( )
   {
      // Set properties to existing elements and newly added elements.
      newElem.setText("hello world");
      existElem.setBackColor(Color.BLUE);

      // Step 3: Hook up an event handler to your object.
      newElem.addOnClick(new EventHandler(this.onClickButton));

      // Step 4: Call setNewElements with an array of new elements.
      setNewElements(new DhElement[] { newElem });

      // Step 4: Call setBoundElements with an array of
      //existing elements.
      setBoundElements(new DhElement[]{ existElem.setBindID("Sample") });
   }

   // Step 5: Implement your event handler.
   private void onClickButton(Object sender, Event e) {
           existElem.setText("Hello, world");
   }
}

The Java portion of the exercise is complete. The other part is the HTML code. The following example shows an HTML document containing two elements that connect this HTML to your code:

  • The <OBJECT> tag loads the com.ms.wfc.html.DhModule class, which is instantiated by the virtual machine.

  • The <OBJECT> tag has a parameter called __CODECLASS. The value of this parameter is the name of the user class that extends DhDocument (for example, Class1).

Example

<HTML>
<BODY>
<OBJECT classid="java:com.ms.wfc.html.DhModule"
        height=0 width=0 ... VIEWASTEXT>
<PARAM NAME=CABBASE VALUE=MyProject>
<PARAM NAME=__CODECLASS VALUE=Class1>
</OBJECT>

<span id=Sample></span>
<!-- Insert your own HTML code here.-->

</BODY>
</HTML>

Open Internet Explorer 4.0, point it at your HTML file, and your application will run.


Using the initForm Method

The initForm method is the major component in the programming model for all user interface programming in WFC. In the com.ms.wfc.html package, this method is in the DhDocument-derived class (for example, Class1 in Creating a DHTML Document) and is called from the constructor of the class.

Use the initForm method to initialize the Java components that represent the HTML elements you want to access and code to. As with the initForm method in Form-derived classes, there are certain restrictions when calling WFC methods from initForm in DhDocument. As a rule, you should call only methods in initForm that set properties. Moreover, you should bind only to elements on the HTML page using the setBoundElements method.

As a result of using the initForm method in this way, calling any method that resets or removes a property or element is strictly not supported in initForm. This also applies to any methods that attempt to locate elements on the existing HTML page (such as DhDocument.findElement).

The reason for this behavior is because the document on the existing HTML page is not merged with your DhDocument-derived class until the DhDocument.onDocumentLoad method is called. Use the onDocumentLoad method to retrieve properties and manipulate or locate elements in the existing HTML document. For information on using the initForm and onDocumentLoad methods on server-side classes, see Using the com.ms.wfc.html Package on a Server.


Understanding the DhElement Class

Elements are objects derived from DhElement, which is the superclass of all user interface elements in the com.ms.wfc.html package. The following list shows consistent qualities of any object derived from DhElement:

  • Every element has an empty constructor. You can therefore instantiate any element with a new statement, and then set properties, hook event handlers, and call methods consistently.

  • Elements are modeless. Setting properties or calling methods always works in any order and is not conditional, independent of an external state or circumstance.

  • Every container has an add method that takes the type-safe element that is appropriate for it.

  • In the browser environment, an element does not become visible to the end user until you add it (or the topmost container element in its parentage) to the document. This is merely an artifact, however, and not part of the programming model. You don't have to change the way you program to elements because they work the same way whether they are visible or not.

If an element is already on the page when the DhDocument.onDocumentLoad method is called, you can call the document's findElement method and start programming to that element. You can also call setBoundElements from initForm to merge known elements on the page with elements in your DhDocument-derived class. (The findElement method has better performance but specifically requires that onDocumentLoad is called first.)

The searching routine used by findElement and setBoundElements assumes that the element you want to bind to has an ID attribute set to a particular name. Using findElement, you can also enumerate all the elements in the document until you find the one you are interested in.


Working with Containers

Containers are elements that can hold other elements. A basic example is the <DIV> element, which can contain any other HTML item. More complex examples include table cells and, of course, the document itself. In most cases, containers can be arbitrarily nested, such as having a table inside a cell of another table.

Containers are like other elements. They are created with a new statement, and many can be positioned and sized on the page. You can position and size elements within a container and set up their z-order relationships. One of the powerful features of DHTML is that you can then change any of these attributes in your code.

Of course, you can also allow elements within a container to be positioned using the normal HTML layout rules. Call either the setLocation or setBounds method of an element to set its absolute position, or call resetLocation to let the HTML layout engine position it (immediately after the last element in the HTML flow layout).

Once you have created a container element, you can add elements to it using either the setNewElements or add method. This mechanism follows the regular pattern of parent-child relationships: the elements, which can also be other containers, added to the container become its children. None of them are actually attached to the document until the topmost container, which is not a part of any other container, is added to the document.

You can position and size a container using its setBounds method. For example, use the following code to create a container.

     DhForm myForm = new DhForm();

You can then set various attributes on the container, including the ToolTip that is shown when the mouse hovers over the panel.

   myForm.setToolTip("This text appears when the mouse hovers");
   myForm.setFont("Arial", 10);
   myForm.setBackColor(Color.RED);
   myForm.setBounds(5, 5, 100, 100);

Finally, add the container you've just created to the document in your DhDocument-derived class (such as Class1.java).

   this.add(myForm);

When adding elements to the container, specify where they go in z-order using one of a set of constants provided by the com.ms.wfc.html package. Elements are added with a default size and position. Call setBounds on the elements to specify a different size as shown in the following example.

   DhForm myOverLay1 = new DhForm();
   DhForm myOverLay2 = new DhForm();
   myOverLay1.setBackColor(Color.BLACK);
   myOverLay1.setBounds(10, 10, 50, 50);
   myOverLay2.setBackColor(Color.BLUE);
   myOverLay2.setBounds(20,25, 50, 50);
   myForm.add(myOverLay1, null, DhInsertOptions.BEGINNING);
   // Black on top of blue.
   myForm.add(myOverLay2, myOverLay1, DhInsertOptions.BEFORE);
   // Blue on top of black (uncomment below and comment above ).
   // myForm.add(myOverLay2, myOverLay1, DhInsertOptions.AFTER);

You can also use the setZIndex method after the elements are added to move the elements around in z-order. For example, the following syntax does not explicitly set a z-order on the added element but uses the default z-order (that is, on top of all other elements).

   myForm.add(myText);

You can set this explicitly as follows, where num is an integer representing the relative z-order of the element within its container.

   myText.setZIndex(num);

The element with the lowest number is at the bottom of the z-order (that is, everything else covers it). The element with the highest number is at the top (that is, it covers everything else).


Handling Events

Many elements in a DHTML program can trigger events. The com.ms.wfc.html package uses the same event model as the com.ms.wfc.ui package. If you are familiar with that mechanism, you'll find little difference between the two. A button is a good example. The following code shows you how to handle the event that occurs when a user clicks a button on a page.

Example

public class Class1 extends DhDocument
{
   Class1() { initForm();}
   DhButton myButton = new DhButton();
   private void initForm()
   {
      add(myButton);
      myButton.addOnClick(new EventHandler(this.myButtonClick));
   }
   void myButtonClick(Object sender, Event e)
   {
      ((DhButton) sender).setText("I've been clicked");
   }
}

In this code, whenever the button triggers the onClick event (that is, when it is clicked), the myButtonClick event handler is called. The code inside the myButtonClick event handler does very little in this example. It just sets the caption on the button to new text.

Most events propagate all the way up a containment tree; this means that the click event is seen by the button's container and by the button itself. Although programmers typically handle events in the container closest to the event, this event bubbling model can be useful in special cases. It provides the programmer with the flexibility to decide the best place to code the event handlers.

Many different events can be triggered by elements in DHTML, and you can catch them all in the same way. For example, to determine when the mouse is over a button, try the following code, which catches mouseEnter and mouseLeave events for the button.

Example

public class Class1 extends DhDocument
{
   DhButton button = new DhButton();
   private void initForm()
   {
      button.addOnMouseEnter(new MouseEventHandler(this.buttonEnter));
      button.addOnMouseLeave(new MouseEventHandler(this.buttonExit);
      setNewElements( new DhElement[] { button } );
   }
   void buttonEnter(Object sender, MouseEvent e)
   {
      button.setText("I can feel that mouse");
   }

   void buttonExit(Object sender, MouseEvent e)
   {
      button.setText("button");
   }
}

All events that can be triggered (and caught) are defined in the event classes, based on com.ms.wfc.core.Event.


Using Dynamic Styles

A Style object can be thought of as a freestanding collection of properties. The term style is borrowed from the word processing model where the editing of a style sheet is independent of the documents to which you apply it. The same is true for using and applying Style objects in this library.

For example, to change the color of elements in your HTML pages to red, set the properties directly on their elements, which is the traditional model for GUI framework programming. This is shown in the following code.

       // Set the properties directly on their elements.
       DhText t1 = new DhText();
       DhText t2 = new DhText();
       t1.setColor( Color.RED );
       t1.setFont( "arial");
       t2.setColor( Color.RED );
       t2.setFont( "arial");

You could, of course, use derivation to save yourself time. For example, you might consider improving this with the following code.

       // Accomplish this task with derivation.
       public class MyText extends DhText
       {
          public MyText()
          {
              setColor( Color.RED );
              setFont( "arial" );
          }

This works fine until you decide you also want those settings for buttons, labels, tabs, documents, and so on. And you’ll find yourself with even more work when you apply these to another part of your program or to another program.

The answer to this problem is a Style object. While using this library, you can instantiate a Style object and set its properties at any point.

       // STEP 1: Create style objects.

       DhStyle myStyle = new DhStyle();

       // STEP 2: Set properties on style objects.

       myStyle.setColor( Color.RED );
       myStyle.setFont( "arial" );

At any other time in the code, you can then apply that style to any number of elements.

       DhText t1 = new DhText();
       DhText t2 = new DhText();

       // STEP 3: Apply styles using the setStyle method.

       t1.setStyle( myStyle );
       t2.setStyle( myStyle );

To make changes of this kind in the future, the following line sets all instances of all elements with myStyle set on them to change a color.

       myStyle.setColor( Color.BLUE );

This functionality is available during runtime. Every time you make a change to the Style object, the DHTML runtime dynamically retrieves and updates all elements that Style object is applied to.

For more information, see Understanding Style Inheritance.


Understanding Style Inheritance

The HTML rendering engine can determine the style to use if conflicting styles are set on an element. For example, if an element has the color property set directly on it (DhElement.setColor), the color defined by the color property is used. However, if an element has a Style object on it (DhElement.setStyle) and that object has the color property set, that value is used. Failing to find a color or a style, the same process is used with the element's container (DhElement.getParent), and failing that, with the container of that container and so on.

The process continues up to the document. If the document doesn't have a color property set on it, the environment (either browser settings or some other environment settings) determines the color to use.

This process is called cascading styles because the properties cascade down the containment hierarchy. The underlying mechanism for DhStyle objects is called Cascading Style Sheets (CSS) by the World Wide Web Consortium.


Working with Dynamic Tables

Working with tables is actually no different from any other part of the library The principles and programming model apply to tables as they do to any other type of element. This section provides the specifics about working with dynamic tables.

To use a table, create a DhTable object, add DhRow objects to that, and then add DhCell objects to the rows. The following are the rules for table usage.

  • Only DhRow objects can be added to a DhTable object.

  • Only DhCell objects can be added to a DhRow object.

  • Any kind of element can be added to a DhCell object.

While this may seem restrictive, you can easily create a simple container that emulates a gridbag by using the code in the following example.

Example

        import com.ms.wfc.html.*;

        public class GridBag extends DhTable
        {
            int   cols;
            int   currCol;
            DhRow currRow;

            public GridBag(int cols)
            {
                this.cols = cols;
                this.currCol = cols;
            }

            public void add(DhElement e)
            {
                if( ++this.currCol >= cols )
                {
                    this.currRow = new DhRow();
                    super.add(currRow);
                    this.currCol = 0;
                }
                DhCell c = new DhCell();
                c.add(e);
                this.currRow.add( c );
            }

        }

To use this GridBag class, you just set the number of rows and columns (they must be the same with this implementation) and then assign elements to cells. The following is an example of the code in your DhDocument-derived class that uses this GridBag.

Example

   protected void initForm()
   {
      GridBag myTable = new GridBag(5);
      for (int i = 0; i < 25; ++i){
         myTable.add(new DhText("" + i));
      setNewElements( new DhElement[] { myTable } );
      }
   }

One of the most powerful uses of the library is the combination of tables and Style objects. This combination enables you to create custom report generators that are powerful, professional looking, and easy to code.


Data Binding to Tables

Tables also have data binding capabilities. Using a com.ms.wfc.data.ui.DataSource object, you can bind data to your table, as shown in the following sample code.

Example

.
import com.ms.wfc.data.*;
import com.ms.wfc.data.ui.*;
.
void private initForm( ){

   DhTable dataTable = new DhTable();
   dataTable.setBorder( 1 );
   dataTable.setAutoHeader( true );

   DataSource dataSource = new DataSource();
   dataSource.setConnectionString("DSN=Northwind");
   dataSource.setCommandText("SELECT * FROM Products" );

   // If you would like to use the table on the server,
   // call dataSource.getRecordset() to force the DataSource
   // to synchronously create the recordset; otherwise,
   // call dataSource.begin(), and the table will be populated
   // when the recordset is ready, asynchronously.
   if ( !getServerMode() ){
      dataSource.begin();
      dataTable.setDataSource( dataSource );
   } else
       dataTable.setDataSource( dataSource.getRecordset() );

   setNewElements( new DhElement[] { dataTable } );
}

If you know the format of the data that is going to be returned, you can also specify a template (repeater) row that the table will use to format the data that is returned.

To specify a template row

  1. Create your DhTable element.
    DhTable dataTable = new DhTable();
  2. Create your template row and set it into the table. You can also (optionally) create a header row. For each item in the template cell that you would like to receive data from the recordset, create a DataBinding for it.
    .
DhRow repeaterRow = new DhRow();
RepeaterRow.setBackColor( Color.LIGHTGRAY );
RepeaterRow.setForeColor( Color.BLACK );
DataBinding[] bindings = new DataBinding[3];
DhCell  cell = new DhCell();
DataBinding[0] = new DataBinding( cell, "text", "ProductID" );
repeaterRow.add( cell );
cell = new DhCell();.
DataBinding[1] = new DataBinding( cell, "text", "ProductName" );
cell = new DhCell();.
cell.setForeColor( Color.RED );
cell.add( new DhText( "$" ) );
DhText price = new DhText();
price.setFont( Font.ANSI_FIXED );
DataBinding[2] = new DataBinding( price, "text", "UnitPrice" );
cell.add( price );
repeaterRow.add( cell );

// Set up the table repeater row and bindings.
table.setRepeaterRow( repeaterRow );
table.setDataBindings( bindings );

// Create and set the header row.
DhRow headerRow = new DhRow();
headerRow.add( new DhCell( "ProductID" ) );
headerRow.add( new DhCell( "Product Name" ) );
headerRow.add( new DhCell( "Unit Price" ) );
table.setHeaderRow( headerRow );
  3. Create a DataSource object, and set it to retrieve data in the format you expect.
    DataSource ds = new DataSource();
ds.setConnectionString("DSN=Northwind");
ds.setCommandText("SELECT ProductID, ProductName, UnitPrice FROM
Products WHERE UnitPrice < 10" );
  4. Set the DataSource into the DhTable object.
    table.setDataSource( ds );
ds.begin();
  5. Add the DhTable to the document.
    setNewElements( new DhElement[] { table } );
// Alternately, add( table );.

Your table is now populated with the data from the recordset and formatted like the template row.


Using the com.ms.wfc.html Package on a Server

The com.ms.wfc.html package can also be used on the server to provide a programmatic model for generating HTML and sending it to the client page. Unlike the client-side DHTML model, the server-side model is static because the server Java class has no interaction with the client document. Instead, the server composes HTML elements and sends them sequentially to the client as they are encountered in the HTML template if one is specified.

Although not fully dynamic, this is still a powerful server feature. For example, you can apply DhStyle attributes to all parts of some template HTML code and then generate vastly different looking pages by just changing the DhStyle attributes. You do not have to programmatically generate all the individual style changes. Another advantage is that you can use the same model for generating dynamic HTML for both client and server applications, thereby making the HTML generation easier to learn and remember.

There are currently two modes of generating HTML on the server. Both use Microsoft® Active Server Pages (ASP) scripting and a class based on the com.ms.wfc.html classes. The first is the essentials-only approach that relies more on the ASP script. The second uses a class derived from DhDocument and is very similar to the model that you use on the client because it places more control inside the class than in the script.


ASP-Based Approach

The ASP-based approach uses two ASP methods on the server page: getObject and Response.Write. The getObject method is used to instantiate a class based on the WFC com.ms.wfc.html classes. The Response.Write method writes the generated HTML string to the client. The com.ms.wfc.html.DhElement class provides a getHTML method that creates the HTML string. This string is then sent to the client page using the ASP Response.Write method.

For example, you have a class called MyServer that extends DhForm and incorporates some HTML elements. In your ASP script, you first call getObject("java:MyServer") to create a DHTML object. You can then perform whatever actions you want on the object from your ASP script, such as setting properties on the object. When you have finished, you call the object's getHTML method to generate the string and pass that result to the ASP Response.Write method, which sends the HTML to the client. The following code fragments show the relevant ASP script and Java code for creating a DhEdit control in HTML and sending it to the client.

Example

// ASP SCRIPT

Dim f,x
set f = getObject( "java:dhFactory" )
set x= f.createEdit
x.setText( "I'm an edit!" )
Response.Write( x.getHTML() )
Response.Write( f.createBreak().getHTML() )
.
.
.

// JAVA CODE

public class dhFactory {
   public dhFactory(){ }

   public DhBreak createBreak() {
      return new DhBreak();
   }

   public DhEdit createEdit(){
      return new DhEdit();
   }
}


HTML-Based Approach

The HTML-based approach is slightly more sophisticated and closer to the client model. It still uses an ASP script to site the DhDocument class, but the remainder of the operational code is in Java. As in the client model, the DhModule class is instantiated as the Java component on the Web page and automatically calls the initForm method in your DhDocument-derived class.

As in the client model, you can do all your binding setup in your initForm call. The onDocumentLoad function is also called for your server-side class. In this method, you can access the Internet Information Server Response and Request objects (using the DhModule getResponse and getRequest methods) and also append new DhElement items to your document stream. It is important to understand, however, that you cannot use document-level functions, such as findElement, or use enumeration operations on a server-side document except on items that you have explicitly added to your DhDocument-derived class.

To use the HTML-based approach

  1. Create your server Java class (extending from DhDocument).

  2. Implement the initForm method (in the server Java class from step 1) as you would with a client application.

  3. Call the Server.CreateObject method from ASP, passing it "DhModule" to create a DhModule object.

  4. Call DhModule.setCodeClass method, passing it the name of your DhDocument-derived class.

  5. Call the DhModule.setHTMLDocument method, passing it the full local file name path of your server Web page as a template (if you have one).

    If you call setHTMLDocument with an empty string (""), your DhDocument class runs and outputs the HTML for any elements you have added at the location in your ASP where setHTMLDocument is called. You can then generate sections of HTML code inline.

    If you do not call setHTMLDocument, the DhDocument class outputs full HTML for the page, including the <HTML>, <HEAD>, and <BODY> tags.

The following sample shows an ASP page that uses a template.

<% Set mod = Server.CreateObject( "DhModule" )
   mod.setCodeClass( "Class1" )
   mod.setHTMLDocument( "c:\inetpub\wwwroot\Page1.htm" )
%>

At runtime, the framework recognizes that your class is running on a server and acts accordingly.

Once instantiated, you can add elements or text to your DhDocument-derived class. Those items will be appended to any template specified just before the </BODY> tag.

The following sample demonstrates a class that works on either the client or the server.

Example

import com.ms.wfc.ui.*;
import com.ms.wfc.html.*;

public class Class1 extends DhDocument {
   public Class1(){
      initForm();
   }
   DhText txt1 = new DhText();
   DhForm sect = new DhForm();

   private void initForm() {

      // Call getServerMode() to check
      // If this object is running on the server.
      if ( getServerMode() ){
          txt1.setText( "Hello from the server!" );
      }else{
          txt1.setText( "Hello from the client!" );
      }

      // Size the section, set its background color,
      // and add the txt1 element to it.
      sect.setSize( 100, 100 );
      sect.setBackColor( Color.RED );
      sect.add( txt1 );
      add( sect );
      setNewElements( new DhElement[] { sect } );
   }
}

If you want to bind to an existing HTML document on the page, use the DhDocument.setBoundElements method, just as you would on the client. For example, if your HTML template contains the following HTML,

<P>
The time is:<SPAN id=txt1></SPAN><BR>
<INPUT type=text id=edit1 value="">
</P>

your initForm method looks like the following:

DhText txt1 = new DhText();
DhEdit edit = new DhEdit();
DhComboBox cb = new DhComboBox();

private void initForm(){
    txt1.setText(com.ms.wfc.app.Time().formatShortTime());

    edit.setText("Hello, world!");
    edit.setBackColor( Color.RED );

    setBoundElements( new DhElement[]{ txt1.setBindID( "txt1" )
                                       edit.setBindID( "edit1" ) } );

    // Create a combo box to be added after the bound items.
    cb.addItem( "One" );
    cb.addItem( "Two" );

    // Add the items to the end of  document.
    setNewElements( new DhElement[]{ cb });
}

One important difference exists between the interpretation of server and client HTML classes: When elements are written (sent to the client), they cannot be modified as they can on a client document (although few differences exist otherwise). The DhCantModifyElement exception, which is relevant only for server applications, is thrown after a write has been performed on an element if an attempt is made to modify that element again. (This underscores the fact that there is no real interoperation between the server Java class and the client document as there is on the client between the Java class and the document: From the server's standpoint, once it is written, the element is essentially gone.)

One advantage of using the DhDocument-derived method is that you can implement an HTML template that is embedded with attributes recognized by the com.ms.wfc.html classes. By first decorating the HTML elements in the file with ID attributes and then setting the corresponding IDs in the source code using the DhElement.setBindID method, you can bind to these HTML elements, set properties on the elements, add your own inline HTML code, and so on. This essentially allows you to code and design separate templates in advance and populate the template with dynamic data when the document is requested from the server.


Data Binding in WFC

To access data from your Java project, you typically use the ActiveX Data Objects (ADO) components, which define the data programming model for WFC applications. The core ADO objects include the Connection, Command, and Recordset objects.

The Connection object allows you to connect to a database. Once a connection is established, you can query the database to retrieve a set of records. The Recordset object represents the records returned from a query. You can use either an SQL string or a Command object to specify the query.

ADO also provides the DataSource component, which combines the functionality of the Connection, Command, and Recordset objects. The ADO classes are defined in the com.ms.wfc.data and com.ms.wfc.data.ui packages.

Once a recordset has been retrieved, either through a Recordset object or a DataSource component, you can bind the recordset to a WFC component. WFC supports both simple and complex data binding, as described in the following table.

Type of Binding | Description
Simple | Refers to the relationship between a field in a recordset and the property of a WFC component. The binding is called simple because the component does not need explicit information about the data protocol or data provider.
Complex | Refers to the direct relationship between a recordset and a WFC component.

Note that the recordset’s cursor and lock types determine whether the data in the recordset dynamically reflects the data in the database, and whether the data in the recordset can be changed.

For more information about ADO, see the Microsoft® ActiveX® Data Objects section of the MSDN™ Library.


Simple Data Binding

Simple data binding refers to the relationship between a field in a recordset and the property of a WFC component. When a property is bound, data is automatically transferred between the field and the property.

  • If the value of the field changes, the new value is propagated to the property.

  • If a new record in the recordset is navigated to, the current field value is propagated to the property.

  • If the value of the property changes and the component supports a property change notification, the new value is propagated to the field in the recordset. The recordset is updated when a new record is navigated to.

    Note If an attempt is made to update a read-only recordset, the recordset will generate an ADO exception. You can then catch this exception and set the bound property back to its previous value; otherwise, the value of the property and the value of the field will be inconsistent.

Bindable Properties

Simple data binding in WFC is performed by the DataBinder component. This component creates and manages the binding between the field and the property. The DataBinder component can bind a property that is accessible through methods matching the following design patterns.

public <PropertyType> get<PropertyName>()
public void set<PropertyName>(<PropertyType>)

Note that if a property is also marked with BindableAttribute.YES in the component's ClassInfo, it is enumerated in the Properties window and in the DataBinder component's design page. (You can still bind a property that is not marked as bindable by manually typing the name in the Properties window or design page, or by binding the property programmatically.)

Property Change Notifications

The component of a bound property can provide a <propertyName>Changed event to indicate that the property's value has been changed. When this event is triggered, the DataBinder component marks the binding as dirty. Then when the user navigates to a new record or when the DataBinder.commitChanges method is called in code, the DataBinder component determines which bindings are dirty and updates those bindings on the recordset.

Note If your component does not provide a <propertyName>Changed event for a property that is bound through the DataBinder component, the binding is read-only and your component will be disabled. To work around this limitation, you can manage the bindings yourself in code by directly reading from and writing to the recordset.


DataBinder Component

ADO defines the DataBinder component to perform simple data binding. This component creates and manages the bindings between the fields in a recordset and the bindable properties of WFC components. For more information about whether a property can be bound, see Bindable Properties.

Although a single DataBinder component can manage multiple bindings, it is associated with only one recordset. To bind the fields of a second recordset, you must use another DataBinder component. Additionally, the DataBinder component should only be used to bind components that exist on the same form.

If the component of a bound property supports a change notification for that property, the DataBinder component marks the binding as dirty when the property value changes. The recordset is updated when the user navigates to a new record or when the DataBinder.commitChanges method is called in code. For more information, see Property Change Notifications.

The following example shows how to programmatically perform simple data binding with the DataBinder component. Note that the DataBinder component uses an array of DataBinding objects to manage the bindings.

Example

import com.ms.wfc.data.*;
import com.ms.wfc.data.ui.*;
import com.ms.wfc.ui.*;

// Use the Connection and Recordset components to
// connect to a database and retrieve a recordset.
Connection c = new Connection();
c.setConnectionString("dsn=myDSN;uid=myUID;pwd=myPWD");
c.open();

Recordset rs = new Recordset();
rs.setActiveConnection(c);
rs.setSource("select * from authors");
rs.open();

// Create a DataBinder component. To associate this
// component with rs, set the dataSource property.
DataBinder db = new DataBinder();
db.setDataSource(rs);

// Create the components whose properties will be bound.
Edit edit1 = new Edit();
Edit edit2 = new Edit();

// Set the DataBinder component’s bindings property to
// an array of DataBinding objects. This array defines
// the bindings between the text property of each Edit
// component and the fields in the recordset.
db.setBindings(new DataBinding[] {
      new DataBinding(edit1, "text", "firstName"),
      new DataBinding(edit2, "text", "lastName") } );
}

For more information about the DataBinder component’s dataSource property, see Complex Data Binding.


Complex Data Binding

Complex data binding refers to components that interact directly with a recordset. A complex data-bound component provides dataSource and dataMember properties that identify the recordset it is bound to. Note that the properties of complex bound components can still be simple bound by means of the DataBinder component.

dataSource and dataMember Properties

The dataSource property identifies an object that implements the IDataSource interface. This object exposes one or more recordsets. The dataMember property then specifies the name of the recordset that is currently bound to the component. For example:

// Bind the component to the recordset named "Products",
// which is exposed by the data source, ds.
dbComponent.setDataSource(ds);
dbComponent.setDataMember("Products");

If you do not set the dataMember property, the data source’s default recordset will be bound. (You can explicitly specify the default recordset by setting the dataMember property to null.)

// Bind the component to the default recordset
// exposed by the data source, ds.
dbComponent.setDataSource(ds);
dbComponent.setDataMember(null);  // This line is optional.

Note that the Recordset and DataSource components already implement the IDataSource interface. You can therefore set the dataSource property directly to one of these components. In this case, you do not have to set the dataMember property.

// Set the dataSource property directly to the Recordset
// component,rs, without setting the dataMember property.
dbComponent.setDataSource(rs);


Security

Trust-based security for Java is a cross-platform security model that provides fine-grained administration of the permissions granted to Java applets and libraries. This security system provides intermediate levels of trust so that Java applications can be given additional permissions without being offered unlimited access to every permission in the system.

This section contains the following topics:

Trust-Based Security for Java provides an overview of the security model for Java classes that is supported by Microsoft® Internet Explorer 4.0.

For information on signing your code to work with the security model, see Signing Cabinet Files with Java Permissions.


Trust-Based Security for Java

Trust-based security for Java provides a flexible, easy-to-use security system. The permission model provides control over what a Java class can do by providing a way to associate a set of permissions with a class. Encoding the permission set in the digital signature allows the Microsoft VM to present the end user with a dialog box. It lists the requested permissions so the user can decide whether to trust the applet.

Administrators can make preliminary security decisions based on predefined zones. As such, the end user is spared from many tedious security decisions. Permission scoping prevents untrusted classes from taking advantage of the expanded permissions of trusted classes and gives developers the ability to decide which parts of their trusted code enable a particular permission. Finally, package management allows for local installation of components that are not fully trusted so that those components have expanded permissions, but not unlimited power.

The following topics describe the implementation of each feature of the trust-based security system:

Security Zones that allow related sites (such as all sites on a company intranet) to be administered as a group.

Permission Model that integrates with security zones to provide parameterized control over what Java classes can do.

Permission Signing that allows a signed cabinet file to specify not only the identity of the signer but also the set of permissions being requested for the signed classes.

Permission Scoping that enables a developer who designs a trusted class to precisely limit the range of code for which a granted permission is enabled.

Package Manager that allows classes to be installed with their permissions.

User Interface that simplifies or eliminates the decisions that end users must make.


Security Zones

Security zones allow a system administrator to manage groups of sites using the same level of trust for a whole group. Administrators can set nonrestrictive security options for trusted areas and, at the same time, set very safe (restrictive) security options elsewhere. Predefined zones exist for categories such as the Local Intranet and the Internet. Security zones relieve administrators of having to list every trusted applet and its permissions, and they help administrators avoid the risk of leaving too many detailed decisions to end users.

There are five default security zones defined in the trust-based security for Java implementation in Microsoft® Internet Explorer 4.0. These zones correspond to the most commonly used types of sites:

My Computer

This zone includes most classes stored on the local machine. Because this zone is completely trusted, few or no security restrictions apply.

Local Intranet

This zone includes content that is known to be reliable (typically located inside the firewall or obtained using a secure sockets layer [SSL] connection).

Trusted Sites

This zone includes responsible Internet sites that are allowed to run with increased permissions, but not with the powerful permissions allowed to the Intranet zone.

Internet

This zone includes all other sites, including scratch and development areas inside the firewall, and untrusted parts of local drives. This zone would typically be set to the standard applet permissions.

Restricted Sites

This zone includes potentially harmful sites to which severely restricted permissions apply. For these sites, you may want to define "sandboxes" that are even more restrictive than the standard Java sandbox.

Network administrators can configure three different sets of permissions for each zone. The set that a permission is placed in determines whether or not the user will be presented with a dialog box that shows requested permissions.

Permissions granted without user intervention

These permissions are granted to applets from the specified zone without querying the user. These permissions can be separately specified for signed and unsigned applets.

Permissions granted with user intervention

These permissions can be determined directly by querying users with a list of the permissions being requested; in this case every permission not mentioned is assumed to be denied.

Permissions that are prohibited

These permissions are considered too dangerous to allow under any circumstances. They are automatically denied.

If an applet uses only permissions granted without user intervention to its zone, it will run without user intervention. If it uses any explicitly denied permissions, it will automatically be prevented from running. Otherwise, the user will be presented with a single dialog box listing all the permissions being requested and their associated risk. The user can then make one decision about whether to trust the applet that has that set of permissions.

An applet that does not receive the additional permissions requested will still be permitted to run, but will be prevented from exercising those permissions by security exceptions. The applet can catch the security exceptions so that it can take alternate action, perhaps continuing to run with more limited functionality.

The administrator can define a set of permissions that is assigned to all unsigned classes and scripts. This set defines the permissions of unsigned applets.


Permission Model

The permission model for trust-based security supports a useful set of parameterized and non-parameterized permissions that can be individually granted or denied for a particular zone by an administrator. To reduce the number of options that administrators must specify in common cases, the administrative user interface provides several predefined permission sets that can be applied. These predefined permission sets, called High, Medium, and Low, represent the most restrictive to the least restrictive set of permissions, respectively.

Permissions can only be defined by system libraries with the highest degree of trust. This solves the problem of having to administer a potentially unlimited set of permission requests with uncertain, application-defined meanings.

Predefined Permissions

The following list describes each permission defined by the permission model and lists the parameters available for limiting each permission.

Client Storage Permission

Determines whether applets can access scratch space. Parameters for this permission include the size of the scratch space and flags that indicate whether storage is exempt from global storage limits and whether roaming files can be created. For more information, see the Client Storage Permission class.

Execution Permission

Determines which programs can be executed on the client's machine. Parameters for this permission include a pattern that indicates which applications to include or exclude from the permission. For more information, see the Execution Permission class.

File I/O Permission

Determines whether applets can perform file operations. Parameters include the type of access (read, write, or delete), the file name or a pattern that indicates a group of files, and a flag that specifies whether the operation is denied or allowed. For more information, see the FileIOPermission class.

Multimedia Permission

Controls access to extended multimedia capability. This permission has no parameters. For more information, see the MultimediaPermission class.

Network I/O Permission

Controls the ability to perform networking components for three types of network operations: connect, bind, and multicast. Parameters include the network operation type (connect, bind, or multicast), a flag that indicates whether to allow or deny the operation, a pattern that indicates which hosts or ports to include or exclude, Internet Protocol (IP) addresses, port ranges, and flags that indicate whether you can bind to a non-file:// URL codebase or to a file://URL codebase. For more information, see the NetIoPermission class.

Printing Permission

Controls whether an applet is allowed to print. This permission has no parameters. For more information, see the PrintingPermission class.

Property Permission

Controls the ability to access and manipulate the global system properties. Parameters include a flag that indicates whether access to all properties is turned on or off, a pattern that indicates which properties are included or excluded, and suffixes indicating properties that could be accessed under certain conditions. For more information, see the PropertyPermission class.

Reflection Permission

Determines whether access to the java.lang.reflect API is permitted. Parameters include a loader type (same loader, different loader, system loader, all, or none) and an access type (public or declared). For more information, see the ReflectionPermission class.

Registry Permission

Controls the ability to access the registry. Parameters include the type of access (read, write, open, delete, or create) and a pattern that indicates which keys/values are included or excluded from access. For more information, see the RegistryPermission class.

Security Permission

Controls access to the java.lang.security package. This permission has no parameters. For more information, see the SecurityPermission class.

System Streams Permission

Controls the ability to change the values of the system streams java.lang.System.in, java.lang.System.out, and java.lang.System.err. Parameters include flags that indicate whether System.in, System.out, and System.err can be set. For more information, see the SystemStreamsPermission class.

Thread Permission

Controls the ability to create and manipulate threads and thread groups. Parameters include a thread or thread group object, a flag that indicates whether unrestricted thread access is allowed, and a flag that indicates whether unrestricted thread group access is allowed. For more information, see the ThreadPermission class.

User File I/O Permission

Determines whether user-directed file I/O can be performed. Parameters for this permission include the access type (read or write) and a file name or a pattern that indicates which files to allow access to. For more information, see the UserFileIOPermission class.

User Interface Permission

Controls the ability to create top-level windows, access the system clipboard, create file dialog boxes, and access the AWT event queue. Parameters for this permission include flags that indicate access to one or more of the enhanced UI functions. For more information, see the UIPermission class.

Defining Applet Permissions

The following sets of permissions correspond to the standard Java sandbox:

  • Thread access in the current execution context.

  • Network connections to the applet host.

  • Creation of top-level windows with warning banners.

  • Reflection to classes from the same loader.

  • Access to base system properties.

You can choose these permissions or you can set up an even more restrictive set of permissions for applets. Choosing a less restrictive set is not recommended.

Defining Custom Permissions

Internet service providers or personal users might want to define custom permissions. Permission objects can be defined to protect some functionality in your code against misuse. Custom permissions can be added to the digital signature so that the user can decide (via a dialog box) whether or not to accept the risk. To add custom permissions to the digital signature, you specify the requested permissions in an .ini file that is used by the signcode tool when signing the cabinet file. For more information about using the permission .ini file with the signcode tool, see Signing a Cabinet File with Java Permissions and the Sample Permissions .INI File.


Permission Signing

Permission signing extends the signed cabinet file functionality provided by Microsoft® Internet Explorer 3.0. Under trust-based security, a signed cabinet file can securely specify not only the identity of the signer but also the set of permissions being requested for the signed classes. The security system can determine all of the permissions requested by a Java component by inspecting the digital signature. This information is used to present the user with a single dialog box that displays all the relevant trust questions. The dialog box is presented before any code starts to run. In addition, because the set of permissions is fully defined and understood by the Microsoft virtual machine, the dialog box can accurately warn users about the risk of each requested permission. For more information on permission signing, see Signing a Cabinet File with Java Permissions.


Permission Scoping

Permission scoping prevents permissions granted to a trusted component from being misused (either inadvertently or intentionally) by a less trusted component. A trusted class can precisely limit the range of code for which a granted permission is enabled. This is an important issue because some methods that use enhanced permissions are designed to be safely called by anyone, while other methods are designed to be used internally by trusted callers only and should not expose their permissions to less trusted callers.

Trust-based security distinguishes between permissions that have been granted to a class and permissions that are actually enabled at a particular time. The granted permissions are determined by the administrative options for a class's zone and by the permissions with which the class was signed. In contrast, enabled permissions are determined by the permissions granted to other callers on the call stack and by any calls that were made to the assertPermission, denyPermission, and revertPermission methods. If there are any less trusted callers on the call stack, the enabled permissions can be more restrictive than the granted permissions.

When the Microsoft VM implements permission scoping, two rules are followed. The first rule is that permissions are never inherited from the caller. If a class has not been directly granted a permission, it can never make use of that permission, regardless of what permissions its callers may have. This makes trust-based security invulnerable to "luring" attacks, in which an untrusted class "lures" a trusted class into calling it so that the untrusted class is allowed to make use of the expanded permissions of its caller.

The second rule is that even if a class has been granted a permission, its methods must explicitly enable that permission using the assertPermission method whenever there is a caller on the call stack that has not been granted that permission. In other words, permission P is enabled only if either statement 1 or 2 listed below is true, and if statement 3 is true.

  1. P is granted in all the stack frames from the active frame up to the earliest frame on the stack.

  2. P is granted in all the stack frames up to a frame that has called assertPermission on P.

  3. No intervening frame has called denyPermission on P.

The deep security checks of the PolicyEngine class perform the stack crawl that follows the above rules. The Java APIs contain calls to the StandardSecurityManager checkXX methods, which in turn call the PolicyEngine.checkPermission methods to check for a particular permission.

The methods of the PolicyEngine class allows you to control which permissions are enabled. For example, the following code sample asserts the right to access scratch space through the com.ms.io.clientstorage APIs, then reverts this right.

import com.ms.security.*;
import com.ms.io.clientstorage.*;

// Assert the right to access the
// com.ms.io.clientstorage APIs.
PolicyEngine.assertPermission(PermissionID.CLIENTSTORE);

// Now open a file for writing. Because rights have been
// asserted, this check will succeed even if the callers
// do not possess the CLIENTSTORE permission.
OutputStream os =
   ClientStorageManager.openWritable("Scratch1.txt");

...
// Remove the scratch space assertion.
PolicyEngine.revertPermission(PermissionID.CLIENTSTORE);
...

// Open a file for reading.
// This time the callers will be included in the
// security check because the right to access the
// com.ms.io.clientstorage APIs is no longer asserted.
// The security check will succeed only if all callers
// have the appropriate CLIENTSTORE permission.
InputStream is =
   ClientStorageManager.openReadable("Scratch2.txt");
...

For more information on asserting, denying, and reverting permissions, see the com.ms.security overview. For more information about how the stack crawl for security checks is implemented, see the overview for the PolicyEngine class.


Package Manager

The package manager allows the installation of local class libraries that are not fully trusted by using permission signing. This is especially important for components such as JavaBeans and class libraries. It is desirable to allow these components to reside locally and to have some expanded permissions, but it is often not necessary to give them unlimited power.

System libraries are libraries that are shared and have all possible security permissions available to them. These libraries are the core of the Java system APIs, and they are the most privileged Java code. Most packages installed from non-system providers do not need this level of permissions. However, Java has traditionally treated all local classes on the class path as if they were system libraries.

Under trust-based security, classes from installed packages are not shared between applets or applications that use them. They carry specific system permission identifiers that are approved by either the user or the system administrator when the package is installed on the user's system. The permission identifiers determine the maximum permissions that can be used by the classes in that package. For more information on the package manager, see Java Package Manager .


Security User Interface

The user interface (UI) defined by trust-based security for Java shields end users from complicated trust decisions and reduces the number of dialog boxes that they must respond to. The integration of permissions with zones means that users only need to make a simple yes/no decision about whether to trust an application. An administrator has already made preliminary decisions, based on the zone involved, about which permissions to leave to the discretion of the user.

Permission signing allows the security system for the Microsoft VM to predetermine all the permissions required by a class. When a package is installed, the security system uses the digital signature to determine exactly which system permissions are needed. Before the code runs, a single dialog box clearly presents to the user all the permissions required by an application.


Internationalization

The Microsoft SDK for Java enhances the internationalization features of Java with support for local character set encoding, Microsoft® Win32® resources, locales, vertical writing, and Java-based input method editors (IMEs). (The primitive character types in Java are based on Unicode, which is an international standard for encoding written language elements.)

This section contains the following topics:

Internationalization Support provides a comprehensive overview of the enhanced internationalization support in the SDK for Java.

LCID Reference lists Win32 LCID values used for localization of resources.


Internationalization Support

The global connectivity provided by the Internet will increase the demand for internationalized software products and place additional requirements on internationalized applications. For example, applications that are delivered and run over the Internet may need to adapt to the user's language at runtime. Other applications will need to be multilingual and support a combination of different languages. Java was designed to support internationalization; its primitive character type is based on Unicode, an international standard for encoding written language elements.

The Microsoft SDK for Java provides the following enhanced internationalization features:

  • Win32 resource file support

  • Vertical writing support

  • Java-based input method editors (IMEs)

  • Conversion between local character set encoding and Unicode

The enhanced internationalization support is provided by the following Microsoft packages:

  • com.ms.ui.resource provides support for using Microsoft® Win32® resources in Java applications. See the Microsoft SDK for AFC for information on this package.

  • com.ms.lang includes the SystemX class that provides system-level internationalization services, such as managing IMEs and converting strings between local code pages and Unicode.

  • com.ms.util.InputMethod provides support for creating Java-based IMEs.

  • com.ms.fx provides FxFormattedText, the standard text layout class, for vertical writing in Far Eastern languages. See the Microsoft® SDK for AFC for information on this package at http://www.microsoft.com/java/afc/.

In addition to the enhanced support provided by the packages in the preceding list, the Microsoft virtual machine includes fully functional versions of the java.lang.Runtime methods getLocalizedInputStream and getLocalizedOutputStream.


Microsoft Win32 Resources

Resources are used to isolate text and user interface elements (such as menus and dialog boxes) from the executable part of an application. Although the advantages of using resources apply to all applications, resources are particularly useful in applications requiring internationalization. Resource files can be localized and tested without having to rebuild an entire application. Using resources also decreases size and shortens load time for .class files, as they are not implemented with large amounts of static data.

The Microsoft SDK for Java supports a compact resource format. The com.ms.ui.resource.ResourceDecoder class is an extensible class designed to load resources from a binary file. The com.ms.ui.resource.Win32ResourceDecoder class reads resources in the Win32 resource format. This class also provides methods for accessing the individual resource elements within a resource file. This enables you to use existing resource files with Java applications and to use familiar tools and processes to create and localize new resources.

One problem with current development tools is that they are not necessarily capable of modifying resources in multiple languages within the same file. For example, a common problem is merging Far Eastern language resources with Western ones due to operating system limitations. The Microsoft SDK for Java includes the resmerge utility that enables you to develop resources separately, and then combine resources for different languages into one .res file. When you load Win32 resources from these combined resource files, you can specify the combined resource file as a source, and the language of the resource (the LCID) that you want to load.

Creating Multilingual Java Applications using Win32 Resources

There are four steps used in creating a Java application that uses localized resources:

  1. Develop the application.
    • Design your application so that you do not set fonts for resources you are loading. The Microsoft VM automatically assigns default system fonts for loaded resources.

    • Make sure you take multilingual requirements (vertical writing, and so on) into account and set the size for GUI elements (for example, dialog boxes) accordingly.
  2. Create the resource files, and localize them with existing resource localization tools.

  3. Merge the localized resource files using the resmerge utility, if necessary.

  4. Use the Win32ResourceDecoder class to access and load localized resources from your Java application.

For example, if you wanted to be able to load both a Japanese and an English string resource, you would first develop these two resources, and then combine them using resmerge.

C:\..\>resmerge -a resources.res MyProjResUS.res MyProjResJP.res

Using Multilingual Java Applications with Win32 Resources

Using Win32 resources in an application is easy. You link to the file and extract the resource using the Win32ResourceDecoder. For example, to populate a panel with localizable controls, you create a resource file that contains dialog resources with the controls laid out as you want them. Execute the following code at runtime:

public void populate(UIPanel p, int id)
{
    Win32ResourceDecoder res=new Win32ResourceDecoder("resources.res");
    try
    {
        res.populateDialog(p, id);
    }
    catch (Exception e)
    {
        System.out.println("Problem "+e);
    }
}

Note that a locale identifier (LCID) is not used because you typically load the resources in the language the user needs. However, you can specify a language for any resource by adding the LCID to the method call. For example, an English/Greek dictionary would specify that the list of translated words be loaded in those languages, even if the application is currently being used by someone in Germany and the rest of the user interface is in German.

Note Using Win32 resources allows you to localize your Java applications without giving your Java source code to localization translators. As a result, there will be no confusion between literal text strings and text that should be localized.


Vertical Writing Support

Traditional Chinese and Japanese texts are written vertically. Characters appear in a vertical line from the top to the bottom of the page, with lines progressing from the right to the left side of the page. The Microsoft VM supports vertical writing with the FxFormattedText class. There are two ways to specify that the text for an FxFormattedText buffer be written vertically:

  • Use the setLocale method to set the locale to a locale that uses vertical writing. Locales that use vertical writing are Locale.TRADITIONAL_CHINESE_VERTICAL, Locale.SIMPLIFIED_CHINESE_VERTICAL, Locale.KOREAN_VERTICAL, and Locale.JAPANESE_VERTICAL.

  • Use the setTextDirection method to set the text direction to top-to-bottom, and right-to-left (FxFormattedText.tdTB_RL).

Example

The following sample code implements a panel that contains vertical writing:

class VerticalWritingSample extends UIPanel
{
    FxFormattedText fxft;

    public VerticalWritingSample ()
    {
        fxft = new FxFormattedText ("Vertical Text!");
        fxft.setLocale (Locale.JAPANESE_VERTICAL);
    }

    public void paint (FxGraphics g)
    {
        fxft.paint (g);
    }
}

Note When written vertically, characters are rotated 90 degrees to the right (clockwise). This rotation is in accordance with the conventions of vertical writing for traditional Chinese and Japanese texts.


Input Method Editors

An input method editor (IME) is a program that allows computer users to enter complex characters and symbols, such as Japanese Kanji characters, by using a standard keyboard. Internationalized versions of Microsoft® Windows® provide native system IMEs for locales with languages using non-Latin alphabets (for example, Japanese, Korean, Traditional Chinese, and Simplified Chinese). The Microsoft virtual machine provides IME support for Java applications with an Input Method Manager (IMM) that hosts Java-based IMEs, as well as native system IMEs.

Native System IMEs

The Microsoft VM supports existing native system IMEs interchangeably with Java-based IMEs. However, there are some limitations associated with using system IMEs. You can use a Java-based IME on any system, regardless of what language the system is localized for, as long as the Microsoft VM is installed. With native system IMEs, however, you are limited to IMEs supported by the host system.

Java-Based IMEs

The Microsoft VM fully supports IMEs written in the Java language. Java-based IMEs provide more flexibility and control for applications than native system IMEs. The following is a summary of the features of Java-based IMEs.

Feature | Description
Unicode-based | Java IMEs can be used with any version of Microsoft Windows.
Cross-platform | Java IMEs will run on any system that has the Microsoft VM installed.
Multilingual | Java IMEs for different languages can be activated concurrently by a single Java application (provided the proper fonts are installed on the user's system).
Web-downloadable | Java IMEs can be packaged and downloaded with applets or downloaded at the discretion of the user.
Managed by the application | Applications can control Java IME interface elements such as composition, status, and candidate windows.
Secure | Java IMEs follow normal Java security rules and run in the "sandbox" with Java applications.

Writing a Java-Based Input Method Editor

The com.ms.util.InputMethod package contains the following classes for creating Java-based IMEs:

  • The IMECompositionMessage Class represents messages sent to the composition window of an IME.

  • The IMENotifyMessage Class represents messages sent to an IME to notify it to perform an action on the status or candidate windows.

  • The InputMethodCallback Class is an interface class that enables an IME to return composed characters and messages to the IMM.

  • The InputMethodListener Class is an interface class that IMEs must implement to be used with the IMM.

Note The Microsoft SDK for Java includes a sample application, SampleIME, that illustrates how to write a simple, Java-based IME located in %SDKDIR%\Samples\International\Sampleime. For more information, see the Internationalization Samples Overview. For information about other samples in this SDK, see the Samples Overview.

Handling Keystrokes

Keystrokes are passed from the Microsoft virtual machine to the IMM, which routes them to the IME. To receive keystrokes, the IME must override the InputMethodListener.handledKey method. The imeCallback parameter in InputMethodListener.handledKey specifies an InputMethodCallback object that allows the IME to send messages back to the Microsoft VM. When composition is complete, the IME should use the InputMethodCallback.handleIMEChar method to return the composed Unicode character to the Microsoft VM.

Note Keystrokes are represented by virtual key codes defined by the KeyEvent class in the java.awt.event package. Keyboard state codes (ALT, CTRL, SHIFT, and so on) are defined in the InputManagerListener class.

Using IMEs with Java Applications

You do not have to do anything special with your Java application to use native system IMEs. If a native system IME is present on a system running the Microsoft VM, it will correctly process and route IME-composed strings to the application.

If you want to use a Java-based IME with your application, you must use the IMM to activate the IME that you want to use. The following list shows the classes you use to work with the IMM.

  • The SystemX class (in the com.ms.lang package) enables you to get and set the default IMM provided by the Microsoft VM.

  • The InputMethodListener class (in the com.ms.util.InputMethod package) is an interface class that includes methods for managing IMEs.

You must set the current IMM before activating an IME.

Example

The following code shows how to set the default IMM and install an IME:

InputManagerListener imm;
MyIME ime;

// Set default IMM
imm = com.ms.lang.SystemX.getDefaultInputManager ();
com.ms.lang.SystemX.setInputManager (imm, true);
if (imm != null)
{
    // Instantiate IME.
    ime = new MyIME () ;

    if (ime != null)
    {
        // Set IME to be current IME and activate it.
        imm.setInputMethod (ime);
        ime.activate ();
    }
}


Conversion between Local Character Set Encoding and Unicode

Although the Java language includes support for Unicode strings, many text editors use local character set encoding, and many text files contain local character set strings, not Unicode strings. This causes two different problems:

  • At compile time, local character set encoded string literals must be converted to Unicode.

  • At runtime, strings must be converted between local character set encoding and Unicode during read and write operations.

The Microsoft Compiler for Java (jvc) translates local character set encoded string literals in Java source code to Unicode when it compiles the source into class files. When the Microsoft VM runs these class files, the string literals will appear correctly. The java.lang.Runtime methods getLocalizedInputStream and getLocalizedOutputStream will convert between local character set encoding and Unicode.

Note You should only use the getLocalizedInputStream method on input streams that are known to be encoded in a local character set. Do not use this method on input streams that contain Unicode characters.

Converting Local Encoding to Unicode

The getLocalizedInputStream method converts local character set encoding to Unicode. To use it, you must first call Runtime.getRuntime to get a Runtime object. Then, call the Runtime.getLocalizedInputStream method, passing the input stream object that you want to have converted. The getLocalizedInputStream method returns a DataInputStream object that performs local-character-set-to-Unicode conversion on the input stream. The following example demonstrates this technique.

Example

Runtime rt = Runtime.getRuntime();
FileInputStream fisLoc;  // local
DataInputStream disUni;  // Unicode
String sInput;

fisLoc = new FileInputStream("LOCAL.TXT");
disUni = (DataInputStream)rt.getLocalizedInputStream(fisLoc);
sInput = disUni.readLine();

Converting Unicode to Local Encoding

The getLocalizedOutputStream method converts Unicode to local character set encoding. To use it, you must first call Runtime.getRuntime to get a Runtime object. Then, call the Runtime.getLocalizedOutputStream method, passing the output stream object that you want to have converted. The getLocalizedOutputStream method returns a DataOutputStream object that performs Unicode-to-local-character-set conversion on the output stream. The following example demonstrates this technique.

Example

Runtime rt = Runtime.getRuntime();
FileOutputStream fosUni;  // Unicode
DataOutputStream dosLoc;  // local
String sOutput = "This is a Unicode string";

fosUni = new FileOutputStream("OUTPUT.TXT");
dosLoc = (DataOutputStream)rt.getLocalizedOutputStream(fosUni);
dosLoc.writeChars(sOutput);


LCID Reference

130 LCIDs assigned (*unsupported)
105 LCIDs supported
 59 Primary languages

Number of LCID Language and Locale
Occurrences
-------------------------------------
 1          0401        Arabic - Saudi Arabia
 2          0801        Arabic - Iraq
 3          0c01        Arabic - Egypt
 4          1001        Arabic - Libya
 5          1401        Arabic - Algeria
 6          1801        Arabic - Morocco
 7          1c01        Arabic - Tunisia
 8          2001        Arabic - Oman
 9          2401        Arabic - Yemen
10          2801        Arabic - Syria
11          2c01        Arabic - Jordan
12          3001        Arabic - Lebanon
13          3401        Arabic - Kuwait
14          3801        Arabic - United Arab Emirates
15          3c01        Arabic - Bahrain
16          4001        Arabic - Qatar
 1          0402        Bulgarian - Bulgaria
 1          0403        Catalan - Spain
 1          0404        Chinese – Taiwan
 2          0804        Chinese - PRC
 3          0c04        Chinese - Hong Kong SAR, PRC
 4          1004        Chinese - Singapore
 5          1404*       Chinese - Macao
 1          0405        Czech - Czech Republic
 1          0406        Danish - Denmark
 1          0407        German - Germany
 2          0807        German - Switzerland
 3          0c07        German - Austria
 4          1007        German - Luxembourg
 5          1407        German - Liechtenstein
 1          0408        Greek - Greece
 1          0409        English - United States
 2          0809        English - United Kingdom
 3          0c09        English - Australia
 4          1009        English - Canada
 5          1409        English - New Zealand
 6          1809        English - Ireland
 7          1c09        English - South Africa
 8          2009        English - Jamaica
 9          2409        English - Caribbean
10          2809        English - Belize
11          2c09        English - Trinidad
12          3009*       English - Zimbabwe
13          3409*       English - Philippines
 1          040a        Spanish - Spain (Traditional Sort)
 2          080a        Spanish - Mexico
 3          0c0a        Spanish - Spain (Modern Sort)
 4          100a        Spanish - Guatemala
 5          140a        Spanish - Costa Rica
 6          180a        Spanish - Panama
 7          1c0a        Spanish - Dominican Republic
 8          200a        Spanish - Venezuela
 9          240a        Spanish - Colombia
10          280a        Spanish - Peru
11          2c0a        Spanish - Argentina
12          300a        Spanish - Ecuador
13          340a        Spanish - Chile
14          380a        Spanish - Uruguay
15          3c0a        Spanish - Paraguay
16          400a        Spanish - Bolivia
17          440a        Spanish - El Salvador
18          480a        Spanish - Honduras
19          4c0a        Spanish - Nicaragua
20          500a        Spanish - Puerto Rico
 1          040b        Finnish - Finland
 1          040c        French - France
 2          080c        French - Belgium
 3          0c0c        French - Canada
 4          100c        French - Switzerland
 5          140c        French - Luxembourg
 6          180c*       French - Monaco
 1          040d        Hebrew - Israel
 1          040e        Hungarian - Hungary
 1          040f        Icelandic - Iceland
 1          0410        Italian - Italy
 2          0810        Italian - Switzerland
 1          0411        Japanese - Japan
 1          0412        Korean (Extended Wansung) - Korea
 2          0812        Korean (Johab) - Korea
 1          0413        Dutch - Netherlands
 2          0813        Dutch - Belgium
 1          0414        Norwegian - Norway (Bokmal)
 2          0814        Norwegian - Norway (Nynorsk)
 1          0415        Polish - Poland
 1          0416        Portuguese - Brazil
 2          0816        Portuguese - Portugal
 1          0417*       Rhaeto-Romanic - Rhaeto-Romanic
 1          0418        Romanian - Romania
 2          0818*       Romanian - Moldavia
 1          0419        Russian - Russia
 2          0819*       Russian - Moldavia
 1          041a        Croatian - Croatia
 2          081a        Serbian - Serbia (Latin)
 3          0c1a        Serbian - Serbia (Cyrillic)
 1          041b        Slovak - Slovakia
 1          041c        Albanian - Albania
 1          041d        Swedish - Sweden
 2          081d        Swedish - Finland
 1          041e        Thai - Thailand
 1          041f        Turkish - Turkey
 1          0420*       Urdu - Urdu
 1          0421        Indonesian - Indonesia
 1          0422        Ukrainian - Ukraine
 1          0423        Belarussian - Belarus
 1          0424        Slovene - Slovenia
 1          0425        Estonian - Estonia
 1          0426        Latvian - Latvia
 1          0427        Lithuanian - Lithuania
 0          0028
 1          0429        Farsi - Iran
 1          042a        Vietnamese - Vietnam
 0          002b
 0          002c
 1          042d        Basque - Spain
 1          042e*       Sorbian - Sorbian
 1          042f*       Macedonian - Macedonian
 1          0430*       Sutu - Sutu
 1          0431*       Tsonga - Tsonga
 1          0432*       Tswana - Tswana
 1          0433*       Venda - Venda
 1          0434*       Xhosa - Xhosa
 1          0435*       Zulu - Zulu
 1          0436        Afrikaans - South Africa
 0          0037
 1          0438        Faeroese - Faeroe Islands
 1          0439*       Hindi - Hindi
 1          043a*       Maltese - Maltese
 1          043b*       Saami - Saami (Lappish)
 1          043c*       Gaelic - Scots
 2          083c*       Gaelic - Irish
 1          043d*       Yiddish - Yiddish
 1          043e*       Malay - Malaysian
 2          083e*       Malay - Brunei
 0          003f
 0          0040
 1          0441*       Swahili - Kenya


Packaging and Distributing Software

A Java package is a collection of classes that share a common namespace. Packages are easier to work with when they are encapsulated in a single file. The Microsoft SDK for Java provides tools for archiving packages in two formats (cabinet files and distribution units), and a package manager that can be used in conjunction with Microsoft® Internet Explorer to download and install packages.

This section contains the following topics:

Package Management Overview provides a brief history of package management and describes the code downloading mechanisms of Microsoft® Internet Explorer 3.0 and 4.0 or later.

Guidelines for Making Java Code Trusted describes the factors that must be considered to set the correct level of trust on your Java code.

Creating and Using Cabinet Files describes how to create and use cabinet files.

Creating and Using Distribution Units describes how to create and use distribution units, which is the preferred method for distributing code using Microsoft® Internet Explorer version 4.0 or later.

Signing Cabinet Files with Java Permissions describes how to include Java permission information in the signature of a cabinet file.

Java Package Manager describes the package management services provided by the Microsoft SDK for Java.

Automatically Updating the Microsoft VM describes how to use the <OBJECT> tag in a Web page to automatically download and install the most recent Microsoft virtual machine.


Package Management Overview

A Java package is a collection of classes that share a common namespace. For example, if a class named test.java contains the line package com.ms.fx, the full name of the compiled class will be com.ms.fx.test. Packages are the building blocks of Java applications. The Java core libraries are a set of packages: java.lang, java.io, and so on.

Early adopters of Java realized that packages would be easier to work with if they could be encapsulated in a single file. The Java community chose to use the public-domain PKZIP archiving standard to encapsulate Java packages. The PKZIP archive format remains the de facto standard for delivering Java packages. Two other packaging standards are also now available to address the packaging requirements of Java applications: the Sun Microsystems Java Archive (JAR) standard and the Microsoft Cabinet File (.cab) standard.

The Java Archive Standard

The JAR standard appeared in Java Development Kit (JDK) version 1.1. .jar files continue to use the PKZIP archiving standard, but add a manifest component to the Java class files in the archive. The manifest file provides a way to individually digitally sign each class file. Signature files are added in a META-INF directory inside the .jar file.

Compression in .jar files is done on a file-by-file basis. This method of compression can be inefficient because Java class files are often too small to benefit from individual compression.

The Cabinet File Standard

The cabinet file (.cab) standard was initially used to package Microsoft® Windows® 95 and other products. Cabinet files have since become Microsoft's standard archive format. Cabinet file compression first concatenates all files into a large block and compresses the block, a method similar to the TAR/GZIP archiving standard used on UNIX platforms. This method of compression significantly increases the compression of Java packages.

The Microsoft Internet Explorer 3.0 Code Download Mechanism

Microsoft® Internet Explorer 3.0 includes a code download feature to allow web distribution of software using cabinet files. To use the code download feature, you first create an inner cabinet with all the files needed for the application. Next, you write a master .inf file to describe how to install the files in the cabinet file. Finally, you place both the .inf file and the inner cabinet file into an outer cabinet file, which you can then use for download.

The OBJECT tag in an HTML file specifies a cabinet file for download. When Internet Explorer detects the OBJECT tag, it checks for a current version of the cabinet file on the user's system. If it is not there, Internet Explorer downloads the cabinet file and installs it according to the instructions in the enclosed .inf file.

Cabinet files should be digitally signed before being made available for download. The cabinet standard does not support individually signing each class file—the signature on the cabinet file is assumed to apply to all the files in the archive.

Note You are not limited to using the cabinet format for code downloading. Other archive formats can be used as long as there is some method for digitally signing the archive.

The Microsoft Internet Explorer 4.0 Solution—Distribution Units

Code download in Microsoft® Internet Explorer 3.0 relies on registry entries to determine if a particular archive (.cab) is installed and, if it is, what version is installed. Version information is maintained at the cabinet-file level (it does not extend to individual packages). The Internet Explorer 3.0 code download mechanism does not uninstall packages or supply version information to the Microsoft virtual machine (Microsoft VM).

Internet Explorer 4.0 or later addresses these limitations with a more advanced transport for code download: the Distribution Unit (DU). DUs have version numbers that are checked by the browser's code download feature to see if they should be downloaded. Each DU contains a list of all the packages and applications inside the DU. This list, called an Open Software Distribution manifest (OSD), also contains version and security information.

A powerful feature of OSDs is that they can be nested inside other OSDs. This allows a single DU to act as a front-end for a multiple component application. DUs can also be delivered with push technology. A push channel can check to see if the client has the latest version of content and update the client, if necessary. Push is superior to standard browsing from the user’s point of view because the user does not have to actively check for updates (the issues are largely the same from a package management viewpoint).

The Microsoft SDK for Java includes the dubuild utility, used to create DUs. See Creating and Using Distribution Units for details on using dubuild to create DUs.


Guidelines for Making Java Code Trusted

This section describes the factors you should consider when determining the correct level of trust to give your Java code so that it will execute in Microsoft® Internet Explorer. The following topics describe these factors:

The Meaning of Trusted Code
The Class Loader
Asserting Permission in Your Java Code
Creating a Cabinet File
Digitally Signing a Cabinet File
HTML Tags to Reference Signed Cabinet Files

For information on the trust-based security model, see Security.


The Meaning of Trusted Code

The term trusted means that the code is no longer confined to the Java "sandbox." The sandbox restricts untrusted coded from successfully performing trusted operations such as calling native code, using COM, using Microsoft® J/Direct™, connecting to remote machines, printing, using JDBC, and creating top-level windows that do not use the applet warning.

For classes to run with permissions above the sandbox level, they must be delivered to the client machine inside a signed cabinet file. The cabinet file signature must specify the permissions that the contained classes require. There are three basic permission levels that can be assigned: High (for untrusted code), Medium (for partially trusted code), and Low (for fully trusted code). Special considerations apply when a cabinet file contains ActiveX controls. For details on these permission levels and what they allow code to do, see Cabinet File Permission Levels.


The Class Loader

The class loader controls much of the security and access granted to a class. For more information, see How the VM Searches for Classes. With this information, you can make a more informed decision about which method of gaining additional permissions is most suitable for your project.


Asserting Permission in Your Java code

It is important to know when, why, and how to assert permission in your Java code. An applet, even if it is fully trusted, must assert permission in cases where there will be an untrusted caller above it on the call stack. This can occur if the applet performs trusted operations in the applet's default constructor, in the init, start, stop, or destroy methods, or in a method called by a script.

Security Exceptions

In the Microsoft virtual machine (build 2252 or higher), the security manager crawls the call stack when an applet is run from a signed cabinet file. When trusted operations are performed, the security manager first ensures that the object is trusted to perform the operation, and then crawls the call stack to ensure that all callers are also entrusted to make the call. During this process, the security manager may throw one of the following exceptions:

  • A SecurityExceptionEx[Host] occurs if the Web browser invokes a method that performs a trusted operation and that method did not first assert its permission to perform the operation. This situation occurs if your applet performs trusted operations in the applet’s default constructor, in the init, start, stop, or destroy methods without first asserting its permissions.

  • A SecurityExceptionEx[Unknown] occurs if the script engine invokes a method that performs a trusted operation and that method did not first assert its permissions to perform the operation. This situation occurs if your applet has a public method called by Microsoft® Visual Basic® Scripting Edition (VBScript) or Microsoft® JScript® and that method performs trusted operations without first asserting its permissions.

  • A "java.lang.SecurityException: J/Direct method has not been authorized for use on behalf of an untrusted caller" exception occurs if the Web browser or script engine invokes a method that makes a J/Direct call, and that method did not first assert its permission to perform the operation.

Asserting Permission

You can do one of the following to prevent these exceptions:

  • Assert your permission using the PolicyEngine class.

  • Spawn a separate thread to perform the trusted operation, giving the thread permission to perform the operation.

Using the assertPermission(PermissionId pid) method in the PolicyEngine class prevents the security manager from crawling the call stack and enables your applet to perform trusted operations even when methods on the call stack are not trusted. You should only assert permissions if you are sure an untrusted member of the call stack cannot harm the user’s system.

A logical place to assert permissions is at the beginning of the method that is making the trusted call. Once this method returns, subsequent public methods called from outside the VM must also assert permission before making trusted calls.

The PermissionID class has predefined granular permissions, such as NETIO, FILEIO, and so forth. To grant full permissions to the applet, use the SYSTEM permission. This is required for calling J/Direct, COM, and native methods.

Example

The following sample applet demonstrates reading a character from a Web page, which is a trusted operation. This example must be trusted either by placing the file in a signed cabinet, running the project from Microsoft® Developer Studio®, or by placing the class in the class path.

 import com.ms.security.*;

    import java.applet.Applet;
    import java.net.*;
    import java.io.*;
    import java.awt.*;

    public class myApplet1 extends Applet {
      TextField message=null;

      public myApplet1() {
        message=new TextField();
        setLayout(new BorderLayout());
        add("Center",message);
      }

 public void init()
 {
    /* Our init function needs to read a character from a URL, which is a
       trusted operation. We assert NET permission to stop the stack
       crawling since the Web page isn't trusted. The applet must be
       signed so the init() function has permission to perform net
       operations.
    */

    try {
      if (Class.forName("com.ms.security.PolicyEngine") != null) {
        PolicyEngine.assertPermission(PermissionID.NETIO);
      }
  } catch (Throwable cnfe) {
  }

 try {
    URL url = new URL("http://www.microsoft.com/");
    DataInputStream dis;
    dis = new DataInputStream(url.openConnection().getInputStream());
    dis.readChar();
    message.setText("Read character.");
  } catch (MalformedURLException mue) {
    message.setText("MalformedURL");
    mue.printStackTrace();
  } catch (Throwable t) {
    message.setText(t.toString());
    t.printStackTrace();
  }
 }
}


Creating a Cabinet File

Before creating a cabinet file, you must decide how you want to distribute your code.

If you want to install your code on the user's machine or if your code must run as trusted, use one of the following methods to create a cabinet file:

  • Use the dubuild tool to create a distribution unit (DU). Distribution units are cabinet files designed for use with the code download feature of Microsoft Internet Explorer 4.0 and later. A DU consists of content files and an automatically-generated Open Software Distribution manifest file (OSD), which contains details on the cabinet contents as well as installation instructions. See Creating and Using Distribution Units for instructions and examples.

  • Use the cabarc tool to create a cabinet file that contains an .inf file. The .inf file, which must be manually created, contains details on the cabinet contents as well as installation instructions. This is the only method that works on Microsoft® Internet Explorer 3.x. For instructions and examples, see Archiving Library Files.

In both cases, code needs to be downloaded only once: on the first visit to the Web page. Subsequent downloads are required only when a newer version of the code becomes available. However, both methods require some permanent space on the user's disk.

If you just want to package your code in a cabinet file for faster downloading upon every visit to your Web page, you can use cabarc to create a cabinet without an .inf file. This provides the benefits of having a single, compressed file download instead of downloading individual class files. This method does not require that you sign the cabinet file if the code does not need to run as trusted. For more information, see Archiving Applets and Multimedia Files.

In all cases, you must use the appropriate HTML tags to reference the cabinet file in your Web page. See HTML Tags to Reference Signed Cabinet Files.


Digitally Signing a Cabinet File

You must sign your cabinet file whenever one of the following conditions apply:

  • When your code must do something outside the Java "sandbox."

  • When you want to install your code to the user's local computer using a Web page.

Use the signcode tool to sign a cabinet file. You can specify one of the three basic security levels (High, Medium, or Low) or you can set custom permissions by creating a permissions .ini file for use with signcode. The finer-grained permissions you can assign in this .ini file enable you to reduce the access allowed to the bare minimum required by your project. For instructions and examples, see Signing Cabinet Files with Java Permissions.

You can use a test certificate when signing your code for development purposes, but you must obtain an actual certificate before deploying your application. Certificates can be obtained from a Certificate Authority. For more information on Microsoft's code-signing technology, see http://www.microsoft.com/security/default.asp This link takes you to a site on microsoft.com.


HTML Tags to Reference Signed Cabinet Files

There are several options for referencing signed cabinet files in HTML.

To download cabinet files with Java code, you can use the cabbase or cabinets parameters with the <APPLET> or <OBJECT> tags. For more information, see Accessing Cabinet Files from Web Pages.

To install code into the Java Package Manager, you must create distribution units and use the useslibrary, useslibrarycodebase, and useslibraryversion parameters with the <APPLET> or <OBJECT> tags. For more information, see HTML Tags to Install DUs.


Creating and Using Cabinet Files

The cabinet format is an efficient way to package multiple files. The cabinet format has two key features: multiple files can be stored in a single cabinet (.cab) file, and data compression is performed across file boundaries, which significantly improves the compression ratio. Cabinet file construction can be designed based on the number of files to be compressed and the expected patterns for gaining access to them (sequential, random, all at once, or a few at a time).

A key concept of the cabinet file is the folder. A folder is a collection of one or more files that are compressed as a single entity. Compressing files in folders instead of individually improves the compression ratio. Random access time suffers, however, because decoding (decompressing) any file in a folder requires that all preceding files in that folder must also be decoded. Because the cabinet format is designed to deliver file content, rather than to stream media, the focus is on maximum compression as opposed to quick decompression.

There are two reasons to use the cabinet technology with Java classes:

  • Archiving applets and multimedia files

    Cabinet files can be used to build Java applets with many classes and graphics or audio files that you would like compressed and that would not be shared by other sites. HTML pages use the <APPLET> tag to access the contents of applet cabinet files.

  • Archiving library files

    Cabinet files can be used to distribute Java class libraries to users so that your classes can be accessed like system classes by Java applets or applications. HTML pages use the <OBJECT> tag to download and access libraries. Note that the library scheme only supports the download and access of class files, not image or audio files. These files should be provided by the applet, not the cabinet file.

The Microsoft SDK for Java provides the cabarc utility that creates, extracts, and lists the contents of cabinet files. Cabarc uses a command-line interface similar to that of popular archiving tools, and supports wildcards and recursive directory searches. For details on this utility's command-line options, see the cabarc section of the Tools Reference.

Note The dubuild utility is an alternative to cabarc when distributing software using Microsoft® Internet Explorer 4.0. The dubuild utility creates distribution units (DUs) that are installed using the Java Package Manager (JPM). For more information, see Creating and Using Distribution Units (dubuild) and Java Package Manager.


Archiving Applets and Multimedia Files

This procedure will help you create a cabinet file for delivering compressed class and multimedia files to a user's system:

  1. Ensure that the %SDKDIR%\Bin directory, which contains Cabarc.exe, is in your path.

  2. Run Cabarc.exe to build a cabinet containing all your files. See the cabarc section of the Tools Reference for this tool's command-line syntax.

  3. Optionally, digitally sign the cabinet file.

    Code-signing is important because it assures users that they can trust your code before placing it on their computers. For more information on trusted code, see Guidelines for Making Java Code Trusted. For information and instructions on signing your code, see Signing a Cabinet File with Java Permissions and http://msdn.microsoft.com/workshop/default.asp This link takes you to a site on microsoft.com.

To access the applet from a Web page, use the <APPLET> tag and the cabbase or cabinets parameters. See Accessing Java Applets for more information.

When creating cabinet files that will be read by the browser from the cabbase parameter, use the default compression mode (MSZIP) and not the LZX (Lempel-Ziv) compression mode. The LZX compression mode is supported by Microsoft® Internet Explorer version 4.0, but not by Internet Explorer 3.x.


Archiving Library Files

When delivering libraries in a cabinet file, the files to be compressed and delivered are archived in one cabinet file called the inner cabinet. This file is itself archived in another cabinet file (called the outer cabinet) with a .inf file. The .inf file, based on the Master.inf template found in the %SDKDIR%\Readmes directory, is used by the setup engine in Microsoft® Internet Explorer. It contains the names of the libraries, where they should be placed, the class identifier used in the HTML <OBJECT> tag, and so on.

The use of the .inf file only pertains to libraries, which are referenced by using the <OBJECT> tag. It does not pertain to applets.

The following topics describe how to create cabinet files for libraries:

Creating a .INF File
Building Cabinet Files for Libraries
For information on the HTML tags to use to download Java libraries from a Web page, see Accessing Java Libraries.


Creating a .inf File

Use the Master.inf file in the %SDKDIR%\Readmes directory as a template for creating a .inf file. The Master.inf file is heavily commented and includes placeholders for required information.

To create your .inf file

  1. Make a copy of the Master.inf file, give it a new name, and open it for editing.

  2. Include the name of the inner cabinet file that contains your classes. Replace CabFileName.cab with your class cabinet name in the following line:
    run=extrac32.exe /e /a /y /l %49000% CabFileName.cab
  3. Include the name of the .inf file that you are using. Replace Master.inf with the name of your .inf file as indicated in the following code example:
    [hook2]

; Change the name of master.inf to the name you are assigning this
; file. Leave the second line alone.

InfFile=master.inf
InfSection=RegistryData
  4. Include a unique ClassId, generated by running Guidgen.exe from the %SDKDIR%\Bin directory. The following code excerpt from the Master.inf template file sets the identifier:
    [Strings]
; Running guidgen in the SDK generates the ClassId you need to fill
; in here. This classId also goes in the OBJECT tag.
; Don't forget the set braces!

ClassId="{99999999-9999-9999-9999-999999999999}"
  5. Include the name of your libraries. The following code excerpt from the Master.inf template file sets the library name:
    ; Put the name by which your packages should be referred to
; (for example, "My Text Viewer") here.

PackageName="name"
  6. Decide whether to place the libraries in the \Lib or \TrustLib directory. In the .inf file, find the lines that determine whether the libraries are placed in the %Windir%\Java\Lib or %Windir%\Java\TrustLib directory and comment out the line that does not apply. The following code sample shows the default that is in Master.inf:
    ; If you use one of these, you will use exactly one.

HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InProcServer32","Lib",,
"%49000%"
;HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InProcServer32",
"TrustedLib",,"%49000%"
  7. Optionally, you can also include the following information:
    • A version number. Version numbers are in the form a,b,c,d (that is, 1,0,5,10). This prevents downloading the same library if the user has the latest version. (This is a recommended practice.) The following code excerpt from Master.inf sets the version number:
      ; Replace <aa...> with the version number (like 1,0,0,1) of this
; version of your library. This is so that when you want to update
; your libraries, you can change the version rather than the
; classId and its associated problems. If the version number here
; and in the OBJECT tag match the version already stored on the
; user's computer, it will not download the classes again, which
; also saves time and energy.

HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InstalledVersion",,,
"aa,bb,cc,dd"
    • The name of one of the class files in your package. This file can be examined by the browser to determine if the library files have already been installed on the system. This is illustrated in the following code example:
      ; Here, replace <file name> with the name of one of the
; class files in your package, including the virtual path
; (specified in classpck.ddf)
; to that file. This will make sure that the classes exist on the
; user's system; if they don't, they will be downloaded,
; regardless of version numbers.

HKLM,"Software\Classes\CLSID\%ClassId%\InstalledVersion","Path",,
"%49000%\<filename>"
    • The names of any native code files that you want to install from your outer cabinet file (the one containing the .inf and .cab file). These files are installed automatically in the %Windir%\System[32] directory. The following code excerpt from Master.inf sets the code names:
      ;; If you are installing native code, you will want to uncomment
;; all the lines in the remainder of this section, except for the
;; ones that are descriptive (and have two semicolons).
; CopyFiles=OtherFiles

;[DestinationDirs]
;OtherFiles=11

;[OtherFiles]
;; List the name of each file (delimited by returns) here.
;; Just list the local name--no need for paths, and so on. Example:
;; foo1.dll,,,32
;; foo2.dll,,,32

;[SourceDisksFiles]
;; For each name listed in the above section, you will want to put
;; <file name>=1 on this list. So it would look like this:
;; foo1.dll=1
;; foo2.dll=1

;[SourceDisksNames]
;1=%PackageName%,"",0

.inf File Example

The following code excerpt shows the mandatory edits made in a .inf file called Sample.inf:

[hook1]

; In this line, replace CabFileName.cab with the inner .cab file name
; that contains your classes.

run=extrac32.exe /e /a /y /l %49000% MyClasses.cab

[hook2]

; Change the name of master.inf to the name you are assigning to this
; file. Leave the second line alone.

InfFile=Sample.inf
InfSection=RegistryData

[Strings]
; Running Guidgen in the SDK generates the ClassId you need to fill
; in here. This classId also goes in the OBJECT tag.
; Don't forget the set braces!

ClassId="{4439E200-6FCC-11d0-89AA-00A0C9054129}"

; Put the name by which your packages should be referred to
; (for example, "My Text Viewer") here.

PackageName="My Sample Java Classes"


Building Cabinet Files for Libraries

To create a cabinet file to install Java libraries on a user's computer

  1. Ensure that the %SDKDIR%\Bin directory, which contains Cabarc.exe, is in your path.

  2. Run Cabarc.exe to build the inner cabinet that contains all your class files. For command-line syntax for this tool, see the cabarc section of the Tools Reference. It is a good idea to put your vendor name as the package name preceding all your classes to avoid having them overwritten by other installed classes. That is, your classes should be in the form suggested by the following example (where "vendor" is your unique vendor name):
    vendor.util.loader.class
vendor.util.builder.class
vendor.applet.start.class

    For example, your company is called MyCompany. You have a package called widgets located on your development computer at C:\JavaCode\MyCompany\Widgets\*.class. You want to install this package in the user's %Windir%\Java\Lib directory. You would change to the directory C:\JavaCode\ and run cabarc as follows.

    cabarc -r -p -P javacode\ n MyClasses.cab MyCompany\*.*

    In this syntax, -r tells cabarc to recursively archive everything under MyCompany, maintain the directory structure (-p), strip javacode from the directories (-P javacode\), and create a cabinet file called MyClasses.cab.

    When the package is installed on the user's system, all classes will be placed under the %Windir%\Java\Lib unless the .inf file is modified to place them in the TrustLib directory.

  3. Create a .inf file from the Master.inf template in the %SDKDIR%\Readmes directory as described in Creating a .INF File. This file sets up the layout and instructions for installing the libraries. The Master.inf file is heavily commented and includes placeholders for required information.

  4. Run Cabarc.exe again to build the outer cabinet file that contains the class cabinet, the .inf file, and any other files you might want to include. The following example creates an outer cabinet file called OuterCab.cab, which includes the Sample.inf and the MyClasses.cab files:
    cabarc  n OuterCab.cab MyClasses.cab Sample.inf
  5. Optionally, digitally sign the cabinet file.

    Code-signing is important for users so they know to trust your code before placing it on their computers. The default settings in Microsoft® Internet Explorer will reject unsigned code. For more information on trusted code, see Guidelines for Making Java Code Trusted. For information and instructions on signing your code, see the Signing a Cabinet File with Java Permissions and http://msdn.microsoft.com/workshop/default.asp This link takes you to a site on microsoft.com.


Accessing Cabinet Files From Web Pages

The HTML tags and parameters used to access cabinet files from Web pages differ depending on whether the cabinet contains applets or libraries.

Accessing Java Applets

To access Java applets, use the cabbase parameter in an <APPLET> tag to point to the .cab file. If the applet is not already present on the user's system, the .cab file is downloaded, the contents are extracted, and the applet is started.

To use the <APPLET> tag, set the parameters as shown in the following example:

<APPLET CODE="sample.class" WIDTH=100 HEIGHT=100>
<PARAM NAME="cabbase" VALUE="vendor.cab">
</APPLET>

Using the cabbase parameter does not conflict with codebase or any other parameters necessary for other browsers. Using cabbase, along with the other tags, allows Internet Explorer 3.0 and other browsers that support cab files to use them without impeding the ability of other browsers to download and execute applets.

You can also use the cabinets parameter to download multiple cabinet files from the same <APPLET> tag. This parameter can be used interchangeably with cabbase on Internet Explorer 4.0 or later. For example:

<APPLET CODE-"sample.class" WIDTH=100 HEIGHT=100>
<PARAM NAME="cabinets" VALUE="firstcab.cab, secondcab.cab">
</APPLET>

Accessing Java Libraries

To access Java libraries, use the <OBJECT> tag to point to the .cab file. The codebase attribute can specify a version number, which enables you to download and install libraries if the version on the user's system is out-of-date. Use the following HTML syntax:

<OBJECT CLASSID="<classid>" CODEBASE="<path to cab>#Version=x,x,x,x">
</OBJECT>

For example:

<OBJECT
    CLASSID="clsid:12345678-9abc-def1-1234567890ab"
    CODEBASE="cabs/vendor.cab#Version=1,0,0,12">
</OBJECT>

With this syntax, if the classes in the current version are not already present on the user's system, the .cab file is downloaded, and the contents are extracted and placed in the appropriate location.

Both the ClassId and the version number are also stored in the .inf file in the outer cabinet file. Including the version number is optional but highly recommended. This permanently installs the classes on the user's system—use this only for libraries.

After libraries are installed in this manner, <APPLET> tags can refer to the classes placed in the library specified by Cabs/Vendor.cab. Those applets work normally with classes brought in through cabbase or codebase.


Creating and Using Distribution Units

Distribution units (DUs) provide a new way of distributing software that is supported by the code download feature of Microsoft® Internet Explorer version 4.0 or later. Traditionally, Java software distribution has been inefficient. You would archive classes in a .zip file, and then archive the .zip in another .zip file along with any documentation or other included files. Users would unpack the first archive (but not the second), add the included .zip to a path, set their class path, and reboot.

DUs make this approach unnecessary. A distribution unit is a cabinet file (.cab) that contains an Open Software Distribution manifest (OSD) file (also known as a Distribution Unit Profile [DUP]), as well as content files. The OSD manifest file, which is written in XML, contains details on the version of the DU, the contents and their versions, and installation instructions for the Java Package Manager (JPM). The DUs must still be created with a hierarchical directory, as with augmented cabinet files, but installation requirements are handled by Internet Explorer and the JPM. The distribution is provided through an HTML <APPLET> tag and useslibrary parameters.

The Microsoft SDK for Java includes a utility, dubuild, that writes the OSD file and places it in a cabinet file archive with any specified contents. The dubuild utility is similar to cabarc, but uses the OSD manifest instead of .inf files.

Because DUs written with dubuild (the OSD manifest in particular) are not recognized by earlier versions of Internet Explorer, creating DUs for Internet Explorer 3.0 is more involved. You can follow the Master.inf template and procedures as you would for creating a cabinet file, then add the .inf to your package, and finally use the dubuild utility to package it. By default, the dubuild utility uses LZX compression, but Internet Explorer 3.0 uses MSZIP compression. Use the /Z command-line option to build DUs with MSZIP compression.

Although this section focuses specifically on using dubuild to distribute and install Java packages with the Microsoft Java Package Manager, dubuild is a general distribution standard; it can be used to distribute applications, libraries, and native code.


HTML Tags to Install DUs

The HTML tags used to install DUs are similar to any applet script. The <APPLET> tag specifies the applet to run, and the <PARAM> tags supply additional information to Internet Explorer about the name and version of the DU that contains the Java classes needed to run the applet. There are three parameters associated with the <APPLET> tag:

  • The useslibrary parameter specifies the friendly name of the DU. This name is registered with Internet Explorer and is used in conjunction with the DU's version number to indicate presence or absence of the contents of the DU in the Java Package Manager.

  • The useslibrarycodebase parameter specifies a URL and cabinet file archive to download (in this example, the cabinet file is local), if the DU is not already present on the current system.

  • The useslibraryversion parameter specifies the version number of the DU. This is used to update the Java Package Manager when new versions, or split DUs, are encountered.

For example:

<APPLET
  code=com.ms.JPMBrowser.BrowserApplet
  width=200
  height=200>
<PARAM NAME=useslibrary VALUE="JPM Browser">
<PARAM NAME=useslibrarycodebase VALUE="jpm.cab">
<PARAM NAME=useslibraryversion VALUE="1,1,23,0">
</APPLET>


Installing Distribution Units

The Java Package Manager and Microsoft® Internet Explorer go through the following steps before a DU is installed.

  1. The Java Package Manager first determines if the DU is already registered by checking the friendly name of the DU, which is specified as a string in the useslibrary parameter.

    If the DU is not present on the current system, the appropriate cabinet file archive is downloaded from the URL specified by the useslibrarycodebase parameter.

    If the DU is present on the current system, the version number, specified in the useslibraryversion parameter, is checked to determine whether the DU is current with the version offered. This eliminates the need to download, open, and examine the contents of the archive to determine if it is current (as is the case when you use <OBJECT> tags with Internet Explorer 3.0).

  2. If the local version number matches or is newer than the offered version, no action is performed. If the local version is older, the DU is downloaded and the OSD manifest is examined.

  3. Internet Explorer and the JPM install the included packages according to the OSD.

  4. The applet is executed.

Note Internet Explorer 3.x does not recognize useslibrary and its associated parameters. You must use the <APPLET> and <OBJECT> tags and their parameters to emulate this distribution.

Using DUs to distribute code enables users to run applets without constantly downloading them in a networked environment. For example, where once you had to interact with security managers every time you visited a site and encountered a signed cabinet file or code, you can now install the code into the Java Package Manager on the first visit and avoid subsequent security interactions; the code is already installed. If the DU's cabinet file is signed, all security and permissions apply the first time the cabinet is downloaded.


Packaging a Java Library with Dubuild

The following tutorial shows how to install a set of Java libraries into the Microsoft virtual machine using a distribution unit created with the dubuild utility. The tutorial uses JPMBrowser as the example package.

To create and distribute DUs

  1. Decide on a package name.

  2. Create the DU with the dubuild utility.

  3. Test install the DU with an HTML page.

Decide on a Package Name

You should choose a meaningful and descriptive name for your package and use the com.company.packagename naming convention. The JPMBrowser example is a Microsoft library for Java so it uses the com.ms. prefix. The resulting package name is com.ms.JPMBrowser.

Make sure your directory structure reflects the package name. In the JPMBrowser example below, the working directory that contains the .class files is C:\projects\JPMBrowser\com\ms\JPMBrowser.

Create the Distribution Unit

  1. From a DOS prompt, change your working directory to the top-level project directory. For this example, it is C:\projects\JPMBrowser:
    C:\>cd \projects\JPMBrowser
  2. Run the dubuild utility, found in the %SDKDIR%\Bin directory:
    C:\..\JPMBrowser>dubuild jpm.cab . /D "JPM Browser" /I *.class /V 1,1,23,0

    In this command, the /D option specifies a friendly name for the DU, the /I option specifies that only Java class files are included, and the /V option specifies the version number.

  3. Run extract /D to view the resulting cabinet file and to verify that the proper files are included with the correct directory paths:
    C:\projects\JPMBrowser>extract /D jpm.cab
Microsoft (R) Diamond Extraction Tool - version (16) 1.00.0530 (04/3/95)
Copyright (c) Microsoft Corp 1994-1995. All rights reserved.

 Cabinet jpm.cab

07-30-1997  5:50:32p ----    295 JPM Browser.osd
07-20-1997  6:38:42p A---  1,960 com\ms\JPMBrowser\JPMPanel.class
07-20-1997  6:38:42p A---    678 com\ms\JPMBrowser\BrowserFrame.class
07-20-1997  6:38:42p A---  1,289 com\ms\JPMBrowser\BrowserApplet.class
                 4 Files   4,222 bytes

The Open Software Distribution (OSD) file that is packaged with the DU is automatically generated by the dubuild utility. The OSD file contains a list of the included Java packages and sets the version number to be 1.1.23.0. Note that when specifying version numbers on the command line, the version number must be comma-separated.

Make sure that your packages are in the appropriate (in this case, com\ms\JPMBrowser) subdirectory, as shown above.

Test Install the DU with an HTML Page

To test the installation of the DU, write an HTML page that installs and runs the application or applet. The HTML for the JPMBrowser sample applet uses an <APPLET> tag and several special useslibrary parameters. These parameters specify the friendly name, location, and version of the DU as shown in the example below. For more information on the <APPLET> tag and associated parameters, see HTML Tags to Install DUs.

<APPLET
  code=com.ms.JPMBrowser.BrowserApplet
  width=200
  height=200>
<PARAM NAME=useslibrary VALUE="JPM Browser">
<PARAM NAME=useslibrarycodebase VALUE="jpm.cab">
<PARAM NAME=useslibraryversion VALUE="1,1,23,0">
</APPLET>

You can place this applet in an HTML file that is in the same directory as your cabinet file, or you can specify a remote location for the cabinet file in the useslibrarycodebase parameter. To test the installation, browse the HTML page in Microsoft® Internet Explorer. It should install the cabinet file and show the applet on the page.


Split Distribution Units

The dubuild utility can also create split, or delta, DUs. This functionality is useful for updated versions of software where some of the files in the original DU have been modified (a service pack, for example).

In order to build a split DU, you must specify a new (version 2) cabinet file, the original path, and the original DU. Whole packages that contain changed files end up in the new DU. If there are no unchanged packages, everything ends up in the new DU. This command creates its own cab file, named ~NEWCAB.cab, which holds the unchanged packages. The OSD in NEWCAB.cab does not have a reference to the original .cab file. A command line to build a split DU follows:

C:\..\>dubuild newcab.cab . /P oldcab.cab /M /I *.class

When Internet Explorer encounters a split DU in the useslibrarycodebase parameter, it follows the same steps previously described, with an additional step. If the newer version of the split DU is not present on the local system, it will be downloaded, and the OSD manifest is examined. If the earlier version of the software, pointed to by the OSD file, does not also exist on the local system, it is downloaded as well. However, if the earlier version of the split DU is already present on the system, no further action is performed.


Signing Cabinet Files with Java Permissions

The Microsoft SDK for Java includes signcode, a utility that enables you to sign cabinet files with Java permissions. While encoding permissions inside an applet is optional, it provides the following additional benefits over regular signing:

  • Applets and controls can be granted only the specific permissions they need.

    If an applet is signed in the "old" style (without Java information), the user must choose between running it in the Java "sandbox," or allowing it to be fully trusted. For example, permission signing enables applets to request permission to store only temporary files on the client's disk. Users of a permission-signed applet can allow it to run without worrying that it will have full access to their system.

  • Fewer dialog boxes are presented to the user.

    When Microsoft® Internet Explorer zones are used, applets might automatically receive some permissions when they are downloaded from a certain zone. When an applet is signed with the permissions it needs, the user will not be queried if the zone automatically grants the permissions.

Using signcode, you can sign a cabinet file with one of three security levels. They work together with the zone security levels Microsoft® Internet Explorer to determine what an applet can do.

This section includes the following topics:

Cabinet File Permission Levels describes the three security levels as well as special considerations for cabinet files containing Microsoft® ActiveX® Controls.

Internet Explorer Zones describes the four Microsoft® Internet Explorer zones and the security levels that can be assigned to each.

Determining What an Applet Can Do describes how cabinet file and Internet Explorer zone security levels work together to determine what an applet can do.

Signing a Cabinet File with Java Permissions provides a brief description of the signcode tool and a tutorial on signing cabinet files.

For information on trusted code, see Guidelines for Making Java Code Trusted.


Cabinet File Permission Levels

The signcode utility enables you to sign a cabinet file at three different security levels, described in the following table. These permission levels work in conjunction with Microsoft® Internet Explorer zones to determine what an applet can do.

Security levels

High | The High security level ensures that all Java code contained in the cabinet file will run in the Java "sandbox." High is the most stringent level of signing, and is equivalent to the same permissions that an unsigned applet is granted. Signing a cabinet file with High ensures that it will never be able to do more than it would in the sandbox, regardless of where the code comes from and what the user allows it to do. A cabinet file signed High will always be allowed to run without any user intervention.
Medium | The Medium security level places the same restrictions on the applet as High, with a few exceptions. Applets signed with the Medium level request user-directed file I/O as well as the ability to store up to 1 MB of data in the client computer's scratch space. This storage can be accessed through the com.ms.io.clientstorage API. A cabinet file signed Medium will run without intervention in Low and Medium security zones. Because the requested permissions are greater than a High security zone can automatically give, a Medium signed cabinet file will prompt the user before allowing code to run in a High security zone.
Low | The Low security level means the code in the cabinet file is requesting to be fully trusted. Only a zone set at Low security can grant this much access without first asking the user. The other two zones prompt the user before running the applet.

Cabinet Files and ActiveX

The security levels described previously apply to cabinet files that contain only Java code. When downloaded using the useslibrary parameter, however, cabinet files may contain both Java code and Microsoft® ActiveX® Controls. Because ActiveX controls must be fully trusted to run, they are treated differently from Java code.

For ActiveX controls to run when they are in a cabinet file that uses Java Permission signing, the signature must specify that the cabinet file contains ActiveX controls. You do this by specifying the LowX, MediumX, or HighX flags. These three flags have the same meaning as their respective flags without the X (Low, Medium, and High). However, if you include ActiveX controls in the cabinet file, they will be denied, allowed to run, or query the user, based on the security settings of the zone.

If your cabinet file has only ActiveX controls, do not use the Java signing method. Instead, use signcode without JavaSign.dll.

The following table summarizes the security levels to use based on the contents of the cabinet file.

Cabinet file contents | Security level
Java code only | High, Medium, or Low
Mixed Java code and ActiveX controls | HighX, MediumX, or LowX
ActiveX controls only | Do not sign with Java permissions; use signcode without JavaSign.dll


Internet Explorer Zones

Zones are a way of reducing the complexity of system security by assigning security policies to entire groups of sites.

Microsoft® Internet Explorer 4.0 or later divides your Internet world into zones, so you can assign specific security settings to each zone, and then assign Web sites to a zone with a suitable security level. The name of the current zone appears on a status bar in the lower-right corner. Whenever you attempt to open or download content from the Web, Internet Explorer checks the security settings for that Web site's zone. Internet Explorer provides four zones.

Zones

Local Intranet | Addresses that don't require a proxy server (those listed in the Proxy Settings as not requiring a proxy server). The addresses included in this zone are defined by the system administrator in the Internet Explorer Administrator's Kit (IEAK). The default security level for the Corporate Intranet zone is Low.
Trusted Sites | Sites you trust enough to require low security before downloading or running files from the Internet. You can assign sites to this zone. By default, the security level for the Trusted Sites zone is Low.
Restricted Sites | Sites you don't trust, requiring medium or high security before downloading or running files from the Internet. You can assign sites to this zone. By default, the security level for the Restricted Sites zone is High.
Internet | By default, the Internet is anything not on your computer, the Intranet, or assigned to any other zone. The default security level for the Internet zone is Medium.

Each zone can be set to a specific security level. The security level applies to all code downloaded from sites within the zone.

Security levels

High security | Java applets will run in the sandbox without intervention from the user. Any requests beyond the sandbox will query the user. ActiveX controls will never be allowed to run.
Medium security | A zone set for Medium security will allow applets to have up to 1 MB of scratch space on the client computer, if it is requested in the cabinet file signature. Any requests beyond those restrictions will cause the user to be queried. ActiveX controls will also prompt the user before running.
Medium-low security | Available in Internet Explorer 5.0 only. This level is the same as Medium security, but runs most content without querying the user. Unsigned ActiveX controls will not be downloaded.
Low security | A zone set for Low security will allow applets to run fully trusted, if they request to do so in their signature. ActiveX controls will prompt the user before running.
Custom security | The user or the administrator defines Custom security levels. They may also allow ActiveX Controls to run without prompting, whereas the predefined zones do not have that option.

For more information on how zones are configured and used, see the online Help for Internet Explorer. The Microsoft SDK for Java includes a custom permissions editor, cprmedit, that enables you to set Java permissions for specific security zones using a graphical user interface. These permissions are recognized by Internet Explorer 4.0 and later. For more information, see Defining Permission Sets Using Cprmedit.


Determining What an Applet Can Do

When a signed cabinet file is downloaded from a page, the signature is examined to see if it contains permission information. If so, Internet Explorer and the Microsoft virtual machine work together to determine what the applet will be allowed to do. This determination is based on the security level of the zone the cabinet file is downloaded from, the permissions requested in the cabinet signature, and the response of the user, if needed.

If a cabinet file is signed at a certain security level, it will be allowed to run with that level of permission without any intervention from the user, but only if the zone is set at that same level or less secure. However, if a cabinet file is requesting permissions greater than those that can be automatically granted by a zone, the user is presented with a query. If the user agrees to let the applet run, it runs with the signed permissions. Otherwise, the applet will not be allowed to run.

The following table details this behavior.

Zone level | Cabinet files signed with this level
 | High | Medium | Low
High | Runs in High | Query (Yes = Medium) | Query (Yes = Low)
Medium | Runs in High | Runs in Medium | Query (Yes = Low)
Low | Runs in High | Runs in Medium | Runs in Low

If the user is presented with a query and denies the request, the applet will not run.


Signing a Cabinet File with Java Permissions

To sign a cabinet file with Java permissions, use the signcode utility and specify the -j JavaSign.dll option. You can also use the -jp option to specify the exact permissions in the signature.

The command line for signcode with Java permission information is as follows:

signcode [options] -j JavaSign.dll [-jp level] [more options] cabfile.cab

Note the following about this command line:

The -j JavaSign.dll option tells signcode to use Java permission information.

The -jp level option specifies the security level to encode in the cabinet file. The level string must appear immediately after the -j parameter. You can use any of the following flags.

Security Level Flags | Use For
Low, Medium, or High | Cabinet files containing only Java code
LowX, MediumX, or HighX | Cabinet files containing Java code and ActiveX controls

If the –jp option is not specified, a default level of LowX will be used. Note that if your cabinet file contains only ActiveX controls, you should not sign it with Java permissions. See Cabinet File Permission Levels for more information about these security levels.

You can set custom permissions instead of using one of these predefined security levels. Custom permissions must be defined in a permissions .ini file, which can be created by hand or by using the piniedit tool. For additional information on creating the .ini file, see Java Permissions .INI Values Reference. To use a custom permissions file with signcode, use the –jp option and specify the .ini file name instead of the security level. For example:

signcode -j JavaSign.dll -jp SamplePerms.ini MyCabFile.cab

Cabinet File Signing Procedure

The following steps show how to sign a cabinet file with Java permissions using signcode and several other tools provided by the Microsoft SDK for Java.

  1. Create a certificate with the makecert utility.
    C:\..\>makecert -sk MyKeyName -n "CN=My Publisher Name" MyTestCert.cer
  2. Turn your certificate into a test Software Publisher Certificate (SPC) using the cert2spc utility. A valid SPC is obtained from a Certification Authority.
    C:\..\>cert2spc MyTestCert.cer MyTestCert.spc
  3. Use signcode to sign the cabinet file with the permissions. The following command line signs MyApplet.cab with medium permissions, using the key and certificate created previously.
    C:\..\>signcode -j javasign.dll -jp medium -spc MyTestCert.spc
   -k MyKeyName MyApplet.cab
  4. Use the chkjava utility to verify that the appropriate permissions have been correctly encoded in the file.
    C:\..\>chkjava MyApplet.cab

For more information on all the parameters for makecert, cert2spc, signcode, and chkjava, see the Microsoft SDK for Java Tools Reference.


Java Permissions .INI Values Reference

Custom Java permissions can be set by specifying a custom permissions .ini file when using the signcode tool's -jp command line option. These .ini files can be generated by hand, or by using the piniedit tool included with the Microsoft SDK for Java. For more information on setting Java permissions with the signcode tool for Microsoft® Internet Explorer 4.01 (and later), see Signing a Cabinet File with Java Permissions.

When using an .ini file to set custom permissions, you set permission variables to values that define the permissions you want. For an example of the .ini file format accepted by signcode, see Sample Permissions .INI File.

This section provides reference information to help you decide how to set these variables. For each of the following permissions, the variables are listed and the meaning of each variable is described.

ExecutionPermission | ReflectionPermission
ClientStoragePermission | RegistryPermission
FileIOPermission | SecurityPermission
MultimediaPermission | SystemStreamsPermission
NetIOPermission | ThreadPermission
PrintingPermission | UIPermission
PropertyPermission | UserFileIOPermission

For more information on these permissions, see the com.ms.security.permissions package.


INI file Permission Values

This section provides reference information to help you decide how to set the .ini file permission variables.

ExecutionPermission

Variable | Meaning
Unrestricted | If true, any application can be executed.
IncludeNames | These applications can be executed.
ExcludeNames | These applications cannot be executed.

ClientStoragePermission

Variable | Meaning
Limit | The maximum number of bytes of data that can be written.
RoamingFiles | If true, roaming files can be created.
GlobalExempt | If true, the storage limit is an absolute limit. If false, the limit is also bounded by the global storage limit.

FileIOPermission

Variable | Meaning
IncludeRead | These files can be read.
ExcludeRead | These files cannot be read.
IncludeWrite | These files can be written to.
ExcludeWrite | These files cannot be written to.
IncludeDelete | These files can be deleted.
ExcludeDelete | These files cannot be deleted.
ReadFileURLCodeBase | If true, classes that have this permission will have read access to the directory that they were loaded from if that location is a file://URL.

MultimediaPermission

No specific settings are required.

NetIOPermission

Variable | Meaning
IncludeConnectIPs | General communication with the hosts at these IP addresses is allowed.
ExcludeConnectIPs | General communication with the hosts at these IP addresses is not allowed.
IncludeBindIPs | Listening for connections on these local IP addresses is allowed.
ExcludeBindIPs | Listening for connections on these local IP addresses is not allowed.
IncludeMulticastIPs | The multicast groups specified by these IP addresses can be joined.
ExcludeMulticastIPs | The multicast groups specified by these IP addresses cannot be joined.
IncludeConnectHosts | General communication with these hosts is allowed.
ExcludeConnectHosts | General communication with these hosts is not allowed.
IncludeBindHosts | Listening for connections with these hosts is allowed.
ExcludeBindHosts | Listening for connections with these hosts is not allowed.
IncludeMulticastHosts | The multicast groups specified by these hosts can be joined.
ExcludeMulticastHosts | The multicast groups specified by these hosts cannot be joined.
IncludeConnectGlobalPorts | General communication with allowed hosts or IP addresses using the specified ports is allowed.
ExcludeConnectGlobalPorts | General communication with allowed hosts or IP addresses using the specified ports is not allowed.
IncludeBindGlobalPorts | Listening for connections with allowed hosts on the local IP addresses using the specified ports is allowed.
ExcludeBindGlobalPorts | Listening for connections with allowed hosts on the local IP addresses using the specified ports is not allowed.
ConnectToFileURLCodebase | If true, connection permissions are adjusted so that general communication is allowed with the location that the class with this permission is loaded from if that location is a file://URL/codebase.
ConnectToNonFileURLCodebase | If true, connection permissions are adjusted so that general communication is allowed with the location that the class with this permission is loaded from if that location is a non-file://URL/codebase.

PrintingPermission

No specific settings are required.

PropertyPermission

Variable | Meaning
Unrestricted | If true, any system property can be accessed.
AllowedSuffixes | These suffixes indicate system properties that could be accessed based on the following rule: If suffix "x" is listed, you have access to a system property "y" if a second system property named "y.x" exists that is set to true.
IncludedProperties | System properties represented by these WildcardExpressions can be accessed.
ExcludedProperties | System properties represented by these WildcardExpressions cannot be accessed.

ReflectionPermission

Variable | Meaning
PublicSame | If true, access is allowed to public members of any class loaded by the same loader as the class initiating the reflection operation.
PublicDifferent | If true, access is allowed to public members of a non-system class loaded by a different loader than the class initiating the reflection operation.
PublicSystem | If true, access is allowed to public members of any system class.
DeclaredSame | If true, access is allowed to any member of any class loaded by the same loader as the class initiating the reflection operation.
DeclaredDifferent | If true, access is allowed to any member of a non-system class loaded by a different loader than the class initiating the reflection operation.
DeclaredSystem | If true, access is allowed to any member of any system class.

RegistryPermission

Variable | Meaning
IncludeOpen | These keys can be opened.
ExcludeOpen | These keys cannot be opened.
IncludeRead | These keys/values can be read.
ExcludeRead | These keys/values cannot be read.
IncludeWrite | These keys/values can be modified.
ExcludeWrite | These keys/values cannot be modified.
IncludeDelete | These keys/values can be deleted.
ExcludeDelete | These keys/values cannot be deleted.
IncludeCreate | These keys/values can be created.
ExcludeCreate | These keys/values cannot be created.

SecurityPermission

No specific settings are required.

SystemStreamsPermission

Variable | Meaning
SetSysIn | If true, the system stream java.lang.System.in can be set.
SetSysOut | If true, the system stream java.lang.System.out can be set.
SetSysErr | If true, the system stream java.lang.System.err can be set.

ThreadPermission

Variable | Meaning
AllThreadGroups | If true, all thread groups can be accessed.
AllThreads | If true, all threads can be accessed.

UIPermission

Variable | Meaning
ClipboardAccess | If true, the system clipboard can be accessed.
TopLevelWindows | If true, top-level windows can be created.
NoWarningBanners | If true, top-level windows do not require warning banners.
FileDialogs | If true, file dialog boxes can be created.
EventQueueAccess | If true, the AWT event queue can be accessed.

UserFileIOPermission

Variable | Meaning
CanRead | If true, user-directed read operations are allowed.
CanWrite | If true, user-directed write operations are allowed.


Sample Permissions .INI File

This is a sample .ini file, complete with comments, that shows you the format accepted by signcode for special permissions. You can generate your own .ini file by using this one as a template or by using the piniedit tool included with this SDK. Each section represents one of the com.ms.security.permissions classes.

;
; PermissionDataSet INI encoding
;
; Sample INI File
;
;

; A semi-colon (;) at the beginning of a line signifies a
; comment to the end of the current line.

; AllowActiveX tells the sign tool to sign with full ActiveX
; permissions, in addition to any other permissions.
;[AllowActiveX]

; If the FullyTrusted section exists, then all other
; permissions are ignored.
;[FullyTrusted]

;
; ExecutionPermission
;
[com.ms.security.permissions.ExecutionPermission]
; If Unrestricted is true then the other settings are ignored.
;Unrestricted=true
Unrestricted=false
IncludeNames=*.exe;*.txt;activextest
ExcludeNames=foo.exe

;
; ClientStoragePermission
;
[com.ms.security.permissions.ClientStoragePermission]
; Limit is in bytes
Limit=100
RoamingFiles=true
GlobalExempt=true

;
; FileIOPermission
;
[com.ms.security.permissions.FileIOPermission]
IncludeRead=blah;c*
ExcludeRead=crayon
IncludeWrite=89kandaf;-l?daf;s
ExcludeWrite=s;-lddaf
IncludeDelete=45*.4;*.*.*.*;****a;??4nf
ExcludeDelete=ff4nf
ReadFileURLCodebase=true

;
; MultimediaPermission
;
[com.ms.security.permissions.MultimediaPermission]
; No specific settings required for MultimediaPermission

;
; NetIOPermission
;
[com.ms.security.permissions.NetIOPermission]
IncludeConnectIPs=1.2.3.4:1-102
ExcludeConnectIPs=
IncludeBindIPs=4.4.4.4:4-55,97;4.4.4.4:4
ExcludeBindIPs=4.4.4.4:8
IncludeMulticastIPs=
ExcludeMulticastIPs=
IncludeConnectHosts=www.microsoft.com:80
;IncludeConnectHosts=www.microsoft.com
ExcludeConnectHosts=
IncludeBindHosts=
ExcludeBindHosts=
IncludeMulticastHosts=
ExcludeMulticastHosts=
IncludeConnectGlobalPorts=3-100, 999
ExcludeConnectGlobalPorts=43, 999
IncludeBindGlobalPorts=43
ExcludeBindGlobalPorts=
ConnectToFileURLCodebase=true
ConnectToNonFileURLCodebase=true

;
; PrintingPermission
;
[com.ms.security.permissions.PrintingPermission]
; No specific settings required for PrintingPermission

;
; PropertyPermission
;
[com.ms.security.permissions.PropertyPermission]
; If Unrestricted is true then the other settings
; are ignored.
Unrestricted=false
AllowedSuffixes=applet;foobar
IncludedProperties=*system*
ExcludedProperties=*cryptsystem*

;
; ReflectionPermission
;
[com.ms.security.permissions.ReflectionPermission]
PublicSame=true
PublicDifferent=true
PublicSystem=true
DeclaredSame=true
DeclaredDifferent=true
DeclaredSystem=true

;
; RegistryPermission
;
[com.ms.security.permissions.RegistryPermission]
IncludeOpen=hk*
ExcludeOpen=*N
IncludeRead=fdjl
ExcludeRead=
IncludeWrite=*?5$$
ExcludeWrite=gd5$$
IncludeDelete=*
ExcludeDelete=d
IncludeCreate=*
ExcludeCreate=s

;
; SecurityPermission
;
[com.ms.security.permissions.SecurityPermission]
; No specific settings required for SecurityPermission

;
; SystemStreamsPermission
;
[com.ms.security.permissions.SystemStreamsPermission]
SetSysIn=true
SetSysOut=true
SetSysErr=true

;
; ThreadPermission
;
[com.ms.security.permissions.ThreadPermission]
AllThreadGroups=true
AllThreads=true

;
; UIPermission
;
[com.ms.security.permissions.UIPermission]
ClipboardAccess=true
TopLevelWindows=true
NoWarningBanners=false
FileDialogs=true
EventQueueAccess=true

;
; UserFileIOPermission
;
[com.ms.security.permissions.UserFileIOPermission]
CanRead=true
CanWrite=true

For a complete reference to the permissions and their values, see the Java Permissions .INI Values Reference. For more information on using .ini files to specify special permissions when signing code, see Signing a Cabinet File with Java Permissions.


Java Package Manager

The Java language supports the use of Java packages to manage the namespace of classes, but provides no mechanism for installing or managing packages. The Microsoft virtual machine (the version included with Internet Explorer 4.0 and with the Microsoft SDK for Java 3.2, or later) includes the Java Package Manager (JPM) to handle package installation and management. The primary function of JPM is to find classes when they are needed by the Microsoft virtual machine (Microsoft VM). When a class is needed, the JPM determines what package the class is in, and then refers to an internal database to determine where the package is stored. All the standard Java packages shipped with Microsoft® Internet Explorer 4.0 are installed in the Package Manager.

The following is a list of JPM features:

Version Control

Package version numbers are tracked, allowing Java programs and installers to intelligently update the system.

Application Namespaces

Java applications are installed in private namespaces, shielding their classes from name conflicts and use by other applications.

Improved Security

Instead of having to fully trust all installed classes, the Package Manager stores the allowed capabilities of each package as verified by Microsoft® Authenticode™.

Ease Of Use

Java applications can install packages without having to alter the CLASSPATH environment variable and without requiring a restart.

Compatibility

The JPM will install ZIP and JAR archives as well as cabinet file archives.


Package Installation

Java classes installed on the class path can be used by any Java applet or application. In many cases, a small group of utility classes will be installed for only a few applications of a particular vendor, but because of current class path limitations, these classes will be visible to all applications. This means that the class path gets cluttered quickly with toolkits and libraries that are used for only a few applications.

The JPM allows packages to be installed in an application namespace where they are visible only to applications and applets running in the namespace. (Packages that must be visible to all applications, such as the system classes and Application Foundation Classes, are installed in the global namespace.) Only packages signed by the namespace's principal are allowed to be installed in the namespace. Applications that have classes in the anonymous package can run without the possibility of name conflicts with other installed applications. Without this protection, Java applications cannot be installed. Application namespaces give vendors the ability to install Java applets and applications in the Java Package Manager.

To run a Java applet or stand-alone application that is installed in an application namespace, you must specify the namespace when you run the applet or application. To specify an application namespace when running an applet, add the following parameter to the <APPLET> tag:

<PARAM NAME=namespace value="namespace">

To specify an application namespace for an application, use the -n option with the jview utility:

jview -n <namespace> <classname>


Package Security

Security is handled on a package-by-package basis. Each package is in a separate archive, and each archive is digitally signed with a certificate. The certificate indicates which privileges the package requests from the Microsoft VM and is stored in the JPM. This way, Java packages can be supplied and placed on the local disk without receiving the carte blanche trust of packages in the class path. For more information on Microsoft's security model for Java applications, see Security.


Package Manager User Interface

You can view the current distribution units held by the Java Package Manager using the Downloaded Program Files shell extension provided by Microsoft Internet Explorer 4.0 or later. To use this feature, open Internet Explorer and select the %Windir%\Downloaded Program Files directory in the Address box. This displays all downloaded components. Each Java distribution unit is listed with a J icon. If you select the Details option from the View menu, the display will also show the size and version number of each distribution unit. For example:

Downloaded Program Files display

You can remove distribution units from the system by right-clicking an entry in the display and selecting Remove. Double-clicking an entry displays its Properties window, which shows the packages that are installed and the namespaces where they are stored. For example:

Other pages in the Properties window provide version and dependency information.


Using the Java Package Manager with Development Tools

When a Java package is installed in the JPM, the original archive file is removed and the classes are stored internally. You must use the clspack tool to generate the .zip files used by Java development tools. This tool enables you to take packages that are installed through the JPM and write their contents into a .zip file.

The easiest way to use clspack is to type the following command:

clspack –auto

This will create a single classes.zip in your %Windir%\Java\Classes directory that contains all classes stored in the JPM. The jvc compiler, which is in the Microsoft SDK for Java, looks for classes in this directory by default so you don't need to change your CLASSPATH environment variable.

If you're using a compiler that doesn't check this directory by default, set your CLASSPATH environment variable as follows:

set CLASSPATH=%WINDIR%\Java\Classes\Classes.zip

Extracting Individual Packages from the Java Package Manager

The clspack tool can also extract individual packages. Use the following command:

clspack myzipfile.zip <listfile>

The listfile parameter specifies the name of a text file containing the list of packages to extract to the . zip file.

Listing Currently Installed Packages

Use the -dump option with clspack to create a list of all packages currently installed in the package manager in the specified output file as follows:

clspack -dump <outputfile>


How the VM Searches for Classes

When a class is requested, the Microsoft VM normally searches for it in the following order.

  1. Check all explicitly specified locations (typically supplied with the jview /cp option; not applicable for applets).

  2. Check the locations specified in the HKLM\Software\Microsoft\Java VM\DevClasspath registry entry.

    Note This registry entry is provided for development and testing and may not be supported in a future release. Microsoft does not recommend relying on it for production purposes.

  3. Search packages in the Java Package Manager (JPM) marked as system packages (see the following notes).

  4. Check the locations specified in the HKLM\Software\Microsoft\Java VM\TrustedClasspath registry entry.

  5. Check the directory specified by the HKLM\Software\Microsoft\Java VM\TrustedLibsDirectory registry entry.

  6. Check the locations specified in the HKLM\Software\Microsoft\Java VM\Classpath registry entry.

  7. Check the directory specified by the HKLM\Software\Microsoft\Java VM\LibsDirectory registry entry.

  8. Check the locations specified in the CLASSPATH environment variable.

  9. Search packages in the JPM marked as non-system packages (see the following notes). Search first for non-system classes in the specified namespace, then search for non-system classes in no namespace (global namespace).

  10. If served from a Web page, the Microsoft VM additionally searches the following locations:
    • Any cabinet files referenced by the cabinets applet parameter (in the order in which they appear in the HTML file). If there is a cabinets applet parameter, the cabbase parameter and the Archive attribute (following) will not be searched.

    • The cabinet file referenced by the cabbase applet parameter. If there is a cabbase applet parameter, the Archive attribute (following) will not be searched.

    • Any .zip or .jar file referenced by the Archive attribute of the <APPLET> tag.
  11. Search the code base of the HTML file.

Notes

  • The contents of the registry values for steps 2, 4, and 6 and the environment variable in step 8 should contain a semicolon-delimited list of directories and .zip files, .jar files or both. Multiple entries will be searched in the order they appear. The registry values for steps 5 and 7 may specify only a single directory.

  • Classes loaded by steps 1-8 are considered system classes. Classes loaded by steps 9-11 are considered non-system classes. Non-system classes are not loaded by the system class loader, but instead are loaded by an instance of a Java ClassLoader. Non-system classes are not global and will not interact with other non-system classes loaded by a different ClassLoader. All the standard packages installed with the Microsoft VM are system packages.

  • When a class is loaded by an untrusted caller from one of the specified locations and it is only safe for use by a trusted caller, an exception may occur when trying to call a method or access a member of the class.

A package installed into the JPM must meet the following requirements to be considered a system package:

  • Must reside in the global namespace.

  • Must be signed with full permissions.

  • The .osd file inside the installation cabinet must specify the <SYSTEM/> tag for each package. If using the dubuild tool to create the cabinet file, use the /S command-line option to specify system packages.


Automatically Updating the Microsoft VM

If it is important that users who navigate to your Web page have the latest version of the Microsoft virtual machine (Microsoft VM), you can automatically update their computer using the <OBJECT> tag. Placing the following <OBJECT> tag on your Web page causes Microsoft® Internet Explorer to download and install the most recent version of the Microsoft VM:

<OBJECT
CLASSID="clsid:08B0E5C0-4FCB-11CF-AAA5-00401C608500"
WIDTH=0 HEIGHT=0
CODEBASE="http://www.microsoft.com/java/download/msjavx86.exe#Version=5,0,xxxx,0">
</OBJECT>

Replace xxxx in the <OBJECT> tag with the current version number. To find this information, see Determining the VM Version Number.

The Microsoft VM should not be in use when the update occurs. Users who have been running Java applets in the current session of Microsoft® Internet Explorer must exit Internet Explorer, and then navigate directly to the page that contains the <OBJECT> tag. If Internet Explorer 4.0x is being used with Active Desktop enabled, and a Java applet has been run since the last time the computer was started, it may need to be restarted to unload the Microsoft VM.

This <OBJECT> tag installs the retail (non-debug) version of the classes on the local computer. On a Java development computer, maintain the debug version of the classes to allow debugging system classes. These classes are included and installed with the Microsoft SDK for Java.

If an automatic update is not necessary, the SDK for Java contains a redistributable, self-extracting executable that performs a complete installation of the retail Microsoft virtual machine.

Microsoft Internet Explorer 3.02 Virtual Machine

If you need the latest virtual machine from the Microsoft® Internet Explorer 3.02 release, use the following <OBJECT> tag instead of the one shown previously:

<OBJECT
CLASSID="clsid:08B0E5C0-4FCB-11CF-AAA5-00401C608500"
CODEBASE="http://www.microsoft.com/java/ie30java.cab#Version=1,0,0,1520">
</OBJECT>

If an automatic update is not necessary, the Microsoft SDK for Java 1.5.1 contains a redistributable, self-extracting executable that performs a complete installation of the 1520 build of the retail Microsoft VM.

Note All versions of the Microsoft SDK for Java mentioned in this section are available from http://www.microsoft.com/java/ This link takes you to a site on microsoft.com.


White Papers

The following white papers include either technical background articles that offer a general introduction to a technology or a tutorial with how-to information and sample code that addresses more specific programming solutions.

Note There are additional white papers about integrating Java with IIS, MTS, MDAC, ADO, Visual Studio, and DirectX media in the Integration.chm, located in the %SDKDIR%\Docs folder.

Integrating Java and COM

This white paper provides an overview of how the Microsoft VM integrates Java with COM and explains how Java objects are exposed as COM objects, and vice-versa. The ability to use and implement COM objects in Java allows for seamless integration with the Microsoft® Windows® operating system, services, and applications from any COM-compliant programming language.

Using COM Objects from Java

This tutorial describes how the Microsoft virtual machine (Microsoft VM) creates and exposes Component Object Model (COM) objects to the Java developer. The reader should have a general understanding of what COM is and some experience programming in Java. This tutorial also has samples that are based on COM objects exposed by the Microsoft® Internet Explorer 4.0 COM object model. They demonstrate how COM objects can be used in Java applications.

Debugging and Profiling Java Applications

This white paper provides an overview of the COM-based profiler and debugger APIs. The profiler monitors application performance, memory use, and events, thus identifying current or potential problems. This profiling aids greatly in debugging applications that may be written in Java or in a mixture of Java and other languages.


Debugging and Profiling Java Applications

A Technology Overview

Microsoft Corporation

January 1999

Contents

Introduction
New Features at a Glance
The Java Profiler API
The Java Heap Monitoring API
The Java Debug API
Microsoft Technologies at Work
Sources for Additional Information

Introduction

Compared to a decade ago, the software development process has become much more complex. In the past, many applications were written as simple stand-alone programs for handling a specific task; now the requirements are for integration between applications. The desktop has matured with the introduction of Microsoft® Windows NT®, Microsoft® Windows® 95, and Microsoft® Windows® 98. New applications targeting these Win32® operating systems are capable of replacing enterprise applications that once ran on UNIX RISC machines and IBM mainframes. Consequently, the need for powerful and robust software development tools has never been greater.

The Java language is receiving wide acceptance by software developers and tool vendors. Compared to C++ and other object-oriented languages, Java is easier to learn, and new programmers can become productive sooner. A number of industry studies have found that applications written in Java can be completed in half the time required with C++. The Java language has the potential to displace other object-oriented languages and become dominant on the Web and in other general business applications.

The Java language leaves out many features found in C and C++ that often introduce errors into programs. The runtime environment provided by the Microsoft virtual machine (Microsoft VM) eliminates pointers and uses automatic garbage collection for managing memory, thus freeing the programmer from these error-prone areas. However, the runtime features needed to provide these benefits also impose a performance penalty each time the program is run. Consequently, there is strong interest in the market for Java profiling and memory-monitoring tools designed to identify potential performance issues.

Although developers may become productive faster using Java, programming errors still occur. In particular, the use of multithreading and other concurrency issues can introduce errors that are difficult to find. While Java may reduce certain classes of errors, developing robust applications for the enterprise or for personal productivity still requires the use of tools for debugging and testing applications.

Microsoft has a strong commitment to Java. The Microsoft VM continues to win awards and accolades as the fastest runtime implementation of Java on Win32 platforms. The Microsoft VM provides a variety of APIs that give software developers and tool vendors access to its underlying features. These features are especially useful for creating powerful Java development tools to use with the Microsoft VM. In particular, the most recent releases of the Microsoft VM add a rich set of APIs for profiling, monitoring memory and events, and debugging applications written in Java or in a mixture of Java and other languages.

New Features at a Glance

The Microsoft VM provides developers with a rich environment for writing powerful and sophisticated tools for profiling and debugging Java applications. The Microsoft VM exposes these features as a series of Component Object Model (COM) objects, so they can be used from any programming language that supports COM. This same flexibility provides developers with the ability to create tools that can be distributed across networked computers using Distributed COM (DCOM). The Microsoft VM also supports using these features with Just-In-Time (JIT) compiled Java code.

Performance is often an issue with applications, including those written in Java. The Microsoft VM supports a set of Java profiler interfaces to assist in the analysis of Java code for speed, memory use, and other performance factors. The profiler interfaces support any number of concurrently operating profilers and event monitors for gathering information on execution times, events, and memory usage. These interfaces can also profile components that mix Java classes with Win32 native code.

Some of the key features in the Microsoft VM designed for execution profiling include the following:

  • Multiple profilers can operate concurrently.

  • Profiling capabilities are easily customized using environment variables or registry settings.

  • Developers have detailed control over the types of events to be monitored.

  • Improvements for sampling profilers provide greater control and accuracy.

  • Object monitor operations can be monitored.

  • Static class information is available for Java classes.

Although Java supports automatic garbage collection, understanding how memory is used in a Java application or applet can be an important part of improving performance. The Microsoft VM includes a powerful set of Java heap monitoring interfaces that allow an application to collect detailed information on heap memory usage and garbage collection activity for a Java application or applet.

New features for supporting heap monitoring include the following:

  • Profilers can receive notifications on each heap object allocation.

  • The occurrence and duration of garbage collections can be tracked.

  • Profilers can determine the number of garbage collections an object survives.

  • A detailed heap dump can be retrieved after garbage collection occurs.

The debugger interfaces assist in the detection, location, and correction of logical errors in Java applications, applets, and COM objects that are run in the Microsoft VM. The debugger interfaces can handle a mixture of JIT-compiled methods and interpreted Java code.

New features in the Microsoft VM to support debugging include the following:

  • Debugging capabilities are easily customized using environment variables or registry settings.

  • Debugging both interpreted and JIT-compiled code is supported.

  • Debuggers can be attached to a Java process that is already running (JIT debugging).

  • Complete access is provided to static information on Java classes.

  • Detailed access is available to dynamic information on Java class fields, local variables in methods, arrays, and other data types.

  • Breakpoints can be set on data access (watchpoints) as well as on code execution.

  • Complete support is available for thread groups and threads.

  • Java inner classes can be debugged.

  • Improvements are available to support mixed-language debugging.

All of these profiling and debugging features are incorporated in the Microsoft VM that ships with Microsoft Internet Explorer 4.01 or later, Visual J++®, Windows 95, Windows 98, Windows NT, and many other Microsoft products. No special software is required to take advantage of these powerful features.

Complete documentation and code samples describing the use of these Java profiler and debugger interfaces are provided in the Microsoft SDK for Java. The SDK for Java is free and can be downloaded from the following location:

http://www.microsoft.com/java/ This link takes you to a site on microsoft.com.

The Java Profiler API

The Java profiler interfaces provide a powerful framework for analyzing Java code performance for speed and heap memory use. The profiler interfaces are implemented as COM objects by the Microsoft VM. This allows these interfaces to be used from Java, Visual C++®, Visual Basic®, or any other programming language that supports COM calling conventions.

The profiler interfaces used by the Microsoft VM can be organized into categories as shown in the following table.

Category | Purpose
Event monitor information | The interfaces called by the profiler to set event masks and request specific information from the Microsoft VM when events occur.
Event notification | The callback interfaces implemented by the profiler through which the Microsoft VM notifies the profiler of various events and returns the requested information.
Heap monitor information | The interface called by the profiler to request information from the Microsoft VM regarding heap memory usage of the Java application or applet.
Heap monitor notification | The callback interfaces that must be implemented by the profiler through which the Microsoft VM notifies the profiler of various memory and object allocation information.

A profiler or event monitor must register itself on the local machine so that it can be started by the Microsoft VM when a Java process begins execution. A profiler calls methods on COM objects implemented by the Microsoft VM to request event notifications and specific information from the Microsoft VM when events occur. Communication from the Microsoft VM to the profiler is based on sending event notifications to the profiler. The profiler implements these callback routines as methods on COM objects. These event notifications inform the profiler of various activities occurring in the Microsoft VM on behalf of the Java application or applet being profiled.

The categories of event types that can be monitored include those in the following table.

Event category | Description
Bytecode instruction execution | Send event notification when a Java bytecode instruction is about to be executed.
Class loading and unloading | Send event notification when a Java class is about to be loaded or unloaded.
Exceptions | Send event notification when an exception is about to be thrown.
Garbage collection | Send event notification when the Microsoft VM is about to execute and has completed a garbage collection.
JIT method compilation | Send event notification when a Java method is about to be JIT-compiled and after JIT compilation is complete.
Method calls | Send event notification when a class method is about to be called and upon completion of the method call.
Object monitor operations | Send event notification when a Java object monitor (synchronization object) operation is about to be executed.
Source line execution | Send event notification when a Java source line is about to be executed.
Track specific method calls | Send event notification when specific Java methods are called. This feature allows a profiler to restrict the methods it is interested in.
Thread creation and destruction | Send event notification when a Java thread is created or destroyed, or when the name of a Java thread has been set.

The profiler COM interfaces implemented by the Microsoft VM use the in-process free-threading model. Events are dispatched from within the VM on the thread that caused the event. Interface methods implemented by the VM can be called any time from any thread that has been properly initialized. These features simplify developing profilers with any language supporting COM.

The Java Heap Monitoring API

The heap monitoring interfaces allow a memory profiler to collect detailed information on heap memory usage and garbage collection activity for a Java process. The heap monitoring interfaces allow a memory profiler to receive notification on each object allocation, to track when garbage collections occur, and to retrieve a detailed heap dump after garbage collection.

The heap monitoring interfaces are implemented by the Microsoft VM as COM objects. A memory profiler calls methods on COM objects implemented by the Microsoft VM to request information from the Microsoft VM regarding heap memory usage of the Java application or applet. A memory profiler must implement its callback routines as COM objects. Heap monitoring follows a conceptual model similar to the other profiler interfaces. A memory profiler must register with the Microsoft VM, indicating an interest in receiving notifications for heap monitoring, and register its heap information callback interface. The Microsoft VM will communicate with the memory profiler through this callback interface.

The heap monitoring interfaces make extensive use of the concept of containers for representing heap usage. Through these containers, a memory profiler can completely rebuild the containment hierarchy for heap memory starting from root containers. Container types are defined for threads, static class references, objects awaiting finalization, internal Microsoft VM objects, and various stack frames (native garbage collection, JIT-compiled methods, native methods, COM methods, interpreted methods, and fast-interpreted methods).

The heap is presented to the memory profiler in a depth-first traversal. Profilers may optionally select to abort traversal of certain branches or from uninteresting roots, enabling control over which portions of the heap are traversed. Additional traversals may be requested to enable searches or other multiple-pass operations.

The heap monitoring COM interfaces implemented by the Microsoft VM use the in-process free-threading model, like the other profiler interfaces.

The Java Debug API

The debugger interfaces provide a powerful framework for locating errors in Java applications, applets, and Java-implemented COM objects that are run in the Microsoft VM. These interfaces can also be used for debugging Java code that mixes Java classes with COM objects and native Win32 code.

The debugger interfaces are implemented in the Microsoft VM as COM objects. A debugger communicates with the Microsoft VM, requesting information and controlling the Java execution environment by calling methods on these COM objects. Similarly, the Microsoft VM notifies the debugger of events and provides requested information to the debugger by calling methods on COM objects that the debugger implements as callback routines. These debugger interfaces can easily be extended to allow remote debugging using DCOM. Debuggers can also be written in Java using a set of Java classes in the com.ms.debug package supplied with the Microsoft SDK for Java. These Java classes provide wrapped COM interfaces to the Java Debug API.

The Java debugger interfaces used by the Microsoft VM can be organized into several categories, as shown in the following table.

Category | Purpose
Registration interfaces | The interfaces called by a debugger to register with the Microsoft VM and that request to be notified when specific events occur.
Notification interfaces | The callback interfaces implemented by the debugger through which the Microsoft VM notifies the debugger of various events and then returns the requested information.
Static information interfaces | The interfaces called by a debugger to request static information about Java classes.
Dynamic information interfaces | The interfaces called by a debugger to request dynamic information about a Java process during execution.
Execution control interfaces | The interfaces called by a debugger to control the execution of a Java process.

To use the debugger interfaces, a debugger calls methods of the registration interfaces implemented by the Microsoft VM. A debugger can request to be informed of new Java processes that are created. A debugger can also call methods implemented by the Microsoft VM to enumerate all Java processes currently running. After a debugger attaches to a Java process, it will be notified of a variety of events. The Microsoft VM calls methods on the COM interfaces implemented by the debugger to communicate these notifications.

A debugger can receive notifications from the Microsoft VM as shown in the following table.

Method | Description when notification occurs
BreakEvent | When an asynchronous break occurs. An asynchronous break may be requested by the debugger. A break can also be caused by the application or applet calling com.ms.debug.Debugger.breakpoint.
CanStopEvent | During a range step when the Java process being debugged makes a function call, or the method in which stepping was initiated returns.
ClassLoadEvent | When a Java class is loaded.
ClassUnloadEvent | When a Java class is unloaded.
CodeBreakPointEvent | When a code breakpoint is hit by the Java process being debugged.
DataBreakPointEvent | When a data breakpoint (a watchpoint) is hit by the Java process being debugged.
DebugStringEvent | When the Java process being debugged outputs a string to the debugger. An application being debugged may produce output for the debugger by using the com.ms.debug.Debugger class.
ExceptionEvent | When an exception occurs in the Java process being debugged.
LoadCompleteEvent | When notifications have been sent for all Java classes loaded before the debugger attached.
ProcessDestroyEvent | When a Java process terminates.
StartClassEvent | Notifies the debugger of classes that caused the Microsoft VM to be loaded, such as Java-implemented COM objects, or the class containing the main method for Java applications.
StepEvent | When an execution step is complete in the Java process being debugged.
ThreadCreateEvent | When a thread is created.
ThreadDestroyEvent | When a thread is destroyed.
ThreadGroupCreateEvent | When a thread group is created.
ThreadGroupDestroyEvent | When a thread group is destroyed.

Static information on the classes used in a Java process is available through a hierarchy of IRemoteField interfaces. These interfaces allow the debugger to navigate from Java classes to the methods, interfaces, inner classes, and fields of the class as well as to the superclass. These interfaces also provide methods for setting code breakpoints, clearing breakpoints, and retrieving Java method bytecodes. Because many attributes of a class are constant while the class is being loaded, this information can be cached by the debugger.

Dynamic information on a Java process is available through a hierarchy of IRemoteObject interfaces. These interfaces provide bound run-time access to objects of different types. An IRemoteObject does not necessarily refer to an instance of a class, but represents an instance of any data type. These interfaces implement methods used to get the type of an object, get or set the value of an object, and set or clear data breakpoints on the object. A data breakpoint will fire when the value of the associated object changes. The information obtained from an IRemoteObject is only valid during the lifetime of the underlying Java object that it represents. IRemoteObjects may be held across execution and re-evaluated when needed.

Monitoring execution of a Java process is possible through the IRemoteThread and IRemoteStackFrame interfaces implemented by the Microsoft VM. Methods on the IRemoteThread interface allow a debugger to suspend or resume execution of a thread, step within a method, step into, over, or out of a call to a method, and get the stack frames on a thread. The IRemoteStackFrame interface provides access to the Java method call stacks of the threads executing in the Java process being debugged. Each stack frame represents a method's state of execution. Stack frame interfaces maintain their identity across the execution of the application or applet being debugged.

The debugger COM interfaces use the apartment-threading model. The Microsoft VM uses a single apartment thread to dispatch all debugger events in order to simplify the debugger's task by serializing event notifications.

Microsoft Technologies at Work

Java technologies are used by Microsoft in several of its own development tools. Visual J++ leverages these features to provide the powerful Java debugger included with this Java-integrated development environment. The command-line debugger included with the Microsoft SDK for Java also uses these Java debugger interfaces.

A number of leading-edge technology companies are already using the Java profiler and debugger APIs to advantage in shipping products. These companies and products include the following:

  • Intel VTune profiler

  • Rational Software Quantify profiler

  • Compuware (formerly NuMega Technologies) TrueTime profiler

  • Sybase PowerJ Java integrated development environment

  • SilverStream Application Server

By taking advantage of the Java profiler and debugger technologies included with the Microsoft VM, these companies are able to offer some of the most powerful tools for Java developers. Other companies have plans to leverage these Microsoft technologies as well.

The Java language is being used to develop a variety of applications for the enterprise and for personal productivity. Programmers and software development teams are demanding more powerful and feature-rich development tools from vendors. As the market for Java development increases, the opportunity expands for new tools that target the varying needs of software development. The profiler and debugger technologies included with the Microsoft VM represent some of the many ways that Microsoft is offering a framework for leading-edge development using Java.

Sources for Additional Information

Debugger Interfaces Overview

Debugger Interfaces Reference

Profiler Interfaces Overview

Profiler Interfaces Reference


Integrating Java and COM

A Technology Overview

Chad Verbowski
Software Design Engineer
Microsoft Corporation

January 1999

Contents

Introduction
Java Objects in COM
COM Objects in Java
COM Functionality in the Microsoft VM
Implementing a Java/COM Object
Summary
Sources for Additional Information

Introduction

Sharing data across a network of computers in a bandwidth-efficient and language-neutral manner is essential to developing a cohesive system for doing business. Microsoft has worked hard to achieve a high degree of integration between all of its products. Key to this success has been developing a robust model that provides backward compatibility and language independence. The Component Object Model (COM) was developed to accomplish exactly these tasks and to provide a way to reuse and integrate components at run time. This is a significant development considering that most object-oriented strategies target reusing components at compile time.

Using Java and COM, integration developers can employ Java's advantages and develop components capable of interaction with operating systems, applications, and services written in any COM-compliant language on any platform. Because most of the Microsoft® Windows® functionality is exposed through COM, and most Microsoft applications provide COM interfaces to their object models, Java developers have instant access to rich functionality.

The Microsoft virtual machine (Microsoft VM) provides automatic mapping, allowing a Java object to be a COM object, and allowing any COM object to be accessible as a Java object. This is a powerful feature that makes all of the existing COM-based applications and services available to Java and enables any existing Java objects to be used by other COM supporting languages. The Microsoft VM contains functionality that automatically converts a Java object to a COM component complete with interfaces like IUnknown, IDispatch, IMarshal, and others used for implementing Microsoft® ActiveX® Controls and COM components. The Microsoft VM automatically handles object references, cleanup, and interface queries for any COM object used in Java, whether the component was written in Java or another COM-compliant language. These features, along with garbage collection and the replacement of pointers with references in the language, make Java ideal for many application development projects. Java/COM development offers distinct advantages over C implementations where the developer must contend with memory, threading, and cleanup issues. This is also true for Microsoft® Visual Basic® where developers can quickly implement an application but want more control over how individual components behave.

Modern software projects typically contain an element of basic development where only the features available in the language are used. For example, for Java applications, this means that only the standard Java packages and derivatives from them would be used. By packaging new functionality as COM components, projects will benefit from distinct encapsulation of capabilities and a clear path for future component reuse.

It is quite common to use existing legacy code or third-party APIs to reduce the development time and costs associated with a software project. Integrating these components can be difficult because they could originate from lots of vendors and may be implemented in different languages. Services like Microsoft® Message Queue Server (MSMQ), Microsoft® Transaction Server (MTS), Microsoft® Active Directory™ (ADSI), Microsoft® Management Console (MMC), and many facilities provided by the Windows operating system are exposed through a set of COM-based objects. Java development projects, through their COM APIs, can easily make use of the Microsoft services in addition to any of the numerous COM components developed by third-party component companies across the industry.

Some software projects benefit by integrating the functionality of other applications. For example, features available through Microsoft® SQL Server, Microsoft® Exchange, Microsoft® Office, Internet Information Server (IIS), Microsoft® Site Server, and Microsoft® Internet Explorer could all be used in your software. All of these COM-based applications and many third-party Windows-based applications expose object models for product integration.

This document explains why Java is an excellent language for COM-component development and why COM is the best method of developing applications to integrate with third-party services and applications.

Java Objects in COM

Overview

Exposing a Java object as a COM component requires that the Java object be contained inside a COM-compatible wrapper. The Microsoft VM does this by using a COM-Callable Wrapper (CCW). It neutrally presents the Java object for all other COM components and COM-compliant languages to use. The Microsoft VM dynamically creates a CCW for the Java object when a COM object is required. The CCW is essentially a generic COM object that has its virtual table (vtable) of function pointers dynamically constructed to support some default COM interfaces as well as any COM interfaces implemented by the Java object. The default COM interfaces exposed for every Java/COM object by the CCW allow Java objects to be used as functional COM objects. For example, a Java object registered as a Control will be exposed as an ActiveX component without additional work. The CCW exposed for a Java object is capable of being aggregated, but cannot aggregate another COM object. The Microsoft VM takes care of storing the pointer to the outer COM object's IUnknown interface in the CCW.

Details

The following table lists the default COM interfaces provided by the CCW for Java objects.

Interface | Description
IUnknown | The Microsoft VM handles the QueryInterface and reference counts for all COM objects (Java implemented or not); there is no need to expose any IUnknown functions to Java developers.
IDispatch | Provides Automation support. IDispatch assumes that the underlying object is static.
IDispatchEx | Extends IDispatch; provides Automation support for dynamic languages such as scripting languages. IDispatchEx was developed to support dynamic objects.
IProvideClassInfo | Provides a single method for accessing the type information for an object's coclass entry in its type library.
IProvideClassInfo2 | Extends IProvideClassInfo with GetGUID, which returns the object's outgoing IID for its default event set.
ISupportErrorInfo | Ensures that error information can be correctly propagated up the call chain. Automation objects that use the error handling interfaces must implement this interface.
IMarshal | Specifies how a COM object can be marshaled between processes and remote computers.
IConnectionPointContainer | Supports connection points for connection objects. Used to locate a specific connection point.
IExternalConnection | Manages a served object's count of marshaled (external) connections. The COM object that implements such a count can detect when it has no external connections and correctly shuts itself down. This interface is used by the Microsoft VM for handling the reference counts of COM objects.

Overriding the functionality of most of these interfaces is done by implementing them. The Java object's COM interface method implementations are added to the vtable instead of the CCW's COM interface method implementations. There are only three interfaces that cannot be overridden: IUnknown, IExternalConnection, and ISupportErrorInfo. This does not pose a problem to Java/COM developers. Because the Microsoft VM deals with these interfaces, the developer is freed from tracking reference counts, querying for interfaces, and propagating exceptions for Automation objects.

When a Java object implements the java.io.Serializable, java.io.Externalizable or com.ms.wfc.core.IComponent interfaces, the CCW implements the following interfaces for that object. COM universally uses these interfaces for serializing COM objects. This allows the Java/COM object to be immediately available as data in an MSMQ message or used in structured storage in conjunction with other COM or ActiveX objects in a document.

Interface | Description
IPersist | Has only GetClassID method; used to retrieve the CLSID of the object for persisting.
IPersistStreamInit | This interface is the same as the IPersistStream functions and InitNew; it is used as a replacement for IPersistStream or for persisting objects to a simple stream.
IPersistStorage | Used to persist an object from a structured storage object.

A Java class that has been registered as a COM object and specified as a Control (implying the object is an ActiveX Control) will cause the CCW for that Java object to implement the interfaces as shown in the following table.

Interface | Description
IOleControl | Used for managing keyboard input.
IOleInPlaceActiveObject | Allows communication with the outer frame.
IOleInPlaceObject | Manages activation or deactivation of in-place objects.
IOleObject | Basic functionality for communicating with the container.
IOleWindow | Used to obtain windows and context-sensitive help.
IPerPropertyBrowsing | Used for exposing property information in an object browser.
IViewObject | Used for drawing the component.
IViewObject2 | Used for drawing the component.

Any class registered as a Control extending an AWT component that contains superclasses of java.awt.Component and contains the Java interfaces com.ms.ui.IUIComponent and com.ms.object.ISiteable will have the following COM interface implemented in its CCW.

Interface | Description
IObjectSafety | Exposes functionality for Internet Explorer "Safe for Scripting" and "Safe for Init" security features: 1) Safe for Automation with untrusted scripts and Automation clients. 2) Safe for initialization with untrusted data. 3) Safe for untrusted scripts.

Any class registered as a Control that contains the com.ms.wfc.core.IComponent interface will have the interface automatically implemented in its CCW.

Interface | Description
IDataObject | Provides a basic data transfer mechanism, used with the Clipboard and drag-and-drop.

The component model of the underlying Java object contained in a CCW will affect how the CCW creates the IDispatch(Ex), IProvideClassInfo(2), and IConnectionPointContainer interfaces. Java objects that implement com.ms.wfc.core.IComponent will have an IDispatch interface that contains the methods and properties from the object's ClassInfo class. The IConnectionPointContainer will have entries for each EventInfo contained in the object's ClassInfo. The IProvideClassInfo(2) interfaces provide type library information when it is first needed for a COM component by dynamically creating the type library from the underlying WFC class's ClassInfo. If the underlying Java object doesn't implement the com.ms.wfc.core.IComponent interface, the JavaBeans Introspector is used to gather information about the object's methods, properties, and events for constructing the IDispatch(Ex), IProvideClassInfo(2), and IConnectionPointContainer implementations.

Implementing the Java interface com.ms.com.NoAutoScripting will turn this default behavior off, ensuring that this Java/COM object is not automatically accessible for scripting. When a Java object implements this interface, the Microsoft VM will not add the IDispatch(Ex), IConnectionPointContainer, and IProvideClassInfo(2) interfaces to that object's CCW.

Normally, a Java/COM object's CCW will aggregate the Free-Threaded Marshaler (FTM). It is provided by COM to automatically marshal a COM object to the correct thread when interface function calls are made. This allows the COM object to be used from any thread without requiring the call to be marshaled to the thread hosting the COM object. A Java/COM object can turn this default behavior off by implementing the com.ms.com.NoAutoMarshaling interface, which causes the CCW not to aggregate the FTM. The CCW will effectively be created in the current apartment, which may be either single-threaded (STA) or multi-threaded (MTA).

COM Objects in Java

Overview

Ideally, a Java developer would like to use a COM object as if it were a Java object. Accomplishing this requires that each COM object have a Java wrapper for exposing its functionality. The Microsoft VM provides this in the form of a Java-Callable Wrapper (JCW). A JCW is a Java class that has some Microsoft-specific attributes that tell the Microsoft VM how to map the Java object to the COM component that it represents. The jactivex tool provided in the Microsoft SDK for Java can be used to automatically generate JCW Java classes from any dynamic-link library (.dll) file containing COM objects, or from any type library file produced from a compiled COM object's Interface Definition Language (IDL) definition. This tool provides a simple mechanism for generating classes that Java developers can quickly and easily integrate with their project to leverage existing COM facilities.

To create a JCW, compiler directives are added to regular Java source files that specify how the Java object maps to the COM equivalent and vice versa. By providing these mappings in the source file, a Java developer can manipulate them to customize the Java representation of the COM object to suit the particular application's needs. When the Microsoft Java compiler compiles these source files, they are converted into Java class attributes, which the Microsoft VM uses to map the COM object to the Java object. This does not affect the operation of these classes on VMs that don't support COM. These attributes will simply be ignored by VMs that don't understand them.

Details

The following table shows a list of the COM-specific directives that the Microsoft Java compiler uses to create a JCW. For a complete description of the directive parameters available for each directive and how to use them, see the Compiler Directives Reference.

Directives | Description
@com.class(GUID, security, casting) | Specifies that this Java object represents a COM coclass with the given GUID, casting support, and Java security requirements.
@com.interface(GUID, thread, type) | Indicates that this Java interface represents a COM interface with the specified GUID, threading model, and types.
@com.method(dispid, vtable, …) | Marks the Java method as a COM interface method, which should be exposed in the object’s vtable, dispatch table, or neither.
@com.parameters | Used to specify which parameters are in, out, or a return value and how they should be mapped to COM and from COM to Java.
@com.typeinfo | Specifies additional information from the type library that represents this COM object.
@com.transaction | Indicates that the Microsoft Transaction Server can host COM objects in a variety of transaction situations that can be indicated with this directive.
@com.struct | Specifies that the Java class will be a Java-Callable Data Wrapper (JCDW).
@com.structmap | Indicates how the field in a JCDW should map to COM and from COM back to this field in Java. This directive can also be used to custom marshal the data between Java and COM and to specify the data's offset from the beginning of the JCDW.

A new instance of a COM object can be created in Java by simply creating a new instance of a JCW Java class. The Microsoft VM creates the COM object that it refers to in addition to tracking its references. A QueryInterface is performed when a JCW is cast to an implemented COM interface using the Java cast operation. When the Microsoft VM sees this operation, it queries the underlying COM object for the interface represented by the JCW being cast to. The resulting interface is returned from the operation. The Java object can then call any methods on the second COM interface as it would any other Java object. The Microsoft VM caches the queried interfaces so that subsequent cast operations are fast.

The key to integrating Java and COM, while maintaining consistency with the Java programming model, is for the Microsoft VM to handle all garbage collection of COM objects, and to map the QueryInterface calls to simple casting operations. This functionality is directly related to how the COM IUnknown interface behaves in Java. The Microsoft VM accomplishes integration by not exposing any of the IUnknown methods to the Java developer and by internally tracking the reference counts. As a result, the developer is freed from possible bugs related to unbalanced reference counts, and avoids the redundant operation of implementing each of the IUnknown methods for each Java/COM object.

The Microsoft VM contains a JCDW classes for the COM VARIANT and SAFEARRAY data types. Variants are objects that hold primitive data types, IUnknown, or IDispatch references. Variants can be used as parameters where multiple data types may be passed as parameters, and the actual data type will be determined at run time. Variants are commonly used in Visual Basic and in COM components for passing data of variable type through Automation interfaces.

A SafeArray object is a COM data type that allows Visual Basic to interact with COM components to pass around variable sized arrays. SafeArrays contain Variant-compatible types and information that describes the type of Variant contained, the starting position of the first element, and the overall length of the SafeArray. The Variant and SafeArray JCDWs contain Java methods that wrap the COM functions used to access the native data types. This makes using Java Variants and SafeArrays intuitive for developers and allows for painless interaction with Visual Basic through COM.

COM Functionality in the Microsoft VM

The Microsoft VM handles the mapping of Java objects to CCWs and from COM objects to JCWs. As such, this section provides details about these two issues. It is interesting to see how the Microsoft VM handles creating an instance of a COM object, and how it performs a QueryInterface call to obtain the currently required interface.

CreateInstance

The create instance process described here covers a Java client creating a new instance of a Java-implemented in-process COM object, which is the superset of possible create instance scenarios. This section notes which information is applicable to non-Java clients creating an instance of a Java-implemented COM object, and for a Java client creating an instance of a non-Java/COM object.

When the Java new operator is applied to a JCW Java object1, the Microsoft VM analyzes the Java object’s class file for the COM_Class_Type attribute generated by the @com.class directive. The Microsoft VM uses the information from this attribute to determine the CLSID of the underlying COM object. It also looks up the necessary information for creating an instance of the COM object from the registry. If the COM object to create is a Java-implemented COM object, the InprocServer32 registry key has the value of the Microsoft VM, Msjava.dll (the default in-process server for Java/COM objects that are registered using the Javareg.exe tool from the Microsoft SDK for Java).

1 All COM objects are accessed from Java through JCWs, even if they are implemented in Java.

The Msjava.dll implementation of DllGetClassObject initially goes to the local registry and again looks under
HKEY_CLASSES_ROOT\CLSID\{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\ for subkeys as shown in the following table.

Subkey | Description
JavaClass | The value of this key will be a fully qualified class name that represents the Java object to be exposed as a COM object.
CodeBase | This will be appended to the class path when the Java object specified by the JavaClass key is created. If this key is not present, only the Java system classes and those located in the \Trustlib directory will be available in the class path.
Control | Marks the Java/COM object as being an ActiveX control. The CCW provided for the Java object will implement additional interfaces required by ActiveX controls.

The Microsoft VM provides a generic class factory for Java/COM objects and initializes it with the information from the registry subkeys in the previous table. Inside the Microsoft VM provided IClassFactory::CreateInstance method, a CCW is created for the Java object. The CCW then creates a COM vtable for each Java-implemented COM interface. Each interface from the CCW is automatically supplied for the COM object. If the Java/COM object created is being aggregated, a pointer to the outer COM objects IUnknown interface is stored in the CCW. The Microsoft VM uses CoCreateInstance to create COM objects that were not implemented in Java.

The actual instance of the Java object contained within the CCW has not yet been created. The actual Java object underlying the returned COM object is created the first time an instance of it is required to answer a COM function call. So, for IUnknown::QueryInterface to work, no Java object instance is required. For an IDispatch method invocation to work, however, a Java object instance would be created and maintained. The first method that requires a Java object creates the instance.

Whenever a COM object is passed from the Microsoft VM to Java, the Microsoft VM analyzes the Java type that the Java application expects. If the return type is java.lang.Object and the COM object is actually a CCW, the Java object contained in the CCW will be returned. Similarly, if the return type is a COM interface JCW (implemented by the CCW's contained Java object), the underlying Java object will be returned. Otherwise, the COM object will be contained within an instance of the specified JCW return type. The Microsoft VM provides a generic JCW (com.ms.com.CUnknown) that can represent any COM object when a JCW is not specified as the return type. A generic JCW can be created for any Java object at run time by using com.ms.com.ComLib.makeProxyRef(Object o). The resulting com.ms.com.CUnknown JCW object will refer to a CCW that wraps the specified Java object.

QueryInterface

The Microsoft VM performs QueryInterface calls on COM objects. This happens whenever a JCW representing a COM object or interface is cast to a JCW representing a COM interface. This implementation allows COM objects to naturally fit into Java development. Effectively, any COM object can be queried for a COM interface in the same way that a Java object can be queried for a Java interface.

Any Java object (pure or JCW) can be cast to an interface implemented by the object's Java class of the object implements, such as java.io.Serializable. If this cast can't succeed because the class doesn't implement the interface, the Microsoft VM performs some COM-specific operations. The VM ensures that the interface is a COM interface, and the object to be cast is a JCW that supports dynamic casts (an option specified in the JCW's @com.class directive). If these conditions are met, the Microsoft VM queries the underlying COM object for the requested COM interface.

Once the Microsoft VM has verified that the Java application is attempting to perform a valid COM QueryInterface operation, it checks the underlying COM object for a previous query for the interface that is being casted to. It does this by looking in the JCW for the COM object's cache of interfaces already returned to the Java client. If the COM interface is in the cache, it is simply retrieved and returned. This table of interfaces is essentially a hash table keyed by IID.

If the required interface is not already in the cache, the Microsoft VM retrieves the underlying COM object from the JCW. QueryInterface is then called on the CCW/COM object for the requested interface. If an interface pointer is returned, it is stored in the JCW's cache and returned from the casting operation. If the QueryInterface operation on the underlying COM object fails, an error is returned to the Java application.

Implementing a Java/COM Object

Visual Basic programmers have had easy application development with COM components through inclusion of the Automation interfaces in the COM specification. Automation allows scripting languages (such as VBScript and JavaScript) to interact with COM objects through the IDispatch interface and late binding with the COM object functions. Automation in COM is similar to manipulating Java objects through the reflection APIs. Essentially, any method can be called on a COM object by specifying its method name and parameters at run time. Further, this has the disadvantage of being slower than vtable binding, as COM must obtain a pointer to the method at run time, and there is no compile time assurance that the correct method name and parameters are used. Automation-compatible interfaces and methods are allowed to use only Automation-compatible types as parameters and return values. A limited number of Automation-compatible types exist, and there is no support for structures. The mapping of Java primitives and objects to Automation types is outlined in the Microsoft SDK for Java. See Type Mappings between Java and COM. The Microsoft VM provides automation interfaces for every Java object in its CCW.

Automation interfaces are helpful when developing COM components that will be used by Visual Basic or scripting languages. Vtable interfaces are generally advantageous when developing components that will be used primarily in Java and C. They are somewhat faster to use at run time and use early binding techniques (programming errors are likely to be caught at compile time rather than at run time). COM supports implementation of an interface as both a Dispatch interface and a vtable interface. This is known as a dual interface. These interfaces are supported in Java, by means of specifying DUAL in the @com.class directive. For complete information on the @com directives and their use, see the Compiler Directives Reference.

Java is capable of implementing custom interfaces that contain methods for passing standard Automation data types, as well as structures, custom data types, and COM objects. The same is true for COM development in C. The standard method for implementing custom interfaces in a COM object is to define the object and all of its interfaces using IDL, and then compiling it with a MIDL compiler. The Microsoft-provided MIDL compiler is Midl.exe, available in the Platform SDK on the MSDN Library and with Microsoft® Visual C++®. The MIDL compiler takes the .idl file as input and generates a type library (.tlb file) and some C code that implements a proxy and a stub for the custom object. Java classes that represent the custom interfaces and the custom object can be generated using Jactivex.exe provided in the SDK for Java. Jactivex takes any standard type library file and generates corresponding .java files for the COM objects, interfaces, and structures defined in the type library. These Java files contain the correct @com directives for specifying the .java files as JCWs.

A Java object can implement a COM interface in exactly the same way that it implements a Java interface. The object being created does not need @com directives when implementing the interface's methods. At run time, the Microsoft VM uses the information from the implemented COM interface wrapper's @com directives when the CCW is creating its vtable for the Java object. Out-of-process and remote use of a Java/COM object containing custom interfaces requires a proxy/stub DLL to be registered on both the server and client computers. The proxy/stub DLL C source code is generated by Midl.exe when compiling an IDL definition of the COM object. The proxy/stub DLL contains the implementation of the proxy and stub COM objects that COM uses to custom marshal client calls to the real COM object containing the custom interfaces. Without the proxy/stub DLL, remote creation and out-of-process creation of the COM object will fail because the COM infrastructure will not know how to marshal the COM object to the client.

To test a custom interface, register the Java/COM object using Javareg.exe, and register the proxy/stub DLL file using Regsvr32.exe. Once the registration is successful, use Oleview.exe (oleview is packaged with Microsoft® Visual Studio® and the Platform SDK) to create an instance of the Java/COM object. Then, examine the interfaces that oleview displays for the Java/COM object. Along with the standard interfaces exposed for a Java/COM object, the name of the custom interface should also appear. Specify that the Java/COM object creation occurs as a local server. This ensures that the proxy/stub DLL code is working correctly. Oleview is an integral tool for COM development and is used to verify COM objects to ensure that they are operating correctly. This is the first place to look when debugging a COM application.

Custom Marshaling of Structures and Parameters

When specifying a structure or a parameter in a COM interface, it is sometimes necessary to indicate to the Microsoft VM exactly how the parameter or structure should be represented in native code. The @com.structmap directive is used to specify how fields in a Java structure are represented in native code. The @com.parameters directive is used to specify how parameters are represented in native code. These directives can indicate that the Java type should be marshaled by means of user-defined methods when creating the native code representation, and the Java representation from native code. To accomplish this task, the custom marshaler must implement two methods, toExternal and toJava. For example, the JCW representing the IPersistFile interface needs to specify the String parameter in the Load method as custom marshaled. The custom marshaler will be indicated in the parameter as a fully qualified Java class. This is shown in the following example.

@com.parameters([in, type=CUSTOM,
customMarshal="com.ms.com.UniStringMarshaller"] pszFileName,
[in, type=u4] dwMode)

The Microsoft VM uses com.ms.com.UniStringMarshaller to marshal the string that is passed as the pszFileName parameter. com.ms.com.UniStringMarshaller must implement the toExternal and toJava methods for performing the actual data marshaling.2 The Microsoft VM calls toExternal and passes the memory address that should be filled in with a native memory pointer to where the actual bytes representing the string are located. The Microsoft VM also calls toJava and passes the address in native memory where the bytes representing the string are located. The toJava method is called to construct the Java equivalent string from those bytes. The return value of toJava is assigned to the parameter that was specified to have the custom marshaler.

2 Note that UniStringMarshaller also needs a method called releaseExternal to free the string created by toExternal. This is a requirement because cbByValSize is not defined by the class (the marshaler will allocate a non-fixed size amount of memory).

Implementing Class Factories

Creating an instance of a COM object is accomplished through a class factory, which is automatically provided for Java/COM objects by the Microsoft VM. It is sometimes useful, however, to implement your own class factory for a Java/COM object. A class factory contains a CreateInstance method that handles requests for new instances of a particular COM object. The class factory can then decide to return an instance that has already been created if a single instance of the requested object is required. Alternatively, a new instance can be created and returned. The class factory, therefore, controls how an instance of a COM object is created, the thread that the object is created on (important for single-threaded objects), and which instance is returned. Fortunately, the Microsoft VM supports implementing class factories in Java, which is accomplished in the same way that a class factory would be developed in C by implementing IClassFactory or IClassFactory2.

Jexegen.exe (from the Microsoft SDK for Java) can package the Java-implemented class factory as an executable file that registers it under the COM object's CLSID in the LocalServer32 registry key. Then, any time an out-of-process request or remote request for the COM object is received, the Java-implemented class factory will be used.

Summary

The essential components for Java/COM integration have been presented, with emphasis on how COM components have been seamlessly integrated with the Microsoft VM. COM development with Java is simpler and less error-prone than implementing similar projects in C. The Microsoft VM handles much of the tedious IUnknown work, and handles creating and querying objects in an easy-to-use way. The Automation features available to Visual Basic developers are also present for Java developers with the option of delving deeper into the specifics of how COM objects are implemented and used. As most Microsoft and third-party products and services export object models for integration through COM interfaces, the Microsoft VM's Java/COM integration provides the ideal environment for developing COM components and applications.

Sources for Additional Information

Integrating Java and COM

Compiler Directives Reference

Java/COM Integration Attributes


Using COM Objects from Java

A Technology Overview

Chad Verbowski
Software Design Engineer
Microsoft Corporation

January 1999

Contents

Introduction
Overview of COM
Java-Callable Wrappers
Apartment Threading
Creating an Instance of a COM Object
Invoking COM Interface Methods
Threading of COM Object Method Parameters
Garbage Collection of COM Objects
Generating JCWs for COM Objects
COM Coclasses in Java
COM Interfaces in Java
VTable, Dispatch, and Dual Interfaces
COM Interface Methods in Java
COM Method Parameters in Java
Java-Callable Data Wrappers as Parameters
Using JCWs in Java Applications
Using JCWs with AWT Controls
Distributed COM
 Sources for Additional Information

Introduction

This tutorial describes how the Microsoft virtual machine (Microsoft VM) creates and exposes Component Object Model (COM) objects to the Java developer. The reader should have a general understanding of what COM is and some experience programming in Java. This tutorial also has samples that are based on COM objects exposed by the Microsoft® Internet Explorer 4.0 COM object model. They demonstrate how COM objects can be used in Java applications. Additional Java/COM information is available in the Microsoft SDK for Java.

COM is a popular object model for creating software applications from independent components. The binary interfaces exposed by COM objects are platform-independent. Therefore, various facets of applications can be written in any COM-compliant language. COM objects also promote encapsulation and object reuse. For example, earlier functionality can be contained in COM wrappers and reused in Microsoft® Windows® Distributed interNet Applications Architecture (Windows DNA) and other Web environments.

By using Java/COM wrappers, the Microsoft VM presents COM objects as regular Java objects. These Java objects contain extra information that the Microsoft VM uses to create and maintain the underlying COM object. The Microsoft VM automatically handles reference counting, garbage collection, marshaling, and threading for every Java/COM object. It does so by combining internal manipulation of COM interfaces with basic Java functionality.

Overview of COM

COM defines a language-independent binary standard for component interoperability. Each COM component can potentially implement several standard or custom interfaces to expose its functionality. These interfaces are the binary standards through which clients and component objects communicate. COM interfaces define related groups of methods. Every COM interface and class has its own globally unique identifier (GUID). The GUID is a 128-bit identification number that uniquely represents the COM interface or class across platforms, computers, and applications. The GUID of a COM interface is an interface identifier (IID), and the GUID of a COM class is a class identifier (CLSID).

COM interfaces can be defined with the Interface Definition Language (IDL). These definitions can be converted into binary form by the Microsoft Interface Definition Language (MIDL) compiler.

Binary interface definitions permit runtime reuse of classes, and permit the actual implementation of COM component object classes (coclasses) and their interfaces to occur in the most appropriate languages. All COM interfaces must extend the root interface IUnknown, and every COM object must implement IUnknown. The IUnknown methods are as follows:

  • IUnknown::AddRef( ) increments the reference count for an interface on an object.

  • IUnknown::QueryInterface( ) requests another interface that is implemented by the COM object. If the object supports the requested interface, QueryInterface( ) retrieves a pointer to the interface while also calling AddRef( ).

  • IUnknown::Release( ) decrements the reference count for the calling interface on a object. If the reference count on the object falls to zero, the object is freed from memory.

Microsoft has defined COM interfaces that provide common functionality. For example, IPersist and interfaces that inherit from IPersist contain methods that allow a client to ask an object to load its persistent data, thus initializing itself. COM objects can implement the IDispatch interface to make themselves accessible from high-level languages such as Microsoft® Visual Basic® and scripting languages such as JavaScript, Microsoft® Visual Basic® Scripting Edition (VBScript), and Active Server Pages.

COM objects are implemented by creating an object in a COM-compliant language, and implementing IUnknown along with other Microsoft- or custom-defined COM interfaces. The MSDN™ Library provides detailed information on the Microsoft-defined COM interfaces.

For more information about COM interfaces, see the COM Interface Reference This link takes you to a site on microsoft.com.

For information about CoCreateInstanceEx( ), see the COM Functions Reference This link takes you to a site on microsoft.com.

Java-Callable Wrappers

Java-Callable Wrappers (JCW) are simple Java objects with additional class file attributes. The Microsoft VM uses Microsoft-defined attributes in Java classes to expose COM objects to Java applications. These attributes are typically generated by the Microsoft Java compiler, jvc, from @com directives in Java source files. The Java representation of COM coclasses and interfaces looks exactly like other Java classes and interfaces, except for the addition of @com directive comments above the class, interface, and method prototypes.

A coclass might look like this:

/**
* @com.class(classid=0002DF01-0000-0000-C000-000000000046, DynamicCasts)
*/
public class InternetExplorer implements IUnknown, … {

An interface definition could look like this:

/**
* @com.interface(iid=0002DF05-0000-0000-C000-000000000046, thread=AUTO, type=DUAL)
*/
public interface IWebBrowserApp {

Interface methods may look like this:

/**
* @com.method(vtoffset=48, dispid=407, type=PROPPUT, name="FullScreen",
              addFlagsVtable=4)
* @com.parameters([in,type=BOOLEAN] pbFullScreen)
*/
public void setFullScreen(boolean pbFullScreen);

Because the @com directives appear as comments in Java source code, compilers that do not support them ignore the directives and compile the class as a regular Java class file. Similarly, virtual machines that do not support the COM attributes in class files ignore them.

The following example shows how the Microsoft VM exposes COM objects to Java runtime code as regular Java objects using a generic Java object (Figure 1) and an exposed COM object (Figure 2). Figure 1 shows how the Java instance is represented in memory, including its references to various components from the object's class file. A typical Java class is represented inside the Microsoft VM as follows:

package test;

public class MyClass{
  public int nField1 = 0;
  public String strField2 = 0;
  public char chField3 = ' ';
}

A generic Java object at runtime

Figure 1: Abstract representation of a generic Java object at runtime in the Microsoft VM

The Microsoft VM internally uses a Java-Callable Wrapper (JCW) to represent a COM object in Java. JCWs appear to Java developers as generic Java objects. JCWs are programmatically manipulated in exactly the same way as any regular Java object. The garbage collector handles any cleanup required if no Java references to the Java/COM object exist, and interfaces are automatically queried whenever a cast operation occurs. Figure 2 is a high-level diagram of the JCW coclass.

A Java-Callable Wrapper

Figure 2: Abstract representation of a Java-Callable Wrapper in the Microsoft VM

Notice that the JCW representation is an extension of the regular Java object internal structure. (The shaded boxes indicate COM extensions to the structure.) The JCW contains all the information necessary for the Microsoft VM to manipulate the underlying COM object. The threading model is used with the thread context (apartment) for marshaling to the correct thread when the COM object is not callable from any thread (see the Apartment Threading section of this topic for more details). The class file attributes created from the @com directives in the Java source file provide the necessary information for the Microsoft VM to create the COM object, call vtable or dispatch methods, and marshal parameters between Java and COM. The cache of interfaces associated with each JCW optimizes interface queries by storing references to previously queried interfaces.

CreateInstance( )

Object creation is accomplished in COM through a standard creation method. COM-compliant languages typically expose a function to create a new instance of a COM class. Typically, this function takes a CLSID or human-readable programmatic identifier (ProgID) as a parameter and returns a reference to the new COM object's IUnknown interface. IUnknown::QueryInterface( ) obtains a pointer to the required interface implemented by the COM object. The Microsoft Guidgen tool generates new GUIDs by using the CoCreateGuid( ) function from the COM API. For more details about GUIDs and Guidgen, see the COM specification on http://www.microsoft.com/com This link takes you to a site on microsoft.com.

The CreateInstance( ) method must obtain the class factory for the specified COM class before it can create a new instance and return it. CreateInstance( ) will internally use the function CoGetClassObject( ) for accomplishing this. CoGetClassObject( ) looks in the Windows registry under the HKEY_CLASSES_ROOT\CLSID key for a subkey with the same name as the GUID for the class of the COM object it is trying to create. This key will have subkeys that contain the name of the dynamic-link library (DLL) or application that implements the class factory for creating instances of that COM class. CoGetClassObject( ) returns this class factory to CreateInstance( ), which uses it to create a new instance of the object, and then returns it to the caller. The class factories returned by CoGetClassObject( ) are COM objects, which implement the IClassFactory interface or one of its derivatives.

After an application is finished using a COM object, it calls the Release( ) method from the COM object’s IUnknown interface. When all the clients using the COM object have released their references, the COM object removes itself from memory, and then unloads the associated library or application if it was the last object being used from that COM object provider.

COM objects can be used in the same manner as regular Java objects because the Microsoft VM exposes COM objects as Java objects. A COM object is created by applying the new operator to the JCW class representing the COM object’s class. The Microsoft VM checks if the class used to create the instance is a JCW. If so, it performs the necessary COM operations to create the underlying COM object. The Microsoft VM reads the CLSID for the underlying COM object from the class file's COM_CLASS_TYPE attribute as specified in the @com.class(clsid=…) directive, and uses this in a call to CoCreateInstance( ). If this call succeeds, the resulting interface is stored inside the Microsoft VM's representation of the JCW (see Figure 2).

Some COM objects can only be used from the thread that they were created from. As a result, the Microsoft VM will store information about the thread used to create the COM object in the JCW. That thread information allows the Microsoft VM to handle the underlying COM object from the correct thread context when performing operations on the underlying COM object, such as querying for interfaces.

Microsoft® J/Direct™ can also be used to access the Microsoft® Win32® API's COM functions to create new instances of COM classes. The com.ms.win32.Ole32 class contains J/Direct method mappings for many COM functions, including CoCreateInstance( ) and CoCreateInstanceEx( ). CoCreateInstanceEx( ) is particularly useful: It takes a remote computer’s name and security credentials as parameters to facilitate remote instantiation of COM objects. CoCreateInstanceEx( ) is the best way to access the functionality of Distributed COM (DCOM).

The J/Direct CoCreateInstance[Ex]( ) function calls can be used to create new instances of COM objects, even if no JCW has been created for the COM object. When the Microsoft VM attempts to marshal a COM object between native code and Java, it coerces the result into the expected Java type, which would typically be the JCW for the COM object or interface. When using a generic CreateInstance[Ex]( ) function through J/Direct, however, the return value will be typed as a generic java.lang.Object. The Microsoft VM has a generic JCW (com.ms.com.CUnknown) that it uses to represent an unknown COM object in Java. CUnknown can be cast to any JCW representing a COM interface supported by the underlying COM object.

It is occasionally useful to create and use an arbitrary COM object from Java without having to first generate JCWs. Script programmers will be familiar with the CreateObject function that takes a COM object's ProgID as a parameter. Create a COM object using Active Server Pages (ASP) as follows:

Set Obj = Server.CreateObject("IISSample.HelloWorld")

Although there isn't a single method that wraps this up as neatly as the IIS service, the following code sample uses J/Direct to get the same effect. The com.ms.com.Dispatch class can be used for late-bound IDispatch access to an object.

import com.ms.com.*;
public class CreateObject {
private static native _Guid CLSIDFromProgID(String str);

  private static _Guid IID_IUnknown = new _Guid("{00000000-0000-0000-C000-000000000046}");

  private static Object createObject(String str) {
    return com.ms.win32.Ole32.CoCreateInstance(
            com.ms.win32.Ole32.CLSIDFromProgID(str),
            null, ComContext.INPROC_SERVER |
              com.ms.win32.win.CLSCTX_LOCAL_SERVER,
            IID_IUnknown);    }

    public static void main(String args[]) {
    //  Load Excel and print its name property.
    Object excel = createObject("Excel.Application");
    System.out.println(Dispatch.get(excel, "name"));
    com.ms.com.ComLib.release(excel);
}

QueryInterface( )

IUnknown is the base interface in COM that every COM object must implement. Its QueryInterface( ) method is used to query a COM object for any of its implemented interfaces. The Java/COM integration provided by the Microsoft VM provides QueryInterface( ) functionality through the Java cast operation. When it performs the casting operation, the Microsoft VM checks if the object being cast is a JCW, and if the type being cast to is a Java class representing a COM interface. If both these conditions are met, the Microsoft VM queries the underlying COM object for the required interface and continues. The Microsoft VM supports the ability to cast the COM object to any of its COM interfaces, even if its JCW class doesn’t explicitly implement a Java class representing those COM interfaces. This is specified in the JCW for the coclass by adding the DynamicCasts parameter to the @com.class directive. The QueryInterface( ) operation is described in Figure 3.

A QueryInterface() operation

Figure 3: How the Microsoft VM performs a QueryInterface( ) operation on a JCW

  1. The Microsoft VM checks the JCW's interface cache for the required interface. If found, it uses the cached copy and continues.

  2. If the interface is not in the JCW's interface cache, the Microsoft VM marshals to the COM object’s home thread to perform a QueryInterface( ) method call.

  3. Next, the Microsoft VM queries for the requested interface.

  4. Then, the Microsoft VM stores the interface in the JCW's interface cache, and then continues.

Exceptions

COM functions and interface methods typically indicate error conditions by returning HRESULTs. Java methods, on the other hand, typically indicate error conditions by throwing Java exceptions. To make working with COM objects more like operating on Java objects, HRESULTs are mapped by the Microsoft VM to Java exceptions. The Microsoft VM will automatically throw an instance of a derivative from the abstract exception class com.ms.com.ComException, such as com.ms.com.ComFailException or com.ms.com.ComSuccessException, if the HRESULT returned from a JCW method call is other than S_OK. For more information on HRESULTs, see the MSDN™ Library. For details on the ComException classes, see the Microsoft SDK for Java.

Apartment Threading

COM objects are sensitive about which threads they can be created on and which threads their methods can be invoked from. By exposing COM objects to Java through JCWs, the Microsoft VM handles the threading issues related to using COM objects for the Java developer. As a result, invoking methods and initializing threads makes working with COM from Java easier and more productive.

The threading contexts that COM objects are useable from are called apartments. COM objects that can’t be used in a multi-threaded environment require a single-threaded apartment (STA). A Microsoft® Windows® thread prepares itself to host an STA COM object by calling the COM initialization function CoInitialize( ), and then starting a message pump to forward the COM-related Win32 messages that it will receive. Access to the hosted COM object can only occur within the STA’s thread context. The process of preparing to operate on the COM object from the correct thread (marshaling to the thread) will generate Win32 messages posted to the STA, which effectively synchronizes access to the hosted COM object.

The Microsoft VM internally maintains an STA thread for creating COM objects. This STA will be used whenever a Java application creates a new instance of a COM object from a regular Java thread. For performance reasons, it is sometimes desirable to create a Java STA thread for the COM object to be created and hosted on1.

1 The performance enhancements of creating an STA versus using the default VM STA are that method calls don't need to be marshaled to the VM’s STA, and the fact that having many COM objects in an STA will queue access to them, which could cause delays.

To create a Java thread capable of directly creating and hosting COM objects, call the ComLib.declareMessagePumpThread( ) method at the start of the Java thread's run( ) method. This tells the Microsoft VM that the Java thread will implement a message pump, if necessary, to service incoming COM calls. An example of this is shown as follows:

package tutorial.sample;

public class STA extends Thread {
   /**
    *Hosted COM object
    */
   private Object comObject = null;
   /**
    *   The returned object will be a proxy to the hosted COM object.
    *   The Microsoft VM will automatically take care of any thread
    *   marshaling requirements, allowing the returned object to be
    *   used like any other Java object.
    */
   public Object getHostedCOMObject( ){
      return com.ms.com.ComLib.makeProxyRef(comObject);
   }

   public void run(){
      com.ms.com.ComLib.declareMessagePumpThread();
      comObject = new SomeJCWClass();
      com.ms.win32.MSG msg = new com.ms.win32.MSG();
         while (com.ms.win32.User32.GetMessage(msg, 0, 0, 0)) {
            com.ms.win32.User32.TranslateMessage(msg);
              com.ms.win32.User32.DispatchMessage(msg);
      }
   }
}

COM objects that support multi-threaded apartments (MTAs) are capable of receiving method calls from other threads at any time, and must implement synchronization in their interface method implementations as required. A process contains only one MTA in which all threads reside that are initialized as part of the MTA. However, that same process may also contain many STAs. Method calls on a COM object that resides in the MTA can be serviced from any MTA thread in the process. This means that a caller doesn’t need to marshal to a different thread before invoking a method on an MTA COM object on any MTA thread.

com.ms.com.ComLib.startMTAThread(Thread) automatically starts a Java thread and initializes the thread as an MTA thread by calling CoInitializeEx( ) with the necessary parameters. java.lang.Thread.start( ) always calls CoInitialize( ), which initializes a thread as an STA thread.

Creating an Instance of a COM Object

The Windows registry contains a list of all COM classes registered on the local system. It has information on how to create new instances and their supported threading models. In particular, the ThreadingModel value under the InprocServer32 and LocalServer32 keys for each COM class entry specify the supported threading models. The following table shows their possible values.

ThreadingModel | Description
Absence of ThreadingModel or None | Originally, COM components didn’t support threading models; new instances had to be created on the thread that called CoInitialize( ) to initialize COM operations on that thread. This is denoted in the registry through the absence of a ThreadingModel value in the InprocServer32 or LocalServer32 keys or by setting ThreadingModel=None.
Apartment | Apartment-threaded components can only be created on threads capable of hosting such objects. A thread prepares to host apartment-threaded COM objects by calling CoInitialize( ) to initialize itself as an STA, and then starts a message pump to forward COM-related Win32 messages it will receive. STA COM objects can only have their methods invoked from the STA they reside in. In the Microsoft VM, Thread.start( ) automatically calls CoInitialize( ).
Free | Indicates that the COM class supports free-threading, and is hosted in an MTA. Method invocations can occur from any thread in the MTA’s thread pool. A thread joins an MTA thread pool by calling CoInitializeEx(COINIT_MULTITHREADED). In Java, com.ms.com.ComLib.startMTAThread(Thread) automatically calls CoInitializeEx(COINIT_MULTITHREADED).
Both | Specifies that the COM object can be hosted on both STA and MTA threads.

STA COM objects created (by default) by the Java new operator on a JCW class are created and serviced on a separate Microsoft VM-implemented STA thread. A Java thread that wants to directly create and manipulate STA COM objects, without marshaling to the Microsoft VM's internal STA thread, can call com.ms.com.ComLib.declareMessagePumpThread( ) and run a message pump. The Microsoft VM treats all COM classes implemented by local servers as STA COM classes, and uses the default STA rules for handling any Java new operations. J/Direct CoCreateInstance( ) calls return a proxy owned by the calling thread's COM apartment.

The Microsoft VM handles the marshaling for CoCreateInstance. This eliminates resorting to awkward pointer routines (as defined in com.ms.win32.Ole32.CoCreateInstance) as shown in the following example:

/** @dll.import("ole32", ole) */
private static native com.ms.com.IUnknown CoCreateInstance
  (com.ms.com._Guid rclsid, com.ms.com.IUnknown outer,
   int dwClsContext, com.ms.com._Guid riid);

CoCreateInstance( ) returns an interface reference that the Java developer can cast to any required COM interface. The resulting JCW contains the current threading context and will be automatically marshaled (Thread=AUTO behavior, discussed in Invoking COM Interface Methods).

Invoking COM Interface Methods

Generally in COM, interface methods cannot be invoked on arbitrary threads. Whenever the Microsoft VM manipulates an external COM interface pointer underlying a Java interface instance (for example, IUnknown), it must perform any required marshaling of that interface pointer. The Microsoft VM stores the threading model type of the underlying COM object in the JCW instance used to expose the COM object to Java. If the JCW is marked free-threaded, the call happens on that thread. If the wrapper is marked apartment-threaded and the current thread context is not the wrapper's home context, the Microsoft VM switches to the correct context and executes the call there. As in standard COM STA marshaling, internal windows determine thread switches, but MTA threads have no obligation to pump messages. Once the Microsoft VM has marshaled to the correct thread context for performing the work on the interface, the Microsoft VM may need to marshal some of the parameters for the invocation. If any of these parameters are not on the right context (based on the same decision as previously mentioned), standard COM marshaling passes out a compatible interface pointer to the external code.

Threading of COM Object Method Parameters

The Microsoft VM automatically determines (by default) the threading model for COM objects used as parameters in Java. It also performs the necessary marshaling to ensure method invocations occur from the correct thread. This behavior can be explicitly controlled on COM objects passed as COM interface method parameters by specifying the thread= AUTO | NO parameter in the method's @com.parameters directive. A default value for all COM objects used as parameters for all methods in the interface can be specified in the @com.interface directive. The Microsoft VM first checks the @com.parameters directive for a thread=<XXX> value for the particular parameter. If no value is specified, the Microsoft VM checks the @com.interface thread=<XXX> value. If none is found, the Microsoft VM uses the default thread=AUTO setting.

Possible values for the thread=<XXX> parameter are as follows:

Thread=AUTO- Indicates that the Microsoft VM should handle the threading of the COM object and take care of marshaling to the correct thread to operate on it. This value indicates that the COM object is either MTA or STA. The Microsoft VM checks any COM object marked with thread=AUTO to see if the object has aggregated the free-threaded marshaler (FTM), and if it has, the Microsoft VM treats the COM object as thread=NO. If the COM object has not aggregated the FTM, its JCW contains the current thread's context.

Thread=NO- Indicates that the Microsoft VM should not perform any threading operations and assumes that any threading issues have been taken care of. The COM object is dealt with as if it has been aggregated with the FTM. The COM object's methods can be invoked from any thread.

Garbage Collection of COM Objects

The garbage collection thread will not do the final release on a COM object. Every COM object wrapped as a Java object contains the thread context where it is safe to use the object. This could potentially be any thread context if the COM object aggregates the FTM. When the Java wrapper is garbage-collected, the underlying COM object's Release method will be called on the appropriate thread context. This is similar to the Microsoft VM’s marshaling calls on arbitrary Java threads to the appropriate thread context (when necessary).

When a JCW is garbage-collected, each COM interface cached in the JCW will have its Release( ) method called by posting a cleanup message to the thread owning the JCW. The Microsoft VM does not block waiting for the Release( ) calls to actually happen. If the thread no longer exists, the post fails, orphaning the interface pointers. The JCW itself is still garbage-collected, however, because the thread doing the garbage collection times out the request to the owning thread, and continues.

com.ms.com.ComLib.release(Object) is a shortcut for immediately releasing the underlying COM object, rendering it immediately unusable. Some COM objects tie their reference count to the release of resources without an explicit dispose( ) or close( ) call. As a result, a mechanism for immediately disconnecting the Microsoft VM's reference was required. Once garbage collection has run and the Microsoft VM has found unused Java wrappers around COM objects, it queues the Release( ) method calls to the appropriate thread contexts based on the JCWs' thread information.

Generating JCWs for COM Objects

JCWs can be generated using the jactivex tool provided in the Microsoft SDK for Java. Wrappers can be generated for existing COM components by running jactivex against the type library that represents the COM component and its associated interfaces. Type libraries are cross-platform binary representations of COM coclasses and COM interface definitions. They are usually2 created by compiling Interface Definition Language (IDL) code with the Microsoft Interface Definition Language (MIDL) compiler, which is available in the Platform SDK section of the MSDN™ Library.

2 JCWs can be created in other ways, too. The VM may be asked to create a JCW, which is how Javareg.exe and Vjreg.exe create type libraries.

Type libraries are used by COM-compliant languages to determine how to represent these coclasses and interfaces in those languages. For instance, Microsoft® Visual Basic® developers typically import a type library into the Visual Basic development environment to use the COM objects and interfaces the type library describes.

Type libraries generated by the MIDL compiler are binary files that have a .tlb extension. It is possible to add type library information to a dynamic-link library (DLL) or .exe file as a resource. Common file extensions of files that may contain type library information are as shown in the following table.

Module extension | Description
DLL | Dynamic-link libraries may contain type library information.
EXE | Applications may contain type library information.
OCX | DLLs that contain Microsoft® ActiveX® Controls.
OLB | Microsoft® Office components store their type libraries in this format.
TLB | Denotes a type library. This will be the output from MIDL.

OleView is a COM tool that ships with the Platform SDK in the MSDN™ Library and Microsoft® Visual Studio® products. OleView is a simple application for examining the COM objects on your system. It presents a treeview of COM components installed on the system, a list of registered COM interfaces, and the installed type libraries. Typically, registered COM objects and COM interfaces contain the location of the file that contains the type library describing it. It is instructive to use OleView to browse through the COM objects, interfaces, and type libraries installed on your system. You can use OleView to examine a file that might contain type library information. For example, look at the shdocvw.dll file like this:

oleview c:\winnt\system32\shdocvw.dll

The type libraries registered on your system describe some of the COM object models exposed by the installed applications. Examine these files to learn how to use the COM objects and interfaces for integration with their associated applications. Jactivex is a tool available in the Microsoft SDK for Java that generates JCWs from any type library. This tool provides instant access to Java classes for integrating with Win32 applications. The shdocvw.dll file contains the type library for the Microsoft® Internet Explorer 4.0 COM object model, and is used here to demonstrate how JCWs are generated. Then, a simple application is presented that uses the generated wrappers.

To generate the JCWs for shdocvw.dll, use the jactivex tool like this:

jactivex /d . /p:b- /p tutorial.ie c:\winnt\system32\shdocvw.dll

Jactivex creates a tutorial\ie directory structure that contains about 50 Java classes, all defined in the tutorial.ie package. These Java classes contain the @com directives that generate the COM attributes in the compiled class files to make the classes JCWs.

COM Coclasses in Java

The following is the generated Java wrapper for the Microsoft® Internet Explorer coclass :

package tutorial.ie;

import com.ms.com.*;
import com.ms.com.IUnknown;
import com.ms.com.Variant;

/** @com.class(classid=0002DF01-0000-0000-C000-000000000046,
               DynamicCasts) */
public class InternetExplorer
              implements IUnknown,
                         com.ms.com.NoAutoScripting,
                         tutorial.ie.IWebBrowser2,
                         tutorial.ie.IWebBrowserApp
{
  /** @com.method()
      @hidden */
  public native void GoBack();

  /** @com.method()
      @hidden */
  public native void GoForward();

  /** @com.method()
      @hidden */
  public native void GoHome();

  /** @com.method()
      @hidden */
  public native void GoSearch();

  /** @com.method()
      @hidden */
  public native void Navigate(String URL, Variant Flags, Variant TargetFrameName,
    Variant PostData, Variant Headers);

  /** @com.method()
      @hidden */
  public native void Refresh();

[Code removed for brevity.]

  // getFullScreen UNMAPPABLE: Name is a keyword or conflicts with another member.
  //  /** @com.method()
  //      @hidden */
  //  public native boolean getFullScreen();

  // setFullScreen UNMAPPABLE: Name is a keyword or conflicts with another member.
  //  /** @com.method()
  //      @hidden */
  //  public native void setFullScreen(boolean pbFullScreen);

  public static final com.ms.com._Guid clsid = new com.ms.com._Guid((int)0x2df01,
    (short)0x0, (short)0x0, (byte)0xc0, (byte)0x0, (byte)0x0, (byte)0x0, (byte)0x0,
      (byte)0x0, (byte)0x0, (byte)0x46);
}

@com.class

The comments at the start of the source file were generated by jactivex, which contains the exact command line parameters used. The Java comment block above the class definition contains an @com.class directive, which specifies the GUID for the represented COM class and indicates that this class supports dynamic casts. A full description of the @com.class directive is presented here.

The @com.class directive is applied at the class level to indicate that the Java class definition represents a COM component object class (coclass).

Syntax

@com.class(classid=<COM CLSID>, DynamicCasts, safe, safeAddFlags=<integer>)

Parameter | Description
classid=<COM CLSID> This parameter is required. Example: classid=0BE35203-8F91-11CE-9DE3-00AA004BB851 | The CLSID associated with the Java-implemented COM class.
DynamicCasts | Indicates that this class supports dynamic casts, which allow the Java developer to cast it to COM interfaces not directly implemented by the Java class. The Microsoft VM supports this by calling QueryInterface( ) for the target interface of the cast on the underlying COM object.
safe | Specifies that the class may be safely used by untrusted classes. A COM_Safety attribute is attached to the class.
safeAddFlags=<int> | Specifies a word (2 bytes) of information to be put in the COM_Safety attribute. Note The Microsoft VM currently ignores this data when reading the COM_Safety attribute.

The following table shows the attributes that the compiler will add to the generated Java class file when compiling the @com.class directive.

Attribute | Scope
COM_ClassType | Class scope.
COM_GuidPool | Class scope.
COM_Safety | Class scope.

The tutorial\ie\InternetExplorer.java file contains a class definition for the InternetExplorer coclass, which implements four interfaces. Three of these interfaces are JCWs that represent the COM interfaces IUnknown, IWebBrowser2, and IWebBrowserApp. The com.ms.com.NoAutoScripting interface is used as a flag by the Microsoft VM to indicate that this COM object is not accessible from scripting languages.

The methods presented in the source file are designated as hidden; they exist only to satisfy the Java requirement that all methods from all implemented interfaces are represented. The native designation on each method in the coclass tells the Microsoft VM that the implementation of the method is contained in the underlying COM object.

The static final CLSID field contains a com.ms.com._Guid initialized with the coclass's GUID.

COM Interfaces in Java

The following is the jactivex-generated source file for the COM interface IWebBrowserApp:

package tutorial.ie;

import com.ms.com.*;
import com.ms.com.IUnknown;
import com.ms.com.Variant;

// Dual interface IWebBrowserApp
/** @com.interface(iid=0002DF05-0000-0000-C000-000000000046, thread=AUTO, type=DUAL) */
public interface IWebBrowserApp
{
  /** @com.method(vtoffset=4, dispid=100, type=METHOD, name="GoBack",
                  addFlagsVtable=4)
      @com.parameters() */
  public void GoBack();

  /** @com.method(vtoffset=5, dispid=101, type=METHOD, name="GoForward", addFlagsVtable=4)
      @com.parameters() */
  public void GoForward();

  /** @com.method(vtoffset=6, dispid=102, type=METHOD, name="GoHome", addFlagsVtable=4)
      @com.parameters() */
  public void GoHome();

  /** @com.method(vtoffset=7, dispid=103, type=METHOD, name="GoSearch", addFlagsVtable=4)
      @com.parameters() */
  public void GoSearch();

  /** @com.method(vtoffset=8, dispid=104, type=METHOD, name="Navigate", addFlagsVtable=4)
      @com.parameters([in,type=STRING] URL, [in,elementType=VARIANT,type=PTR] Flags,
                      [in,elementType=VARIANT,type=PTR] TargetFrameName,
                      [in,elementType=VARIANT,type=PTR] PostData,
                      [in,elementType=VARIANT,type=PTR] Headers) */
  public void Navigate(String URL, Variant Flags, Variant TargetFrameName,
    Variant PostData, Variant Headers);

  /** @com.method(vtoffset=9, dispid=4294966746, type=METHOD, name="Refresh",
        addFlagsVtable=4)
      @com.parameters() */
  public void Refresh();

[Code removed for brevity.]

  /** @com.method(vtoffset=48, dispid=407, type=PROPPUT, name="FullScreen",
        addFlagsVtable=4)
      @com.parameters([in,type=BOOLEAN] pbFullScreen) */
  public void setFullScreen(boolean pbFullScreen);

  public static final com.ms.com._Guid iid = new com.ms.com._Guid((int)0x2df05,
    (short)0x0, (short)0x0, (byte)0xc0, (byte)0x0, (byte)0x0, (byte)0x0, (byte)0x0,
    (byte)0x0, (byte)0x0, (byte)0x46);
}

@com.interface

The tutorial\ie\IWebBrowserApp.java source file contains a Java interface definition that has been marked as a COM interface with a class-scope @com.interface directive. This directive contains the IID and specifies the type of COM interface that is represented (dual).

Syntax

@com.interface(iid=<GUID>, thread=AUTO | NO, type=DISPATCH | DUAL | VTABLE)

Parameter | Description
iid=<GUID> | Required. This GUID represents the IID for this interface.
thread=AUTO | NO | Specifies the default Microsoft VM marshaling behavior to be applied to the COM object method parameters in this interface's methods. If AUTO is specified, the Microsoft VM automatically marshals any calls from Java on this object to the thread that the object was created in. This is the safest option, and the default. If NO is specified, the Microsoft VM assumes that the object is callable on any Java thread.
type=DUAL | DISPATCH | VTABLE | VTABLE indicates that this interface can be used only through a vtable. DISPATCH indicates that this interface can be used only through IDispatch. DUAL indicates that this interface is accessible through both its vtable and through IDispatch. If the type is unspecified, vtable access is assumed.

The following table shows the attributes indirectly affected by @com.interface directive.

Attribute | Scope
COM_ExposedAs_Group | Method scope.
COM_GuidPool | Class scope.
COM_MethodPool | Class scope.
COM_ProxiesTo | Method scope.

VTable, Dispatch, and Dual Interfaces

By default, COM interfaces use early binding through a virtual table (vtable) of function pointers. This means that references to COM interface methods are determined at compile time, and are therefore subject to all compile-time syntax checking rules. Each interface method is placed in the interface's vtable in a specific order. At compile time, the compiler can call an interface method through the code pointer at the method's offset in the interface's vtable. For example, looking at the interface definition for the base COM interface IUnknown, it contains three methods and has a specific vtable order for these methods. All COM interfaces extend IUnknown, have vtables that contain the three IUnknown methods in exactly the same vtable positions, and append their own methods to the base IUnknown vtable.

Visual Basic® and Visual Basic® for Applications(VBA) always use the vtable-interface by default when the object-type is declared. Only variables declared as Objects or invoked methods or properties not declared in the interface definition go through IDispatch. Visual Basic® and Visual Basic® for Applications(VBA) also work with IUnknown-derived interfaces.

Automation is a mechanism that facilitates late binding to a COM object's interface methods by providing a generic Invoke( ) method. This is similar to using the reflection APIs in Java where the String form of the method name can be used to obtain a reference to the method. The generic Invoke( ) method is then called by passing the method identifier and all its required parameters. These late binding facilities are provided by the IDispatch interface, which contains methods for looking up the method ID (called the dispatch ID or DISPID) for a given method name, and for invoking the actual method. For this process of late binding to work correctly, it is necessary that only known data types be used as parameters to automation interfaces. The acceptable types are called automation data types, and are discussed in the COM Method Parameters in Java section of this topic.

Dispinterfaces are custom interfaces that extend IDispatch. By creating a dispinterface, a developer allows the interface's methods to be accessible through automation using the IDispatch interface. Dual interfaces are implemented as both dispinterfaces and vtable interfaces. This means that the functions they contain are accessible both from IDispatch and directly from the vtable. The implemented interface is available to C++ and Java programmers through early binding, and to Visual Basic® and scripting programmers through the late binding of the IDispatch interface. Dual interfaces are the preferred way of implementing dispinterfaces.

COM Interface Methods in Java

Each of the methods in the tutorial.ie.IWebBrowserApp interface definition has an associated @com.method directive that indicates how the COM method is mapped to Java.

@com.method

The @com.method directive indicates the method dispatch ID for dispatch interfaces, the vtable offset for vtable interfaces, or both for dual interfaces. It includes a set of parameters that indicate the mapping to the equivalent IDL form. Because COM interfaces support properties, the method can be a typical method or an accessor method for an interface property.

Syntax

@com.method(vtoffset=<offset>, dispid=<dispid>, name=<COM method name>, name2=<COM method name>, type=METHOD | PROPGET | PROPPUT | PROPPUTREF, nodispatch, returntype=VOID | HRESULT, addFlagsVtable=<int>

Parameter | Description
vtoffset=<offset> | This specifies the vtable offset for this method. Not required if the method is only being called through an IDispatch interface.
dispid=<dispid> | Indicates the dispatch ID for this method. Not required if this method is only being called through a vtable.
name="<COM method name>" Example: name="<myMethod1>" | Specifies how to expose this Java method to COM by means of IDispatch. The Microsoft VM implements an IDispatch interface that maps the name given by this parameter to the DISPID given by the dispid parameter. If unspecified, the default is the method name.
name2="<COM method name>" | Specifies a secondary mapping from this Java method to COM by means of IDispatch. The Microsoft VM implements an IDispatch interface that maps the name given by this parameter to the DISPID given by the dispid parameter.
type=METHOD | PROPGET | PROPPUT | PROPPUTREF | Used for dispatch interfaces. Indicates the type of COM method represented by this Java method. The method may manipulate COM object properties or it may be a COM object method.
nodispatch | Specifies that this method should not be accessible through IDispatch.
returntype=VOID | HRESULT | Specifies the return type for this method. Generally, the default, HRESULT, is used. If HRESULT is specified, the COM method associated with this Java method returns an HRESULT. A com.ms.com.ComException will be thrown if the method returns a non-S_OK HRESULT. If the Java method returns a value, it is mapped to the last parameter in the COM method, which is assumed to be a return value. If VOID is specified, the Java and COM method return values are directly related. That is, if the COM method returns an integer, its value is returned by the Java method.
addFlagsVtable=<int> Example: addFlagsVtable=4 | A low-level parameter that allows modification of created class attributes, specifically, the Flags field of the MCFuncDesc structure created in the MethodPool for this method. Specify the value 4 to cause the Microsoft VM to ignore non-failing HRESULTs. The Microsoft VM will still throw a ComFailException for failing HRESULTs, but will not throw a ComSuccessException for successful HRESULTs.

The following table shows class file attributes generated by the @com.method directive.

Attribute | Scope
COM_ProxiesTo | Method scope.
COM_ExposedAs_Group | Method scope.
COM_GuidPool | Class scope.
COM_MethodPool | Class scope.

The following is the Refresh( ) method from the tutorial.ie.WebBrowserApp COM interface:

 /**
  * @com.method(vtoffset=9, dispid=4294966746, type=METHOD, name="Refresh",
  *             addFlagsVtable=4)
  * @com.parameters()
  */
public void Refresh();

This method is a COM method that is part of a dual interface, because it has both a vtoffset and a DISPID. The value 4 for the addFlagsVtable parameter indicates that successful HRESULT error codes should not be thrown as com.ms.com.ComExceptions. For more information on successful and failed HRESULTs, see the MSDN™ Library.

The following method is an accessor method for setting a property in the dual interface. type=PROPPUT indicates that this method sets the property named "FullScreen" in the COM interface IWebBrowserApp:

/**
 * @com.method(vtoffset=48, dispid=407, type=PROPPUT, name="FullScreen", addFlagsVtable=4)
 * @com.parameters([in,type=BOOLEAN] pbFullScreen)
 */
  public void setFullScreen(boolean pbFullScreen);

COM Method Parameters in Java

Each of the methods in the tutorial.ie.IWebBrowserApp interface definition has an associated @com.parameters directive that indicates how the COM method parameters are mapped to Java.

@com.parameters

The @com.parameters directive denotes the mapping of each Java parameter's data type to the underlying COM data type and vice versa. Because COM interfaces support properties, the method may be a typical method or an accessor method for an interface property.

@com.parameters is used with @com.method to specify how Java parameters and return types are mapped to the underlying COM method. It is also possible to specify a custom marshaler that handles how the parameters are represented in the COM and Java representations. Each @com.parameters directive contains a group of directive parameters, which are inside brackets ([]), for each parameter in the method and for the return value (if it is not void).

For example, in previous description of the setFullScreen( ) COM method, the pbFullScreen Java parameter is represented as the automation type BOOLEAN. It need only be marshaled into the COM method.

Syntax

/**

@com.parameters([directive parameters] param1,

[directive parameters] param2,

…,

[directive parameters] return)

*/

public int myMethod1(IUnknown param1, Variant param2) {…}

The COM.parameters directive [directive parameters] describes each variable in the method prototype. This is accomplished by specifying the directive parameters for a variable inside brackets, followed by the parameter name (param1, param2, and so on). The keyword return is used as the variable name for the method return type when describing the directive parameters for the return value.

Parameter | Description
type=I1 | I2 | I4 | I8 | U1 | U2 | U4 | U8 | R4 | R8 | STRUCT | OBJECT | STRING | CUSTOM | CUSTOMBYREF | CUSTOMBYVAL | CURRENCY | DATE | DISPATCH | BOOLEAN | VARIANT | PTR | ARRAY | SAFEARRAY STRUCT means byval struct. Unsupported for dispatch classes.

OBJECT means a pointer to IUnknown for vtable calls, and VT_UNKNOWN for dispatch calls.

CUSTOM specifies that this parameter will be custom marshaled by the Java class specified in the customMarshaler parameter.

CUSTOMBYREF specifies that this parameter will be custom marshaled by the Java class specified in the customMarshaler parameter as a by reference value. This means that the custom marshaler's toExternal( ) method will be called to marshal the parameter to native code, and its toJava( ) method will be called to marshal the parameter from native code to Java.

CUSTOMBYVAL specifies that this parameter will be custom marshaled by the Java class specified in the customMarshaler directive parameter as a by-value parameter. This means that the custom marshaler's copyToExternal( ) method will be called to marshal the parameter to native code, and its copyToJava( ) method will be called to marshal the value from native code to Java.

STRING means BSTR for vtable call, and VT_BSTR for dispatch call.

CURRENCY means I8 for vtable call, and VT_CY for dispatch call.

DATE means R8 for vtable call, and VT_DATE for dispatch call.

DISPATCH means IUnknown * for vtable call, and VT_DISPATCH for dispatch call.

SAFEARRAY specifies that this parameter should be marshaled as a COM SafeArray. This parameter must be typed as com.ms.com.SafeArray in the method prototype.

BOOLEAN means U2 for vtable call, and VT_BOOL for dispatch call.

VARIANT means byval VARIANT, and VT_VARIANT for dispatch call.

PTR for string parameters means pointer to a task-allocated Unicode string. For struct parameters, PTR means pointer to struct. For dispatch calls, PTR generally means VT_BYREF | elementType.

ARRAY for a boolean array means a VARIANT_BOOL array. For an integer or float array, ARRAY means an integer or float array, respectively. For a string array, ARRAY means a BSTR array. For an array of structs, ARRAY means an array of pointers to structs. For an array of other objects, ARRAY means an array of IUnknown *s. For dispatch calls, ARRAY generally means VT_BYREF | elementType.
in | Specifies that the parameter will be marshaled to the COM method call. Specify [in,out] to marshal the parameter both to and from the COM method call.
out | Specifies that the parameter will be marshaled from the COM method call. Specify [in,out] to marshal the parameter both to and from the COM method call.
iid=<GUID> | Identifies a COM interface parameter. Used instead of the type specification.
thread=NO | AUTO Specifies the marshaling behavior to be applied to the COM object parameter. If AUTO is specified, the Microsoft VM automatically marshals any calls from Java on this object to the thread that the object was created in. This is the safest option, and the default.

If NO is specified, the Microsoft VM assumes that the object is callable on any Java thread.

Valid only for type=OBJECT and type=DISPATCH types.

elementType=VARIANT | U1 | I2 | I4 | R4 | R8 | STRING | OBJECT | DISPATCH Specifies the element type of arrays if type=ARRAY or type=PTR. A default value is generated based on the Java type of the element (for example, int[] is equal to I4).

Dependency: Used only if type=ARRAY or PTR.
size=<int> The number of elements in the array.

Dependency: Used only if type=array.
customMarshal="<class>"

Example: customMarshal="com.ms.
com.UniStringMarshaller"

 Specifies the name of a class. This class will marshal the parameter. Dependency: Used only if type =CUSTOM.
customMarshalFlags=<int> Specifies bits available to the custom marshaler when invoked. Must be in the 0 to 3 range. These bits move into the high two bits of the MCMT_Attr.typedesc.Flags field in the COM_MapsTo attribute generated for the field.

Dependency: Used only with customMarshal.

vt=<int> Specifies the VARTYPE of elements within a SAFEARRAY parameter. Use the VT_* values. For example, for an array of integers, use VT_I4 (3).

Dependency: Required and used only for parameters of type SAFEARRAY.
byref Specifies that this argument is passed by reference (VT_BYREF) in a VARIANT.

Dependency: Valid only for type=DISPATCH methods.
array Specifies that this parameter is passed as an array (VT_ARRAY) in a VARIANT.

Dependency: Valid only for type=DISPATCH methods.

name="<name>"

Example:

name="Hello"

 Specifies a name to be associated with this parameter.

Dependency: Valid only for type=DISPATCH methods.

Note This parameter is not currently used by the Microsoft VM.

The following table shows the attributes generated in class files by the @com.parameters directive.

Attribute | Scope
COM_GuidPool | Class scope.
COM_MethodPool | Class scope.

COM interface methods typically return HRESULTs. A returned HRESULT other than S_OK causes the Microsoft VM to throw a com.ms.com.ComException. Additional returned data from a COM interface method, if any, is typically returned in the last parameter of the method. In an effort to make COM interfaces easier to use from Java, developers should endeavor to map the real result of the COM function to the return value of the Java method in the COM wrapper. For example, the COM definition of the IClassFactory interface's CreateInstance( ) method is as follows:

HRESULT CreateInstance(IUnknown *pUnkOuter, REFIID riid, void **ppvObject);

The equivalent Java representation might be as follows:

/**
 * @com.method(vtoffset=0, addFlagsVtable=4)
 * @com.parameters([in,type=OBJECT] pUnkOuter, [in,type=PTR] riid,
                   [type=OBJECT] return)
 */
public IUnknown CreateInstance(IUnknown pUnkOuter, _Guid riid);

The interface pointer returned in **ppvObject from the IClassFactory::CreateInstance( ) COM method call will be mapped to the Java method's IUnknown return value.

Automation Data Types

Visual Basic provides a simple way to create Windows applications. However, Visual Basic does not support C++ features such as pointers and vtable methods. Automation makes COM objects accessible to Visual Basic and scripting languages such as VBScript, Microsoft® JScript®, and dynamic HTML (DHTML). Automation is enabled by a COM interface called IDispatch, which supports late binding of interface methods. This is similar to the reflection API in Java. Automation methods only use automation-compatible data types.

Besides the string, integer, and boolean data types, automation defines two other special data types: Variant and SafeArray. A Variant is a generic data type that can contain any other automation data type (including other Variants). A SafeArray is a structure that contains an array of automation data types, the number and type of the array elements, and the total size of the array. This table lists the automation data types and their Java equivalents:

Automation Type | Java Type
VT_BOOL, boolean | boolean
VT_I4, char | char
VT_R8, DATE, double | double
VT_I4, int | int
VT_I4, long, int64, CURRENCY, CY | long
VT_I4, short | short
VT_I4, byte, unsigned char | byte
VT_BSTR, LPCOLESTR | java.lang.String
SCODE, HRESULT | int (see the com.ms.com.ComException class)
VARIANT | com.ms.com.Variant
IUnknown | com.ms.com.IUnknown
IDispatch | java.lang.Object
SAFEARRAY | com.ms.com.SafeArray
VT_VOID, void | void
VT_R8, float | float

All Java objects not explicitly mentioned in this table map to VT_DISPATCH, except for the following special ActiveX control types that are used for the Microsoft Windows Foundation Classes (WFC) and JavaBeans ActiveX control bridges.

ActiveX type | Java type
OLECOLOR | com.ms.wfc.ui.Color
IFont | java.awt.Font, com.ms.Fx.FxFont
IFonstDisp | com.ms.wfc.ui.Font
IPictureDisp | com.ms.wfc.ui.Image

When dealing with arrays, a generic <type> * parameter in IDL maps to an <type> [] parameter in Java. But when jactivex sees an <type> [] it is mapped to a Variant[]. For this case, the Microsoft VM doesn't have enough metadata to know the underlying element type of the single-dimensional array. As a result, it treats it as an array of Variants.

Note that the Variant and SafeArray data types are equivalent to specific Java classes, com.ms.com.Variant and com.ms.com.SafeArray, respectively. These classes are Java-Callable Data Wrappers (JCDWs). JCDWs are Java classes with extra attributes indicating to the Microsoft VM that the object has a native representation and how the object should be represented in native code.

Java-Callable Data Wrappers as Parameters

Java-Callable Data Wrappers (JCDWs) represent native structures as Java objects. They are particularly useful for implementing structures, Variants, and SafeArrays. Each JCDW includes a generic Java object that exposes the native structure to Java developers, and an associated block of native memory that contains the native representation. It is the native memory that will be passed to native function calls or COM method calls. Figure 4 is an overview of how the JCDW is represented inside the Microsoft VM.

package tutorial.jcdw;

/** @com.struct() */
public class JCDW {
   public int nField1;
   public String strField2;
}

Java-Callable Data Wrapper at runtime

Figure 4: Abstract representation of the Java-Callable Data Wrapper at runtime in the Microsoft VM

The JCDW stores primitive data for the structure directly in the native memory, but must keep a separate garbage-collectible object for each embedded reference such as arrays, strings, or other JCDWs. The Microsoft VM typically propagates the referenced objects when it attempts to marshal the JCDW to native memory. Essentially, propagation involves synchronizing the native memory values with the garbage-collection objects on the way into native memory, and synchronizing the garbage-collection objects with the native memory values on the way out. The Microsoft VM supports implementation of custom marshaling through calls to toExternal( ) (for Java-to-native marshaling) and toJava( ) (for native-to-Java marshaling) methods in custom marshaling Java classes. The Microsoft SDK for Java contains detailed documentation and sample code for custom marshaling. The Microsoft VM is able to create the appropriate data structure in native memory by examining the underlying class file for the JCDW. A JCDW class will contain extra class file attributes that were generated by the @com.struct or @dll.struct directives, or the @com.structmap or @dll.structmap directives.

@com.struct and @dll.struct

The @com.struct directive is specified at the class level and marks the class declaration as equivalent to a C structure definition. Instances of the class can then be passed through J/Direct and COM method calls that require a C structure with the same composition.

Note The syntax for @dll.struct and @com.struct is identical. The only difference between them is the way that some fields are marshaled between Java and native code.

Within the class declaration, you need to supply fields whose Java types map to the types of the fields in the native structure in the order they occur in the native structure.

Syntax

@dll.struct(ansi | unicode | auto, pack=1 | 2 | 4 | 8, noAutoOffset, safe, safeAddFlags=<int>)

Be aware that white space within @dll directives can cause syntax errors. You can put white space between the directive and the comment tags, but not within the directive itself. For example, the following directive would cause a syntax error:

  /**@dll.struct("MyDll",   auto)*/

But this one would not cause an error:

  /**       @dll.struct("MyDll",auto) */

Parameter | Description
noAutoOffset | Specifies that the offset of each field in the structure will be explicitly defined. This is accomplished by specifying an @dll.structmap directive for each field, and using the offset parameter to specify the offset. If this parameter is specified, each field in the class must have an @dll.structmap directive that gives the field's offset. If this parameter is not specified, the Microsoft VM automatically calculates offsets for each field in the structure. In this case, the default packing size is 8 bytes, but can be modified by the pack parameter. Dependency: @dll.structmap.
unicode | Specifies that strings and char fields used in this structure should be converted to Unicode native values. Dependency: This cannot be specified with ansi or auto. Not valid in @com.struct.
ansi | Specifies that strings and char fields used in this structure should be converted to ANSI native values. This is the default. Dependency: This cannot be specified with unicode or auto. Not valid in @com.struct.
auto | Determines how the strings and char fields in the defined structure will be interpreted in the native mapping. Generally, Microsoft® Windows® 95 or Microsoft® Windows® 98 requires ANSI strings, while Microsoft® Windows NT® version 4.0 accepts Unicode strings. The auto parameter chooses the correct string type at runtime, depending on the system that the class is used on. The default is ansi. Dependency: This cannot be specified with unicode or ansi. Not valid in @com.struct.
safe | Specifies that the structure may be used safely by untrusted classes. A COM_Safety attribute is attached to the class.
safeAddFlags=<int> | Specifies a word of information to be put in the COM_Safety attribute. Note The Microsoft VM currently ignores this data when reading the COM_Safety attribute.
pack=1 | 2 | 4 | 8 | Specifies the packing alignment of the structure, which determines how fields will be aligned in memory. Typically, the packing alignment for a structure is specified in C by using the #pragma pack(n) syntax. The value given for the Java pack parameter should be the same as that used for the corresponding C structure. The default value is 8, which is the default Microsoft® Visual C++® packing alignment. Dependency: If the noAutoOffset parameter is specified, the Microsoft VM ignores this parameter.

The following table shows class file attributes generated by the @com.struct and @dll.struct directives.

Attribute | Scope
COM_ClassType | Class scope.
COM_MapsTo | Field scope.
COM_Safety | Class scope.

@com.structmap and @dll.structmap

The @dll.structmap directive is applied to a field in an @dll.struct class to specify how a field is exposed to native memory. This directive must be used if the structure was declared using @dll.struct(noAutoOffset), which requires the offset keyword in each @dll.structmap directive. This directive can also override the default field mappings in other struct classes.

Static fields are not considered part of the structure by the Microsoft VM, and can hold information that is not part of the structure definition.

Note There are no differences other than name between @dll.structmap and @com.structmap.

Syntax

@dll.structmap(offset=<int | long>, iid=<GUID>, thread=AUTO | NO, size=<int | long>, customMarshalFlags=<int>, customMarshal=<class name>, addFlags=<byte>, type=BOOLEAN | CURRENCY | CUSTOM | CUSTOMBYREF | CUSTOMBYVAL | DATE | DISPATCH | FIXEDARRAY | I1 | I2 | I4 | I8 | OBJECT | PTR | R4 | R8 | STRING | TCHAR<int> | U1 | U2 | U4 | U8 | VARIANT, <field name>)

Parameter | Description
offset=<int | long>

Example: offset=4

 Specifies the byte offset from the start of the structure.

Dependency: Used only in structures specified with no auto offsets, as in @dll.struct(noAutoOffset).

thread=<AUTO | NO> Specifies the Microsoft VM marshaling behavior to be applied to this field. If AUTO is specified, the Microsoft VM automatically marshals any calls from Java on this object to the thread that the object was created in. This is the safest option, and the default.

If NO is specified, the Microsoft VM assumes that the object is callable on any Java thread.

Dependency: Valid only for type=OBJECT and type=DISPATCH types.

iid=<GUID>

Example: iid=0000000F-0000-0000-C000-000000000046

 Indicates the IID of the COM interface reference being mapped to this field. If this parameter is not used and the type is specified as OBJECT, the default is IID_IUnknown.

Dependency: Valid only for type=OBJECT and type=DISPATCH types.

size=<int | long>

Example: size=3

 Specifies the number of elements in an array.

Dependency: Valid only for type=FIXEDARRAY.

customMarshalFlags=<int> Specifies bits available to the custom marshaler when invoked. Must be in the 0 to 3 range. These bits move into the high two bits of the MCMT_Attr.typedesc.Flags field in the COM_MapsTo attribute generated for the field.

Dependency: Used only with customMarshal.

customMarshal=<class name>

Example: customMarshal="com.ms.com.UniStringMarshaler"

 Specifies the name of a class that will marshal the field.

Dependency: Valid only for type=CUSTOM and type=CUSTOMBYVAL

addFlags=<int> | Specifies a byte value in the 0 to 255 range that is moved into the MCMT_Attr.typedesc.Flags field in the COM_MapsTo attribute generated for the field.
type=I1 | I2 | I4 | I8 | U1 | U2 | U4 | U8 | R4 | R8 | PTR | OBJECT | STRING | CUSTOM | CUSTOMBYVAL | DATE | CURRENCY | DISPATCH | BOOLEAN | TCHAR | TCHAR<int> | FIXEDARRAY | VARIANT PTR is valid only for fields of structure (JCDW) type. Indicates a pointer to structure in a native structure.

CUSTOM specifies that the field should be custom-marshaled by the class specified in the customMarshaler parameter. The indicated class's toExternal( ) method will be called to marshal the field from Java to native, and its toJava( ) method will be called to marshal the field from native to Java.

CUSTOMBYVAL specifies that the field should be custom-marshaled by the class specified in the customMarshaler parameter as a by-value entity. The indicated class's copyToExternal( ) method will be called to marshal the field from Java to native, and its copyToJava( ) method will be called to marshal the value from native to Java.

OBJECT is a pointer to a COM object, IUnknown *.

STRING indicates a pointer to a Unicode string. Valid only for fields of type java.lang.String.

DATE is the same as R8. Use R8 instead.

CURRENCY is the same as I8. Use I8 instead.

DISPATCH is the same as OBJECT. Use OBJECT instead.

BOOLEAN maps to U2 (VARIANT_BOOL).

TCHAR specifies that a character type in a native structure (U1 or U2) is based on the default character type (auto, ansi, or unicode).

TCHAR<int> is an embedded array of characters with length <int>. The character type in a native structure is based on the default character type. Valid only for fields of type java.lang.String.

FIXEDARRAY is an embedded array. The size parameter defaults to 1, but can be overridden by specifying a value for it that gives the number of elements. Valid only for fields specified as an array of primitive types. For arrays of characters, native type is determined by default character type (auto, ansi, or unicode). Arrays of booleans are mapped to BOOL[] in native code.

VARIANT should be used only for a field of type com.ms.com.Variant.

If there is no structmap for a field, the defaults shown in the following table are used.

Java type | Native type for @dll.struct | Native type for @com.struct
boolean | U4 | U2
byte | I1 | I1
short | I2 | I2
char | TCHAR | U2
int | I4 | I4
long | I8 | I8
float | R4 | R4
double | R8 | R8
java.lang.String | type=CUSTOM customMarshal="com.ms.com. AnsiStringMarshaler", "com.ms.com. UniStringMarshaller", or "com.ms.dll.StringMarshaler" | String
com.ms.com.Variant | VARIANT | VARIANT
struct class | OBJECT | OBJECT

The following table shows the affected attributes.

Attribute | Scope
COM_MapsTo | Field scope.

Working with JCDWs

Sometimes it is necessary to access the address of the native memory used by the JCDW, or to create a JCDW from data in an arbitrary native memory block. The classes in the com.ms.dll package help accomplish these tasks. For example, to obtain the underlying native memory address of a JCDW, do something like this:

public class JCDWExample {

  public static MyJCDWClass myJCDW = new MyJCDWClass();

  public static void main(String args[]){
    int handle = com.ms.dll.Root.alloc(myJCDW);
    int addr = com.ms.dll.DllLib.addrOf(handle);
    com.ms.dll.Root.free(handle);
  }
}

The call to com.ms.dll.Root.alloc( ) creates a root handle that represents the JCDW in the garbage-collection heap, and protects it from being garbage-collected. com.ms.dll.DllLib.addrOf( ) takes the root handle and returns the address of the underlying native memory to the caller. com.ms.dll.Root.free( ) frees the root handle, allowing the object to be garbage-collected.

To create a JCDW object from a given memory location, use the com.ms.dll.DllLib.ptrToStruct( ) method. It takes the native memory location of the data and the class of the JCDW representing the structure stored in that location. The result is an instance of specified JCDW initialized with the values from the specified memory location. Note that the Microsoft VM attempts to propagate all native values into the new JCDW instance. As a result, if the memory location is simply a newly allocated block, it will contain uninitialized garbage-collection values. This may cause the Microsoft VM to fault, especially if the JCDW contains some pointer values that may be mapped into protected memory. To guard against this, ensure that the memory location being used in the mapping has been initialized.

To access the native memory used by the JCDW from Raw Native Interface (RNI) code, use the functions described in Nativcom.h in the Microsoft SDK for Java. Specifically, use jcdwGetData(HObject *), which returns LPVOID that can be cast to your defined structure.

Variants

Variants are used as generic data types in automation for passing data through COM dispinterfaces. The @com.parameters section of this topic describes the default mappings between automation data types and Java data types. Whenever it is necessary to communicate with a COM object through its IDispatch interface, the parameters will need to be passed as variants. The Microsoft VM provides the com.ms.com.Variant class for this purpose.

Jactivex maps overloaded methods from dispinterfaces as methods that contain the maximum number of parameters, with each parameter as a variant. To invoke an overloaded method instance with fewer parameters, pass instances of the com.ms.com.Variant object, which have their noParam( ) method called. This indicates that the variant is being used to fill a missing or optional parameter in the underlying COM interface function call. All Java objects that don’t explicitly have a Variant mapping (as outlined in the Automation Data Types section of this topic) will be passed as COM objects exposed through their IDispatch interfaces. Methods can be invoked on the Java object parameter by invoking methods on this IDispatch interface by means of methods of the com.ms.com.Dispatch class.

SafeArrays

Languages that interact with COM objects through automation typically can't directly handle pointers and native memory. This becomes a problem when working with arrays of data types. A SafeArray is used in automation for passing an array of data, along with details about what type of elements are contained in the array, the size of the array, and the index of the first element. SafeArrays can be used to pass arrays of Variant data types. The Microsoft VM exposes SafeArrays to the Java developer through the com.ms.com.SafeArray class.

There are some strict rules that must be followed when dealing with SafeArrays to ensure that the data contained is not corrupt or lost. Only the owner of a SafeArray should dispose of the actual SafeArray and its contents. Any method that receives a SafeArray as a parameter should make a copy of the array's contents if it needs to hold the values after the method has returned. The following code demonstrates how a SafeArray containing an array of strings is created and passed to an arbitrary COM object. It also shows how a SafeArray received as a return value can be examined to retrieve its Java data types.

private void processStringArray() {
  SafeArray safeIn = new SafeArray(Variant.VariantVariant,4);
  safeIn.fromStringArray(new String[]{"start",
                                      "of",
                                      "the",
                                      "String",
                                      "Array"});
  Variant retSafe = comObject.processStringArray(safeIn);
  for (int i=retSafe.toSafeArray().getLBound();
       i<retSafe.toSafeArray().getUBound(); i++)
    System.out.println("index ["+i+"] value ["+retSafe.toSafeArray().getVariant(i)+"]");
}

Structures

JCDWs are also used to represent structures used in C, C++, and COM. Essentially, any Java class that contains an @com.struct or @dll.struct directive is marked as a JCDW, and any non-static fields within the class are exposed as native fields. The @com.structmap or @dll.structmap directive can be used in association with any field to specify exactly how that field is natively represented. The following is an example of a simple structure defined in Java using these directives:

package tutorial;

/** @com.struct() */
public class MyStruct {
     public int foo;
     public String bar;
   /** @com.structmap([customMarshaler="tutorial.MyCustomMarshaler", type=CUSTOM])
   public tutorial.MyObject;
}

Using JCWs in Java Applications

In COM, coclasses are never directly used. You must create an instance of a coclass, request one of its implemented interfaces, and use that interface to do the work you want. Method implementations exist in the JCW coclass only to conform to The Java Language Specification by Addison Wesley. To use the coclass in an application, create an instance of it and cast it to an interface as follows:

IWebBrowserApp ie = (IWebBrowserApp) new InternetExplorer();

The following is a simple application that creates an instance of Microsoft® Internet Explorer and writes a message to the browser's status area:

package tutorial.app;
import tutorial.ie.*;
public class TutorialApp1 {
  public static void main(String args[]) {
    IWebBrowserApp ie = new InternetExplorer();
    ie.setStatusText("Our simple Java/COM sample.");
    ie.setVisible(true);
  }
}

Using JCWs with AWT Controls

Some threading issues need to be considered when using COM objects with AWT components. AWT itself is thread-safe, but as with any other hierarchy of locks, be careful when taking non-AWT locks inside of an AWT lock, such as the global AWT component lock.

COM adds another element you must consider. While inside an AWT lock, a call to a method of a non-Java/COM object may involve a thread switch. If the thread that owns the COM object is blocked on a Java object monitor, the thread won't be servicing incoming COM calls, creating another type of deadlock.

For example, the Microsoft VM's internal support for running applets inside Microsoft® Internet Explorer is careful not to take AWT locks from the browser’s GUI thread. In general, the Microsoft VM posts messages to a worker thread to make the AWT calls on behalf of the client thread. AWT applications that create COM objects should ensure that new instances of the objects are created on a separate thread. This can be accomplished by creating a new java.lang.Thread, which has been declared as a message pump thread using com.ms.com.ComLib.declareMessagePumpThread( ) at the start of the run( ) method, which runs a message pump.

Distributed COM

Any COM objects created remotely use Distributed COM (DCOM) to communicate between the local proxy and the remote COM object instance. Adding registry keys to the client computer that specifies the name of the server where the object creation occurs or using the COM API function CoCreateInstanceEx( ) will instantiate a remote instance of a COM object using DCOM. The remote computer is not required to have any registry settings only if the COM object's IDispatch interface is used.

Remote Registry Settings

COM will look under the COM object’s associated application identifier (APPID) registry key for a RemoteServerName setting. If this setting is there, its value is the server computer where the COM object should be created. COM will use this computer and the application's current security settings to create an instance of the COM object on the indicated server, and will return a proxy to the server object.

For a COM object to be usable out-of-process or remotely, the client computer must have registry entries for the COM interfaces to be used specifying the proxy/stub DLL for each interface. This DLL will contain the COM object to use as the proxy object, and performs the work of communicating references, methods calls, and lifetimes with the COM object on the server. If the COM object uses only dispinterfaces with automation types, only the type library is needed by the COM infrastructure to perform all the marshaling of data and method calls between the proxy and the client.

CoCreateInstanceEx( )

DCOM objects can be created by invoking the CoCreateInstanceEx( ) function using J/Direct. This has the advantage of removing the dependency on registry settings from the object creation and provides flexibility in specifying the security credentials used during the creation process.

For information about CoCreateInstanceEx( ), see the COM Functions Reference This link takes you to a site on microsoft.com.

The following is an example of how to use CoCreateInstanceEx( ) from Java:

private IUnknown createInstance() {
  int HRESULT = 0;
  com.ms.com.COSERVERINFO ser =  new com.ms.com.COSERVERINFO();
  ser.pwszName = "MyRemoteMachineName";
  ser.pAuthInfo = new com.ms.com.COAUTHINFO();
  ser.pAuthInfo.dwAuthnLevel = com.ms.win32.win.RPC_C_AUTHN_LEVEL_CONNECT;
  ser.pAuthInfo.dwImpersonationLevel = com.ms.win32.win.RPC_C_IMP_LEVEL_IDENTIFY;
  ser.pAuthInfo.pAuthIdentityData = new com.ms.com.COAUTHIDENTITY();
  ser.pAuthInfo.pAuthIdentityData.user = "UserName";
  ser.pAuthInfo.pAuthIdentityData.domain = "UsersDomainName";
  ser.pAuthInfo.pAuthIdentityData.password= "UsersPassword";

  //Create the Multi_Qi structure indicating which interfaces we want.
  com.ms.com.MULTI_QI mul = new com.ms.com.MULTI_QI();
  mul.pIID = com.ms.com.ComLib.getGuidOf(com.ms.com.IUnknown.class);

  //Perform the actual CreateInstance call.
  HRESULT = com.ms.win32.Ole32.CoCreateInstanceEx(new com.ms.com._Guid(clsid), null,
    com.ms.win32.win.CLSCTX_LOCAL_SERVER | com.ms.win32.win.CLSCTX_REMOTE_SERVER, ser, 1,
    new com.ms.com.MULTI_QI[]{mul});
  return(mul[0].pItf);
}

The com.ms.com.IUnknown COM object returned from the method can be cast to any JCW representing an interface implemented by the underlying COM object. For example, if the created COM object has an implementation of the IMoniker interface, it can be used like this:

int nHash = ((com.ms.com.IMoniker)COMobject).Hash();

When using CoCreateInstanceEx( ) to create instances of DCOM objects, it is important to note that the security credentials specified in the COAUTHINFO/COAUTHIDENTITY structure in the call apply only to the creation of the object. Security must be set on each interface of the COM object that will be used using the COM function CoSetProxyBlanket( ).

For information about CoSetProxyBlanket( ), see the COM Functions Reference This link takes you to a site on microsoft.com.

This can be done as follows:

/**
 *@dll.import("OLE32")
 */
public static native int CoSetProxyBlanket(
    int pProxy,                 //Indicates the proxy to set.
    int dwAuthnSvc,             //Authentication service to use.
    int dwAuthzSvc,             //Authorization service to use.
    String pServerPrincName,    //Server principal name to use with
                                // the authentication service.
    int dwAuthnLevel,           //Authentication level to use.
    int dwImpLevel,             //Impersonation level to use.
    Object pAuthInfo,           //Identity of the client.
    int dwCapabilities          //Capability flags.
);

/**
 * The IID for the IDispatch interface.
 */
  public static final com.ms.com._Guid IID_IDispatch = new com.ms.com._Guid((int)0x20400,
    (short)0x0, (short)0x0, (byte)0xc0,(byte)0x0, (byte)0x0, (byte)0x0, (byte)0x0,
    (byte)0x0, (byte)0x0, (byte)0x46);

/**
 * Method for setting security.
 */
private void setSecurity(COSERVERINFO ser, Object COMobject) {
     int intPtr = com.ms.com.ComLib.unknownToPtr(COMobject,com.ms.win32.win.IID_IUnknown);
int HRESULT = CoSetProxyBlanket(intPtr, ser.pAuthInfo.dwAuthnSvc, ser.pAuthInfo.dwAuthzSvc,
      ser.pAuthInfo.pwszServerPrincName, ser.pAuthInfo.dwAuthnLevel,
      ser.pAuthInfo.dwImpersonationLevel, ser.pAuthInfo.pAuthIdentity,
      ser.pAuthInfo.dwCapabilities);
   com.ms.com.ComLib.ptrRelease(intPtr);
try {
// This second call may throw a ClassCastException if the security settings for IUnknown
// are insufficient. The user needs to specify a higher level of security credentials
// (connect) rather than none for authentication, or impersonate rather than identify.
intPtr = com.ms.com.ComLib.unknownToPtr(COMobject, com.ms.win32.win.IID_IDispatch);
HRESULT = CoSetProxyBlanket(intPtr, ser.pAuthInfo.dwAuthnSvc, ser.pAuthInfo.dwAuthzSvc,
      ser.pAuthInfo.pwszServerPrincName, ser.pAuthInfo.dwAuthnLevel,
      ser.pAuthInfo.dwImpersonationLevel, ser.pAuthInfo.pAuthIdentity,
      ser.pAuthInfo.dwCapabilities);
com.ms.com.ComLib.ptrRelease(intPtr);
} catch(ClassCastException c) {
com.ms.com.ComLib.release(COMobject);
  object=null;
  return;
  }
}

When the previous code is used with the CoCreateInstanceEx( ) snippet, the security credentials used for creating the COM object can also be used for setting credentials on the individual interfaces. You may want to experiment with CoCreateInstanceEx( ) and CoSetProxyBlanket( ) with various security settings to develop a solid understanding of how COM handles establishing security for COM objects and proxies.

The security set on the proxy must be at least as strict as the default security for the created COM object as specified on the server. The DCOMCnfg tool can be used to view the security settings for the local computer, and to adjust the access and launch access control lists (ACLs) for individual COM classes. The MSDN™ Library and the Platform SDK provide detailed information related to DCOM security settings.

Security

JCW and JCDW classes must be loaded from a fully trusted source to be usable from Java applets or applications. This means that they must be placed on the class path, trusted class library, or in a signed .cab file. The applications or applets that use them don’t need to have any special permission if they are found on the system’s class path. The security check for loading these classes happens during the resolving phase in the class loader. Once the class is loaded, it can be used by any Java program that was loaded from that class loader.

Java/COM developers who are creating COM wrappers should consider the security implications of where they place their class files. To ensure that the wrappers are accessible from only fully trusted Java programs, the classes should be placed in the trusted class library. This means that only local applications and fully trusted applications will be able to use them.

@security

Another method of restricting the accessibility of class files is through use of the @security directive, which controls when the security checks are performed for linking to the class. When class-level @security directive is used with the checkClassLinking=on parameter, the Microsoft VM allows only fully trusted classes to use the COM wrapper. A fully trusted class is any class that has been loaded from the local class path, trusted class library, or from a signed .cab (with low permissions). The @security directive can be placed on any Java class to restrict linking to fully trusted callers, regardless of whether the class uses any J/Direct or COM directives.

Syntax

@security(checkClassLinking on | off | auto, checkDllCalls on | off)

Parameter | Description
checkClassLinking= on | off | auto | Specifies whether the Microsoft VM should allow only trusted classes to use this class (on), or whether any Java class can use this class (off). Default is auto, which specifies normal Java access checks.
checkDllCalls= on | off | If on is specified, the Microsoft VM performs a security stack crawl when a J/Direct method is invoked. If the classes on the stack are untrusted and permissions have not been asserted, the J/Direct call throws a SecurityException. Off disables the requirement that all callers on the stack be fully trusted. Default is on.

The following table shows the affected attributes.

Attribute | Scope
LinkSafe | Class scope.
LinkUnsafe | Class scope.
NAT_L_DCTS | Class scope.

Sources for Additional Information

Integrating Java and COM

Attributes Reference

Compiler Directives Reference


Samples Overview

The Microsoft SDK for Java includes over 90 samples to be used as a reference for Java application development. When you download the SDK for Java, these samples are installed in the %SDKDIR%\Samples folder and its subfolders. This overview serves as a roadmap to the samples. Full documentation on all samples is available from the Start.htm file in the \Samples folder.

Note For users of Microsoft® Visual J++®, the Samples contained within the Microsoft SDK for Java support newer features supported by the Microsoft Compiler for Java (Jvc.exe).

To use these new language features with Microsoft® Visual J++® and the Microsoft SDK for Java Samples, you must replace three files in Visual J++ with their respective SDK versions:

  1. Back up the current Visual J++ versions of Jvc.exe, Jps.dll, and Msjvc.dll.

  2. Copy Jvc.exe, Jps.dll, and Msjvc.dll from %SDKDIR%\Bin to your Visual J++ directory. Projects and samples will then build using the new compiler.

The samples are organized by category according to the technologies they demonstrate. Samples that illustrate several technologies are listed in more than one category.

The following sections provide a brief overview of the samples provided:

ActiveX Samples

AFC11 Samples

AFC102 Samples

ASP Java Component Framework Samples

COM Samples

Debugger Samples

DirectAnimation

DirectX Samples

Internationalization Samples

JDBC Samples

J/Direct Samples

MTS Samples

Native Code Samples

Packaging Samples

Profiler Samples

Scripting Samples

Security Samples

WFC Samples

Windows Samples


ActiveX Samples

Microsoft® ActiveX® is a language-neutral component model that uses COM as its base. The Microsoft virtual machine (Microsoft VM) integrates ActiveX Controls and JavaBeans so that an ActiveX control appears as a Bean to the Java programmer. Similarly, the JavaBeans component appears as an ActiveX control to you and your control container. For more information, see Integrating JavaBeans and ActiveX.

The following ActiveX samples are provided.

Sample Description
AFC Bean Location: \Samples\ActiveX\AFCBean

Technologies: ActiveX, AFC

Demonstrates:

  • Writing a pure AFC object and hosting it inside an ActiveX container.
Calendar Location: \Samples\ActiveX\Calendar

Technologies: ActiveX

Demonstrates:

  • Hosting the Microsoft ActiveX Calendar control in a jview application.
Event Location: \Samples\Scripting\Event

Technologies: Scripting, ActiveX

Demonstrates:

  • Handling events from Java applets using scripting.
Invoke Bean Location: \Samples\ActiveX\Invoke

Technologies: ActiveX

Demonstrates:

  • Hosting the Microsoft ActiveX Calendar control in a jview application.
JBrowser Location: \Samples\ActiveX\JBrowser

Technologies: ActiveX

Demonstrates:

  • Hosting the WebBrowser ActiveX Control in a Java application.
JCalendar Location: \Samples\ActiveX\JCalendar

Technologies: ActiveX

Demonstrates:

  • Creating a complete JavaBean with properties, events, icons, and property editors.
JChart Location: \Samples\ActiveX\JChart

Technologies: ActiveX

Demonstrates:

  • Various techniques used to create JavaBeans.
Organizaton Tree Location: \Samples\Scripting\orgtree

Technologies: Scripting, ActiveX, AFC

Demonstrates:

  • Controlling an applet through scripting.

  • Hosting a JavaBean in an ActiveX container.
Sample Bean Location: \Samples\ActiveX\SampleBean

Technologies: ActiveX, AFC

Demonstrates:

  • Creating a JavaBean that handles simple events and can be added as a control to an ActiveX container.
SimpleOCXControl Location: \Samples\Wfc\SimpleOCXControl

Technologies: WFC, ActiveX

Demonstrates:

  • Creating custom WFC controls.

  • Using WFC controls as Microsoft® ActiveX® Controls.

  • Using Design-time property editors.


AFC102 Samples

The Microsoft Application Foundation Classes (AFC) is a set of Java class libraries that provide user interface components and graphics effects for use in Java applets and applications. For additional information on AFC, see the Microsoft SDK for AFC.

The AFC 1.0.2 samples are compatible with the Java Development Kit (JDK) 1.0.2. In order to run the AFC 1.0.2 samples, you must install the Microsoft SDK for AFC This link takes you to a site on microsoft.com.

The AFC 1.0.2 samples work with Netscape Navigator 3.04, Netscape Communicator 4.03, and Netscape Communicator 4.04 (without the Netscape Java 1.1 developer patch). The behavior exhibited under non-compatible browsers is the closing of the browser without warning.

Versions of these samples that are compatible with JDK 1.1 are also provided in the \Samples\afc11 directory.

The following AFC 1.0.2 samples are provided.

Sample Description
AFC Detect Location: \Samples\afc102\AFCDetect

Technologies: AFC, packaging

Demonstrates:

  • Using the com.ms.util.SystemVersionManager class to retrieve package version information and take appropriate actions (such as installing new package versions). The sample determines whether AFC is installed on a computer and which version is installed.
Bands and Menus Location: \Samples\afc102\BandsnMenus

Technologies: AFC

Demonstrates:

  • Using AFC graphics and effects classes to create and manipulate bands, buttons, menus, and scrollable viewers.
Buttons Location: \Samples\afc102\Buttons

Technologies: AFC

Demonstrates:

  • Using AFC graphics and effects classes to create various types of button controls.
FxShapes Location: \Samples\afc102\FxShapes

Technologies: AFC

Demonstrates:

  • Using the various pen lines, shapes, and styles provided by the com.ms.fx package.
JTreeVue Location: \Samples\afc102\JTreeVue

Technologies: AFC

Demonstrates:

  • Using AFC components to build a class hierarchy tree.
Lists Location: \Samples\afc102\Lists

Technologies: AFC

Demonstrates:

  • Using the various list types and selection options provided by AFC's UIList controls.
Loan Calculator Location: \Samples\afc102\LoanCalc

Technologies: AFC

Demonstrates:

  • Using AFC classes to create applets or applications that use wizards for user input.
Puzzle 15 Location: \Samples\afc102\Puzzle15

Technologies: AFC

Demonstrates:

  • Using AFC classes to create property sheets and various types of UI controls.
Scrolls Location: \Samples\afc102\Scrolls

Technologies: AFC

Demonstrates:

  • Using AFC classes to create scroll, spin box, slider, and progress monitoring controls.
Statics Location: \Samples\afc102\Statics

Technologies: AFC

Demonstrates:

  • Using AFC classes to create and manipulate various types of static controls.
Viewers Location: \Samples\afc102\Viewers

Technologies: AFC

Demonstrates:

  • Using AFC classes to create various types of viewers.

  • Using classes in the com.ms.object and com.ms.object.dragdrop packages to provide
    drag-and-drop functionality.

  • A com.ms.ui component hosting an AWT component, and an AWT component hosting a com.ms.ui component.

The following additional samples also demonstrate how to use AFC:

Sample Description
AFC Bean Location: \Samples\ActiveX\AFCBean

Technologies: ActiveX, AFC

Demonstrates:

  • Writing a pure AFC object and hosting it inside an ActiveX container.
Class Decoder Location: \Samples\Wfc\ClassDecoder

Technologies: WFC, AFC, COM, J/Direct

Demonstrates:

  • Building a WFC application.

  • Decoding Java class files into the attributes, structures, and properties that make up the class.
Organization Tree Location: \Samples\Scripting\orgtree

Technologies: Scripting, ActiveX, AFC

Demonstrates:

  • Controlling an applet through scripting.

  • Hosting a JavaBean in an ActiveX container.
SampleBean Location: \Samples\ActiveX\SampleBean

Technologies: ActiveX, AFC

Demonstrates:

  • Creating a JavaBean that handles simple events and can be added as a control to an ActiveX container.
Win32 Resource Loading Location: \Samples\Windows\Win32ResSupport

Technologies: Windows, AFC, internationalization, packaging

Demonstrates:

  • Using the supported Microsoft® Win32® resource styles and controls included with the Win32ResourceDecoder class in the com.ms.ui.resource package.

  • Using Win32 resource (.res) files to develop multilingual applications.

  • Using the resmerge tool to combine multiple Win32 resource files into a single file.


AFC11 Samples

The Microsoft Application Foundation Classes (AFC) is a set of Java class libraries that provide user interface components and graphics effects for use in Java applets and applications. For additional information on AFC, see the Microsoft SDK for AFC.

AFC samples located in the \Samples\Afc11 directory are compatible with the Java Development Kit (JDK) 1.1. (A subset of these samples, compatible with JDK 1.0.2, is also provided in the \Samples\afc102 directory.) The AFC 1.1 samples are compatible with Netscape Communicator 4.06 through 4.08 and Netscape Communicator 4.5. Netscape 4.04 is compatible only where the Netscape Java 1.1 developer patch has been installed. The behavior exhibited under non-compatible browsers is the closing of the browser without warning.

The following AFC 1.1 samples are provided.

Sample Description
AFC Detect Location: \Samples\Afc11\AFCDetect

Technologies: AFC, packaging

Demonstrates:

  • Using the com.ms.util.SystemVersionManager class to retrieve package version information and take appropriate actions (such as installing new package versions). The sample determines whether AFC is installed on a computer and which version is installed.
Bands and Menus Location: \Samples\Afc11\BandsnMenus

Technologies: AFC

Demonstrates:

  • Using AFC graphics and effects classes to create and manipulate bands, buttons, menus, and scrollable viewers.
Buttons Location: \Samples\Afc11\Buttons

Technologies: AFC

Demonstrates:

  • Using AFC graphics and effects classes to create various types of button controls.
FxShapes Location: \Samples\Afc11\FxShapes

Technologies: AFC

Demonstrates:

  • Using the various pen lines, shapes, and styles provided by the com.ms.fx package.
FxTextures Location: \Samples\Afc11\FxTextures

Technologies: AFC

Demonstrates:

  • Using the texture options provided by the com.ms.fx.FxTexture class.
JNotepad Location: \Samples\Afc11\JNotepad

Technologies: AFC

Demonstrates:

  • Using AFC classes to create complete applications. The sample is a full-featured text editor.
JTreeVue Location: \Samples\Afc11\JTreeVue

Technologies: AFC

Demonstrates:

  • Using AFC components to build a class hierarchy tree.
Lists Location: \Samples\Afc11\Lists

Technologies: AFC

Demonstrates:

  • Using the various list types and selection options provided by AFC's UIList controls.
Loan Calculator Location: \Samples\Afc11\LoanCalc

Technologies: AFC

Demonstrates:

  • Using AFC classes to create applets or applications that use wizards for user input.
Puzzle 15 Location: \Samples\Afc11\Puzzle15

Technologies: AFC

Demonstrates:

  • Using AFC classes to create property sheets and various types of UI controls.
Scrolls Location: \Samples\Afc11\Scrolls

Technologies: AFC

Demonstrates:

  • Using AFC classes to create scroll, spin box, slider, and progress monitoring controls.
Statics Location: \Samples\Afc11\Statics

Technologies: AFC

Demonstrates:

  • Using AFC classes to create and manipulate various types of static controls.
Viewers Location: \Samples\Afc11\Viewers

Technologies: AFC

Demonstrates:

  • Using AFC classes to create various types of viewers.

  • Using classes in the com.ms.object and com.ms.object.dragdrop packages to provide drag-and-drop functionality.

  • A com.ms.ui component hosting an AWT component, and an AWT component hosting a com.ms.ui component.

The following additional samples also demonstrate how to use AFC:

Sample Description
AFC Bean Location: \Samples\ActiveX\AFCBean

Technologies: ActiveX, AFC

Demonstrates:

  • Writing a pure AFC object and hosting it inside an ActiveX container.
Class Decoder Location: \Samples\Wfc\ClassDecoder

Technologies: WFC, AFC, COM, J/Direct

Demonstrates:

  • Building a WFC application.

  • Decoding Java class files into the attributes, structures, and properties that make up the class.
Organization Tree Location: \Samples\Scripting\orgtree

Technologies: Scripting, ActiveX, AFC

Demonstrates:

  • Controlling an applet through scripting.

  • Hosting a JavaBean in an ActiveX container.
SampleBean Location: \Samples\ActiveX\SampleBean

Technologies: ActiveX, AFC

Demonstrates:

  • Creating a JavaBean that handles simple events and can be added as a control to an ActiveX container.
Win32 Resource Loading Location: \Samples\Windows\Win32ResSupport

Technologies: Windows, AFC, internationalization, packaging

Demonstrates:

  • Using the supported Microsoft® Win32® resource styles and controls included with the Win32ResourceDecoder class in the com.ms.ui.resource package.

  • Using Win32 resource (.res) files to develop multilingual applications.

  • Using the resmerge tool to combine multiple Win32 resource files into a single file.


ASP Java Component Framework Samples

The Active Server Pages (ASP) Java Component Framework simplifies creating Active Server components by creating new interfaces that expose the ASP object model. The goal is to retain all the features and flavor of the ASP programming model, but to expose it in a way that is more natural for the Java programmer. The classes use native Java types and support native Java interfaces.

The following ASP Java Component Framework samples are provided.

Sample Description
Accessing Built-in ASP Objects Location: \Samples\ASP

Technologies: ASP

Demonstrates:

  • Calling ASP objects directly without using the ASP Java Component Framework.
Forms and Cookies Location: \Samples\ASP

Technologies: ASP

Demonstrates:

  • Accessing form variables and cookies using the ASP Java Component Framework.
Server Variable Enumeration Location: \Samples\ASP

Technologies: ASP

Demonstrates:

  • Using the Framework to access HTTP server variables.
File Expiration Location: \Samples\ASP

Technologies: ASP

Demonstrates:

  • Using Java dates with ASP.

  • Setting the page cache expiration date.
HelloWorld Location: \Samples\ASP

Technologies: ASP

Demonstrates:

  • Creating a simple Java class.
Java and Tables Location: \Samples\ASP

Technologies: ASP, Windows, J/Direct

Demonstrates:

  • Creating an HTML table based on attributes set by the caller.
Binary Data Output Location: \Samples\ASP

Technologies: ASP

Demonstrates:

  • Using the framework to output binary data.


COM Samples

Java/COM integration lets you combine Java's advantages with COM and develop components that can interact with operating systems, applications, and services written in any COM-compliant language on any platform.

Most of the Microsoft® Windows® functionality is exposed through COM, and most Microsoft applications provide COM interfaces to their object models. At the same time, Java offers automatic garbage collection and replaces pointers with references, while the Microsoft virtual machine (Microsoft VM) automatically handles object references, cleanup, and interface queries for any COM object used in Java, whether the component was written in Java or another COM-compliant language.

The Microsoft VM also provides automatic mapping, allowing a Java object to be a COM object, and allowing any COM object to be accessible as a Java object. For more information, see Integrating Java and COM.

The following COM samples are provided.

Sample Description
Class Decoder Location: \Samples\Wfc\ClassDecoder

Technologies: WFC, AFC, COM, Microsoft® J/Direct™

Demonstrates:

  • Building a WFC application.

  • Decoding Java class files into the attributes, structures, and properties that make up the class.
CoCreateInstanceEx Location: \Samples\Com\CCIEx

Technologies: COM, DCOM, J/Direct

Demonstrates:

  • Implementing a Java/COM object with custom IDL-defined interfaces.

  • Implementing a Java client application that uses a J/Direct call to CoCreateInstanceEx to create instances of an in-process COM object from a local server and from a remote client.
COM Location: \Samples\Com\Com

Technologies: COM

Demonstrates:

  • Implementing a simple Java/COM object and register it using javareg.

  • Using jactivex with a type library to generate Java wrappers and use them in a Java application.
COM Class Object Location: \Samples\Com\ComClassObject

Technologies: COM

Demonstrates:

  • Implementing a COM class object and a small class client that co-creates the object through the same Java implemented interface.
COM iid_is and size_is Location: \Samples\Com\iid_is_size_is

Technologies: COM, Jactivex

Demonstrates:

  • Creating an interface that uses the new iid_iis and size_is marshaling support of the 32xx series Microsoft VM and jactivex.
COM Security Location: \Samples\Com\Security_com

Technologies: COM, security

Demonstrates:

  • Implementing Call security on a Java/COM object using the com.ms.security package.

  • Implementing a Java/COM object with a custom interface.

  • Implementing a C COM object with a custom interface.

  • Defining a custom interface in IDL.
Custom Marshaling Location: \Samples\Com\CustomMarshal

Technologies: COM, custom marshaling

Demonstrates:

  • Implementing custom marshaling between Java and COM.

  • Marshaling simple structure types, variable-sized data, VARIANTs, and mutable Java objects.

  • Using hook classes.

  • Custom allocation support.
Dispatch Location: \Samples\Com\Dispatch

Technologies: COM

Demonstrates:

  • Implementing and registering a simple Java/COM object.

  • Creating an instance of Java/COM object using CoCreateInstanceEx from a J/Direct call.

  • Invoking methods on a COM object using its IDispatch interface through the com.ms.com.Dispatch class.
IMarshal Location: \Samples\Com\IMarshal

Technologies: COM, J/Direct

Demonstrates:

  • Using Java-implemented structures, arrays of structures, and embedded structures.

  • Implementing the IMarshal interface on a Java/COM object.

  • Creating a COM server in Java by creating a Java/COM object that implements IClassFactory.

  • Implementing a COM proxy object in Java that can be used by a client without registry settings.
IPersist Location: \Samples\Com\Ipersist

Technologies: COM, native code

Demonstrates:

  • How the Microsoft virtual machine automatically exposes an IPersist interface for any Java object that implements java.io.Externalizable or java.io.Serializable. The sample uses the exposed COM persist interfaces to write the Java/COM object into a simple IStream and to a structured storage file.

  • How a C application can create an instance of a Java/COM object and use its IPersistStreamInit interface.
Java/COM Apartment Model Threading Location: \Samples\Com\JCOMApartment

Technologies: COM, native code

Demonstrates:

  • Implementing a Java/COM object with an IDL-defined interface.

  • Building a Java application that creates and uses out-of-process Java/COM objects with a custom interface.

  • Creating a C application that hosts Single-Threaded Apartment Java/COM objects.
Java/COM Communications Location: \Samples\Com\Native_com

Technologies: COM, native code

Demonstrates:

  • Java-COM and COM-Java communications

  • Java-Callable Wrappers

  • COM-Callable Wrappers
Java/COM DLL Stub Location: \Samples\Com\Jexegen\Stub

Technologies: Jexegen

Demonstrates:

  • Creating a DLL and implementing a component in that DLL.
Raw Native Interface Location: \Samples\Native\Native_raw

Technologies: Native interface, COM

Demonstrates:

  • The native interface of the Microsoft VM and native code operations that are garbage-collector safe.
NT Service Location: \Samples\Com\NTService

Technologies: COM, native code, J/Direct, Windows

Demonstrates:

  • Building an Microsoft® Windows NT® Service using only Java, and implementing the Service Main and Service Control as Java classes.

  • Using the Windows NT Event Log with a custom message file.
OleMode Location: \Samples\JDirect\olemode

Technologies: J/Direct, COM

Demonstrates:

  • Using @dll.import with the ole keyword.
SafeArray Location: \Samples\Com\SafeArray

Technologies: COM, J/Direct

Demonstrates:

  • Using @com directives with CLSIDs and IIDs.

  • How to create a SafeArray in Java, pass it to a COM server written in Visual Basic, inspect the SafeArray when returned from a COM server, and extract all or some of its elements.
Variant SafeArray Location: \Samples\Com\VariantSafeArray

Technologies: COM

Demonstrates:

  • Passing Variants and SafeArrays of data between a Microsoft® Visual Basic® COM component and a Java application.


Debugger Samples

The debugger interfaces assist in the detection, location, and correction of logical or syntactical errors in Java applications, applets, and COM objects that are run in the Microsoft virtual machine (Microsoft VM). These interfaces can also be used for debugging Java code that mixes Java classes with native Microsoft® Win32® code. For additional information, see the Debugger Interfaces Overview.

The following debugger sample is provided.

Sample Description
Debugger Location: \Samples\Debugger

Technologies: VM debugger interfaces, native code

Demonstrates:

  • How to use the debugger interfaces exposed by the Microsoft VM. The sample contains examples of creating a C++ debugger, tracing a method call, and implementing a Java debugger.


DirectAnimation Samples

For Microsoft® DirectAnimation™ samples that combine 3-D models, sound, movies, and animation paths, download the DirectAnimation tutorial and samples from http://www.microsoft.com/directx/overview/danim/default.asp This link takes to you a site on microsoft.com.


DirectX Samples

The com.ms.directX package provides the classes and interfaces needed by Java programs and applets to access the services and features of the Microsoft® DirectX® Component Object Model (COM) interface for Microsoft® Windows®. See com.ms.directX for detailed reference information on the DirectX package. For additional information on how to use DirectX classes, see the DirectX Software Development Kit and the MSDN™ Library.

To use these samples, you must have the DirectX runtime installed.

The following DirectX samples are provided.

Sample Description
Castle Location: \Samples\DirectX\D3drmcastle

Technologies: DirectX

Demonstrates:

  • Using Microsoft Direct3D Retained Mode features, with an emphasis on the settings required for high-performance rendering.
Direct Draw Location: \Samples\DirectX\Ddraw

Technologies: DirectX

Demonstrates:

  • The high performance of Microsoft® DirectDraw® when working with Java.
Direct Input Location: \Samples\DirectX\Dinput

Technologies: DirectX

Demonstrates:

  • Using joysticks with the Microsoft DirectDraw sample.
Direct Play Location: \Samples\DirectX\Dplay

Technologies: DirectX

Demonstrates:

  • Using the Microsoft DirectX for JavaDirectPlay object to implement a simple chat applet.
Direct Sound Location: \Samples\DirectX\Dsound

Technologies: DirectX

Demonstrates:

  • Using Microsoft® DirectSound®.
Flip Cube Location: \Samples\DirectX\D3d

Technologies: DirectX

Demonstrates:

  • Using three-dimensional immediate mode, including creating and using execute buffers.
Viewer Location: \Samples\DirectX\D3drmviewer

Technologies: DirectX

Demonstrates:

  • Using Microsoft Direct3D Retained Mode features, including different lighting and rendering styles, different models, and fog.


Internationalization Samples

The Microsoft SDK for Java enhances the internationalization features of Java with support for local character set encoding, Microsoft® Win32® resources, locales, vertical writing, and Java-based input method editors (IMEs). For more information about the SDK's internationalization support, see Internationalization.

The following internationalization sample is provided.

Sample Description
Sample Input Method Editor Location: \Samples\International\Sampleime

Technologies: Internationalization

Demonstrates:

  • Implementing a Java-based, level 2 Input Method Editor (IME) using the InputMethodListener and InputMethodCallback interfaces.
Win32 Resource Loading Location: \Samples\Windows\Win32ResSupport

Technologies: Windows, AFC, Internationalization

Demonstrates:

  • Using the supported Microsoft® Win32® resource styles and controls included with the Win32ResourceDecoder class in the com.ms.ui.resource package.

  • Using Win32 resource (.res) files to develop multilingual applications.

  • Using the resmerge tool to combine multiple Win32 resource files into a single file.


JDBC Samples

The Microsoft JDBC-ODBC bridge is part of the core set of classes that come with the Microsoft virtual machine. The relevant classes are part of the com.ms.jdbc.odbc package.

The following JDBC sample is provided.

Sample Description
JDBC/ODBC Bridge Location: \Samples\Jdbc

Technologies: JDBC

Demonstrates:

  • Using the Microsoft JDBC/ODBC bridge.


J/Direct Samples

Microsoft® J/Direct™ allows you to directly call an unmodified dynamic-link library (DLL) without having to write an intermediate wrapper DLL. J/Direct provides seamless and automatic type conversion of a large set of commonly used data types, eliminating most manual type conversion.

One specific use of J/Direct is to provide Java processes with access to the Microsoft® Win32® APIs. Another use of J/Direct is to call custom APIs provided in third-party DLLs. The Microsoft virtual machine (Microsoft VM) automatically translates common Java data types to those expected by C functions. For more info, see Integrating Java and Win32 using J/Direct.

The following J/Direct samples are provided.

Sample Description
AutoMode Location: \Samples\JDirect\automode

Technologies: J/Direct

Demonstrates:

  • Using @dll.import with the auto keyword.
CdPlayer Location: \Samples\JDirect\Cdplayer

Technologies: J/Direct

Demonstrates:

  • Using @dll.import calls to the com.ms.win32.Winmm API.
CdPlay2 Location: \Samples\JDirect\Cdplay2

Technologies: J/Direct

Demonstrates:

  • Using the com.ms.win32 APIs.
Class Decoder Location: \Samples\Wfc\ClassDecoder

Technologies: WFC, AFC, COM, J/Direct

Demonstrates:

  • Building a WFC application.

  • Decoding Java class files into the attributes, structures, and properties that make up the class.
CoCreateInstanceEx Location: \Samples\Com\CCIEx

Technologies: COM, DCOM, J/Direct

Demonstrates:

  • Implementing a Java/COM object with custom IDL-defined interfaces.

  • Implementing a Java client application that uses a J/Direct call to CoCreateInstanceEx to create instances of an in-process COM object, form a local server, and form a remote client.
Cryptography Location: \Samples\Windows\Crypto

Technologies: Windows, J/Direct

Demonstrates:

  • Using the Windows Cryptography API from Java.

  • Importing Win32 API functions that use Windows error codes and mapping these to Java methods that throw com.ms.dll.Win32Exceptions.

  • Creating a custom input and output stream class.
C to Java Parser Location: \Samples\JDirect\CToJParser

Technologies: J/Direct

Demonstrates:

  • Exposing functions from DLLs and providing access to them in Java using J/Direct.
FuncPtr1 Location: \Samples\JDirect\Funcptr1

Technologies: J/Direct

Demonstrates:

  • Using @dll.import to call USER32.DLL.

  • Using Handles (hWnds) and abstract classes.
FuncPtr2 Location: \Samples\JDirect\Funcptr2

Technologies: J/Direct

Demonstrates:

  • Using the com.ms.dll.DllLib.ptrToStruct method to work around the limitation that the callback can take only integer parameters. The ptrToStruct method acts like a C-style cast.

  • Using the auto parameter of @dll.struct.
LastErr Location: \Samples\JDirect\Lasterr

Technologies: J/Direct

Demonstrates:

  • Using com.ms.dll.Win32Exception.

  • Using @dll.import.

  • Using @dll.struct.
Java and Tables Location: \Samples\ASP

Technologies: ASP, Windows, J/Direct

Demonstrates:

  • Creating an HTML table based on attributes set by the caller.
Java Media Player Location: \Samples\JDirect\mediaplayer

Technologies: JDirect

Demonstrates:

  • Calling one function (MCISendCommand) to play different media files (audio and video) for the Windows format.
NT Service Location: \Samples\Com\NTService

Technologies: COM, native code, J/Direct, Windows

Demonstrates:

  • Building an Microsoft® Windows NT® Service using only Java, and implementing the Service Main and Service Control as Java classes.

  • Using the Windows NT Event Log with a custom message file.
OleMode Location: \Samples\JDirect\olemode

Technologies: J/Direct, COM

Demonstrates:

  • Using @dll.import with the ole keyword.
Pointers Location: \Samples\JDirect\Pointers

Technologies: J/Direct

Demonstrates:

  • Parsing data through a double-indirected pointer.
SDump Location: \Samples\JDirect\Sdump

Technologies: J/Direct

Demonstrates:

  • Using the Reflection API with com.ms.com.DllLib to examine the physical layout of a class declared with @dll.struct.
Simple J/Direct Sample Location: \Samples\JDirect\Simple

Technologies: J/Direct

Demonstrates:

  • Using the @dll.import J/Direct directive in code.
Strings Location: \Samples\JDirect\Strings

Technologies: J/Direct

Demonstrates:

  • Using @dll.import to read the contents of KERNEL.DLL.

  • Using the com.ms.dll.DllLib.ptrToStringAnsi method, which extracts strings from a series of concatenated strings.
Structs Location: \Samples\JDirect\Structs

Technologies: J/Direct

Demonstrates:

  • Using @dll.import and @dll.struct to read the memory contents of KERNEL.DLL and display the results.

  • Passing a pointer to a simple structure. To declare a native structure in Java, use the @dll.struct directive as shown in the MEMORYSTATUS structure in Structs.java.
TBarIcon Location: \Samples\JDirect\Tbaricon

Technologies: J/Direct, Windows

Demonstrates:

  • Using mouse events and callback classes.


MTS Samples

Microsoft® Transaction Server (MTS) is a component-based transaction processing system for developing, deploying, and managing high-performance, scalable, and robust enterprise, Internet, and intranet server applications. MTS defines a programming model for developing distributed, component-based applications. It also provides a run-time infrastructure and a graphical tool for deploying and managing these applications. MTS application components can be built using Java. For more information on integrating Java with MTS, see the Integration.chm file located in the %SDKDIR%\Docs directory.

The following MTS sample is provided.

Sample Description
MTS Sample Bank Application Location: \Samples\Mts

Technologies: MTS

Demonstrates:

  • Building MTS application components using Java.

Note This sample is designed to run on operating systems prior to Microsoft® Windows® 2000.


Native Code Samples

The Microsoft virtual machine supports the integration of Java with native code. These samples demonstrate some of ways in which Java can be integrated with native code, including using the Raw Native Interface (RNI), J/Direct, and Java/COM integration. For more information, see the following sections:

Integrating Java and COM

Integrating JavaBeans and ActiveX

Integrating Java and Win32 using J/Direct

Integrating Java and Windows using Raw Native Interface (RNI)

The following native code samples are provided.

Sample Description
Browser Applet Control Location: \Samples\Native\BrowserAppletControl

Technologies: Native code

Demonstrates:

  • Using the Microsoft® ActiveX® Browser Applet Control.

  • Creating an application in C that can host Java applets.
Debugger Location: \Samples\Debugger

Technologies: VM debugger interfaces, native code

Demonstrates:

  • How to use the debugger interfaces exposed by the Microsoft VM. The sample contains examples of creating a C++ debugger, tracing a method call, and implementing a Java debugger.
Invocation Location: \Samples\Native\Invocation

Technologies: RNI

Demonstrates:

  • Using the PrepareThreadForJava and UnprepareThreadForJava invocation APIs.

  • Using a Java object from a C application.
IPersist Location: \Samples\Com\Ipersist

Technologies: COM, native code

Demonstrates:

  • How the Microsoft virtual machine automatically exposes an IPersist interface for any Java object that implements java.io.Externalizable or java.io.Serializable. The sample uses the exposed COM persist interfaces to write the Java/COM object into a simple IStream and to a structured storage file.

  • How a C application can create an instance of a Java/COM object and use its IPersistStreamInit interface.
Java/COM Apartment Model Threading Location: \Samples\Com\JCOMApartment

Technologies: COM, native code

Demonstrates:

  • Implementing a Java/COM object with an IDL-defined interface.

  • Building a Java application that creates and uses out-of-process Java/COM objects with a custom interface.

  • Creating a C application that hosts Single-Threaded Apartment Java/COM objects.
Jexegen Location: \Samples\Native\Jexegen

Technologies: Native code, packaging

Demonstrates:

  • Packaging Java applications as executables using the jexegen tool.

  • Attaching an arbitrary native stub to a Java application to create stand-alone executables.

  • Starting the Microsoft VM using C code and running an arbitrary Java application.
JView Location: \Samples\Native\JView

Technologies: Native code

Demonstrates:

  • Creating an instance of the Microsoft VM in a C application to run Java applications.
NT Service Location: \Samples\Com\NTService

Technologies: COM, native code, J/Direct, Windows

Demonstrates:

  • Building an Microsoft® Windows NT® Service using only Java, and implementing the Service Main and Service Control as Java classes.

  • Using the Windows NT Event Log with a custom message file.
Raw Native Interface Location: \Samples\Native\Native_raw

Technologies: RNI

Demonstrates:

  • The native interface of the Microsoft VM and native code operations that are garbage-collector safe.
RNI Security Location: \Samples\Security\Rni

Technologies: Security, RNI

Demonstrates:

  • Protecting access to resources from native code.
Sample Monitor Location: \Samples\Profiler\SampMon

Technologies: Profiler, native code

Demonstrates:

  • Defining a simple implementation of several Microsoft VM event monitor interfaces.


Packaging Samples

A Java package is a collection of classes that share a common namespace. Packages are easier to work with when they are encapsulated in a single file. The Microsoft SDK for Java provides tools for archiving packages in two formats (cabinet files and distribution units), and a package manager that can be used in conjunction with Microsoft® Internet Explorer to download and install packages. For more information on packaging, see Packaging and Distributing Software.

The following packaging samples are provided.

Sample Description
AFC Detect Location: \Samples\afc11\AFCDetect

Technologies: AFC, packaging

Demonstrates:

  • Using the com.ms.util.SystemVersionManager class to retrieve package version information and take appropriate actions (such as installing new package versions). The sample determines whether AFC is installed on a computer and which version is installed.
Cabinet File Creation Location: \Samples\Packaging\Create

Technologies: Packaging

Demonstrates:

  • Using the CabCreator class in com.ms.util.cab to create cabinet files.
Cabinet File Extraction Location: \Samples\Packaging\Extract

Technologies: Packaging

Demonstrates:

  • Using the cabinet decoder classes in com.ms.util.cab to extract files from cabinets.
Java Package Manager Location: \Samples\Packaging\Pkgmgmt

Technologies: Packaging, Java Package Manager (JPM), HTML scripting, security

Demonstrates:

  • Building cabinet files using the Microsoft SDK for Java.

  • Signing cabinet files for use in a Web browser.

  • Generating certificates for signing cabinet files using tools provided by the Microsoft SDK for Java.

  • Using HTML script to run an applet that installs classes into the local computer's package manager.

  • Using JPM to install applications, class libraries, and applets.
Jexegen Location: \Samples\Native\Jexegen

Technologies:Native code, packaging

Demonstrates:

  • Packaging Java applications as executables using the jexegen tool.

  • Attaching an arbitrary native stub to a Java application to create stand-alone executables.

  • Starting the Microsoft VM using C code and running an arbitrary Java application.
Win32 Resource Loading Location: \Samples\Windows\Win32ResSupport

Technologies: Windows, AFC, internationalization, packaging

Demonstrates:

  • Using the supported Microsoft® Win32® resource styles and controls included with the Win32ResourceDecoder class in the com.ms.ui.resource package.

  • Using Win32 resource (.res) files to develop multilingual applications.

  • Using the resmerge tool to combine multiple Win32 resource files into a single file.


Profiler Samples

The Java profiler interfaces assist in the analysis of Java code for speed, memory use, redundancy, and other performance factors. The profiler interfaces are Component Object Model (COM) objects and interfaces implemented by the Microsoft virtual machine (Microsoft VM). The profiler interfaces support any number of concurrently operating event monitors, thus profiling both execution time and memory usage. These interfaces can also profile components that mix Java classes with Microsoft® Win32® native code. For more information, see Profiler Interfaces Overview.

The following profiler samples are provided.

Sample Description
Heap Monitor Location: \Samples\profiler\heapmon

Technologies: Profiler

Demonstrates:

  • Using the heap monitor interfaces to create tools for finding memory leaks and inspect application state.
JView Profiler Location: \Samples\Profiler\JviewPrf

Technologies: Profiler

Demonstrates:

  • Defining a simple implementation of several Microsoft VM event monitor interfaces. This sample uses two new configurations of the jview tool, pjview and pwjview, which run and profile applications and applets.
Sample Monitor Location: \Samples\Profiler\SampMon

Technologies: Profiler, native code

Demonstrates:

  • Defining a simple implementation of several Microsoft VM event monitor interfaces.


Scripting Samples

The Microsoft virtual machine (Microsoft VM) makes Java applets scriptable. When a Java applet is running in a browser, such as Microsoft® Internet Explorer, most of the public methods and variables of the applet automatically become available to Microsoft® Visual Basic® Scripting Edition (VBScript) or any other language supporting the Microsoft® ActiveX® scripting protocol. Additionally, COM objects can implement the IDispatch interface to make themselves accessible from high-level languages such as Visual Basic and scripting languages such as JavaScript, VBScript, and Active Server Pages.

For more information, see the following topics:

Controlling an Applet Using Scripting

Integrating Java and COM

The following scripting samples are provided.

Sample Description
Event Location: \Samples\Scripting\Event

Technologies: Scripting, ActiveX

Demonstrates:

  • Handling events from Java applets using scripting.
Organization Tree Location: \Samples\Scripting\orgtree

Technologies: Scripting, ActiveX, AFC

Demonstrates:

  • Controlling an applet through scripting.

  • Hosting a JavaBean in an ActiveX containe.
Java Package Manager Location: \Samples\Packaging\Pkgmgmt

Technologies: Packaging, Java Package Manager (JPM), HTML scripting, security

Demonstrates:

  • Building cabinet files using the Microsoft SDK for Java.

  • Signing cabinet files for use in a Web browser.

  • Generating certificates for signing cabinet files using tools provided by the Microsoft SDK for Java.

  • Using HTML script to run an applet that installs classes into the local computer's package manager.

  • Using JPM to install applications, and signed and unsigned applets.
Script Debugger Location: \Samples\Scripting\Script Debugger

Technologies: Scripting, COM

Demonstrates:

  • How a Java applet can communicate with JScript content on an HTML page.

  • Using a scripting object through its exposed IDispatch interface.
INI Files for Java Code Signing Location: \Samples\Security\sign

Technologies: Security, code signing, scripting

Demonstrates:

  • Using .ini files to sign Java code. Several sample .ini files are provided, showing high, medium, and low permissions.
XML Data Source Object Location: \Samples\Scripting\xmldso

Technologies: Java XML DSO Data Source Provider; JavaScript interface to the XML Java Parser

Demonstrates:

  • Using the XMLDSO applet (provided by the com.ms.xml.dso package) as an XML data provider for the data binding features of Microsoft® Internet Explorer 4.0.


Security Samples

Trust-based security for Java is a cross-platform security model that provides fine-grained administration of the permissions granted to Java applets and libraries. This permission model provides control over what a Java class can do by providing a way to associate a set of permissions with a class. Encoding the permission set in the digital signature allows the Microsoft virtual machine to present the end user with a dialog box that lists the requested permissions so that the user can decide whether to trust the applet. For more information, see Security.

The following security samples are provided.

Sample Description
Custom Permissions Location: \Samples\Security\Custom

Technologies: Security

Demonstrates:

  • Setting custom permissions to protect resources that are not described by the stock permissions in com.ms.security.permissions.
Classloader Security Location: \Samples\Security\Loader

Technologies: Security

Demonstrates:

  • Setting security attributes on class files as they are loaded by implementing a secure class loader.
COM Security Location: \Samples\Com\Security_com

Technologies: COM, security

Demonstrates:

  • Implementing Call security on a Java/COM object using the com.ms.security package.

  • Implementing a Java/COM object with a custom interface.

  • Implementing a C COM object with a custom interface.

  • Defining a custom interface in IDL.
RNI Security Location: \Samples\Security\Rni

Technologies: Security, RNI

Demonstrates:

  • Protecting access to resources from native code.
INI Files for Java Code Signing Location: \Samples\Security\sign

Technologies: Security, code signing, scripting

Demonstrates:

  • Using .ini files to sign Java code. Several sample .ini files are provided, showing high, medium, and low permissions.


WFC Samples

Windows Foundation Classes for Java (WFC) is a new application framework that accesses the Microsoft® Windows® API, enabling you to write full-featured Windows applications with the Java programming language. WFC also wraps the Dynamic HTML (DHTML) object model implemented in Microsoft® Internet Explorer 4.0, which allows you to dynamically manipulate HTML on both the client and the server. For more information, see Windows Foundation Classes for Java.

The following WFC samples are provided.

Sample Description
Class Decoder Location: \Samples\Wfc\ClassDecoder

Technologies: WFC, AFC, COM, J/Direct

Demonstrates:

  • Building a WFC application.

  • Decoding Java class files into the attributes, structures, and properties that make up the class.
Simple OCX Control Location: \Samples\Wfc\SimpleOCXControl

Technologies: WFC, ActiveX

Demonstrates:

  • Creating custom WFC controls.

  • Using WFC controls as Microsoft® ActiveX® Controls.

  • Using Design-time property editors.


Windows Samples

The Microsoft SDK for Java provides features that support the integration of Java with Windows. These samples demonstrate some of ways in which Java can be integrated with Windows, including using Windows APIs from Java, using Win32 resource files, and implementing a Microsoft® Windows NT® service in Java.

The following Windows samples are provided:

Sample Description
Cryptography Location: \Samples\Windows\Crypto

Technologies: Windows, J/Direct

Demonstrates:

  • Using the Windows Cryptography API from Java.

  • Importing Win32 API functions that use Windows error codes and mapping these to Java methods that throw com.ms.dll.Win32Exceptions.

  • Creating a custom input and output stream class.
Win32 Resource Loading Location: \Samples\Windows\Win32ResSupport

Technologies: Windows, AFC, internationalization, packaging

Demonstrates:

  • Using the supported Microsoft® Win32® resource styles and controls included with the Win32ResourceDecoder class in the com.ms.ui.resource package,

  • Using Win32 resource (.res) files to develop multilingual applications.

  • Using the resmerge tool to combine multiple Win32 resource files into a single file.
Java and Tables Location: \Samples\ASP

Technologies: ASP, Windows, J/Direct

Demonstrates:

  • Creating an HTML table based on attributes set by the caller.
NT Service Location: \Samples\Com\NTService

Technologies: COM, Windows, native code, J/Direct

Demonstrates:

  • Building a Microsoft Windows NT service using only Java, and implementing the Service Main and Service Control as Java classes.

  • Using the Windows NT Event Log with a custom message file.
TBarIcon Location: \Samples\JDirect\tbaricon

Technologies: J/Direct, Windows

Demonstrates:

  • Using mouse events and callback classes.


KB Articles Overview

This page provides links to Java-related Knowledge Base (KB) Articles that are included in the Microsoft SDK for Java. The articles are organized by their article type (HOWTO, INFO, BUG, and so on).

HOWTO KB Articles

Q163638: HOWTO: Automatically Update the Microsoft virtual machine(VM)
Q169796: HOWTO: Automate Excel from Java
Q169808: HOWTO: Disable "Warning: Applet Window"Message
Q172200: HOWTO: Using Scratch Space From Your Java Applet
Q173790: HOWTO: Using DllSurrogate Support for Java/DCOM Servers
Q177160: HOWTO: Dynamically Adding a Java Package to the CLASSPATH
Q177161: HOWTO: Getting an Applet to Submit Information
Q177177: HOWTO: Enabling Messages Printed Using System.out.printIn
Q177753: HOWTO: Creating a Modal Dialog Box from Java
Q178561: HOWTO: Use Java Serialization with VARIANT SafeArrays
Q179021: HOWTO: Redirect Output from jview or wjview.
Q179543: HOWTO: How Do I Enable Test Certificates on a Client Machine?
Q179652: HOWTO: Deploying Java in Internet Explorer 4.0 and Netscape 4.0
Q179849: HOWTO: Use Connectable Objects Including ActiveX Objects in Java
Q179850: HOWTO: Playing a .WAV file in Java
Q179851: HOWTO: Clearing a Selection in an AFC UIChoice Control
Q179852: HOWTO: Enabling Hot-Tracking in an AFC UIPushButton
Q180707: HOWTO: Reading a File on a Web Server from an Applet
Q184067: HOWTO: Using TrueType Fonts in Java
Q195175: HOWTO: Sending Text to the Visual J++ Output Window
Q222092: HOWTO: Call Native (DLL) Code From Java Using JNI
Q222117: HOWTO: Print the Contents of WFC's HTMLControl
Q232485: HOWTO: Programmatically Create Members in Site Svr w/ Java
Q232642: HOWTO: Install a DU or Java ZIP in the JPM with Rundll32
Q233200: HOWTO: Silently Install Microsoft virtual machine (VM) Without Reboot

INFO KB Articles

Q167938: INFO: How Do I run JavaSrc After Installing Classes.zip
Q177159: INFO: Support for Multiple CABs or JARs in the Same APPLET Tag
Q177165: INFO: Use New Java 1.1 Language Features with Visual J++ 1.1
Q177167: INFO: JACTIVEX /X:m- Disables Automarshaling of COM INTERFACES
Q177179: INFO: Internet Explorer Doesn't Display Signed .cab Certificate
Q177750: INFO: Visual J++ Relaxes Security Restrictions on Java Applets
Q181374: INFO: Related Component Download Articles

FAQ KB Articles

Q168942: Frequently Asked Questions About the Microsoft SDK for Java

DOC KB Articles

Q179000: DOC: Clspack's "/" Option Doesn't Work As Expected

SAMPLE KB Articles

Q161706: SAMPLE: GCDJava.exe Integrates Native Methods in a Java App
Q169802: SAMPLE: Jword8.exe Demonstrates Automating Word 8.0 from Java
Q177162: FILE: JWindow Demonstrates How to call Win32 APIs from Java
Q231294: SAMPLE: SmartGC Uses an ATL Server to Trigger Java GC

BUG KB Articles

Q177752: BUG: java.awt.TextArea Does Not Provide Shortcut Menus
Q180046: BUG: Internet Explorer Print Creates New Instance of Applet Class
Q188808: BUG: KEY_PRESSED Event Not Generated for Some Controls
Q189064: BUG: Java Applets That Use DirectAnimation Do Not Display
Q190301: BUG: java.awt.event.KeyListener.keyTyped Method Does Not Work
Q194772: BUG: SaveFileDialog.showDialog() Fails at Head of Empty if Block
Q195527: BUG: Protection Fault with Reserved System WNDCLASS Names
Q195528: BUG: WFC DataGrid Control Fails When Displaying a Binary Column
Q201484: BUG: Close Button Does Not Close Modeless AFC UIPropertyDialog
Q214780: BUG: Scrolling Over Applet in IE Causes Improper Painting
Q220592: BUG: PaintEvent.clipRect Does Not Return Clip Area Width/Height
Q221206: BUG: System.getProperty("user.home") Returns Java Home Directory

FIX KB Articles

Q177166: FIX: Jvc.exe Gives Ambiguity Error on Overloaded Methods
Q177751: FIX: java.text.DateFormat.parse() Throws a NullPointerException
Q177754: FIX: NoClassDefFoundError When a Valid Class Definition Exists
Q180057: FIX: Codebase URL Problems with <object> Tags
Q182623: FIX: PrintJob Output is Incorrect After First Page
Q184600: FIX: WebBrowser Events Not Being Received Inside Java
Q214760: FIX: TextField and TextArea Are Not Grayed Out
Q218595: FIX: Automation Object Not Being Released
Q222581: FIX: MSJAVAH Fatal Error: java.lang.UnsatisfiedLinkError
Q223351: FIX: Child Controls Not Properly Painted for setSelectedTab()
Q223355: FIX: WJView Hangs with CPU Usage at 100% Using 315x VMs
Q223358: FIX: Creating MDI Children in Parent's Constructor Causes Error
Q223362: FIX: WFC ActiveX Controls Do Not Fire Custom Events in VB
Q223363: FIX: Unhandled Exception When Hosting Java ActiveX Controls
Q223367: FIX: RegistryKey setValue() Fails Terminating Character on NT
Q233271: FIX: DateFormat Class Does Not Default to the System Time Zone
Q233359: FIX: JActiveX fails for COM Property Declared as IUnknown

PRB KB Articles

Q169799: PRB: Error J0051: Undefined package 'lang'
Q175622: PRB: SecurityExceptionEx Exception Running a Java Applet
Q177178: PRB: Unable to Sign the Cabfile When Running Signcode
Q177181: PRB: System.getProperty("user.home") Returns Incorrectly
Q178560: PRB: NoClassDefFoundError Accessing a COM Object Through Java
Q178707: PRB: Unable to Play .wav File from Applet or AudioClip
Q179001: PRB: Cannot Use JDBC in Applets Outside of Visual J++'s IDE
Q179062: PRB: COM Objects are not Being Released in Java
Q179854: PRB: No Suitable Driver Exception With JDBC Bridge and SDK
Q183805: PRB: Digitally Signed File Cannot Be Confirmed by IE4
Q189065: PRB: Catastrophic Failure Error Using an ActiveX Control
Q195160: PRB: Wjview.exe Causes Unhandled Exception on Handle Creation
Q198322: PRB: JVC: J0029 and J5020 Errors When Using Language Extensions
Q199950: PRB: Application Using JNI Gives UnsatisfiedLinkError
Q225523: PRB: JAVAH Cannot Find Classes When Executing
Q232638: PRB: Java Distribution Units Need Lots of Disk Space to Install
Q232640: PRB: Obsolete Packages Not Removed from Java Package Manager


HOWTO KB Articles Overview

The following Java-related HOWTO Knowledge Base (KB) Articles are included in the Microsoft SDK for Java.

Q163638: HOWTO: Automatically Update the Microsoft virtual machine(VM)
Q169796: HOWTO: Automate Excel from Java
Q169808: HOWTO: Disable "Warning: Applet Window"Message
Q172200: HOWTO: Using Scratch Space From Your Java Applet
Q173790: HOWTO: Using DllSurrogate Support for Java/DCOM Servers
Q177160: HOWTO: Dynamically Adding a Java Package to the CLASSPATH
Q177161: HOWTO: Getting an Applet to Submit Information
Q177177: HOWTO: Enabling Messages Printed Using System.out.printIn
Q177753: HOWTO: Creating a Modal Dialog Box from Java
Q178561: HOWTO: Use Java Serialization with VARIANT SafeArrays
Q179021: HOWTO: Redirect Output from jview or wjview.
Q179543: HOWTO: How Do I Enable Test Certificates on a Client Machine?
Q179652: HOWTO: Deploying Java in Internet Explorer 4.0 and Netscape 4.0
Q179849: HOWTO: Use Connectable Objects Including ActiveX Objects in Java
Q179850: HOWTO: Playing a .WAV file in Java
Q179851: HOWTO: Clearing a Selection in an AFC UIChoice Control
Q179852: HOWTO: Enabling Hot-Tracking in an AFC UIPushButton
Q180707: HOWTO: Reading a File on a Web Server from an Applet
Q184067: HOWTO: Using TrueType Fonts in Java
Q195175: HOWTO: Sending Text to the Visual J++ Output Window
Q222092: HOWTO: Call Native (DLL) Code From Java Using JNI
Q222117: HOWTO: Print the Contents of WFC's HTMLControl
Q232485: HOWTO: Programmatically Create Members in Site Svr w/ Java
Q232642: HOWTO: Install a DU or Java ZIP in the JPM with Rundll32
Q233200: HOWTO: Silently Install Microsoft virtual machine (VM) Without Reboot


Q163638 HOWTO Automatically Update the Microsoft VM

 Microsoft SDK for Java

Q163638 HOW TO: Automatically Update the Microsoft Virtual Machine

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® Visual J++®, versions 1.0, 1.1, 6.0

  • Microsoft® Internet Explorer (Programming) versions 3.0, 3.01, 3.02, 4.0, 4.01, 5.0

SUMMARY

If it is important that users who navigate to your Web page have the latest version of the Microsoft VM, you can automatically update their machine by including the Object tag from the MORE INFORMATION section of this article on your Web page.

MORE INFORMATION

Place the following Object tag on your page to cause Internet Explorer (IE) to download and begin installing the most recent version of the Microsoft VM:

<OBJECT CLASSID="clsid:08B0E5C0-4FCB-11CF-AAA5-00401C608500"
WIDTH=0 HEIGHT=0
CODEBASE="http://www.microsoft.com/java/download/
msjavx86.exe#Version=5,0,xxxx,0"> </OBJECT>

You should replace xxxx in the Object tag with the current version number. Note that when you paste this code from a Web page you need to remove the <> from around the hyperlink. Please see the Knowledge Base article mentioned in the REFERENCES section of this article to determine the current version number.

The Object tag above installs the retail (non-debug) version of the classes on the local machine. On a Java development machine, you would want to maintain the debug version of the classes to allow debugging system classes. These classes are included and installed with the Microsoft® SDK for Java, which is available on the following Web site:

http://www.microsoft.com/java/ This link takes you to a site on microsoft.com

It is important that the Microsoft VM is not currently in use when attempting to update. If you have previously run a Java applet in this session of Internet Explorer, please exit Internet Explorer and then navigate directly to the page that contains the Object tag. If you are using Internet Explorer 4.0x with Active Desktop enabled and you have previously run a Java applet since the time the machine was restarted, you may need to restart your machine to unload the VM.

If an automatic update is not necessary, the Microsoft SDK for Java contains a redistributable, self-extracting executable that performs a complete installation of the retail Microsoft VM, and is available on the Web site noted above.

Note The self-extracting executable version is also available for download directly on the same Web site.

If the latest Microsoft VM from the Internet Explorer 3.02 release is still required, it can be obtained with the following OBJECT tag instead of the one listed above:

<OBJECT CLASSID="clsid:08B0E5C0-4FCB-11CF-AAA5-00401C608500"
   CODEBASE="http://www.microsoft.com/java/ie30java.cab#Version=
1,0,0,1520"></OBJECT>

If an automatic update is not necessary, the Microsoft SDK for Java 1.51 contains a redistributable, self-extracting executable that performs a complete installation of the 1520 build of the retail Microsoft VM, and is available on the same Web site referenced above.

REFERENCES

For additional information on the current release of the Microsoft VM, please refer to the following Knowledge Base article:

Q163637 INFO: Availability of the current build of Microsoft VM.

For the latest Knowledge Base articles and other support information on Visual J++ and the Microsoft SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q169796 HOWTO Automate Excel from Java

 Microsoft SDK for Java

Q169796 HOWTO: Automate Excel from Java

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer (Programming) versions 3.0x, 4.0x

SUMMARY

This article illustrates how to call a COM object like Microsoft® Excel from Java. It provides code samples that show how you can make an Excel application visible and open an existing Excel file. There are two code samples. One illustrates how to invoke Excel 7.0 from Java and the other shows how to invoke Excel 8.0 from Java. You will find the classes and interfaces to be quite different in Excel 8.0.

MORE INFORMATION

Before using code samples 1 and 2, follow these steps below:

  1. Use the Java Applet Wizard to create a default applet or application.

  2. Run JAVATLB or JActiveX (utility similar to JAVATLB and supported by the SDK for Java 2.0x) on the Microsoft Excel 7.0 Object Library if you are using Excel 7.0 or the Microsoft Excel 8.0 Object Library if you are using Excel 8.0. This will create Java descriptions of the Excel Object. If you are using Excel 97, run the JActiveX tool on EXCEL8.OLB

    Note If you are using JActiveX, then you will need to build this sample with the JVC.EXE that ships with the SDK for Java 2.0 or later. You can download the SDK for Java from http://www.microsoft.com/java/ This link takes you to a site on microsoft.com.

  3. Use the import statement to import the classes of the Excel Object Library into your Java project.

  4. Insert either one of the two code snippets in your Java Project to automate Excel from Java.

Code Sample 1

   import xl5en32.*;
   import com.ms.com.*;
   public void TestExcel()
   {
      _Global gbl = (_Global) new _ExcelApplication();
      Variant param = gbl.Application();
      Application app = (Application) param.getDispatch();
      param.putInt(xl5en32.Constants.xlVisible);
      app.putVisible(param);
      Variant vtemp = new Variant();
      vtemp.noParam();

      Variant vtWorkbooks = Dispatch.get(gbl,"Workbooks");
      Workbooks wbs = (Workbooks)vtWorkbooks.getDispatch();

      Variant vtName = new Variant();
      VtName.putStringRef("C:\\book1.xls");

      Variant vtEmpty = new Variant();
      vtEmpty.noParam();
      wbs.Open(vtName,vtEmpty,vtEmpty,vtEmpty,vtEmpty,vtEmpty,vtEmpty,
               vtEmpty,vtEmpty,vtEmpty,vtEmpty,vtEmpty,vtEmpty);
   }

Code Sample 2

   import excel8.*;
   import com.ms.com.*;

   _Global globXL=null;
   _Application appXL=null;
   Workbooks books=null;
   _Workbook book = null;

   try{
      globXL = (_Global)new Global();
      appXL = (_Application)globXL.getApplication();
      appXL.putVisible(0,true);  // in Excel 97 use:
                                 // appXL.setVisible(0,true);

      books = (Workbooks)appXL.getWorkbooks();

      Variant vTemp = new Variant();
      vTemp.putString("c:\\book1.xls");

      Variant vOptional = new Variant();
      vOptional.noParam();
      book =
   (_Workbook)books.Open("c:\\book1.xls",vOptional,vOptional,vOptional,vOption
   al,vOptional,vOptional,vOptional,vOptional,vOptional,vOptional,vOptional,vO
   ptional,0);

      }
      catch(ComFailException e)
      {
         System.out.println(e.getMessage());
      }

The above code will make the Excel application visible, and it will open up an existing Excel file.

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q169808 HOWTO Disable "Warning: Applet Window" Message

 Microsoft SDK for Java

Q169808 HOWTO: Disable ": Applet Window" Message

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 1.0, 1.5, 1.51, 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

When you create a frame from within a Java applet and run this applet outside the Microsoft® Developer Studio® environment, the frame sizing is inconsistent and the following Warning message also appears in the frame's Status Bar:

Warning: Applet window

MORE INFORMATION

To disable this message so that this warning does not appear when you run the applet, you need to assert SYSTEM permissions and cabsign your applet's class files.

Steps to Reproduce Problem

  1. Create a default Java applet using the Applet Wizard.

  2. At the beginning of your project class, which extends the applet, include the following:
    Frame window
  3. In the init function include the following code, which creates and shows the frame:
    public void init()
   {
     window = new Frame("A popup window");
     window.resize(150,150);
     window.show();
   }
  4. Build the project.

  5. Execute the project's HTML file.

  6. This invokes the Browser and a Frame window with the title "A popup window" appears. The window, which is resized inconsistently, has the Warning message in its status bar.

You can disable the warning message by asserting SYSTEM permissions, and cabsigning your applet.

REFERENCES

For additional information about cabsigning and asserting permissions, please refer to the following Knowledge Base article:

Q193877 HOWTO: Making your Java Code Trusted in Internet Explorer

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q172200 HOWTO Using Scratch Space From Your Java Applet

 Microsoft SDK for Java

Q172200 HOWTO: Using Scratch Space From Your Java Applet

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

This article describes how to access scratch space on a client machine from a Java applet. Scratch space requires features of Microsoft® Internet Explorer (IE) and the Microsoft® virtual machine (Microsoft VM). These features are available in Internet Explorer 4.0 and the Microsoft VM that includes Build 2252 or later.

MORE INFORMATION

What is Scratch Space?

Scratch space is storage on the client machine that an applet can safely access without needing full access to the client file system. Scratch space is managed by the Microsoft VM a to ensure that it cannot be abused by malicious applets.

The following is true of scratch space:

  • Persists across applet invocations and download sites. Applets with the same signer downloaded from multiple sites have access to one unified scratch space. This is ideal for storing configuration information for applets that may be used in many places.

  • Is allowed in most IE Security Zones by default. The user will generally not be asked if using scratch space is okay.

  • Is available only to the signer of the applet that created it.

  • Is safe. Access is restricted to a certain portion of the client directory structure. Applets cannot use scratch space to modify files outside the allowed scratch space area.

  • Is secure. Applets must be signed or run in a fully trusted zone to use scratch space. Unsigned applets run from a fully trusted zone or from the CLASSPATH have their own scratch space.

  • Is limited to a fixed amount of disk space. Applets may request more space before the applet starts running, but the user must approve these requests.

  • Can be allowed or denied by the security system separately from regular file operations.

How to Use Scratch Space in Your Applet

Follow these steps to use scratch space in your applet:

  1. Import the Microsoft Client Storage library by placing the following line at the top of the file that will use scratch space:
    import com.ms.io.clientstorage.*;
  2. Declare a variable of type ClientStore to provide access to the storage system:
    ClientStore m_store;
  3. Retrieve the Client Store object from the system client storage manager. This action could throw an IOException:
    m_store = ClientStorageManager.getStore();
  4. Create an input or output stream. This could also throw an IOException:
    OutputStream o = m_store.openWritable(m_filename);
InputStream o = m_store.openReadable(m_filename);
  5. Access the stream as you would any other stream.

  6. Scratch space will work from your local machine for debugging, but for use on the Internet, place the compiled class into a .cab file:

    cabarc N MyApplet.cab MyApplet.class

  7. Sign the cab with privilege information that requests client storage access. For Internet Explorer 4.0 Preview 2, this means signing at either the Medium or Low level.

    SignCode ... -j JavaSign.dll -jp Medium ... MyApplet.cab

Variations:

You can also open an output file where new data is appended onto the existing file. To do so, call the following:

ClientStore.OpenWritable(String filename, boolean append) throws IOException;

If append is true, new data will be appended. Otherwise, the file will be truncated if it already exists. In either case, the file is created if it does not already exist.

If all you need to do is open a file for input or output, you can do so without having to declare a ClientStore variable. Simply call one of the following three functions directly. These three functions maintain the store internally. Each function throws an IOException in the case of an error.

InputStream ClientStorageManager.OpenReadable(String filename);
OutputStream ClientStorageManager.OpenWritable(String filename);
OutputStream ClientStorageManager.OpenWritable(String filename,
                                               boolean append);

Example

The following code fragment opens a scratch space file called "Demo.txt" on the client machine, and appends a string to the file:

   m_store = ClientStorageManager.getStore();
   OutputStream os = m_store.openWritable("demo.txt", true);
   os.write("This is stored in scratch space");

REFERENCES

More information on the clientstorage package is available in the following location:

For additional information on making your Java Code trusted in Microsoft Internet Explorer, please refer to the following Knowledge Base article:

Q193877 HOWTO: Making your Java Code Trusted in Internet Explorer

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q173790 HOWTO Using DllSurrogate Support for Java/DCOM Servers

 Microsoft SDK for Java

Q173790 HOWTO: Using DllSurrogate Support for Java/DCOM Servers

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

This article explains how to use a Java/COM object as a Distributed COM (DCOM) server using the system surrogate provided by DCOM in Microsoft® Windows® 95 and Microsoft® Windows NT® 4.0 with SP2 or SP3.

MORE INFORMATION

DCOM allows COM objects to be activated on remote machines. It allows clients to create and invoke the methods of objects on other machines. Java objects can be used remotely using DCOM. One way to remotely use a Java object is by using the system surrogate support (DllSurrogate) in DCOM for Windows 95 and Window NT 4.0 with SP2 or SP3 along with the Microsoft® virtual machine (Microsoft VM). JAVAREG is a tool that supports remote access to a COM class implemented in Java. It is a command-line tool that is used for registering Java classes as COM components in the registry. In fact many of JAVAREG's options are intended for use only with DCOM.

The JAVAREG (version 1.0) that shipped with Microsoft® Visual J++®, versions 1.0 and 1.1 implemented a surrogate process itself, but it had some bugs making it difficult to set up Java DCOM servers and clients. There is also a Knowledge Base article listed in the REFERENCES Section below that addresses this problem.

The DCOM support now in Windows 95 and Windows NT 4.0 with SP2 and SP3 supports a surrogate as part of the system, so the surrogate support with JAVAREG 1.0 has been dropped.

JAVAREG 2.0 and newer is a new tool that ships with SDK for Java 2.0 and newer. This tool fixes the bugs associated with JAVAREG 1.0 and supports remote access to a Java COM object using the system provided surrogate process. The following steps explain how to set up a Java/COM object as a DCOM server using the new JavaReg2.0 tool.

Server Side Steps

The following sample makes use of the AutoIDispatch mechanism where you do not need to create an IDL file for your Java/COM object. This method does not require tools like JAVATLB or JActiveX that ship with the SDK for Java 2.0x. For more information on the use of the AutoIDispatch mechanism, see the REFERENCES section below.

  1. Using Visual J++ 1.1, create the following Java class:
       public class TestDCOM
   {
      public String getString()
      {
         String str = "SSSS";
         return str;
      }
   }
  2. Build the class and move the .class file to the <windir>/Java/trustlib directory where <windir> = windows directory in Windows 95/98 and winnt directory in Windows NT.

  3. Run JAVAREG (version 2.0 and later):

    javareg /register /class:TestDCOM /progid:TestDCOM.1 /surrogate

    This step generates a class ID (CLSID) for your class and automatically adds the DllSurrogate (which is the system surrogate) to the APPID portion of your Java Class in the registry. So if you run Regedit.exe, you can find this key under HKEY_CLASSES_ROOT\APPID\{yourclsid}.

    If you want to use a CLSID that you have already allocated, you can use the /clsid: flag to specify it and JavaReg2.0 and later will use the one you specify. In either case, you need to note your CLSID so that you can use it on your client machine.

  4. Once you have registered the COM object successfully, run OLEVIEW, which is a tool that lets you view all the registered COM objects interfaces and Type_Libraries. Select View.ExpertMode and also set Object.CoCreateInstance flags to CLSCTX_LOCAL_SERVER and CLSCTX_REMOTE_SERVER. (Make sure that CLSCTX_INPROC_SERVER is not selected). Expand the Java classes node. Then expand the Java Class:TestDCOM node. This is the same as right-clicking and selecting CreateInstance on the class. If it expands showing all the interfaces, then your COM object has been created in a separate process on your machine. Getting your class to activate out-of-process on a single machine is the first step towards getting it to activate on another machine, so it is essential that you test this scenario first.

  5. Configure your applications to run your Java COM object in a remote machine and provide both Launch and Access Permissions to the remote machine user. You can do this either using OLEVIEW or DCOMCNFG. DCOMCNFG is a utility included with DCOM for Windows 95 and Windows NT 4.0 with SP2 or SP3.

Client Side Steps

  1. Run JAVAREG 2.0 or later:

    javareg /register /class:TestDCOM /progid:TestDCOM.1

    /clsid:{yourclsid}

    /remote:servername

    Where /remote:servername is a new option that lets you specify the remote server machine name.

  2. Use OLEVIEW to test that your class activates remotely. Run OLEVIEW on the client, find the Java Classes:TestDCOM class under the Java Classes component category, and double-click it. After a brief pause you will see the list of interfaces your class supports displayed by OLEVIEW. If you use the Task Manager on the server machine to look at the running processes, you will see Dllhost.exe running. This is the surrogate process under which your class is running on the server.

  3. Now you can create a Microsoft® Visual Basic® application (or any other client such as Microsoft® Visual C++® or Microsoft® VBScript) to create an instance of TestDCOM.1:
       Dim X As Object
   Dim str As String
   Set X = CreateObject("TestDCOM.1")
   str = X.getString()
   MsgBox str
  4. Now you should be able to run this Vb.exe file from your client machine, which will remotely activate the TestDCOM object on the server machine.

Note If the client application specifies both a CLSID (instead of relying on theProgID) and a remote server name to CoCreateInstanceEx (or equivalent), then no client side registration steps are necessary.

Other Tips

Whenever you attempt to get a DCOM solution to work, it is useful to know when processes are starting and stopping on a machine. One very effective way to do this is to enable the Process Start and Process Stop sounds in the Sounds Control Panel applet. With these sounds enabled (and set to two distinguishable noises), you will be able to tell whenever a process starts or stops on your machine. This is useful in tracking down problems where DCOM's launch security has allowed a client to launch the server process, but access security is disallowing access (you'll hear the process start sound, but the client will get E_ACCESSDENIED from the activation request). Of course, this requires that your server machine have a sound card installed with appropriate drivers.

Use OLEVIEW to test that your components are installed and registered correctly. Always test new components first in-process (CLSCTX_INPROC_SERVER checked in OLEVIEW), then cross-process-same-machine (CSLCTX_LOCAL_SERVER), then remotely (CLSCTX_REMOTE_SERVER with no LocalServer32 key). By doing this you reduce the number of variables (things that can go wrong) as you do your testing.

REFERENCES

Download the new SDK for Java from http://www.microsoft.com/java/ This link takes you to a site on microsoft.com.

For additional information on downloading DCOM for Windows 95, please see:

http://msdn.microsoft.com/library/default.htm This link takes you to a site on microsoft.com.

For additional information on the issues involved with JAVAREG 1.0's surrogate support please refer to the following Microsoft Knowledge Base article:

Q162164 BUG: Using Java Servers and DCOM

For additional information on the usage of AutoIDispatch mechanism, please refer to the following Knowledge Base article:

Q172202 INFO: Implementing Java Automation Objects Using AutoIDispatch

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java This link takes you to a site on microsoft.com

Additional query words:

Java DCOM surrogate


Q177160 HOWTO Dynamically Adding a Java Package to the CLASSPATH

 Microsoft SDK for Java

Q177160 HOWTO: Dynamically Adding a Java Package to the CLASSPATH

The information in this article applies to:

  • Microsoft® SDK for Java, versions 1.0, 1.5, 1.51, 2.0x, 3.0, 3.1, 3.2

SUMMARY

This article explains how to have the Microsoft® virtual machine (Microsoft VM) dynamically add a Java package (ZIP file) to the CLASSPATH before executing applets on a Web page. This method uses an install cab that is compatible with both Microsoft® Internet Explorer 3.x and Internet Explorer 4.0x. You will need the SDK for Java 2.0 or later available at http://www.microsoft.com/java/ This link takes you to a site on microsoft.com.

MORE INFORMATION

The typical method in Internet Explorer 3.x for downloading, installing, and executing a Java applet is to use an install cab. This method is also compatible with Internet Explorer 4.0x. When installing a Java package in ZIP format, there are certain registry entries that need to be made to make the Microsoft VM aware that the CLASSPATH needs to be altered. Fortunately, there is a template provided for you with the SDK for Java that does most of the work for you.

The purpose of using this method for installing a Java package is not necessarily to make it trusted (run outside of the Java "sandbox"). The Microsoft VM will not automatically see the class files included in a ZIP file if the ZIP file is not explicitly included in the CLASSPATH. For example, if the Java package Test1.zip is in a directory in your CLASSPATH (like %Windir%\Java\Classes), but not explicitly listed in the CLASSPATH, it will not be found by the Microsoft VM when the package is referenced. An install cab will dynamically instruct the VM to add the given ZIP file to its CLASSPATH – even if the ZIP is already installed on the machine.

An install cab contains two files. One file is called the inner cab, which contains the files to be installed on the user's machine (in this case, one uncompressed zip file which is the Java package). The other file, Master.inf, controls the install of the inner cab. The Master.inf file is included with the SDK for Java 2.0 and later distribution (available from http://www.microsoft.com/java This link takes you to a site on microsoft.com). By modifying the default syntax of Master.inf, the Microsoft VM can be instructed to add custom path information to the CLASSPATH during run time.

The <OBJECT> tag is used to instruct the Web browser to download and install the contents of the inner cab. In your HTML document, add an entry like this:

<OBJECT CLASSID="CLSID:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    CODEBASE="install.cab#Version=1,0,0,1">

The Microsoft VM looks at two registry keys when deciding whether to run the Java applet in trusted mode or not. Trusted Java code will execute outside of the Java "sandbox." Code that is trusted is installed in %Windir%\Java\TrustLib. Code that does not require the relaxed restrictions is installed in %Windir%\Java\Lib (which is the default in Master.inf).

The Microsoft VM will trust the installed ZIP file if it is installed in %Windir%\Java\TrustLib and the registry key HKEY_CLASSES_ROOT\CLSID\%ClassId%\InProcServer32\TrustLib is equal to %Windir%\Java\TrustLib.

For Java code that does not need to be trusted, it should be installed in %Windir%\Java\Lib, and the registry key HKEY_CLASSES_ROOT\CLSID\%ClassId%\InProcServer32\Lib should be set to %Windir%\Java\Lib.

Please follow the instructions in Master.inf to make the appropriate changes for your install. Make sure to put the name of your ZIP file in the following section as stated in 1 below:

; Under most circumstances, you should leave the next two keys alone.
; Only change them if
; 1) You have not expanded the classes into their subdirectories on
; the user's machine, but have instead stored them in an uncompressed
; .ZIP file; in that case, change the appropriate value
; to "%49000%\<ZipFileName>".
;
; 2) You have decided to install the files onto another, hard-coded
; directory of your choice. This is not recommended, for you will
; clutter up the user's directories and have to make other changes.
; If you do so, though, change the appropriate value to the absolute
; pathname to that directory, and change it in the run= line above.
;
; If you use one of these, you will use exactly one.
HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InProcServer32","Lib",,"%49000%"
;HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InProcServer32",
  "TrustLib",,"%49000
%"

The above key will dynamically add the "%49000%" (or "%49000%\<ZipFileName>") directory to the Microsoft VM’s CLASSPATH when the <OBJECT> tag is read. The "%49000%" variable is defined as the contents of the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Java VM\LibsDirectory that, by default, is defined as %Windir%\Java\Lib.

Note If you are installing the ZIP file in the %Windir%\Java\TrustLib directory, make sure to update the following section as stated in the instructions:

[PackageDestination49000]
; This value should only change if you have decided to place your
; classes in the TrustedCLASSPATH. In that case, you
; will change "LibsDirectory" to "TrustedLibsDirectory".

"HKLM","Software\Microsoft\Java VM","LibsDirectory","",""

By default, the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Java VM\LibsDirectory is equal to %Windir%\java\lib, and

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Java VM\TrustedLibsDirectory is equal to

%Windir%\java\trustlib

Even though the <OBJECT> tag points to an install cab, the install cab is only installed once, and there after runs from its installed directory (either %Windir%\Java\Lib or %Windir%\Java\TrustLib). Since the Master.inf file stores either "TrustLib" or "Lib" in the InProcServer32 node in the registry, the Microsoft VM will be able to add the appropriate entries to the CLASSPATH to run the Java applet.

In SDK for Java 2.0 and later, the package manager DUBUILD can be used, but to be Internet Explorer 3.x compatible, the above method should be used.

REFERENCES

The Master.inf file included SDK for Java contains several comments explaining how to create an install cab. The SDK for Java documentation also includes information on how to use CABARC, which is used to create .cab files.

For information on the Frequently Asked Questions for .cab files, see the following article in the Microsoft Knowledge Base:

Q168941 INFO: Frequently Asked Questions for .cab Files

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

install .cab CLASSPATH


Q177161 HOWTO Getting an Applet to Submit Information

 Microsoft SDK for Java

Q177161 HOWTO: Getting an Applet to Submit Information

The information in this article applies to:

  • Microsoft® SDK for Java, versions 1.51, 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

When I have an applet in a <FORM> it doesn't submit any information to the server. How can I get the applet to submit its information?

MORE INFORMATION

The applet doesn't submit any information because the information a user would want to submit is specific to the applet. For example, an applet that shows images may want to submit the currently displayed image number, while an applet that displays a clock may want to submit the GMT time. It is up to the programmer to write the methods to submit the applet. The five steps below show one way you might implement submitting an applet.

  1. Create an applet with a public function that returns the information you want to submit. (For the first example above, you would return the image number.)
       public int getCurrentImage() {
      return m_nCurrImage;
   }
  2. Create a Web page with an applet inside your form.

  3. Create a hidden field in the <FORM>, where your applet will submit its data.

  4. Write a script function, like processApplet in the example below, to populate the hidden field by calling public functions of your applet.

  5. Set your submit button's onClick function to call the script function you wrote in step 4. Here is the finished product:
       <form action="/scripts/info.dll" method=GET name="myForm" >
   <applet code=AppletInForm.class id=myapplet width=320 height=240 >
   </applet>
   <input type=hidden name="appletImage">
   <script language=JScript>
      function processApplet()
      {
         parent.myForm.appletImage.value=document.myForm.myapplet.
         getCurrentImage();
         alert("Sending form: image="+parent.myForm.appletImage.value+"
         user="+parent.myForm.Username.value);
      }
      </script>
      <br>
      Username:<input type=text name="Username"><br>
      <input type=submit value="Please send me the above picture."
       language="JScript" onClick="processApplet();">
      </form>

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

submit applet information


Q177177 HOWTO Enabling Messages Printed Using System.out.printIn; logging

 Microsoft SDK for Java

Q177177 HOWTO: Enabling Messages Printed Using System.out.printIn

The information in this article applies to:

  • Microsoft® SDK for Java, versions 1.51, 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer (Programming), versions 3.01, 3.02, 4.0, 4.01, 4.01 SP1

SUMMARY

When running Java applets, it may be useful for you to see messages that are printed using System.out.println. In Internet Explorer 3.x and 4.x, output through the System.out stream is stored in a file on the client hard-drive. In Internet Explorer 4.01 you can also view this output in the Java console.

MORE INFORMATION

You need to enable Java logging in Internet Explorer. A Javalog.txt file will be created in your %Windir%\java directory. This log file will contain all information that is sent to the System.out stream. To enable Java logging select Options (or Internet Options if using Internet Explorer 4.x) from the View menu. Then click the Advanced tab and Enable Java logging (or Java logging enabled if using IE4.x).

To enable the Java console in Internet Explorer 4.01 select Internet Options from the View menu. Then click the Advanced tab and check Java Console Enabled (requires Restart). Restart your computer. The next time you start Internet Explorer 4.01, you can view the Java console by selecting Java Console from the View menu.

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q177753 HOWTO Creating a Modal Dialog Box from Java

 Microsoft SDK for Java

Q177753 HOWTO: Creating a Modal Dialog Box from Java

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer (Programming) versions 4.0, 4.01

SUMMARY

This article describes how to create a modal dialog box with respect to the Internet Explorer browser in Java. The class java.awt.Dialog allows you to create a modal dialog box, but this dialog box is not modal with respect to the browser. To create a modal dialog box with respect to the browser, you can use Internet Explorer 4.0's showModalDialog method (part of the Window object). Due to a limitation in calling showModalDialog directly from Java, a technique is used to call the showModalDialog method on behalf of the Microsoft® virtual machine (Microsoft VM).

MORE INFORMATION

The following HTML and Java applet demonstrate how to create a modal dialog box from Java under Internet Explorer 4.0. This sample demonstrates invoking the showModalDialog method from Java using the setTimeout method and interaction between Java and Internet Explorer 4.0 using AutoIDispatch.

Please see the following Java code, which is used in HTML later. This applet has a method called setMyObject, which takes an object as a parameter. When the user clicks the "click me" button, the doModal method is invoked on the object passed in from the setMyObject method. The doModal method takes a string as a parameter, which is the content of the text field.

   import java.applet.Applet;
   import java.awt.*;
   import java.awt.event.*;
   import com.ms.com.Dispatch;
   public class DialogTest extends Applet implements ActionListener
   {
      Object MyObject;
      TextField tf= new TextField("testing.....",30);
      public void init()
      {
         Button b = new Button("click me");
         add(b);
         b.addActionListener(this);
         add(tf);
      }
      public void setMyObject(Object MyObject) { MyObject = MyObject; }
      public void actionPerformed(ActionEvent e)
      {
         Dispatch.call(MyObject, "doModal", tf.getText());
      }
   }

The following HTML creates a Java applet called DialogTest and, upon initialization, passes in a reference to "this" via the setMyObject method in the applet. The applet stores a reference to this object in order to call the method doModal, which in turn sets a timeout that is a workaround for calling showModalDialog directly. The argument passed into doModal is passed down to showModalDialog as the dialog argument into the modal dialog box.

   <HTML>
   <HEAD>
   <TITLE>Dialog Test</TITLE>
   </HEAD>
   <BODY>
   <APPLET
      CODE=DialogTest
      ID=DialogTest
      WIDTH=300
      HEIGHT=70 >
   </APPLET>
   <SCRIPT LANGUAGE="JavaScript">
   <!--
   function doModal(tst)
   {
      setTimeout("doModal2('DialogTestDialog.html', '"+tst+"')",100);
   }
   function doModal2(url, dialogarg)
   {
      var strFeatures = "dialogWidth:385px;dialogHeight:100px;" +
         "help:no;maximize:no;minimize:no;scrollbars:no";
      var cRetValue=showModalDialog(url,dialogarg,strFeatures);
      if (cRetValue == null)
      {
         alert('You clicked the cancel or close button');
      }
      else
      {
         alert(cRetValue);
      }
   }
   function init()
   {
      DialogTest.setMyObject(this);
   }
   window.onload=init;
   -->
   </SCRIPT>
   </BODY>
   </HTML>

The following HTML is the DialogTestDialog.html referenced in the HTML above. This HTML effectively becomes the modal dialog box. It takes the window.dialogArguments variable (which originated from the Java applet) and puts this string into a text field. When the user clicks the "click me" button on this page, the window.returnValue is set to the value of this text field. The above HTML then displays the return value using the JavaScript alert method.

   <HTML>
   <HEAD>
   <TITLE>DialogTestDialog</TITLE>
   <SCRIPT LANGUAGE="JavaScript">
   <!--
   function doOK()
   {
      window.returnValue=document.all.inp1.value;
      window.close()
   }
   function init()
   {
      document.all.inp1.value=window.dialogArguments;
   }
   window.onload=init;
   -->
   </SCRIPT>
   </HEAD>
   <BODY>
   <INPUT TYPE=BUTTON NAME=b1 VALUE="click me" onclick="doOK()">
   <INPUT NAME=inp1 SIZE=30>
   </BODY>
   </HTML>

REFERENCES

See the Internet Client SDK documentation for more information on the showModalDialog method in Internet Explorer 4.0.

Please see following article in the Microsoft Knowledge Base for more information on interactivity between Java and scripting using COM:

Q172202 INFO: Implementing Java Automation Objects using AutoIDispatch

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

modal dialog internet explorer


Q178561 HOWTO Use Java Serialization with VARIANT SafeArrays

 Microsoft SDK for Java

Q178561 HOWTO: Use Java Serialization with VARIANT SafeArrays

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® virtual machine (Microsoft VM)

SUMMARY

VARIANT SafeArrays are used in COM to hold Arrays of data (bytes, ints, etc). It may be useful for a Java developer to use a SafeArray to persist a Java object. In order to do so, we need a way to convert the data from ObjectOutputStream to a SafeArray and back again.

MORE INFORMATION

Serialization in Java allows you to transmit or store a Java object in a stream. If you would like to use Serialization with COM objects, you will need to convert the Java stream to some form that COM understands. The most common form of parameter in COM is a VARIANT.

Because a VARIANT has limited types that can be placed inside of it, a serialized Java object's stream must be converted to a SafeArray. A SafeArray can hold a collection of bytes which is what a serialized Java object consists of. Java's representation of a SafeArray is com.ms.com.SafeArray. We need to create a simple class to convert the OutputStream to the SafeArray and another class to convert the SafeArray back to an InputStream.

Note In order to compile the following code, you MUST use the Microsoft VM version 2339 or newer included in Microsoft SDK for Java 2.0 and later. The following code depends on new features of the SafeArray class included in the new Microsoft VM.

The following class called SafeArrayOutputStream converts data coming from an OutputStream into a SafeArray:

   import java.io.*;
   import java.util.*;
   import com.ms.com.*;
   // SafeArrayOutputStream
   public class SafeArrayOutputStream extends ByteArrayOutputStream
   {
      public SafeArray getSafeArray()
      {
         // Allocate an array the size of the vector
         byte[] byteArray = toByteArray();
         // Create the safearray
         SafeArray array = new SafeArray(Variant.VariantByte,
            byteArray.length);
         // Fill in safearray
         array.setBytes(0, byteArray.length, byteArray, 0);
         return array;
     }
   }

The following class called SafeArrayInputStream converts data from a SafeArray into an InputStream:

   import java.io.*;
   import com.ms.com.*;
   // SafeArrayInputStream
   public class SafeArrayInputStream extends ByteArrayInputStream
   {
      public SafeArrayInputStream(SafeArray array)
      {
         super(array.toByteArray());
      }
   }

Notice that both of these classes extend classes that are in the package Java.io. The ByteArrayOutputStream and the ByteArrayInputStream already provide most of the functionality necessary for the conversion.

If you have the following Automation COM interface:

   interface IShortStorage
   {
      public void setAppData(Variant v);
      public Variant getAppData();
   }

You would be able to use them in the following manner:

   // This is our variable that contains the COM interface
   IShortStorage istor = (IShortStorage) storageCOMObject;
   // This is our Object that we want to store
   Color color = new Color(255,0,128);
   // Create our SafeArrayOutputStream
   SafeArrayOutputStream safeOutStream = new SafeArrayOutputStream();
// Declare a ObjectOutputStream for Serialization
   ObjectOutputStream objOutStream = null;
   try
   {
      // Create the ObjectOutputStream passing in our SafeArrayOutputStream
      objOutStream = new ObjectOutputStream(safeOutStream);
      // Write our color object to the stream
      objOutStream.writeObject(color);
      // Flush the stream
      objOutStream.flush();
   }
   catch(Exception e)
   {
      // ObjectOutputStream threw an exception
   }
   // Close the stream
   safeOutStream.close();
   // Get the SafeArray from our SafeArrayOutputStream
   SafeArray bytes = safeOutStream.getSafeArray();
   // Create a new Variant to hold the SafeArray
   Variant data = new Variant();
   // Put the SafeArray inside the Variant
   data.putSafeArray ( bytes );
   // Store the Variant inside the Automation Object
   istor.setAppData(data);

When you are ready to retrieve the Object, use this code to deserialize your Object from the SafeArrayInputStream:

// Get the Variant back from the Automation Object
   Variant data = istor.getAppData();
// Get the SafeArray out of the Variant
   SafeArray bytes = body.toSafeArray();
// Create a new SafeArrayInputStream based on the SafeArray
   SafeArrayInputStream safeInStream = new SafeArrayInputStream(bytes);
// Create a ObjectInputStream based on the SafeArrayInputStream
   ObjectInputStream objInStream = new ObjectInputStream(safeInStream);
// Get the serialized object out of the ObjectInputStream
   Object obj = objInStream.readObject();
// Check to see if the object is a color
   if(obj instanceof Color)
   {
      Color col = (Color)obj;
      // Use the color
   }

REFERENCES

SafeArrays and Variants are described in the Microsoft SDK for Java documentation which is available from the following Web site:

http://www.microsoft.com/java/sdk/ This link takes you to a site on microsoft.com

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

SafeArray serialization


Q179021 HOWTO Redirect Output from jview or wjview

 Microsoft SDK for Java

Q179021 HOWTO: Redirect Output from jview or wjview.

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 1.0, 1.5, 1.51, 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

This article describes two methods that can redirect output from jview or wjview.

MORE INFORMATION

Method 1

Unfortunately, there is not an option or registry setting for jview or wjview that enables Java logging. However, you can redirect the output when invoking an application like the following example:

jview main > javalog.txt

This works for both jview and wjview.

Method 2

Or you can programmatically direct the output to a file or pipe by reassigning System.out. The following steps, which work for jview or wjview and Internet Explorer, show how this can be done:

  1. Open a new Java project and call it "test."

  2. Open a new Java source file and call it "sample."

  3. Copy and paste the following code in the file you created in step 2.
         //
      // sample.java
      //
      import java.io.*;
      public class sample {
         public static void main(String[] args)
         {
            if ("true".equalsIgnoreCase(System.getProperty
                  ("com.ms.applet.enable.logging")))
            {
               try
               {
                  String logdir = System.getProperty("java.home");
                  PrintStream ps = new PrintStream(new
BufferedOutputStream
                        (new FileOutputStream(new File
                        (logdir,"javalog.txt"))), true);
           // Use the following two lines for SDK 1.5 and 1.5.1:
                  // System.out = ps;   // comment line if using SDK 2.0
                  // System.err = ps;   // comment line if using SDK 2.0
           // Otherwise, use the following two lines for SDK 2.0 and
greater:
                 System.setOut(ps);     // uncomment line if using SDK 2.0
                  System.setErr(ps);    // uncomment line if using SDK 2.0
               }
               catch (Exception e)
               {
               }
               System.out.println("sample.java executed successfully!");
            }
         }
      }
  4. Build and execute the above project.

    Javalog.txt should contain the line: "sample.java executed successfully!".

Note Javalog.txt is normally found in your Windows directory at %Windir%\Java\Javalog.txt.

The ability to alter the value of System.out and other system streams may be removed or changed in the future.

REFERENCES

For additional information, please see the following articles in the Microsoft Knowledge Base:

Q177177 HOWTO: Enabling Messages Printed Using System.out.println

Q173469 How to Enable the Javalog.txt File

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q179543 HOWTO How Do I Enable Test Certificates on a Client Machine?

 Microsoft SDK for Java

Q179543 HOWTO: How Do I Enable Test Certificates on a Client Machine?

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Visual J++®, versions 1.0, 1.1

SUMMARY

When creating a test certificate using makecert, cert2spc, and signcode to sign a .cab file, it is not always obvious why the client machine running Microsoft® Internet Explorer 3.0 or Internet Explorer 4.0 ignores the signed .cab file. The answer is to use setreg 1 true with SDK for Java 2.0 or later. This will force the client machine to treat the root authority as trusted and therefore allow signed cabfiles, which are signed with test certificates.

MORE INFORMATION

Setreg.exe is a utility program provided with the SDK for Java 2.0 and later. You will find it in the %SDKDIR%\Bin\Packsign or %SDKDIR%\Bin folder. The root authority (test root) may be set back to untrusted by running setreg 1 false.

Please see the SDK for Java 2.0 and later documentation for more information on using makecert, cert2spc and signcode. Setreg.exe replaces the Wvtston.reg utility included with earlier versions of the digital signing tools.

When Internet Explorer encounters a .cab file that is signed with a test certificate on a machine that does not trust the root authority, it may react in several different ways. When downloading an ActiveX Component, Internet Explorer 3.0 displays an error message saying "The component appears to have been digitally signed by its publisher, but the signature cannot be verified." When downloading an applet, Internet Explorer 3.0 presents no dialog box or message; it simply runs the applet in untrusted mode, and the applet generally fails with a security exception.

When Internet Explorer 4.0 encounters any .cab file that is signed with a test certificate on a machine that does not trust the root authority, it displays a warning message, saying that "The authenticity of this content cannot be verified," and that "the test root has not been enabled as a trusted root."

REFERENCES

For more information on the setreg tool, or other tools mentioned in this article, please browse the SDK for Java documentation at the following Web site:

http://www.microsoft.com/java/sdk/ This link takes you to a site on microsoft.com

For additional information, please see the following article in the Microsoft Knowledge Base:

Q177179 INFO: IE Does Not Display Signed .cab File Certificate

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

test certificate


Q179652 HOWTO Deploying Java in Internet Explorer 4.0 and Netscape 4.0

 Microsoft SDK for Java

Q179652 HOWTO: Deploying Java in Internet Explorer 4.0 and Netscape 4.0

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer (Programming) version 4.01 SP1

SUMMARY

The Need to Sign Java Code

Java code can typically be grouped into two categories: applications and applets. Java applications are installed on the user's machine and have complete access to all system resources. Java applets, however, were restricted to the "sandbox." This meant that they were restricted from doing certain tasks, like reading or writing to the hard disk. These restrictions were necessary to provide a secure environment for applets to run in but they also severely restricted their functionality.

MORE INFORMATION

Early Solutions

The first attempt to solve this problem was in Microsoft Internet Explorer 3.0. Using a technology called Authenticode (see below for a description): developers could sign files that contained their Java applets. When the .cab file was downloaded from a Web page, a certificate dialog box was presented to the user. If the user trusted the publisher of the code, the Java code was treated as fully trusted and would have complete access to system resources. If the user did not trust the publisher of the code, the applets were denied access. Sun, in its JDK 1.1 release also had a similar, binary model. Netscape Navigator 3.0 did not have a comparable security model.

Current Models

In the 4.0x releases of Internet Explorer and Netscape Communicator, the binary model was extended to a more fine-grained access of system resources. (At the time of release of Internet Explorer 4.0, Sun had not yet released their JDK 1.2 security model, which also promised fine-grained access functionality). Internet Explorer 4.0x additionally includes a feature called the Package Manager that allows developers to install applets locally and other features such as versioning, namespace management, and so forth. For end users this resulted in benefits such as reduced download time since the applet did not have to be downloaded every time a Web page was hit.

Differences Between the Microsoft and Netscape Models

There are five significant differences between the Java security models in Internet Explorer 4.0x and Netscape Communicator 4.0. These differences and workarounds, if applicable, are described below.

Packaging

In order to step out of the Java "sandbox," applets need to be packaged in .cab files for use with Internet Explorer 4.0x and into JAR files for use with Netscape Communicator. In order to create .cab files, you need to use the Cabarc or Dubuild utilities. Details about the Cabarc utility is available in the Microsoft SDK for Java documentation (http://www.microsoft.com/java/sdk/ This link takes you to a site on microsoft.com) in the tools section. To create a JAR file for Netscape Communicator, you need to use the JAR packager utility from a Web page or the Zigbert utility that can be run from the command line.

Installing Java Applets and Applications

Java applets and applications may be installed using the Package Manager that is available as a new feature in Internet Explorer 4.0x. Some of the advantages of using the Package Manager are versioning control, application namespace management, improved security, ability to uninstall, and ease of use. In order to use the Package Manager in Internet Explorer 4.0x, you need to use the dubuild utility to create a Distribution Unit. There is no equivalent package management facility in Netscape Communicator 4.0. Details about the Package Management feature is available in the SDK for Java documentation

http://www.microsoft.com/java/sdk/ This link takes you to a site on microsoft.com

Signing Code

Signing Java code uses a technology called Authenticode in Internet Explorer and Object Signing in Communicator. Authenticode technology was introduced as a feature in Internet Explorer 3.0 and allowed signed CABS to step out of the sandbox. In Internet Explorer 4.0x this feature was extended to allow Java code fine-grained access to system resources. Both CABs and JARs are signed using industry standard X. 509 v3 certificates and PKCS #7 signatures. Currently, Verisign is the only Certificate Authority (CA) that issues Microsoft Authenticode and Netscape Object Signing certificates. However, these certificates are not interchangeable. In addition, Communicator does not recognize .cab files or the signature that is embedded in a .cab file. Internet Explorer 4.0x can download jar files but does not recognize the signature in a JAR file. In order to sign code, developers should use the Signcode utility. The Signcode utility allows developers to sign their code with the specific permissions that are being requested. Details are available at http://www.microsoft.com/java/security/secfaq.htm This link takes you to a site on microsoft.com. The signcode utility is available in the SDK for Java 2.0 and later (http://www.microsoft.com/java/sdk/ This link takes you to a site on microsoft.com).

Security Model

The security model in version 4.0x of Internet Explorer and Communicator allows Java applets to selectively step out of the sandbox. Both use a trust model that explicitly requires user permission before the code is allowed access to system resources. However, there are a few differences between the two models. The Microsoft model is a static model that requires the user to trust the code up front. In contrast, the Netscape model is a dynamic model where the code requests user input during its execution. This results in the user being presented with multiple dialog boxes at unpredictable times. The Microsoft model allows parameterization of the permissions giving developers and users fine-grained access to resources. For example, in the Microsoft model, a publisher can request access to a particular file on the users hard disk; this level of detail is not available in the Netscape model. The Microsoft model is often referred to in documentation as "Trust-Based Security Model for Java" while the Netscape model is often referred to as "Capabilities Based Model." Details about the Microsoft model and comparison with other models are available at http://www.microsoft.com/java/security/ This link takes you to a site on microsoft.com.

As described above, the Netscape model requires developers to write to a capabilities API. This results in developers having to maintain two separate code bases for deploying code for both browsers. One way to avoid having to maintain separate code bases is to make the security class files visible on the class path while compiling your Java code. You can then catch the ClassNotFound exceptions and take appropriate action.

The Microsoft model does not require developers to write to an API since the permissions are encoded in the signature. However, an API is provided for classes that need to assert or deny permissions. For example, if you are developing a library, you may want to explicitly assert your permission to access system resources. Details on the assert permission interface are provided in the documentation for the SDK for Java 2.0 and later (http://www.microsoft.com/java/sdk/ This link takes you to a site on microsoft.com) and the following Knowledge Base article:

Q175622 PRB: SecurityExceptionEx Exception Running a Java Applet

HTML Tags

To download a .cab file with Java code, you need to use the APPLET tag with the Cabbase parameter. This works with Internet Explorer version 3.0 and 4.0x.

   <APPLET
      code=MyClass.class
      width=100
      height=100>
   <PARAM NAME=cabbase VALUE=MyApplet.cab>
   <PARAM NAME=... VALUE=...>
   </APPLET>

If you wish to use the Package Manager, you need to use the APPLET tag with the Useslibrary parameter. The Package Manager feature is available in Internet Explorer 4.0 and later versions.

   <APPLET
      code=com.mycorp.AppletMain
      width=100
      height=100>
   <PARAM NAME=useslibrary VALUE="MyApplet">
   <PARAM NAME=useslibrarycodebase VALUE="MyApplet.cab">
   <PARAM NAME=useslibraryversion VALUE="1,1,2,3">
   <PARAM NAME=... VALUE=...>
   </APPLET>

If you wish to deploy JAR files with Netscape Communicator 4.0, you need to use APPLET tag with the archive parameter:

   <APPLET
      code="MyApplet"
      width=200
      height=200>
      archive="test.jar">
   <PARAM NAME="ApplicationClass" VALUE="mycompany.MyApplet">
   <PARAM NAME=... VALUE=...>
   </APPLET>

If you wish to fully optimize performance on Internet Explorer 3.x, Internet Explorer 4.x and Netscape Communicator, you can combine the tags as in the example below.

Internet Explorer 4.x looks for the Useslibrary parameter first and will then look for the Cabbase parameter. Internet Explorer 3.x will not see the Useslibrary parameter, but will see the Cabbase parameter. The important feature to note regarding Useslibrary is that it will install the package on the user's machine permanently until they are removed by the user, whereas the Cabbase parameter will simply download and use the .cab every time the user hits the page. Also note, the Internet Explorer 3.x method using Cabbase will also work on Internet Explorer 4.x and is sometimes the best solution. Communicator does not recognize the Cabbase or Useslibrary parameter and will ignore it. The author of the page will need to decide on the most appropriate combination of tags/parameters.

Note If you use the Useslibrary and Cabbase parameters together, both .cab referenced by these parameters will be searched before individual class files that may exist on the Web server. This may cause a performance loss and should be noted if some Java classes needed by the applet exist only outside of the cabs on the Web server:

   <APPLET
      code="MyApplet"
      width=200
      height=200>
      archive="test.jar">
   <PARAM name="ApplicationClass" value="mycompany.MyApplet">
   <PARAM NAME=cabbase VALUE=MyApplet.cab>
   <PARAM NAME=useslibrary VALUE="MyApplet">
   <PARAM NAME=useslibrarycodebase VALUE="MyApplet.cab">
   <PARAM NAME=useslibraryversion VALUE="1,1,2,3">
   <PARAM NAME=... VALUE=...>
   </APPLET>

For more information on how to include an Archive attribute and Cabinets parameter in the same <APPLET> tag, please see the following article in the Microsoft Knowledge Base:

Q177159 INFO: Support for Multiple CABs or JARs in the Same APPLET Tag

Note If you have a complex set of tags, you may want to sniff the user agent string to determine the client being used. For example since the package management functionality is not supported in Internet Explorer 3, you may want to determine the version number of the browser as in the example below:

   <SCRIPT>
      ua=navigator.userAgent;
      v=navigator.appVersion.substring(0,1);
      if (ua.lastIndexOf("MSIE")!=-1)
   {
      if (v == '4')
      {
       'do IE4.x stuff here
      }
      else if (v == '3')
      {
       'do IE3.x stuff here
      }
      else
      {
       'do other browser stuff here
      }
   </SCRIPT>

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q179849 HOWTO Use Connectable Objects Including ActiveX Objects in Java

 Microsoft SDK for Java

Q179849 HOWTO: Use Connectable Objects Including ActiveX Objects in Java

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

Connectable objects are COM objects that use a standard COM mechanism for notifying clients that something has occurred or changed. Microsoft® ActiveX® controls and Automation objects use this mechanism to fire "events." Developer environments such as Microsoft® Visual Basic® and Microsoft® Visual C++® have built-in support for these events.

The Microsoft SDK for Java 2.0 and later gives Java client developers the ability to use these connectable objects and receive their events.

MORE INFORMATION

A connectable object is a COM object that implements the interface IConnectionPointContainer. A client application calls IConnectionPointContainer->FindConnectionPoint to ask the object if it supports a specific type of connection which is defined by a unique COM interface and ID. If the object supports that connection type, the result is a pointer to an IConnectionPoint interface that represents that specific connection type.

Now that the client application has the object's IConnectionPoint interface for a specific type of connection, the client can instruct the object to add the client as a recipient for the connection's outgoing calls.

To do this, the client application has to create a "sink" object, which is just a COM object that implements the unique COM interface used by this connection. The client then calls IConnectionPoint->Advise and passes its sink to the connectable object. The object gives the client a value called a "cookie" that represents this connection.

When the connectable object needs to notify the client application that some event has occurred, it makes a call to the interface that is implemented on the clients "sink" object.

Later, when the client wants to disconnect from the object, the client calls IConnectionPoint->Unadvise and passes in the "cookie."

Fortunately for Java developers, the Microsoft SDK for Java 2.0 and later makes this process much simpler. To attach a client written in Java to a connectable object, you must first make the "sink" by creating a Java class that implements the COM interface defined in the objects type library. Once you have created an instance of this "sink" class, you will use the com.ms.com.ConnectionPointCookie class to make the "connection" between your sink and the connectable object. All calls to the sink occur in the methods defined on the COM interface.

Example

Note In order to compile the following code, you MUST use the latest Java compiler included in SDK 2.0 or later (Jvc.exe version 1.02.4337 or above). The version of the compiler included with Visual J++ and SDK 1.5 will not work with the source produced by JActiveX.exe. For information on about using the new Java compiler with Visual J++, see the REFERENCES section of this document.

To demonstrate this, use the Microsoft® Internet Explorer 4.0 COM object. Internet Explorer fires "events," or calls to a "sink" object connected to it. Since Internet Explorer's type information includes the description of the interface Internet Explorer uses as a sink, you need to convert the type information into Java classes by using the JActiveX.exe tool.

Open a command prompt and set the current directory to

C:\%Windir%\SYSTEM[32]\

Make sure that the %SDKDIR%\BIN directory is in the PATH, then type:

JACTIVEX.EXE SHDOCVW.DLL

This produces a directory and many files under C:\%Windir%\JAVA\TRUSTLIB\. The directory name is Shdocvw and the files that you need to know about follow:

  • InternetExplorer.java

  • IWebBrowser2.java

  • DWebBrowserEvents2.java

These files are the wrapper classes for the Internet Explorer 4.0 COM object and its interfaces. Notice the DWebBrowserEvents2.java file. This source file contains the interface definition for the sink required to connect to Internet Explorer 4.0. The methods on the interface represent the events that Internet Explorer "fires." This sink has many methods. The two that we are concerned with for this sample are StatusTextChange (String Text) and OnQuit. In order for a program to receive Internet Explorer's events, you need to create a class that implements this interface.

Below is an application that implements the DWebBrowserEvents2 interface:

   import java.awt.*;
   import java.awt.event.*;
   import com.ms.activeX.*;
   import com.ms.com.*;
   import shdocvw.*;  // Import the IE40 package created by JactiveX.
   public class JavaConnect extends Frame
      implements DWebBrowserEvents2, ActionListener
   {
      IWebBrowser2 browser; // Member to hold IE COM object
      TextField location; // Member on Frame for user to type in URL
      TextArea out; // TextArea on Frame that shows Browser status text
      ConnectionPointCookie cookie; // Cookie that connects your event
                                    // "sink" to the browser
      public static void main(String args[])
      {
         // Create an instance of this class. Resize and show.
         final JavaConnect jc = new JavaConnect();
         jc.addWindowListener(new WindowAdapter() {
           public void windowClosing(WindowEvent e)
           {
              if (jc.browser != null)
                 jc.browser.Quit();
           }
         });
         jc.setSize(400,400);
         jc.show();
      }
      public JavaConnect()
      {
         // Create an instance of IE and make it visible
         browser = (IWebBrowser2)new InternetExplorer();
         browser.setVisible(true);
         // Create a ConnectionPoint between the browser
         // and our DWebBrowserEvents2 interface
         cookie = new ConnectionPointCookie(browser, this,
                      shdocvw.DWebBrowserEvents2.class);
         // Create a Panel for the Button and TextField
         Panel northPanel = new Panel();
         northPanel.setLayout(new BorderLayout());
         // Create a Button, add yourself as its ActionListener
         // and add it to the Panel
         Button nav = new Button("Navigate");
         nav.addActionListener(this);
         northPanel.add("West", nav);
         // Create a TextField and add it to the Panel
         location = new TextField();
         northPanel.add("Center", location);
         // Add Panel to Frame
         add("North", northPanel);
         // Create a TextArea and add it to the Frame
         out = new TextArea();
         add("Center", out);
      }
// ***********************************************************
      // These methods are declared in the ActionListener interface.
      // By implementing this interface, you can receive events
      // from the button on the Frame.
public void actionPerformed(ActionEvent e)
      {
         // Create a variant for use with the optional
         // parameters of the Navigate2 method
         Variant optional = new Variant();
         optional.noParam();
// Call Navigate2 on IE
         browser.Navigate2(new Variant(location.getText()),
                               optional, optional, optional, optional);
      }
// ***************************************************************
      // These methods are declared in the DWebBrowserEvents2 interface.
      // By implementing this interface and using a ConnectionPointCookie,
      // you can receive events from Internet Explorer.
      // Each method represents a different event that can come from
      // Internet Explorer.
public void StatusTextChange(String Text)
      {
         // The status bar information has changed.
         // Append this new status text to the TextArea.
         out.append(Text+"\n");
      }
public void ProgressChange(int Progress, int ProgressMax)
      {}
public void CommandStateChange(int Command, boolean Enable)
      {}
public void DownloadBegin()
      {}
public void DownloadComplete()
      {}
public void TitleChange(String Text)
      {}
public void PropertyChange(String szProperty)
      {}
public void BeforeNavigate2(Object pDisp, Variant URL,
          Variant Flags, Variant TargetFrameName, Variant PostData,
          Variant Headers, boolean[] Cancel)
      {}
public void NewWindow2(Object[] ppDisp, boolean[] Cancel)
      {}
public void NavigateComplete2(Object pDisp, Variant URL)
      {}
public void DocumentComplete(Object pDisp, Variant URL)
      {}
public void OnQuit()
      {
         // The user closed IE.
         out.append("Quiting IE\n");
         cookie = null;
// Manually release the browser COM object.
         // This is not necessary, but ensures that no extra
         // references to the COM object hang around after we
         // exit the Java application.
         ComLib.release(browser);
browser = null;
         System.exit(0);
      }
public void OnVisible(boolean Visible)
      {}
public void OnToolBar(boolean ToolBar)
      {}
public void OnMenuBar(boolean MenuBar)
      {}
public void OnStatusBar(boolean StatusBar)
      {}
public void OnFullScreen(boolean FullScreen)
      {}
public void OnTheaterMode(boolean TheaterMode)
      {}
   }

In the constructor, create a ConnectionPointCookie. The constructor parameters should be based on the following:

  • The COM object that is a connectable object.

  • A Java object that implements the sink interface.

  • The Class object that represents the sink interface.

In this application's case, you called ConnectionPointCookie (browser, this, shdocvw.DWebBrowserEvents2.class).

The ConnectionPointCookie handles all of the COM complexities of attaching the sink to the correct IConnectionPoint on the connectable object.

When this application is executed using the following you will see two windows:

jview JavaConnect

One is a Java Frame that contains a TextField, a Button, and a TextArea. The other is the Internet Explorer windows. On the Java Frame, enter a URL in the TextField and click Navigate. You should notice the Internet Explorer window load the URL you specified. As Internet Explorer loads the Web page, the Status Bar at the bottom of the browser window changes to give the user an updated status. This text is also echoed to the Java application through the event mechanism. The applications StatusTextChange method gets called each time. The StatusTextChange method appends the text to the bottom of the TextArea on the Frame.

By clicking on the window close button on the Browser, you can send an OnQuit event to the Java application. The application responds by releasing the Internet Explorer COM object and quitting.

REFERENCES

For more information on connectable objects and Automation events, see Inside OLE (Second Edition) by Kraig Brockschmidt, Microsoft Press.

For more information on ConnectionPointCookie, see the Microsoft SDK for Java.

For information on about using the new Java compiler with Microsoft® Visual J++®, please see the following article in the Microsoft Knowledge Base:

Q177165 INFO: Use New Java 1.1 Language Features with Visual J++ 1.1

Additional query words:

ConnectionPointCookie event sink


Q179850 HOWTO Playing a .WAV file in Java

 Microsoft SDK for Java

Q179850 HOWTO: Playing a .WAV file in Java

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® virtual machine (Microsoft VM)

SUMMARY

The Applet and AudioClip class only play .AU files. Microsoft offers two solutions to play .WAV files when using the Microsoft VM.

The Microsoft SDK for Java 2.0 and later includes a sample, DirectX Direct Sound, demonstrating how to use DirectSound to play .WAV files from a URL. It is also possible to use the Winmm class to play a .WAV file from the local drive, although your program must be trusted.

MORE INFORMATION

The sample code below demonstrates how to use the Winmm class to play a .WAV file. This sample requires you place a .WAV file in the current directory and name the file "sound.wav".

Sample Code

import com.ms.win32.Winmm;
   import com.ms.win32.wins;
public class PlayWav {
     public static void main(String args[])
     {
       WavAudio ac = new WavAudio("sound.wav");
       System.out.println("Looping sound...");
       ac.loop();
       try {
         Thread.sleep(20000);
       } catch (Exception e) {
       }
       System.out.println("stoping audio.");
       ac.stop();
     }
   }
class WavAudio {
     String wavFile=null;
     public WavAudio(String file) {
       wavFile=file;
     }
     public void stop() {
       Winmm.PlaySound(null,0,
          wins.SND_ASYNC|wins.SND_FILENAME|wins.SND_NOWAIT);
     }
     public void play() {
       stop();
       Winmm.PlaySound(wavFile,0,
         wins.SND_ASYNC|wins.SND_FILENAME|wins.SND_NOWAIT);
     }
     public void loop() {
       Winmm.PlaySound(wavFile,0,
         wins.SND_ASYNC|wins.SND_LOOP|wins.SND_FILENAME|wins.SND_NOWAIT);
     }
   }

REFERENCES

For more information please see the Microsoft SDK for Java documentation, available at http://www.microsoft.com/java/sdk/ This link takes you to a site on microsoft.com.

For additional information, please see the following article in the Microsoft Knowledge Base:

Q178707 PRB Unable to play .Wav file from Applet or Audio Clip

Additional query words:

audio .wav winmm


Q179851 HOWTO Clearing a Selection in an AFC UIChoice Control

 Microsoft SDK for Java

Q179851 HOWTO: Clearing a Selection in an AFC UIChoice Control

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

You can programmatically clear a UIChoice selection by setting its selected index to -1.

MORE INFORMATION

The sample code below demonstrates how to use setSelectedIndex(-1) to clear the item currently selected in the UIChoice. Compile and run the program, select an item in the UIChoice control, then click the Clear UIChoice button. This results in the setSelectedIndex method getting called with a value of -1, clearing the previously selected item from the UIChoice control.

Sample Code

import com.ms.ui.*;
   import com.ms.ui.event.*;
public class ResetUIChoiceDemo implements IUIActionListener {
     UIChoice choice=null;
public ResetUIChoiceDemo(UIChoice choice) {
       this.choice=choice;
     }
public static void main(String args[])
     {
       UIFrame frame = new UIFrame("AFC Frame");
       frame.setSize(320,50);
       frame.setLayout(new UIGridLayout(0,2));
       UIChoice choice=new UIChoice();
       choice.addString("ChoiceA");
       choice.addString("ChoiceB");
       choice.addString("ChoiceC");
       choice.addString("ChoiceD");
       frame.add(choice);
       UIPushButton clearButton=new UIPushButton("Clear UIChoice");
       clearButton.addActionListener(new ResetUIChoiceDemo(choice));
       frame.add(clearButton);
       frame.setVisible(true);
     }
public void actionPerformed(UIActionEvent e) {
       choice.setSelectedIndex(-1);  // Clear the UIChoice selection.
     }
   }

REFERENCES

For more information please see the Microsoft SDK for Java 2.0x documentation, available at http://www.microsoft.com/java/sdk/ This link takes you to a site on microsoft.com.

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q179852 HOWTO Enabling Hot-Tracking in an AFC UIPushButton

 Microsoft SDK for Java

Q179852 HOWTO: Enabling Hot-Tracking in an AFC UIPushButton

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® SDK for AFC 1.0

SUMMARY

The Microsoft Application Foundation Classes (AFC) includes the ability to enable hot-tracking by overriding the setHot method.

MORE INFORMATION

The sample code below demonstrates overriding the setHot(boolean hot) method, changing the color of the component inside a UIPushButton when the cursor is over the button.

Sample Code

import com.ms.ui.*;
   import com.ms.fx.*;
public class HotTrackDemo {
     public static void main(String args[])
     {
       UIFrame frame = new UIFrame("HotPushButton Example");
       frame.setLayout(new UIGridLayout(3,0));
       frame.setSize(320,200);
       frame.setVisible(true);
       HotPushButton btn1=new HotPushButton("BUTTON1");
       HotPushButton btn2=new HotPushButton("BUTTON2");
       btn2.setColors(FxColor.green,FxColor.lightGray);
       frame.add(btn1);
       frame.add(btn2);
     }
   }
class HotPushButton extends UIPushButton {
     java.awt.Color colorNorm=java.awt.Color.black;
     java.awt.Color colorHot=java.awt.Color.red;
     public HotPushButton(String value) {
       super(value);
     }
     public HotPushButton(IUIComponent comp) {
       super(comp);
     }
     public void setColors(java.awt.Color hot,java.awt.Color norm) {
       colorHot=hot;
       colorNorm=norm;
       setHot(isHot());
     }
     public void setHot(boolean hot) {
       super.setHot(hot);
       setForeground(hot?colorHot:colorNorm);  // Change color of component
       invalidateAll();
     }
   }

REFERENCES

For more information please see the Microsoft SDK for Java 2.0x documentation, available at http://www.microsoft.com/java/sdk/ This link takes you to a site on microsoft.com.

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

hot tracking afc uipushbutton


Q180707 HOWTO Reading a File on a Web Server from an Applet

 Microsoft SDK for Java

Q180707 HOWTO: Reading a File on a Web Server from an Applet

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

The following sample code shows how to read a file on a Web Server from an applet.

MORE INFORMATION

The class below shows how to read a text file named Readme.txt from the server.

Note Place all of the files in the same folder on the Web server.

The following steps give an example of how an applet can read a file on a Web Server:

  1. Create the following file, naming it ReadFile.java:
       //
   // ReadFile.java
   //
   import java.io.*;
   import java.net.*;
   import java.applet.*;
   import java.awt.*;
   public class ReadFile extends Applet {
      public void start () {
         TextArea textArea=new TextArea();
         setLayout(new BorderLayout());
         add("Center",textArea);
         String text=null;
         try {
            URL url = new URL(getDocumentBase(),"readme.txt");
            DataInputStream stream = new
            DataInputStream(url.openStream());
            do {
               text = stream.readLine();
               if (text!=null) textArea.appendText(text+"\r\n");
            } while (text!=null);
         }
         catch (IOException e) {
            e.printStackTrace();
         }
      }
   }
  2. Compile the ReadFile.java class, creating a ReadFile.class.

  3. Create a text file with at least one line of text and name it Readme.txt.

  4. Create an HTML file named ReadFile.html with the following code:
       <html>
   <head>
   <title>readfile</title>
   </head>
   <body>
   <hr>
   <applet
       code=ReadFile
       name=readfile
       width=320
       height=240 >
   </applet>
   <hr>
   <a href="ReadFile.java">The source.</a>
   </body>
   </html>
  5. Put ReadFile.java, ReadFile.class, ReadFile.html, and Readme.txt in the same folder on your Web Server.

  6. Open ReadFile.html from Internet Explorer.

You should be able to see your text from Readme.txt on the applet.


Q184067 HOWTO Using TrueType Fonts in Java

 Microsoft SDK for Java

Q184067 HOWTO: Using TrueType Fonts in Java

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

The java.awt.Font class represents a font in a platform-independent way. This class restricts the programmer to using a small subset of the fonts installed on a user's system. Microsoft's VM exposes a class to access all of the TrueType fonts installed on the user's system.

MORE INFORMATION

The com.ms.awt.FontX class provides access to all of the fonts that are installed on the user's system. This class creates a new font with the specified name, style, and point size. It is used to access system fonts on the Microsoft® Win32® platform not otherwise available in Java (for example, the "symbol" font). This class is available only for the Microsoft VM.

Sample Code

public AWTFontXDemo()
      {
         appFrame = new Frame("TrueType Font Demo");
         appFrame.setLayout(new BorderLayout());
         edit = new TextArea("Enter some text");
         button = new Button("Change Font");
         appFrame.add(edit,"Center");
         appFrame.add(button,"South");
         button.addActionListener(this);
         appFrame.setSize(320,200);
         appFrame.setVisible(true);
      }
public void actionPerformed(ActionEvent ae)
      {
         UIFontDialog dialog = new
         UIFontDialog(FxToolkit.getHelperUIFrame());
    dialog.show();
    FontX font = (FontX)dialog.getFxFont();
         edit.setFont(font);
         edit.repaint();
      }
   }

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

font truetype


Q195175 HOWTO Sending Text to the Visual J++ Output Window

 Microsoft SDK for Java

Q195175 HOWTO: Sending Text to the Visual J++ Output Window

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, versions 3.1, 3.2

SUMMARY

There are several ways to send debug text strings to the Visual J++ Output window for diagnosing runtime problems. These methods will work only when you launch your application from the Visual J++ environment. Applications launched standalone will not be able to access the Output window.

MORE INFORMATION

The first way to send text strings to the Visual J++ Output window is by using the print and println methods of the com.ms.debug.Debugger.out package. When you call these methods from a Java application that is spawned from JVIEW or WJVIEW in either debug or release builds, the text string will appear in the Visual J++ Output window.

Here is a simple sample that demonstrates using the println method:

   public class Class1 {
      public static void main (String[] args) {
         com.ms.debug.Debugger.out.println("Hello World");
      }
   }

When this class is built and run from within Visual J++, you will see the string "Hello World" appear in the Visual J++ Output window. Notice that the string is output whether you build your application in Debug or Retail mode.

Another way to send text strings to the Visual J++ Output window is by using the Windows Foundation Classes (WFC) methods in the com.ms.wfc.util.Debug package. This package is different from the com.ms.debug.Debugger package in that the methods are conditionally compiled so that they exist only in Debug builds of your application. When you build your application for Retail release, the calls to output diagnostic strings through the WFC Debug package will not be compiled into your code, saving size and possibly execution speed.

Here is a WFC button click message handler that will output a text string to the Visual J++ Output window:

   private void button1_click(Object source, Event e) {
      com.ms.wfc.util.Debug.println("Hello World");
   }

Notice that if you build your form in Debug mode (selectable in the Project Properties dialog box), the text string will appear in the Visual J++ Output window when you click button1. If you then build your application in Retail mode and execute from Visual J++, the text will no longer appear in the Output window. In fact, the method call will no longer exist in your code.

One thing to be aware of with the com.ms.wfc.util.Debug package is that it will pass output only to the Visual J++ Output window if you are executing under WJVIEW, as is done in most WFC Project templates. If you are executing your application with JVIEW–either by using the Console Application project template or by selecting the Launch as a Console Application check box in the Project Properties Launch tab, your output will go to the MS-DOS CONSOLE window by default. For additional information, please see the following article in the Microsoft Knowledge Base:

Q194187 Redirecting WFC Debug Output to the VJ6 Output Window

This article demonstrates how to redirect this output from the Console window to the Visual J++ Output window so that you can utilize the benefits of conditional compilation in your Java Console applications as well.

One further point is that all Console output from an application run under WJVIEW is rerouted to the Visual J++ Output window. This means that for applications that are run from the Visual J++ IDE and use WJVIEW to launch the Microsoft® virtual machine (Microsoft VM), System.out.println method calls will also appear in the Visual J++ Output window for both Retail and Debug builds.

The following two tables show where output for the calls discussed in this article will appear, depending upon whether they are run under JVIEW or WJVIEW, and whether they are built in DEBUG or RETAIL modes.

Java Method Call | WJVIEW Retail Build | WJVIEW Debug Build
System.out.println | VJ Output Window | VJ Output Window
com.ms.debug.Debugger.out.println | VJ Output Window | VJ Output Window |
com.ms.wfc.util.Debug.println | no Output | VJ Output Window |

Java Method Call | JView Retail Build | JView Debug Build
System.out.println | MS-DOS Console | MS-DOS Console
com.ms.debug.Debugger.out.println | VJ Output Window | VJ Output Window |
com.ms.wfc.util.Debug.println | no Output | MS-DOS Console |


Q222092 HOWTO Call Native (DLL) Code From Java Using JNI

 Microsoft SDK for Java

Q222092 HOWTO: Call Native (DLL) Code From Java Using JNI

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® Visual Studio® 6.0

  • Microsoft® SDK for Java, version 3.1

SUMMARY

This article details the process of calling native C/C++ code (in a DLL) from Java using JNI (Java Native Interface). This article presumes a working knowledge of the Microsoft® Visual C++® command-line compiler, CL.EXE.

  • Make sure that you are using a version of Microsoft's SDK for Java that supports JNI. JNI support was added in December of 1998 to SDK version 3.1 and above. For more information, visit the Java lawsuit information center.

  • Make sure that the environment variable, CLASSPATH, contains a reference to %Windir%\Java\Classes\Classes.zip and C:\ (assuming that C:\ is your development drive).

  • Make sure that your %SDKDIR%\Bin directory is included in your path (for JavaH, JVC, and JView).

  • Make sure that Visual C++ is properly set up for command-line use. See your Visual C++ documentation for details.

  • Write your Java code:
       public class TestJNI {
      public native void greetings();
      static {
         System.loadLibrary("greet");
      }
      public static void main(String args[]) {
         new TestJNI().greetings();
      }
   }
  • Compile the Java file:

    jvc TestJNI.java

  • Run JavaH on the generated class file:

    javah -jni TestJNI

  • Write the C/C++ code based on the generated header file:
    #include "TestJNI.h"
#include <stdio.h>
   JNIEXPORT void JNICALL Java_TestJNI_greetings(JNIEnv *env,jobject jobj) {
      printf("Hello from Visual C++!");
   }
  • Compile the C/C++ code:

    cl greet.cpp -Ic:\sdk-java.31\include -Fegreet.dll -MD -LD

  • Test the application:

    jview TestJNI

MORE INFORMATION

Things to note:

  • In the call to System.loadLibrary, omit the ".dll" extension from the native library's file name.

  • To support legacy native code, just have your DLL's function redirect the call to the legacy code.

REFERENCES

For more information on the legal action brought by Sun regarding Microsoft's Java agreement, visit the Java lawsuit information center.

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q222117 HOWTO Print the Contents of WFC's HTMLControl

 Microsoft SDK for Java

Q222117 HOWTO: Print the Contents of WFC's HTMLControl

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, version 3.2

  • Microsoft® virtual machine (Microsoft VM)

SUMMARY

WFC's HTMLControl is a convenient way to display HTML in a Visual J++ 6.0 application. Unfortunately, it does not provide a method for sending its contents to the printer. This article will explain how to do this.

MORE INFORMATION

The HTMLControl object is a WFC component that makes dealing with the Microsoft® Internet Explorer browser control easy. Unfortunately, it doesn't provide an easy way to print a Web page. But you can send an OLE command to the underlying browser control to make it print.

If you want to include the browser control (or any ActiveX control) on your WFC Form, you would normally use "JActiveX.EXE" on the command line or "Add COM Wrapper..." from the menu in Visual J++ 6.0 to generate Java-callable methods for that control.

Included in this article is JActiveX-generated wrapper code for the browser control. Because the interfaces on COM objects cannot change, it is safe to just use this code instead of recreating it from scratch.

Add the following code to the import section of the Java class you want to print from:

   import myole.IOleCommandTarget;

Add the following code to the Java class that you want to print from. When you're done, you can just call this method to print from the specified HTMLControl:

   private void HTMLControl_Print(HTMLControl hc) {
      final int OLECMDID_PRINT = 6;
      final int OLECMDEXECOPT_PRMOPTUSER = 1;
      final int OLECMDEXECOPT_DONTPROMPTUSER = 2;
      IOleCommandTarget cmdtarget = (IOleCommandTarget) hc.getDocument().getPeer();
      cmdtarget.Exec(null, OLECMDID_PRINT, OLECMDEXECOPT_DONTPROMPTUSER, null,null);

   }
IOleCommandTarget.java:
   package myole;
   import com.ms.com.*;
   import com.ms.com.IUnknown;
   import com.ms.com.Variant;
   // VTable-only interface IOleCommandTarget
   /** @com.interface(iid=B722BCCB-4E68-101B-A2BC-00AA00404770, thread=AUTO) */
   public interface IOleCommandTarget extends IUnknown
   {
    /** @com.method(vtoffset=0, addFlagsVtable=4)
        @com.parameters([in,type=PTR] pguidCmdGroup, [in,type=U4] cCmds,
   [in,out,type=PTR] prgCmds, [in,out,type=PTR] pCmdText) */
    public void QueryStatus(com.ms.com._Guid pguidCmdGroup, int cCmds,
   myole._tagOLECMD prgCmds, myole._tagOLECMDTEXT pCmdText);
    /** @com.method(vtoffset=1, addFlagsVtable=4)
        @com.parameters([in,type=PTR] pguidCmdGroup, [in,type=U4] nCmdID,
   [in,type=U4] nCmdexecopt, [in,type=PTR] pvaIn, [in,out,type=PTR] pvaOut) */
    public void Exec(com.ms.com._Guid pguidCmdGroup, int nCmdID, int nCmdexecopt,
   Variant pvaIn, Variant pvaOut);
    public static final com.ms.com._Guid iid = new
   com.ms.com._Guid((int)0xb722bccb, (short)0x4e68, (short)0x101b, (byte)0xa2,
   (byte)0xbc, (byte)0x0, (byte)0xaa,
        (byte)0x0, (byte)0x40, (byte)0x47, (byte)0x70);
   }

The following code comments are listed at the top of each of the remaining code listings. They are listed here as a reference and as a reminder. Feel free to add them to the code when you cut and paste or you can just leave them out.

   //
   // Auto-generated using JActiveX.EXE 4.79.2337
   //   (jactivex d.tlb)
   //
   // WARNING: Do not remove the comments that include "@com" directives.
   // This source file must be compiled by a @com-aware compiler.
   // If you are using the Microsoft Visual J++ compiler, you must use
   // version 1.02.3920 or later. Previous versions will not issue an error
   // but will not generate COM-enabled class files.
   //
_tagOLECMD.java:
   package myole;
   import com.ms.com.*;
   import com.ms.com.IUnknown;
   import com.ms.com.Variant;
   /** @com.struct(noAutoOffset) */
   public final class _tagOLECMD
   {
    /** @com.structmap([offset=0,type=U4] cmdID) */
    public int cmdID;

    /** @com.structmap([offset=4,type=U4] cmdf) */
    public int cmdf;
   }
_tagOLECMDTEXT.java:
   package myole;
   import com.ms.com.*;
   import com.ms.com.IUnknown;
   import com.ms.com.Variant;
   /** @com.struct(noAutoOffset) */
   public final class _tagOLECMDTEXT
   {
    /** @com.structmap([offset=0,type=U4] cmdtextf) */
    public int cmdtextf;
    /** @com.structmap([offset=4,type=U4] cwActual) */
    public int cwActual;
    /** @com.structmap([offset=8,type=U4] cwBuf) */
    public int cwBuf;
   // UNMAPPABLE: rgwz: Cannot be used as a structure field.
   //   /** @com.structmap(UNMAPPABLE rgwz) */
   //  public UNMAPPABLE rgwz;
   }

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q232485 HOWTO Programmatically Create Members in Site Server with Java

 Microsoft SDK for Java

Q232485 HOWTO: Programmatically Create Members in Site Server with Java

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, version 3.1

SUMMARY

This article describes how to programmatically create members in Site Server 3.0 Membership Directory, using Active Directory Service Interfaces (ADSI) 2.0, Java/COM integration, and Microsoft® J/Direct™. This article is based on the following article in the Microsoft Knowledge Base and performs the same tasks using Java rather than Microsoft® VBScript:

Q192781 How to Programmatically Create Members in Site Server 3.0

MORE INFORMATION

When you create a new Member object, the following three properties must be set:

  • objectClass

  • cn (Common Name)

  • GUID

The first two, objectClass and cn, are set when the Create method is called. The third, GUID, must explicitly be set. If these properties are not set properly, the call to SetInfo will fail and the new Member object will not be created.

The following code demonstrates adding a member programmatically:

   import activeds.*;
   //import autoobj.*;
   //Uncomment the above line if you want to use
   //early binding for the GuidGen object.
   import com.ms.com.*;
   import com.ms.win32.*;
   public class ADSISamp
   {
     IADsContainer oADsContainer;
     IADs oADsNewUser;
     Object oGuidGen;
     Variant strGuid;
     String strLdapPath;

     public static void main (String[] args) throws Exception
     {
       ADSISamp app = new ADSISamp();
       app.run();
       System.in.read();
     }

     public void run()
     {
       try
       {
         //The path to the ou=Members container.
         strLdapPath = "LDAP://localhost:5292/o=Microsoft/ou=Members";
         //Instantiate the GUID Generator that comes with Site Server
         //and store the GUID for use later on.
         //Using CoCreateInstance here, but could
         //also use a wrapper from autoobj.dll
         //in the Bin\P&M directory of the Site Server installation.
         oGuidGen = createObject("Membership.GuidGen.1");
         //oGuidGen = (IGuidGen)new GuidGen();
         //strGuid.putString(((IGuidGen)oGuidGen).GenerateGuid());

         //Using the IDispatch pointer returned from createObject
         //via the Dispatch class to call GenerateGuid.
         //Once again, could also use early-binding via the wrapper class.
         //Use of IDispatch allows us to use this object with out
         //importing the wrapper classes for autoobj.dll.
         strGuid = Dispatch.call(oGuidGen, "GenerateGuid");
         //Bind to the container in which the Member will be created.
         //Note that this is an API call, and is declared native
         //with other API J/Direct declarations at the bottom of this
         //source file.  It does, however, return a COM Interface
         //exposed by the activeds.dll and described in activeds.tlb,
         //both of which can be found in the %windir%\system32 directory.
         oADsContainer = (IADsContainer)ADsGetObject(strLdapPath,
         IADs.iid);
         //Create the new user object.  Note that the Create() method
         //returns an Interface pointer that maps to the IADs wrapper
         //class in Java, which is the core ADSI COM Interface.
         oADsNewUser = (IADs)oADsContainer.Create("member", "cn=JohnDoe");

         oADsNewUser.Put("givenName", new Variant("John"));
         oADsNewUser.Put("sn", new Variant("Doe"));
         oADsNewUser.Put("userPassword", new Variant("password"));
         //No need for a new Variant as Dispatch.call returns a Variant.
         oADsNewUser.Put("GUID", strGuid);
         oADsNewUser.SetInfo();

         //Destroy the objects.
         ComLib.release(oGuidGen);
         ComLib.release(oADsNewUser);
         ComLib.release(oADsContainer);
       }
       catch (Exception ex)
       {
         User32.MessageBox(0,
                           ex.toString(),
                           "Java Exception",
                           0);
       }
     }

     // J/Direct native API method declarations.
     //*******************************************************

     /** @dll.import("activeds", ole) */
     public static native IUnknown ADsGetObject(String pathname,
                                                _Guid riid);

     /** @dll.import("ole32", ole) */
     public static native IUnknown CoCreateInstance(_Guid clsid,
                                                    IUnknown punkOuter,
                                                    int context,
                                                    _Guid riid);
     /** @dll.import("ole32", ole) */
     public static native _Guid CLSIDFromString(String str);

     public static _Guid IID_IUnknown = new _Guid
     ("{00000000-0000-0000-C000-000000000046}");

     public static Object createObject(String str)
     {
       return CoCreateInstance(CLSIDFromString(str),
                               null,
                               ComContext.INPROC_SERVER |
                               ComContext.LOCAL_SERVER,
                               IID_IUnknown);
     }
   }

REFERENCES

Microsoft Developer Network (MSDN™) Library: "Active Directory Service Interfaces Version 2.0" located in SDK Documentation/Platform SDK/Networking and Distributed Services.

For more information, see the following article in the Microsoft Knowledge Base:

Q192781 How to Programmatically Create Members in Site Server 3.0

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q232642 HOWTO Install a DU or Java ZIP in the JPM with Rundll32

 Microsoft SDK for Java

Q232642 HOWTO: Install a DU or Java ZIP in the JPM with Rundll32

The information in this article applies to:

  • Microsoft® SDK for Java, versions 3.0, 3.0 Preview 1, 3.1, 3.2

  • Microsoft® virtual machine (Microsoft VM)

SUMMARY

This article explains how to install Java packages into the Java Package Manager (JPM), without the aid of a download tool, such as Microsoft® Internet Explorer.

MORE INFORMATION

To install a package into the JPM from the command line, using the Rundll32 interface, first put it into a standard ZIP file or a .cab file with an Open Software Distribution (OSD) manifest. Here is a brief explanation of the OSD specification from the Microsoft Developer Network (MSDN):

Software distribution. Recently Microsoft and Marimba co-authored and submitted a specification to the Worldwide Web Consortium (W3C) called Open Software Description (OSD) that describes the delivery of software applications over the Internet. OSD uses unique XML tags to describe software components, including their versions, underlying structure, relationships to other components, and dependencies. It can describe and reference platform-native code (such as Macintosh, Win32, or ActiveX components) as well as Java packages and applications.

Next, use the JPM Rundll32 interface as follows.

Note An alias in %Windir%\Downloaded Program Files is created only while installing a .cab file with an OSD, and not while installing a ZIP file. But in both the cases, a ZIP file with a mangled name will be created in %Windir%\java\packages as expected. This ZIP file contains the package being installed. Here, %Windir% represents the Windows directory. Replace System32 by System in the example below while using Microsoft® Windows® 95 or Microsoft® Windows® 98.

rundll32 %windir%\System32\msjava.dll,JavaPkgMgr_Install <filename>,<file type>,<hi version>,<lo version>,<build>,<package flags>,<install flags>,<namespace>

File Type:

0=CAB

1=ZIP

Package Flags:

0=System class

1=Non system class

2=Needs trusted source

Install Flags:

1=No version check

2=No signer check

4=Autodetect packages

8=Delete input file

A sample command line might look like:

rundll32 %windir%\System32\msjava.dll,JavaPkgMgr_Install myclasses.zip,1,4,79,2151,0,12

Additional query words:

kbSDKJava Rundll32 JPM


Q233200 HOWTO Silently Install Microsoft Virtual Machine Without Reboot

 Microsoft SDK for Java

Q233200 HOWTO: Silently Install Microsoft virtual machine Without Reboot

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

SUMMARY

Under certain circumstances you may need to install the Microsoft VM without user input or without the forced reboot at the end.

A common situation that requires this functionality is when you create a custom setup program that, in addition to installing an application, needs to upgrade the client's virtual machine.

Note The custom setup program must reboot the client's computer or the Microsoft VM will not install properly.

MORE INFORMATION

To accomplish this task you must install the Microsoft VM (Msjavx86.exe) with the following command line switches.

msjavx86 /q:a /r:n

The only thing that will be displayed is a window showing which components are being installed during the setup process. The computer will not be rebooted.

Switches

/q:a is quiet admin mode

This skips the disk space and administrative rights checks, both items that could potentially pop up an error dialog box. Using /q alone will allow the possibility of such errors occurring.

/r:n signifies no reboot

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the Microsoft® SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q234457 HOWTO Downgrade the Microsoft virtual machine

 Microsoft SDK for Java

Q234457 HOWTO: Downgrade the Microsoft virtual machine

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

SUMMARY

Downgrading the Microsoft virtual machine is not a recommended procedure and should be done only as a last resort. Furthermore, this article should be passed to a customer only when all other options have been exhausted.

Important This article contains information about editing the registry. Before you edit the registry, make sure you understand how to restore it if a problem occurs. For information about how to do this, view the Restoring the Registry Help topic in Regedit.exe or the Restoring a Registry Key Help topic in Regedt32.exe.

Warning Using Registry Editor incorrectly can cause serious problems that may require you to reinstall your operating system. Microsoft cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk.

For information about how to edit the registry, view the Changing Keys and Values Help topic in Registry Editor (Regedit.exe) or the Add and Delete Information in the Registry and Edit Registry Data Help topics in Regedt32.exe.

Note You should back up the registry before you edit it. If you are running Microsoft® Windows NT®, you should also update your Emergency Repair Disk (ERD).

MORE INFORMATION

This downgrade procedure works in most cases but is not 100 percent guaranteed. Please use this at your own risk:

  1. Refer to the following article in the Microsoft Knowledge Base, which contains a list of the files installed on a system as part of the Microsoft VM installation.

    Q163637 INFO: Availability of Current Build of Microsoft VM.

  2. Unregister Msjava.dll using Regsvr32.exe. Use the following command lines:

    cd \%Windir%\system32

    regsvr32 /u msjava.dll

  3. Rename any DLL that was installed with the newer Microsoft VM. These files are listed in Q163637 after the following sentence:

    The latest Microsoft VM released under Internet Explorer is version [nnnn] and consists of the following files for the X86 platform:

    Note Make sure that each DLL being renamed has a version number that is higher than that of the Microsoft VM you will be downgrading to. Also, if you can't rename one or more of the DLLs, you will need to reboot your computer.

    Note Please be aware that an error made using RegEdit can render a computer unusable.

  4. In RegEdit, remove the following keys:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Code Store Database\Global Namespace\Java Packages

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Java VM

  5. On the hard disk, remove the %Windir%\java directory. Among other things, this removes all Java packages installed on the machine, including the system classes.

  6. The current Microsoft VM should now be completely removed.

  7. You can now run the version of Msjavx86.exe with a version number that matches the Microsoft VM you wish to install. You might see dialog boxes asking whether you want to replace an existing DLL with an older version that Msjavx86 is trying to install. Since these files are not part of the Microsoft VM itself, the safe answer is generally No. If you are uncertain, check Q163637.

    Important The recent 24xx series of the Microsoft VM checks the version of Msjava.dll on the system to determine if it should install. There is a bug in the setup engine such that when there is no Msjava.dll on the system, setup reports that a newer Microsoft VM is already present. The workaround is to install the Microsoft VM with the following command line:

    msjavx86.exe /n:v

  8. Once you are confident that the correct Microsoft VM is installed and working properly, you can delete the old, renamed versions of the files.

    Important If you normally install any custom classes on the computer, you will have to install them again.

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the Microsoft® SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


INFO KB Articles Overview

The following Java-related INFO Knowledge Base (KB) Articles are included in the Microsoft SDK for Java.

Q167938: INFO: How Do I run JavaSrc After Installing Classes.zip
Q177159: INFO: Support for Multiple CABs or JARs in the Same APPLET Tag
Q177165: INFO: Use New Java 1.1 Language Features with Visual J++ 1.1
Q177167: INFO: JACTIVEX /X:m- Disables Automarshaling of COM Interfaces
Q177179: INFO: Internet Explorer Doesn't Display Signed .cab Certificate
Q177750: INFO: Visual J++ Relaxes Security Restrictions on Java Applets
Q181374: INFO: Related Component Download Articles


Q167938 INFO How Do I run JavaSrc After Installing Classes.zip

 Microsoft SDK for Java

Q167938 INFO: How Do I run JavaSrc After Installing Classes.zip

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

This article describes the JavaSrc.exe utility installed by Microsoft Visual J++ and the Microsoft SDK for Java. This tool helps extract Java sources from Classes.zip file. It also discusses the problem that occurs when you run JavaSrc on Classes.zip file and a message stating that the Classes.zip file did not contain any Java sources appears.

MORE INFORMATION

JavaSrc is a utility for extracting .java files from a .zip file. It extracts the source files for the Java class libraries from the Microsoft version of Classes.zip. Visual J++ installs this tool in the directory %Windir%\java\classes\ and the SDK installs the tool into %SDKDIR%\Bin. To extract the .java files from Classes.zip, use the following command:

javasrc classes.zip

This creates a directory tree below the directory that Classes.zip resides in and contains the source files for the Java class libraries.

Whenever a new version of Classes.zip is installed, you should run the JavaSrc.exe tool. Sometimes when you run JavaSrc on Classes.zip file, a dialog box appears with the message that the installed version of Classes.zip is not a developer version and it does not contain any Java sources. This problem could occur because the Classes.zip file was updated during an Internet Explorer or Microsoft® virtual machine (Microsoft VM) installation. This could cause a version mismatch of the Classes.zip file.

In this case, delete the Classes.zip file from %Windir%\java\classes directory, then try installing the classd.exe file from http://www.microsoft.com/java This link takes you to a site on microsoft.com by following the download link.

Note Before you install the updated Classes.zip file, make sure you have the latest Microsoft VM on http://www.microsoft.com/java This link takes you to a site on microsoft.com. See the References section of this article for more information.

If you are running the Microsoft SDK for Java, you may use the classd.exe file located in your %SDKDIR%\Bin directory.

Then run classd.exe in the Windows Explorer. This should install Classes.zip file. Then run JavaSrc.exe on Classes.zip, which should extract all the Java source files.

To delete the extracted Java source files from the hard disk, use the following command:

javasrc classes.zip

REFERENCES

For additional information on how to find the latest Microsoft VM, please see the following article in the Microsoft Knowledge Base:

Q163637 INFO: Availability of the current build of Microsoft VM.

For the latest Knowledge Base articles and other support information on Visual J++ and the Microsoft SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q177159 INFO Support for Multiple CABs or JARs in the Same APPLET Tag

 Microsoft SDK for Java

Q177159 INFO: Support for Multiple CABs or JARs in the Same APPLET Tag

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® Internet Explorer for Microsoft® Windows® 95

  • Microsoft Internet Explorer for Microsoft® Windows NT® 4.0

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

The Microsoft VM that ships with Internet Explorer 4.0x as well as with the SDK for Java 2.0 and later provides support for having multiple CABs and JARs in the same APPLET tag.

MORE INFORMATION

A parameter named Cabinets may contain multiple .cab files, separated by commas (,). For example, the <APPLET> tag in your HTML file can look like this:

   <applet
       code=foo.class
       name=foo
       width=320
       height=240 >
   <param name=cabinets value=foo.cab,bar.cab>
   </applet>

An Archive attribute may contain multiple JAR files or ZIP files, separated by commas. The JAR files or ZIP files may be compressed or uncompressed, but the manifest of the JAR file is ignored, including any digital signature information the manifest may contain.

For example, the APPLET tag in your HTML file can look like this:

   <applet
       code=foo.class
       ARCHIVE=foo.zip,bar.jar
       name=foo
       width=320
       height=240 >
   </applet>

You can include an Archive attribute and Cabinets parameter in the same <applet> tag. If you do, the Microsoft VM will search the .cab files from the Cabinets parameter and ignore the Archive attribute.

Note Browsers other than Internet Explorer 4.0 will generally ignore the Cabinets parameter.

REFERENCES

In order to understand how the Microsoft VM searches for the class requested from a Web page, please see the following article in the Microsoft Knowledge Base:

Q163637 INFO: Availability of the current build of Microsoft VM.

Q177168 INFO: How Does the Microsoft Virtual Machine Search for Java Classes?

You can download the latest release build of the Microsoft VM from

http://www.microsoft.com/java/ This link takes you to a site on microsoft.com.

For more information on the latest version of the Microsoft VM, please see the following article in the Microsoft Knowledge Base:

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java This link takes you to a site on microsoft.com

Additional query words:

multiple cabs jar files applet


Q177165 INFO Use New Java 1.1 Language Features with Visual J++ 1.1

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Visual J++®, versions 1.0, 1.1

SUMMARY

The new features of the Java programming language version 1.1 include the following:

  • Inner Classes

  • Anonymous Classes

  • Instance Initializers

  • Anonymous Array Expressions

  • Class Literals

  • Blank Finals and Final Locals

  • The @deprecated Tag

The new Java Compiler included with the Microsoft SDK for Java 2.01 and later includes the ability to compile code with these features plus the following:

  • Uncompressed JAR File Support

  • Support @COM syntax for JActiveX users

  • Support @DLL syntax for Microsoft® J/Direct™ users

Installing the SDK 2.01 or later will not automatically replace the Visual J++ compiler if a developer has Visual J++ installed. Please see the MORE INFORMATION section to use the new compiler with Visual J++ 1.1.

MORE INFORMATION

It is possible to use these new language features with Visual J++ 1.1. You can do this by replacing the compiler file in Visual J++ with three files from the Microsoft SDK for Java. First, save a copy of the compiler (Jvc.exe) from your existing Visual J++ installation. Next, copy Jvc.exe, Jps.dll and Msjvc.dll into your Visual J++ directory. Projects will then build using the new compiler.

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q177167 INFO JActiveX Option Disables Automarshaling of COM Interfaces

 Microsoft SDK for Java

Q177167 INFO: JActiveX /X:m- Disables Automarshaling of COM Interfaces

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

When using COM objects in Java, there are threading issues that can cause unusual behavior. Depending on the threading model of the COM object, the Microsoft® virtual machine (Microsoft VM) will either freely make calls to the COM object or use a special marshaling thread to make the calls to the COM object.

In certain scenarios, calls using the special thread can cause call blocking problems.

Using switches on the JActiveX tool, you can choose to not marshal the COM object on a special thread.

MORE INFORMATION

JActiveX produces Java interface source files for COM interfaces and inserts comments that tell the compiler and the Microsoft VM how to handle them. The following example of the @COM comment tells the compiler and VM that the interface is a COM interface, has a specific IID, is a dual interface, and its threading model is to be determined automatically at runtime.

   /** @com.interface(iid=12345678-ABCD-12AB-A1B2-123412341234,
      thread=AUTO, type=DUAL) */
   public interface IFoo extends IUnknown
   {
   ...

When the thread property of the @com.interface comment equals AUTO, the Microsoft virtual machine determines at runtime whether or not to use a special thread to marshal the call.

If the Microsoft VM creates the COM object with the new operator on a wrapper class, the VM determines the threading model of the COM object from the registry. Then, it chooses whether or not to marshal the interfaces based on that information.

If the Microsoft VM gets a COM object from a method call or a return value of a method call, the VM cannot determine the threading model of the object from the registry. Therefore, it uses the thread property of the @com.interface comment to determine whether marshaling is needed. If the thread property is AUTO, then the VM checks to see if the COM object aggregates the free-threaded marshaler. If so, it will not marshal the interface for that COM object. If the COM object does not aggregate the free-threaded marshaler, it will automatically marshal the interface.

There are many multithread-aware COM objects that do not aggregate the free- threaded marshaler. In these cases, the VM will still marshal the thread. In order to prevent this, you must use the /X:m- switch with JActiveX. The wrapper interface will now have the following comment:

   /** @com.interface(iid=12345678-ABCD-12AB-A1B2-123412341234,
      thread=NO, type=DUAL) */
   public interface IFoo extends IUnknown
   {
   ...

This tells the VM to not use a marshaler thread to make calls to the COM object. Calls will directly enter the COM object from the Java code.

Note It is important to make sure the COM object is truly "Free-Threaded" before using this switch. If you use this switch on Apartment or Single-threaded COM objects, it can cause bad behavior or crashes. Check the object's documentation or the registry to find out the object's threading model.

REFERENCES

For information about when a COM object should and shouldn't be marshaled by a custom thread, look at the Microsoft SDK for Java documentation's Apartment Model and Threading Issues section. The SDK for Java documentation can be found at the following Web site:

http://www.microsoft.com/ java/ This link takes you to a site on microsoft.com

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q177179 INFO Internet Explorer Doesn't Display Signed .cab Certificate

 Microsoft SDK for Java

Q177179 INFO: Internet Explorer Doesn't Display Signed .cab Certificate

The information in this article applies to:

  • Microsoft® SDK for Java, versions 1.51, 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer (Programming) versions 3.01, 3.02, 4.0x

SUMMARY

There are several scenarios where Internet Explorer does not show a certificate for a signed .cab file. The following section describes those scenarios.

MORE INFORMATION

Here are the three most common reasons for this behavior:

  • If the .cab file was signed using a test certificate, you must enable test certificates for the local machine; otherwise, the signature is not considered valid. You can do this by running the Wvtston.reg (SDK for Java 1.5x) or Setreg.exe (SDK for Java 2.0 or later) file included with the code signing kit.

  • You have accepted a software publisher as "always trusted." To verify this, in Internet Explorer, go to View, Options, Security, Publishers to ensure the publisher does not appear in the list box. If so, you can use this dialog box to remove it.

  • If the client machine is running Microsoft® Windows NT®, the current user must have administrator privileges or have "Full Control" access to the following registry keys (and existing subkeys):

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SystemCertificates

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDlls

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WinTrust

These privileges can be granted by a user on the machine who has administrator privileges using Regedt32.exe. This requirement will be addressed in future versions of Internet Explorer.

Note If the certificate does not appear or you answer No to the certificate, the applet will still load but will not be trusted.

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q177750 INFO Visual J++ Relaxes Security Restrictions on Java Applets

 Microsoft SDK for Java

Q177750 INFO: Visual J++ Relaxes Security Restrictions on Java Applets

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0x, 3.0, 3.1, 3.2

  • Microsoft® Visual J++®, versions 1.0, 1.1

SUMMARY

How does the Msdev.exe in Visual J++ relax the security in Microsoft® Internet Explorer so that my applet can run outside the Java sandbox, despite the fact that it is not in a signed .cab file?

MORE INFORMATION

In the Microsoft® virtual machine (Microsoft VM), which is included with Internet Explorer 3.x and 4.0x, only trusted class files can access resources outside the Java sandbox. Class files from digitally signed .cab files are trusted. If the HTML file is run from Microsoft® Developer Studio®, the class files are also trusted. This can be very helpful during applet development. However, to deliver your applet to other users, you must place them in a signed .cab file.

When executing or debugging a Java applet from Developer Studio, the security restrictions in Internet Explorer are relaxed for quick and easy testing. MSDEV prepends the project path to the CLASSPATH that is used by Internet Explorer. This gives the classes trusted status.

Applets outside of MSDEV must be cabbed and signed in order to run in Internet Explorer without the sandbox restrictions. One of the references below is a FAQ about cabbing and signing.

Note All trusted applets (including those running under Developer Studio) running under the Microsoft VM (version 2252 or higher) included with either the SDK 2.0x for Java or Internet Explorer 4.0x have additional restrictions (please see references below).

REFERENCES

For additional information on making your Java code trusted in Microsoft Internet Explorer, please refer to the following Knowledge Base article:

Q193877 HOWTO: Making your Java Code Trusted in Internet Explorer

For more information on .cab signing, please see the SDK for Java documentation and the following article in the Microsoft Knowledge Base:

Q168941 INFO: Frequently Asked Questions for .cab Files

For more information on additional security restrictions for the Microsoft VM (version 2252 or higher) included with either the SDK for Java or Internet Explorer 4.0x, please see the following article in the Microsoft Knowledge Base:

Q175622 PRB: SecurityExceptionEx Exception Running a Java Applet

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q181374 INFO Related Component Download Articles

 Microsoft SDK for Java

Q181374 INFO: Related Component Download Articles

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® Visual Studio® 97

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer versions 4.0, 4.01 for Microsoft® Windows NT® 4.0

  • Microsoft® Internet Explorer versions 4.0, 4.01 for Microsoft® Windows® 95

SUMMARY

This article illustrates where to find more information about .cab files, DUBUILD, component download technology, and Java trust-based security.

MORE INFORMATION

For more information visit The MSDN Web Workshop and read "Downloading Code on the Web":

http://msdn.microsoft.com/workshop/component/downcode.asp This link takes you to a site on microsoft.com

For additional information, please see the following articles in the Microsoft Knowledge Base:

Q193877 HOWTO: Making your Java Code Trusted in Internet Explorer

Q168941 INFO: Frequently Asked Questions for .cab Files

Q177178 PRB: Unable to Sign the Cabfile When Running Signcode

Q176810 HOWTO: Manually Modify and Rebuild .cab Files

Q177159 INFO: Support for Multiple CABs or JARs in the Same APPLET Tag

Q163954 PRB: SignCode Returns "Unable to Sign the Program 0x80070057

Q179652 HOWTO: Deploying Java in Internet Explorer 4.0 and Netscape 4.0

Q177160 HOWTO: Dynamically adding a Java Package to the Classpath

Q175622 PRB: SecurityExceptionEx Exception Running a Java Applet

Microsoft® ActiveX® Software Development Kit (SDK):

http://msdn.microsoft.com/workshop/misc/activexsdk/default.asp This link takes you to a site on microsoft.com

See the following topics in the Microsoft SDK for Java:

  • Cabarc

  • Signing a Cabinet File with Java Permissions Using Signcode

  • Creating and Using Distribution Units

  • Package Management Overview

See the Microsoft Internet Component Download Overview:

http://msdn.microsoft.com/workshop/delivery/msicd/reference/reference.asp This link takes you to a site on microsoft.com

See Trust-Based Security for Java:

http://www.microsoft.com/Java/security/default.htm This link takes you to a site on microsoft.com

Additional query words:

cab dubuild security download


FAQ KB Articles Overview

The following Java-related FAQ Knowledge Base (KB) Articles are included in the Microsoft SDK for Java.

Q168942: Frequently Asked Questions About the Microsoft SDK for Java


Q168942 Frequently Asked Questions About the Microsoft SDK for Java

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.2

SUMMARY

This article covers some of the Frequently Asked Questions (FAQ) about the Microsoft SDK for Java. For other Java related FAQs, search the Web at:

http://support.microsoft.com/support This link takes you to a site on microsoft.com for JAVA and FAQ.

MORE INFORMATION

Q. 1. When running the JDBC sample, I get java.sql.SQLException: -7ffbfeee (80040112h).

A. Download the two files located under the "ActiveX Data Objects (ADO) version 1.0" section of http://msdn.microsoft.com/downloads/default.asp?MSCOMTB=ICP_DOWNLOADS This link takes you to a site on microsoft.com.

  • Microsoft ActiveX Data Objects 1.0 DLL (221k)

  • Microsoft ActiveX Data Objects 1.0 Supporting Error DLL (16k)

Q. 2. How does the Msdev.exe, in Microsoft® Visual J++® relax the security in Microsoft® Internet Explorer so that my applet can run outside the Java sandbox, despite the fact that it is not in a signed .cab file?

A. In the Microsoft VM that is included with Internet Explorer 3.x, only trusted class files can access resources outside the Java sandbox. Class files from digitally signed .cab files are trusted. If the HTML file is run from Microsoft® Developer Studio® (MSDEV), the class files are also trusted. This can be very helpful during applet development. However, to deliver your applet to other users, you must place them in a signed .cab file.

When executing or debugging a Java applet from MSDEV, the security restrictions in Internet Explorer are relaxed for quick and easy testing. MSDEV prepends the project path to the CLASSPATH environment variable that is used by Internet Explorer. This gives the classes trusted status.

Q. 3. Why does InetAddress.getLocalHost() return localhost/127.0.0.1 in my applet?

A. An untrusted applet isn't allowed to get the real localhost IP address because it opens various types of network attacks. If the Java libs detect an untrusted applet, then they will return the loopback address (127.0.0.1).

JDK 1.02's/1.1's appletviewer will do the same thing unless you've changed the "network access" property in the appletviewer to "unrestricted."

Q. 4. Is it possible for an applet to read a file from my Web server? If so, how?

A. The class below shows how to read a text file named poem.txt from the server.

Note Place the .htm and .class files in the same directory on the Web server along with a text file named poem.txt with at least one line of text:

import java.io.*;
import java.net.*;
import java.applet.*;
import java.awt.*;
   class ReadFile extends Applet {
      public void start () {
         try {
            URL u2 = new URL(getCodeBase(),"poem.txt");
            DataInputStream d = new DataInputStream(u2.openStream());
            String s5 = d.readLine();
            add(new Label(s5));
         }
         catch (Exception e) {
            System.out.println("Error: " + e.toString());
         }
      }
   }

Q. 5. What are common causes of the "Failed to create object" message when trying to instantiate a COM object written in Java?

A. Here are some common causes:

  • Failing to have the Java class in the CLASSPATH.

  • Failing to declare your Java method as public.

  • Failing to register the class file (using javareg.exe).

  • Using an old version of the Microsoft VM in some cases (for example, if you are attempting to use CreateObject). Install the latest Microsoft VM from http://www.microsoft.com/java This link takes you to a site on microsoft.com.

  • Missing required steps in the process. Follow the steps in the Visual J++ sample named COMCALLINGJAVA.

Q. 6. When I have an applet in a <FORM>, it doesn't submit any information to the server. How can I get the applet to submit its information?

A. The applet doesn't submit any information because the information a user would want to submit is specific to the applet. For example, an applet that shows images may want to submit the currently displayed image number, while an applet that displays a clock may want to submit the GMT time. It is up to the programmer to write the methods to submit the applet. The five steps below show one way you might implement submitting an applet:

  1. Create an applet with a public function that returns the information you want to submit: (For the first example above, you would return the image number.)
       public int getCurrentImage() {
      return m_nCurrImage;
   }
  2. Create a Web page with an applet inside your form.

  3. Create a hidden field in the <FORM>, where your applet will submit its data.

  4. Write a script function, like processApplet in the example below, to populate the hidden field by calling the public functions of your applet.

  5. Set your submit button's onClick function to call the script function you wrote in step 4.

Here is the finished product:

         <form action="/scripts/info.dll" method=GET name="myForm" >
         <applet code=AppletInForm.class id=myapplet
          width=320 height=240 >
         </applet>
         <input type=hidden name="appletImage">
         <script language=JScript>
           function processApplet() {
   parent.myForm.appletImage.value=document.myForm.myapplet.getCurrentImage();
           alert("Sending form: image="+parent.myForm.appletImage.value+"
   user="+parent.myForm.Username.value);
           }
         </script>
         <br>
         Username:<input type=text name="Username"><br>
         <input type=submit value="Please send me the above picture."
          language="JScript" onClick="processApplet();">
         </form>

Q. 7. How can I get showDocument to display a URL, when the URL protocol isn't supported by Java (for example FTP)?

A. The URL class verifies Java protocol support by calling the protocol's Handler class. The four steps below show how to add a protocol and demonstrates how to make the call to showDocument:

  1. Create a package to implement the protocol; for example:
    .\sun\net\www\protocol\ftp
  2. Implement the Handler class in the sun.net.www.protocol.{protocol-name} package. For example:
    .\sun\net\www\protocol\ftp\Handler.java.
package sun.net.www.protocol.FTP;
import java.net.URL;
import java.net.URLConnection;
import java.net.URLStreamHandler;
public class Handler extends URLStreamHandler {
public synchronized URLConnection openConnection(URL u) {
return new FTPURLConnection(u);
   }
}
  3. Implement any functions your Handler class uses:
    package sun.net.www.protocol.FTP;
import java.io.IOException;
public class FTPURLConnection extends sun.net.www.URLConnection {
FTPURLConnection(java.net.URL u) {
super(u);
    }
public void connect() throws IOException {
throw new IOException("FTP doesn't support connect().");
   }
}
  4. Create the URL and call the showDocument function:
    import java.net.*;
public class FTPTest extends java.applet.Applet {
public void init() {
add(new java.awt.Button("Click to open FTP session."));
}
public boolean action(java.awt.Event  evt, Object  what) {
try {URL u=new URL("ftp://ftp.microsoft.com");
getAppletContext().showDocument(u,"FTPFrame");
} catch (Exception e) {
showStatus(e.toString());
e.printStackTrace();
}
return true;
}
}

Q. 8. What steps must be followed to use a Java class from a Microsoft® Active Server Page (ASP)?

A. First, you must install build 1257 or later of the Microsoft VM or else install the Microsoft SDK for Java 1.5. Then, follow these steps:

  1. Create your Java class. For example, here is a class in a file called simple.java:
    class Simple
{
int SimpleFn ( int x )
{
return x * 2;
}
}
  2. From the command line or from MSDEV, compile the .java file into a .class file; for example:

    jvc simple.java

  3. Copy the resulting .class file into your java\trustlib directory; for example:

    copy simple.class \winnt\java\trustlib

  4. Register your Java class as a COM object using JavaReg; for example:

    javareg /register /class:simple /progid:Simple

    /class: argument is the name of the .class file in your trustlib directory.

    /progid: is the name that you will use to create your COM object.

    Now your Java class is registered as a COM object and ready to use from ASP.

  5. Create an .asp file in a HTTP shared directory on your machine. Be sure that the directory the file is in has EXECUTE access. You can check this in the Microsoft Internet Service Manager. A simple .asp file would look like this:
    <html>
<body>
<h1>Simple Test</h1>
The result from SIMPLE is:
<% Set SimpleObj = Server.CreateObject("Simple") %>
<% = SimpleObj.SimpleFn(5) %>
<hr>
</body>
</html>

That's it! Open your Web browser and point it at YOUR_MACHINE/simple.asp.

Q. 9. How do I redirect output from jview or wjview?

A. Unfortunately, there is not an option or registry setting for jview or wjview that enables Java logging. However, you can redirect the output when invoking an application like the following example:

jview main > javalog.txt

This works for both jview and wjview. Or, you could programmatically direct the output to a file or pipe by reassigning System.out. The following code, which works for jview/wjview and Internet Explorer, shows how this can be done:

      if
   ("true".equalsIgnoreCase(System.getProperty("com.ms.applet.enable.logging")
   )) {
      try {
         String logdir = System.getProperty("java.home");
         PrintStream ps = new PrintStream(new BufferedOutputStream(new
                              FileOutputStream(new File(logdir,
                                               "javalog.txt"))), true);
         System.out = ps;           // comment line if using SDK 2.0x
   //    System.setOut(ps);         // uncomment line if using SDK 2.0x
         System.err = ps;           // comment line if using SDK 2.0x
   //    System.setErr(ps);         // uncomment line if using SDK 2.0x
      } catch (Exception e) {
         }
      }

The ability to alter the value of System.out and other system streams may be removed or changed in the future.

Q. 10. When I create an ActiveX control in Java and then call its methods, I get a java.lang.UnsatisfiedLinkError exception. Why can't I call the methods?

A. For the Microsoft VM build 1518:

The problem is that applets aren't ActiveX containers and therefore cannot host ActiveX controls. The call to new myActiveXControl(); doesn't make sense because there is no container to host the control. You should use an <OBJECT> tag in your HTML file, and then pass this object reference to your applet. For an example of how this is done, see the OLEControls sample in the Microsoft Visual J++ samples documentation.

For the Microsoft VM build 2057 (SDK 2.0x):

You need to use the AXComponent class, located in the com.ms.activeX package, to host your ActiveX control.

Q. 11. How do I get the SampleSelect JDBC-ODBC sample to work with the Northwind database that comes with Microsoft® Access?

A. An updated jdbcrel.htm has been placed in the sample pack that details the steps necessary to connect to the Northwind database. The sample pack can be obtained at http://www.microsoft.com/java This link takes you to a site on microsoft.com.

Q. 12. When I call show on a modal dialog, the Microsoft VM continues executing the code after the show call, even though I haven't dismissed the dialog yet. Is this a known bug?

A. This is a bug and has been fixed in the Microsoft VM that is provided in the SDK 2.0x (build 2057 of the Microsoft VM).

Q. 13. Why does System.getProperty("user.name") return null?

A. This is a bug and has been fixed in the Microsoft VM that is provided in the SDK 2.0x (build 2057 of the Microsoft VM).

Q. 14. How do I tell from my Java applet or application what version of the Microsoft VM is installed on the system?

A. Use the SystemVersionManager.getVMVersion static method in com.ms.util package to find the version number of the installed Microsoft VM. The BuildIncrement property will indicate the version the Microsoft VM:

   String build;
   build=SystemVersionManager.getVMVersion().getProperty("BuildIncrement");
   System.out.println("Using build "+build);

Q. 15. I am getting the error message "Security Exception: Couldn't connect to with origin from file ***" in my javalog.txt file.

A. This could be caused by changes to the AppletSecurity class, some of these restrictions have been loosened in build 1520 of the VM. This problem was occuring with build 1516 of the VM when loading an applet via a file URL.

For more information, please refer to the following article in the Microsoft Knowledge Base :

Q169815 : PRB: Security Exception when Launching an Applet with Images Build 1520 of the VM, that has a fix to the problem, can be obtained by navigating to http://www.microsoft.com/java/vm/dl_vm151.htm This link takes you to a site on microsoft.com.

Q. 16. How can I execute jview.exe without displaying a DOS box?

A. Use wjview.exe instead of jview.exe. Wjview can be found in the Microsoft SDK for Java.

Q. 17. How can I combine all of my Java application's classes into one executable file?

A. Use jexegen.exe to convert your Java classes into a Win32® application. The Win32 application will still require the Microsoft VM to be installed on the local machine.

Q. 18. Has the support for SafeArray been updated in the Microsoft VM?

A. Yes, see the documentation for the Microsoft SDK for Java 2.0x at http://www.microsoft.com/java/sdk/20/default.htm This link takes you to a site on microsoft.com and follow the link from Packages and Classes to the com.ms.com package then to Class Variant or Class SafeArray.

Q. 19. How do I install the developer version of Classes.zip for the SDK 2.0x?

A. Run the ClassD.exe from the %SDKDIR%\bin directory of the SDK 2.0x, then run javasrc.exe (installed by Visual J++ in the %Windir%\java\classes directory) to extract the Java files. If you do not have Visual J++, use a program that can unzip the *.java files from the Classes.zip file.

Note You may have to delete your old Classes.zip first.

Q. 20. How can I see messages that are printed using System.out.println. In Netscape Navigator, I can see these in the Java Console?

A. For the answer to this question, please see the following article in the Microsoft Knowledge Base:

Q177177 HOWTO: Enabling Messages Printed Using System.out.printIn

Q. 21. How can I enable the Java JIT compiler for my application?

A. If you have enabled JIT in Internet Explorer, your applications will also run in JIT compiler mode. To enable JIT in Internet Explorer choose View, Options, Advanced, Enable Java JIT compiler.

In the registry JIT can be enabled by setting the following to 0x00000001:

HKEY_Current_User\Software\Microsoft\Java VM\EnableJIT

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the Microsoft SDK for Java, see the following page on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


DOC KB Articles Overview

The following Java-related DOC Knowledge Base (KB) Articles are included in the Microsoft SDK for Java.

Q179000: DOC: Clspack's "/" Option Doesn't Work As Expected


Q179000 DOC Clspack's / Option Doesn't Work As Expected

 Microsoft SDK for Java

Q179000 DOC: Clspack's "/" Option Doesn't Work As Expected

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

Running clspack /auto or clspack /dump as mentioned in the SDK for Java documentation gives a syntax message instead of creating a Classes.zip file or writing to the specified output file.

MORE INFORMATION

The clspack utility does not process the slash character; you should use a hyphen character. Use -auto instead of /auto, and -dump instead of /dump.

Steps to Reproduce Behavior

If you run clspack /auto from the command line, it puts up message box as follows:

Usage:clspack<ZipFile> <PackageListFile>
or: clspack -dump <PackageListFile> to create a file listing all system packages
or: clspack -auto to place all packages in
%windir%\java\classes\classes.zip

The correct usage is clspack -auto, which will create the Classes.zip file.

REFERENCES

For more information on the clspack utility, please refer to the SDK for Java documentation available at the following Web site:

http://www.microsoft.com/java/sdk/ This link takes you to a site on microsoft.com

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

clspack auto dump separator slash


SAMPLE KB Articles Overview

The following Java-related SAMPLE Knowledge Base (KB) Articles are included in the Microsoft SDK for Java.

Q161706: SAMPLE: GCDJava.exe Integrates Native Methods in a Java App
Q169802: SAMPLE: Jword8.exe Demonstrates Automating Word 8.0 from Java
Q177162: FILE: JWindow Demonstrates How to call Win32 APIs from Java
Q231294: SAMPLE: SmartGC Uses an ATL Server to Trigger Java GC


Q161706 SAMPLE GCDJava.exe Integrates Native Methods in a Java App

 Microsoft SDK for Java

Q161706 SAMPLE: GCDJava.exe Integrates Native Methods in a Java App

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 1.5, 1.51, 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

The GCDJava.exe sample illustrates how to use native methods from a Java application. This sample contains two Java classes: NativeM and Main. In the NativeM class, you define a native method called ComputeGCD. In the Main class, you define the main function in which you instantiate an object of type NativeM to call the ComputeGCD method. The ComputeGCD method in the NativeM class is actually implemented in C language, and it calculates the greatest common factor (denominator) of two integers.

MORE INFORMATION

The following file is available for download from the Microsoft® Software Library:

Gcdjava.exe

(http://support.microsoft.com/download/support/mslfiles/Gcdjava.exe This link takes you to a site on microsoft.com.)

The GCDJAVA sample contains two parts: A Java project and a DLL project.

Following are the files included in the projects.

The Java project

  1. NativeM.java - contains the ComputeGCD native method. It also loads the DLL that contains the native method implementation.

  2. Main.java - the driver program that instantiates the native method class and calls the native method.

The DLL project

This project is named Native and it includes the following:

  • NativeM.h - the header file generated by msjavah; contains the native method declaration.

  • NativeM.c - contains the implementation for the native method.

  • Gcdjava.def - exports the native method.

To use native methods in Java, you need msjavah. Msjavah is a tool that is installed by the Microsoft SDK for Java, and is available at http://www.microsoft.com/java This link takes you to a site on microsoft.com. This tool helps you generate a header file from a Java class file. The header file generated by msjavah provides a function declaration of the native method. In this sample, it is the ComputeGCD method defined in the NativeM Java class. This header file can then be used in the native language project. In this sample, it is the DLL project in C.

The following steps give a short tutorial on how to use native methods in Java:

  1. Use Visual J++ to create a Java WorkSpace.

  2. Create a Java class. For example, name it NativeM, and declare a native method called ComputeGCD. (The method definition provides only the method signature and not the implementation for it.)

  3. Create another class that defines the main method. In this sample, we create a class named Main. In the main function, instantiate a NativeM class object and call ComputeGCD.

  4. Add the .java files to the project WorkSpace. Please refer to NativeM.java and Main.java in the GCDJAVA project directory.

  5. Build the project, or use jvc (Java compiler) to compile the Java code you wrote in step 2.

  6. Use msjavah.exe (this is the tool that you get from Microsoft SDK for Java available at http://www.microsoft.com/java This link takes you to a site on microsoft.com) to create the header file.

    Msjavah.exe is installed in the %SDKDIR%\Bin directory. It helps create a header file from the Java class (NativeM.java) you created in step 2. The header file defines a structure that represents the Java class on the native language side and provides a function declaration for the implementation of the native method defined in that class.

    Look at the header file NativeM.h to see what is added to this file. Notice that the Native.h is included in NativeM.h. Native.h is one of the header files from the Microsoft SDK for Java. It is located in the SDKJava\Include directory. You need to add this directory to your Microsoft® Developer Studio® (MSDEV) environment. See step 9 below.

  7. Implement the corresponding .c file. The implementation is a regular function that is integrated with your Java class. Please refer to NativeM.c file in the Native (the DLL project) project directory.

  8. Create a new DLL project and include the .h and .c files that you created in steps 6 and 7. Also create a .def file that exports the native method. Look at Gcdjava.def file in this sample.

    Note If you prefer to export functions using __declspect(dllexport) in your source code, you do not need the .def file.

  9. Make sure that you point the include files to %SDKDIR%\Include in Tools.Options.Directories.

  10. Build the DLL. Copy the resulting DLL to the Windows\System directory.

  11. Run the Main program using jview.

If the following exception appears, then you have a library path set in your environment, but the name of the directory where your library lives is not in the environment:

java.lang.UnsatisfiedLinkError

Or, if you get the following exception when trying to execute this sample under Microsoft® virtual machine (Microsoft VM) build 2252, or 2339, or later:

Error: java,lang.UnsatisfiedLinkError: native.dll cannot load because
RNIGetCompatibleVersion export not found (new behavior). Press any key
to continue.

This exception occurs because several enhancements have been made to the Raw Native Interface in the Microsoft SDK for Java versions 2.0x, which requires many RNI DLLs, designed for earlier versions of the Microsoft VM to be recompiled. To identify whether an RNI DLL is compatible with the current version of the Microsoft VM, it will call the RNI DLLs RNIGetCompatibleVersion export. RNI DLLs that do not export this API will not be loaded by the current Microsoft VM.

To fix this exception, make sure you export RNIGetCompatibleVersion in the Native.def file in the DLL project. Also include its implementation in the NativeM.c file in the same DLL project:

DWORD __cdecl RNIGetCompatibleVersion()
   {
      return RNIVER;    /* RNIVER is defined in Native.h */
   }

Rebuild the DLL. Copy the resulting DLL to the Windows\System directory.

Note It is also possible to access native code by creating COM objects that can be accessed via Java. There are several advantages to taking this approach:

  • By using the COM model, you make the interfacing to the Garbage Collection system transparent to the programmer. In contrast, Garbage Collection does not take place automatically when you use the Native Methods.

  • It is generally easier to reuse the COM objects in non-Java programs than native methods.

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the Microsoft SDK for Java, see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

Native Code SDK


Q169802 SAMPLE Jword8.exe Demonstrates Automating Word 8.0 from Java

 Microsoft SDK for Java

Q169802 SAMPLE: Jword8.exe Demonstrates Automating Word 8.0 from Java

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® virtual machine (Microsoft VM)

SUMMARY

The Jword8.exe sample illustrates how to automate Microsoft® Word 97 version 8.0 (MS Word) from a Java application. This sample shows how to invoke Word 97, make it visible, and open up an existing Word document. It also PrintPreviews the document and Prints it. It uses the Open, PrintPreview, and PrintOut methods of MS Word 97.

MORE INFORMATION

The following file is available for download from the Microsoft Software Library:

Jword8.exe

http://support.microsoft.com/download/support/mslfiles/Jword8.exe This link takes you to a site on microsoft.com.

After downloading the Jword8.exe file, extract the files into a new directory and ensure the files are named as seen in the Project Files in Jword8.exe section below.

Overview of Jword8.exe

This sample illustrates how to call a COM object like Word 97 from Java. It shows how you can invoke MS Word, make it visible, and open an existing MS Word document. It also PrintPreviews and Prints the document. It makes use of methods like Open, PrintPreview, and PrintOut, and properties like putVisible (or setVisible) of the MS Word Type Library.

How to Use Jword8.exe

  1. Using Visual J++, create a default Java Applet Wizard Applet or Application, or both.

  2. Run JavaTLB on "Microsoft Word 8.0 Object" – this creates a Java interface for the COM Object. The Java Type Library Wizard is a tool that reads type libraries from .tlb, .olb, .ocx, .dll, and .exe files and creates Java class files with information about the COM interfaces and methods. You need these class files for both compiling and running a Java project using COM components. If you are using JActiveX instead of JavaTLB, then you will need to build this sample using the latest jvc.exe that ships with the SDK for Java 2.0 and later. The file that contains the Word 8.0 interface information is msword8.olb.

  3. After you have created Java descriptions of COM components, the output window shows two useful types of information: the import statement and the Summary.txt notice. It displays the following Java import statement:
    import msword8.*;

    Copy this line of text and insert it into the beginning of any Java source file that uses the COM component. This has been done for you in this sample (see line 9 in JWord8.java). In the summary.txt line, you will note that there are no methods listed for any of the classes. Recall that when you call COM from Java, you use the class file to create the COM component, but you must use the interface file to access the COM component. Double-click the Summary.txt line to view that file in Microsoft® Developer Studio®.

  4. Refer to the public method called CallWord in the JWord8.java from the sample. This code shows how to use the methods and properties of the MS Word object. If you are using a machine with Microsoft® Office 97, you will need to change one line in the method CallWord as seen here:
    //   appWord.putVisible(true);
appWord.setVisible(true);
  5. In Developer Studio, build the applet.

  6. Using MS Word, create a new document. Add some text to it. Save the file as Hello.doc in your c:\temp directory. Exit MS Word.

  7. In Developer Studio, run the applet. If this is the first time you have run the applet, Developer Studio will prompt you for the name of the class. Type: JWord8. Alternatively, you can modify the APPLET tag in the HTML file to point to JWord8.class.

Security

COM components can get access to any system resources. As such, they are both very powerful and potentially very dangerous. In the Microsoft VM in Microsoft® Internet Explorer 3.x and higher, only trusted class files can use COM components. Class files from digitally signed .cab files are trusted.

If the HTML file is run from Microsoft Developer Studio, the class files are also trusted. This can be very helpful during applet development. However, to deliver your applet to other users, you must put it in a signed .cab file.

When it is run as an application, the class file must already be on your machine.

When it is run as an applet, the class file may be downloaded to your machine.

There is a potential security threat running downloaded software. To run a Java applet that uses COM components, the applet code must be trusted. For more information on trusted class files, see the Knowledge Base Article, HOWTO: Make Your Java Code Trusted in Internet Explorer.

Project Files in Jword8.exe

  • JWord8.java: the Java source code for the sample.

  • JWord8Frame.java: the Java source code for the sample as a standalone application.

  • JWord8.dsw: the project workspace file.

  • JWord8.dsp: the project file.

  • JWord8.html: the HTML for the sample applet.

REFERENCES

You can download the SDK for Java 2.0x at the following Web site:

http://www.microsoft.com/java This link takes you to a site on microsoft.com

For the latest Knowledge Base articles and other support information on VisualJ++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q177162 FILE JWindow Demonstrates How to call Win32 APIs from Java

 Microsoft SDK for Java

Q177162 FILE: JWindow Demonstrates How to call Win32 APIs from Java

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

The JWindow sample illustrates how to call Win32® APIs from a Java application. This sample contains a single class called Jwindow, which basically creates a Window by using the Win32 API CreateWindow and displays "Hello JWindow" in the client area by processing the WM_PAINT in the WndProc. This sample illustrates how to use the @dll.import directives to invoke a Win32 DLL function from Java, callbacks, and nested struct types.

MORE INFORMATION

The following file is available for download from the Microsoft Software Library:

JWindow.exe

http://support.microsoft.com/download/support/mslfiles/Jwindow.exe This link takes you to a site on microsoft.com

The JWINDOW sample contains JWindow.java, which calls the standard Win32 DLLs and illustrates how to use the @dll.import directives to invoke the DLL functions from Java.

To use Microsoft® J/Direct™, you need to have installed version 1.02.4337 or higher of the Microsoft compiler for Java (Jvc.exe) and the Microsoft® virtual machine (Microsoft VM) version 2252 or later. The compiler is available with the Microsoft SDK for Java version 2.0x or later. The Microsoft VM, however, is no longer included with the SDK for Java in versions 3.2 and later, and must be downloaded separately from the Developer Updates site.

When executing this Java application , if you encounter an UnsatisifiedLinkError, then check your version of the compiler. If your compiler does not support J/Direct, the Microsoft VM will attempt to link native methods using the Raw Native Interface and hence will not succeed.

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

J/Direct Win32 directives


Q231294 SAMPLE SmartGC Uses an ATL Server to Trigger Java GC

 Microsoft SDK for Java

Q231294 SAMPLE: SmartGC Uses an ATL Server to Trigger Java GC

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® Visual C++®, 32-bit Editions, version 6.0

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® Windows NT®, versions 4.0, 4.0 SP4

SUMMARY

Java applications can register a sink with the JVMmem ActiveX Template Library (ATL) server, which periodically monitors memory load. When a memory threshold is exceeded, the server fires a notification event to the Java application indicating that the Java garbage collector should be invoked.

SmartGC.exe provides a foundation for Java applications to more optimally control garbage collection. Since Java garbage collection is triggered by Virtual Memory usage, some applications may run more efficiently if garbage collection is triggered on available RAM or the process Working Set size.

MORE INFORMATION

The following file is available for download from the Microsoft Software Library:

SmartGC.exe

http://support.microsoft.com/download/support/mslfiles/SmartGC.exe This link takes you to a site on microsoft.com.

Release Date: Jun-8-1999

For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:

Q119591 How to Obtain Microsoft Support Files from Online Services

SmartGC Files | Size in Bytes
CCheckMem.h | 1866
CheckMem.cpp | 3779
CheckMem.h | 2193
CheckMem.rgs | 637
dlldata.c | 839
JVMmemMod.aps | 3736
JVMmemMod.cpp | 1970
JVMmemMod.def | 226
JVMmemMod.dsp | 13088
JVMmemMod.dsw | 541
JVMmemMod.h | 19900
JVMmemMod.idl | 2430
JVMmemMod.rc | 2861
JVMmemMod.tlb | 3376
JVMmemModCP.h | 917
JVMmemModps.def | 251
JVMmemModps.mk | 478
JVMmemMod_i.c | 1272
JVMmemMod_p.c | 21624
memory.pmc | 758
PSAPI.H | 4172
PSAPI.LIB | 19790
resource.h | 502
rm.cpp | 0
StdAfx.cpp | 315
StdAfx.h | 908

The following steps describe how to use SmartGC.exe.

  1. Build the ATL project. This creates and registers the JVMmem ATL DLL server.

  2. Open the Java project, select Add COM Wrapper from the Project menu.

  3. Select JVMmemMod 1.0 Type Library from the list of installed COM Components.

  4. Build the sample.

You will get better results if you run the sample outside the Visual J++ IDE; that is, from Explorer:

  1. Click the Create button a few times until the Current Available Physical Memory is at least 5 MB lower than the initial Available Physical Memory.

  2. Click Delete All. This will initialize the JVMmem server to monitor Available Physical Memory.

After about a minute the Object Cnt: should match the Vector Cnt: and the Current Working Set and Available Physical Memory should return near initial Levels.

Note All the memory statements in this article assume other applications are not consuming more memory while you run the sample test. Obviously, if you start several large applications, the current available memory will be lowered regardless of GC activity on the test sample.

The current available memory and current working set may take some time to return to initial levels, as Windows NT does not immediately trim the working set if there is no need for RAM.

Notice the program calls SetProcessWorkingSetSize in the constructor to encourage Windows NT to limit the maximum Working Set.

Use the following steps to test that the GC sink routine is actually forcing the freeing of memory and objects:

  1. Click the Stop Timer button. Notice it now changes to Start Timer.

  2. Create and delete several objects so the Object count is 30 but the Vector Count is zero. The memory and objects will not be garbage collected.

  3. After waiting until you are convinced that no garbage collection will take place, click Start Timer button. Within about a minute you should see the Object Count return to zero and corresponding memory freed.

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


BUG KB Articles Overview

The following Java-related BUG Knowledge Base (KB) Articles are included in the Microsoft SDK for Java.

Q177752: BUG: java.awt.TextArea Does Not Provide Shortcut Menus
Q180046: BUG: Internet Explorer Print Creates New Instance of Applet Class
Q188808: BUG: KEY_PRESSED Event Not Generated for Some Controls
Q189064: BUG: Java Applets That Use DirectAnimation Do Not Display
Q190301: BUG: java.awt.event.KeyListener.keyTyped Method Does Not Work
Q194772: BUG: SaveFileDialog.showDialog() Fails at Head of Empty if Block
Q195527: BUG: Protection Fault with Reserved System WNDCLASS Names
Q195528: BUG: WFC DataGrid Control Fails When Displaying a Binary Column
Q201484: BUG: Close Button Does Not Close Modeless AFC UIPropertyDialog
Q214780: BUG: Scrolling Over Applet in IE Causes Improper Painting
Q220592: BUG: PaintEvent.clipRect Does Not Return Clip Area Width/Height
Q221206: BUG: System.getProperty("user.home") Returns Java Home Directory


Q177752 BUG java.awt.TextArea Does Not Provide Shortcut Menus

 Microsoft SDK for Java

BUG: java.awt.TextArea Does Not Provide Shortcut Menus

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer (Programming), version 4.01

SYMPTOMS

The default right-click Shortcut menus that JDK1.1 provides for java.awt.TextArea are not seen with the Microsoft® virtual machine (Microsoft VM) provided in the SDK for Java 2.0 and later and Internet Explorer 4.0.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

MORE INFORMATION

Steps to Reproduce Behavior

Create a Java project and include the following class:

   import java.awt.*;
   public class Test
   {
      public static void main(String a[])
      {
         Frame f = new Frame();
         TextArea t = new TextArea();
         f.add(t, "Center");
         f.setSize(300,300);
         f.setVisible(true);
      }
   }

When you right-click the Frame, you do not see the Shortcut menus with the following options:

  • Undo

  • Cut

  • Copy

  • Paste

  • Delete

  • Select All

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

popup menus TextArea


Q180046 BUG Internet Explorer Print Creates New Instance of Applet Class

 Microsoft SDK for Java

Q180046 BUG: Internet Explorer Print Creates New Instance of Applet Class

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer (Programming) versions 4.0, 4.01

SYMPTOMS

When printing an HTML page in Microsoft Internet Explorer 4.x that contains a Java applet, Internet Explorer creates a new instance of the applet class to be printed. In other words, you see only the initial, default state of the applet on the resulting printout and any changes the user made from the default state of the applet are not printed.

RESOLUTION

Currently, there are no supported workarounds for this bug.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

MORE INFORMATION

To reproduce this behavior, the following example can be used:

  1. Copy the following HTML code to a file named SimpleApplet.html:
    <HTML>
   <TITLE>
   SimpleApplet
   </TITLE>
   <BODY>
   Simple Applet<BR>
   <APPLET
     CODE     = "SimpleApplet.class"
     WIDTH    = 400
     HEIGHT   = 300>
   </APPLET>
   </BODY>
   </HTML>
  2. Copy the following Java source to a file named SampleApplet.java:
    // SimpleApplet.java
   import java.awt.*;
   import java.applet.*;
public class SimpleApplet extends Applet {
TextField textfield = new TextField(30);
     Choice choice = new Choice();
public SimpleApplet() {
             System.err.println("SimpleApplet SimpleApplet() "+this);
     }
public void init() {
       System.err.println("SimpleApplet Applet.init() "+this);
choice.addItem("Option 1");
       choice.addItem("Option 2");
       this.add(textfield);
       this.add(choice);
       validate();
     }
public void start() {
         System.err.println("SimpleApplet Applet.start() "+this);
     }
public void stop() {
         System.err.println("SimpleApplet Applet.stop() "+this);
     }
public void destroy() {
         System.err.println("SimpleApplet Applet.destroy() "+this);
     }
public void finalize() {
         System.err.println("SimpleApplet Applet.finalize() "+this);
     }
   }
  3. Compile the SimpleApplet.java file using a Java compiler.

  4. Open the SimpletApplet.html file in Internet Explorer 4.x.

  5. Enter some text in the TextBox and set the Choice control to Option 2.

  6. Click Print on the File menu in Internet Explorer 4.x and notice that the printout does not contain the text entered or the nondefault option in the Choice control.

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

print instance applet


Q188808 BUG KEY_PRESSED Event Not Generated for Some Controls

 Microsoft SDK for Java

Q188808 BUG: KEY_PRESSED Event Not Generated for Some Controls

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Visual J++®, versions 1.0, 1.1

SYMPTOMS

Programs that try to respond to KEY_PRESSED events miss those events for certain keys and certain controls that use the 1.1 or 1.02 event model of the Java Development Kit (JDK) from Sun Microsystems Inc. For example, this problem occurs when trying to intercept a TAB inside a TextArea.

CAUSE

Certain controls do not generate KEY_PRESSED or ACTION_PRESSED events, or call the keyPressed method of a KeyListener, for certain keys.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Create a Java project and include the following class:
    import java.awt.*;
// To see JDK 1.1-style events, uncomment this line.
// import java.awt.event.*;
public class Testevent
{
   public static void main(String args[])
   {
      Frame f=new Frame();
      f.setLayout(new java.awt.BorderLayout());
      TextArea ta = new TextAreaEvents();
      f.add("Center", ta);
      f.setSize(320,200);
      f.setVisible(true);
      // To see JDK 1.1-style events, uncomment this line.
      // To see JDK 1.02-style events, leave it out.
      // ta.addKeyListener(new TestKeyListener());
   }
}
class TextAreaEvents extends TextArea
{
   public boolean handleEvent(Event e)
   {
      System.out.println(e);
      System.out.print(e.id==Event.KEY_PRESS? "KEY_PRESS":"");
      System.out.print(e.id==Event.KEY_RELEASE? "KEY_RELEASE":"");
      System.out.print(e.id==Event.KEY_ACTION? "KEY_ACTION":"");
      System.out.print(e.id==Event.KEY_ACTION_RELEASE?
                       "KEY_ACTION_RELEASE":"");
      System.out.println();
      return super.handleEvent(e);
   }
}
// To see JDK 1.1-style events uncomment the following class:
/*
class TestKeyListener implements KeyListener
{
   public void keyPressed(KeyEvent e)
   {
     System.out.println("Listener -- pressed: "+e);
   }
   public void keyTyped(KeyEvent e)
   {
      System.out.println("Listener -- typed: "+e);
   }
   public void keyReleased(KeyEvent e)
   {
      System.out.println("Listener -- released: "+e);
   }
}
/* End of block. */
  2. Build and execute the above Java class. You will notice that the TextArea control does not generate KEY_PRESSED events for the TAB key.

Other Affected Keys

You will notice that the following controls do not create KEY_PRESSED or ACTION_PRESSED events, or call keyPressed, for the following keys:

Button | SPACE, ENTER
Choice | SPACE, ENTER, HOME, END, PGUP, PGDOWN, ARROWUP, ARROWLEFT, ARROWRIGHT, ARROWDOWN
Checkbox | SPACE, ENTER
List | SPACE, ENTER, HOME, END, PGUP, PGDOWN, ARROWUP, ARROWLEFT, ARROWRIGHT, ARROWDOWN
TextArea | TAB, PGUP, PGDOWN

Additional query words:

tab key-pressed event textarea Component


Q189064 BUG Java Applets That Use DirectAnimation Do Not Display

 Microsoft SDK for Java

Q189064 BUG: Java Applets That Use DirectAnimation Do Not Display

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer (Programming) version 4.01

SYMPTOMS

Java applets that use DirectAnimation will not display in Internet Explorer 4.0x with the Java Console enabled. To resolve this issue, clear the Java Console Enabled option on the Internet Options Advanced Tab. After this, you will need to restart Internet Explorer, and then you will see your DirectAnimation applets appear.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

Additional query words:

directAnimation console


Q190301 BUG java.awt.event.KeyListener.keyTyped Method Does Not Work

 Microsoft SDK for Java

Q190301 BUG: java.awt.event.KeyListener.keyTyped Method Does Not Work

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer (Programming) version 4.01

SYMPTOMS

The methods java.awt.event.KeyEvent.setKeyChar and java.awt.event.KeyEvent.consume have no effect on the AWT control when called from within the java.awt.event.KeyListener.keyTyped method.

RESOLUTION

The workaround is to move the event handling from the keyTyped method to the keyPressed method.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Create a Java project and paste the following code into a file called TestKeyTyped.java:
    import java.applet.*;
import java.awt.*;
import java.awt.event.*;
public class TestKeyTyped extends Applet
{
   TestPanel myTestPanel;
   public void init()
   {
      myTestPanel = new TestPanel();
      add(myTestPanel);
   }
}
class TestPanel extends Panel implements KeyListener
{
   TextArea myTextArea;
   TestPanel()
   {
     setLayout(new BorderLayout());
     add("West", new Label("Lower case \'a\' should change to upper "
       + "case \'A\' and \'%\' should be consumed:"));
     myTextArea = new TextArea(1, 25);
     add("Center", myTextArea);
     myTextArea.addKeyListener(this);
   }
   public void keyTyped(KeyEvent e)
   {
      char ch = e.getKeyChar();
      if (ch == 'a')
      {
         e.setKeyChar('A');   // Bug: Has no effect within
                              // keyTyped
      }
      else if (ch == '%')
      {
         e.consume();         // Bug: Has no effect
                              // within keyTyped
      }
      else
      {
         e.setKeyChar(ch);    // Bug: Has no effect within
                              // keyTyped
      }
      System.out.println("Modified event to be: "+e+
                          " Consumed:"+e.isConsumed());
    }
    public void keyPressed(KeyEvent e)
   {
      // WORKAROUND
      // Cutting the above code from the keyTyped method
      // and pasting it here will cause the setKeyChar and
      // consume calls to work.
  }
   public void keyReleased(KeyEvent e)
   {
   }
}
  2. Copy the following text into a file called TestKeyTyped.html:
    <applet
name="TestKeyTyped"
code="TestKeyTyped"
width="600"
height="50"
align="Top">
</applet>
  3. Build the project and execute it with the Internet Explorer browser. The correct behavior when running this applet is for any "a" typed in the text area to be converted to "A" before being displayed and for any "%" typed in the text area to be consumed without being displayed on the screen. This does not work due to the bug mentioned above.

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site.

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

KeyListener keyTyped KeyEvent TextArea setKeyChar consume


Q194772 BUG SaveFileDialog.showDialog() Fails at Head of Empty if Block

 Microsoft SDK for Java

Q194772 BUG: SaveFileDialog.showDialog() Fails at Head of Empty if Block

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

The Save File dialog box does not appear when a SaveFileDialog.showDialog call is placed in the conditional expression of an if statement that is followed by an empty if code block.

RESOLUTION

Place a line of code such as the following in the if block or following the if statement:

if(...)
   int localint = 0;
-or-
if(...) {
   int localint = 0;
}

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article. This bug was corrected in Microsoft virtual machines 3165 and later.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Save and compile the following code.

  2. Uncomment int localint = 0; to see the Save File dialog box.

  3. Leave int localint = 0; commented to reproduce the behavior.
    import com.ms.wfc.ui.*;
import com.ms.win32.*;
public class SFDialogTest
{
public static void main(String args[]) {
SaveFileDialog sfd = new SaveFileDialog();
     if (sfd.showDialog() == DialogResult.OK) {
     //int localint = 0;
     }
    String message = "SaveFileDialog should have been shown by now.";
    message += "\r\n";
    message += "If not, Uncomment the \"int localint = 0;\" line ";
    message += "to make it work.";
    User32.MessageBox(0,
    message,
    "Message Box",
    MessageBox.OK);
   }
}

REFERENCES

For additional information regarding Microsoft® Visual J++® 6.0, visit the following Web site:

http://msdn.microsoft.com/visualj/ This link takes you to a site on microsoft.com


Q195527 BUG Protection Fault with Reserved System WNDCLASS Names

 Microsoft SDK for Java

Q195527 BUG: Protection Fault with Reserved System WNDCLASS Names

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, versions 3.1, 3.2

SYMPTOMS

When sub-classing a pre-defined Win32® Window class by calling CreateHandle(CreateParams) in Windows Foundation Classes (WFC), certain reserved system Window classes may cause one of the following error messages. This occurs if the param field of CreateParams is not set correctly, or the WM_CREATE message is not passed on to defWndProc, or if other particulars are not met that are similarly required when sub-classing predefined system window classes in traditional windows programming:

Access violation, General Protection Fault, or java.lang.UnknownError:
Exception 0xc0000005 occurred in native code at 0x77e83564

RESOLUTION

Rather than subclassing in this manner, extend the WFC Java class that corresponds to the reserved system Window class that you want to subclass. Or, be sure that the required Windows protocols are followed when subclassing with createHandle, such as passing WM_CREATE on to defWndProc, or setting the CreateParam.param member to either null or to refer to an instance of the required STRUCT declared with the @dll.struct compiler directive as described in the WFC createHandle documentation.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

MORE INFORMATION

Steps to Reproduce Behavior

---------------------------

  1. Compile and run the following code.

  2. Click the button.

  3. This will be followed by a dialog box saying an exception or illegal operation has occurred. For example: java.lang.UnknownError: Exception 0xc0000005 occurred in native code at 0xSomeAddr.
   import com.ms.wfc.app.*;
   import com.ms.wfc.core.*;
   import com.ms.wfc.ui.*;
   import com.ms.wfc.html.*;
   import com.ms.win32.*;
   /**
    * This class can take a variable number of parameters on the command
    * line. Program execution begins with the main() method. The class
    * constructor is not invoked unless an object of type 'Form1' is
    * created in the main() method.
    */
   public class Form1 extends Form
   {
      public Form1()
      {
         // Required for Visual J++ Form Designer support
         initForm();
         // TODO: Add any constructor code after initForm call
      }
      /**
       * Form1 overrides dispose so it can clean up the
       * component list.
       */
      public void dispose()
      {
         super.dispose();
         components.dispose();
      }
      private void button1_click(Object source, Event e)
      {
         CreateParams cp = new CreateParams();
         cp.className = "MDICLIENT";
         // Uncomment this next line to correct the problem
         // cp.param = new CLIENTCREATESTRUCT(0, 1);
         Window w = new Window();
         w.createHandle(cp);
      }
      /**
       * NOTE: The following code is required by the Visual J++ form
       * designer.  It can be modified using the form editor.  Do not
       * modify it using the code editor.
       */
      Container components = new Container();
      Button button1 = new Button();
      private void initForm()
      {
         this.setText("Form1");
         this.setAutoScaleBaseSize(new Point(5, 13));
         this.setClientSize(new Point(292, 273));
         button1.setLocation(new Point(56, 72));
         button1.setSize(new Point(168, 80));
         button1.setTabIndex(0);
         button1.setText("Create MDIClient Window Class");
         button1.addOnClick(new EventHandler(this.button1_click));
         this.setNewControls(new Control[] {
                             button1});
      }
      /**
       * The main entry point for the application.
       *
       * @param args Array of parameters passed to the application
       * via the command line.
       */
      public static void main(String args[])
      {
         Application.run(new Form1());
      }
   }

REFERENCES

For additional information about getting an Unhandled Exception when using a system class name such as LISTBOX, please see the following article in the Microsoft Knowledge Base:

Q195160 PRB: Wjview.exe Causes Unhandled Exception on Handle Creation


Q195528 BUG WFC DataGrid Control Fails When Displaying a Binary Column

 Microsoft SDK for Java

Q195528 BUG: WFC DataGrid Control Fails When Displaying a Binary Column

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, versions 3.1, 3.2

SYMPTOMS

An attempt to display a binary field in a Windows Foundation Classes (WFC) DataGrid control may cause an Application Error.

CAUSE

An underlying call to field.getString fails.

RESOLUTION

Avoid using the DataGrid control to display binary data, if possible.

If you are writing code that directly manipulates binary fields, use field.getValue instead of field.toString.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Using Visual J++, create a new empty project. Add a new WFC Form to the project.

  2. Add a DataSource to the Form by dragging a DataSource control over from the Toolbox.

  3. In the Properties pane for the DataSource, set the connectionString property by selecting that field and clicking the ... button. Select a database that contains a binary field. You can follow these steps if you have Microsoft® Access and the Northwind sample database installed.
    1. A Data Link Properties dialog box will appear. Click the Provider tab and select Microsoft Jet 3.51 OLE DB Provider.

    2. Click Next or the Connection tab. Type in the path to the Northwind database, or click the ... button to browse for it. The Northwind database is commonly located at C:\ProgramFiles\MicrosoftOffice\Office\Samples\Northwind.mdb.

    3. Click the Test Connection button to test the data source.

    4. Click OK.
  4. In Properties for the DataSource, select the commandText property and type in a command string that describes a table with binary data in at least one column. If you are using the Northwind database, you can type in select * from employees.

  5. In Properties for the DataSource, select the cursorLocation property and choose the value Server.

  6. Add a DataGrid control to the Form by selecting the DataGrid control from the Toolbox and dragging out its shape on the Form.

  7. In the Properties pane for the DataGrid, select the dataSource property and choose the DataSource you added in step 2.

    Note Data from the database will appear in the DataGrid, and Microsoft® Visual Studio® may stop if a field with binary data is visible at this point.

  8. Run the application.

  9. Scroll the DataGrid to reveal the column with binary data. If you are using the Northwind database as described above, this will be the Photo column.

    At this point, the program attempts to access memory that is invalid. You will see a dialog box similar to the following:

    WJView.exe - Application Error The instruction at "0x7c01254d"
referenced memory at "0x056f2000". The memory could not be "read".
Click on OK to terminate the application Click on CANCEL to debug the
application."

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q201484 BUG Close Button Does Not Close Modeless AFC UIPropertyDialog

 Microsoft SDK for Java

Q201484 BUG: Close Button Does Not Close Modeless AFC UIPropertyDialog

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, version 3.2

SYMPTOMS

If a Java application or applet displays a modeless Application Foundation Classes (AFC) Property Sheet dialog box, the Close button on that dialog box has no effect. You must click OK or Cancel to close the dialog box.

RESOLUTION

You can avoid this behavior if you create the Property Sheet dialog box as a modal dialog box.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

MORE INFORMATION

When the Property Sheet dialog box is modeless and you click the Close button, it also does not result in a call to doApplyAction, doCancelAction, or doOKAction.

Steps to Reproduce Behavior

  1. Enter and compile the following program:
    // Propertydialog.java
         import java.awt.*;
         import com.ms.ui.*;
         import com.ms.ui.event.*;
         import java.awt.event.*;
         import com.ms.fx.*;
         import java.text.*;
class propertydialog extends UIFrame implements IUIActionListener
         {
             public static void main(String args[])
             {
               try {
                   propertydialog app = new propertydialog();
app.resize(200, 100);
                  app.show();
               }
               catch (Exception e) {
                  e.printStackTrace();
               }
             }
public boolean handleEvent(Event e)
             {
                 if (e.id == Event.WINDOW_DESTROY)
                     System.exit(0);
return (super.handleEvent(e));
             }
public propertydialog()
             {
               setLayout(new UIFlowLayout());
               UIPushButton pb = new
                  UIPushButton("Create PropertyDialog",UIPushButton.RAISED);
               pb.addActionListener(this);
               add(pb);
            }
public void createDialog()
            {
               UIFrame frame = new UIFrame("Dialog");
               UIPropertyDialog dialog = new myDialog(frame, false);
               myPage sheet = new myPage(dialog);
dialog.addPage("PropertySheet1",sheet);
               System.out.println("Displaying Property Sheet");
               Object o = dialog.display();
               System.out.println("Property sheet returned " + o);
            }
public void actionPerformed(UIActionEvent event)
            {
               createDialog();
            }
}
class myDialog extends UIPropertyDialog
         {
            public myDialog(UIFrame f, boolean modal) {
               super(f, "UIPropertyDialog", modal, UIPropertyDialog.SMALL);
            }
public boolean doApplyAction(Event e, Object o) {
               System.out.println("Doing ApplyAction");
               return true;
            }
public boolean doCancelAction(Event e, Object o) {
               System.out.println("Doing CancelAction");
               return true;
            }
public boolean doOKAction(Event e, Object o) {
               System.out.println("Doing OKAction");
               return true;
            }
}
class myPage extends UIPropertyPage
         {
            myPage(UIPropertyDialog dialog)
            {
               super(dialog);
            }
public boolean isApplyable() {
               return true;
            }
public boolean addContent()
            {
add(new UIText("This is UIPropertySheet"));
return true;
            }
         }
  2. Run it using jview propertydialog and click Create PropertyDialog.

  3. Click the Close button on the Property Sheet dialog box.

    RESULT: It does not close.

  4. Click OK or Cancel to close the dialog box.

REFERENCES

The Application Foundation Classes are documented as part of the SDK for Java on the following Web site:

http://www.microsoft.com/java/afc This link takes you to a site on microsoft.com

UIPropertyDialog class is documented on the same Web site

Additional query words:

AFC, UIPropertyDialog


Q214780 BUG Scrolling Over Applet in IE Causes Improper Painting

 Microsoft SDK for Java

Q214780 BUG: Scrolling Over Applet in IE Causes Improper Painting

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 3.1, 3.2

  • Microsoft® Visual J++®, version 6.0

SYMPTOMS

When you scroll up and down over a Java applet in a Web page, the components in the applet or the applet itself are repainted incorrectly and appear jumbled or corrupted.

CAUSE

The cause of this problem is not yet known. However, the behavior seems to be much more pronounced when the Use smooth scrolling check box is selected in Microsoft® Internet Explorer. To see the Use smooth scrolling check box in Internet Explorer, go to the View menu, click Internet Options, and click the Advanced tab.

RESOLUTION

Clear the Use smooth scrolling check box in Internet Explorer to eliminate, or significantly reduce, the occurrence of this problem.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

MORE INFORMATION

Steps to Reproduce Behavior

Compile and run the following code:

JAVA SOURCE:

   import java.awt.*;
   import java.applet.*;
   public class PaintApplet extends Applet
   {
     TestPanel tp;
     public void init()
     {
        setForeground(Color.cyan);
        setBackground(Color.blue.darker());
        setLayout(new BorderLayout());
        tp = new TestPanel();
        add(tp, "Center");
     }
   }
   class TestPanel extends Panel
   {
     public void paint(Graphics g)
     {
        Dimension d = getSize();
        int x = d.width/5;
        int y = d.height;
        for (int i = 0; i < x; i++)
        {
          g.drawLine(i*8, 0, 0, y);
        }
     }
   }

HTML SOURCE:

<HTML>
   <HEAD>
   <TITLE>Painting Problem Page</TITLE>
   </HEAD>
   <BODY>
     <applet
        code=PaintApplet.class
        name=PaintApplet
        width=220
        height=600 VIEWASTEXT>
     </applet>
   </BODY>
   </HTML>

RESULT: Scroll up and down over the applet using the Page Up and Page Down keys with the Use smooth scrolling check box selected in Internet Explorer. Notice how the lines drawn on the embedded panel become corrupted. This may take several tries because this problem occurs randomly.

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

AWTPkg


Q220592 BUG PaintEvent.clipRect Does Not Return Clip Area Width/Height

 Microsoft SDK for Java

Q220592 BUG: PaintEvent.clipRect Does Not Return Clip Area Width/Height

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, version 3.2

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

When you use the Windows Foundation Classes for Java PaintEvent class, the member variable called clipRect erroneously returns the lower-right corner of the clip area instead of the width and height of the clip area in its member variables "width" and "height".

RESOLUTION

Make sure that any code that uses clipRect also uses the member variables named "width" and "height" as if they were named "right" and "bottom", respectively.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

MORE INFORMATION

Steps to Reproduce Behavior

  1. In Visual J++ 6.0, create a new Windows Application project.

  2. Add a paint event handler by opening the Properties window, double-clicking the form to display the display the form's properties in the Properties window, opening the event list, and double-clicking the paint entry.

  3. Add System.out.println(e.clipRect); to the new method.

  4. Debug the application.

  5. Cover only the lower-right corner of the form with another window, such as Notepad.

  6. Click on the form to bring it to the front.

    RESULT: The output for a form that is 300 pixels wide and 275 pixels high should be like the following:

    {x=202,y=153,width=300,height=275}

    If the entire client area of the same form is repainted, you should see the following:

    {x=0,y=0,width=300,height=275}

Additional query words:

PaintEvent clipRect width height right bottom


Q221206 BUG System.getProperty("user.home") Returns Java Home Directory

 Microsoft SDK for Java

Q221206 BUG: System.getProperty("user.home") Returns Java Home Directory

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

According to the documentation, System.getProperty("user.home") should return a String containing the user's home directory. Instead, the Microsoft VM returns the Java home directory, which is also returned by a call to System.getProperty("java.home").

RESOLUTION

While there are no known pure Java workarounds, there are a couple of things to try using Win32® code. To get the user's home directory, you could do the following:

  • Use the USERPROFILE environment variable in Microsoft® Windows NT® to determine the user's home directory by making a J/Direct™ call to the Win32 API function GetEnvironmentVariable (For Microsoft® Windows® 9x users, require the user to set USERPROFILE on boot.)

  • Use Win32's GetWindowsDirectory and WFC's getUserName to find the user's home directory.

  • Use WFC's getUserName method to create a directory under "C:\A_KNOWN_DIRECTORY\[username]".

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.


FIX KB Articles Overview

The following Java-related FIX Knowledge Base (KB) Articles are included in the Microsoft SDK for Java.

Q177166: FIX: Jvc.exe Gives Ambiguity Error on Overloaded Methods
Q177751: FIX: java.text.DateFormat.parse() Throws a NullPointerException
Q177754: FIX: NoClassDefFoundError When a Valid Class Definition Exists
Q180057: FIX: Codebase URL Problems with <object> Tags
Q182623: FIX: PrintJob Output is Incorrect After First Page
Q184600: FIX: WebBrowser Events Not Being Received Inside Java
Q214760: FIX: TextField and TextArea Are Not Grayed Out
Q218595: FIX: Automation Object Not Being Released
Q222581: FIX: MSJAVAH Fatal Error: java.lang.UnsatisfiedLinkError
Q223351: FIX: Child Controls Not Properly Painted for setSelectedTab()
Q223355: FIX: WJView Hangs with CPU Usage at 100% Using 315x VMs
Q223358: FIX: Creating MDI Children in Parent's Constructor Causes Error
Q223362: FIX: WFC ActiveX Controls Do Not Fire Custom Events in VB
Q223363: FIX: Unhandled Exception When Hosting Java ActiveX Controls
Q223367: FIX: RegistryKey setValue() Fails Terminating Character on NT
Q233271: FIX: DateFormat Class Does Not Default to the System Time Zone
Q233359: FIX: JActiveX fails for COM Property Declared as IUnknown


Q177166 FIX Jvc.exe Gives Ambiguity Error on Overloaded Methods

 Microsoft SDK for Java

Q177166 FIX: Jvc.exe Gives Ambiguity Error on Overloaded Methods

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02

  • Microsoft® Visual J++®, versions 1.0, 1.1

SYMPTOMS

When using the new Java compiler provided in the Microsoft SDK for Java 2.0 (jvc.exe version 1.02.4337), compiling code with overloaded methods whose parameters are various combinations of double and long types gives the following error:

Ambig.java(14,5) : error J0079: Ambiguity between 'void Ambig.foo(double d, long l)' and 'void Ambig.foo(long l, double d)'

CAUSE

A bug in the Java Compiler (jvc.exe) produces this error when the overloaded method that takes two doubles appears in the code first and directly before the method that takes two longs.

RESOLUTION

To work around this problem, either move the method that takes two doubles to any point in the class after the method that takes two longs, or move the method that takes two longs anywhere in the code after the other overloaded methods.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in Microsoft® virtual machine (Microsoft VM) contained in the SDK for Java 3.0 and later.

MORE INFORMATION

To reproduce the problem, compile the following code:

public class Ambig
   {
      public static void main(String args[])
      {
         Ambig b = new Ambig();
b.foo((long)1, (double)2);
         b.foo((double)1, (long)2);
         b.foo(1,2);
         b.foo(1.5,2.5);
// pause for user to press return
         try{System.in.read();}catch(Exception e){}
      }
public void foo(double d, double d2)
      {
         System.out.println("Double = "+d+" Double2 = "+d2);
      }
public void foo(long l, long l2)
      {
         System.out.println("Long = "+l+" Long2 = "+l2);
      }
public void foo(long l, double d)
      {
         System.out.println("Long = "+l+" Double = "+d);
      }
public void foo(double d, long l)
      {
         System.out.println("Double = "+d+" Long = "+l);
      }
   }

You should see the following error:

Ambig.java(14,5) : error J0079: Ambiguity between
'void Ambig.foo(double d, long l)' and 'void Ambig.foo(long l, double d)'

To work around this problem, change the order of the overloaded methods to the following:

public void foo(long l, long l2)
   {
      System.out.println("Long = "+l+" Long2 = "+l2);
   }
public void foo(long l, double d)
   {
      System.out.println("Long = "+l+" Double = "+d);
   }
public void foo(double d, long l)
   {
      System.out.println("Double = "+d+" Long = "+l);
   }
public void foo(double d, double d2)
   {
      System.out.println("Double = "+d+" Double2 = "+d2);
   }

-or-

public void foo(double d, double d2)
   {
      System.out.println("Double = "+d+" Double2 = "+d2);
   }
public void foo(long l, double d)
   {
      System.out.println("Long = "+l+" Double = "+d);
   }
public void foo(double d, long l)
   {
      System.out.println("Double = "+d+" Long = "+l);
   }
public void foo(long l, long l2)
   {
      System.out.println("Long = "+l+" Long2 = "+l2);
   }

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, see the following page on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q177751 FIX java.text.DateFormat.parse() Throws a NullPointerException

 Microsoft SDK for Java

Q177751 FIX: java.text.DateFormat.parse() Throws a NullPointerException

The information in this article applies to:

  • Microsoft® SDK for Java, version 2.0x

  • Microsoft® Internet Explorer version 4.0x for Windows NT 4.0

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

When the parse method of the java.text.DateFormat cannot parse a date, the Microsoft VM incorrectly throws a NullPointerException error instead of a ParseException error.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in the Microsoft VM contained in the SDK for Java 3.0 and later.

MORE INFORMATION

To Reproduce Behavior

Create a Java project and include the following class:

   class Test
   {
      public static void main(String[] args)
      {

         {
            java.text.DateFormat Df;
            Df = java.text.DateFormat.getDateInstance();
            Df.parse("Foo");
            System.out.println ("Done.");
         }
         catch(Exception e)
         {
            System.err.println("caught exception");
            e.printStackTrace();
         }
      }
   }

java.text.DateFormat is a package that is included with JDK1.1. Build the above code with the JVC that is provided in the SDK2.0x for Java and execute. You will see that the VM throws a NullPointerException instead of ParseException as mentioned in the Documentation.

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

DateFormat parse exception


Q177754 FIX NoClassDefFoundError When a Valid Class Definition Exists

 Microsoft SDK for Java

Q177754 FIX: NoClassDefFoundError When a Valid Class Definition Exists

The information in this article applies to:

  • Microsoft® Internet Explorer version 4.0 for Microsoft® Windows NT® 4.0

  • Microsoft® Internet Explorer version 4.0 for Microsoft® Windows® 95

  • Microsoft® SDK for Java, version 2.0

Note The information in this article applies specifically to version 4.79.2252 of the Microsoft® virtual machine (Microsoft VM), which is included in the products listed at the beginning of this article.

SYMPTOMS

A Java applet or program that attempts to load certain valid Java classes may fail with a NoClassDefFoundError exception.

If the applet is running inside Internet Explorer, there may be no visible symptoms, except that the applet does not run properly. If Java Logging is enabled in Internet Explorer. however, the file Javalog.txt file, created in the Java subdirectory of the Windows directory, contains a log of the exception and a call stack. Here is a typical example of the exception:

java.lang.NoClassDefFoundError: COM/objectspace/jgl/HashMap

CAUSE

The Microsoft VM verifies that the .class file that defines each Java class is valid before loading it. Version 4.79.2252 erroneously decides that certain .class files are not valid, and, therefore, fails to load them. When it fails to find a valid definition for a class, the VM throws a NoClassDefFoundError exception.

RESOLUTION

Download and install the current Microsoft VM from the following Web site:

http://www.microsoft.com/java/download.htm This link takes you to a site on microsoft.com.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article. This bug was corrected in Microsoft VM, version 4.79.2334 and later.

MORE INFORMATION

One class that the Microsoft VM fails to validate is the HashMap class from ObjectSpace's JGL class library. It is possible to produce other .class files that the VM will fail to validate using a Java compiler, including Microsoft® Visual J++® or SDK 2.0 for Java.

To Reproduce Behavior

If you have JGL and SDK 2.0 for Java, the following program will exhibit this bug:

   import COM.objectspace.jgl.*;
   public class HashMapTest
   {
      public static void main (String args[])
      {
         HashMap    hm = new HashMap();
      }
   }

Version 4.79.2252 of the Microsoft VM throws a NoClassDefFoundError. Version 4.79.2334 of the VM executes this with no errors.

REFERENCES

JGL is manufactured by ObjectSpace, Inc., a vendor independent of Microsoft; we make no warranty, implied or otherwise, regarding this product's performance or reliability.

Further information about JGL can be found at the following Web site:

http://www.objectspace.com/

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

NoClassDefFoundError


Q180057 FIX Codebase URL Problems with OBJECT Tags

 Microsoft SDK for Java

Q180057 FIX: Codebase URL Problems with <OBJECT> Tags

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® Internet Explorer (Programming) versions 3.02, 4.0, 4.01, 4.01

SYMPTOMS

If an HTML file uses an <OBJECT> tag to include an applet, specifies a class library for that applet to use via the three useslibrary parameters, and there is no codebase parameter to completely specify the applet's codebase, the <OBJECT> tag will fail to load the library. If Java logging is enabled, the following message occurs in the Java log or the Java console:

USESLIBRARYCODEBASE, no base URL

The CODEBASE attribute of the <OBJECT> tag has no effect.

RESOLUTION

Specifying a fully qualified URL for the codebase via a codebase *parameter* enables the <OBJECT> tag to work as expected. If a fully qualified codebase URL is specified, then both the useslibrary install and the regular object loading operate successfully.

Note You must specify the codebase as a param; placing a codebase attribute inside the <OBJECT ...> block has no effect at present. For example:

   <object
   classid="java:MyApplet"
   height=240 width=320>
      <param name=codebase value=http://myserver/myfolder>
      <param name=useslibrary VALUE="MyPackageName">
      <param name=useslibrarycodebase VALUE="MyPackage.cab">
      <param name=useslibraryversion VALUE="1,0,0,1">
   </object>

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in the Microsoft VM contained in the SDK for Java 3.0 and later.

MORE INFORMATION

The codebase must be specified as a parameter, not as an attribute of the <OBJECT> tag, and it must fully specify the folder in which the applet classes and library .cab file reside.

REFERENCES

Further information about libraries can be found in the documentation for the Microsoft SDK for Java, version 2.01, at the following address:

http://www.microsoft.com/java/sdk/20/default.htm This link takes you to a site on microsoft.com.

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

codebase url object tags


Q182623 FIX PrintJob Output is Incorrect After First Page

 Microsoft SDK for Java

Q182623 FIX: PrintJob Output is Incorrect After First Page

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

When printing text or graphics from Java using java.awt.PrintJob, the output has different font sizes, line thickness, and other Graphics attributes on different pages even when the same Graphic attributes and fonts are used on all pages.

Also, subsequent pages do not reset the offset from a previous translate call. For example, if your paint routine calls gr.translate(10,10), then the first page printed starts at origin (10,10), the second page starts at origin (20,20) and so on.

CAUSE

This problem happens with some printer drivers depending on whether the driver resets state between pages.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in the Microsoft VM contained in the Microsoft® SDK for Java 3.0 and later.

MORE INFORMATION

To Reproduce the Font and Graphic Attribute Issue

Create a Java application and include the following class:

   import java.awt.*;
   import com.ms.ui.*;
   public class PrintFont extends UIFrame
   {
      public PrintFont()
      {
         PrintJob pj = getToolkit().getPrintJob(null, "Printer", null);
         if (pj != null)
         {
            for (int i=1; i<=3; i++)
            {
               Graphics pg = pj.getGraphics();
               if (pg != null)
               {
                  pg.setFont(new Font("TimesRoman", Font.PLAIN, 16));
                  pg.setColor(Color.black);
                  pg.drawRect(100, 100, 100, 100);
                  pg.drawString("Page " + i, 600, 900);
                  pg.drawString("TimesRoman", 500, 900);
               }
               System.out.println("Dispose");
               pg.dispose();
            }
            pj.end();
            System.out.println("End");
         }
       }
       public static void main(String args[])
      {
          UIFrame f = new PrintFont();
         System.exit(0);
      }
   }

A workaround for this problem is to select a different attribute (font/color) and do a drawString of an empty string, then select back in the desired attribute.

A workaround for the translation accumulation issue is to get your current translation and set the translation to the inverted values:

   try {
      com.ms.awt.GraphicsX gx = (com.ms.awt.GraphicsX) printGraphics;
      Point pt = gx.getTranslation();
      gx.translate(-pt.x, -pt.y);
   } catch (Exception e) {
   }

Additional query words:

print font


Q184600 FIX WebBrowser Events Not Being Received Inside Java

 Microsoft SDK for Java

Q184600 FIX: WebBrowser Events Not Being Received Inside Java

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02

SYMPTOMS

Attempting to call the following methods after hosting a WebBrowser control inside a Java application or applet fails:

   public void BeforeNavigate2(Object pDisp, Variant URL, Variant Flags,
                               ...);
   public void NewWindow2(Object[] ppDisp, boolean[] Cancel);

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in the Microsoft® virtual machine (Microsoft VM) contained in the SDK for Java 3.0, VM build 2829.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Install Microsoft® Internet Explorer 4.0x.

  2. Download SDK for Java version 2.0x from http://www.microsoft.com/java/ This link takes you to a site on microsoft.com.

  3. Load the sample JBrowser from the SDK-Java.20x/Samples directory.

  4. Modify JBrowser.Java to implement the following two methods:
   public void BeforeNavigate2(Object pDisp, Variant URL, Variant Flags,
                              Variant TargetFrameName, Variant PostData,
                              Variant Headers, boolean[] Cancel)
   {
        System.out.println("BeforeNavigate2");
   }
public void NewWindow2(Object[] ppDisp, boolean[] Cancel)
   {
      System.out.println("NewWindow2");
   }
  5. Build the JBrowser project using the JVC that ships with the SDK for Java.

  6. You will notice the output in the DOS window from which the JBrowser application is launched. Watch for specified events above:
    • Try navigating using the Open option on the File menu.

    • Try navigating to any site, then right-click, and click Open in the new window.
  7. The above mentioned events are not received.

REFERENCES

You can download all versions of the SDK for Java from the following Web site:

http://www.microsoft.com/java/ This link takes you to a site on microsoft.com

Additional query words:

WebBrowser events java


Q214760 FIX TextField and TextArea Are Not Grayed Out

 Microsoft SDK for Java

Q214760 FIX: TextField and TextArea Are Not Grayed Out

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 1.0, 1.5, 1.51, 2.0, 2.01, 2.02

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

When making a call to the Component.disable method for an AWT TextArea or TextField, the text in the component's client area should be grayed out, but it is not.

RESOLUTION

Upgrade to a version of the Microsoft VM with a build number equal to or higher than 2613. You can find the latest Microsoft VM version by going to http://www.microsoft.com/java/ This link takes you to a site on microsoft.com.

STATUS

Microsoft has confirmed this to be a problem in the Microsoft products listed at the beginning of this article.

This bug was corrected in Microsoft VM version 2613 for Visual J++ 6.0 Tech Preview 1.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Compile and run the following code. If the Microsoft VM you have was shipped with one of the products above, you will see that the text in the TextArea and TextField is not grayed out.

    If you have a version later than 2613 of the VM, you will see that the text is in fact grayed out as it should be.

    import java.awt.*;
public class CTATest extends Frame
{
  static CTATest app;
  public static void main(String[] args)
  {
    app = new CTATest();
    app.resize(400, 400);
    app.setLayout(new BorderLayout());

    TextArea ta = new TextArea();
    TextField tf = new TextField();
    app.add("North", ta);
    app.add("South", tf);

    ta.appendText("This String should be grayed out.");
    tf.setText("This String should be grayed out.");

    ta.disable();
    tf.disable();
    app.show();
  }

  public boolean handleEvent(Event e)
  {
    if (e.id == Event.WINDOW_DESTROY)
    {
      CTATest.app.dispose();
      System.exit(0);
      return true;
    }
    return false;
  }
}

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

AWTPkg, JVM


Q218595 FIX Automation Object Not Being Released

 Microsoft SDK for Java

Q218595 FIX: Automation Object Not Being Released

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM) Build 3165 and later

  • Microsoft® Visual J++®, versions 1.1, 6.0

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.0 Preview 1, 3.1

SYMPTOMS

When automating an Office product as an out-of-proc server, such as Microsoft® Excel or Microsoft® Word, even though the automation object has been released (through the use of ComLib.release()), its resources may not be freed and the Microsoft® Office product process may not exit after the Java program has exited. For more details on ComLib.release(), see the following article in the Microsoft Knowledge Base:

Q179062 PRB: COM Objects are not Being Released in Java

CAUSE

The actual proxy Interface pointer is on another Microsoft VM thread, waiting to be released, and may not get enough CPU time to make the call.

RESOLUTION

In some cases on more recent builds of the Microsoft VM, this workaround will fix the problem. Make a call to ComLib.release as usual, but then also include a call to System.gc and put the thread to sleep long enough for the object to be released. This problem has been fixed in build 3167 of the Microsoft VM.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in the Microsoft VM version 3167. Build 3167 is the build associated with the SDK for Java version 3.2. The Microsoft® Visual Studio® Service Pack 3 will also contain this fix in build 3176 of the Microsoft VM.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Compile and run the code listed below.

  2. Check the running processes list in the Task Manager by pressing CTRL+ALT+DEL.

  3. If the problem occurs, there will still be an Excel.exe process listed after the Java application has exited.

Note You will either need to add a COM wrapper in Visual J++ 6.0, or run JactiveX on the Excel object library to generate the wrapper classes required to run this sample. For more information on automating Excel, see the following article in the Microsoft Knowledge Base:

Q169796 HOWTO: Automate Excel from Java

   import excel8.*;
   import com.ms.com.*;
   import com.ms.win32.*;
   public class JExcel
   {
     _Application app = null;
     _Global global = null;
     Workbooks workbooks = null;
     _Workbook workbook = null;
     Sheets sheets = null;
     _Worksheet worksheet = null;
     String name = null;
     Variant vNoParam = null;
     Range range = null;

     int index = 0;
     public static void main(String args[])
     {
       new JExcel().go();
     }
     public void go()
     {
       try
       {
         global = (_Global) new Global();
         app = (_Application)global.getApplication();
         app.setVisible(0, true);
         workbooks = app.getWorkbooks();

         vNoParam = new Variant();
         vNoParam.noParam();
         workbook = workbooks.Add(vNoParam, 0);
         name = workbook.getName();
         User32.MessageBox(0, "Workbook Name:  " + name,
                           "Application Message" ,
                           0);

         sheets = workbook.getWorksheets();

         index = sheets.getCount();
         User32.MessageBox(0,
                           "Number of sheets:  " + index,
                           "Application Message" ,
                           0);

         for (int i = 1; i <= index; i++)
         {
           worksheet = (_Worksheet)sheets.getItem(new Variant(i));
           worksheet.Activate(0);
           worksheet.setName("Bob's Sheet "+ i);
         }

         User32.MessageBox(0,
                           "Changed sheets' names.",
                           "Application Message" ,
                           0);

         range = worksheet.getColumns();
         range.setColumnWidth(new Variant(40));

         User32.MessageBox(0,
                           "Set column width to 40.",
                           "Application Message" ,
                           0);

         range = worksheet.getCells();

         range.setItem(new Variant(1),
                       new Variant(1),
                       new Variant("This is a result of a call to Range.setItem"));

         User32.MessageBox(0,
                           "Set the value of cell 1:A.",
                           "Application Message" ,
                           0);

         User32.MessageBox(0,
                           "Closing Excel Application.",
                           "Application Message" ,
                           0);
         app.Quit();
         ComLib.release(app);
         ComLib.release(global);
         ComLib.release(workbooks);
         ComLib.release(workbook);
         ComLib.release(sheets);
         ComLib.release(worksheet);
         ComLib.release(name);
         ComLib.release(range);
         //      System.gc();
         //      Thread.currentThread().sleep(1000);
       }

       catch(Throwable t)
       {
         User32.MessageBox(0,
                           t.toString(),
                           "Exception",
                           0);
       }
     }
   }

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

The latest information on updates can be found at http://www.microsoft.com/java/download.htm This link takes you to a site on microsoft.com. For more information on known issues in the SDK for Java version 4.0, please consult the SDK for Java 4.0 release notes. For more information on Visual J++ fixes included in Service Pack 3, please consult the Visual J++ Fixes page.


Q222581 FIX MSJAVAH Fatal Error java.lang.UnsatisfiedLinkError

 Microsoft SDK for Java

Q222581 FIX: MSJAVAH Fatal Error: java.lang.UnsatisfiedLinkError

The information in this article applies to:

  • Microsoft® SDK for Java, version 3.1

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

When running MSJAVAH on a compiled Java class, the following error appears:

Fatal error: java.lang.UnsatisfiedLinkError: no myDLL in shared library path

CAUSE

In the 29xx series of the Microsoft VM, MSJAVAH never wants to initialize the specified class. In the 31xx series, it always wants to initialize the specified class if the class contains primitive members that are declared static and final. Under these conditions, the static block containing the System.loadLibrary method is executed and the aforementioned error occurs.

RESOLUTION

You can use one of the following to resolve this problem:

  • Use SDK for Java Version 3.2 or later. You can download this from http://www.microsoft.com/java/ This link takes you to a site on microsoft.com. This includes a version of MSJAVAH that doesn't ignore the -NOCLINIT command-line option. The -NOCLINIT option tells MSJAVAH not to run static initializers.

  • Comment out the System.loadLibrary line before running MSJAVAH.

  • Use a PC with the earlier 29xx series Microsoft VM to generate your headers.

  • If you created the DLL before upgrading to SDK for Java 3.1, do not delete the DLL. If MSJAVAH can find it, it won't complain.

STATUS

Microsoft has confirmed this to be a problem in the Microsoft products listed at the beginning of this article.

This problem was corrected in Microsoft SDK for Java version 3.2 for Windows.

MORE INFORMATION

To reproduce this error, make sure that you are using SDK for Java 3.1 and compile the following source. Then run MSJAVAH on the resulting class file.

   public class TestMSJAVAH {
     public native void myNativeMethod();
     // this is the culprit:
     public static final double A=3.1;
     // these work fine:
     public static double B=3.2;
     public final  double C=3.3;
     // and this is OK, too:
     public static final Double D=new Double(3.4);
     static {
       System.loadLibrary("myDLL");
     }
     public static void main(String args[]){
       new TestMSJAVAH().myNativeMethod();
     }
   }

Additional query words:

RNI


Q223351 FIX Child Controls Not Properly Painted for setSelectedTab()

 Microsoft SDK for Java

Q223351 FIX: Child Controls Not Properly Painted for setSelectedTab()

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, version 3.1

SYMPTOMS

When making a call to TabPage.setSelectedTab from within an OnSelectedIndexChanged event handler of the parent TabControl, the focus will first go to the user-selected index before returning to the index value set in the setSelectedTab call. In addition, when returning to the index set in code by the setSelectedTab call, the children components of the set TabPage will not be visible and Control.setVisible(true) must be used, causing a noticeable flicker.

RESOLUTION

To work around this problem, call Control.setVisible(true) on the TabPage after the setSelectedTab call is made.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in Microsoft® Visual Studio® 6.0 Service Pack 3. For more information about Visual Studio service packs, please see the following articles in the Microsoft Knowledge Base:

Q194022 INFO: Visual Studio 6.0 Service Packs, What, Where, Why

Q194295 HOWTO: Tell That Visual Studio 6.0 Service Packs Are Installed

MORE INFORMATION

Steps to Reproduce Behavior

  1. Open a new Visual J++ Windows Application project.

  2. Add a TabControl and add some TabPages to the control.

  3. Add an Edit control and a Button control to each TabPage.

  4. Add an OnSelectedIndexChanged event handler to the TabControl.

  5. In the event handler, check the text value of the Edit control on the current TabPage; and, if it is not valid, use setSelectedTab to keep the focus on the current TabPage until the value is valid (see the code sample below).

    Results: When setting the TabPage back to the one that had invalid data in its Edit box, the Edit box will not be visible. Call TabControl.setVisible(true) to work around this problem.

    import com.ms.wfc.app.*;
import com.ms.wfc.core.*;
import com.ms.wfc.ui.*;
import com.ms.wfc.html.*;
import com.ms.win32.*;
public class Form1 extends Form
{
  TabPage lastPage;
  public Form1()
  {
    super();
    initForm();
    lastPage = tabPage1;
  }
  public void dispose()
  {
    super.dispose();
    components.dispose();
  }
  private void onSelectedIndexChanged(Object source, Event e)
  {
    Control[] ctrls = lastPage.getControls();
    for (int i = 0; i < ctrls.length; i++)
    {
      if (ctrls[i] instanceof Edit)
      {
        Edit edit = (Edit)ctrls[i];
        if (edit.getText().equalsIgnoreCase("Valid Data"))
        {
          lastPage = tabControl1.getSelectedTab();
          return;
        }
        tabControl1.setSelectedTab(lastPage);
        break;
      }
    }
  }
  /**
   * NOTE: The following code is required by the Visual J++ form
   * designer. It can be modified using the form editor. Do not
   * modify it using the code editor.
   */
  Container components = new Container();
  TabControl tabControl1 = new TabControl();
  TabPage tabPage1 = new TabPage();
  TabPage tabPage2 = new TabPage();
  TabPage tabPage3 = new TabPage();
  Edit edit1 = new Edit();
  Button button1 = new Button();
  Button button2 = new Button();
  Edit edit2 = new Edit();
  Button button3 = new Button();
  Edit edit3 = new Edit();
  private void initForm()
  {
    this.setText("Form1");
    this.setAutoScaleBaseSize(new Point(5, 13));
    this.setClientSize(new Point(546, 261));
    tabControl1.setLocation(new Point(16, 8));
    tabControl1.setSize(new Point(504, 232));
    tabControl1.setTabIndex(0);
    tabControl1.setText("tabControl1");
    tabControl1.setSelectedIndex(2);
    tabControl1.addOnSelectedIndexChanged
      (new EventHandler(this.onSelectedIndexChanged));
    tabPage1.setLocation(new Point(4, 25));
    tabPage1.setSize(new Point(496, 203));
    tabPage1.setTabIndex(0);
    tabPage1.setText("tabPage1");
    tabPage2.setLocation(new Point(4, 25));
    tabPage2.setSize(new Point(496, 203));
    tabPage2.setTabIndex(1);
    tabPage2.setText("tabPage2");
    tabPage3.setLocation(new Point(4, 25));
    tabPage3.setSize(new Point(496, 203));
    tabPage3.setTabIndex(2);
    tabPage3.setText("tabPage3");
    edit1.setLocation(new Point(8, 8));
    edit1.setSize(new Point(448, 20));
    edit1.setTabIndex(0);
    edit1.setText("edit1");
    button1.setLocation(new Point(8, 168));
    button1.setSize(new Point(75, 23));
    button1.setTabIndex(1);
    button1.setText("button1");
button2.setLocation(new Point(8, 168));
    button2.setSize(new Point(75, 23));
    button2.setTabIndex(0);
    button2.setText("button2");
edit2.setLocation(new Point(8, 8));
    edit2.setSize(new Point(424, 20));
    edit2.setTabIndex(1);
    edit2.setText("edit2");
    button3.setLocation(new Point(8, 168));
    button3.setSize(new Point(75, 23));
    button3.setTabIndex(0);
    button3.setText("button3");
    edit3.setLocation(new Point(8, 8));
    edit3.setSize(new Point(416, 20));
    edit3.setTabIndex(1);
    edit3.setText("edit3");
    this.setNewControls(new Control[] {
                        tabControl1});
    tabControl1.setNewControls(new Control[] {
                               tabPage1,
                               tabPage2,
                               tabPage3});
    tabPage1.setNewControls(new Control[] {
                            button1,
                            edit1});
    tabPage2.setNewControls(new Control[] {
                            edit2,
                            button2});
    tabPage3.setNewControls(new Control[] {
                            edit3,
                            button3});
  }
  public static void main(String args[])
  {
    Application.run(new Form1());
  }
}

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q223355 FIX WJView Hangs with CPU Usage at 100 Percent Using 315x VMs

 Microsoft SDK for Java

Q223355 FIX: WJView Hangs with CPU Usage at 100 Percent Using 315x VMs

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, version 3.1

SYMPTOMS

Running the below program causes the Microsoft VM to use 100 percent of the CPU. This process will hang the PC until it is terminated.

CAUSE

This is due to a bug found in builds 315x of the Microsoft VM exception handling logic.

RESOLUTION

Download and install the latest Microsoft VM from the following Web page:

http://www.microsoft.com/java/download.htm This link takes you to a site on microsoft.com.

STATUS

Microsoft has confirmed this to be a bug in Microsoft VM Version 315x.

MORE INFORMATION

To Reproduce Behavior

Compile and run the following code. On machines with the Microsoft VM that contain this bug, the CPU usage on the machine will go to 100 percent and the Microsoft VM will hang. However, on a machine with a fixed Microsoft VM, the string "java.lang.Exception" will be output and the program will exit immediately.

   public class Test
   {
    public static void main( String [] args )
    {
       Integer i = new Integer( 6 );
       synchronized( i )
       {
         if (true)
           throw new NullPointerException();
       }
    }
   }

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

hhtp://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q223358 FIX Creating MDI Children in Parent's Constructor Causes Error

 Microsoft SDK for Java

Q223358 FIX: Creating MDI Children in Parent's Constructor Causes Error

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, version 3.2

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

When creating more than two Multiple Document Interface (MDI) child windows in the constructor of the parent window, a WFCException is thrown with a message that an error has occurred creating a window handle.

CAUSE

This problem is related to the time at which the Win32® window handles are created, which may not be the same time the child window objects are created in Java code.

RESOLUTION

To work around this problem, limit the number of child windows created in the constructor of the parent to two, and/or create child windows after the parent has been constructed. A third option is to use Control.invokeAsync as illustrated in the commented code in the sample below.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in Microsoft® Visual Studio® 6.0 Service Pack 3. For more information about Visual Studio service packs, please see the following articles in the Microsoft Knowledge Base:

Q194022 INFO: Visual Studio 6.0 Service Packs, What, Where, Why

Q194295 HOWTO: Tell That Visual Studio 6.0 Service Packs Are Installed

MORE INFORMATION

In WFC, handle creation for children of an MDI parent is deferred until the parent Form is made visible.

To Reproduce Behavior

Compile and run the following code using an install of Visual Studio 6.0 that has not had Service Pack 3 applied:

   import com.ms.wfc.app.*;
   import com.ms.wfc.core.*;
   import com.ms.wfc.ui.*;
   public class Form1 extends Form
   {
     public Form1()
     {
       initForm();
       createKids();
     }

     protected void onCreateHandle(Event e)
     {
       super.onCreateHandle(e);
       //uncomment the following line for workaround
       //invokeAsync(new MethodInvoker(createKids));
     }

     public void createKids()
     {
       for (int i = 0; i < 3; i++)
       {
         Form f = new Form();
         f.setMDIParent(this);
         f.show();
       }
     }
public void dispose()
     {
       super.dispose();
       components.dispose();
     }
     /**
      * NOTE: The following code is required by the Visual J++ form
      * designer. It can be modified using the form editor. Do not
      * modify it using the code editor.
      */
     Container components = new Container();
     private void initForm()
     {
       this.setText("Form1");
       this.setAutoScaleBaseSize(new Point(5, 13));
       this.setClientSize(new Point(292, 273));
       this.setIsMDIContainer(true);
     }
public static void main(String args[])
     {
       Application.run(new Form1());
     }
   }

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the Microsoft® SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q223362 FIX WFC ActiveX Controls Do Not Fire Custom Events in VB

 Microsoft SDK for Java

Q223362 FIX: WFC ActiveX Controls Do Not Fire Custom Events in VB

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, version 3.1

SYMPTOMS

When creating an ActiveX control using WFC, custom events are not fired in the target/client application.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in Microsoft® Visual Studio® 6.0 Service Pack 3. For more information about Visual Studio service packs, please see the following articles in the Microsoft Knowledge Base:

Q194022 INFO: Visual Studio 6.0 Service Packs, What, Where, Why

Q194295 HOWTO: Tell That Visual Studio 6.0 Service Packs Are Installed

MORE INFORMATION

Steps to Reproduce Behavior

  1. Open a new Control project in Visual J++ 6.0.

  2. Create a simple control that includes a custom event as outlined in MSDN under the topic, "Creating a Custom Event."

  3. Build and deploy the control.

  4. Test the control in a Microsoft® Visual Basic® application.
    1. Create a new Standard .exe project in Visual Basic.

    2. From the Project menu, click Components and add your new custom control to the project.

    3. In the Visual Basic designer, drag-and-drop the control onto the Visual Basic Form.

    4. From the code view, select the variable name for the control object (MyControl1 is the default) in the right-hand drop-down list and select the custom event in the left-hand drop-down list. This will cause Visual Basic to generate an outline for the custom event handler that will look something like this:
      Private Sub MyControl1_errorEvent(ByVal Parameter0 As Object,
ByVal Parameter1 As Object)
End Sub

Do the same for the Form Load event and insert code that will cause your custom event to fire. The following code handles the MSDN errorEvent sample mentioned below. It should look something like this:

Private Sub Form_Load()
MyControl1.myProp = 201
End Sub

Notice that the custom event doesn't get fired whenever the myProp property value exceeds 200.

For convenience, here is the code pasted from the MSDN documentation:

    // MyControl.java
   import com.ms.wfc.ui.* ;
   import com.ms.wfc.core.* ;
   import com.ms.lang.Delegate;
   /**
    * @com.register(clsid=428B4065-E8B5-11D2-A801-00C04FB624C0,
        typelib=428B4064-E8B5-11D2-A801-00C04FB624C0)
    */
   public class MyControl extends Control
   {
     private int myProp = 1;
     public int getMyProp()
     {
       return myProp;
     }
     public void setMyProp(int value)
     {
       // Fires error event if property value exceeds 200
       if(value > 200)
       {
         onErrorEvent(new ErrorEvent(1020, "Invalid value"));
       }
       myProp = value;
     }
     protected void onPaint( PaintEvent p)
     {
       super.onPaint(p);
       Graphics g=p.graphics;
       g.drawString( getText(), 0, 0);
     }
     // event setup to be able to fire event "ErrorEvent"
     private ErrorEventHandler errDelegate = null;
     public final void addOnErrorEvent(ErrorEventHandler handler)
     {
       errDelegate = (ErrorEventHandler)Delegate.combine(errDelegate,
                                                         handler);
     }
     public final void removeOnErrorEvent(ErrorEventHandler handler)
     {
       errDelegate = (ErrorEventHandler)Delegate.remove(errDelegate,
                                                        handler);
     }
     protected void onErrorEvent(ErrorEvent event)
     {
       if(errDelegate != null)
       {
         errDelegate.invoke(this, event);
       }
     }

     public static class ClassInfo extends Control.ClassInfo
     {
       public static final PropertyInfo myProp =
         new PropertyInfo(MyControl.class, "myProp", int.class);
       public void getProperties(IProperties props)
       {
         super.getProperties(props);
         props.add(myProp);
       }

       public static EventInfo evt = new EventInfo(MyControl.class,
         "errorEvent", ErrorEventHandler.class);
       public void getEvents(IEvents events)
       {
         super.getEvents(events);
         events.add(evt);
       }
     }
   }
   // ErrorEventHandler.java
   import com.ms.wfc.core.*;
   public final multicast delegate void ErrorEventHandler(Object sender,
     ErrorEvent event)
   ;
   // ErrorEvent.java
   import com.ms.wfc.core.*;
   public class ErrorEvent extends Event
   {
     public final int errorNumber;
     public final String errorText;
     public ErrorEvent( int eNum, String eTxt)
     {
       this.errorNumber = eNum;
       this.errorText   = eTxt;
     }
   }

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q223363 FIX Unhandled Exception When Hosting Java ActiveX Controls

 Microsoft SDK for Java

Q223363 FIX: Unhandled Exception When Hosting Java ActiveX Controls

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, version 3.1

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

Java Beans registered as Microsoft® ActiveX® controls might cause a memory fault when exiting if the hosting application/window is a WFC-based Form.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in Microsoft® Visual Studio® 6.0 Service Pack 3. For more information about Visual Studio service packs, please see the following articles in the Microsoft Knowledge Base:

Q194022 INFO: Visual Studio 6.0 Service Packs, What, Where, Why

Q194295 HOWTO: Tell That Visual Studio 6.0 Service Packs Are Installed

MORE INFORMATION

Steps to Reproduce Behavior

  1. Register a Java AWT-based Bean Widget as an ActiveX control using javareg:
    javareg /register /control /class:ClassName /codebase:PathToClassFile
/typelib:NameOfTypeLibraryFile.tlb

    (See the SDK For Java documentation for more information on the javareg tool.)

  2. Open a new Visual J++ 6.0 Windows Application project.

  3. Customize the toolbox (right-click) and add the newly-registered control to the toolbox (ActiveX tab).

  4. Select the new control from the toolbox and add it to the form.

  5. View the code of the WFC Form. After the initForm call, set the text or title of the Bean/Control with a call to setText/Title.

  6. Run the application in the debugger [F5].

  7. Close the Form by clicking on the [x] in the upper-right corner of the window.

    Results:

    An error dialog will pop up with a memory access violation message.

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q223367 FIX RegistryKey setValue() Fails Terminating Character on Windows NT

 Microsoft SDK for Java

Q223367 FIX: RegistryKey setValue() Fails Terminating Character on NT

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, versions 1.0, 1.5, 1.51, 2.0, 2.01, 2.02, 3.0, 3.0 Preview 1, 3.1, 3.2

SYMPTOMS

RegistryKey.setValue might not set the value of a registry key correctly. This problem only occurs on Microsoft® Windows NT®.

CAUSE

The setValue method, when executed under Windows NT, does not account for the terminating null character, which causes incorrect data to be written to the registry key.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This bug was corrected in Microsoft® Visual Studio® 6.0 Service Pack 3. For more information about Visual Studio service packs, please see the following articles in the Microsoft Knowledge Base:

Q194022 INFO: Visual Studio 6.0 Service Packs, What, Where, Why

Q194295 HOWTO: Tell That Visual Studio 6.0 Service Packs Are Installed

MORE INFORMATION

Steps to Reproduce Behavior

  1. Create a new Console Application.

  2. Import com.ms.wfc.app.*

  3. Add the following code to main:
    RegistryKey r = Registry.CURRENT_USER.createSubKey
("Software\\Microsoft\\VisualStudio\\6.0\\Debugger");

r.setValue("Test1","ABC");
r.setValue("Test2","DEF");
r.setValue("Test3","XYZ");
r.setValue("Test2","");
  4. Compile and run the code.

  5. View the specified keys in REGEDIT.

    Without Visual Studio Service Pack 3, the key "Test2" will hold the value of one of its peer keys.


Q233271 FIX DateFormat Class Does Not Default to the System Time Zone

 Microsoft SDK for Java

Q233271 FIX: DateFormat Class Does Not Default to the System Time Zone

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

When using the java.text.DateFormat class, you will observe that it properly sets the time/date. However it does not display the time corresponding to the default system time zone set on your machine. Instead, it defaults to the first time zone of the system's locale. (For US English, the default would always be PST/PDT.)

CAUSE

The problem is that the time zone is not set by default in the versions of the Microsoft VM prior to build 3181.

STATUS

Microsoft has confirmed this to be a bug in the Microsoft products listed at the beginning of this article.

This problem has been fixed in Microsoft VM builds 3181 or later. The latest build is available at:

http://www.microsoft.com/java/ This link takes you to a site on microsoft.com

If you are using a Microsoft VM build prior to this version, then the workaround is to call setTimeZone on the DateFormat object.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Create a new Console Application project using Microsoft® Visual J++® 6.0.

  2. Include the following piece of code in its main method:
    Calendar now = Calendar.getInstance();
   DateFormat df = DateFormat.getDateTimeInstance();
   //df.setTimeZone(TimeZone.getDefault());-->Uncomment this to fix the problem
   System.out.println(df.format(now.getTime()));
  3. Build and execute the above code. This displays the correct date and time.

  4. Now open Control Panel, select Date/Time and change the Time Zone to Eastern Time Zone (EST) on your machine.

  5. Rerun the above code. It still displays the time as if the machine were set to Pacific Time Zone.

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the Microsoft® SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q233359 FIX JActiveX fails for COM Property Declared as IUnknown

 Microsoft SDK for Java

Q233359 FIX: JActiveX fails for COM Property Declared as IUnknown

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 1.51, 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SYMPTOMS

The following error is generated when trying to build a Java project that imports a COM component whose property is declared as type IUnknown:

Undefined name 'stdole2.IUnknown' (J0049)

CAUSE

The problem is that JActiveX generates Java code that treats IUnknown as a user-defined type, rather than as com.ms.com.IUnknown.

RESOLUTION

The problem has been fixed for the JActiveX.exe version 3549 that ships with the SDK for Java version 3.2 available at:

http://www.microsoft.com/java This link takes you to a site on microsoft.com

However, if you are still using a JActiveX prior to SDK3.2, you could still work around the problem using either of the following two ways:

  1. Declare the property as Object in Microsoft® Visual Basic®. It will then be exposed as IDispatch in the type library and Object in Java.

  2. Use a configuration file that will tell JActiveX to use com.ms.com.IUnknown for all types with a GUID of IID_IUnknown. The config file will look like the following:
         ; IUnknown!
     [{00000000-0000-0000-C000-000000000046}]
     Use Class=com.ms.com.Iunknown
  3. If the configuration file were called mappings.jnf, JActiveX would be invoked like this:

    jactivex /d . /javatlb /t mappings.jnf MyControl.DLL

  4. Note that the stdole2 package will not be created because there are no referenced types.

STATUS

Microsoft has confirmed this to be a problem in the Microsoft products listed at the beginning of this article.

MORE INFORMATION

Here is a sample case that reproduces the problem. In the following example, the COM component is an ActiveX DLL created using Visual Basic 6.0. This DLL implements a property declared to be of type IUnknown. When you run JActiveX or do an AddCOMWrapper from within Visual J++ 6.0, it treats this property IUnknown as a user-defined type rather than as com.ms.com.IUnknown. The problem is that Visual Basic is marking the IUnknown property type as a user-defined type (VT_USERDEFINED) instead of the usual IUnknown (VT_UNKNOWN).

Steps to Reproduce Behavior

  1. Create an ActiveX DLL (say Project1.dll) using Visual Basic 6.0, and include the following code:
       Public Property Get NewEnum() As IUnknown
       Set NewEnum = Nothing
   End Property
  2. Create a Windows application using Visual J++ 6.0.

  3. Select Project.Add COM Wrapper.

  4. In the COM Wrappers dialog box, select the Project1.dll created in step 1.

  5. This will create two wrapper class files, project1 and stdole2.

  6. Build the application.

  7. You see the above mentioned error.


PRB KB Articles Overview

The following Java-related PRB Knowledge Base (KB) Articles are included in the Microsoft SDK for Java.

Q169799: PRB: Error J0051: Undefined package 'lang'
Q175622: PRB: SecurityExceptionEx Exception Running a Java Applet
Q177178: PRB: Unable to Sign the Cabfile When Running Signcode
Q177181: PRB: System.getProperty("user.home") Returns Incorrectly
Q178560: PRB: NoClassDefFoundError Accessing a COM Object Through Java
Q178707: PRB: Unable to Play .wav File from Applet or AudioClip
Q179001: PRB: Cannot Use JDBC in Applets Outside of Visual J++'s IDE
Q179062: PRB: COM Objects are not Being Released in Java
Q179854: PRB: No Suitable Driver Exception With JDBC Bridge and SDK
Q183805: PRB: Digitally Signed File Cannot Be Confirmed by IE4
Q189065: PRB: Catastrophic Failure Error Using an ActiveX Control
Q195160: PRB: Wjview.exe Causes Unhandled Exception on Handle Creation
Q198322: PRB: JVC: J0029 and J5020 Errors When Using Language Extensions
Q199950: PRB: Application Using JNI Gives UnsatisfiedLinkError
Q225523: PRB: JAVAH Cannot Find Classes When Executing
Q232638: PRB: Java Distribution Units Need Lots of Disk Space to Install
Q232640: PRB: Obsolete Packages Not Removed from Java Package Manager


Q169799 PRB Error J0051 Undefined package lang

 Microsoft SDK for Java

Q169799 PRB: Error J0051: Undefined package 'lang'

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1, 6.0

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® Internet Explorer (Programming) versions 1.0, 2.0, 2.01, 2.1, 3.0, 3.01, 3.02, 4.0, 4.01, 4.01 SP1, 4.01 SP2, 5.0, 5.0dp1, 5_beta

Important This article contains information about editing the registry. Before you edit the registry, make sure you understand how to restore it if a problem occurs. For information about how to do this, view the Restoring the Registry Help topic in Regedit.exe or the Restoring a Registry Key Help topic in Regedt32.exe.

SYMPTOMS

The following compiler error appears when you try to build simple Java applets or applications:

error J0051: Undefined package 'lang'

This article discusses the possible reasons why this error occurs.

Note This is not specific to the 'lang' package, but could occur for any package whether implicitly or explicitly imported.

CAUSE

This problem often occurs after installing a virtual machine that supports the Java Package Manager (JPM). Beginning with Microsoft VM build 2252 (installed with Internet Explorer 4.0x or the SDK for Java 2.0x) and later, the JPM contains all the system classes. These VM builds no longer require a Classes.zip file on the CLASSPATH at run-time.

Compilers that do not search the JPM will need to find the system classes on the conventional CLASSPATH (%Windir%\java\classes). To create a single zip file that contains all the system classes, see the RESOLUTION section of this article.

RESOLUTION

The MORE INFORMATION section contains a checklist that provides some of the common fixes for this error.

MORE INFORMATION

  1. Following is a checklist that provides some of the common fixes for this error:

    If you have installed Internet Explorer 4.0x or later or the SDK for Java 2.0-3.1, classes.zip may not have been created on the installation machine. This is caused by a new feature of the Java VM called the Java Package Manager (JPM). The JPM contains the system classes in this release of the Microsoft VM. In order to extract the classes from the JPM for use by tools (such as the Java compiler) that search the class path only, type the following in a command window:

    type clspack -auto

    This creates a new Classes.zip file in the %Windir%\java\classes directory and automatically adds it to the CLASSPATH of the VM. For more information on the clspack utility, please refer to the SDK for Java documentation available at http://www.microsoft.com/java This link takes you to a site on microsoft.com.

  2. Add an existing Classes.zip to your CLASSPATH.

    Warning Using Registry Editor incorrectly can cause serious problems that may require you to reinstall your operating system. Microsoft cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk.

    For information about how to edit the registry, view the Changing Keys And Values Help topic in Registry Editor (Regedit.exe) or the Add and Delete Information in the Registry and Edit Registry Data Help topics in Regedt32.exe. Note that you should back up the registry before you edit it. If you are running Microsoft® Windows NT®, you should also update your Emergency Repair Disk (ERD).

    1. Load the registry editor (REGEDT32.EXE).

    2. Open the HKEY_LOCAL_MACHINE window.

    3. In the View dialog box, make sure the Tree and Data check box is selected.

    4. Expand the SOFTWARE node.

    5. Expand the Microsoft node.

    6. Select the Microsoft VM node.

    The CLASSPATH should read something like the following:

    C:\windows\java\classes\classes.zip;C:\windows\java\classes;

    You can also load Microsoft® Developer Studio® and on the Tools menu, click Options to open the Options dialog box. Click the Directories tab. Make sure the platform is the Microsoft VM. Show directories for class files. Add the directory for your Classes.zip file.

  3. Download the latest build of the Microsoft VM from http://www.microsoft.com/java This link takes you to a site on microsoft.com, click Downloads, and follow the Developer Updates link. The REFERENCE section below lists two Knowledge Base articles that discuss the availability of the current Microsoft VM and how to automatically update the Microsoft VM. You need to run clspack after the new Microsoft VM is installed. See item #1 above.

REFERENCES

For additional information, please see the following articles in the Microsoft Knowledge Base:

Q163638 HOWTO: Automatically Update the Microsoft VM

Q163637 INFO: Availability of the current build of Microsoft VM.

For the latest Knowledge Base articles and other support information on VisualJ++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://msdn.microsoft.com/support/scripting This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java This link takes you to a site on microsoft.com


Q175622 PRB SecurityExceptionEx Exception Running a Java Applet

 Microsoft SDK for Java

Q175622 PRB: SecurityExceptionEx Exception Running a Java Applet

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Internet Explorer (Programming) versions 4.0, 4.01

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

When running a Java applet, the security manager throws one of the following exceptions:

com.ms.security.SecurityExceptionEx[classname.methodname]

-or-

com.ms.security.SecurityExceptionEx[Host]

-or-

com.ms.security.SecurityExceptionEx[Unknown]

-or-

java.lang.SecurityException: J/Direct method has not been authorized for use on behalf of an untrusted caller.

CAUSE

  • A SecurityExceptionEx[methodname.classname] will occur if your applet attempts to perform a trusted operation and is not trusted.

  • A SecurityExceptionEx[Host] will occur if the Web browser invoked a method that performs a trusted operation and that method did not first assert its permission to perform the trusted operation. This situation will occur if your applet performs trusted operations in the applets default constructor,

  • init, start, stop or destroy method without first asserting its permissions.

  • A SecurityExceptionEx[Unknown] will occur if the script engine invoked a method that performs a trusted operation, and that method did not first assert its permission to perform the trusted operation. This situation will occur if your applet has a public method called by Microsoft® VBScript® or Microsoft® JScript®, and that method performs trusted operations without first asserting its permissions.

  • A "java.lang.SecurityException: J/Direct method has not been authorized for use on behalf of an untrusted caller" will occur if the Web browser or script engine invoked a method that makes a Microsoft® J/Direct™ call, and that method did not first assert its permission to perform the trusted operation.

RESOLUTION

If a SecurityExceptionEx[methodname.classname] occurs, you must sign your applet to enable it to perform operations outside of the Java sandbox. For more information please see the documentation in the Microsoft SDK for Java 2.0 or 2.01.

Note You must sign your cabinet file with the appropriate permissions.

-Low or -LowX permission will guarantee you have appropriate access or you may sign with the appropriate granular permissions using an ini file passed to Signcode.exe.

If a SecurityExceptionEx[Host], SecurityExceptionEx[Unknown], or "java.lang.SecurityException: J/Direct method has not been authorized for use on behalf of an untrusted caller" and you are sure your caller cannot do harm if your trusted operation is performed, you can do one of the following:

  • Assert your permission using the PolicyEngine class.

Note The lifetime of PolicyEngine.assertPermission is the same as the lifetime of the method in which it is called. Once the method that asserts its permission returns, you would need to re-assert permissions, as needed.

  • Spawn a separate thread to perform the trusted operation, giving the thread permission to perform the operation.

STATUS

This behavior is by design.

MORE INFORMATION

In the Microsoft VM (build 2252 or later) that is included in the SDK for Java 2.0 and later and Internet Explorer 4.0 and later, the security manager now crawls the call stack when an applet is run from a signed cabinet file. This behavior is new in this build of the VM, and helps ensure that the applet author is aware of the security risks of untrusted code manipulating their applet. By asserting an applet's permission, the programmer is acknowledging that they understand the security risks and have taken all measures possible to protect the user's system.

When trusted operations are performed, the security manager ensures the object is trusted to perform the operation, and then the call stack is crawled to ensure all callers are also trusted to make the call. A SecurityExceptionEx[Host] or SecurityExceptionEx[Unknown] exception will be thrown if an untrusted caller is found on the call stack.

The assertPermission(PermissionId pid) method in the PolicyEngine class will prevent the security manager from crawling the call stack, enabling your applet to perform trusted operations even when methods on the call stack are not trusted. You should only assert your permission if you are sure an untrusted member of the call stack cannot harm the users system. A logical place to assert your permissions is at the beginning of the method that is making the trusted call. Once this method returns, subsequent public methods called from outside the VM will also need to assert permission before making trusted calls.

The PermissionID class has predefined granular permissions, such as NETIO, FILEIO, and so forth. In order to grant full permissions to the applet use the SYSTEM permission. This is needed for calling J/Direct, COM, and native methods.

The following sample applet demonstrates reading a character from a Web page, which is a trusted operation. This example needs to be trusted either by placing the file in a signed cabinet file, running the project from Microsoft® Developer Studio®, or by placing the class in the CLASSPATH:

   import com.ms.security.*;

   import java.applet.Applet;
   import java.net.*;
   import java.io.*;
   import java.awt.*;

   public class myApplet1 extends Applet {
     TextField message=null;

     public myApplet1() {
       message=new TextField();
       setLayout(new BorderLayout());
       add("Center",message);
     }

     public void init()
    {
       /*
         Our init function needs to read a character from a URL, which is a
         trusted operation.  We assert NET permission to stop the stack
         crawling since the Web page isn't trusted.  The applet must be
         signed so the init() function has permission to perform net
        operations.
      */
       try {
         if (Class.forName("com.ms.security.PolicyEngine") != null) {
           PolicyEngine.assertPermission(PermissionID.NETIO);
         }
       } catch (Throwable cnfe) {
       }

       try {
         URL url = new URL("http://www.microsoft.com/");
         DataInputStream dis;
         dis = new DataInputStream(url.openConnection().getInputStream());
         dis.readChar();
         message.setText("Read character.");
       } catch (MalformedURLException mue) {
         message.setText("MalformedURL");
         mue.printStackTrace();
       } catch (Throwable t) {
         message.setText(t.toString());
         t.printStackTrace();
       }
     }
   }

REFERENCES

For more information on using the com.ms.security package and for information on signing a Java cabinet file, see this Microsoft SDK for Java documentation:

http://www.microsoft.com/java/sdk/32/default.htm This link takes you to a site on microsoft.com

For additional information on making your Java code trusted in Microsoft Internet Explorer, please refer to the following Knowledge Base article:

Q193877 HOWTO: Making your Java Code Trusted in Internet Explorer

For additional information, the full SDK for Java is available for download at:

http://www.microsoft.com/java/sdk/32/default.htm This link takes you to a site on microsoft.com

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q177178 PRB Unable to Sign the Cabfile When Running Signcode

 Microsoft SDK for Java

Q177178 PRB: Unable to Sign the CAB file When Running Signcode

The information in this article applies to:

  • Microsoft® SDK for Java, versions 1.0, 1.5, 1.51, 2.0x, 3.0, 3.1, 3.2

SYMPTOMS

When you run Signcode.exe on your .cab file, one or more of the following errors occur:

  • Unable to sign the program <cabfile>. (80004005)

  • Unable to sign the program <cabfile>. (80030070)

  • Unable to sign the program <cabfile>. (80070005)

  • Unable to sign the program <cabfile>. (80070057)

CAUSE

Signcode.exe could not sign the .cab file for the reason indicated by the error number. The .cab file may not have been created with -s 6144 parameter or it is either read-only or corrupt.

RESOLUTION

Unable to sign the program <cabfile>. (80004005)

This error appears because you did not reserve space in your .cab file. Re-create the .cab file using the -s 6144 option to Cabarc.exe. This space must be reserved in the .cab file to allow room for the digital signature. It is not necessary to use the -s option with the signing tools included with the SDK for Java 2.0x or newer. The Signcode.exe utility now creates the necessary space for the certificate at the time the .cab is signed.

Unable to sign the program <cabfile>. (80030070)

This error occurs because you did not reserve enough space in your .cab file. Re-create the .cab file using the -s 6144 option to Cabarc.exe. It is not necessary to use the -s option with the signing tools included with the SDK for Java 2.0x or newer. The Signcode.exe utility now creates the necessary space for the certificate at the time the .cab is signed.

Unable to sign the program <cabfile>. (80070005)

This error appears because your .cab file is marked read-only.

Unable to sign the program <cabfile>. (80070057)

This error occurs because your .cab file is corrupt.

STATUS

This behavior is by design.

MORE INFORMATION

To use the -s option for Cabarc.exe, the -s 6144 option reserves unnecessary space in most situations. With the "test" certificate, you can typically get by with 1K of reserved space in the .cab. A good estimate of the space required is slightly larger than the size of the .spc file you are signing with. Also note, it is possible that the certificate will require more than 6144 bytes.

Example

C:>CABARC -s 6144 N mycab *.class

Note It is not necessary to use the -s option with the signing tools included with the SDK for Java 2.0x or newer. The Signcode.exe utility now creates the necessary space for the certificate at the time the .cab is signed.

REFERENCES

For additional information on making your Java code trusted in Microsoft® Internet Explorer, please refer to the following Knowledge Base article:

Q193877 HOWTO: Making your Java Code Trusted in Internet Explorer

For additional information on Frequently Asked Questions for .cab files, please refer to the following Knowledge Base article:

Q168941 INFO: Frequently Asked Questions for .cab Files

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

CABARC, Cab and Sign technology, internet


Q177181 PRB System.getProperty("user.home") Returns Incorrectly

 Microsoft SDK for Java

Q177181 PRB: System.getProperty("user.home") Returns Incorrectly

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.02, 3.0, 3.1, 3.2

SYMPTOMS

When calling System.getProperty("user.home") the Microsoft VM ignores the HOME environment variable value. It always returns %Windir%\java whether or not you set the HOME environment variable.

MORE INFORMATION

Steps to Reproduce Behavior

Create a Java project and include the following class to it:

   class TestProperty
   {

      public static void main(String args[])
      {
         System.out.println(System.getProperty("user.home"));
      }

   }

This always returns %Windir%\java (where %Windir% is the location of your Microsoft® Windows® 95, Microsoft® Windows® 98, or Microsoft® Windows NT® installation), no matter which directory you set the HOME environment variable to.

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

System properties home


Q178560 PRB NoClassDefFoundError Accessing a COM Object Through Java

 Microsoft SDK for Java

Q178560 PRB: NoClassDefFoundError Accessing a COM Object Through Java

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SYMPTOMS

When executing a Java application that calls a COM object like an ATL Server, you may sometimes get the following error message on the COM object:

error: java.lang.NoClassDefFoundError:

The error occurs on the line where you create a new COM object in the Java Class.

CAUSE

One reason why you may get this error could be related to missing parameter attributes for the methods in the COM object's IDL file.

RESOLUTION

Check your methods in the IDL file so that they have the right attributes like [in],[out],[retval] and so on. Once modifying the IDL file, rebuild your COM Server, and rerun JavaTLB or JActiveX on the COM Object's type library so that the changes gets reflected.

STATUS

This behavior is by design.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Create a default ATL COM object using Microsoft® Visual C++® 5.0. Name it AtlServ.

  2. Add a new ATL COM object to the above project. This can be done by right-clicking in Class View and selecting New ATL Object. This will bring up the ATL Object Wizard. Select Simple Object in it and click Next. Now select the Names Tab and name the object as Test.

  3. Add a method to the IDL file as follows:
       ........
   interface ITest : IDispatch
   {
      [id(1), helpstring("Hello")] HRESULT TestMethod(BSTR* strGUID);
   };
   ..........
  4. Add declaration/implementation to this method in the .cpp and .h files of your Test ATL COM Object as follows. Declare this method in the Test.h file as follows:
       .............
   public:
   STDMETHOD(TestMethod)(BSTR* a);

    Following are its implementation:

       // Test.cpp : Implementation of CTes
   ..................
   STDMETHODIMP CTest::TestMethod(BSTR* a)
   {
      USES_CONVERSION;
      *a = SysAllocString(T2OLE("This is a test!"));
      return S_OK;
   }
  5. Now build the ATL Server object, which should also register it.

  6. Run JAVATLB or JActiveX on the server you created in Step 1. If you are using JActiveX, then you will have to use JVC version 4337 or greater that ships with the SDK2.0 and 2.01 for Java in order to build your Java applet.

  7. Create a new Java project using Visual J++ 1.1 and create a new class as follows:
       import atlserv.*;      //This is your ATl Server Object
                          //created in Step 1.
   public class Main
   {
      public static void main(String args[])
     {
         ITest a = (ITest) new Test();
         String result[]=new String[1];
         a.TestMethod(result);
         System.out.println(result[0]);
     }
   }
  8. Build the class and copy it to <windir>/java/lib where <windir> = windows directory in Windows 95/98 and winnt directory in Windows NT.

  9. When running this application using JVIEW you will get the NoClassDefFoundError in the Command-Prompt window.

    Note When using SDK for Java 3.0 and newer you will get null returned.

  10. To fix this problem, specify the [out] attribute to the method in the IDL file as follows:
       interface ITest : IDispatch
   {
      [id(1), helpstring("Hello")] HRESULT TestMethod([out]BSTR*
       strGUID);
   };
  11. Now rebuild your ATL server, and rerun JAVATLB or JActiveX on the ATL Server's type library so that the changes gets reflected.

  12. You should now be able to run your Java application without any problems.

REFERENCES

For the latest Knowledge Base articles and other support information on Visual ++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

NoClassDefFoundError atl server com


Q178707 PRB Unable to Play .wav File from Applet or AudioClip

 Microsoft SDK for Java

Q178707 PRB: Unable to Play .wav File from Applet or AudioClip

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 1.51, 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SYMPTOMS

When an applet tries to play a .wav file from an applet using the Applet.play method or the AudioClip.play method, either nothing happens or you get the following console output:

NativeAudioStream: invalid file type

CAUSE

The Sun Microsystems Inc. Java Development Kit (JDK) 1.02 and 1.1 APIs are able to play only AU files. The AU files need to be 8 bit, ulaw, 8000 Hz, and one channel.

RESOLUTION

Use a product that is capable of creating AU files according to these specifications. Convert the .wav file and change the URL to point to the AU file.

STATUS

This behavior is by design.

REFERENCES

For additional information, please see the following article in the Microsoft Knowledge Base:

Q179850 HOWTO: Playing a .wav file in Java

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q179001 PRB Cannot Use JDBC in Applets Outside of Visual J++'s IDE

 Microsoft SDK for Java

Q179001 PRB: Cannot Use JDBC in Applets Outside of Visual J++'s IDE

The information in this article applies to:

  • Microsoft® Visual J++®, versions 1.0, 1.1

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SYMPTOMS

When programming an applet that uses JDBC, everything works in the development environment. When the applet is run outside of the development environment, the Applet throws a com.ms.security.SecurityExceptionEx.

CAUSE

JDBC requires access to resources that are available only when outside the set of security restrictions placed on non-trusted Java applets, also known as the "sandbox." Regular applets cannot access files on the client's hard disk, access other network sockets, or print. JDBC requires file input/output. When trying to access a file on the client, the SecurityExceptionEx is thrown.

RESOLUTION

In order for the applet to work properly, you will need to create a cabinet file and digitally sign it (see references for more information). Then you need to add certain method calls in the applet to "assert permissions" (please see article reference below) for file input/output.

STATUS

This behavior is by design.

REFERENCES

For additional information on making your Java code trusted in Microsoft® Internet Explorer and other information, please see the following articles in the Microsoft Knowledge Base:

Q193877 HOWTO: Make Your Java Code Trusted in Internet Explorer

Q175622 PRB: SecurityExceptionEx Exception Running a Java Applet

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q179062 PRB COM Objects are not Being Released in Java

 Microsoft SDK for Java

Q179062 PRB: COM Objects are not Being Released in Java

The information in this article applies to:

  • Microsoft® SDK for Java, versions 1.51, 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Visual J++®, versions 1.0, 1.1

SYMPTOMS

When setting a COM object reference to null and possibly attempting to force garbage collection by calling gc, COM objects may not be released in a timely or predictable fashion.

CAUSE

If you do not call ComLib.release, normal garbage collection will attempt to perform the release for you. However, this mechanism is not guaranteed due to the threading limitations of many COM objects. That is, many COM objects can be called only on the thread on which they were created. Because garbage collection occurs at unpredictable times, the required thread may have expired or may be no longer responding to messages by the time garbage collection reclaims the object. In addition, this unpredictability can obscure true memory leaks and/or tie up important system resources.

RESOLUTION

It is recommended that you use explicit releases by calling ComLib.release in order to free COM objects in a timely and predictable fashion.

MORE INFORMATION

For example, if you have the following code that creates a COM object in Java:

import excel8.*;
   import com.ms.com.*;
   _Global globXL=null;
   _Application appXL=null;
   try
   {
      globXL = (_Global)new Global();
      appXL = (_Application)globXL.getApplication();
   }
   catch (ComFailException e)
   {
      System.out.println(e.getMessage());
   }

You would use this to release these COM objects (note all references to COM objects should be released):

   try
   {
      ComLib.release(appXL);
      appXL=null;
      ComLib.release(globXL);
      globXL=null;
   }
   catch (ComFailException e)
   {
      System.out.println(e.getMessage());
   }

REFERENCES

Please see the Microsoft SDK for Java documentation for more information.

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

JCOM garbage collection release com objects


Q179854 PRB No Suitable Driver Exception With JDBC Bridge and SDK

 Microsoft SDK for Java

Q179854 PRB: No Suitable Driver Exception With JDBC Bridge and SDK

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® virtual machine (Microsoft VM)

SYMPTOMS

When running your Java class that uses the JDBC bridge with the SDK for Java 2.0 or newer, you see the following exception:

java.sql.SQLException: No suitable driver

CAUSE

One of the frequent causes for this exception is running any application that the JDBC bridge shipped with the SDK for Java 2.0 Beta.

RESOLUTION

In general, the package name has changed to com.ms.jdbc.odbc with Microsoft® Internet Explorer 4.0x and SDK for Java 2.0 or later Microsoft VM. For example the following lines should be changed:

Class.forName("sun.jdbc.odbc.JdbcOdbcDriver");

or

Class.forName("com.ms.sql.CDriver");

to:

Class.forName("com.ms.jdbc.odbc.JdbcOdbcDriver");

MORE INFORMATION

Other common causes for "No suitable driver" are invalid connection strings, user IDs, passwords, and security restrictions imposed on the driver (if it was downloaded and is not trusted).

REFERENCES

More information on the JDBC driver is included the SDK for Java documentation and the JDBC sample available with the SDK for Java.

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q183805 PRB Digitally Signed File Cannot Be Confirmed by Internet Explorer 4.0

 Microsoft SDK for Java

Q183805 PRB: Digitally Signed File Cannot Be Confirmed by IE4

The information in this article applies to:

  • Microsoft® ActiveX® SDK

  • Microsoft® SDK for Java, versions 1.5, 1.51

SYMPTOMS

When downloading a digitally signed file, rather than popping up the certificate dialog box as expected, a message box comes up indicating that the file has been digitally signed but that it cannot be confirmed.

CAUSE

Microsoft has recently confirmed a rare certificate verification problem caused by the .reg files offered as part of the tools set of the Microsoft ActiveX SDK and SDK for Java 1.5x. The problem is that the .reg files, Wvtston.reg and Wvtstoff.reg, set the system to check Verisign's revocation server extraneously. This error occurs only when your system is set to check the revocation server, and the revocation server itself is down.

RESOLUTION

Use SetReg.exe available in the Internet Client SDK's \Inetsdk\Bin folder or the %SDKDIR%\Bin directory of the SDK for Java 2.0x or later, rather than the .reg files in the ActiveX SDK or older SDK for Java. SetReg.exe should be used to disable Revocation checking on your machine.

By issuing the following command, the revocation server for individual certificates is disabled:

setreg 4 true

By issuing the following command, the revocation server for commercial certificates is disabled:

setreg 5 true

REFERENCES

For more information, please refer to code signing on the MSDN™ Online Web Workshop. Additionally, you can find information on code signing in the SDK for Java 2.0 or later in the %SDKDIR%\Bin\Packsign or the %SDKDIR%\Bin directory.

Downloading Code on the Web is an excellent article on the MSDN Online Web Workshop that provides information on digital signing. It also contains many links to various resources related to component download.

Additional query words:

revocation certificate Verisign


Q189065 PRB Catastrophic Failure Error Using an ActiveX Control

 Microsoft SDK for Java

Q189065 PRB: Catastrophic Failure Error Using an ActiveX Control

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

  • Microsoft® Visual J++®, versions 1.0, 1.1

SYMPTOMS

When trying to use a Microsoft® Visual C++®-generated ActiveX Control from Java, you will see the following error when trying to run the Java application:

Error:<0x8000ffff> Catastrophic failure Press any key to continue...

RESOLUTION

When trying to use a Microsoft® ActiveX® Control as an automation server, you need to override the method IsInvokeAllowed. For more information on why this method has to be overridden, please see the REFERENCES section below.

To fix the problem, override IsInvokeAllowed in your ActiveX Control as follows:

   BOOL CMyOleControl::IsInvokeAllowed (DISPID)
   {
      // You can check to see if COleControl::m_bInitialized is FALSE
      // in your automation functions to limit access.
     return TRUE;
   }

For the example case given below, you will override this method in the Circ3ctl.cpp file and declare this virtual function in the Cir3ctl.h file. Also make sure you rebuild and reregister the control before using it from Java.

STATUS

This behavior is by design.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Build and register the Circ3.ocx sample that comes with Visual C++.

  2. Run JACTIVEX /javatlb circ3.ocx. This will create a folder called circ3 under %wWINDIR%\java\trustlib, which will contain .java files for the corresponding coclass, interfaces for the CIRC3.OCX.

  3. Create a Java application as follows and import the ActiveX Control:
       import com.ms.com.*;
   import circ3.*;
   public class circle
   {
      public static void main(String args[])
      {
         circle main = new circle();
         main.test();
      }
   }
   public void test()
   {
      _DCirc3 c  = null;
      c  = (_DCirc3) new Circ3();
      c.AboutBox();
   }
   }
  4. Build the Java application using the JVC that ships with the SDK for Java2.0x or later. For more information on how to use this JVC with Visual J++, please see the REFERENCES section below.

  5. You will see the above mentioned error message.

REFERENCES

For more information on how to use an ActiveX Control as an Automation Server, please see the following article in the Microsoft Knowledge Base:

Q146120 HOWTO: Use an OLE Control as an Automation Server

For more information on how to use the new Jvc.exe with Visual J++, please see the following article in the Microsoft Knowledge Base:

Q183712: HOWTO: Installation Instructions for the Microsoft SDK for Java.

Additional query words:

Catastrophic error activex control


Q195160 PRB Wjview.exe Causes Unhandled Exception on Handle Creation

 Microsoft SDK for Java

Q195160 PRB: Wjview.exe Causes Unhandled Exception on Handle Creation

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, versions 3.1, 3.2

SYMPTOMS

If a class that extends the Window class is created with className LISTBOX and overrides wndProc and handles the WM_CREATE message, then Wjview.exe causes an unhanded exception on handle creation.

RESOLUTION

The Window with className LISTBOX must pass the WM_CREATE message on to defWndProc in order for the class to be created correctly.

MORE INFORMATION

Steps to Reproduce Behavior

  1. Create a Java source WndTest.java:
    import com.ms.wfc.app.*;
   import com.ms.win32.*;
public class WndTest extends Window
   {
     protected void wndProc(Message m)
      {
         switch (m.msg)
         {
           case winw.WM_CREATE:
                        break;
            default :
               defWndProc(m);
                break;
         }
      }
   }
  2. Create a Java source Form1.java:
    import com.ms.wfc.app.*;
   import com.ms.wfc.core.*;
   import com.ms.wfc.ui.*;
   import com.ms.wfc.html.*;
   import com.ms.win32.*;
/**
   * This class can take a variable number of parameters on the command
   * line. Program execution begins with the main() method. The class
   * constructor is not invoked unless an object of type 'Form1' is
   * created in the main() method.
   */
   public class Form1 extends Form
   {
      public Form1()
      {
         // Required for Visual J++ Form Designer support
         initForm();
// TODO: Add any constructor code after initForm call
      }
/**
   * Form1 overrides dispose so it can clean up the
   * component list.
   */
      public void dispose()
      {
         super.dispose();
         components.dispose();
      }
       private void button1_click(Object source, Event e)
      {
         CreateParams cp = new CreateParams();
         cp.className = "LISTBOX";
         cp.style = winw.WS_VISIBLE;
         WndTest w = new WndTest();
         w.createHandle(cp);
      }
/**
   * NOTE: The following code is required by the Visual J++ form
   * designer.  It can be modified using the form editor.  Do not
   * modify it using the code editor.
   */
   Container components = new Container();
   Button button1 = new Button();
private void initForm()
     {
        this.setText("Form1");
        this.setAutoScaleBaseSize(new Point(5, 13));
        this.setClientSize(new Point(292, 273));
button1.setLocation(new Point(112, 128));
        button1.setSize(new Point(75, 23));
        button1.setTabIndex(0);
        button1.setText("button1");
        button1.addOnClick(new EventHandler(this.button1_click));

        this.setNewControls(new Control[] {button1});
     }
/**
   * The main entry point for the application.
   *
   * @param args Array of parameters passed to the application
   * via the command line.
   */
     public static void main(String args[])
     {
        Application.run(new Form1());
     }
   }
  3. Compile the Java source files.

  4. Run Form1.

  5. Click the button on the form. This will create a WndTest class with className LISTBOX and style WS_VISIBLE. The WndTest class overrides wndProc such that WM_CREATE is not passed on to defWndProc and everything else is. WJVIEW causes an unhandled exception.

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q198322 PRB JVC J0029 and J5020 Errors When Using Language Extensions

 Microsoft SDK for Java

Q198322 PRB: JVC: J0029 and J5020 Errors When Using Language Extensions

The information in this article applies to:

  • Microsoft® SDK for Java, versions 2.02, 3.2

SYMPTOMS

One or more of the following warnings/errors may occur when compiling a Java program that uses Microsoft language extensions:

warning J5020: Directive '@security' ignored--extensions are turned off

-or-

warning J5020: Directive '@com' ignored--extensions are turned off

-or-

warning J5020: Directive '@dll' ignored--extensions are turned off

-or-

error J0029: Invalid character

CAUSE

Microsoft SDK for Java 2.02 (Microsoft® virtual machine (Microsoft VM) Build 2435) includes the Microsoft compiler for Java (Jvc.exe) version 1.02.7318 or later, which disables Microsoft language extensions by default. Previous versions of the Microsoft compiler for Java (Jvc.exe) did not disable Microsoft language extensions by default.

RESOLUTION

To compile code that uses Microsoft extensions, you should use the /x- option to enable extensions.

Jvc.exe supports the following command-line options for enabling and disabling language extensions:

/x Disable language extensions (now the default setting)

/x- Enable language extensions

MORE INFORMATION

Steps to Reproduce Behavior

  1. Create a file named Test.java that contains the following:
    /**
         @dll.import("USER32.DLL")
         */
         public class Test {
           public static void main(String args[])
           {
           #if MSGBOX
              MessageBox(0,"HELLO","Hello World",0);
           #else
              System.out.println("Hello World");
           #endif
           }
           #if MSGBOX
           public native static int MessageBox (int hWnd, String lpText,
               String lpCaption, int uType);
           #endif
         }
  2. Compile the file using the following command:

    jvc Test.java

    This produces the following error messages:

    Test.java(4,1) : warning J5020: Directive '@dll' ignored -- extensions are turned off

    -or-

    Test.java(7,1) : error J0029: Invalid character

    -or-

    Test.java(7,5) : error J0013: Expected '('

    -or-

    Test.java(8,4) : error J0014: Expected ')'

    -or-

    Test.java(9,1) : error J0029: Invalid character

The correct way to compile a file that uses Microsoft language extensions is to use the following command line:

jvc /x- Test.java

This produces the following warning message:

Note Use of the Microsoft language extensions for Java results in compiled code that will run only on Windows systems with the Microsoft VM installed and may not run on other virtual machines. The Microsoft VM is installed with Windows 98, and a freely redistributable version is included with this product. While future versions of Microsoft's Java development tools may be prohibited by court order from incorporating keyword extensions and compiler directives not contained in Sun's Java language specification, any code written and compiled with this version of the product will be unaffected by such a ruling. (Use /nomessage to disable this message.)

If you want to compile the file and define the MSGBOX symbol, you would use the following command:

jvc /x- /D MSGBOX Test.java

When compiling Java code that contains Microsoft language extensions, it is possible to disable the warning message by passing the /nomessage option to JVC. Older compilers do not support the /nomessage option and will generate a "warning J5003: Ignoring unknown compiler option '/nomessage'." To use the /nomessage option, your command-line options would be as follows:

jvc /x- /nomessage /D MSGBOX Test.java

If you upgrade Microsoft® Visual J++® to use the compiler from the SDK for Java, it is possible that your Microsoft Visual J++ product will always disable Microsoft extensions, regardless of the check box "Disable Microsoft Language Extensions" being selected or not. In this case, to compile code using language extensions, you will need to add the /x- option (without the quotes) to the Additional compiler options, in the Project Properties/Compile tab.

If you compile code and receive the J5020 warning, the .class file generated may not function properly. You should recompile using the /x- option. Failure to do so may result in the following error message when running your application:

Caught exception: java.lang.UnsatisfiedLinkError: Simple.MessageBox Possible causes: If you are trying to use Microsoft® J/Direct™ (@dll.import), check your compiler version (for JVC, requires 4336 or greater.) If you are trying to use RNI, there are new requirements: see documentation. Probably wrong version of Java compiler.

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q199950 PRB Application Using JNI Gives UnsatisfiedLinkError

 Microsoft SDK for Java

Q199950 PRB: Application Using JNI Gives UnsatisfiedLinkError

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.02, 3.1, 3.2

  • Microsoft® Visual J++®, versions 1.1, 6.0

SYMPTOMS

When you run a Java application that requires Java Native Interface (JNI) the following error might occur:

java.lang.UnsatisfiedLinkError:AClassWithNativeMethods.theNativeMethod
Possible causes: If you are trying to use J/Direct (@dll.import), check
your compiler version (for JVC, requires 4336 or greater.) If you are
trying to use RNI, there are new requirements: see documentation.
Probably wrong version of Java compiler.

CAUSE

When you run a JNI application using the Microsoft VM in the SDK for Java 2.x, you must use build 2435 or greater of the Microsoft VM. When you run a JNI application using the Microsoft VM in the SDK for Java 3.x, you must use build 3158 or greater of the Microsoft VM.

REFERENCES

For additional information on the current release of the Microsoft VM, please refer to the following Knowledge Base article:

Q163637 INFO: Availability of the current build of Microsoft VM.

INFO

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, see the following page on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Q225523 PRB JAVAH Cannot Find Classes When Executing

 Microsoft SDK for Java

Q225523 PRB: JAVAH Cannot Find Classes When Executing

The information in this article applies to:

  • Microsoft® SDK for Java, versions 3.1, 3.2

SYMPTOMS

When running Javah.exe on a Java class, you may get one of the following or similar errors:

Signalled error "java/lang/NoClassDefFoundError" with detail "java/io/Serializable"

-or-

java.lang.Object not found: aborting

CAUSE

Javah.exe, unlike the other Microsoft SDK for Java tools, requires the user to specify a class path via the -classpath command-line option or via the CLASSPATH environment variable. If the class path is not specified, is invalid, or contains corrupted or missing data, Javah.exe does not work.

RESOLUTION

There are a couple of things to check if you receive one of these error messages:

  • Verify that the CLASSPATH environment variable or the -classpath command-line option points to

    %Windir%\Java\Classes\Classes.zip and the directory that contains your class files.

  • Open Classes.zip and verify that the class specified in the error message is contained within. If Classes.zip is corrupt or if the specified class is missing, run the following from a DOS command prompt to regenerate a new Classes.zip file:

    clspack -auto

STATUS

This behavior is by design.

Additional query words:

JAVAH.EXE JAVAH


Q232638 PRB Java Distribution Units Need Lots of Disk Space to Install

 Microsoft SDK for Java

Q232638 PRB: Java Distribution Units Need Lots of Disk Space to Install

The information in this article applies to:

  • Microsoft® Visual J++®, version 6.0

  • Microsoft® SDK for Java, versions 3.1, 3.2

  • Microsoft® Internet Explorer (Programming) versions 4.0, 4.01, 4.01 SP1, 4.01 SP2, 5.0

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® Visual Studio® versions 6.0, 6.0 SP1, 6.0 sp1, sp2, sp3, 6.0 SP2, 6.0 SP3

SYMPTOMS

Java Distribution Units (.cab files that are installed into the Java Package Manager) require a lot more disk space during the installation on FAT systems when compared to NTFS or FAT32 systems.

Because of this drives formatted as FAT that are low on disk space have a higher chance of running out of space during the .cab download and install process. The end result is a failed .cab installation, which unfortunately is usually silent, presenting no error messages to the user. Here are some symptoms of this problem:

  • Java applets installed into the JPM do not run after they are downloaded.

  • No Java applets run on a particular computer after upgrading the Microsoft VM. Note that the user may not be aware that the Microsoft VM was upgraded.

  • When installing Visual Studio, setup keeps prompting the user to install the Microsoft VM and reboot (even though they already performed this step).

CAUSE

More temporary disk space is required on a hard disk formatted as FAT (as compared to NTFS or FAT32) when downloading and installing the same Distribution Unit (DU).

DU .cab files download into a temporary directory. As an intermediate step, all of the files inside the .cab archive get extracted to temporary space on the hard disk. Finally, all the extracted files get re-packaged into a ZIP file that resides in your %Windir%\java\packages directory (where %Windir% is the client's Windows directory).

If the drive has a large cluster size (such as drives formatted as FAT), each file will temporarily take up more space before it is recompressed into a ZIP file. Since Java DUs typically contain hundreds (or possibly thousands) of small class files, the cluster size can cause a relatively small DU to require a huge amount of temporary hard disk space.

RESOLUTION

The easiest resolution is for the user to free up some disk space and try the download or install again. To be safe, ensure that the hard disk where Windows is installed has at least 200 MB of free disk space.

Developers can minimize the impact of this problem on their users by breaking up each DU into smaller DUs. That way the temporary disk space required by each DU is smaller.

MORE INFORMATION

Example

NTFS and FAT32, by default on a 3 gigabyte (GB) partition, use a 4 kilobyte (KB) cluster size (512 byte sector * 8 sectors). FAT, by default will use a 64 KB cluster size (512 byte sector * 128 sectors).

Note A cluster consists of one or more 512 byte sectors and each file consumes one or more clusters (always rounded up).

Therefore, on a 3 GB hard disk with a .cab file consisting of five files (where these file are 0.5 KB, 1 KB, 2 KB, 5 KB, 10 KB, 75 KB, respectively):

File Size | NTFS | FAT
500 bytes | 1 cluster | 1 cluster
1 KB file | 1 cluster | 1 cluster
2 KB file | 1 cluster | 1 cluster
5 KB file | 2 clusters | 1 cluster
10 KB file | 3 clusters | 1 cluster
75 KB file | 19 clusters | 2 clusters
 | 27 clusters | 7 clusters

Total Space needed to decompress .cab file:

NTFS: 27 clusters * 4 KB/cluster = 108 KB

FAT: 7 clusters * 64 KB/cluster = 448 KB

Note The above example uses only six files. If a .cab archive contains hundreds or even thousands of Java class files, it is fairly easy to run out of disk space on a FAT system.

REFERENCES

For more information on file systems, see the following articles in the Microsoft Knowledge Base:

Q101267 Files Are Larger on FAT Partitions

Q140365 Default Cluster Size for FAT and NTFS

Q192322 Description of Default Cluster Sizes for FAT32 File System

Q100108 Overview of FAT, HPFS, and NTFS File Systems

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com

Additional query words:

FAT NTFS FAT32 disk space VM .cab DU VJ


Q232640 PRB Obsolete Packages Not Removed from Java Package Manager

 Microsoft SDK for Java

Q232640 PRB: Obsolete Packages Not Removed from Java Package Manager

The information in this article applies to:

  • Microsoft® virtual machine (Microsoft VM)

  • Microsoft® SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SYMPTOMS

If you have distributed version V1 (for example, 0,0,0,1) of a Distribution Unit (DU) containing packages A, B, and C, then upgrading to version V2 (for example 0,0,0,2) of the same DU containing packages A and C, with package B now being obsolete, would not remove package B from the Java Package Manager.

RESOLUTION

A workaround is to ship package B in version V2 of the DU (so that version V2 of the DU has packages A, B, and C) in such a way that you remove all the classes and/or resources from package B and replace them with a single dummy file (for instance, 'obsolete.txt').

STATUS

This behavior is by design.

MORE INFORMATION

The reason for keeping package B in the Java Package Manager is to accommodate incremental upgrades of the DU as given in the above example. In such a scenario, package B might not be really obsolete. It just might be that package B was not included in version V2 of the DU because it had not changed since version V1 of the DU.

Not removing obsolete packages from the Java Package Manager would result in the following side effects:

  • consumption of disk space

  • you would still be able to successfully compile against the old classes in package B

The workaround suggested would remove the obsolete package(s) and replace them with a dummy file, '0' bytes in size, thereby taking care of the above-mentioned side effects.

REFERENCES

For the latest Knowledge Base articles and other support information on Microsoft® Visual J++® and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/ This link takes you to a site on microsoft.com

http://support.microsoft.com/support/java/ This link takes you to a site on microsoft.com


Tools Reference

The Microsoft SDK for Java tools enable you to compile, run, and test Java programs and applets. The tools are located in the %SDKDIR%\Bin directory. Make sure this directory is in your path before using the tools. This section provides reference information on the command-line options. The use for each of the tools is listed in the following table.

Java SDK Tools

Compiling and Debugging Tools
AppletViewer | Runs Java applets.
ClassVue | Displays compiled classes at the bytecode level.
ClassD and ClassR | Installs debugging and retail versions of the system classes to be package managed and updates the CLASSPATH environment variable.
Javasrc | Extracts source code from the debugging version of the system classes.
Jexegen | Converts Java classes into native executables.
Jntsvc | Converts Java classes into a Microsoft® Windows NT® Service executable.
Jvc | Creates Java applications and applets by compiling Java source code. For a list of all errors and warnings produced by this compiler, see JVC Errors and Warning Messages.
Jview | Runs Java applets and applications from the command line.
NMake | Builds projects based on the commands contained in a makefile.
Qvue | Prints out class method signatures and identifies .class files that were generated from a type library.
Wjview | Runs Java Frame applets and applications that create a frame window in a separate process.

Native Code and COM Tools
Guidgen | Generates globally unique identifiers (GUIDs).
Jactivex | Allows you to host automation-enabled Microsoft® ActiveX® Controls in Java and create Java source from type libraries. Used for creating Java/COM interfaces. Replaces javatlb and jcom.
Javah | Generates C header and source files from a Java class.
Javareg | Registers Java classes as COM components in the Microsoft® Windows® registry.
Msjavah | Generates C language header files for Java classes.
Resmerge | Combines multiple Microsoft® Win32® resource (.res) files into a single file.
Vjreg | Registers Java classes as COM components in the registry. With vjreg, you can register multiple Java classes in one execution.

Software Distribution Tools
Cabarc | Handles the archiving of multiple files in a compressed format.
Cert2spc | Creates a Software Publisher's Certificate from one or more X.509 certificates.
Certmgr | Manages and displays certificates, CTLs, and CRLs. Replaces the dumpcert utility.
Chkjava | Allows users to view security information placed in a cabinet file by signcode with the JavaSign DLL.
Chktrust | Checks the validity of a file.
Cprmedit | A Microsoft® Windows®-based utility that enables end users and developers to specify permissions that govern the download of unsigned and signed software when using Microsoft® Internet Explorer 4.0 (and later).
Dubuild | Writes Open Software Distribution files and creates Distribution Units for Java software distribution on Microsoft Internet Explorer 4.0 or later.
Makecert | Generates a test X.509 certificate.
MakeCTL | Creates a certificate trust list (CTL) and saves the encoded CTL to a certificate store or to a file.
Piniedit | A Windows-based tool that generates custom Java permissions .ini files for use with the signcode –jp command-line option.
Setreg | A tool to change registry settings.
Signcode | Signs cabinet files and gives developers more control over the security restrictions placed on an applet.

Package Manager Tools
Clspack Writes packages that are installed with package manager to a .zip file archive.

Miscellaneous Tools
IntegrationClasses.exe and IntegrationClasses2000.exe | Installs Microsoft integration classes.
VM Uninstaller | Removes the Microsoft virtual machine from the computer.


Compiling and Debugging Tools

The compiling and debugging tools included with the Microsoft SDK for Java are as follows:

AppletViewer runs a Java applet.

ClassVue displays the contents of a Java class in a readable format.

ClassD and ClassR install debugging (ClassD) and retail (ClassR) versions of the system classes to be package managed.

Javasrc extracts source from the debugging version of the system classes.

Jexegen converts Java classes into a fully executable Microsoft® Win32® application.

Jntsvc generates self-contained, self-installing/uninstalling, redistributable executables (.exe files) for Microsoft® Windows NT® system services.

Jvc creates Java programs and applets by compiling Java source code.

Jview executes Java applets and applications from the command line.

Nmake builds projects based on commands contained in a description file (makefile).

Qvue prints out class method signatures and identifies .class files that were generated from a type library.

Wjview executes Java applets and applications from the command line and spawns a separate window process.

The following topics cover general information pertaining to some or all the compiling and debugging tools:

CLASSPATH Environment Variable

Command Files


CLASSPATH Environment Variable

Use the CLASSPATH environment variable to specify additional class path information when compiling from the command line. The CLASSPATH environment variable has the following syntax:

SET CLASSPATH = <path>

When the Microsoft virtual machine (Microsoft VM) and the command line get class path information, Java programs may behave differently, depending on where they run. When the Microsoft VM installs, it enters the value C:\%Windir%\Java\Classes\Classes.zip;. into the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\Classpath. When a Java program runs, the Microsoft VM first looks for the class path value in the registry. If the application executes from the command line, the Microsoft VM also uses the CLASSPATH environment variable, if one has been set.

The jexegen tool uses virtual paths in command line arguments. It is important that the jexegen tool is in your CLASSPATH environment variable, as well as the classes you are working with. If jexegen is not in the class path, the utility must be run from the directory where the associated classes are located (in particular, any classes that contain the main method), or an application error occurs. For example, the following command will not work:

C:\>\SDK-java\bin\jexegen /v c:\_java\BsetEditor\*.class
   c:\_java\BsetEditor\sun\audio\*.class ...

The jexegen utility is running directly from \bin, and it uses absolute paths. This results in an Ignoring File message. You can avoid this by adding jexegen to your class path and by using virtual paths in command line arguments. The classes you include on the command line needs to be only a package name, as follows:

C:\_java\BsetEditor\>jexegen /V com.ms.ui.*.class ...

For more information on this, see Working with Package Names.


Command Files

The jexegen, jvc, Nmake, and jntsvc tools can use command files. Command files (also referred to as response files) are text files containing the information you would otherwise type on the command line.

A command file contains a list of options and file specifications, one per line. Specify a command file with an "at" sign (@), followed by a file name; the file name can specify an absolute or relative path.

For example, this command line:

C:\..\>jexegen /main:myapp /out:myapp.exe
             Myapp.class Fido.class Fido2.class Fido3.class

can be replaced with the following command line:

 jexegen @myapp.dat

where the contents of the file myapp.dat is:

  /main:myapp
  /out:myapp.exe
  Myapp.class
  Fido.class
  Fido2.class
  Fido3.class


AppletViewer

The Microsoft Applet Viewer (AppletViewer) runs a Java applet.

Use the following command to run AppletViewer:

appletviewer <url> | <filename>

AppletViewer Command-Line Arguments

<url> | Specifies the address of an HTML file containing an APPLET tag that defines the Java applet to run.
<filename> | Names the HTML file containing an APPLET tag that defines the Java applet to run.


ClassVue

The Class File Contents Viewer (ClassVue) displays the contents of a Java class in a readable format.

Use the following command to run ClassVue:

classvue [options] [drive:][path] <classname.class> [>outputfile]

ClassVue Command-Line Arguments

<options> | One or more ClassVue options.
[drive:][path] <classname.class> | Specifies the name of the Java .class file to display. This must specify a drive or a path (or both) of the file if it is not in the current drive or directory. Include the .class file extension.
[>outputfile] | Specifies an output file for the ClassVue results. (By default, ClassVue writes information to the standard output.)

ClassVue Command-Line Options

/cpno /cvue /d? /ivmal /ltd /min /q /readme /tables /v /?

Usage Notes

ClassVue writes information to the standard output, listing a class overview and the offsets, sizes, types, and values of the constant pool, fields, methods, and attributes belonging to the class.

ClassVue generates seven description levels. By default, all levels are displayed. You can use the /min, /ltd, or /cpno options to alter the levels displayed. The description levels are shown in the following table.

D1 | Overview information
D2 | Methods, fields, and classes
D3 | Root data structures
D4 | Constant pool
D5 | Fields pool
D6 | Methods pool
D7 | Attributes pool

Example

The following command line generates information about a class named Hello:

classvue \SDK\Samples\Jexegen\Hello\Test\Hello.class

See Also

ClassVue Options


ClassVue Options

This section describes the command-line options that can be used with ClassVue.

/cpno

Suppresses the display of constant pooling.

/cvue

Displays output sent to a file named by the package and class with the extension .cvue.

/d?

Displays the list of information levels.

/ivmal

Generates informal Virtual Machine Assembly Language.

/ltd

Displays only D1, D2, and D3 level information. See the ClassVue usage notes for a description of these levels.

/min

Displays only D1 level information. See the ClassVue usage notes for a description of this level.

/q

Quiet mode; suppresses the Microsoft copyright banner.

/readme

Displays descriptions of Microsoft® ActiveX® terms and abbreviations displayed by ClassVue.

/tables

Displays many of the items in table form.

/v

Provides a verbose display of the .class file.

/?

Displays ClassVue usage information including a list of available options.


ClassD and ClassR

ClassD installs debugging versions of the system classes to be package managed, and updates the CLASSPATH environment variable.

ClassR installs retail versions of the system classes to be package managed, and updates the CLASSPATH environment variable.

Use the following commands to run ClassD and ClassR, then follow the prompts:

classd [options]
classr [options]

ClassD and ClassR Command-Line Options

/c | Extracts files only to the folder when used with the /t option.
/c:<command> | Overrides install command defined by author.
/q | Quiet mode.
/t:<full path> | Specified temporary working folder.

Usage Notes

After running ClassD, reboot your machine.

Note Installation of the debug classes will degrade the performance of Java on your machine due to the extended symbol information. To remove the debug classes, run ClassR to install the retail classes.

If you run ClassD from the \Bin directory and then run javasrc, the error message Unable to Open File Classes.zip may appear. Run javasrc from within the %WINDIR%\Java\Classes directory or run it with a command line that includes the path to classes.zip, shown as follows:

C:\..\>javasrc C:\%WINDIR%\java\classes\classes.zip

See Also

CLASSPATH Environment Variable

Javasrc


Javasrc

The Package Manager Extraction Utility (javasrc) extracts source from the debugging version of the system classes.

Use the following command to run javasrc:

javasrc [-] [/?] [class_zip]

Javasrc Command-Line Arguments

- | Deletes all Java source files that are extracted from class_zip.
/? | Displays javasrc usage information.
class_zip | The .zip archive from which to extract or delete source files. If no file is specified, classes.zip is assumed.

Usage Notes

Javasrc extracts or deletes Java source files from the specified .zip file archive.

If you install the classd.zip debug source file by running ClassD from the \Bin directory, and then run javasrc, the error message Unable to Open File Classes.zip may appear. Run javasrc from within the %WINDIR%\Java\Classes directory, or run it with a command line that includes the path to classes.zip, shown as follows:

C:\..\>javasrc C:\%WINDIR%\java\classes\classes.zip

To delete the extracted source files from the hard disk, use the hyphen (-) option. For example:

javasrc –classes.zip

See Also

ClassD


Jexegen

The Java Win32® Executable Generator (jexegen) converts Java classes into a fully executable Microsoft® Win32® application. The executable produced is in the exegen format. Jexegen can also create COM DLLs with embedded type libraries.

Use the following command to run jexegen:

jexegen [options] [@commandfile] files

Jexegen Command-Line Arguments

options | One or more jexegen options.
@commandfile | A command file listing options and file specifications to be used by jexegen. For more information, see Command Files.
<files> | Names of the files to be converted. You can specify class files and arbitrary data files.

Jexegen Command-Line Options

/ba /base /bindto /cri /d /main /maxver /nologo /nomain /out /r /r- /raw /reg /special:tlb[-] /special:pe[-] /special:all[-] /special:res /stack /v /w /win32res /win32res- /?

See Also

Jexegen Options

Jexegen Usage Notes

Exegen Format


Jexegen Options

This section describes the command-line options that can be used with jexegen.

/ba:<address>

Valid only when building a DLL; specifies the base address where you want the DLL to load. Both hex and decimal formats are supported.

/base:<dir>

Sets the base directory; used to determine package names of specified class files. When used with the /raw or /bindto option, this option specifies the base directory that file operations are relative to. By default, package names and file operations are determined relative to the current directory. If used more than once on the command line, all /base options are relative to the original (current) directory.

/bindto:<stub>

Specifies the executable (.exe file) or dynamic-link library (DLL) to bind the class resources to.

/cri:<filename>

Valid only when building a DLL; specifies a file that provides COM registration information (CRI). See CRI Files for details on the format of CRI files.

/d

Builds a COM DLL.

/main:<classname>

Required; sets the name of the main class file, which must contain the public static main method. The name specified on the command line must be the same as the class's internal name; it is case-sensitive and you must separate package names with periods(.).

For example, if you usually run your application with the command line

view MySample.Sample

the appropriate switch for jexegen would be

/main:MySample.Sample

This option is ignored when building DLLs.

/maxver:<version>

Specifies the maximum format version allowed. Specifying /maxver:1 generates version 1 format resources, which can only contain class files (in order to be compatible with older virtual machines). Specifying /maxver:2 generates version 2 format resources, which can contain arbitrary data files. This is the default.

/nologo

Suppresses display of the Microsoft copyright banner.

/nomain

Indicates that you do not want to specify a main class file. This option is only useful in conjunction with the /raw or /bindto option, and is ignored when building DLLs.

/out:<filename>

Specifies the name of the output file. If you do not specify the /out option, jexegen creates the executable file Jex.exe by default.

/r

Searches subdirectories recursively for the specified class files. By default, subdirectories are not searched.

/r-

Turns off subdirectory recursion. Only useful if the /r option has already been used.

For example, the following partial command line instructs jexegen to find all class files matching This*.class in the current directory and all subdirectories, and all files matching That*.class only in the current directory:

/r This*.class /r- That*.class

/raw

Saves resource data to a file and does not generate an executable. The data file generated is of the appropriate format to be used with the IJavaExecute2::SetClassSource method.

/reg

Valid only when building a DLL; autoregisters (by calling DllRegisterServer) the built DLL.

/special:all[-]
/special:pe[-]
/special:tlb[-]
/special:res

These three options allow you to switch between the old (prior to the Microsoft SDK for Java version 3.2) and new ways that jexegen handles .res, .tlb, and portable executable (PE) files. For more information, see the section How Jexegen Handles Resource Files. If you use the option with the minus sign, you turn off the new behavior. The default is /special:all (all new behaviors are enabled).

Note If you turn off the TLB behavior, jexegen will not parse the type library that is looking for custom MTS registration attributes.

/stack:<reserve>

Specifies the desired per-Win32-thread stack reserve size, which is the amount of virtual memory reserved for each thread's stack. This option is only useful when building executables; the value is read from the .exe header when the executable is launched and is static thereafter. Both hex and decimal formats are supported.

/v

Verbose mode; provides detailed output.

/w

The generated executable will not have an associated console window. This option will only be useful for graphical applications.

/win32res

Exposes Java resources as Win32 resources. The resource files are listed as file inputs to the jexegen command. By default, this option is disabled (that is, Java resources are not exposed as Win32 resources).

/win32res-

Does not expose Java resources as Win32 resources. Useful only if the /win32res option has already been used.

/?

Displays jexegen usage information including a list of available options.


Jexegen Usage Notes

This section provides the following additional information on using jexegen:

Working with Package Names

Custom Stubs

Generating COM DLLs

Support for onCOMRegister Method

Generating Version 2 Format Resources

How Jexegen Handles Resource Files

Jexegen Limitations

Jexegen Examples

Working with Package Names

Preserve package names when using the jexegen tool. The package names of the classes to be bound into the executable are determined by the directories in which those class files are located. You must therefore run the jexegen tool from a directory above the directory containing the class files.

For example, a Java application consists of two class files, Main.class and Helper.class, that exist in a package called Sample. The files are in the C:\Classes\Sample directory.

C:\Classes\Sample\Main.class
  C:\Classes\Sample\Helper.class

If the command jexegen /main:Main *.class is run from the C:\Classes\Sample directory, the generated executable will not work correctly, because the names of the class files in the executable will not reflect their actual names. The correct way to build the .exe file is to run the command jexegen /main:Sample.Main Sample/*.class from the C:\Classes directory. To verify that the correct names are included, use the command jexegen /v option to observe the names of class files that are stored in the executable.

By default, the current directory is used as the base directory. Package names are determined relative to the base directory. You can use the /base option to specify an alternative base directory.

Custom Stubs

Jexegen works by binding the class files to a small stub program. This stub simply instantiates the Microsoft virtual machine (VM), and uses the IJavaExecute2::SetClassSource method to tell the VM that it should look for class files inside the executable.

If the built-in stub is insufficient for your needs, you can provide your own stub file. For example, a custom stub could contain version information or a custom icon. You can use the jexegen /bindto option to add the class resource data to your own stub program. Alternatively, you can use the jexegen /raw option and reference the resulting data file from your program's resource script.

The Samples folder of the SDK for Java includes the source code for a sample jexegen stub.

Generating COM DLLs

You can now use jexegen to create COM DLLs with embedded type libraries. The DLL can contain any number of Java/COM objects. COM registration information (CRI) must be provided for Java classes, which tells jexegen how to expose the classes as COM objects. There are three ways to provide CRI for a class:

  • Using the @com.register directive.

  • Using MTS typelib attributes, which you specify in the .idl file. Only two attributes are defined:

    JAVACLASS("<classname>") specifies the name of the Java class.

    PROGID("<text>") specifies the program identifier.

  • Using a CRI file and the /cri option with jexegen.

You can use multiples CRI sources. Information from multiple sources will be merged and verified against each other to detect conflicts.

CRI Files

A CRI file is a text file that provides COM registration information for Java classes. You can use CRI files to provide information that cannot be specified in any other way (such as the desired threading model). Each line of a CRI file provides COM information for one Java class.

Use the keywords shown in the following table to provide COM information in a CRI file.

class:<class name> | Required; the name of the Java class.
clsid:{<GUID>} | The class identifier. If the CLSID is not specified in the CRI file or in any other CRI source (@com.register or MTS typelib attributes), then one is generated via CoCreateGuid.
progid:<text> | The program identifier. Note that quotation marks are not used.
TypelibGUID:{<GUID>} | The type library's GUID.
version:"<decimal>.<decimal>" | The type library's version number.
description:"<text>" | Description text inserted into the registry as the default value for the CLSID.
ThreadingModel:<Apartment | Free | Both> | The object's threading model.
control | Registers the object as an ActiveX control.

The ThreadingModel:<Apartment | Free | Both> supports the COM+ neutral apartment: it allows you to specify ThreadingModel=Neutral in CRI files. If ThreadingModel=Neutral is specified for a COM object, the COM object’s InprocServer32\ThreadingModel value will be set to Neutral when the DLL is registered.

Only the class:<class name> is required; all other keywords are optional. The keywords can be specified in any order but must be specified on one line in the CRI file. For example:

clsid:{0B765470-A05D-11d2-970C-0080C7E171C0} class:depth.CRIReg
progid:BLARG! Typelibguid:{CD94BA10-C560-11d2-9772-0000F8771C2E}
control description:"my class" version:"345.1234"
ThreadingModel:Apartment

Support for onCOMRegister Method

Jexegen now supports the implementation of the static method onCOMRegister. You can use this method to perform additional registration, such as creating custom registry keys needed by a DLL. When you add this method to a COM class, it will be automatically invoked when the COM DLL is registered.

The onCOMRegister method is a user-defined method whose signature must match the following signature:

public static void onCOMRegister(boolean isRegister)
{
// Add your custom registration code here
}

Generating Version 2 Format Resources

Jexegen now generates version 2 format resources which can contain arbitrary data files. This allows you to include files in the executable that could previously only be placed in the class path, in a .zip file, or by using some other method. To add arbitrary files, use the same jexegen syntax as for class files. For example:

jexegen /main:Hello /out:Hello.exe Hello.class Hello.dat

If jexegen encounters a file that is not a class file (in this example, Hello.dat), it automatically generates a version 2 format resource. You can use the /maxver option to force jexegen to generate a version 1 format resource (which can only contain class files).

How Jexegen Handles Resource Files

Previously, jexegen classified all files that were not class files as Java resources. Now, jexegen applies the following rules before determining that a file should become a Java resource:

  • Win32 portable executable (PE) files are ignored.

  • Win32 resource files are merged into the final image. If conflicts occur, resources in the .res file will overwrite resources in the image without warning.

  • Type libraries are merged into the final image; type libraries are registered and unregistered when the generated DLL is registered and unregistered.

  • All other files are considered to be Java resources.

  • Jexegen will now merge .res files into the generated image. If you are binding to an .exe that was created by jexegen, any class file information will be overwritten by the current use of jexegen. If you need to use a two-step build process, merge your resources first, then call jexegen a second time to put all the class files in it.

Jexegen Limitations

Note the following limitations when using jexegen:

  • A type library is not automatically created for COM classes that are not already associated with one. In this case, you can use the following procedure:
    1. Use vjreg on all of your classes to create the type library and register the classes.

    2. Package the type library and all other files into a DLL and register the DLL. This overwrites the registry values created by vjreg.
  • All files being packaged must be specified relative to the base directory. The default base is the current directory. You can specify a different base with the /base option.

  • Image versioning is not supported. Since image versioning is accomplished using Win32 resources, you could create a version resource in Microsoft® Developer Studio® and merge it into your image.

Jexegen Examples

This section contains examples of how to use jexegen.

On the jexegen command line, you must specify the class files you want to include and the name of the class file containing the main method.

For example, assume you have a Java application that consists of three class files: A.class, B.class, and C.class. A.Class contains the application's main method. To generate an executable, run the following command from the directory that contains the class files:

jexegen /main:A /out:MyApp.exe A.class B.class C.class

In this case, the jexegen tool creates the file MyApp.exe, which contains your Java application.

The following command line creates the executable file, Hello.exe, from a single .class file, Hello.class:

jexegen /main:Hello /out:hello.exe Hello.class

The following command line creates the executable file, classvue.exe, from all classes in the ClassVue directory in the Microsoft SDK for Java:

jexegen /main:ClassVue /out:classvue.exe *.class


Jntsvc

The Microsoft® Windows NT® Service Executable Generator (jntsvc) generates self-contained, self-installing/uninstalling, redistributable executables (.exe files) for Microsoft® Windows NT® system services.

Use the following command to run jntsvc:

jntsvc /svcmain:<classname> [options] [@commandfile] <files>

Jntsvc Command-Line Arguments

/svcmain:<classname> | Sets the name of the main service class file, which must be derived from com.ms.service.Service. For more information, see the /svcmain description. Can be used multiple times to specify the service class of each service that may be run within the same process.
options | One or more jntsvc options.
@commandfile | A command file listing options and file specifications to be used by jntsvc. For more information, see Command Files.
<files> | Names of the files that the executable will be generated from. You can specify class files and arbitrary data files.

Jntsvc Command-Line Options

/base /hookdll:hookdllname /out /r /r- /svcmain /v /w /?

See Also

Jntsvc Options

Jntsvc Usage Notes

com.ms.service


Jntsvc Options

This section describes the command-line options that can be used with jntsvc.

/base:<dir>

Sets the base directory and determines package names of specified class files. By default, package names and file operations are determined relative to the current directory. If this option is used more than once on the command line, all /base options are relative to the original (current) directory.

/hookdll:hookdllname

The specified DLL (hookdllname) will be loaded before loading the Microsoft virtual machine (Microsoft VM). This allows the DLL to perform any custom initialization needed for the service, such as calling CoInitializeSecurity.

/out:<filename>

Specifies the name of the output file.

/r

Searches subdirectories recursively for the specified class files. By default, subdirectories will not be searched.

/r–

Turns off subdirectory recursion. This is only useful if the /r option has already been used.

For example, the following partial command line instructs jntsvc to find all class files that match This*.class in the current directory and all subdirectories, and all files that match That*.class only in the current directory:

/r This*.class /r- That*.class

/svcmain:<classname>

Required; sets the name of the main service class file, which must be derived from com.ms.service.Service. The name that is specified on the command line must be the same as the class's internal name; it is case-sensitive and you must separate package names with periods (.).

For example, if the service's class name is MyService and is in the package MyPackage, the appropriate switch for jntsvc would be as follows:

/svcmain:MyPackage.MyService.

The /svcmain option can be used multiple times to specify the service class of each service that can be run within the same process. One or more service-specific options may follow each service, as follows:

/classpath:<path>

Sets any additional class paths required. Because the service classes are embedded in the generated executable, this does not need to point to the service classes (unlike Microsoft SDK for Java version 1.5.1 services).

/displayname:<display name>

Sets the descriptive name of the service. This is displayed in the first column of the Services control panel. The default value is the fully-qualified name of the service’s main class.

/eventsource:<event source name>

Sets the event source name in the error log. The default is Java Service. This is displayed in the Source column of the event viewer.

/installparams:<params>

Sets the installation parameters. When the service is installed, the service's static installService method will be invoked with this string. If no parameters are specified, an empty string ("") is used. Note that parameters can also be specified at service install time using the /params option. See Installing, Uninstalling, and Running the Executable for details.

/servicename:<service name>

Sets the name the service is registered as. The default value is the name of the service’s main class.

General Options

/v

Verbose mode; provides detailed output.

/w

Generates a service executable without a console window.

/?

Displays jntsvc usage information including a list of available options.


Jntsvc Usage Notes

The Microsoft SDK for Java provides the following support for writing Windows NT system services:

  • Multiple services can be run within the same process.

  • The jntsvc tool generates self-contained executables for ease of distribution. A generated executable can install or uninstall itself by using the /install or /uninstall options.

  • The service can be started in command-line mode, which is useful when starting the service from a debugger.

  • Arguments can optionally be applied to the service.

For information on writing Microsoft® Windows NT® system services in Java, see the com.ms.service package.

The jntsvc tool generates a service executable. It is similar in usage and purpose to the jexegen tool. The use of the command file and specification of the class files in combination with the /base and /r options are identical to those used with jexegen.

Service Example

The following command line generates an executable for the test service included with the SDK for Java:

jntsvc /svcmain:TestService /eventsource:TestService
   /base:%SDKDIR%\bin\jntsvc TestService.class

In this example, %SDKDIR% is the SDK for Java directory.

Generating Version 2 Format Resources

Jntsvc (like jexegen) now generates version 2 format resources which can contain arbitrary data files. To add arbitrary files, use the same jntsvc syntax as for class files. For example:

jntsvc /svcmain:MyService /out:MyService.exe MyService.class MyService.dat

If jntsvc encounters a file that is not a class file (in this example, MyService.dat), it automatically generates a version 2 format resource.

Note that unlike jexegen, jntsvc does not have a /maxver option that can be specified to force the use of version 1 format resources.

Installing, Uninstalling, and Running the Executable

After you have generated the executable, use the following command line to install, uninstall, or run the executable:

<executable name> [options] [arguments to service]

For example the following commands install and uninstall MyService:

MyService /install
MyService /uninstall

See the table below for a description of the available options.

If the service class has methods of the form:

static void installService(String PackagedParams, String UserParams)

and/or:

static void uninstallService()

then these methods will be invoked when the service is installed or uninstalled, respectively. This allows the service to programmatically specify any custom settings on the machine. The service executable can then be a distribution unit instead of being packaged as a cab file.

The installService method's parameters come from two sources:

  • PackagedParams are specified when the executable is generated using the /installparams option to the jntsvc /svcmain switch.

  • UserParams are specified when the service is installed using the /params option described in the table below.

The following table briefly describes the available options for installing, uninstalling, and running a service:

/install | Installs the service.
/uninstall | Uninstalls the service.
/cmd:<service name> Runs the service <service name> in command-line mode. This is useful when starting and controlling a service under a debugger. Messages that are normally sent to the event log are sent to the console. Service events can be simulated by entering the following commands in the console window:

Note /cmd is not available for windowed services.

  • STOP
    Sends a SERVICE_CONTROL_STOP event to the service.

  • PAUSE
    Sends a SERVICE_CONTROL_PAUSE event to the service.

  • CONTINUE
    Sends a SERVICE_CONTROL_CONTINUE event to the service.

  • SHUTDOWN
    Sends a SERVICE_CONTROL_SHUTDOWN event to the service.

  • INTERROGATE
    Sends a SERVICE_CONTROL_INTERROGATE event to the service.
/debug | Displays additional diagnostic information. When used with /install, it pauses before installing each service.
/rename:<old name>=<new name> Sets the service's name at install time. This option can be used to install a service multiple times from the same executable, with each instance of the service having a different name and running in a separate process. This option can also be used to rename a service without regenerating the executable.

For example, if a service is built with the following command:

jntsvc /out:MyService.exe /svcmain:MyService MyService.class

then the service can be installed with a different service name using the following command:

MyService /install /rename:MyService=MyService2
/params:<parameters> Specifies the parameters that are provided to the service as the UserParams parameter in its installService method. If none are specified, an empty string ("") is used.

The service receives both the parameters specified when the service executable was generated (using the /installparams option to the jntsvc /svcmain switch) and the parameters specified at install time using this /params option.
/username:<user name> | Specifies the account the service runs as. The default value is LocalSystem. This option cannot be specified for multiple-service executables.
/password:<password> | Specifies the password for the user name.
/quiet | Completely suppresses the user interface, including console output.

Important Note As of version 2.02, the service information is contained within the generated executable. Therefore, the registry keys under HKLM\System\CurrentControlSet\Services that were used for version 1.5.1 services are no longer recognized. In version 1.5.1, certain parameter values were specified when the svcsetup was run. However, with version 2.02, to change the values of these parameters you must regenerate the executable. The only exceptions to this rule are the /password and the /username parameters, which are now options that you can specify on the generated executable.


Jvc

The Microsoft Compiler for Java (jvc) creates Java programs and applets by compiling Java source code.

Use the following command to run jvc:

jvc [options] [@commandfile] <files>

Jvc Command-Line Arguments

options | One or more jvc options.
@commandfile | A command file listing source files to be compiled by jvc.
<files> | Names of one or more Java source files.

Jvc Command-Line Options

/cp /cp:o /cp:p /D /d /g /g:l /g:t /nologo /nowarn /nowrite /O /O:I /O:J /ref /verbose /w /wx /x /?

Usage Notes

Use jvc.exe (jvc) to compile specified .java source files into interpreted .class files. To compile without producing the .class files, use the /nowrite option.

If you are compiling your Java project from the command line, place the jvc options before the names of your source files. Jvc reads the command line from left to right, processing options and files in the order they are encountered. Each option applies to all files on the command line. If jvc encounters conflicting options, it uses the rightmost option.

You can specify any number of options and file names—the number of characters on the command line must not exceed 1024 or the limit dictated by the operating system.

Jvc recognizes the following file name syntax:

  • Jvc accepts files with names that follow FAT, HPFS, or NTFS naming conventions.

  • Any file name can include a full or partial path.

A full path includes a drive name and one or more directory names. Jvc accepts file names separated either by backslashes (\) or forward slashes (/).

A partial path omits the drive name; jvc defaults to the current drive. If you do not specify a path, jvc defaults to the current directory for the file's location.

Note If a file does not have an extension, jvc defaults to .java for the file's extension.

Jvc accepts a command file as an argument on the command line. When used with jvc, a command file can only contain the names of the Java source files to be compiled; it cannot contain any jvc compiler options nor can it invoke the jvc command.

To use the JDK 1.1 language features supported by jvc with Microsoft® Visual J++®, you must replace the Visual J++ versions of Jvc.exe, Jps.dll, and Msjvc.dll with the SDK versions. See Microsoft Visual J++ Compiler for instructions.

For a complete list of errors and warning messages produced by jvc, see Jvc Errors and Warning Messages.

See Also

Jvc Options

CLASSPATH Environment Variable

Command Files

Jvc Errors and Warning Messages


Jvc Options

This section describes the command-line options that can be used with jvc.

/cp <classpath>

Sets the CLASSPATH environment variable for the current compilation. This option specifies the path where jvc can find system and user-defined classes. The Java interpreter uses a platform-dependent default location and the CLASSPATH environment variable to find system classes. The directories in the class path are separated by semicolons on a Microsoft® Windows® system; on UNIX, by colons.

For example, on Windows NT, the class path might be as follows:

jvc /cp x:.;x:\java\classes

In this example, jvc searches in and beneath the directories on the path for system- and user-defined classes.

/cp:o

Prints the class path to standard output. This option is especially useful for troubleshooting errors, such as Class not Found, when compiling from the command line.

The following example prints the class path to the screen:

jvc /cp:o

/cp:p <path>

Prepends the path entered to the beginning of the existing class path and inserts a semicolon (;) between them.

The value for the existing class path can come from the CLASSPATH environment variable or from the /cp option. When multiple /cp:p switches are entered, the paths are concatenated.

For example, the following command concatenates the directories myproj1 and myproj2, and inserts the resulting path before the existing class path:

jvc /cp:p myproj1 /cp:p myproj2

/D <symbol>

Defines a conditional compilation symbol.

/d <directory>

Specifies an output directory other than the current directory for the .class files. If the directory does not exist, jvc will create it.

The following command compiles the myClass.java file into a myClass.class file and writes this file into the class directory:

jvc /d c:\classdir myClass.java

/g[-]

Generates all debugging information. No debugging options are set by default. The effect of using the /g switch is the same as using the /g:l (generates line numbers) and /g:t (generates debug tables) options together.

To disable this option, use a hyphen (-) after the switch on the command line.

Examples

The following command creates a .class file called myClass.class that contains debugging information:

jvc /g myClass.java

The following command instructs jvc to exclude debugging information from the myClass.class file:

jvc /g- myClass.java

/g:l[-]

Generates line numbers that are used when debugging a program. By default, no debugging options are set.

To disable this option, use a hyphen (-) after the switch on the command line.

Examples

The following command instructs jvc to generate line-number information for the resulting myClass.class file:

jvc /g:l myClass.java

The following command instructs jvc to turn line-number generation off:

jvc /g:l- myClass.java

/g:t[-]

Generates debug tables that are used when debugging a program. By default, no debugging options are set.

To disable this option, use a hyphen (-) after the switch on the command line.

Examples

The following command instructs jvc to generate debug-table information for the resulting myClass.class file:

jvc /g:t myClass.java

The following command instructs jvc to turn debug-table generation off:

jvc /g:t- myClass.java

/nologo

Suppresses the display of the Microsoft copyright message.

/nowarn

Turns off warnings. By default, warnings are enabled.

/nowrite

Compiles a .java file without writing a .class file.

In the following example, the myClass.java file is compiled and errors and warnings are reported, but no myClass.class file is produced:

jvc /nowrite myClass.java

/O[-]

Full optimization; combines optimizing options to produce the fastest possible program. The effect of using this option is the same as using the /O:I (optimizes by inlining methods) and /O:J (optimizes bytecode jumps) options together.

To disable any optimization option, use a hyphen (-) after the switch on the command line.

Examples

The following command fully optimizes the code for the myClass.class file that is produced:

jvc /O myClass.java

The following command turns all code optimization off:

jvc /O- myClass.java

/O:I[-]

Optimizes by inlining methods. Code that is inlined does not have the overhead associated with a method call. Because Java has no mechanism to request method inlining, use this option when you want the compiler to inline your code.

To disable this option, use a hyphen (–) after the switch on the command line.

Examples

The following example evaluates the source code in the myClass.java file and inlines methods where possible. The resulting myClass.class file contains the optimized code:

jvc /O:I myClass.java

The following command turns all inline-code optimization off:

jvc /O:I- myClass.java

/O:J[-]

Optimizes the bytecode jumps in the compiled .class file. This switch tells the compiler to generate code that jumps to another jump. This switch is the compiler's default optimization setting.

To disable this option, use a hyphen (-) after the switch on the command line.

Examples

The following example evaluates the source code in the myClass.java file and optimizes the bytecode jumps to produce more efficient code. The resulting myClass.class file contains the optimized code.

jvc /O:J myClass.java

The following command turns bytecode jump optimization off:

jvc /O:J- myClass.java

/ref[-]

Recompiles referenced classes if they are out-of-date. This option is enabled by default. To disable this option, use a hyphen (-) after the switch on the command line.

/verbose

Displays all messages while compiling a file or project. These messages give useful information about the progress of the compilation.

/w {0-4}

Specifies the number of warning messages produced by the compiler; this only applies to source files named on the command line.

Compiler warning message numbers begin with J5. The documentation describes the warnings, indicates each warning's level, and indicates potential problems (rather than actual coding errors) with statements that might not compile as you intend. See Jvc Errors and Warning Messages for a complete list of the warning messages produced by jvc.

The meanings of the /w options are shown in the following table.

/w0 | Turns all warning messages off.
/w1 | Displays severe warning messages.
/w2 | Displays a less-severe level of warning message than /w1 ; the default option.
/w3 | Displays a less-severe level of warning message than /w2, including use of methods with no declared return type, failure to put return statements in methods with non-void return types, and data conversions that would cause loss of data or precision.
/w4 | Displays the least severe level of warning messages.

/wx[-]

Treats warnings as errors.

/x[-]

Treats extended keywords as simple identifiers and disables all other Microsoft extensions. The /x option is enabled by default and should be used if you plan to port your program to other environments.

Jvc supports the Java language specification. The compiler also offer a number of features beyond those required by the Java language specification. These features are not available when the /x option is used. To enable these extensions, use a hyphen (-) after the switch on the command line.

Examples

The following command ignores any extensions used in the myClass.class file:

jvc /x myClass.java

The following command enables the language extensions:

jvc /x- myClass.java

/?

Displays jvc usage information including a list of command-line options.


Jview

The Java Viewer (jview) executes Java applets and applications from the command line. Jview provides an environment that your application can run in, and supports both debug and retail versions of your application.

Use the following command to run jview:

jview [options] <classname> [arguments]

Jview Command-Line Arguments

options | One or more jview options.
classname | The name of the .class file to execute. Do not include the .class extension to this file name. For example, use HelloWorldApplet rather than HelloWorldApplet.class.
arguments | Command-line arguments to be passed to the .class file supplied in classname parameter.

Jview Command-Line Options

/a /cp /cp:a /cp:p /d: /n /prof /p /v /vst /?

Usage Notes

Jview supports both applications and applets. If your Java project has a main method, jview will execute it. Jview executes applets, when used with the /a switch, by sending the applet to Appletviewer.

Specify options to jview before the name of the .class file. If not, they will be interpreted as command-line arguments to the .class file.

Jview is similar to the wjview tool, except that wjview runs the application as a separate graphical user interface process and does not use a console window.

See Also

Jview Options

AppletViewer

CLASSPATH Environment Variable

Wjview


Jview Options

This section describes the command-line options that can be used with jview.

/a

Invokes the Microsoft AppletViewer. Applets that are run with the applet viewer behave the same as when run by a browser host application, including loading, sound, and security. The applet viewer accepts applet parameters and class names in addition to URLs and HTML files.

When the /a option is used, any remaining command-line tokens become parameters for the applet viewer.

Example

You can load an applet either by using an HTML file to specify parameters, or by loading parameters directly from the command line. The following example shows how to load an applet from an HTML source file with the applet tag:

<applet code=MyApplet.class width=100 height=200>
<param name=SomeName value=SomeValue></applet>

The same applet can run in the applet viewer with the following command line information:

jview /a width=100 height=200 SomeName=SomeValue MyApplet

The following example shows how to run more than one applet at a time:

jview /a width=200 height=400 MyApplet height=300 MySecondApplet

This displays the first applet in a 200 x 400 frame, and the second applet in a 200 x 300 frame. If no height and width are specified on the command line, the applet's default size is one-third of the size of the screen.

The following code shows that any parameter, including HTML files, can be loaded from the class path:

jview /a /cp \src\bvt MyApplet.html

/cp <classpath>

Sets the CLASSPATH environment variable. This option specifies the path where jview can find system and user-defined classes. The Java interpreter uses a platform-dependent default location and the CLASSPATH environment variable to find system classes. For more information, see CLASSPATH Environment Variable. The directories in the class path are separated by semicolons on a Microsoft® Windows® system; on UNIX, by colons.

Example

For example, on Microsoft® Windows NT®, the class path might be as follows:

jview /cp x:.;x:\java\classes

In this example, jview searches in and beneath the directories on the path for system and user-defined classes.

/cp:a <path>

Appends the path entered to the end of the existing class path and inserts a semicolon (;) between them.

Note The value for the existing class path can come from the CLASSPATH environment variable or from the /cp option. When multiple /cp:a switches are entered, the paths are concatenated.

For example, the following command concatenates the directories myproj1 and myproj2, and appends the resulting path to the end of the existing class path:

jview /cp:a myproj1 /cp:a myproj2

/cp:p <path>

Prepends the path entered to the beginning of the existing class path and inserts a semicolon (;) between them. When multiple /cp:p switches are entered, the paths are concatenated.

Note The value for the class path can come from the CLASSPATH environment variable or from the /cp option. When multiple /cp:p switches are entered, the paths are concatenated.

For example, the following command concatenates the myproj1 and myproj2 directories, and inserts the resulting path before the existing class path:

jview /cp:p myproj1/cp:p myproj2

/d:<property=string value>

Sets a system property, which can be read using the java.lang.System.getProperty or java.lang.System.getProperties methods. See these methods for descriptions of system properties.

For example, you can use the following command line to set the user.dir property to some arbitrary value:

jview /d:user.dir=c:\java\test myapp

You can also set user-defined properties. For example, you can set a property called myprop with the following command line:

jview /d:myprop=12 myapp

/n <namespace>

Specifies a namespace to run the application in. Separate namespaces allow Java packages with identical names to exist without conflict. The Microsoft Java Package Manager stores packages in a global namespace and searches there for packages if no namespace is specified to its API elements (for example, the contents of classes.zip is stored in the global namespace). Be aware that applications running in the namespace specified with the /n switch cannot access other namespaces.

/p

Causes jview to pause before exiting if an error occurs. You can use this to determine the user interface state just prior to the error when debugging an application.

/prof[:<parameter>, <parameter>, …]

The parameters shown in the following table can be used.

Parameter | Description
call[time]s[=<methods>] | Shows time execution in the specified methods.
calltrace[=<methods>] | Prints entry and exit messages.
callparams[=<methods>] | Prints parameters and return values.
permethodalloc | Counts per-method allocations.
perclassalloc | Counts per-class allocations.
gc | Prints per-garbage-collection heap information.
heapdump | Dumps a list of live objects at each garbage collection.
file=<filename> | Appends profiling output to the specified file.
sample[=<frequency>] | Samples method locations with the given frequency.
verbose | Prints class loads and thread creations.
table | Prints tabular output in simple space-delimited form.

For examples of how to use /prof with its parameters and view the profiler results, see the Jview Profiler Sample in the \Samples\Profiler\jviewprf directory (Samples Overview).

/v

Causes jview to verify all invoked methods. Without this option, only methods from untrusted loaders are verified. The verification process is applied to bytecode that is loaded from the class files. This ensures that they don't pose a security threat. For remotely loaded class files, the Microsoft virtual machine (Microsoft VM) only allows a subset of the total functionality possible with bytecode. Verification enforces this: If your class files attempt to do anything illegal, they are rejected.

For performance reasons, local system classes are not normally verified. The /v option forces the verifier to process these. Use this option to ensure that a set of class files will pass the verifier.

/vst

Prints verbose stack traces; must be used with debug classes.

/?

Displays jview usage information including a list of command-line options.


Nmake

The Microsoft Program Maintenance Utility (Nmake) builds projects based on commands contained in a description file (makefile).

Use the one of the following command to run Nmake:

nmake [@commandfile]

nmake [options] [macros] [targets]

Nmake Command-Line Arguments

options | One or more Nmake options.
macros | One or more Nmake macros.
targets | Files to be built.
@commandfile | A command file listing options and file specifications to be used by Nmake. For more information, see Command Files.

Nmake Command-Line Options

/a /b /c /d /e /f /help, /? /i /k /n /nologo /p /q /r /s /t /u /x /y

Usage Notes

Nmake only builds specified targets or, if none are specified, the first target in the makefile. The first makefile target can be a pseudo-target that builds other targets. Nmake uses makefiles specified with /f. If /f is not specified, it uses the Makefile file in the current directory. If no makefile is specified, it uses inference rules to build command-line targets.

Use the @commandfile argument to specify a separate command file that supplies command-line input. Other input can precede or follow @commandfile. A path is permitted.

Nmake options may be preceded by either a forward slash (/) or a hyphen (–) and are not case-sensitive. Use !CMDSWITCHES to change option settings in a makefile.

See Also

Nmake Options

Nmake Exit Codes

Command Files


Nmake Options

This section describes the command-line options that can be used with Nmake.

/a

Forces a build of all evaluated targets, even if not out-of-date with respect to dependents. Does not force a build of unrelated targets.

/b

Forces a build even if timestamps are equal. Recommended only for very fast systems (resolution of two seconds or less).

/c

Suppresses default output, including nonfatal Nmake errors or warnings, timestamps, and Nmake copyright message. Suppresses warnings issued by /k.

/d

Displays timestamps of each evaluated target and dependent, and a message when a target does not exist. Useful with /p for debugging a makefile.

Use !CMDSWITCHES to set or clear /d for part of a makefile.

/e

Causes environment variables to override makefile macro definitions.

/f makefile

Specifies a makefile. Spaces or tabs can precede the makefile name. Specify /f once for each makefile. To supply a makefile from standard input, specify a hyphen (–) for the file name, and end the keyboard input with either F6 or CTRL+Z.

/help, /?

Displays Nmake usage information including a list of command-line options.

/i

Ignores exit codes from all commands. To set or clear /i for part of a makefile, use !CMDSWITCHES. To ignore exit codes for part of a makefile, use a hyphen (–) command modifier or .IGNORE. If both are specified, overrides /k.

/k

Continues building unrelated dependencies, if a command returns an error. Also issues a warning and returns an exit code of 1. By default, Nmake halts if any command returns a nonzero exit code. Warnings from /k are suppressed by /c. If both are specified, /i overrides /k.

/n

Displays but does not execute commands; preprocessing commands are executed. Does not display commands in recursive Nmake calls. Useful for debugging makefiles and checking timestamps. To set or clear /n for part of a makefile, use !CMDSWITCHES.

/nologo

Suppresses the Nmake copyright message.

/p

Displays Nmake information (macro definitions, inference rules, targets, .SUFFIXES list) to standard output, and then runs the build. If no makefile or command-line target exists, it only displays information. Use with /d to debug a makefile.

/q

Checks timestamps of targets but does not run the build. Returns a zero exit code if all targets are up-to-date and a nonzero exit code if any target is not. Preprocessing commands are executed. Useful when running Nmake from a batch file.

/r

Clears the .SUFFIXES list and ignores inference rules and macros that are predefined.

/s

Suppresses display of executed commands. To suppress display in part of a makefile, use the @ command modifier or .SILENT. To set or clear /s for part of a makefile, use !CMDSWITCHES.

/t

Updates timestamps of command-line targets (or first makefile target) and executes preprocessing commands, but does not run the build.

/u

Dumps inline Nmake files so that the /n output can be used as a batch file. Must be used in conjunction with /n.

/x <filename>

Sends Nmake error output to the specified file name instead of standard error. Spaces or tabs can precede the file name. To send error output to standard output, specify a hyphen (–) for file name. Does not affect output from commands to standard error.

/y

Disables batch-mode inference rules. When this option is selected, all batch-mode inference rules are treated as regular inference rules.


Nmake Exit Codes

Nmake returns the exit codes as shown in the following table.

Nmake Exit Codes

0 | No error (possibly a warning).
1 | Incomplete build (only issued when /k is used).
2 Program error, possibly due to:
  • A syntax error in the makefile.

  • An error or exit code from a command.

  • An interruption by the user.
4 | System error, out of memory.
255 | Target is out-of-date (only issued when /q is used).


Qvue

The Java Class Viewer (qvue) prints out class method signatures and identifies .class files that were generated from a type library.

Use the following command to run qvue:

qvue classname

Qvue Command-Line Arguments

classname Specifies the name of the .class file to inspect. Qvue supports wildcards.

Qvue Command-Line Options

/s

Usage Notes

Qvue is convenient for selecting the correct class file to use when the class files are generated from a type library using jactivex.

See Also

Jactivex


Qvue Options

This section describes the command-line options that can be used with Qvue.

/s

This option causes qvue to print a synopsis of the class within the class file.


Wjview

The Java Window Viewer (wjview) executes Java applets and applications from the command line and spawns a separate window process.

Use the following command to run wjview:

wjview [options] <classname> [arguments]

Wjview Command-Line Arguments

options | One or more wjview options.
classname | Name of the .class file to execute. Do not use the .class extension with this file name.
arguments | Command-line arguments to be passed to the .class file supplied in the classname parameter.

Wjview Command-Line Options

/a /cp /cp:a /cp:p /d /n /p /prof /v /vst /?

Usage Notes

Use wjview to launch window-based Java applications and applets. Wjview is the same as jview, except that wjview runs the application as a separate graphical user interface (GUI) process and does not use or require a console window. Consequently, you do not use wjview for Java applications that require output to or input from the console window.

See Also

Wjview Options

AppletViewer

CLASSPATH Environment Variable

Jview


Wjview Options

This section describes the command-line options that can be used with wjview.

/a

Invokes the use of the Microsoft AppletViewer. Applets viewed with the Microsoft Applet Viewer function the same as when viewed with a browser, including sound, loading, security features, and so on. When the applet viewer switch is used, all other remaining command-line tokens become parameters that are used by the AppletViewer.

/cp <classpath>

Sets the CLASSPATH environment variable. This option specifies the path where wjview can find system and user-defined classes. The Java interpreter uses a platform-dependent default location and the CLASSPATH environment variable to find system classes. For more information, see CLASSPATH Environment Variable. The directories in the class path are separated by semicolons on a Microsoft® Windows® system; on UNIX, by colons.

/cp:a <path>

Appends the path entered to the end of the existing class path and inserts a semicolon (;) between them.

Note The value for the existing class path can come from the CLASSPATH environment variable or from the /cp option. When multiple /cp:a switches are entered, the paths are concatenated.

For example, the following command concatenates the directories myproj1 and myproj2, and appends the resulting path to the end of the existing class path:

wjview /cp:a myproj1 /cp:a myproj2

/cp:p <path>

Prepends the path entered to the beginning of the existing class path and inserts a semicolon (;) between them.

The value for the existing class path can come from the CLASSPATH environment variable or from the /cp option. When multiple /cp:p switches are entered, the paths are concatenated.

For example, the following command concatenates the directories myproj1 and myproj2, and inserts the resulting path before the existing class path:

wjview /cp:p myproj1 /cp:p myproj2

/d:<property=string value>

Sets a system property.

/n namespace

Specifies a namespace to run an application in. Separate namespaces allow Java packages with identical names to exist without conflict. The Microsoft Java Package Manager stores packages in a global namespace. It is searched for packages if no namespace is specified by its API elements (for example, the contents of classes.zip is stored in the global namespace). Be aware that applications running in the namespace specified with the /n switch cannot access other namespaces.

/p

Causes wjview to pause before exiting if an error occurs.

/prof[:<parameter>, <parameter>, …]

The parameters shown in the following table can be used.

Parameter | Description
call[time]s[=<methods>] | Shows time execution in the specified methods.
calltrace[=<methods>] | Prints entry and exit messages.
callparams[=<methods>] | Prints parameters and return values.
permethodalloc | Counts per-method allocations.
perclassalloc | Counts per-class allocations.
gc | Prints per-garbage-collection heap information.
heapdump | Dumps a list of live objects at each garbage collection.
file=<filename> | Appends profiling output to the specified file.
sample[=<frequency>] | Samples method locations with the given frequency.
verbose | Prints class loads and thread creations.
table | Prints tabular output in simple space-delimited form.

For examples on how to use /prof with its parameters and view the profiler results see the Jview Profiler Sample in the Profiler Samples directory (Samples Overview.

/v

Verifies all invoked methods (normally, only methods from untrusted loaders are verified).

/vst

Prints verbose stack traces; must be used with debug classes.

/?

Displays wjview usage information including a list of available options.


Native Code and COM Tools

The Microsoft SDK for Java provides these tools for working with native code and COM.

Guidgen generates a globally unique identifier (GUID).

Jactivex hosts automation-enabled Microsoft® ActiveX® Controls in Java and generates Java source from type libraries.

Javah generates C header and source files from a Java class.

Javareg registers Java classes as COM components in the Microsoft® Windows® registry.

Msjavah generates C language header files for Java classes.

Resmerge combines multiple Microsoft® Win32® resource (.res) files into a single file.

Vjreg also registers Java classes as COM components in the registry. With vjreg, you can register multiple Java classes in one execution.


Guidgen

The GUID Generator (guidgen) generates a globally unique identifier (GUID).

Use the following command to run guidgen:

guidgen

Usage Notes

Guidgen displays a dialog box in which you specify the format of the GUID definition. You can then save the definition to the Clipboard and paste it into your source file. For more information about using this utility, press F1 in the guidgen dialog box to open a Help window.


Jactivex

The Java/ActiveX Integration Utility (jactivex) hosts automation-enabled ActiveX Controls in Java and generates Java source from type libraries.

Use the following command to run jactivex:

jactivex [options] <filename>

Jactivex Command-Line Arguments

options | One or more jactivex options.
filename | When run in default mode, this is the name of the ActiveX file to create a wrapper for. Otherwise, if you use /javatlb option and any other options, this is the name of the type library that the Java source will be generated from.

Jactivex Command-Line Options

/ao[+|-] /bx /ci:as /d /e /G5 /is[+|-] /javatlb /l /nologo /p /p:b- /r /t /udi[+|-] /w /wec /wfc /WX /xi /X:m- /X:rkc /X:s2 /X:vi /?

Jactivex /javatlb Options

/b /c2j /creg /G3.1 /j /n /x2 /xc /xd- /xh

Usage Notes

Jactivex replaces both javatlb and jcom. By default, jactivex is used to host automation-enabled ActiveX controls in Java. To access typelib features, you must use the /javatlb command-line option to activate the other options described in the Jactivex Options section.

The default operation is to create a JavaBean wrapper for an ActiveX Control. Jactivex creates IDispatch wrappers for an ActiveX object using code and helper objects that are similar to JavaBeans to add and remove listeners for the ActiveX event interfaces.

You can also use jactivex to generate .java files for the classes and interfaces described in a type library. These .java files, once compiled into .class files, allow Java programs to use Component Object Model (COM) services. Jactivex uses COM type library information to create Java classes that represent COM interfaces. See Using COM Objects in Java for details.

Jactivex also inherits all the capabilities of the jcom utility (released in previous versions of the Microsoft SDK for Java) to generate Java source files from type libraries. These operations are performed with /javatlb, but are otherwise the same as with the jcom utility.

When run in default mode, <filename> is the name of the ActiveX file to create a wrapper for.

The following command creates a JavaBean wrapper for an ActiveX Control:

jactivex mscal.ocx

Otherwise, if you use /javatlb option and any other options, this is the name of the type library or .dll that the Java source will be generated from.

!WARNING Do not use a version of the Microsoft® Visual J++® compiler earlier than 1.02.3920 to compile the files generated by this tool.

Jactivex allows and correctly generates attributes for fields that are of type:

  • Interface pointer (type=OBJECT)

  • Embedded structure

  • Pointer to structure (type=ptr)

  • Embedded array of primitive type (type=FIXEDARRAY)

See Also

Jactivex Options

Jactivex /javatlb Options

JNF File Type Information

Using COM Objects in Java


Jactivex Options

This section describes the command-line options that can be used with jactivex.

/ao[+|-]

The auto-offset structures are turned off by default. Turn on the auto-offset structures with /ao+ or /ao to make them more portable between Win32 and Win64 platforms. The auto-offset structures will only work correctly if all fields are fully represented. If any fields are generated as UNMAPPABLE, the Microsoft VM will be unable to determine the correct offset for fields that come after the UNMAPPABLE field. This can lead to corrupted data and access violations.

/bx[+ | -] [!]

Exposes OCX files as JavaBeans.

/ci:as

Creates EventInfo entries for all source interfaces (Windows Foundation Classes only).

/d <directory>

Specifies the base directory where the package directory will be placed. For example, the following command will create the widgets package directory in the C:\MyPackages directory and place all generated .java files in C:\MyPackages\Widgets.

jactivex /javatlb /d c:\mypackages widgets.tlb

Note When the .tlb is embedded in the .dll as a resource, the following command can also be used:

jactivex /d . /javatlb component.DLL

By default, the base directory is the value specified in the registry HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\TrustedLibsDirectory. The installation of the Microsoft VM sets this to %Windir%\java\trustlib.

/e

Generate files only for type libraries explicitly listed on the command line. This option allows you to set command-line options on a per-typelib basis. This may cause generation of .java files that reference unresolved names or packages.

If /e is not specified, jactivex will recursively compile type libraries needed to resolve all references.

/G4

This option targets the Microsoft VM in the Microsoft SDK for Java version 4.0.

/G5

This option generates classes that use features of the 32xx series of the Microsoft virtual machine (Microsoft VM). This option is turned on by default. size_is and iid_is information is propagated from a .tlb file to a Java class file. If you do not place explicit custom attributes in your IDL files (see javaax.h), the generated class will be usable on any Internet Explorer 4.0 or later version of the Microsoft VM.

/is [+|-]

This enables or disables the generation of size_is and iid_is attributes. The COM iid_is and size_is sample in %SDKDIR%\Samples\COM\iid_is_size_is demonstrates how to create an interface that uses the iid_is and size_is marshaling support of the Microsoft VM and jactivex.

/javatlb

Javatlb compatibility mode accesses COM integration features not available in default mode (generates Java source from type libraries). Use /javatlb to integrate COM objects into Java programs. To access lower-level COM integration features with the jactivex utility, use the /javatlb option and any combination of other options. See Jactivex /javatlb Options for a list of additional options that can be used with /javatlb.

When the .tlb is embedded in the .dll as a resource, both of the following commands work:

/javatlb <file name>.dll
/javatlb <file name>.tlb

/l <listfile>

Generates a text file listing every .java file created by jactivex. This text file can serve as an input file to jvc and can also be used to find out where and what files jactivex created.

For example, the following command line creates a file called mylist.lst, which can then be used as an input file to jvc:

jactivex /javatlb /l myfiles.lst widget.tlb

jvc @myfiles.lst

If a relative path is given for the response file, it is placed in the current directory. Its location is not affected by the /d option.

/nologo

Suppresses the Microsoft copyright message.

/p <package name>

Specifies the target directory for .java files generated by jactivex as shown in the following example.

Example

jactivex /javatlb /p gremlinsoft widgets.tlb

This example command line places the .java files in C:\%Windir%\Java\TrustLib\MyCompany\Widgets directory. With this option, you can define a company-specific directory tree that contains the .java files for all the COM objects produced by your company. The package parameter can have multiple levels. For example, the following command would place the .class files in the directory C:\%Windir%\Java\TrustLib\MyCompany\MySample\Widgets.

jactivex /javatlb /p mycompany.mysample widgets.tlb

To use these classes in your Java program, specify an import statement of the following form in your source code:

import mycompany.mysample.widgets.*;

/p:b-

Includes or excludes the base name as the package for the converted class. For example, if you are converting Widgets.tlb to Java classes, this option will create a package called widgets. Because the default is to use the base name as the package, this option is generally followed by a hyphen (-) to disable the automatic creation of the package directory. This places the created .java files in the default package directory (Java\TrustLib or the directory specified in the /d option). For example, the following command places all class files in the C:\MyPackages directory:

jactivex /javatlb /p:b- /d c:\mypackages widgets.tlb

/r

Registers type libraries specified on the command line.

/t <jnffile>

Specifies a .jnf file for type conversions. For more detailed type information on jnf files go to the JNF File Type Information.

/udi [+|-]

Causes jactivex to use the IID of IDispatch instead of using the IID of the default dispinterface. This option is turned on by default.

/w

Disables all warnings.

/wec

Sets exit code to Warning.

/wfc[!]

Exposes .ocx files as WFC controls.

/WX

Treats warnings as errors. This prevents any output files from being generated if a warning is reported.

/xi

Causes the method declarations and COM declarations to be duplicated in the coclass files. This simplifies using COM objects from Java because default interface methods can be called directly on the object without first casting to an interface pointer. That is, without /xi, the code would look like the following example:

IBeeper b = (IBeeper)new Beeper();
b.beep();

Using /xi, this can be simplified as follows:

Beeper b = new Beeper();
b.beep();

In addition, this form speeds up method invocation. The trade offs are that the coclass files are larger and any manual changes to the information generated by jactivex must be made in both the coclass and the interface.

/X:m-

Disables thread switching. By default, the Microsoft VM assumes that all COM objects passed as parameters are non-thread-safe. The VM also performs background thread-switching to ensure that such objects are called on the correct thread. Using this option disables this extra thread-switching. Use this option when you've designed a new thread-safe COM library.

/X:rkc

For coclasses; looks for Control registry key.

/X:s2

Represents unsigned 2-byte integers as char.

/X:vi

Represents void pointers as int.

/?

Displays command-line Help and usage.

Jactivex /javatlb Options

This section describes additional jactivex options that can be used with the /javatlb option.

/b[+|-]

Uses the JavaBeans design pattern for properties. For example, by default, a read-write property named "a" becomes mapped to property accessor methods named "geta" and "puta". If the "/b" flag is specified, the names "getA" and "setA" will be used instead. In addition, the property is exposed to COM by the name "A" only. It is not possible to access the names "getA" or "setA" from COM (these names were exposed only for compatibility with javatlb).

/c2j

Generates implementation classes for coclass entries; does not generate wrapper classes.

/creg

Generates @com.register directives for coclass wrappers (JCWs).

/G3.1

Prevents use of features that are not supported by the virtual machine in Microsoft® Internet Explorer version 3.1. Disabled by default.

/j

Generates Java source files without the extended COM information. As a result, these source files can be browsed more easily and will compile. They will not, however, integrate with COM if they are loaded into the Microsoft VM.

/n <jnffile>

Specifies an optional .jnf file, which supplies extra information on how to convert the type library. The .jnf file is a text file that has the following format:

[Custom]
   <typename>=<javatype>,<javamarshalertype>
      ...

The purpose of the .jnf file is to inform jactivex that certain types are to be marshaled using a COM Custom Marshaling hook class. For more detailed type information on jnf files go to the JNF File Type Information.

/x2

Maps VT_I2 and VT_UI2 to Java char rather than Java short. By default, these types are mapped to Java short for compatibility with javatlb.

/xc

Ignores coclasses in typelib.

/xd-

Suppresses creation of default versions of the .java files. Jactivex normally creates two .java files for each dispinterface: one that is used when the interface is the default for a coclass, and one that is used when the interface is not the default. The default versions of the java files are needed only to implement the interface using Java. Suppressing the creation of default versions can speed up compilation considerably on large type libraries.

/xh

Modifies translation of HRESULT types so that only HRESULT return types that have the high (FAIL) bit set cause Java exceptions. Non-failing HRESULTs (such as S_FALSE) are treated as if they were S_OK.


JNF File Type Information

JNF files are formatted like standard .ini files. For a given native type, OriginalTypeName, with associated GUID, G, jactivex will search section [G] in the JNF file for the following key/value pairs:

Use Class=<UseClassTypeName>

UseClassTypeName must be a fully-qualified Java type name in dotted form (for example, com.ms.wfc.ax.IFont).

If the Use Class key is defined, jactivex will replace all occurrences of type OriginalTypeName with UseClassTypeName. Furthermore, jactivex will generally not generate a Java wrapper for OriginalTypeName. Realistically, this keeps jactivex from using a generated type (for example, stdole2.IFont) when you would rather use your own standard type (for example, com.ms.wfc.ax.IFont).

Conversion Info=<NewTypeName>,<OldToNewConversionMethod>,<NewToOldConversionMethod>

NewTypeName must be a fully-qualified Java type name in dotted form (for example, com.ms.wfc.ui.Font) and both OldToNewConversionMethod and NewToOldConversionMethod must be fully-qualified Java method names in dotted form (for example, com.ms.wfc.ui.AxHost.getIFontFromFont and com.ms.wfc.ui.AxHost.getIFontFromFont).

Jactivex uses the information given by this key only when generating a coclass wrapper. Let OldClassName be UseClassTypeName if the Use Class key is present; otherwise, it should be OriginalTypeName. This key specifies that objects of type OldClassName should be converted to and from NewTypeName, using methods OldToNewConversionMethod and NewToOldConversionMethod.

The specified conversion methods must have the following signatures:

NewTypeName OldToNewConversionMethod( OldTypeName obj )

OldTypeName NewToOldConversionMethod( NewTypeName obj )

Properties=<comma delimited list of values from {editable}>

Currently, the only defined property is editable. If specified, jactivex will consider the type OriginalTypeName as editable. This is important: in generated WFC wrappers, PropertyInfo's are created only for properties of an editable type (primitive types, strings, and anything marked with this new editable property).

The following is a sample JNF file:

; this section is for IFont.
[{bef6e002-a874-101a-8bba-00aa00300cab}]
Use Class=com.ms.wfc.ax.IFont
Conversion Info=com.ms.wfc.ui.Font,com.ms.wfc.ui.AxHost.getFontFromIFont,com.ms.wfc.ui.AxHost.getIFontFromFont
Properties=editable

; this section is for OLE_COLOR.
; notice the lack of the 'Use Class' key, since OLE_COLOR is really an int.
[{66504301-BE0F-101a-8bbb-00aa00300cab}]
Conversion Info=com.ms.wfc.ui.Color,com.ms.wfc.ui.AxHost.getOleColorFromColor,com.ms.wfc.ui.AxHost.getColorFromOleColor
Properties=editable


Javah

The C Header and Stub File Generator Utility (javah) produces C header and source files from a Java class. These files allow Java and C code to interact.

Use one of the following commands to run javah.

javah [options] [classname]

Javah Command-Line Arguments

options | One or more javah options.
classname | Java class file to generate C code from.

Javah Command-Line Options

-classpath -d -jni -o -stubs -td -trace -version -v

Usage Notes

Javah generates C header and source files that are needed to implement native methods. The generated header and source files are used by C programs to reference an object's instance variables from native source code. The .h file contains a struct definition whose layout parallels the layout of the corresponding class. The fields in the struct correspond to instance variables in the class.

The name of the header file and the structure declared within it are derived from the name of the class. If the class passed to javah is inside a package, the package name is prepended to both the header file name and the structure name. Underscores (_) are used as name delimiters.

By default javah creates a header file for each class listed on the command line and puts the files in the current directory. Use the -stubs option to create source files. Use the -o option to concatenate the results for all listed classes into a single file.

The native method interface, Java Native Interface (JNI), does not require header information or stub files. Javah can still be used with the -jni option to generate the native method function prototypes needed for JNI-style native methods. The result is placed in the .h file.

Note You must set the CLASSPATH environment variable to make sure this tool works. You can set your class path directly on the command line or use the javah -classpath option. Set your class path to C:\%Windir%\Java\Classes\Classes.zip. To make sure you have the latest classes installed, you should also run clspack –auto after setting the class path. If you see the message "java.lang.Object not found: aborting" when you run javah, type clspack –auto, let it run, and then try running javah again.

See Also

Javah Options


Javah Options

This section describes the command-line options that can be used with javah.

-classpath <path>

Specifies the path javah uses to look up classes. Overrides the default or the CLASSPATH environment variable if it is set. Directories are separated by semi-colons. The general format for path is:

.;<your_path>

For example:

.;C:\users\dac\classes;C:\tools\java\classes

-d <directory>

Specifies the directory where javah saves the header or stub files.

-help

Prints out the options.

-jni

Creates an output file containing JNI-style native method function prototypes.

-o <output file>

Concatenates the resulting header or source files for all the classes listed on the command line into the specified output file.

-stubs

Causes javah to generate C declarations from the Java object file.

-td <directory>

Specifies the directory where javah stores temporary files. By default, javah stores temporary files in the directory specified by the %TEMP% environment variable. If %TEMP% is unspecified, then javah checks for a %TMP% environment variable. If %TMP% is unspecified, javah creates the directory C:\tmp and stores the files there.

-trace

Adds tracing information to stubbs file.

-version

Prints out the build version.

-v

Prints a message to standard output concerning the status of the generated files.


Javareg

The Java Register Utility (javareg) registers Java classes as COM components in the Microsoft® Windows® registry. (A similar tool, vjreg, is also provided, that allows you to register multiple Java classes in one execution.)

Use the following command to run javareg:

javareg [/?] | [/register | /unregister [/class:<Java class> [options] ]]

Javareg Command-Line Arguments

/class:<Java class> | The class to be registered or unregistered.
options | One or more javareg options.

Javareg Command-Line Options

/class /clsid /codebase /control /nomktyplib /progid /q /register /remote /surrogate /typelib /unregister /?

See Also

Javareg Options

Vjreg


Javareg Options

This section describes the command-line options that can be used with javareg.

/class:<class name>

Specifies the name (<class name>) to be registered or unregistered with the class identifier (or with the CLSID generated by javareg if no class identifier is provided).

If this option is specified, either /register or /unregister must also be specified. For example, the following command line will cause javareg to register the Java class Pager:

javareg /register /class:Pager

Because /clsid:<clsid> is not specified, javareg will automatically generate a UUID to be used as the CLSID for the class (it uses the COM API CoCreateGUID).

If you execute javareg again with the same Java class name, javareg will reuse the CLSID already assigned to the Java class. As such, you can execute javareg with additional options later to reconfigure the class (for example, by specifying the /surrogate option).

/clsid:<CLSID>

Specifies the class identifier (<CLSID>) to be registered with the class. Omit this parameter to force javareg to create a CLSID.

For example, the following command will cause javareg to register the Java class Pager using the CLSID {2488D68A-D3BF-11D0-A145-080036006703}:

javareg /register /class:Pager
    /clsid:{2488D68A-D3BF-11D0-A145-080036006703}

/codebase:[path]

Specifies the base location, either a URL or a directory name, that contains the Java class. This option can be used with /register as a part of registering a JavaBeans object as an ActiveX Control.

/control

Adds the necessary registry information for containers to treat the Java class as an ActiveX Control. This option can be used with /register as a part of registering a JavaBeans object as an ActiveX Control. If you use this option, you must also use /typelib.

/nomktyplib

Registers an existing typelib, specified in the file name argument of the /typelib option, without creating a new one.

/progid:<PROGID>

Specifies a ProgID for the class being registered.

By default, javareg does not assign a COM ProgID to your class. This option lets you designate what ProgID to use. For example, the following command will cause javareg to register the Java class Pager and assign it the ProgID called Pager.Java.1.

javareg /register /class:Pager /progid:Pager.Java.1

/q

Quiet mode; suppresses all message boxes. Regardless of whether this option is specified, javareg will return 0 (zero) on success or 1 upon failure.

/register

Registers class specified in the /class parameter with the class identifier specified in /clsid. If you use /register, you must specify at least /class as well. You can, however, also use /register with /class, but without the class identifier. This forces javareg to create a CLSID and register it.

Javareg also recognizes /regserver for this command.

You can use /codebase, /control, and /typelib with /register to register a JavaBean object as an ActiveX Control. Note that if you use /control to register a JavaBean, you must also generate a type library using /typelib as shown in the following example:

javareg /register /class:[classname] /codebase:[filename|URL]
        /control /typelib:[filename]

/remote:<RemoteServerName>

Activates the class on a remote server using Distributed Component Object Model (DCOM).

If you want to activate and call a Java class on a different computer using DCOM, use /remote on the client computer. When using this option, the Java class cannot be activated on the client computer—only on the server. The <RemoteServerName> can be any computer identifier supported by distributed COM. Typically, it can be a NetBIOS name, a Domain Name System (DNS) name, or a decimal-dotted IP address.

The following example explains the necessary steps for using this functionality.

  1. Write a Java class with some public members (for example, Pager.java).
    class Pager
{
   public boolean Page(String PhoneNumber, String PIN, String Msg)
   {
      System.out.println("Page request received. Sending.");
      System.out.println(" Phone: " + PhoneNumber);
      System.out.println(" PIN: " + PIN);
      System.out.println(" Message: " + Msg);
      return true;
   }
}
  2. Compile the Java source (into Pager.class, for example), and move the .class file to your trusted class library directory on the server (for example, C:\Winnt\Java\TrustLib\).

  3. On the server, run javareg. The following code shows the Pager example:
    javareg /register /class:Pager /progid:Pager.Java.1
        /clsid:{2488D68A-D3BF-11D0-A145-080036006703}
        /surrogate
  4. On the client, run javareg. The following shows the Pager example (replace <YourServerName> with the name of the server in the previous step):
    javareg /register /class:Pager /progid:Pager.Java.1
        /clsid: :{2488D68A-D3BF-11D0-A145-080036006703}
        /remote:yourservername

Now you can use Microsoft® Visual Basic® to create an instance of Pager.Java.1. For example:

Dim x As Object
Set x = CreateObject("Pager.Java.1")
fSuccess = x.Page ("555-1212", "1234", "Call Home!")

The Pager class will be activated and will run remotely on <RemoteServerName>.

/surrogate

Supports remote access to COM classes. Writes the registry entries required to allow the Java class to be activated out-of-process. This is necessary if you want your Java class to be activated and called from a different computer. In other words, you use the /surrogate option when registering your Java class to run as a DCOM server.

For example, the following command causes javareg to register the Java class Pager so it can be run from a different computer and accessed through DCOM:

javareg /register /class:Pager
        /clsid:{2488D68A-D3BF-11D0-A145-080036006703}
        /surrogate

Notice that it is not strictly necessary to specify the CLSID when using /surrogate. If you do not, javareg will generate one.

/typelib:<filename>

Generates a type library for a Java class at the specified <filename's> location. To register a typelib without generating a new one, use this option with /nomktyplib. This option can also be used with /register as a part of registering a JavaBeans object as an ActiveX Control.

/unregister

Unregisters the class specified in the /class parameter. If you specify /unregister, you must specify /class:<classname> as well. Notice that javareg will also recognize /unregserver for this command.

/?

Displays usage information including a list of command-line options.


Msjavah

The Header File Converter for Java (msjavah) generates C language header files for Java classes.

Use the following command to run msjavah:

msjavah [options] <classes>

Msjavah Command-Line Arguments

options | One or more msjavah options.
classes | Names of the Java classes to create a C header file for. This argument is required.

Msjavah Command-Line Options

/classpath /ctors /d /helpers /noclinit /nocppconsts /nologo /nowarn /nowritebarrier /o /portable /v /?

Usage Notes

Unlike other utilities, you must give a Java class reference instead of a file name for the given class, as in the following example:

msjavah java.lang.Thread

One command can create multiple headers, and unless the /o option is included, a header file will be created for each class. For example, the following command line produces two header files, java_util_Hashtable.h and java_lang_System.h.

msjavah java.util.Hashtable java.lang.System

In contrast, the following command line generates a file called headers.h, which includes both classes.

msjavah /o headers.h java.util.Hashtable java.lang.System

Use the /portable option to create headers that suppress pragmas specific to the Microsoft compiler (and other compiler information) to ease portability. The following command line produces a portable file called headers.h, which includes several classes.

msjavah /o /portable headers.h java.util.Hashtable
    java.lang.System java.lang.Thread

Use the /helpers and /ctors options with the msjavah utility to generate inline Raw Native Interface (RNI) wrapper method calls. For example, the following class has a constructor and a static and a dynamic method.

class sample {
   void dynamicMethod (int i) {}
   static void staticMethod (String s) {}
   sample (int i1, int i2) {}
}

The msjavah utility generates the following native code.

C:\..\>msjavah /helpers /ctors sample

void nativeMethod () {
   GCFrame gcf;
   struct gc {
      Hsample *sample;
   };
   GCFramePush(&gcf, &gc, sizeof(gc));
#ifdef __cplusplus
   // Note that arguments are presented before the
   // class name, as arguments to the new operator
   // and not directly to the constructor.
   // Generated by /ctors.
   gc.sample = new (3, 10) Hsample;
   // Generated by /helpers.
   gc.sample->dynamicMethod(5);
#else
   /* Generated by /ctors */
   gc.sample = new_sample(3, 10);
   /* Generated by /helpers */
   sample_dynamicMethod(gc.sample, 5);
#endif
   /* Generated by /helpers */
   sample_staticMethod(makeJavaString("Hello", 5));
   GCFramePop(&gcf);
}

See Also

Msjavah Options


Msjavah Options

This section describes the command-line options that can be used with msjavah.

/classpath <pathname>

Sets an alternate class path to search in addition to the CLASSPATH environment variable.

/ctors

Generates inline wrapper methods for constructing new Java objects through the execute_java_constructor API. This option is similar to /helpers; incompatible changes to constructors result in compilation errors rather than run-time errors.

/d <directory>

Specifies an output directory to place the header files. This option is ignored if the file name used with the /o option includes absolute pathnames.

/helpers

Generates inline wrapper methods for making static and non-static Java calls through the execute_java_dynamic_method and execute_java_static_method RNI APIs. The /helpers option allows incompatible changes to a Java method's signature to result in compilation errors rather than run-time errors.

/noclinit

Does not run class initializers in any specified classes. By default, msjavah attempts to run initializers. If the initializers fail, a warning message is displayed and the class is reloaded without running the initializers.

/nocppconsts

Generates C++ const declarations for static final fields.

/nologo

Suppresses the Microsoft copyright message.

/nowarn

Suppresses warning messages.

/nowritebarrier

Produces headers without const declarations of object member fields. Newer implementations of the Java garbage collector require all members of objects that are object references be modified with the GCSetObjectReferenceForObject API. As a result, these fields are generated as const fields. Pragmas for the Microsoft compilers are generated to disable the appropriate warnings encountered when the compiler fails to generate default constructors. To ensure portability, the /portable option suppresses these pragmas.

/o <outfile>

Specifies the output filename of the header file. By default, a separate header name is generated for each class name based on the class name. With this option specified, all classes are generated in the header file specified by <outfile>.

/portable

Generates headers without enhancements specific to the Microsoft compiler (pragmas and so on).

/v

Specifies verbose output.

/?

Displays msjavah usage information including a list of available options.


Resmerge

The Win32 Resource File Merging Utility (resmerge) combines multiple Microsoft® Win32® resource (.res) files into a single file.

Use the following command to run resmerge:

resmerge [-a] <targetfile> <resourcefile> <resourcefile> …

Resmerge Command-Line Arguments

targetfile | The primary resource file that other resource files will be appended to.
resourcefile | Additional resource files that are appended to the target file.

Resmerge Command-Line Options

-a Appends the specified resource files to the first named resource file (the target file).


Vjreg

Vjreg is a command-line tool that registers Java classes as COM components in the Microsoft® Windows® registry. This tool is similar to javareg, but allows you to register and create type libraries for multiple Java classes in one execution.

Use the following command to run vjreg:

vjreg [options] <class files>

Vjreg Command-Line Arguments

options | One or more vjreg command-line options.
class files | Java class files to be registered.

Vjreg Command-Line Options

/cp:p /noinvoke /nologo /nowarn /regtypelib /typelib /unreg /unregclasses /vbr

See Also

Vjreg Options

Javareg


Vjreg Options

This section describes the command-line options that can be used with vjreg.

/cp:p <path>

Prepends path to the class path for type library creation.

/noinvoke

Does not invoke user code during registration.

/nologo

Suppresses the Microsoft copyright message.

/nowarn

Does not display warning messages.

/regtypelib <type library>

Registers an existing type library.

/typelib <filename> <options>

Creates a type library with the specified filename. The following additional options can be specified with /typelib:

/name <name>

Specifies the internal name of the type library.

/description <description>

Specifies the description of the type library.

/helpfile <filename>

Specifies the type library's help file name.

/helpcontext <number>

Specifies the type library's help context identifier.

/unreg

Unregisters both classes and the type library.

/unregclasses

Unregisters classes only (leaving the type library registered).

/vbr <filename>

Generates a .vbr file that contains remote server information.


Software Distribution Tools

The software distribution tools included with the Microsoft SDK for Java include the following.

Cabarc handles the archiving of multiple files in a compressed format.

Cert2spc creates a Software Publisher's Certificate (SPC) from one or multiple X.509 certificates (for test purposes only).

Certmgr manages certificates, certificate trust lists (CTLs), and certificate revocation lists (CRLs).

Chkjava allows users to view security information placed in a cabinet file by the signcode tool with the JavaSign DLL.

Chktrust checks the validity of a file.

Cprmedit edits Java permissions for security zones recognized by Microsoft® Internet Explorer 4.0 and later.

Dubuild writes an Open Software Distribution (OSD) file and places it in a cabinet file archive with any specified contents.

Makecert generates a test X.509 certificate.

MakeCTL creates a certificate trust list (CTL) and saves the encoded CTL to a certificate store or to a file.

Piniedit creates and edits .ini files for use with the signcode tool.

Setreg changes registry settings.

Signcode signs a cabinet file with Java permissions.


Cabarc

The Cabinet File Archiving Utility (cabarc) handles the archiving of multiple files in a compressed format.

Use the following command to run cabarc:

cabarc [options] <command cabfile> [@filename.txt] [files] [dest_dir]

Cabarc Command-Line Arguments

options | One or more cabarc options.
command One of the following cabarc commands:
L
N
X
cabfile | The name of the archive file.
@filename.txt | Takes the list of files to be added to the cabinet file from the specified text file.
files A list of files to be archived. Wildcards (such as *.java) are accepted. All files are placed in a single folder, unless a plus sign (+) is placed in the list to delimit the folders. For example, the following command would create two folders.
cabarc n mycab.cab test.* + *.java
dest_dir | Location of resulting cabinet file.

Cabarc Command-Line Options

/c /i /m /o /P /p /r /s /?

Usage Notes

When creating a cabinet file, the plus sign (+) can be used as a file name to force a folder boundary. For example:

cabarc n test.cab *.c test.h + *.bmp

When extracting a file to disk, the dest_dir, if provided, must end in a backslash (\). For example:

cabarc x test.cab bar*.cpp *.h d:\test\

See Also

Cabarc Options

Cabarc Commands

Creating and Using Cabinet Files


Cabarc Options

This section describes cabarc command-line options.

/c

Confirms the files to be operated on.

/I <cabinet ID>

Includes a specified 16-bit cabinet identifier for application use; defaults to 0 (zero).

/m <compression type>

Specifies the compression mode. It can be NONE, MSZIP, or LZX:n, where n is between 15 and 21 inclusive. The LZX compression mode is supported by Internet Explorer 4.0 or later. By default, MSZIP is used as the compression type.

/o

When extracting, overwrites without a prompt for confirmation.

/P <prefix>

Removes the specified prefix entered from files when added. This option can be used to remove path information and can be used multiple times to remove multiple paths. For example,

cabarc –r –p –P myproj\ a test.cab myproj\balloon\*.*

/p

Preserves path names in the cabinet file when used with the N command, and uses that path information with the X command. By default, only the file name component is stored or extracted.

/r

Archives files recursively in all subdirectories.

/s <size>

Reserves space in the cabinet file for a code signature. For example, /s 6144 reserves 6 KB.

/?

Displays cabarc usage information including a list of available options.


Cabarc Commands

This section describes cabarc commands.

L

Lists the contents of the cabinet file specified by the cabfile argument on the command line. Cabarc also displays any cabinet identifier in the cabinet file (see the /s option) and its size, date, time, and attributes.

N

Creates a new cabinet file with a name specified by the cabfile argument on the command line. See the cabarc options for a description of the options available with this command.

X

Extracts files from the cabinet file specified by the cabfile argument on the command line. See the /p option for extracting files into the original directory.


Cert2SPC

The Cert2SPC utility creates a test software publisher certificate (SPC) using existing X.509 certificates. Cert2SPC can wrap multiple X.509 certificates into a PKCS #7 signed-data object. For the latest documentation on Cert2spc, see the CryptoAPI Tools This link takes you to a site on microsoft.com section of the MSDN™ Library.

Note This utility is for test purposes only. A valid SPC is obtained from a certificate authority (CA).

For more information on application security, see the Platform SDK, Security This link takes you to a site on microsoft.com section of the MSDN™ Library.

Cert2SPC cert1.cer cert2.cer. . .certN.cer output.spc

cert1...certN

Names of the X.509 certificates to include in the SPC. Each certificate name ends with the .cer extension.

output

Name of the PKCS #7 object containing the X.509 certificates to be created. The output file name ends with the .spc extension.

Using Cert2SPC

The following command wraps an X.509 certificate, MyCert.cer, into a test PKCS #7 software publisher's certificate (SPC), called MyCert.spc. The SPC created is to be used for test purposes only. An SPC to be used to sign code to be distributed to the public must be obtained from GTE, VeriSign, Inc., or another trusted CA.

Cert2SPC MyCert.cer MyCert.spc


CertMgr

The CertMgr utility replaces DumpCert. It includes new capabilities for the management of certificates, certificate trust lists (CTLs), and certificate revocation lists (CRLs). CertMgr performs four functions:

  • Displays certificates, CTLs, and CRLs.

  • Copies certificates, CTLs, and CRLs from one certificate store to another.

  • Deletes certificates, CTLs, and CRLs from a certificate store.

  • Saves an X.509 encoded certificate, CTL, and CRL from a certificate store to a file.

This utility performs one of these actions depending on the action indicated in the command. For the latest documentation on Certmgr, see the CryptoAPI Tools This link takes you to a site on microsoft.com section of the MSDN™ Library.

For more information on application security, see the Platform SDK, Security This link takes you to a site on microsoft.com section of the MSDN™ Library.

CertMgr [-add | -del | -put][options] [-s [–r registryLocation]]
SourceName [-s [–r registryLocation]] DestinationName

The following table indicates the basic actions of the CertMgr utility.

Action Flag | Description
None | Displays certificates, CRLs, or CTLs.
-add | Copies certificates, CTLs, and CRLs to a certificate store.
-del | Deletes certificates, CTLs, and CRLs from a certificate store.
-put | Saves an X.509 encoded certificate, CTL, or CRL to a file.

With no action flag (to display only), SourceName is the name of the certificate store or file containing the items to display. The store can be a serialized store (StoreFile) or a system store. By default, CertMgr displays all the certificates, CTLs, or CRLs in the certificate store or file. DestinationName is not used for display.

When using -add, SourceStore is the source certificate store that contains the existing certificates, CTLs, and CRLs. DestinationStore is the destination certificate store to which the certificates, CTLs, and CRLs will be added. The destination store will be saved as a serialized store, unless the -7 option is used, which saves the store as a PKCS #7 file. Note that the -7 option cannot be used when the destination store is a system store.

When using -del, SourceStore is the source certificate store that contains the existing certificates, CTLs, and CRLs. DestinationStore is the destination certificate store which will contain copies of the remaining certificates, CTLs, and CRLs after the specified items have been deleted. If DestinationStore is not specified, SourceStore will also serve as the destination store (it will be modified). The destination store will be saved as a serialized store, unless the -7 option is used, which saves the store as a PKCS #7 file. Note that the -7 option cannot be used when the destination store is a system store.

When using -put, SourceStore is the source certificate store that contains the existing certificates, CTLs, and CRLs. DestinationName is the name of a file to which an X.509 encoded certificate, CTL, and CRL will be saved. If the -7 option is used, the file will be saved as a PKCS #7 file. The -s and -r options are not used with -put.

Options

The following options apply to all CertMgr functions except where noted.

Option | Action flag | Description
-v | None (display only) | Verbose mode. Displays detailed information about certificates, CTLs, and CRLs. The default is to display brief information.
-c | All | Use certificates only.
-CTL | All | Use CTLs only.
-CRL | All | Use CRLs only.
-all | -add, -del, –put only | Adds all entries of the chosen type.
-e encoding type | All | Certificate encoding type.
-y storeProviderType | All | Store provider type.
-7 | -add, -del, -put only | Saves the destination store as a PKCS #7 file.
-f dwFlags | All | Store open flag. This is the dwFlags parameter passed to CertOpenStore. The default value is CERT_SYSTEM_STORE_CURRENT_USER. Meaningful only if -y is set. For more information, see the description of the CertOpenStore function in the MSDN™ Library.
-n commonNameString | -add, -dell, -put only | Common name of the certificate to add. Can be used only with certificates.
-sha1 sha1Hash | -add, -del, -put only | SHA1 hash of the certificate, CTL, or CRL to be copied, deleted, or saved.
-s | All | Indicates that the store is a system store.
-r registryLocation | All | Registry location of the system certificate store. Meaningful only when -s is set. Must be set to either currentUser (registry key HKEY_CURRENT_USER) or localMachine (registry key HKEY_LOCAL_MACHINE). currentUser is the default.
-? | All | Displays all the options.

Remarks

CertMgr is only supported in Microsoft® Internet Explorer 4.0 or later.

CertMgr can copy, delete, or save one or more certificates, CTLs, or CRLs. If there is more than one item in one of these categories, the user has three options:

  • Use the -all option to copy, delete, or save all the items in the category indicated.

  • Use the -n and -sha1 options to uniquely identify the item to be copied, deleted, or saved.

  • If -all, or -n and -sha1 are not indicated, CertMgr prompts the user with a list of items to copy, delete, or save. The user responds by entering the index of the item to be copied, deleted, or saved.

The actions of CertMgr use slight variations of the syntax and options. The syntax and options specific to an action must be used.

CertMgr works with two kinds of certificate stores: StoreFile and system store. A StoreFile can be one of the following kinds of files:

  • An encoded CTL/CRL/certificate file (could be base 64 encoded)

  • A PKCS #7 file

  • A signed document

  • A serialized StoreFile

It is not necessary to specify the type of the StoreFile. CertMgr can determine the StoreFile type and take the appropriate actions.

A system store is a certificate store normally located in the registry under currentUser. The user can refer to a system store by providing just its name. It is not necessary to specify the certificate store provider type. Depending on the type of StoreFile or system store, CertMgr chooses the corresponding store provider type.

Using CertMgr

CertMgr can be used to view certificates, CRLs, and CTLs from a file or a certificate store, to copy certificates into a certificate store, to delete certificates from a certificate store, and to save certificates to files.

The file must be one of the following types:

  • An encoded CTL, CRL, or certificate file (could be base 64 encoded)

  • A PKCS #7 file

  • An SPC file

  • A signed document

  • A serialized storeFile

The following examples use CertMgr commands to perform common certificate tasks.

  • View the certificates, CRLs, and CTLs from Myfile.ext.
    CertMgr myFile.ext
  • View the certificates, CRLs, and CTLs from the MY system store.
    CertMgr -s my
  • Copy all the certificates, CRLs, and CTLs in a file named MyFile.ext to a new file, called NewFile.ext.
    CertMgr -add –all –c myFile.ext newFile.ext
  • Copy all the certificates, CRLs, and CTLs from the MY system store to a file called NewMy.ext.
    CertMgr -add -all –c –s my newMy.ext
  • Copy a certificate with common name myCert in the MY system store to a file called NewCert.cer.
    CertMgr -add –c –n myCert –s my newCert.cer
  • Delete all the certificates from the MY system store.
    CertMgr -del –all –c –s MY
  • Delete all the CTLs from the MY system store and save the resulting store to a file called NewStore.str.
    CertMgr -del –all –ctl –s my newStore.str
  • Build a CTL and move it to the Root store.
    //Make a self-signed test certificate called sign.cer.
MakeCert -sv sign.pvk -r -n "CN=THIS IS A TEST OF MAKECTL" sign.cer

// Make a test SPC file using Cert2SPC.
Cert2SPC sign.cer sign.spc

// Make another self-signed test certificate called test.cer.
MakeCert -sv test.pvk -r -n "CN=THIS IS MY TEST CERT" test.cer

// Make an SPC file using Cert2SPC.
Cert2SPC test.cer test.spc

// Make a test.stl from test.cer.
MakeCTL test.cer test.stl

// Sign test.stl with the sign.pvk and sign.spc made in step 1.
SignCode -v sign.pvk -spc sign.spc test.stl

// Move test.stl to the trust system store.
CertMgr –add –ctl test.stl -s trust

// Move sign.cer to the root system store.
CertMgr -add –c sign.cer -s root

// Sign something (test.exe) with test.pvk, and test.spc.
SignCode -v test.pvk -spc test.spc test.exe

// Since test.cer is in the test.stl, ChkTrust will succeed.
ChkTrust test.exe
  • Save an X.509 encoded certificate (with the common name "myCert") located in the Root certificate store to a file called NewCert.cer.
    certmgr -put -c -n myCert -s root newCert.cer


Chkjava

The Java Signature Verification Utility (chkjava) allows users to view security information placed in a cabinet file by signcode with the JavaSign DLL.

Use the following command to run chkjava:

chkjava [options] <filename>

Chkjava Command-Line Arguments

options | One or more chkjava options.
filename | Specifies the name of the file to verify Java permissions for.

Chkjava Command-Line Options

/o /q /?

Usage Notes

The chkjava utility checks the validity of a signature. It also displays the certificate information and security permissions contained in the file on the console output.

If the signing information is valid and the signature contains Microsoft® ActiveX® permissions, chkjava displays a message that the file is signed with ActiveX permissions.

Examples

The following output is an example showing the format used when the signed file is successfully read and the information is dumped to the screen.

   Filename:         <filename>
   Program Name:     <OpusName>
   Further Info:     <Info Location>

   Published by:     <Publisher Name>
   Publisher type:   (Commercial | Individual)
   Verified by:      <Agency Name>

   Trust Level:      (High | Medium | Low | Custom)
   [<permission info>]

If the /o option is specified, the permission information will be written to a text file suitable for input as the information file in signcode using the JavaSign.dll.

The following example shows various sample command lines using the chkjava utility, and their results.

C:\..\>chkjava my.cab
\\ Displays a dialog box with signature information.

C:\..\>chkjava /o test.ini my.cab
\\ Displays a dialog box and outputs the .ini file as <test.ini>.

C:\..\>chkjava /o test.ini /q my.cab
\\ Outputs only to .ini.

C:\..\>chkjava /q my.cab
\\ Displays only basic information.

See Also

Chkjava Options


Chkjava Options

This section describes chkjava command-line options.

/o <outputfile>

Specifies permissions that are read from the signed cabinet file will be written to the output file in an .ini format. The format of the output file is the same as the input file for JavaSign.dll.

/q

Quiet mode; suppresses all message boxes. If you do not specify the /q option, chkjava displays a dialog box that shows all permissions and signature information.

/?

Displays chkjava usage information including a list of available options.


ChkTrust

The ChkTrust utility checks the validity of a signed file. If the hashes agree, ChkTrust verifies the signing certificate. For the latest documentation on Chktrust, see the CryptoAPI Tools This link takes you to a site on microsoft.com section of the MSDN™ Library.

For more information on application security, see the Platform SDK, Security This link takes you to a site on microsoft.com section of the MSDN™ Library.

ChkTrust [options] signedFile

signedFile

Name of the signed file containing the signature to be verified.

Options

The following options are supported.

Option | Internet Explorer Version | Description
-c | 3.02 only | Signed file is a cabinet file.
-i | 3.02 only | Signed file is a PE image file. Includes .exe, .dll, and .ocx files.
-n | 3.02 only | Do not display user interface.
-q | 4.0 and later | Do not display user interface.
-? | 4.0 and later | Displays all the options.

Remarks

ChkTrust with Internet Explorer 4.0 or later can distinguish file types automatically. The -c and -i switches used in Internet Explorer 3.02 are obsolete.

Using ChkTrust

The following command demonstrates the use of ChkTrust with Internet Explorer 4.0 or later.

ChkTrust MyProgram.exe

A successful response from the above would be:

Result: 0

Note Versions of ChkTrust older than the version released with Internet Explorer 3.02 cannot validate files signed with the current release of CryptoAPI Tools.


Cprmedit

The Custom Permission Editor (cprmedit) edits Java permissions for security zones recognized by Microsoft® Internet Explorer 4.0 and later.

Use the following command to run cprmedit:

cprmedit

Usage Notes

The cprmedit tool enables you to edit Java permissions for specific security zones using a graphical user interface. The permissions set by cprmedit are recognized by Internet Explorer 4.0 or later. See Defining Permission Sets Using Cprmedit for details on using cprmedit.

See Also

Defining Permission Sets Using Cprmedit

Trust-Based Security for Java

com.ms.security

com.ms.security.permissions


Defining Permission Sets Using Cprmedit

The cprmedit tool enables you to edit Java permissions for specific security zones using a graphical user interface. The permissions set by cprmedit are recognized by Microsoft Internet Explorer 4.0 or later. The user interface presented by the cprmedit tool is similar to the dialog boxes in Internet Explorer 4.01 that enable administrators to set security options.

To run the Custom Permission Editor, make sure that the %SDKDIR%\Bin directory is in your path, and then type cprmedit on the command line. The Custom Permission Editor dialog box will appear. To edit the permissions for a particular zone, choose one of the zones listed in the drop-down list box. For each zone, there are three sets of permissions that you can edit: Unsigned Permissions, Trusted Signed Permissions, and Untrusted Signed Permissions. Each permission set has its own area in the dialog box, and each area contains check boxes and buttons that are used to define the group.

The following sections explain how to define a permission set.

Unsigned Permissions

Unsigned Permissions are permissions granted to unsigned content. To edit these permissions, select one of the following choices.

Unsigned Content is Fully Trusted | Gives all permissions to unsigned content. This setting is not recommended because damaging content could be run on your computer.
Edit | Specifies a set of permissions to give to unsigned content. For more information, see Editing Permission Sets.

Trusted Signed Permissions

Trusted Signed Permissions are permissions requested by signed content that do not require user approval. To edit these permissions, select one of the following choices.

Grant all Permissions Requested by Signed Content | Gives signed content all requested permissions. This setting is not recommended.
Edit | Specifies a set of permissions to give to the Trusted Signed Permissions group. For more information, see Editing Permission Sets.

Untrusted Signed Permissions

Untrusted Signed Permissions are permissions requested by signed content that require user approval or are absolutely denied. When editing the Untrusted Signed Permissions group, you must select one of the following options to indicate whether the user should be queried.

Ask for Approval of Untrusted Permissions | Queries the user if signed content requests a permission set that is not a subset of the Trusted Signed Permissions group and is a subset of the Untrusted Signed Permissions group. If signed content requests any other permission set that is not a subset of the Trusted Signed Permissions group, the content is automatically refused.
Refuse Untrusted Permissions Without Asking | Automatically refuses signed content requesting a permission that is not a subset of the Trusted Signed Permissions group and is a subset of the Untrusted Signed Permissions group. The user is asked for approval if any other permission set is requested.

You can also choose the Apply to all Permissions not Specifically Allowed option to include all permissions in the Untrusted Signed Permissions group. Any permission set that is not a subset of the Trusted Signed Permissions group will be queried or denied based on the setting of the buttons previously described.

If you do not choose this option, you can select the Edit button to specify a set of permissions to give to the Untrusted Signed Permissions group. For more information, see Editing Permission Sets.

Editing Permission Sets

To edit a set of permissions, select the Edit button for the permission set you are interested in. The Edit Custom Permissions dialog box appears. This dialog box contains the following tabs, each of which indicates permissions that can be edited.

Tab name | Permission description
File | The ability to read, write, or delete files.
Registry | The ability to read, write, delete, create, or open keys in the registry.
Network | The ability to connect or bind to various hosts or ports on the network.
Client Services | The ability to access client storage, perform user-directed file I/O, access user interface functionality, print, use multimedia libraries, and access security classes.
System | The ability to run programs, access system properties, manipulate threads, and redirect system streams.
Reflection | The ability to access public or declared members of a class, based on the class loader.
Custom | The ability to use a non-system permission designed by the user.

Choose the tab for the permission that you want to edit and complete the fields and check boxes to set the permissions you want. Note the following general rules for entering information:

  • Navigate between permissions by selecting the tabs.

  • For File, Registry, and Network permissions, as well as Property and Execution permissions in the System tab, you can use the asterisk (*) and the question mark (?) as wildcard characters in any edit box. For example, in the File tab, if you want to add read permission for all files ending in .doc, select Read from the Access type list box, type *.doc in the Include files edit box, and then click Add.

  • You can use the semicolon (;) as a delimiter for Property and Execution permissions in the System tab.

  • When using a character such as an asterisk (*), a question mark (?), or a semicolon (;) as a literal in expressions, you must enclose the entire expression in double quotes and precede the character with a backslash. You must also precede each literal backslash with a backslash. For example, if you want to specify all file names in the C:\Windows\ directory whose second character is an asterisk (*), enter the following, including the double quotes: "C:\\Windows\\?\**".

  • Use the Medium, High, or Clear buttons to set all the permissions in the set to a security setting or to clear the permission settings. Be aware that using these buttons affects all the permissions, not just the currently selected tab. Any previous edits to the permissions will be erased and reset to Medium, High, or Clear.

  • When you have finished editing a set of permissions, click OK. This returns you to the Custom Permission Editor dialog box. You can then edit another permission group. To save the chosen settings but continue editing other permission settings, click Apply. To save the chosen settings and close the dialog box, click OK. To quit without saving your settings, click Cancel.

The following topics describe how to edit each permission tab:

File

Registry

Network

Client Services

System

Reflection

Custom

File

  1. Select one of the following from the Access type drop-down list: Read, Write, or Delete.
  • To include a file, enter the file name in the Include files edit box, and then click Add.

  • To exclude a file, enter the file name in the Exclude files edit box, and then click Add.

  • To remove a file, select the file name from the included or the excluded file list, and then click Remove.
  2. Repeat this process until you have added or removed the appropriate included or excluded files from the access types.

Registry

  1. Select one of the following from the Access type drop-down list: Read, Write, Delete, Create, or Open.
  • To include a key, enter the key name in the Include keys edit box and then click Add.

  • To exclude a key, enter the key name in the Exclude keys edit box and then click Add.

  • To remove a key, select the key name from the included or the excluded key list, and then click Remove.
  2. Repeat this process until you have added or removed the appropriate included or excluded keys from the access types.

Network

  1. Select one of the following from the Access type drop-down list: Connect, Bind, Multicast, or Global Ports.
    • To include a host, enter the host name or IP address in the Include host edit box. You can specify a list of single ports, port ranges, or both by entering them in the Ports edit box, separated by commas. For example, 27-80, 95, 100-102 is a valid list of ports. If you choose the Multicast access type, you can only specify the host. If you choose the Global Ports access type, you can only specify the ports, not the host. Then, click Add.

    • To exclude a host, enter the host name or the IP address in the Exclude host edit box. You can enter the list of ports and port ranges in the Ports edit box, separated by commas. Then, click Add.

    • To remove a host or port, select the name of the host or port from the included or excluded host list, and then click Remove.
  2. Repeat this process until you have added or removed the appropriate included or excluded hosts or ports from the access types.

Client Services

Client storage settings

  • To change the amount of allowed client storage, enter the appropriate number of kilobytes in the Storage limit edit box.

  • To exempt client storage from global storage limits, select the Exempt from global client storage limit check box.

  • To allow or deny access to roaming files, select or clear the Access to roaming files check box.

Miscellaneous

  • To allow or deny access to printing services, select or clear the Access to printing services check box.

  • To allow or deny access to multimedia libraries, select or clear the Access to multimedia libraries check box.

  • To allow or deny access to security classes, select or clear the Access to security classes check box.

User-directed file I/O

  • To allow or deny user-directed read access to files, select or clear the Read access check box.

  • To allow or deny user-directed write access to files, select or clear the Write access check box.

User interface restrictions

  • To allow or deny the creation of file dialog boxes, select or clear the Create file dialogs check box.

  • To allow or deny the creation of top-level windows, select or clear the Create top level windows check box. If you allow top-level window creation, you can enable or disable the applet warning banner by clearing or selecting the Turn off applet warning banner check box.

  • To allow or deny access to the Clipboard, select or clear the Clipboard access check box.

System

Property access

  • To allow access to specific system properties, enter the name of the property or properties in the Include properties edit box; separate property names with semicolons (;).

  • To deny access to specific system properties, enter the name of the property or properties in the Exclude properties edit box; separate property names with semicolons (;).

  • To allow access to properties that are described by a particular suffix, enter the suffix in the Suffixes edit box. For instance, entering the "applet" suffix would allow access to a system property "X" if the system property "X.applet" exists and is set to True.

  • To allow or deny unrestricted access to system properties, select or clear the Unrestricted access to properties check box.

Thread access

  • To allow or deny access to thread objects, select or clear the Thread objects check box.

  • To allow or deny access to thread group objects, select or clear the Thread group objects check box.

Execution access

  • To allow specific files to be executed, enter the file name in the Include applications edit box.

  • To deny the right to execute specific files, enter the file name in the Exclude applications edit box.

  • To allow or deny the right for all applications to be executed, select or clear the Unrestricted execution of applications check box.

System stream redirection access

  • To allow or deny the ability to redirect the standard system input stream (System.in), select or clear the Standard input stream check box.

  • To allow or deny the ability to redirect the standard system output stream (System.out), select or clear the Standard output stream check box.

  • To allow or deny the ability to redirect the standard system error stream (System.err), select or clear the Standard error stream check box.

Reflection

Public member reflection

  • To allow or deny access to public members of classes loaded by the same class loader, select or clear the Same loader check box.

  • To allow or deny access to public members of classes loaded by a different class loader, select or clear the Different loader check box.

  • To allow or deny access to public members of classes loaded by a system loader, select or clear the System loader check box.

Declared member reflection

Note A declared member is any member of a class.

  • To allow or deny access to declared members of classes loaded by the same class loader, select or clear the Same loader check box.

  • To allow or deny access to declared members of classes loaded by a different class loader, select or clear the Different loader check box.

  • To allow or deny access to declared members of classes loaded by a system loader, select or clear the System loader check box.

Custom

  • To add a parameter to a custom permission (a non-system permission), enter the name of the permission class in the Class name edit box. Then, enter the parameter in the Parameters edit box and click Add.

  • To remove a parameter from a custom permission, enter the name of the permission class in the Class name edit box. Then, enter the parameter in the Parameters edit box and click Remove.

The class must be on the class path or it will not be found. In addition, the class should support the EncodeFormats.TEXT encoding if it requires parameters and needs to support the Custom Permission Editor.

If you edit a custom permission class that does not have the thread permission, the Custom Permissions Editor will add the thread permission so that unrestricted access to threads and thread groups is denied.


Dubuild

The Distribution Unit Archiving Utility (dubuild) writes an Open Software Distribution (OSD) file and places it in a cabinet file archive with any specified contents.

Use one of the following commands to run dubuild:

dubuild <filename>.cab [drive:][path] [options]

dubuild @<file>

Dubuild Command-Line Arguments

filename.cab | Specifies the Distribution Unit (DU) file name.
drive:path | Specifies the source path to the files that are included in the archive.
options | One or more dubuild options.
@file | A file that lists command-line parameters to be used by dubuild.

Dubuild Command-Line Options

/B /D /H or /? /I /M /N /P /S /V /VD /VN /VP /X /Z

Usage Notes

The dubuild utility creates DUs, split distribution units and registers ActiveX controls as JavaBeans. The dubuild utility is similar to cabarc, but uses the OSD manifest instead of .inf files. Dubuild and DUs are used only by Internet Explorer 4.0 or later.

Any command-line parameters may be specified from a file by using the @file argument.

The {BeanInfo} syntax is as follows:

/B package,class,regmode,progid,guid,iconfile,flags,tlbguid,
   tlbfile,bitmap32

The arguments must be in the previous syntax order and cannot contain any spaces. If you exclude parameters, do not use spaces between comma separators. For example, if you do not want to include an icon file, you would use the following syntax:

C:\..\>dubuild /B pkg,cls,regmd,pid,guid,,flags,tlbguid,tlbfile,bit32

Simple Bean identification can be done by supplying only the package name and the class file name. ActiveX registration requires regmode and at least the GUID argument, as well.

\\Simple Registration
C:\..\>dubuild /B com.mycompany.net,Connect.class

\\Full Registration
C:\..\>dubuild /B com.mycompany.net,Connect.class,ActiveX,
      MycompanyNetConnector,{FCOCF5C5-06DA-11d1-8F36-00C04FD8FF5E},
      com\mycompany\net\Connect.ico,1,
      {FCOCF5C6-06DA-11d1-8F36-00C04FD8FF5E},
      com\mycompany\net\Connect.tlb,
      com\mycompany\net\Connect.bmp

See Also

Dubuild Options

Creating and Using Distribution Units

Java Package Manager


Dubuild Options

This section describes dubuild command-line options.

/B <BeanInfo>

Provides information about each Bean; used to register ActiveX Controls as JavaBeans.

/D "<friendlyname>"

Sets the distribution unit's (DU) friendly name.

/H or /?

Displays dubuild usage information including a list of available command-line options.

/I <pattern>

Includes files that match the specified pattern.

/M

Creates a multicabinet file DU.

/N "<namespace>"

Sets the distribution unit's namespace. If you have any anonymous classes in your DU (classes that are not in a package), you must specify an application namespace. Otherwise, the anonymous classes will not be properly installed. For more information about application namespaces, see Java Package Manager.

/P <oldDUName>.cab

Specifies a previous DU file name; used in creating Split DUs.

/S <pattern>

Marks packages that match the pattern as system packages.

/V <version>

Use default version numbers for VD, VP, and VN.

/VD <version>

Sets the minimum version number for the DU.

/VN <version>

Sets the version number for new packages included in the DU (used in creating split DUs).

/VP <version>

Sets the minimum version number for the packages included in the distribution unit.

/X <pattern>

Excludes files that match the specified pattern.

/Z

Builds distribution units with MSZIP compression for Internet Explorer 3.0x compatibility. By default, LZX:21 compression is used.


MakeCert

The MakeCert utility creates an X.509 certificate, signed by the test root key or other specified key, that binds your name to the public part of the key pair. The certificate is saved to a file, a system certificate store, or both.

MakeCert [basic options | extended options] outputFile

outputFile

Name of the file where the certificate will be written. May be omitted if the certificate is not to be written to a file.

For the latest documentation on Makecert, see the CryptoAPI Tools This link takes you to a site on microsoft.com section of the MSDN™ Library.

For more information on application security, see the Platform SDK, Security This link takes you to a site on microsoft.com section of the MSDN™ Library.

Options

MakeCert includes basic and extended options. Basic options are those most commonly used to create a certificate. Extended options provide more flexibility. The options for MakeCert are also divided into three functional groups:

  • Extended options applicable to SPC file, private key, and certificate store technology.

  • Extended options specific to SPC file and private key technology only.

  • Basic options specific to certificate store technology only.

Extended Options - SPC Files, Private Key, and Certificate Store Technology

The following options are for SPC file, private key, and certificate store technology.

Extended option | Internet Explorer version | Description
-a (3.02) or –a algorithm (4.0 and later) | 3.02 or later | 3.02: Indicates that the SHA1 hash algorithm should be used. MD5 is the default. 4.0: Hash algorithm. Must be set to either SHA1 or MD5 (default).
-b dateStart | 3.02 or later | Date the certificate first becomes valid. The default is when the certificate is created. The format of dateStart is mm/dd/yyyy.
-c | 3.02 only | Certificate will be used by commercial software publishers.
-c f | 3.02 only | Certificate will be used by commercial software publishers who have met the minimum financial criteria.
-t:types | 3.02 only | Certificate type. This parameter can be E for end-entity, C for certification authority, or both.
-cy certificateTypes | 4.0 and later | Certificate type. Can be end for end-entity, authority for certification authority, or both.
-d displayName | 3.02 or later | Display name of the subject.
-e dateEnd | 3.02 or later | Date when the validity period ends. The default is the year 2039.
-eku OID1, OID2… | 4.0 and later | Inserts a list of one or more comma-separated, enhanced key usage object identifiers (OIDs) into the certificate. For example, -eku 1.3.6.1.5.5.7.3.2 inserts the client authentication OID. For definitions of allowable OIDs, see the Wincrypt.h file in the Microsoft® CryptoAPI 2.0.
-g | 3.02 only | Creates a glue certificate.
-h numChildren | 3.02 or later | Maximum height of the tree below this certificate.
-i | 3.02 only | Certificate will be used by individual software publishers.
-l: policyLink (3.02) or –l policyLink (4.0 and later) | 3.02 or later | Link to SPC agency policy information (for example, a URL).
-d: nMonths | 3.02 only | Duration of the validity period.
-m nMonths | 4.0 and later | Duration of the validity period.
-m | 3.02 only | The MD5 hash algorithm should be used. This is the default.
-n: name (3.02) or –n name (4.0 and later) | 3.02 or later | Name for the publisher's certificate. This name must conform to the X.500 standard. The simplest method is to use "CN=MyName" format. For example: -n "CN=Test".
-n | 3.02 only | The Netscape client authentication extension should be included.
-nscp | 4.0 and later | The Netscape client authentication extension should be included.
-r | 3.02 and later | Creates a self-signed certificate.
-u: subjectCertFile | 3.02 only | Certificate file name with the existing subject public key to be used.
-u: subjectKey | 3.02 only | Location of the subject's key container which holds the private key. If a key container does not exist, one is created.
-sc subjectCertFile | 4.0 and later | Certificate file name with the existing subject public key to be used.
-sk subjectKey | 4.0 and later | Location of the subject's key container which holds the private key. If a key container does not exist, one is created. If neither the -sk or -sv option is used, a default key container is created and used by default.
-sky subjectKeySpec | 4.0 and later | Subject's key specification, which must be one of three possible values: 1. Signature (AT_SIGNATURE key specification) 2. Exchange (AT_KEYEXCHANGE key specification) 3. An integer, such as 3. See notes on key specifications below.
-sp subjectProviderName | 3.02 and later | CryptoAPI provider for subject. The default is the user's provider. See the CryptoAPI 2.0 documentation in the MSDN™ Library for details on CryptoAPI providers.
-sr subjectCertStoreLocation | 4.0 and later | Registry location of the subject's certificate store, which must be either localMachine (registry key HKEY_LOCAL_MACHINE) or currentUser (registry key HKEY_CURRENT_USER). currentUser is the default.
-ss subjectCertStoreName | 4.0 and later | Name of the subject's certificate store where the generated certificate will be stored.
-k: subjectKeyFile | 3.02 only | Location of the subject's .pvk file.
-sv subjectKeyFile | 4.0 and later | Name of the subject's .pvk file. If neither the -sk or -sv option is used, a default key container is created and used by default.
-sy nSubjectProviderType | 4.0 and later | CryptoAPI provider type for subject. The default is PROV_RSA_FULL. See the CryptoAPI 2.0 documentation in the MSDN™ Library for details on CryptoAPI provider types.
-#: serialNumber (3.02) or -# serialNumber (4.0 and later) | 4.0 and later | Serial number of the certificate. The maximum value is 2^31. The default is a value generated by the utility that is guaranteed to be unique.
-$ certificateAuthority | 4.0 and later | Type of certification authority, which must be set to either commercial (for certificates to be used by commercial software publishers) or individual (for certificates to be used by individual software publishers).
-? | 3.02 and later | Displays the basic options.
-! | 4.0 and later | Displays the extended options.

Note If the -sky key specification option is used in Microsoft® Internet Explorer version 4.0 or later, the specification must match the key specification indicated by the private key file or private key container. If the key specification option is not used, the key specification indicated by the private key file or private key container will be used. If there is more than one key specification in the key container, MakeCert will first attempt to use the AT_SIGNATURE key specification. If that fails, MakeCert will try to use AT_KEYEXCHANGE. Since most users have either an AT_SIGNATURE key or AT_KEYEXCHANGE key, this option does not need to be used in most cases.

Extended Options - SPC Files and Private Key Technology

The following options are only for software publisher certificate (SPC) files and private key technology.

SPC/private key option | Internet Explorer version | Description
-i: issuerCertificate | 3.02 only | Location of the issuer's certificate.
-ic issuerCertFile | 3.02 and later | Location of the issuer's certificate.
-s: issuerKeyFile | 3.02 only | Location of the issuer's key container. The default is the test root key.
-ik issuerKey | 4.0 and later | Location of the issuer's key container. The default is the test root key.
-k: keySpec | 3.02 only | Issuer's key specification. Can be either S for a signature key (default) or E for a key-exchange key.
-iky issuerKeySpec | 4.0 and later | Issuer's key specification, which must be one of three possible values: 1. Signature (AT_SIGNATURE key specification) 2. Exchange, (AT_KEYEXCHANGE key specification) 3. An integer, such as 3. See notes on key specifications below.
-x: providerName | 3.02 only | CryptoAPI provider for issuer. The default is the user's provider. See the CryptoAPI 2.0 documentation in the MSDN™ Library for details on CryptoAPI providers.
-ip issuerProviderName | 4.0 and later | CryptoAPI provider for issuer. The default is the user's provider. See the CryptoAPI 2.0 documentation in the MSDN™ Library for details on CryptoAPI providers.
-iv issuerKeyFile | 3.02 or later | Issuer's private-key file. The default is the test root.
-y: nProviderType | 3.02 only | CryptoAPI provider type for issuer. The default is PROV_RSA_FULL. See the CryptoAPI 2.0 documentation in the MSDN™ Library for details on CryptoAPI provider types.
-iy nIssuerProviderType | 4.0 and later | CryptoAPI provider type for issuer. The default is PROV_RSA_FULL. See the CryptoAPI 2.0 documentation in the MSDN™ Library for details on CryptoAPI provider types.

Note If the -iky key specification option is used in Internet Explorer 4.0 or later, the specification must match the key specification indicated by the private key file or private key container. If the key specification option is not used, the key specification indicated by the private key file or private key container will be used. If there is more than one key specification in the key container, MakeCert will first attempt to use the AT_SIGNATURE key specification. If that fails, MakeCert will try to use AT_KEYEXCHANGE. Since most users have either an AT_SIGNATURE key or AT_KEYEXCHANGE key, this option does not need to be used in most cases.

Basic Options - Certificate Store Technology

The following options are for certificate store technology only. These options are supported with Internet Explorer 4.0 and later.

Certificate store option | Internet Explorer version | Description
-ic issuerCertFile | 4.0 and later | File containing the issuer's certificate. MakeCert will search in the certificate store for a certificate with an exact match.
-in issuerNameString | 4.0 and later | Common name of the issuer's certificate. MakeCert will search in the certificate store for a certificate whose common name includes issuerNameString.
-ir issuerCertStoreLocation | 4.0 and later | Registry location of the issuer's certificate store, which must be either localMachine (registry key HKEY_LOCAL_MACHINE) or currentUser (HKEY_CURRENT_USER). currentUser is the default.
-is issuerCertStoreName | 4.0 and later | Issuer's certificate store that includes the issuer's certificate and its associated private key information. If there is more than one certificate in the store, the user must uniquely identify it with the -ic or -in option. If the certificate in the certificate store is not uniquely identified, MakeCert will fail.

Using MakeCert

The following examples create test certificates with MakeCert, using options available with Microsoft® Internet Explorer version 4.0 or later:

  • Make a certificate issued by the default test root. Save the certificate to a file.
    MakeCert myNew.cer
  • Make a certificate issued by the default test root. Save it to a certificate store.
    MakeCert –ss myNewStore
  • Make a certificate issued by the default test root. Create a .pvk file, save the certificate to both a store and a file, and then sign a document with the newly-created certificate.
    MakeCert –sv myNew.pvk –ss myNewStore myNew.cer
SignCode -v myNew.pvk -spc myNew.cer -t
     http://timestamp.verisign.com/scripts/timestamp.dll myControl.exe
  • Make a certificate issued by the default test root. Create a key container and save the certificate to both a store and a file.
    MakeCert –sk myNewKey –ss myNewStore myNew.cer
  • Make a certificate using the default test root. Save the certificate to a store. Then make another certificate issued by the newly-created certificate. Save the second certificate to another store.
    MakeCert –sk myNewKey –ss myNewStore
MakeCert –is myNewStore –ss anotherStore
  • Make a certificate using the default test root. Save the certificate to the MY store. Then make another certificate using the newly-created certificate. If there is more than one certificate in the MY store, the certificate must be identified using its common name.
    MakeCert –sk myNewKey –n "CN=XXZZYY" –ss my
MakeCert –is my –in "XXZZYY" –ss anotherStore
  • Make a certificate using the default test root. Save the certificate to the MY store and to a file. Then make another certificate using the newly created myNew certificate. If there is more than one certificate in the MY store, uniquely identify the first certificate using the certificate file name.
    MakeCert –sk myNewKey –n "CN=XXZZYY" –ss my myNew.cer
MakeCert –is my –ic myNew.cer –ss anotherStore
  • Create a self-signed certificate named myNewRoot using the default test root. Then use SignCode with the certificate to sign a file.
    MakeCert –sk myNewRootKey –r –ss myNewRoot
SignCode –s myNewRoot myControl.exe
  • Create a self-signed certificate named myNewRoot using the default test root. Save myNewRoot into a system certificate store ca. Then make a certificate from myNewRoot and sign some code with the certificate.

    Note When SignCode uses a certificate in a store for signing, it will also build a certificate chain from the signing certificate to a root. All the certificates in the certificate chain must be in any of the MY, ca, or Root certificate stores. In this case, myNewRoot is in the ca certificate store.

    MakeCert –sk myNewRootKey –r –ss ca myNewRoot.cer
MakeCert –is ca –ic myNewRoot.cer –ss myNewSign
SignCode –s myNewSign myControl.exe


MakeCTL

The MakeCTL utility creates a certificate trust list (CTL) and saves the encoded CTL to a certificate store or to a file. MakeCTL is only supported with Microsoft® Internet Explorer 4.0 or later. A CryptoAPI Tool wizard is available with Internet Explorer 5.0 or later and Microsoft® Windows NT® version 4.0 SP4 or later.

The input to MakeCTL is an array of certificate stores. MakeCTL builds a CTL that includes the SHA1 hash of all of the certificates in the certificate stores. A certificate store can be one of the following:

  • A serialized store file

  • A PKCS #7 file

  • An encoded certificate file

  • A system store
MakeCTL [-u subjectUsageID] [-s [-r registryLocation]]
     store1 [-s [-r registryLocation]] store2 … [-s [-r registryLocation]]
     storeN output.stl

store1...storeN

Names of the certificate stores for which to make the certificate trust list.

output.stl

Name of the output file to contain the CTL.

For the latest documentation on MakeCTL, see the CryptoAPI Tools This link takes you to a site on microsoft.com section of the MSDN™ Library.

For more information on application security, see the Platform SDK, Security This link takes you to a site on microsoft.com section of the MSDN™ Library.

Options

Option | Description
-u subjectUsageID | CTL subject usage identifier. The default identifier, 1.3.6.1.4.1.311.2.2.1, defined as szOID_TRUSTED_CODESIGNING_CA_LIST in Wintrust.h, specifies that the CTL consists of root CAs for code signing. It can be any enhanced key usage object identifier (OID).
-s | Indicates that the certificate store is a system store.
-r registryLocation | Registry location of the system certificate store. Meaningful only when –s is set. Must be set to either currentUser (registry key HKEY_CURRENT_USER) or localMachine (registry key HKEY_LOCAL_MACHINE). The default setting is currentUser.
-? | Lists command syntax and options.

Note An encoded CTL file must be signed before using. CTL files can be signed using the SignCode utility. Once the CTL file is signed, it can be moved to the trust system store by CertMgr. CertMgr can also move the CTL's signed certificate to the Root store. If the subject usage identifier of the CTL is szOID_TRUSTED_CODESIGNING_CA_LIST (the default), all the files signed by certificates in the CTL will be trusted by ChkTrust and Microsoft® Authenticode™.

Using MakeCTL

The MakeCTL utility creates a certificate trust list (CTL) and saves the encoded CTL to a certificate store or to a file.

  • The following example generates a CTL that includes all the certificates in a system certificate store named Root:
    MakeCTL –s root output.stl
  • The following command generates a CTL that includes three certificates named One.cer, Two.cer, and Three.cer. The CTL is created in the file Output.stl.
    MakeCTL -u one.cer two.cer three.cer output.stl

Built on Wednesday, May 12, 1999


Piniedit

The Permission INI File Editor (piniedit) creates and edits .ini files for use with the signcode tool.

Use the following command to run piniedit:

piniedit [inifilename]

Piniedit Command-Line Arguments

inifilename Permission INI file to edit.

Usage Notes

Piniedit provides a quick way to create .ini files that are used with the signcode tool. It uses .ini files to provide descriptions of the permission settings needed by Java applets. Using an .ini file with signcode enables you to digitally sign your applet with the permissions encoded within the digital signature.

Alternatively, you can manually create .ini files and set the value of each of its variables. Piniedit creates and edits .ini files quickly and easily by enabling you to specify the permissions using a graphical user interface.

For details on creating .ini files using piniedit, see Using the Permissions INI File Editor.

See Also

Using the Permissions INI File Editor

Java Permissions .INI Values Reference

Sample Permissions INI File


Using the Permissions INI File Editor

The Permission INI File Editor creates and edits .ini files quickly and easily by enabling you to specify the permissions using a graphical user interface. (Alternatively, you can create .ini files manually and set the value of each variable in the file.)

To start the Permission INI File Editor, type piniedit on the command line, optionally followed by the name of the .ini file that you want to edit:

piniedit [inifilename]

The Permissions INI File Editor dialog box appears. This dialog box contains seven permissions tabs. Choose the tab that corresponds to a permission that you want to set. You can then edit the permission by selecting appropriate check boxes and entering parameters in the text boxes contained in each tab.

The following table describes the permissions that can be edited in each tab:

Tabs and their editable permissions

Tab name | Permission description
File | The ability to read, write, or delete files.
Registry | The ability to read, write, delete, create, or open keys in the registry.
Network | The ability to connect or bind to various hosts or ports on the network.
Client Services | The ability to access client storage, perform user-directed file I/O, access user interface functionality, print, use multimedia libraries, and access security classes.
System | The ability to run programs, access system properties, manipulate threads, and redirect system streams.
Reflection | The ability to access public or declared members of a class, based on the class loader.
Custom | The ability to use a non-system permission designed by the user.

The piniedit tool uses the same user interface as the Edit Custom Permissions dialog box of the Custom Permissions Editor, cprmedit. (The cprmedit tool sets Java permissions for security zones). For detailed information about the permission tabs and how to edit them, see the Editing Permission Sets section of Defining Permission Sets Using Cprmedit.

Note the following general rules for entering information:

  • Select the High or Medium buttons to set all permissions to a High or Medium security level, respectively. Use these buttons to save time by adding to or removing permissions from a preset group of permissions. Be aware that selecting these buttons erases any permission editing that you have done previously and resets the permissions to High or Medium. To clear the settings for all permissions, click Clear. To create an .ini file with a Low security level, select the Full Permissions check box. This setting allows all permissions.

  • You can also load the permissions from a specific zone by choosing Load from Zone from the Zone menu. This action allows you to edit the .ini file using a set of permissions that are identical to the permissions for the specified zone.

  • To add ActiveX permissions to the .ini file, select the ActiveX Permissions check box.

  • For File, Registry, and Network permissions as well as Property access and Execution access permissions in the System tab, you can use the asterisk (*) and the question mark (?) as wildcard characters in the text boxes.

  • To delimit multiple entries in text boxes in the Property access and Execution access permissions of the System tab, use semicolons (;). Separate multiple ports in the Network permission by commas.

  • If you are using an asterisk (*), a question mark (?), or a semicolon (;) as a literal in an expression, you must precede the literal character with a backslash (\) and put the whole expression in double quotes. Each literal backslash must also be preceded by a backslash. For example, if you want to specify all files in the C:\Windows directory whose second character is the asterisk, you should enter "C:\\Windows\\?\**".

  • When you have finished editing the permissions, save the file. To save the permissions as an .ini file, choose Save from the File menu. To save the edited permissions to a zone, choose Save to Zone from the Zone menu, which will modify the permissions that are recognized by Internet Explorer 4.0 and later for the specified zone.

For more information on .ini files, see the Java Permissions .INI Values Reference and the Sample Permissions .INI File. To learn how .ini files are used with the signcode tool, see Signing a Cabinet File with Java Permissions.


SetReg

The SetReg utility sets the value of the registry keys controlling the behavior of the Microsoft® Authenticode™ certificate verification process. These keys are called the Software Publishing State Keys. After completing the requested action, the utility displays the current state of the Software Publishing State Keys. For the latest documentation on setreg, see the CryptoAPI Tools This link takes you to a site on microsoft.com section of the MSDN™ Library.

SetReg [options] [Choice # <TRUE | FALSE>]

For more information on application security, see the Platform SDK, Security This link takes you to a site on microsoft.com section of the MSDN™ Library.

Options

The options can be one of the following values.

Option | Internet Explorer Version | Description
-q | 3.02 and later | Suppress the display of the Software Publishing State Key values after SetReg has completed the requested action. The values are displayed by default.
-h | 3.02 only | List command syntax and options.
-? | 4.0 and later | List command syntax and options.

Choice # must be one of the following values. All the listed values are valid for Internet Explorer 3.02 and later, except 9 and 10, which are for Internet Explorer 4.0 or later only.

Choice | Description | Result
1 | Trust the Test Root | If TRUE, trusts a test root. This is equivalent to running "regedit wvtston.reg" in Internet Explorer 3.x. The default is FALSE. Any file signed with a test root will not verify unless this flag is set to TRUE.
2 | Use expiration date on certificates | If TRUE, checks the certificate expiration date. To ignore expiration dates, set this flag to FALSE. The default is TRUE.
3 | Check the revocation list | If TRUE, performs the revocation check. To bypass revocation check, set this flag to FALSE. The default is FALSE in Internet Explorer 3.x and TRUE in Internet Explorer 4.0 or later.
4 | Offline revocation server OK (Individual) | If TRUE, allows offline approval for individual certificates. The default is FALSE.
5 | Offline revocation server K (Commercial) | If TRUE, allows offline approval for commercial certificates. The default is FALSE.
6 | Java offline revocation server OK (Individual) | If TRUE, allows offline approval for individual certificates and does not display the user interface for bad certificates. The default is FALSE.
7 | Java offline revocation server OK (Commercial) | If TRUE, allows offline approval for commercial certificates and does not display the user interface for bad certificates. The default is FALSE
8 | Invalidate version 1 signed objects | If TRUE, invalidates version 1 signed objects. The default is FALSE.
9 | Check the revocation list of timestamp server | If TRUE, performs the revocation check on the timestamp server's certificate. The default is FALSE. For Internet Explorer 4.0 or later only.
10 | Only trust items found in the Trust database | If TRUE, allows downloads from publishers that are contained in the Personal Trust Database. The default is FALSE. For Internet Explorer 4.0 or later only.

Using SetReg

The following command lists the syntax and options for using SetReg:

setreg -?

The following command makes a test root trusted. By default, a test root is not trusted. After any changes in the key values are made, a list of the current value of all the key values is displayed. If the -q option is used, the key values are not displayed:

setreg 1 TRUE

The following command makes a test root untrusted and causes all verification to check for revocation. The -q option is used so that the list of key values is not displayed:

setreg -g 1 FALSE 3 TRUE

Note Commands, options, and arguments are not case-sensitive.


Signcode

The Cabinet File Signing Utility (signcode) signs a cabinet file with Java permissions. This gives developers detailed control over the security restrictions placed on their applet when it is used over the Internet or an intranet.

Use the following command to run signcode:

signcode [options] <filename>

Signcode Command-Line Arguments

options | One or more signcode options.
filename | Cabinet file to be signed.

Signcode Command-Line Options

/a /c /cn /i /j /jp /k /ky /n /p /r /s /sp /spc /t /tr /tw /v /x /y /$ /?

Usage Notes

To add the Java permission information into the signature, add the /j JavaSign.dll option to signcode. You may also specify the /jp option for finer control over the exact permissions in the signature.

Note To sign with an SPC file, the required options are /spc and /v if your private key is in a PVK file. If you private key in is a registry key container, /spc and /k are the required options.

Command-line options can be used with either a forward slash (/) or a hyphen (-).

See Also

Signcode Options

Signing Cabinet Files with Java Permissions


Signcode Options

This section describes signcode command-line options.

/a <algorithm>

Specifies the hashing algorithm for signing; can be one of <md5 | sha1>. The default is md5.

/c <file>

Specifies the software publishing certificate file.

/cn <name>

Specifies the common name of the certificate.

/I <info>

Specifies where to get more information on content (usually a URL).

/j dllname

Specifies the name of the DLL that provides attributes of the signature.

/jp <level>

Specifies the level of permissions to encode in the cabinet file. This must occur immediately after the /j parameter. You can use any of the following flags.

Low | Medium | High
LowX | MediumX | HighX

If the string is not one of these six flags, it is accepted as the name of a .ini file that gives the permissions to encode. You can manually create this .ini file following the example provided by the sample permissions .ini file Alternatively, use the piniedit tool to automatically generate the .ini file. For more details on custom permissions, see Security and the Java Permissions .ini Values Reference.

If the /jp option is not specified, a default level of LowX will be used.

/k <keyname>

Specifies the key container name.

/ky <keytype>

Specifies the key type.

/n <name>

Specifies the text name that represents the content of the file to be signed.

/p <provider>

Specifies the name of the cryptographic provider on the system.

/r <location>

Specifies the location of the certificate store in the registry; can be either <HKEY_LOCAL_MACHINE | HKEY_CURRENT_USER>. The default is HKEY_CURRENT_USER.

/s <store>

Specifies the store containing certificates (the default to my+root+ca+spc).

/sp <chain|spcstore>

Specifies whether to add all the certificates in the chain (chain), or add them until one certificate in the chain is from the SPC store (spcstore). The default is spcstore.

/spc <file>

Specifies the SPC file containing software publishing certificates.

/t <URL>

Specifies the time stamp server's http address.

/tr <number>

Specifies the number of time stamp trials until success; defaults to 1.

/tw <number>

Specifies the delay in number of seconds between each time stamp. Defaults to 0 (zero).

/v <pvkfile>

Specifies the name of the PVK file containing the private key.

/x

Time stamps the file; does not sign it.

/y <type>

Specifies the cryptographic provider type to use.

/$ <authority>

Specifies the signing authority of the certificate; can be either <individual | commercial>. The default is using the certificate's highest permission.

/?

Displays signcode usage information including a list of available options.


Package Manager Tools

The Microsoft SDK for Java provides the Package Manager Archive Utility (clspack) to manage packages.


Clspack

The Package Manager Archive Utility (clspack) writes packages that are installed with the Java Package Manager (JPM) to a .zip file archive.

clspack [options] [zipfile] [packagelist]

Clspack Command-Line Arguments

options | One or more clspack options.
zipfile | The .zip file to be created.
packagelist | The text file containing the list of packages to write to the zipfile.

Clspack Command-Line Options

-auto -dump

Usage Notes

The Microsoft® Windows®-based clspack utility writes the contents of packages that are installed with JPM to a .zip file archive. This avoids constant downloads of the classr.exe self-extracting archive; you can create your own archive from the contents of JPM.

Clspack reads from a text file that contains the list of packages to write to the .zip file archive. This enables you to archive only packages that you need. The clspack utility is case insensitive, so packages like com.ms.activeX and com.ms.util.InputMethod are parsed as com.ms.activex, and com.ms.util.inputmethod, respectively. The following example shows how to create a .zip file using the contents of a text file, which lists the following packages:

java.io
com.ms.util
com.ms.util.cab
com.ms.util.InputMethod

Clspack automatically skips non-system classes (including when the -dump or -auto options are used from a command line). The utility will export any class, however, if it is included in the text file that lists the packages.

See Also

Clspack Options

Java Package Manager

Javasrc


Clspack Options

This section describes the command-line options that can be used with clspack.

-auto

Creates a single Classes.zip file and adds it to your class path, if not already present. This .zip file contains all the system classes stored in JPM. The Microsoft compiler for Java (jvc) checks this location by default; there is no need to set your CLASSPATH environment variable. If you use another Java compiler that does not check this location, set your CLASSPATH environment variable as follows:

C:\>set CLASSPATH=%WINDIR%\java\classes\classes.zip

Use javasrc to extract the contents of classes.zip.

-dump <outputfile>

Writes all the system packages that are currently installed in JPM to the specified output file.


Miscellaneous Tools

The Microsoft SDK for Java provides the following additional tools:

IntegrationClasses and IntegrationClasses2000 install Microsoft integration packages.

VM Uninstaller removes the Microsoft virtual machine (Microsoft VM) from a computer.


IntegrationClasses

 Microsoft SDK for Java

IntegrationClasses and IntegrationClasses2000

These tools install packages and .cab files for use in integrating Java with other technologies.

IntegrationClasses.exe is for use on machines running versions of Microsoft® Windows® prior to Microsoft® Windows® 2000. It installs the following Microsoft packages and .cab files:

  • com.ms.asp (Active Server Pages classes)

  • com.ms.iis.asp (Active Server Pages classes)

  • com.ms.osp (OLE DB Simple Provider classes)

  • com.ms.mtx (MTS classes)

  • iejava.cab (Microsoft® Internet Explorer classes)

To install these packages, run IntegrationClasses.exe from the %SDKDir%\Bin directory.

IntegrationClasses2000.exe is for use on computers running Windows 2000. It installs the com.ms.iis.asp package, which is required for running the ASP Java Component Framework Samples. It also installs iejava.cab, which contains classes that are hooks from Java into Microsoft® Internet Explorer. To install these packages and classes, run IntegrationClasses2000.exe from the %SDKDir%\Bin directory. The other packages cannot be installed on Windows 2000 machines.

Important Iejava.cab uses system tools that are installed by Internet Explorer 4.0 or later. You should not run these Integration .exe files on early Windows 95 computers that have no browser, or that have a version of Internet Explorer prior to 4.0.

Important Windows 2000 installs updated versions of the com.ms.asp and com.ms.mtx packages in the Java\trustlib directory rather than into the Java Package Manager. If you run the IntegrationClasses.exe that was included in the Microsoft® SDK for Java version 3.2 to install these packages into the Java Package Manager on a computer running Windows 2000, the older versions of these packages will override the newer versions installed in the Java\trustlib. (The IntegrationClasses.exe in the version 4.0 SDK will not update a Windows 2000 system.)

To fix this, follow these steps to remove the com.ms.asp and com.ms.mtx packages from the Java Package Manager:

  1. Launch the regedit utility (Registry Editor) to view the registry. From the Start menu, select Run and then type regedit.

    Warning Using the Registry Editor incorrectly can cause serious problems that might require you to reinstall your operating system. Microsoft cannot guarantee that problems resulting from the incorrect use of the Registry Editor can be solved. Use the Registry Editor at your own risk.

    For information on editing the registry, see the Changing Keys and Values Help topic in regedit.exe or the Add and Delete Information in the Registry and Edit Registry Data Help topics in regedt32.exe. Note that you should back up the registry before editing. You should also update your Emergency Repair Disk (ERD).

  2. In the regedit window, locate the following:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Code Store Database\Global Namespace\Java Packages\com\ms

  3. Locate the asp key, which will contain values such as the following:
    "Path"="C:\WINNT\JAVA\Packages\MHZ9VDRB.ZIP"
"Signer"="C:\WINNT\JAVA\Packages\Data\W13XZL3Z.DAT"
"Info"=hex:00,00,05,00,5f,0c,00,00,1a,00,00,00
  4. Locate the .zip file listed in the "Path" value. Create a directory on your drive and move the .zip file from the location specified in the path value to the new directory.

  5. Delete the asp key from the registry.

  6. Locate the mtx key, which will contain values such as the following:
    "Path"="C:\WINNT\JAVA\Packages\HGZQ9UUOX.ZIP"
"Signer"="C:\WINNT\JAVA\Packages\Data\Q24YAM4A.DAT"
"Info"=hex:00,00,05,00,5f,0c,00,00,1a,00,00,00
  7. Locate the .zip file listed in the "Path" value. Create a directory on your drive and move the .zip file from the location specified in the path value to the new directory.

  8. Delete the mtx key from the registry.

For more information about integrating Java with other technologies, see Integration.chm in the %SDKDIR%\Docs directory.


VM Uninstaller

The VM Uninstaller removes the Microsoft VM from a computer. You can then install previous versions of the Microsoft VM with no version conflicts.

Use the following command to run the VM Uninstaller:

Uninstaller.exe [options]

VM Uninstaller Command Line Arguments

[options] Any of the following command–line options:
  • noreboot

    Runs the VM Uninstaller without rebooting your computer.

  • quiet

    Disables warning messages.

  • help

    Displays Help on the VM Uninstaller’s command-line options.

Usage Notes

To use the VM Uninstaller

  1. Run Uninstaller.exe, which is located in the %SDKDIR%\Bin directory. The following warning message appears:

    Warning Some Java-dependent applications may require reinstallation after running the VM Uninstaller. Systems running Internet Explorer 4.0x require Microsoft VM version 3167 or later to function correctly.

  2. Click OK to continue the uninstall process. The following message appears:

    Windows will restart to ensure that no applications are running Java.

    If you are sure Java is not active, click Cancel and rerun with the noreboot option.

  3. Click OK to uninstall the VM. The VM Uninstaller now closes all applications, then restarts your computer. The VM Uninstaller window now appears.

  4. Click OK to start the VM uninstall process. The status bar indicates which step in the removal process is being executed.

Before executing, the VM Uninstaller checks what’s shown in the following table.

Operating System | The VM Uninstaller will not run under Microsoft® Windows® 2000 build 2031 or later. The security settings of this build do not allow the user to change the system directory.
Administrative Rights | You must have administrative privileges to remove the Microsoft VM from a computer running Microsoft® Windows NT®.

The VM Uninstaller removes registry keys that were installed with the Microsoft VM and other files that were installed by Microsoft applications. The VM Uninstaller also displays the registry keys that cannot be removed. In this case, you can choose to continue or cancel the process.

You can uninstall without rebooting by using the noreboot option.

You can also combine command-line options. For example, to disable warning messages and uninstall without rebooting, use the following command:

Uninstaller.exe quiet noreboot

Important If you want to install Microsoft VM build 2439 after you uninstalled your existing Microsoft VM, use the following instructions:

  1. In the MS-DOS® Command Prompt window, change to the directory where MSJavx86.exe, which is the Microsoft VM, is stored.

  2. Type the following command:

    Msjavx86.exe /n:v


Jvc Errors and Warning Messages

This section contains a listing of all errors and warning messages produced by the jvc compiler.

Error Message Links

J0001–J0020 | J0021–J0040 | J0041–J0060
J0061–J0080 | J0081–J0100 | J0101–J0120
J0121–J0140 | J0141–J0160 | J0161–J0180
J0181–J0200 | J0201–J0220 | J0221–J0242
J0243-J0263 | J0264-J0500 |

Warning Message Links

J5001-J5020

J5021-J5500


J0001-J0020

 Microsoft SDK for Java

J0001–J0020

J0001 | J0002 | J0003
J0004 | J0005 | J0006
J0007 | J0008 | J0009
J0010 | J0011 | J0012
J0013 | J0014 | J0015
J0016 | J0017 | J0018
J0019 | J0020 |

J0001 - INTERNAL COMPILER ERROR: 'identifier'

The compiler was unable to recover after detecting an error. Contact Microsoft Product Support Services for further assistance on how to resolve this problem.

J0002 - Out of memory

The compiler attempted to allocate some additional memory during processing, but was unable to do so. When this error occurs, check the location, size, and validity of your system swap file. Also, check that there is sufficient growth space available on the drive on which your swap file resides. This error can also occur if a source file is too large. Break your source file into smaller blocks, and then try compiling again.

J0003 - Invalid code: 'string'

The compiler may have detected generation of invalid code. Try dividing larger methods defined within your classes into smaller methods and compiling again.

J0004 - Cannot open class file 'file name' for reading

The compiler could not open the program source file for reading. This error most likely occurs when another program has an exclusive lock on the source file. Try shutting down other processes that may be accessing the source file and compiling again.

J0005 - Cannot open class file 'file name' for writing

The compiler failed to generate the output .class file. This error most likely occurs when the compiler cannot get write or create permission for the file. Make sure the file does not have its read-only attribute set, and that it is not currently in use by another process. This error can also occur when you are currently running or debugging the program that contains the specified .class file. Stop all running instances of the program and try compiling again.

J0006 - Cannot read class file 'file name'

The compiler failed to read the specified .class file. This error most likely occurs when the compiler encounters an error reading the storage device, or when the compiler cannot otherwise get read permission for the file. Check to ensure the file is not currently in use by another process. Also, use whatever means available (for example, SCANDISK) to ensure the validity of the storage device you are attempting to use.

J0007 - Cannot write class file 'file name'

The compiler failed while attempting to write the contents of a buffer to the specified .class file. This error most likely occurs when space is exhausted on the targeted storage device. Try freeing up any available space on the storage device and compiling again.

J0008 - Cannot locate class file 'file name'

The compiler could not locate a core language class for the java.lang package. This error most likely occurs when the Java CLASSPATH variable is not properly set. Try correcting the CLASSPATH environment variable, and compiling again.

J0009 - Not used

This error message is currently not used.

J0010 - Syntax error

The compiler could not determine the meaning of an expression or statement within the source program. This error most likely occurs when the line indicated in the error message is syntactically invalid. This error usually accompanies a more descriptive error. Try correcting any accompanying errors and compiling again.

The following sample illustrates this error.

public class Simple {

   public void method1() {
      int i =; // error: initialization error
   }
}

J0011 - Expected ':'

The compiler expected to find a colon following a case label or in a conditional expression that makes use of the ternary operator. This error most likely occurs when the colon is accidentally omitted. Many times this error is caused on the line previous to the line the compiler has reported the error on. Check to make sure lines that require a colon are correct, and then compile again.

The following sample illustrates this error.

public class Simple {

   private int i;
   private static int x = 1;

   public void method1(int arg1) {

      switch (arg1) {
         case 1 // error: ':' omitted
            ; // do something meaningful
      }

      i = ( arg1 &lt; x) ? arg1  x; // error: ':' omitted
   }
}

J0012 - Expected ';'

The compiler expected to find a semicolon in the position indicated by the error message. This error most likely occurs when the semicolon is accidentally omitted from the end of a statement. This error can also occur when a conditional expression is not syntactically correct. Many times this error is caused on the line previous to the line the compiler has reported the error on. Check to make sure both lines of source code have proper semicolon usage, and then compile again.

The following sample illustrates this error.

public class Simple {

   private static int x = 10 // error: ';' omitted

   public void method1(int arg1) {

      for (int i = 1; i &lt; x i++) {
         // error: ';' omitted
         ;
      }
   }
}

J0013 - Expected '('

The compiler expected to find a left parenthesis in the position indicated by the error message. This error most likely occurs when the left parenthesis is accidentally omitted in any of the following situations:

  • type initializations

  • catch statements

  • parenthesized expressions

  • while loops

  • for loops

  • if-else statements

The following sample illustrates this error.

public class Simple {

   private int i;

   public void method1(int arg1, int arg2) {

      if arg1 &lt; arg2) // error: '(' omitted
         i = arg1;
      else
         i = arg2;

   }
}

J0014 - Expected ')'

The compiler expected to find a right parenthesis in the position indicated by the error message. This error most likely occurs when the right parenthesis is accidentally omitted in any of the following situations:

  • type initializations

  • type casts

  • catch statements

  • parenthesized expressions

  • while loops

  • for loops

  • if-else statements

The following sample illustrates this error.

public class Simple {

   private int i;

   public void method1(int arg1, int arg2) {

      i = (arg1 &lt; arg2 ? arg1 : arg2;
      // error: ')' omitted
   }
}

J0015 - Expected ']'

The compiler expected to find a right square bracket in the position indicated by the error message. This error most likely occurs when the right square bracket is accidentally omitted from an array declaration. Many times this error is caused on the line previous to the line the compiler has reported the error on. Check to make sure all brackets match again.

The following sample illustrates this error.

public class Simple {

   private int x[ = new int[500]; // error: ']' omitted

}

J0016 - Expected '{'

The compiler expected to find a left brace in the position indicated by the error message. This error most likely occurs when the left brace is accidentally omitted from the beginning of a class declaration or method code block. Many times this error is caused on the line previous to the line the compiler has reported the error on. Check to make sure all braces match, and then compile again.

The following sample illustrates this error.

public class Simple // error: '{' omitted

   public void method1() {
      // do something meaningful
   }
}

J0017 - Expected '}'

The compiler expected to find a right brace in the position indicated by the error message. This error most likely occurs when a class or method's closing brace is not found. Many times this error is caused on the line previous to the line the compiler has reported the error on. Check to make sure all braces match, and then compile again.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      int arr[] = {1, 2A};
      // error: invalid initialization

   }
}

J0018 - Expected 'while'

The compiler expected to find the keyword while in the position indicated by the error message. This error most likely occurs when a do/while loop is not syntactically correct. The correct structure for a do/while loop is:

do {
   // do something useful here
} while (condition);

J0019 - Expected identifier

The compiler expected to find an identifier toward the end of a class, interface, variable, or method declaration. This error most likely occurs when the type is accidentally omitted in a declaration.

The following sample illustrates this error.

public class Simple {

   private i;  // error: type omitted

}

J0020 - Expected 'class' or 'interface'

The compiler expected to find either class or interface used within the corresponding declaration. This error most likely occurs when the keywords are accidentally omitted from a class or interface declaration. Another possible cause of this error is unbalanced scoping braces.

The following sample illustrates this error.

public class Simple {

   // do something meaningful

}}   // error: additional '}' is the problem


J0021-J0040

J0021 | J0022 | J0023
J0024 | J0025 | J0026
J0027 | J0028 | J0029
J0030 | J0031 | J0032
J0033 | J0034 | J0035
J0036 | J0037 | J0038
J0039 | J0040 |

J0021 - Expected type specifier

The compiler expected to find a type specifier in the position indicated by the error message. Other errors may accompany this error due to the missing type specifier.

The following example illustrates this error.

public class Simple {

   public Object o =new; //error: missing 'Object' type specifier
}

J0022 - Expected end of file

The compiler expected to encounter an end-of-file character, but did not. This error most likely occurs when the source file has been damaged in some way. Try visually checking the source file for obvious corruption, save any changes, and then compile again.

J0023 - Expected 'catch' or 'finally'

The compiler expected to find a catch or finally block immediately following a corresponding try block.

The following sample illustrates this error.

public class Simple {

   public void method1( ) {

      try {
         // do something meaningful
      }

   } // error: 'catch' or 'finally' not found
}

J0024 - Expected method body

The compiler expected to find a method body immediately following a method declaration. This error most likely occurs when the braces surrounding the method body are not properly balanced. This error may also occur when the method was intended to be abstract or native, but the abstract or native keyword was mistakenly omitted from the method declaration.

The following sample illustrates this error.

public abstract class Simple {

   public void method1( );
   // error: 'abstract' omitted

}

J0025 - Expected statement

The compiler expected to find a statement before the end of the current scope. This error most likely occurs when the right brace designating the end of the current scope is misplaced.

The following sample illustrates this error.

abstract class Simple {

   void method1() {

      if (1)
      // error: a statement is required
      // after the if statement
   }
}

J0026 - Expected Unicode escape sequence

The compiler expected to find a valid Unicode escape sequence. This error most likely occurs when a syntactical error is found in a Unicode escape sequence.

The following sample illustrates this error.

public class Simple {

   int i = \\u0032;
   // error: '\\' not invalid

}

J0027 - Identifier too long

The compiler detected an identifier name with a length greater than 1024 characters. Shorten the identifier name, and then compile again.

J0028 - Invalid number

The compiler detected a numeric value that the Java language is not capable of supporting. This error most likely occurs when the number specified is an amount greater than any of the Java language's primitive types can accept.

The following sample illustrates this error.

public class Simple {

   long i = 12345678901234567890;
   // error: value out of range

}

J0029 - Invalid character

The compiler detected an ASCII character that could not be used in an identifier. This error most likely occurs when a class, interface, method, or variable identifier includes an invalid character.

The following sample illustrates this error.

public class Simple {

   private int c#;
   // error: '#' not supported

}

This error may also occur when you compile code that uses conditional directives (such as #if, #else, #endif, #define, and so on) without enabling the Microsoft language extensions. The Microsoft compiler for Java (jvc.exe) now disables Microsoft language extensions by default. To enable Microsoft extensions, use the /x- option with jvc. To define conditional compilation symbols, you should also use the /D <symbol> option:

jvc /x- /D <symbol>  Test.java

Compiling with the /x- option generates a message warning that the use of Microsoft extensions results in compiled code that will run only on Windows systems with the Microsoft virtual machine installed and may not run on other virtual machines. You can disable this message by using the /nomessage option with jvc. For example:

jvc /x- /D <symbol> /nomessage Test.java

J0030 - Invalid character constant

The compiler detected an attempt to assign an invalid character or character escape sequence to a variable of type char.

The following sample illustrates this error.

public class Simple {

   char c = '\';
   // error: invalid escape character

}

J0031- Invalid escape character

The compiler detected the use of an invalid escape character. This error most likely occurs when a syntactical error is found in a Unicode escape sequence.

The following sample illustrates this error.

public class Simple {

   int i = \u032;
   // error: Unicode uses 4 hex digits
   int x = \u0032;
    //correct assignment of a unicode escape sequence

}

J0032 - Unterminated string constant

The compiler did not detect a terminating double-quote character at the end of a string constant. This error most likely occurs when the string terminator is accidentally omitted, or when the string constant is mistakenly divided onto multiple lines.

The following sample illustrates this error.

public class Simple {

   String str = "Hello
   // error: '"' and ';' omitted

}

J0033 - Unterminated comment

The compiler detected the beginning of a block comment, but did not detect a valid ending for it. This error most likely occurs when the comment terminator is accidentally omitted.

The following sample illustrates this error.

public class Simple {

   /* This comment block
    * does not have a valid
    * terminator

}

J0034 - Not used

This error message is currently not used.

J0035 - Initializer block must be declared 'static'

The compiler detected a modifier other than static associated with an initializer. Initializers can only use the static keyword to specify the initializer as a static initializer or no modifier to signify that the initializer is a field initializer. Remove the modifier from the initializer specified in the error message or add the static modifier to the initializer, and then compile again.

The following sample illustrates this error.

public class Simple {

   static private int i;

   {   // error: 'static' omitted
      i = 1;
   }
}

J0036 - A data member cannot be 'native', 'abstract' or 'synchronized'

The compiler detected one of the modifiers previously shown used in the declaration of a variable. The modifiers synchronized and native can only be applied to method declarations. The abstract modifier can be applied to methods, classes, and interfaces.

J0037 - A method cannot be 'transient' or 'volatile'

The compiler detected one of the modifiers shown above used in the declaration of a method. The modifiers transient and volatile can only be applied to field declarations.

J0038 - 'final' members must be initialized

The compiler detected an uninitialized final variable in an interface definition. Variables declared as final in an interface definition must have their value set at declaration. Once set, the value cannot be programmatically changed.

The following sample illustrates this error.

public class Simple {

   private final int COOL_RAD;
   // error: must have value set

}

Note that variables declared within interfaces are implicitly defined as final or static. As such, this error also occurs when their initial values are not set at declaration.

J0039 - Not used

This error message is currently not used.

J0040 - Cannot define body for abstract/native methods

The compiler detected a method body defined immediately following the corresponding declaration of an abstract or native method. An abstract method must have its implementation code defined in a subclass. Native methods are implemented using code of a native language, such as C++.

The following sample illustrates this error.

public interface Simple {

   public void method1() {
      // error: must define this method body
      // in a class that implements the
      // 'Simple' interface
   }
}

Note that methods declared within an interface are implicitly abstract. As such, this error will also occur when you attempt to define a method body in an interface.


J0041-J0060

J0041 | J0042 | J0043
J0044 | J0045 | J0046
J0047 | J0048 | J0049
J0050 | J0051 | J0052
J0053 | J0054 | J0055
J0056 | J0057 | J0058
J0059 | J0060 |

J0041 - Duplicate modifier

The compiler detected a modifier used twice in a declaration. This error most likely occurs when the same modifier is mistakenly used more than once within a declaration.

The following sample illustrates this error.

public class Simple {

   public public void method1() { // error: 'public' used twice
      // do something meaningful
   }
}

J0042 - Only classes can implement interfaces

The compiler detected an interface declaration using the implements keyword. Interfaces cannot implement other interfaces. Interfaces may only be implemented by classes.

The following sample illustrates this error.

public interface Simple implements color{
   // error: 'Simple' cannot implement the
   // 'color' interface

}
interface color {
   // do something meaningful
}

J0043 - Redeclaration of member 'identifier'

The compiler detected the same identifier name being declared more than once within the same scope. This error most likely occurs when a variable is mistakenly declared more than once.

The following sample illustrates this error.

public class Simple {
   private int i;
   private int i; // error: 'i' declared twice
}

J0044 - Cannot find definition for class 'identifier'

The compiler could not locate the definition for the specified class. This error is most likely caused by a typographical error. It may also occur when the package containing the specified class cannot be found.

The following sample illustrates this error.

public class Simple {

   char buf[] = new chaar[5];
   // error: 'chaar' not a valid type

}

J0045 - 'identifier' is not a class name

The compiler detected one of the following conditions:

  • A class name provided as part of an import statement could not be found or the import statement was not syntactically valid.

  • The class attempted to extend an interface.

Make sure that the package exists and that any classes that you import exist in the package specified in the import statement, and then compile again.

The following sample illustrates this error.

package non.existent;

import non.existent; // error:

public class Simple {

   // do something meaningful

}

J0046 - 'identifier' is not an interface name

The compiler detected that the identifier referred to by the keyword implements is not an interface.

The following sample illustrates this error.

class Simple2 {

   // do something meaningful

}
public class Simple implements Simple2 {

   // error: cannot implement class 'Simple2'

}

J0047 - 'identifier' is not a package name

The compiler detected an invalid package name. This error most likely occurs when a syntactical error exists in an import statement or when the package name does not otherwise exist.

J0048 - Cannot extend final class 'identifier'

The compiler detected an attempt to subclass a class declared with the keyword final. Classes declared as final cannot be subclassed.

The following sample illustrates this error.

final class Simple2 {

   // do something meaningful

}
public class Simple extends Simple2 {

   // error: cannot extend 'Simple2'

}

J0049 - Undefined name 'identifer'

The compiler detected an unknown class name while processing an import statement. This error most likely occurs when the identifier is misspelled or does not exist. This error may also occur if the CLASSPATH environment variable is not set correctly.

The following sample illustrates this error.

import java.io.bogus; // error: unknown class name

public class Simple {

   // do something meaningful

}

J0050 - 'identifier' is not a member of 'identifier'

The compiler detected a reference to an identifier that is not a member of the specified package. This error most likely occurs when the identifier is misspelled or does not exist.

The following sample illustrates this error.

class Simple2{
   public void methodx(){}
}
public class Simple {

   public void method1() {
      Simple2 smp = new Simple2();
      smp.method2();
      // error: 'method2' not member of 'Simple2'
   }
}

J0051 - Undefined package 'identifier'

The compiler detected a package name, but was unable to locate the package definition. This error most likely occurs when a syntactical error exists in an import statement. This error may also occur when the package cannot be found or does not exist. Make sure the path is set in the CLASSPATH environment variable.

The following sample illustrates this error.

import java.lang.String.*;
// error: 'String' not a valid package name
public class Simple {

   // do something meaningful

}

J0052 - Not used

This error message is currently not used.

J0053 - Ambiguous name: 'identifier' and 'identifier'

The compiler could not resolve an ambiguity between the two identifiers shown. The error most likely occurs when the same class name occurs in two packages that are both imported into a source file using the "*" class import specifier. Make sure that you do not have two classes with the same name in the packages you are importing into your source file.

J0054 - Not used

This error message is currently not used.

J0055 - Not used

This error message is currently not used.

J0056 - Missing return type specification

The compiler detected a method declaration without a return type specified. All method declarations must specify a return type. If the method is not meant to return a value, use the void keyword.

The following sample illustrates this error.

public class Simple {

   public method1() { // error: no return type

      // do something meaningful
   }
}

J0057 - Class file 'identifier' doesn't contain class 'identifier'

The compiler did not detect the class name previously shown within the specified file. This error most likely occurs when the class name is either misspelled or does not exist. This error may also occur when a .class file has been renamed after successful compilation.

J0058 - Cannot have a variable of type 'void'

The compiler detected a variable declared as type void. The keyword void is not allowed in variable declarations. Rather, void can only be used as a method return type, indicating that the method does not actually return a value.

The following sample illustrates this error.

public interface Simple {

   public final static void i = 1;
   // error: 'void' not valid
}

J0059 - Cannot reference member 'identifier' without an object

The compiler detected an attempt to reference a variable without a known object association. This error most likely occurs when an instance field or method (a field or method declared without the keyword static) is referenced from within a static method without a valid instance. Static methods cannot use instance fields and methods without a valid instance of the class.

The following sample illustrates this error.

public class Simple {

   private int x;

   public static void method1() {

      x = 0; // error: 'x' must be static
   }
}

J0060 - Invalid forward reference to member 'identifier'

The compiler detected an attempt to initialize a variable with another variable that had not yet been defined. To avoid this situation, reverse the field declarations order so that a variable that is referenced by another is defined first.

The following sample illustrates this error.

public class Simple {

   private static int i = j;
   // error: 'j' not yet defined
   private static int j = 0;
}


J0061-J0080

J0061 | J0062 | J0063
J0064 | J0065 | J0066
J0067 | J0068 | J0069
J0070 | J0071 | J0072
J0073 | J0074 | J0075
J0076 | J0077 | J0078
J0079 | J0080 |

J0061 - The members 'identifier' and 'identifier' differ in return type only

The compiler detected a subclass method attempting to overload a base class method, but the methods differed only in return type. In Java, overloaded methods must be distinguished by unique signatures. A unique signature consists of the method name, the number, type and positions of its parameters, and the return type.

The following sample illustrates this error.

public class Simple extends Simple2 {

   public void method1() {
      // error: only return type differs
   }
}
class Simple2 {

   public int method1() {

      return 1;
   }
}

J0062 - Attempt to reduce the access level of member 'identifier'

The compiler detected an overridden method in the class being compiled that reduces the access level of its base class method. The base class access modifier for a method must be maintained by all derived classes that want to overload the method.

J0063 - Declare the class abstract, or implement abstract member 'identifier'

The compiler detected the declaration of an abstract method within a class, but the class was not declared to be abstract.

The following sample illustrates this error.

public class Simple {

   public abstract void method1();
   // error: class not abstract

}

J0064 - Not used

This error message is currently not used.

J0065 - Cannot assign to this expression

The compiler detected an expression in the position normally held by an lvalue for assignment. This error most likely occurs when an expression is being assigned a value, but the expression is not capable of accepting the assignment.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      int x = 0;
      int y = 1;

      x++ = y; //error: '++' not valid
   }
}

J0066 - 'this' can only be used in non-static methods

The compiler detected use of the keyword this within a class (or static) method. Class methods are not passed implicit this references. As such, they cannot reference instance (non-static) variables or methods.

The following sample illustrates this error.

public class Simple {

   int x;

   public static void method1() {

      this.x = 12; // error: 'this' instance specific
   }
}

J0067 - Cannot convert 'identifier' to 'identifier'

The compiler detected a variable type used out of its correct context. As such, the compiler could not implicitly convert the result to anything meaningful. Convert the value you are attempting to use to something the method or field definition requires, and then compile again.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      int i = 10;

      if (i--) {
         // error: conditional needs expression
         // or boolean variable
      }
   }
}

J0068 - Cannot implicitly convert 'identifier' to 'identifier'

The compiler could not convert the specified variable without an explicit typecast. The error most likely occurs when a numeric field is assigned to a data type that is not numeric. Use a typecast to convert the data type to the appropriate data type, and then compile again.

The following sample illustrates this error.

public class Simple {

   int i = 10;

   public char method1() {

      return i; // error: expected type char
   }
}

J0069 - Cannot apply '.' operator to an operand of type 'identifier'

The compiler detected the '.' operator applied to an invalid type. This error most likely occurs when the length method is applied to an invalid type.

The following sample illustrates this error.

public class Simple {

   int i = 123;
   int j = i.length; // error: 'i' not an array

}

J0070 - Not used

This error message is currently not used.

J0071 - Not used

This error message is currently not used.

J0072 - 'identifier' is not a member of class 'identifier'

The compiler detected a method call, but the method remains undefined. This error most likely occurs when the method name is either misspelled or cannot be found within proper scope. This error may also occur when the method does not exist. Make sure that the member you are trying to reference exists in the specified class.

The following sample illustrates this error.

public class Simple {

   public static void main(String args[]) {

      System.out.printline("Hello");
      // error: 'printline' should be 'println'
   }
}

J0073 - Not used

This error message is currently not used.

J0074 - Operator cannot be applied to 'identifier' and 'identifier' values

The compiler detected an operator that cannot be correctly applied to the identifiers shown in the error message. This error most likely occurs when two fields are non-numeric and operators used for numbers are applied to the fields.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      String s1 = "one";
      String s2 = "two";
      String result;

      result = s1 * s2; // error: invalid operands
   }
}

J0075 - Invalid call

The compiler detected syntax for a method call, but the identifier does not represent a valid method name. This error most likely occurs when a method name is misspelled or contains characters that are not recognized as valid in Java naming conventions.

The following sample illustrates this error.

class Simple {

   int x = 1();
   //error: 1 is not a valid method name
}

J0076 - Too many arguments for method 'identifier'

The compiler detected a known method call, but the call contained more arguments than needed. Check the number of arguments for the method you are attempting to call, and remove any additional arguments from the call.

The following sample illustrates this error.

public class Simple {

   public void method1(int arg1) {

      // do something meaningful
   }

   public void method2() {

      method1(1, 2); // error: Too many arguments
   }

}

J0077 - Not enough arguments for method 'identifier'

The compiler detected a known method call, but the call contained fewer arguments than needed. This error most likely occurs when one or more arguments are accidentally omitted from the call.

The following sample illustrates this error.

public class Simple {

   public void method1(int arg1) {
      // do something meaningful
   }

   public void method2() {

      method1(); // error: Too few arguments
   }
}

J0078 - Class 'identifier' doesn't have a method that matches 'identifier'

The compiler identified a call to a known overloaded method within another class, but was unable to detect a matching method with the correct number of arguments. Make sure the overloaded method call has the correct number and type of arguments, and then compile again.

The following sample illustrates this error.

public class Simple {

   public void method1() {
      // do something meaningful
   }
   public void method1(int arg1) {
      // do something meaningful
   }
}
class Simple2 {

   public void method1() {

      Simple s = new Simple();
      s.method1(1, 2, 3); // error: too many args
   }
}

J0079 - Ambiguity between 'identifier' and 'identifier'

The compiler could not distinguish the correct method to execute. This error most likely occurs when two overloaded methods have related argument lists and the method call cannot be differentiated between the two methods. Make sure your method call is not using a parameter that conflicts with another overloaded method. Another way to avoid this error is to change the argument lists of the two overloaded methods so that they have a different number of arguments or more uniquely defined parameter data types.

The following sample illustrates this error.

public class Simple {

   static void method1(Simple2 s2, Simple3 s3) {
      // do something meaningful
   }

   static void method1(Simple3 s3, Simple2 s2) {
      // do something meaningful
   }

   public static void main(String args[]) {

      Simple2 s2 = new Simple2();
      method1(s2, s2);
      // error: Ambiguity between Simple2 and Simple3
   }
}
class Simple2 extends Simple3 {
   // do something meaningful
}
class Simple3 {
   // do something meaningful
}

J0080 - Value for argument 'identifier' cannot be converted from 'identifier' in call to 'identifier'

The compiler detected a method argument that does not match the parameters specified in the method declaration. This error most likely occurs when a numeric field is passed as an argument to a method but the method requires a different numeric type. To pass different numeric types to arguments of a method, typecast the field being passed to method.

The following sample illustrates this error.

public class Simple {

   public void method1(int arg1) {
      // do something meaningful
   }

   public void method2() {

      float f = 1.0f;
      method1(f); // error: mismatched call types
   }
}


J0081-J0100

J0081 | J0082 | J0083
J0084 | J0085 | J0086
J0087 | J0088 | J0089
J0090 | J0091 | J0092
J0093 | J0094 | J0095
J0096 | J0097 | J0098
J0099 | J0100 |

J0081 - Value for argument 'identifier' cannot be converted from 'identifier' in call to 'identifier'

The compiler detected a method call, but was unable to convert one of the arguments from the supplied type to the type shown in the method declaration. This error most likely occurs when a method is called with the arguments in the wrong order or the wrong method was called.

J0082 - Class 'identifier' doesn't have a constructor that matches 'identifier'

The compiler did not detect a constructor matching the call identified in the error. This error most likely occurs when a constructor is called with the wrong number of arguments. Check to make sure that the class has a constructor that matches the one you are attempting to call.

The following sample illustrates this error.

public class Simple {
   Simple(int arg1) {
      // do something meaningful
   }
   public static void main (String args[]) {

      Simple s = new Simple(12, 13);
      // error: too many arguments
   }
}

J0083 - 'super( )' or 'this( )' may only be called within a constructor

The compiler detected use of either the super() or this() keyword outside of a constructor. The super() keyword is used to call a superclass constructor, while the this() keyword is used to call one constructor from another. To reference methods in a base class, you must use the super keyword.

The following sample illustrates this error.

public class Simple {
   public void method1 () {
      super(); // error: 'super' cannot be called
   }
}
public class Simple{
   public method2(){
      super.method1(); //correct way to call a method of a superclass
   }
}

J0084 - Can't return a value from a 'void' method

The compiler detected an attempt to return a value from a method declared with a return type of void.

The following sample illustrates this error.

public class Simple {

   public void method1() {
      return 1; // error: cannot return a value
   }
}

J0085 - Expected return value of type 'identifier'

The compiler detected the keyword return within the body of a method which was declared to return a specific type, but the return had no associated value. The return statement with no associated value will not return a default value and thus must be assigned a valid return value.

The following sample illustrates this error.

public class Simple {

   public int method1() {
      return; // error: must return int value
   }
}

J0086 - '[]' cannot be applied to a value of type 'identifier'

The compiler detected array brackets used with a non-array variable type. Change the field to be a valid array declaration if you wish to use the field as an array.

The following sample illustrates this error.

public class Simple {

   public void method1() {
      int i = 0;
      int j, x;

      x = j[i]; // error: 'j' not declared as array
   }
}

J0087 - The 'goto' statement is not currently supported by Java

The keyword goto, while defined as a keyword, has not yet been implemented in the Java language.

J0088 - Not used

This error message is not currently used.

J0089 - Already had 'case: 'identifier'

The compiler identified two or more case statements with the same identifier or value occurring within the same switch statement.

The following sample illustrates this error.

public class Simple {

   public int method1(int arg1) {

      switch (arg1) {
         case 1:
            return (int) 1;
         case 2:
            return (int) 2;
         case 2: // error: duplicate of above
            return (int) 3;
         default:
            return (int) 0;
      }
   }
}

J0090 - Already had 'default'

The compiler identified two or more instances of the keyword default occurring within the same switch statement.

The following sample illustrates this error.

public class Simple {

   public int method1(int arg1) {

      switch (arg1) {
         case 1:
            return (int) 1;
         case 2:
            return (int) 2;
         default:
            return (int) 3;
         default: // error: duplicate of previous
            return (int) 0;
      }
   }
}

J0091 - 'case' outside of switch statement

The compiler identified the keyword case used outside the scope of a switch statement.

The following sample illustrates this error.

public class Simple {

   public int method1() {
      case 1: // error: no switch statement
         return 1;
   }
}

J0092 - Constant expression expected

The compiler has detected an expression that used a nonconstant value when a constant value was required. This error most likely occurs when a variable is used in a case statement. Check the expression and make sure that a constant value is being used.

The following sample illustrates this error.

public class Simple{
   int var1 = 10;
   int var2 = 20;
   public void method1(){
      switch(var1){
        case var2:
        //error: cannot use variable with case
      }
   }
}

J0093 - 'break' only allowed in loops and switch statements

The compiler detected the keyword break occurring outside the scope of a loop or switch statement.

J0094 - Label 'identifier' not found

The compiler detected a label name associated with one of the keywords continue or break, but could not find the label. This error most likely occurs when a label does not exist yet is being referenced by a break or continue statement. The error can also occur if the label is placed outside of the break or continue statement's scope. A label cannot reference labels in other classes or other source files. Check to make sure the break or continue statement can access a valid label, and then compile again.

The following example illustrates this error.

public class Simple{
   public int method1(){
      int y;
      for (int x = 0; x &#60; 10; x++){
         y = x *2;
         if (x == 5)
            break test; //error 'test' is not defined as a label
      }
      return y;
   }

The following example illustrates the proper usage of a label when used with the break or continue statements.

public class Simple{
   public int method1(){
      int y;
      for (int x = 0; x &#60; 10; x++){
         y = x *2;
         if (x == 5)
            break test; //error 'test' is not defined as a label
      }
      test:
      return y;
   }

J0095 - 'continue' only allowed in loop

The compiler detected attempted use of the keyword continue outside the scope of a loop.

J0096 - Class value expected

The compiler detected a synchronization block, but the synchronized modifier was applied to an invalid type. This error most likely occurs when an identifier other than a class object instance is used with the synchronized statement.

The following sample illustrates this error.

public class Simple {

   public void method1() {
      int i;
      synchronized (i);
      // error: 'i' must resolve to
      // class or array type
   }
}

J0097 - Class or array expected

The compiler detected the instanceof operator applied to a type that did not resolve to a class or array. The instanceof operator is used to determine if identifier is an instance of a specific class or array. Make sure the lvalue used with the instanceof operator references a class instance or array and the rvalue references a valid class name or array.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      Simple2 obj = new Simple2();

      if (obj instanceof int) // error: bad type
         ; // do something meaningful
   }
}
class Simple2 {
   // do something meaningful
}

J0098 - Attempt to access nonexistent member of 'identifier'

The compiler detected an array member that was specified, but could not identify it. This error most likely occurs when an attempt to reference the length method of an array is mistyped. This error can also occur when an attempt is made to call a method in an array of objects, but the call does not reference an element of the array.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      int j[] = new int[10];
      int i = j.bogus;
      // error: 'bogus' not valid member
   }
}

J0099 - Not used

This error message is currently not used.

J0100 - Cannot throw 'identifier' - the type doesn't inherit from 'Throwable'

The compiler detected an object in a throw statement that was not derived from the class Throwable. This error most likely occurs when a throw statement uses a class that does not inherit from the Throwable class. Check to make sure that the exception class you are throwing is a valid exception class.


J0101-J0120

J0101 | J0102 | J0103
J0104 | J0105 | J0106
J0107 | J0108 | J0109
J0110 | J0111 | J0112
J0113 | J0114 | J0115
J0116 | J0117 | J0118
J0119 | J0120 |

J0101 - The type 'identifier' does not inherit from 'Throwable'

The compiler detected an invalid class argument used as an argument in a catch declaration. When using a catch statement to handle exceptions, you must define it with a class derived from Throwable as a parameter. Make sure the class you defined for the catch statement is derived from Throwable, and then compile again.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      try {
         // do something meaningful
      } catch (String s) {
         // error: 'String' not a subclass
         // of 'Throwable'
      }
   }
}

J0102 - Handler for 'identifier' hidden by earlier handler for 'identifier'

The compiler detected an exception handler that will never be executed because an earlier handler would have already caught the exception. This error is most likely caused by putting catch statements in the wrong order.

The following sample illustrates this error.

class Simple {

   static
   {
      try
      {
      }
      catch (Exception e)
      {
      }
      catch (ArithmeticException e)
      {
      }
      // error: any exceptions this block
      // could have caught are already caught
      // by the first catch statement.
   }
}

J0103 - Cannot override final method 'identifier'

The compiler detected a class method attempting to override one of its base class methods, but the base class method was declared with the keyword final. Methods defined with the final modifier cannot be overridden by a derived class.

The following sample illustrates this error.

public class Simple extends Simple2 {

   public void method1() {
      // error: 'method1' final in superclass
   }
}
class Simple2 {

   public final void method1() {
      // do something meaningful
   }
}

J0104 - Unreachable statement or declaration

The compiler detected a statement or declaration that cannot be reached under any circumstances. This error most likely occurs when a return statement is called from a method and code is placed below the return statement. This error can also occur if a break statement is used in a loop without any flow control to allow code below it to be run.

The following sample illustrates this error.

class Simple {
   static
   {
      return;
      int x;
      //error: the declaration cannot be reached
   }
}

J0105 - Method 'identifier' must return a value

The compiler detected a method declaration, which included a return type other than void, but the keyword return was not found in the method body. This error most likely occurs when a method that returns a value is missing a valid return statement. This error can also occur if a return statement is called within a flow control block and cannot always accessed due to the logic of the method.

The following sample illustrates this error.

public class Simple {

   public int method1(int arg1) {

   } // error: expected an integer returned
}

J0106 - Class 'identifier' has a circular dependency

The compiler detected two or more classes directly or indirectly attempting to subclass each other. One class should act as the base class of the other.

The following sample illustrates this error.

public class Simple extends Simple2 {

   // error: extending 'Simple2'
}
class Simple2 extends Simple {

   // error: also extending 'Simple'
}

J0107 - Missing array dimension

The compiler detected the initialization of an array, but failed to detect a valid array dimension. This error most likely occurs when an array is defined but one of the dimensions of the array is not defined. To use an array, all dimensions must be defined.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      int [][] i = new int[][12];
      // error: missing first array dimension
   }
}

J0108 - Cannot 'new' an instance of type 'identifier'

The compiler detected an attempt to instantiate a data type that does not require use of the keyword new. This error most likely occurs when an attempt is made to use the new keyword with an intrinsic data type and the declaration is not an array. Make sure your member declaration does not use the new keyword unless it is a class object or array declaration.

The following sample illustrates this error.

public class Simple {

   public void method1() {
      int i = new int(5);
      // error: cannot use 'new' on 'int' types
   }
}

J0109 - Cannot 'new' an instance of abstract class 'identifier'

The compiler detected an attempt to instantiate a class object declared as abstract. A class declared as abstract cannot be instantiated and exists only as a base class for other classes to derive from.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      Simple2 s2Object = new Simple2();
      // error: class 'Simple2' declared as abstract
   }
}
abstract class Simple2 {
   // do something meaningful
}

J0110 - Cannot 'new' an interface 'identifier'

The compiler detected an attempt to instantiate an interface object declared as abstract. Note that interfaces are abstract by default, regardless whether the keyword abstract is used in their declaration.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      Simple2 s2Object = new Simple2();
      // error: interface Simple2 is abstract
   }
}
interface Simple2 {
   // do something meaningful
}

J0111 - Invalid use of array initializer

The compiler detected an attempt to initialize an array, but the initialization statement was not syntactically correct. Arrays can be initialized at declaration with an initial set of values. The compiler detected that the syntax of the initialization was incorrect. This error most likely occurs when trying to initialize a multidimension array with the incorrect number or positioning of braces and commas. Check the syntax of your array initialization, and then compile again.

J0112 - Cannot assign final variable 'identifier'

The compiler detected an attempt to change the value of a variable declared as final. A field declared as final cannot be assigned a value once it has been initialized with a value either at declaration or in an initializer block.

The following sample illustrates this error.

public class Simple {
   private final int i = 3;
   public void method1(int arg1) {
      i = arg1;
      // error: variable 'i' declared final
   }
}

J0113 - Call to constructor must be first in constructor

The compiler detected a constructor called from within the body of a second constructor, but the constructor call was not placed at the beginning of the second constructor body. In a constructor, calls to another constructor must be the first line of code in the constructor's body. Move the constructor call to the top, and then compile again.

The following sample illustrates this error.

public class Simple {

   int i, j;
   Simple () {

      i = 0;
   }

   Simple(int arg1) {

      j = arg1;
      this(); // error: call to Simple() must be first
   }
}

J0114 - Cannot reference 'this' in constructor call

The compiler detected a reference to this in a constructor. The this statement can only be used in a constructor to access methods and fields of the constructor's class. Usage of this(this) or super(this) in a constructor will cause this error to occur because the instance of the class has not yet been created, and thus cannot be passed to another constructor.

The following sample illustrates this error.

class SuperSimple {

   SuperSimple(Object o) { }
}
public class Simple extends SuperSimple {

   Simple()
   {
      super(this);
      //error: cannot refer to this in constructor
   }
}

J0115 - Cannot call constructor recursively

The compiler detected a recursive constructor call. This error most likely occurs when a constructor has a call to the same constructor. This error can also occur if one constructor calls a second constructor and the second constructor has a call back to the first constructor.

The following sample illustrates this error.

public class Simple {

   Simple (int arg1) {

      this(1);
      // error: constructor calling itself
   }
}

J0116 - Variable 'identifier' may be used before initialization

The compiler detected an attempt to use a variable before it was properly initialized. To use a variable in an assignment or expression, you need to assign a value to it. Initialize the variable in a constructor or field initializer, and then compile again.

The following sample illustrates this error.

public class Simple {

   static
   {
      int i;
      int j = i;
      // error: 'i' not yet initialized

   }
}

J0117 - Cannot declare a class to be 'private'

The compiler detected use of the modifier private in an outer class declaration. This modifier may only be used with fields, methods, and inner class declarations.

The following sample illustrates this error.

private class Simple {

   // error: a class cannot be 'private'

}

J0118 - Not used

This error message is currently not used.

J0119 - Not used

This error message is currently not used.

J0120 - Divide or mod by zero

The compiler detected a division by zero error in code.

The following sample illustrates this error.

public class Simple {

   final int x = 0;
   int y = 1 % x;
   //error: x cannot be 0

}


J0121-J0140

J0121 | J0122 | J0123
J0124 | J0125 | J0126
J0127 | J0128 | J0129
J0130 | J0131 | J0132
J0133 | J0134 | J0135
J0136 | J0137 | J0138
J0139 | J0140 |

J0121 - Unable to recover from previous error(s)

The compiler encountered a serious error and could not continue processing the file reliably. Try fixing whatever errors are already flagged, and then compile again.

J0122 - Exception 'identifier' not caught or declared by 'identifier'

The compiler detected an exception that was thrown but never caught within the exception class. This error most likely occurs when a method calls another method with a declaration to throw an exception. For a method to call another method that throws an exception, the method must either be declared to throw the exception or handle the error using a try catch combination.

The following sample illustrates this error.

class SimpleException extends Exception {
   // do something meaningful
}
class Simple {

   void method1() throws SimpleException { }
   void method2() { method1(); }
   // error: exception not declared for method2
}

J0123 - Multiple inheritance of classes is not supported

The compiler detected a class attempting to apply the keyword extends to more than one base class. This is defined as multiple inheritance in other languages and is not supported in Java.

The following sample illustrates this error.

public class Simple extends BaseClass1, BaseClass2 {
   // error: Multiple inheritance not supported in Java
}
class BaseClass1 {

   // do something meaningful
}
class BaseClass2 {

   // do something meaningful
}

J0124 - Operator cannot be applied to 'identifier' values

The compiler detected an operator being applied to a type it cannot be used with. Make sure the operation you are attempting is valid for the type of variable or object, and then compile again.

The following sample illustrates this error.

public class Simple {

   void method1(boolean b) {

      b++;
      // error: post increment operator cannot
      // be applied to boolean variables
   }
}

J0125 - 'finally' without 'try'

The compiler detected a finally block but did not find a corresponding try statement. A finally block is used to execute code after a try statement and regardless of the results of the try statement.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      finally {
         // error: missing corresponding 'try'
      }
   }
}

J0126 - 'catch' without 'try'

The compiler detected a catch block but did not find a corresponding try statement. To use a catch block you must have a try statement preceding it. Make sure you have a valid try statement, and then compile again.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      catch {
         // error: missing corresponding 'try'
      }
   }
}

J0127 - 'else' without 'if'

The compiler detected the keyword else, but did not find a corresponding if statement. This error most likely occurs when there are scoping issues with regards to the placement of an else statement. This error can also occur if an else statement's corresponding if statement is missing.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      else // error: no corresponding 'if'
         ;
   }
}

J0128 - Cannot declare an interface to be 'final'

The compiler detected an interface declared with the keyword final. Interfaces cannot be defined as final and thus cannot use the final modifier. Remove the final keyword from the interface's declaration, and then compile again.

The following sample illustrates this error.

final interface Simple {

   // error: 'final' only applies to
   // classes, methods or variables

}

J0129 - Cannot declare a class to be 'identifier' and 'identifier'

The compiler detected a class declared with modifiers that cannot be combined. Make sure that the modifiers you have applied to the class do not conflict with each other, and then make appropriate changes.

The following sample illustrates this error.

public abstract final class Simple {

   // error: 'abstract' and 'final' cannot
   // be used together in a class declaration

}

J0130 - Cannot declare an interface method to be 'native', 'static', 'synchronized' or 'final'

The compiler detected one of the keywords previously shown used in the declaration of an interface method. Because an interface method does not have implementation code, it cannot be declared as native, static, synchronized, or final.

The following sample illustrates this error.

interface Simple {

   public final void method1();
   // error: 'method1' cannot be declared
   // as final in an interface
}

J0131 - Cannot declare a method to be 'identifier' and 'identifier'

The compiler detected the use of two or more incompatible modifiers in the declaration of a method. This error most likely occurs when a method has been defined with two access modifiers such as public and private. Make sure the modifiers for the method do not conflict with each other, and then make appropriate changes.

The following sample illustrates this error.

public class Simple {

   public private void method1() {

      // error: modifiers 'public' and 'private'
      // cannot be combined in a declaration
   }
}

J0132 - Cannot declare a field to be 'identifier' and 'identifier'

The compiler detected the use of two or more incompatible modifiers in the declaration of a variable. This error most likely occurs when a field has been defined with two access modifiers, such as public and private. Make sure the modifiers for the field do not conflict with each other, and then make appropriate changes.

The following sample illustrates this error.

public class Simple {

   public private int i;
   // error: modifiers 'public' and 'private'
   // cannot be combined in a declaration
}

J0133 - Constructors cannot be declared 'native', 'abstract', 'static', 'synchronized', or 'final'

The compiler detected the use of one of the modifiers previously shown in the declaration of a constructor. Make sure that the constructor is not defined with any of the modifiers mentioned in the error message, and then compile again.

The following sample illustrates this error.

public class Simple {

   final Simple() {}
   // error: constructors cannot be 'final'

}

J0134 - Interfaces cannot have constructors

The compiler detected an interface containing a constructor declaration. Because an interface cannot be instantiated, constructors are not allowed to be defined for an interface. If you are defining a method with the same name as the method, make sure that it has appropriate modifiers to differentiate it from a constructor declaration.

The following sample illustrates this error.

interface Simple {

   Simple();
   // error: interfaces cannot
   // declare constructors

}

J0135 - Interface data members cannot be declared 'transient', 'volatile', 'private', or 'protected'

The compiler detected one of the modifiers previously shown used in the declaration of an interface member variable.

The following sample illustrates this error.

interface Simple {

   volatile int i = 1;
   // error: 'volatile'cannot be used.

}

J0136 - Public class 'identifier' should not be defined in 'identifier'

The compiler detected more than one class declared with the modifier public in a source file. Remove the public access modifier from the other classes, and make sure that the class that will be exposed through the class file is declared as public. You can also move classes that need to remain declared as public to their own source file. This error can also occur if the source file does not have the same name as the public class.

The following sample illustrates this error.

public class Simple {

   // do something meaningful

}
public class Errorclass {

   // error: only one class may be defined as
   // 'public' within the same source file

}

J0137 - Not used

This error message is currently not used.

J0138 - Interface cannot have static initializer

The compiler detected a static initializer within an interface. Because an interface does not get instantiated, initializers cannot be defined in an interface. To set the values of interface fields, initialize them at the time of declaration.

The following sample illustrates this error.

interface Simple {

   static {
      // error: static initializers cannot
      // be used in interfaces
   }

}

J0139 - Invalid label

The compiler detected an invalid label. Labels must start with an alphanumeric character. Change the label, and then compile again.

The following sample illustrates this error.

public class Simple {

   public void method1() {

   123:
   // error: label cannot
   // begin with alphanumeric

   return;

   }
}

J0140 - Cannot override static method 'identifier'

The compiler detected an attempt to override a static method from within a subclass. A method that has been declared as static cannot be overridden.

The following sample illustrates this error.

public class Simple {

   static void method1() {}
}
class SimpleSubclass extends Simple {

   void method1() {}
   // error: cannot override
   // static method
}


J0141-J0160

J0141 | J0142 | J0143
J0144 | J0145 | J0146
J0147 | J0148 | J0149
J0150 | J0151 | J0152
J0153 | J0154 | J0155
J0156 | J0157 | J0158
J0159 | J0160 |

J0141 - Argument cannot have type 'void'

The compiler detected a method argument defined as type void. The void type can only be used for method return values to declare a method has no return value. Change the data type of the argument, and then compile again.

The following sample illustrates this error.

public class Simple {

   public void method1(void i) {
      // error: type void can only
      // be used as a return value
   }
}

J0142 - Cannot make static call to abstract method 'identifier'

The compiler detected an attempt to directly call an abstract method. Abstract methods are defined to provide a definition of a method to be implemented by subclasses and thus abstract methods do not have implementation code. Because of this lack of implementation in an abstract method, calling an abstract method using the super keyword is invalid.

The following sample illustrates this error.

abstract class Simple {

   abstract int method1();
}
class SimpleSubclass extends Simple {

   int method1() {

      return super.method1();
      // error: 'method1' must be
      // implemented instead
   }
}

J0143 - Cannot throw exception 'identifier' from static initializer

The compiler detected an attempt to throw an exception from within a static initializer. This error most likely occurs when a throw statement is called or an initialization of a static class instance occurs within a static initializer. To capture exceptions from static class instance initializations in a static initializer, use a try and catch block combination.

The following sample illustrates this error.

public class Simple {

   static {
      ThrowClass TClass = new ThrowClass();
      // error: cannot throw exceptions
      // within static initializers
   }
}
class ThrowClass {

   ThrowClass() throws Exception{}

}

J0144 - Cannot find definition for interface 'identifier'

The compiler could not locate a definition for the named interface. This error most likely occurs when an implemented interface is either missing or misspelled. Verify the location and name of the interface you are implementing, and then compile again.The following sample illustrates this error.

public class Simple implements Bogus {
   // error: the interface 'Bogus' does not exist

}

J0145 - Output directory too long: 'identifier'

The output directory exceeded 228 characters in length. Try shortening the length of the output directory path, and then compile again.

J0146 - Cannot create output directory 'identifier'

The output directory could not be created. This error most likely occurs when you do not have write permission on the specified drive.

J0147 - Cannot access private member 'identifier' in class 'identifier' from 'identifier'

The compiler detected an invalid attempt to access a private member contained within another class. Private class members are only accessible from within the member's class.

The following sample illustrates this error.

class AccessClass {
   private int i = 0;
}
public class Simple {

   public void method1() {

      AccessClass ac = new AccessClass();

      ac.i = 1;
      // error: cannot access 'i'
   }
}

J0148 - Cannot reference instance method 'identifier' before superclass constructor has been called

The compiler detected an attempt to reference an instance method before the superclass constructor was called. This error most likely occurs when a base class method is called from within a subclass's constructor using the super() method. This error can also occur if the subclass calls its own methods from the constructor using the this() method. Because instances of the subclass and base class have not been instantiated at the time the constructor is called, this error occurs. To avoid this situation, use the super statement to call a base class method, and use the this statement to call a subclass method.

The following sample illustrates this error.

abstract class Simple {

   Simple(int i) {}

   int method1() {

      return 0;
   }
}
class SimpleSubclass extends Simple {

   SimpleSubclass() {

      super(method1());
      // error: constructor must be called first
   }
}

J0149 - Not used

This error message is currently not used.

J0150 - Cannot have repeated interface 'identifier'

The compiler detected an interface name being repeated within a class declaration. This error is most likely caused when a class implements a large number of interfaces and an interface has a duplicate entry in the implements list. Check to make sure you do not have a duplicate interface entry, and then compile again.

J0151 - Variable 'identifier' is already defined in this method

The compiler detected two variables with the same name that are defined twice within the same scope of a method. Make sure that a variable has not been defined twice in the same scope, and then compile again.

The following sample illustrates this error.

public class Simple {

   public void method1() {

      int i = 1;
      int i = 0;
      // error: 'i' defined twice within
      // the same scope

   }
}

J0152 - Ambiguous reference to 'identifier' in interfaces 'identifier' and 'identifier'

The compiler detected an ambiguous reference to an identifier. The identifier may have been declared in two or more interfaces, and the compiler could not determine which reference to use. Make sure that you do not have two interfaces with the same field defined.

The following sample illustrates this error.

interface Interface1 {
    final int i = 0;
}
interface Interface2 {
    final int i = 1;
}
public class Simple implements Interface1, Interface2 {
   int method1() {
      return i; //Error, the class implements two
                //interfaces that define 'i' separately.
   }
}

J0153 - Not used

This error message is currently not used.

J0154 - Not used

This error message is currently not used.

J0155 - Not used

This error message is currently not used.

J0156 - Not used

This error message is currently not used.

J0157 - Not used

This error message is currently not used.

J0158 - Class 'identifier' already defined

The compiler detected two or more classes defined with the same name. Make sure that you do not have the class defined more than once in the same source file. This error can also occur if a class is duplicated by an imported class. Rename one of the classes or remove the duplicate instance, and then compile again.

The following sample illustrates this error.

public class Simple {
   // do something meaningful
}
class Simple {
   // error: class 'Simple' already defined
}

J0159 - '@' must be followed by the response file name

The compiler detected the @ character on the jvc command line, but did not detect a valid response file name immediately following it. Supply the response file name, and then compile again.

J0160 - response file 'identifier' could not be opened

The compiler could not open the specified response file. This error most likely occurs when the response file name is misspelled or the file does not exist.


J0161-J0180

J0161 | J0162 | J0163
J0164 | J0165 | J0166
J0167 | J0168 | J0169
J0170 | J0171 | J0172
J0173 | J0174 | J0175
J0176 | J0177 | J0178
J0179 | J0180 |

J0161 - Cannot open source file: 'identifier'

The source file specified in the error message could not be opened. This error most likely occurs when either the filename specified is misspelled or the file does not exist. Check the location of the specified source file, and then compile again.

J0162 - Failed to initialize compiler - maybe you didn't set the class path?

The compiler failed to properly initialize. Check to ensure the CLASSPATH environment variable is set properly, and then compile again.

J0163 - Array 'identifier' missing array index

The compiler detected access to an array type, but the index value was missing. To access an element of an array, you must provide a valid integer index for the array.

The following sample illustrates this error.

public class Simple {

   int j[] = {1, 2, 3};

   void method1() {
      j[] = 0;
      // error: 'j' missing index value
   }
}

J0164 - Ambiguous import of class 'identifier' from more than one package

The compiler detected two or more import statements attempting to import identical class names from different packages. This error most likely occurs when two packages contain duplicate classes and both packages are imported into the same source file. Check the packages imported into the source file for duplicate classes. Remove the duplicate class from one of the packages or remove one of the import statements from the source file.

J0165 - Cannot throw exception 'identifier' from method 'identifier' -- it is not a subclass of any exceptions thrown from overloaded method 'identifier'

The compiler detected an override method attempting to throw more exceptions than the method it overrides. In Java, an override method may not be declared to throw more exceptions than the overridden method. Either change the exception thrown to one that the base class throws, or change the base class declaration to throw the exception type that the subclass needs to throw.

The following sample illustrates this error.

class ExceptionA extends Exception (
   // do something meaningful
}
class ExceptionB extends Exception {
   // do something meaningful
}
class AnotherClass {

   public void method1() throws ExceptionA {
      // do something meaningful
   }
}
public class Simple extends AnotherClass {

   public void method1() throws ExceptionA, ExceptionB {
      // error: cannot throw greater than
      // one exception here
   }
}

J0166 - Cannot access member 'identifier' in class 'identifier' from 'identifier' -- it is in a different package

The compiler detected an invalid attempt to reference a member variable defined within a different package. This error most likely occurs when an attempt is made to access a protected member defined within another package.

J0167 - Cannot override non-static method 'identifier' with static method 'identifier'

The compiler detected an attempt to override a superclass method with a subclass method declared with the modifier static. When a method is overridden in a subclass, the method cannot raise or lower the access level of the method or apply the static modifier. Remove the static modifier from the overridden method declaration, and then compile again.

The following sample illustrates this error.

public class Simple {

   public void method1() {
      // do something meaningful
   }
}
class Simple2 extends Simple {

   static public void method1() {
      // error: overriding superclass 'method1'
      // with a static method is not valid
   }
}

J0168 - The declaration of an abstract method must appear within an abstract class

The compiler detected a method declared with the modifier abstract within a class which was not defined as abstract. This error most likely occurs when a class was intended to be abstract but is missing the abstract modifier in the class declaration. Either change the class so it is declared as abstract or remove the modifier from the methods defined in the class.

The following sample illustrates this error.

public class Simple {

   abstract void method1();
      // error: class must also be abstract
}

J0169 - Cannot access 'identifier' -- only public classes and interfaces in other packages can be accessed

The compiler detected an attempt to access a non-public class or interface contained within another package. Only classes or interfaces defined with the modifier public can be accessed in other packages. Check the access level of the class or interface you are accessing in the other package and ensure that it is public.

J0170 - Cannot load predefined class 'identifier' -- is CLASSPATH set correctly?

The compiler attempted to load a predefined class, but was unable to find the appropriate file. This error most likely occurs when the CLASSPATH variable has not been set correctly. Check to ensure the CLASSPATH is set properly, and then compile again.

J0171 - Not used

This error message is currently not used.

J0172 - Not used

This error message is currently not used.

J0173 - Found class 'identifier' in package 'identifier' rather than package 'identifier'

The compiler found the specified class, but the class was not defined as a member of the correct package. This error most likely occurs when an import statement includes an incorrect package identifier for the class.

J0174 - Not used

This error message is currently not used.

J0175 - Cannot invoke method on 'null' literal

The compiler detected an attempt to call a method from the null keyword. Null is not a class object and provides no methods.

J0176 - Duplicate label 'identifier' nested inside another label with same name

The compiler detected a nested label that was the same as another label. Rename the label to something different then change all break and continue statements that reference the label, and then compile again.

The following sample illustrates this error.

public class Simple{
   void method1(){
      outsideLoop:
      for (int i=0;i&#60;10;i++)
      {
         outsideLoop:  //error: duplicate label
         for (int x=0;x&#60;10;x++)
         {
            break outsideLoop;
         }
         break outsideLoop;
      }
   }
}

J0177 - Not used

This error message is currently not used.

J0178 - Not used

This error message is currently not used.

J0179 - Not used

This error message is currently not used.

J0180 - Not used

This error message is currently not used.


J0181-J0200

J0181 | J0182 | J0183
J0184 | J0185 | J0186
J0187 | J0188 | J0189
J0190 | J0191 | J0192
J0193 | J0194 | J0195
J0196 | J0197 | J0198
J0199 | J0200 |

J0181 - Not used

This error message is currently not used.

J0182 - Not used

This error message is currently not used.

J0183 - Not used

This error message is currently not used.

J0184 - Not used

This error message is currently not used.

J0185 - Not used

This error message is currently not used.

J0186 - Not used

This error message is currently not used.

J0187 - Not used

This error message is currently not used.

J0188 - Not used

This error message is currently not used.

J0189 - 'return' not allowed in a static initializer or instance initializer

A return statement was found in a static initializer. Initializers, like constructors, cannot return a value. Remove the return statement, and then compile again.

The following sample illustrates this error.

public class Simple{

   static int var1;

   static{

   var1 = 0;
   return; // Error, static initializer cannot use the
           // return statement.

   }
}

J0190 - Not used

This error message is currently not used.

J0191 - Expected '.class'

The compiler detected usage of an intrinsic type name in an assignment statement but did not find .class after the name. This error most often occurs when the .class keyword was omitted. Make the appropriate changes to the statement, and then compile again.

The following sample illustrates this error.

public class Simple{
   public static void main (String args[]){
      Class x = int;//error: missing '.class'
   }
}

J0192 - '.class' on intrinsic type requires Java 1.1 compatible class libraries

The compiler has detected usage of .class with an intrinsic data type, but either the Microsoft virtual machine or the Java class libraries are based on Java 1.0. Make sure that your class libraries and Microsoft VM are the Java 1.1 versions, and then compile again.

J0193 - Cannot have an array of type 'void'

An attempt to define an array of type void was found by the compiler. The void data type is for use with methods to declare the method has no return value and thus cannot be used as an array.

J0194 - class or interface cannot be declared 'volatile', 'native', 'transient', or 'synchronized'

The compiler detected that an inner class has been declared with one of the above mentioned modifiers. Inner classes can only use the private, public, protected, and static modifiers.

The following example illustrates this error.

public class Simple{
   //Do something here
   volatile class InnerClass{
      /*error: like outer class, inner classes cannot be defined as
               volatile */
   }
}

J0195 - Cannot declare 'identifier' as 'static' in inner class 'identifier'

The compiler detected an attempt to declare a variable or method as static from within an inner class. Unlike regular class declarations, inner classes do not support static members unless the inner class has been declared static. This error can also occur if an interface was defined within an inner class.

The following example illustrates this error.

public class Simple{

   //Do something meaningful here

   class InnerClass{

   static int var1; /* error: cannot declare static
                              members in inner class */
   }
}

J0196 - Nested class 'identifier' cannot have the same name as any of its enclosing classes

The specified inner class has the same name as one of the classes that it is nested under. Make sure you have not duplicated the name of a class that your inner class is nested in.

The following example illustrates this error.

public class Simple{

   // Do something meaningful here
   class InnerClass{
      //Do something meaningful here
        class Simple{
            //error: inner class has same name as a parent class
        }
   }
}

J0197 - Cannot declare interface in inner class 'identifier'.

The compiler detected an attempt to declare an interface inside an inner class. Inner class definitions do not support interfaces declared within them.

The following example illustrates this error.

public class Simple{
   //Do something meaningful here
   class InnerClass{
   //Do something meaningful here
      interface MyInterface{
         /*error: interfaces cannot be declared
                  inside inner classes */
      }
   }
}

J0198 - An enclosing instance of type 'identifier' is required

The compiler detected that an inner class definition has tried to reference something outside of its scope. Examples of when this can occur are:

  • A static inner class definition referenced one of the parent class's variables. Because the inner class is declared static, it cannot reference any members of the parent class without an instance of the parent class defined.

  • An inner class tried to reference a class that was not its outer class using the this keyword with the classes name preceding it. Since the referenced class it not the inner class's parent class, an instance cannot be implied.

The following example illustrates this error.

//This example illustrates the first error situation
public class Simple{
   int x = 10;
   static class InnerClass{
      public void method1(){
         int y = x; /*error: instance variable needed
                             to reference parent
                             variables. */
      }
   }
}
//This example illustrates the second error situation
class A{
   int x;
}
class B{
   //Do something meaningful here
   class InnerClass{
      void method1(){
         int y = A.this.x;
         /*error: no instance of A defined. Cannot use
           the &#60;classname.this.variable&#62; syntax here.*/
      }
   }
}

J0199 - Call of 'this()' cannot be qualified

The compiler detected that an inner class's constructor attempted to call a constructor from its outer class using the class name and this(). Inner classes cannot call their outer class's constructors.

The following example illustrates this error.

public class Simple{
   int x;
   Simple(int x){
      this.x = x;
   }
   class InnerClass{
      InnerClass(){
         Simple.this(10);
         //error: cannot call outer class constructor
      }
   }
}

J0200 - 'this' must be qualified with a class name

The compiler detected that an attempt was made in an inner class to reference an outer class member using the this keyword with a name other than an outer class's name. Only the name of the outer class can be used from an inner class to reference members of the outer class.

The following example illustrates this error.

public class Simple{
   int x;
   class InnerClass{
      void method1(){
         int j = x.this;
         /*error: only a class name can be used with
         this to reference outer class */
      }
   }
}


J0201-J0220

J0201 | J0202 | J0203
J0204 | J0205 | J0206
J0207 | J0208 | J0209
J0210 | J0211 | J0212
J0213 | J0214 | J0215
J0216 | J0217 | J0218
J0219 | J0220 |

J0201 - 'super' cannot be qualified except as a superclass constructor call

The compiler detected the usage of the super keyword with an instance of the superclass preceding it to access a field or method of the superclass. Using an instance of a superclass along with the keyword super is limited to referencing a superclass constructor when the superclass has inner classes defined.

J0202 - 'super()' cannot be qualified; superclass 'identifier' is not an inner class

The compiler has detected a call to a superclass constructor using an instance of the superclass but the superclass is not an inner class. The usage of an instance of a superclass with the super keyword is only valid when the superclass is an inner class.

The following example illustrates this error.

class Simple{
   //Do something meaningful here
}
class NotSimple extends Simple
{
   NotSimple(Simple smp){
      smp.super();
      /*error: cannot call 'super' with instance when
        superclass does not contain inner classes*/
   }
}

J0203 - Cannot access protected member 'identifier' in class 'identifier' from class 'identifier'

The compiler has detected an attempt to access a protected member from a class in a different package. Classes that reside in separate packages cannot refer to protected members unless you are subclassing a class in the other package

J0204 - Cannot access protected member 'identifier' in class 'identifier' through a qualifier of type 'identifier'

The compiler detected that a class in one package that is extending a class in another package, attempted to access a protected member of the base class using an instance of the base class. This error most likely occurs when a class attempts to access members of its base class through an instance other than or super.

J0205 - Cannot use non-final local variable 'identifier' from a different method

The compiler detected that a local variable, which was not declared as final, was referenced in a method. This error can occur if an inner class is defined in a method declaration and the inner class attempts to reference a parameter or local variable passed to the method.

The following example illustrates this error.

public class Simple{
   void method1(int var1){
      class InnerClass{
         boolean getVar1(){
           return(var1 == 1);
           /*error cannot reference local variable of
                   method from within inner class. */
         }
      }
   }
}

J0206 - Cannot assign a second value to blank final variable 'identifier'

The compiler detected an attempt to assign a value to a final variable more than once. This error most likely occurs when a blank final variable is initialized more than once in constructor or initializer. Check for duplicate initializations of the final variable mentioned in the error message, and then compile again.

J0207 - Cannot assign blank final variable 'identifier' in a loop

The compiler detected that a final variable was assigned a value from within the scope of a program control loop. A final variable can only be assigned a value once and thus cannot be initialized within a loop. Move the initialization of the final variable specified in the error message outside of the loop and ensure that it is initialized only once.

The following example illustrates this error.

public class Simple{
   final int x;

   public Simple(){
      for (int z=0;z&#60;10;z++){
         x = z; /*error: cannot assign final variable
                  in loop */
      }
   }
}

J0208 - Constructor or instance initializer must assign a value to blank final variable 'identifier'

The compiler detected that a final variable was declared but never assigned a value in either an initializer or constructor. For a variable to be properly declared final, it must be assigned a value.

J0209 - Expected '='

The compiler detected that an "=" was missing from a comment tag (for example @com, @security, @dll) attribute. This error most often occurs when an equal sign is missing from an attribute in a comment tag declaration. This error could also occur if another symbol or character obscures the "=" sign from being evaluated by the compiler. Check to make sure all comment tag attributes have proper "=" signs applied, and then compile again.

The following example illustrates this error.

/**@com.interface(iid 31415926-5358-9793-2384-612345678901)*/
//error: missing equal sign in 'iid' parameter
interface Itest{
   //Do something meaningful here
}

J0210 - Expected '.'

The compiler detected that the specified comment tag's declaration (for example @com) is missing a period (.) after the comment tag. This error can also occur if another symbol or character obscures the period symbol from being evaluated by the compiler. Check to make sure your comment tag declaration contains a period after the comment tag, and then compile again.

The following example illustrates this error.

/**@com class*/
//error: missing '.' from @com statement
public class Simple{
   //Do something meaningful here
}

J0211 - Not used

This error message is currently not used.

J0212 - Not used

This error message is currently not used.

J0213 - Not used

This error message is currently not used.

J0214 - Invalid GUID specified

The compiler detected that an @com attribute that uses a GUID was incorrect. This can be caused by a syntax error in entering the GUID. Check the syntax for the GUID, and then compile again.

J0215 - Syntax error in @com declaration

A syntax error was found in the specified @com declaration. This is most often caused by incorrectly typing the declaration. Check the syntax of the @com declaration, and then compile again.

J0216 - @com attribute 'identifier' on 'identifier' is illegal in this context

The compiler has detected that a value assigned to an attribute within an @com declaration is illegal. This error most often occurs when an attribute is specified but usage of the attribute requires that other specific attributes be specified. This error can also occur if an attribute is specified in the wrong location within an @com declaration. The following list illustrates some examples of when this can occur.

  • The @com.parameter attribute iid can only be specified if the attribute type has a value of either "OBJECT" or "DISPATCH".

  • The @com.parameter attribute size can only be specified if the type attribute is specified as either "ARRAY", "STRUCT", "SYSFIXEDSTRING", or "FIXEDARRAY".

  • The @com.method attribute name2 can only be specified if the method is declared within an @com.interface declaration that has its type attribute equal to either dual or dispatch.

  • The @com.parameter attribute name cannot be specified as the last attribute in an @com.parameter declaration.

J0217 - @com attribute 'identifier' was not specified for 'identifier' but is required in this context

The compiler has detected an attribute for the @com declaration shown in the error is missing, and is required for this type of declaration. Each type of @com declaration has attributes that are required. Check the documentation on @com for more details on what attributes are required for the @com declaration that is listed in the error message.

The following example illustrates this error.

/**@com.class() */
//error: must specify iid for @com.class
public class Simple{
   //Do something here
}

J0218 - @com attribute 'identifier' on 'identifier' has an invalid value

The compiler has detected that the value specified in the error message is either not the correct type for the attribute specified in the error or is outside the valid ranges for the error. Check the value assigned to the specified attribute, and then compile again.

J0219 - An @com attribute cannot be placed on member 'identifier' unless the containing class also has an @com attribute

The compiler has detected that an @com declaration was placed on a member of a class or interface but the class or interface was not declared with an @com declaration. Check to make sure the class or interface that contains the method specified in the error has a valid @com declaration defined.

The following example illustrates this error.

interface Simple{
   /**@com.method(dispid=777) */
   public void method1();
   /*error: interface does not have an @com comment tag
            assigned*/
}

J0220 - An @com attribute cannot be placed on static member 'identifier'

The compiler detected that an @com declaration was placed on a static member of a class. Static members cannot be exposed through COM. Remove the static keyword from the method or field, and then compile again.


J0221-J0242

J0221 | J0222 | J0223
J0224 | J0225 | J0226
J0227 | J0228 | J0229
J0230 | J0231 | J0232
J0233 | J0234 | J0235
J0236 | J0237 | J0238
J0239 | J0240 | J0241
J0242 |  |

J0221 - The @com attribute on member 'identifier' cannot be used in this kind of class or interface

The compiler has detected that an @com declaration was placed on a member of a class or method but because of the type of @com declaration used with the class or interface, it is not allowed. This error can occur in the following situations:

  • Using an @com.structmap declaration on a member of a class or interface that has the @com.class or @com.interface declaration applied.

  • Using an @com.method declaration on a member of a class that has the @com.struct declaration applied.

The following example illustrates this error.

/**@com.struct()*/
class Simple{
   /**@com.method(dispid=777)*/
   public native void method1();
   /*error: cannot use @com.method inside of
            @com.struct*/
}

J0222 - @com attribute cannot be placed on method 'identifier'-- it must be declared 'native' or be in an interface

The compiler has detected that a method was specified with an @com.method or @com.parameters declaration but the method was not declared with the native modifier or declared in an interface definition. For methods to be exposed through a COM interface, they must be either declared native from within a class declaration or be declared in an interface declaration.

J0223 - The @com.parameters declaration on member 'identifier' has the wrong number of parameters

The compiler has detected that the @com.parameters declaration, specified in the error message, has a different number of parameters than the method it is exposing through COM. Make sure that both the method's declaration and the @com.parameters declaration have the correct number of parameters, and then compile again.

The following example illustrates this error.

/**@com.interface(iid=31415926-5358-9793-2384-612345678910)*/
interface Itest{
   /** @com.method(dispid=306)
       @com.parameters([type=BOOLEAN] var1, var2, var3)
   */
   public void method1(boolean var1, int var2);
   /*error: extra parameter added to com.parameters
            declaration */
}

J0224 - 'return' must be the last item in an @com.parameters declaration

When declaring @com.parameters for a method, the return parameter must be the last parameter in the list. The compiler has detected the return parameter in a different position within the parameter list. Check the location of the return parameter in the @com.paramters declaration specified in the error message, make appropriate changes, and then compile again.

J0225 - An @com.'identifier' declaration is illegal for this kind of item

The compiler detected that an @com declaration was defined for the wrong type of item. This error most likely occurs as a result of a change to your code but not to the syntax or placement of an @com declaration. Make sure the proper @com declaration is used on the specified item in your code.

The following example illustrates this error.

/**@com.interface(iid=31415926-5358-9793-2384-612345678901,dual)*/
interface Itest{
   /**@com.struct()*/
   public int method1();
   //error: wrong type of @com attribute applied
}

J0226 - The @com declared type of 'identifier' is illegal for a dispatch or a dual interface

The compiler detected that an @com interface declaration, declared as either a dual or dispatch interface, has a member that contains an @com.parameters declaration with an incorrect type. Certain @com.parameters types are not allowed when the interface they are defined in is declared as either dual or dispatch interface. The following list shows which values are invalid for type.

  • FIXEDARRAY

  • SYSFIXEDSTRING

  • I8

  • U8

  • STRUCT

  • CUSTOM, CUSTOMBYREF/CUSTOMBYVAL

  • PTR (except PTR to VARIANT)

  • Arrays of any of the previously listed values.

J0227 - It is impossible for an expression of type 'identifier' to be an instance of 'identifier'

The compiler has detected that a comparison of two classes using the instanceof operator could never be instances of each other. To use the instanceof operator correctly, you must be comparing classes that have some common class lineage. Either change the expression containing the instanceof operator so that it uses a related class and instance for its comparison, or remove the expression, and then compile again.

The following example illustrates this error.

class Simple1{
   //do something meaningful here
}
class Simple2{
   //do something meaningful here
}
class CompClasses{
   Simple1 x = new Simple1();
   public static void main(String args[]){

   if(smp.x instanceof Simple2){
      /*error: nonrelated classes cannot be instances of each other*/
   }
}

J0228 - Syntax error in @dll declaration

The compiler has detected a syntax error in an @dll statement. This error most likely occurs when an @dll statement has been mistyped. Check the statement for syntactical errors, and then compile again.

J0229 - Expected string constant

The compiler detected a parameter of a comment tag's declaration (for example @com, @dll, or @security) that was expecting a string constant, was either missing it or it was incorrectly entered. This error most often occurs when matching quotes are missing around a value passed to an attribute. Check your comment tag declaration's attributes, and then compile again.

The following example illustrates this error.

/**@com.interface(iid=31415926-5358-9793-2384-612345678901,dual)*/
interface ITest{
   /**@com.method(name=method1);*/
   //error: Missing quotes around 'method1'
   public void method1();
}

J0230 - Class or interface name 'identifier' conflicts with import 'identifier'

The specified class or interface conflicts with a class that has been imported. This could be caused by declaring a class or interface that is already declared in the Java API and you are importing that API class or interface into your source file.

J0231 - Expression statement must be assignment, method call, increment, decrement, or 'new'

The compiler has detected an invalid expression statement. An expression statement is a statement that can reside on its own line of source code. The following are some examples of valid expression statements.

Method calls

m_cars.changeColor();

Assignment statements

int x = y + z;

Increment statement

j++;

m_tempVar1 += 3;

Use of the new keyword

new Simple();

The following are examples of invalid expression statements.

1+2;

Error: No assignment statement

j+k-method1();

A method call but not a valid assignment statement

var1 == var2;

Comparison statements should be contained in flow control statements

J0232 - Expected '{' or ';'

The compiler has detected an error with a method declaration in a class or interface. This error most likely occurs if an interface's method declaration is missing a semicolon at the end of the declaration or a class's declaration is missing its opening brace '{'. Check the specified class or interface method declaration and check for a missing semicolon or opening brace, and then compile again.

J0233 - Catch clause is unreachable; exception 'identifier' is never thrown in the corresponding try block

The compiler detected that the specified catch clause will never be executed because the corresponding try statement never throws the catch statement's exception type. Catch statements are required to catch exceptions or derivations of exceptions that the try statement can throw. This error can be avoided by changing the catch statement so it does not catch a specific exception type but catches the base Exception class. Change the exception class so that your catch statement will trap it, and then compile again.

J0234 - 'identifier' is not a field in class 'identifier'

The compiler detected a field reference but the field does not exist in the specified class. This error most likely occurs when the field reference is mistyped or the field reference was meant to reference a field in a different class. Make sure that the field exists in the specified class and that your reference to the field is syntactically correct, and then compile again.

J0235 - 'identifier' is not a method in class 'identifier'

The compiler detected a method call but the method does not exist in the specified class. This error most likely occurs when the method call is called incorrectly or the method call was meant to reference a method in a different class. Make sure that the method exists in the specified class and that your method call is syntactically correct.

J0236 - 'identifier' is not a nested class or interface in class 'identifier'

The compiler has detected a reference to a nested class or interface but the nested class or interface does not exist in the specified class. This error most likely occurs because of a syntactical error in referencing a nested class or interface. Check the reference to the inner class for syntax errors and make sure that the class or interface exists inside the specified class, and then compile again.

The following example illustrates this error.

class NotSimple{
}
public class Simple{
   void method1(){
      NotSimple nt = new NotSimple();
      Object o = nt.new InnerClass();
      //error: 'InnerClass' is not an inner class of 'NotSimple'
   }
}

J0237 - 'identifier' is not a field or nested class in class 'identifier'

The compiler has detected a reference to a nested class or field but the nested class or field does not exist in the specified class. This error most likely occurs because of a syntactical error in referencing a nested class or field. This error can also occur if a reference to a field in an inner class is made but the field does not exist within the inner class definition. Check to make sure the inner class or field exists, and then compile again.

J0238 - Cannot throw exception 'identifier' from field initializer

The compiler has detected that an exception was thrown within a field initializer. This error most likely occurs when an exception can be thrown from a constructor of a class, and an instance of that class is declared and instantiated as a member of another class. To resolve this problem, have the class object that throws the exception instantiated inside a constructor so it can use a try and catch combination to trap any exceptions from the other class's constructor call.

The following example illustrates this error.

public class Simple{
   public int i;
   public Simple(boolean var1) throws Exception{
      if (var1 = true)
         i = 0;
      else
         throw new Exception();
   }
}
//This is the incorrect way to instantiate this class
class Simple2{
   Simple smp = new Simple(true);
   /* error: cannot call constructor that throws exception in field
            initializer*/
}

J0239 - Static initializer must assign a value to blank final variable 'identifier'

The compiler detected that a static final variable was not initialized to a value using a static or field initializer. To declare a variable as static and final, you must use a static or field initializer to set an initial value. This error can also occur if a field is declared as static and final and assigned a value in a constructor.

The following example illustrates this error.

public class Simple{
   static final int MAX_CONTROL;
} //error: static final variables must have value assigned

J0240 - Syntax error in @security declaration

The compiler detected a syntax error in the specified @security comment tag. This error most likely occurs when the comment tag is missing a closing parenthesis or the tag's attributes are incorrect. Check the syntax of the specified @security comment tag declaration, and then compile again.

The following example illustrates this error.

/**@security()*/   //error: invalid @security syntax
public class Simple{
   //Class members defined here
}

J0241 - '@security' can only be specified on a class or interface

The compiler detected that the @security comment tag was applied to something other than a class or interface declaration. @security comment tags are used to define the security settings for a class or interface definition and cannot be applied to methods or fields of a class or interface.

J0242 - Cannot make static call to nonstatic method 'identifier'

The compiler has detected that a method was called by using the static method call syntax of '<classname>'.'<method>', but the method is not a static method. Change the method call to use an instance of the class that contains the method instead of the class name itself, and then compile again.


J0243-J0262

 Microsoft SDK for Java

J0243-J0263

J0243 | J0244 | J0245
J0246 | J0247 | J0248
J0249 | J0250 | J0251
J0252 | J0253 | J0254
J0255 | J0256 | J0257
J0258 | J0259 | J0260
J0261 | J0262 | J0263

J0243 - 'identifier' is obsolete; use 'identifier' instead

The compiler detected a comment tag (for example @com, @dll, @security) that is using a format that is now considered obsolete. To avoid this error, change the line of code that the error occurred on to the newer format specified in the error message and compile again.

The following example illustrates this error.

public class Simple{
   /**@dllimport("kernel32", ansi)*/
   /* error: 'dllimport' is no longer a supported format for
      @dll.import declarations */
   public static native boolean GetComputerName(StringBuffer s, int[]cb);
}

J0244 - @conditional allowed only on void-returning methods

The compiler detected an @conditional comment tag for a method that has a non-void return value. The @conditional comment tag can only be used for methods without a return value. Change the method declaration to return void or remove the @conditional comment tag and compile again.

The following example illustrates this error.

public class Simple{
   /**@conditional(DEBUG)*/
   public int method1(int x){
      //error: conditional methods cannot return a value
   return x * 2;
   }
}

J0245 - Warning treated as error

The compiler was run using the /wx switch, and a warning was found during compilation. The /wx compiler switch treats all warnings as errors. In order for the /wx compiler switch to display this error, the warning level switch (/w{0-4}) must be set high enough to display the warning. Determine the cause of the warning and compile again. You can also remove this switch from your compiler options and compile again.

J0246 - Invalid token on a # directive

The compiler detected an invalid token for a conditional compilation expression. This error usually occurs when a token is mistyped or the token used is not a legal token. Ensure that the conditional compilation directive specified in the error is correct and compile again.

The following example illustrates this error.

public class Simple{
   public void method1(){
      #iff DEBUG //error: 'iff' is not a valid token
        System.out.println("Do something meaningful here");
      #endif
   }
}

J0247 - #elif without matching #if

The compiler detected a #elif conditional compilation directive, but did not detect a matching #if directive. Ensure that you have a valid #if conditional compilation directive to match your #elif directive and compile again.

The following example illustrates this error.

public class Simple{
   public void method1(){
      //error: need to have '#if' before '#elif'
      #elif DEBUG
         System.out.println("Do something meaningful here");
      #endif
   }
}

J0248 - #endif without matching #if

The compiler detected a #endif conditional compilation directive, but did not detect a matching #if directive. This error usually occurs because an extra #endif directive was supplied. This error can also occur when a #if conditional compilation directive was deleted or commented out but the matching #endif directive was not deleted. Ensure that you have matching directives and compile again.

The following example illustrates this error.

public class Simple{
   public void method1(){
      //#if SIMPLE
      //do something here
      #if DEBUG
          //do something here
          #if WIN95
             //do something here
          #endif
      #endif
      #endif //error: extra '#endif' directive not permitted
   }
}

J0249 - #else without matching #if

The compiler detected a #else conditional compilation directive but, did not detect a matching #if directive. This error usually occurs because an extra #else directive was supplied. This error can also occur when a #if conditional compilation directive was deleted or commented out but a #else directive was not deleted. Ensure that you have matching directives and compile again.

The following example illustrates this error.

public class Simple{
   public void method1(){
      //do something here
      #else /*error: this '#else' directive has no matching '#if'
              directive */
   }
}

J0250 - Already had an #else

The compiler detected a duplicate #else conditional compilation directive in a #if directive block. A #if directive can only have one #else directive. Ensure that you have only one #else conditional compilation directive for the #if directive in which the error occurred and compile again.

The following example illustrates this error.

public class Simple{
   #if A
     #if B
     void method1{
       //do something here
     }
   #else
     void method2{
       //do something here
   #else  //error: extra '#else' directive supplied
   #endif
}

J0251 - Unexpected EOF while looking for #endif

The compiler detected a #if conditional compilation directive but did not find a matching #endif directive, and the symbol used by the #if directive was not defined. This error usually occurs when a #if conditional compilation directive is used but a matching #endif directive was not defined to close the conditional compilation block. Ensure that you have a matching #endif directive for the #if directive specified in the error and compile again.

The following example illustrates this error.

public class Simple{
   void method1(){
      #if DEBUG //debug has not been defined
         System.out.println("Do something here");
   //error: '#endif' not specified for the '#if' directive
   }
}

J0252 - #if nested too deeply

The compiler detected nested #if conditional compilation blocks that were nested too deeply. Nesting of #if conditional compilation blocks is limited to 64 levels. Ensure that your nesting of #if blocks is within the limit and compile again.

J0253 - Cannot have #define/#undef after source

The compiler detected a #define or #undef conditional compilation directive after other Java source code. The #define and #undef directives must be placed before other Java source code (except for other conditional compilation directives and source comments). Move the #define or #undef directive indicated by the error to the front of all Java source code in the file and compile again.

The following example illustrates this error.

package boxes;

#define DEBUG
//error: '#define' must occur before the 'package' statement

public class Simple{
}

J0254 - Cannot change predefined symbol

The compiler detected an attempt to use the #define or #undef directive on a symbol already defined in Java. This error occurs when a symbol such as true or false, which are already defined for conditional compilation, is redefined using the #define or #undef conditional compilation directives. Remove or change the #define or #undef directives specified in the error and compile again.

The following example illustrates this error.

#undef false //error: cannot undefine the 'false' symbol
#define true //error: cannot define the predefined 'true' symbol

public class Simple{
   //do something here
}

J0255 - Expected #endif

The compiler detected a #if conditional compilation directive but did not find a matching #endif directive; however, the symbol used by the #if directive was defined. This error usually occurs when a #if conditional compilation directive is used but a matching #endif directive in not defined to close the conditional compilation block, and the code is intended to be compiled. Ensure that you have a matching #endif directive for the #if directive specified in the error and compile again.

The following example illustrates this error.

#define DEBUG

public class Simple{
   void method1(){
      #if DEBUG
         System.out.println("Do something here");
   //error: '#endif' has not been specified for the '#if' directive
   }
}

J0256 - Expected 'class', 'interface', or 'delegate'

The compiler expected to find the class, interface, or delegate keywords used within the corresponding declaration. This error usually occurs when the keywords are accidentally omitted from a class, interface, or delegate declaration. Another possible cause of this error is unbalanced scoping braces.

Note This error will only occur if the Microsoft Extensions are enabled in your project. Otherwise, compiler error J0020 will be displayed.

The following example illustrates this error.

public Simple{ //error: missing the 'class' keyword
   //Do something here
}

This example illustrates this error caused by unbalanced scoping braces.

public class Simple {

   // do something meaningful

}}   // error: additional '}' is not permitted

J0257 - Delegate cannot be initialized with static method 'identifier'

The compiler detected a delegate instantiation but the method reference, passed as a parameter, was a static method. When instantiating a delegate, you must pass a non-static method as a parameter. Ensure that the method you are defining the delegate to use is a non-static method and compile again.

The following example illustrates this error.

delegate int MyDelegate (int var1, String var2)throws Exception;

public class Simple{

   public static int method1(int var1, String var2) throws Exception{
      //do something here
      return var1;
   }

   public static void main (String args[]){
      Simple smp = new Simple();
      MyDelegate md = new MyDelegate(smp.method1);
      /*error: the method passed as a parameter to the delegate is a
               static method */
   }
}

J0258 - Cannot declare delegate in inner class 'identifier'

The compiler detected an attempt to declare a delegate inside an inner class. Inner class definitions do not support delegates declared within them. Remove the delegate declaration from within the inner class declaration and compile again.

The following example illustrates this error.

public class Simple{
   //Do something meaningful here
   class InnerClass{
   //Do something meaninful here
      delegate int MyDelegate (int var1, String var2);
         /*error: delegates cannot be declared
                  inside inner classes */
   }
}

J0259 - Exception 'identifier' from method 'identifier' is not a subclass of any exceptions declared thrown by delegate 'identifier'

The compiler detected a delegate that was initialized with a method that throws an exception that is incompatible with the delegate's declared set of exceptions. Each exception thrown by the method must be the same class or a subclass of an exception that the delegate throws. Change the set of exceptions thrown by either the delegate or the method and compile again.

The following example illustrates this error.

delegate void SimpleDelegate(String var1) throws Exception;

public class Simple{
   public void method1(String var1) throws Throwable{
      //do something here
   }
   public static void main (String args[]){

      Simple smp = new Simple();
      SimpleDelegate del1 = new SimpleDelegate(smp.method1);
      /* error: the method reference argument throws an exception that is
             not the same or a subclass of the exception declared by the
             delegate */
   }
}

J0260 - Cannot declare an interface method to be 'protected' or 'private'

The compiler detected an interface with a method declared as protected or private. Interface methods must be declared as either public or with no access modifier (default). Change the interface method declaration specified in the error so that it is not declared protected or private and compile again.

The following example illustrates this error.

interface ISimple{
   public void method1(); //this is OK!
   void method2(); //this is OK! Declared as "default" access
   protected void method3(); /*error: cannot declare interface method as
                                      protected */
   private void method4(); /*error: cannot declare interface method as
                                    private */
}

J0261 - An explicit enclosing instance of class 'identifier' is needed to instantiate inner class 'identifier'

The compiler detected an attempt to create an instance of an inner class without specifying an instance of its enclosing class. This error usually occurs when an attempt is made, within a static method, to instantiate an inner class as you would an outer class. To create an instance of an inner class, you must use an existing instance of its outer class. Create an instance of the enclosing class and use it to instantiate the inner class and compile again.

The following example illustrates this error.

public class Simple{
   class InnerClass{
      //do something here
   }

   public static void main(String args[]){
      InnerClass inc = new InnerClass();
      /*error: an instance of the outer class is required to instantiate
               its inner class */
   }
}

The following example illustrates how to create an instance of an inner class using an instance of its outer class.

public class Simple{
   class InnerClass{
      //Do something here
   }
   public static void main(String args[]){
      Simple smp = new Simple();
      /*use the instance of 'Simple' to create an instance of its inner
        class*/
      InnerClass inc = smp.new InnerClass();
   }
}

J0262 - An explicit enclosing instance of class 'identifier' is needed to call constructor of superclass 'identifier'

The compiler detected an attempt by a derived class to call its superclass constructor without an instance of the superclass. This error usually occurs because the superclass is also an inner class. When a derived class is instantiated, an instance of its superclass is also created (and the superclass constructor is invoked). In order to create an instance of an inner class you must instantiate the inner class using an instance of its outer class.

The following example illustrates this error.

class OuterClass{
   class InnerClass{
   //do something here
   }
}

public class Simple extends OuterClass.InnerClass{
   //do something here
}
/*error: superclass 'InnerClass' cannot be instantiated without its outer class 'OuterClass' being instantiated */

The following example illustrates how to instantiate a class that is derived from an inner class.

class OuterClass{
   class InnerClass{
   //do something here
   }
}

public class Simple extends OuterClass.InnerClass{
   Simple(){
      /*this line creates an instance of the outer class and calls
        the superclass (the inner class) constructor */
      new OuterClass().super();
   }
}

J0263 – Not used

This error message is currently not used.


J0264-J0500

J0264 | J0265 | J0266
J0267 | J0268 | J0269
J0270 | J0271 | J0272
J0273 | J0274 | J0275
J0276-J0499 | J0500 |

J0264 - Array cannot have a dimension

The compiler detected an attempt to initialize an array dimension incorrectly. This error usually occurs when an array dimension size is specified before the instance is created. This error can also occur when an array is given a dimension in the proper place but an initialization list is also provided to set the values of the array (you cannot specify an array size for the dimension when using an initialization list). Correct the initialization of the array specified by the error and compile again.

The following example illustrates this error.

public class Simple{
   public void method1(){
      String[3] var1; /* error: cannot specify array size here since
                         array is not instantiated yet */
      String[] var2 = new String[3]; //this is OK!

      boolean var3 = new boolean[3]{true,false,true};
      /*error: cannot specify an array size for the dimension when using
               an initialization list */
      boolean var4 = new boolean[]{true, false,true}; //this is OK!
   }
}

J0265 - @dll attribute cannot be placed on method 'identifier' — it must be declared 'native'

The compiler detected an @dll comment tag placed on a method that is not declared with the native modifier. This error usually occurs if an @dll comment tag is defined but the method it was applied to was removed or commented out, and other methods in the class can have the comment tag applied to them. Ensure that the method declared with the @dll comment tag is declared as native or remove the @dll comment tag and compile again.

The following example illustrates this error.

public class Simple{
   /** @dll.import("USER32") */
   //private native static int MessageBox(int hwndOwner, String text,
                                          String title, int fuStyle);

   /*error: the @dll comment tag cannot applied to 'method1' which is a
            non-native method instead of the intended native method*/
   public void method1(){
     //do something here
   }
}

J0266 - Compilation canceled by user

The user canceled compilation. This error simply informs the user that the request to cancel compilation was successful.

J0267 - A delegate cannot be 'identifier'

The compiler detected an attempt to declare a delegate with an invalid modifier. Only the public and final modifiers can be applied to a delegate declared outside of a class. A delegate declared within a class can have the public, final, protected, and private modifiers applied. Ensure that your delegate declaration is not using an invalid modifier and compile again.

Note Although you can use the final modifier in a delegate declaration, it is not needed as delegates are implicitly final.

The following example illustrates this error.

private delegate void Simple(int var1, int var2);
//error: cannot declare a delegate as 'private'

J0268 - A delegate cannot be 'identifier' and 'identifier'

The compiler detected a delegate declaration, within a class, attempted to use a combination of access modifiers that are not allowed. This error usually occurs when a delegate is declared with two access modifiers applied. Remove the additional access modifier applied to the specified delegate declaration and compile again.

The following example illustrates this error.

public class Simple{
   public private delegate void SimpleDelegate();
   //error: cannot declare a delegate to be 'public' and 'private'
}

J0269 - Ambiguous name: inherited 'identifier' and outer scope 'identifier' — an explicit 'this' qualifier is required

The compiler detected reference to a variable or method from within an inner class that is defined in both its outer class and its superclass. The compiler cannot determine which variable or method is to be used. You can reference the outer class variable or method by using class.this.name, where class is the name of the outer class whose variable or method you wish to reference and name is the variable or method name. To reference the superclass variable or method you can use the this super keyword before the reference.

The following example illustrates this error.

class NotSimple{
   int var1 = 20;
}

public class Simple{
   int var1 = 10;
   class InnerClass extends NotSimple{
      int var2 = var1;
      //error: cannot determine which 'var1' to use
   }
}

The following example illustrates how to resolve name ambiguity between the outer class and superclass variables.

class NotSimple{
   int var1 = 20;
}

public class Simple{
   int var1 = 10;
   class InnerClass extends NotSimple{
      int var2 = Simple.this.var1;
      //this is OK and references the outer class variable
      int var3 = super.var1;
      //this is OK and references the superclass variable
   }
}

J0270

The compiler detected an ambiguous reference to a field. This error usually occurs when a class's superclass and an interface the class implements have the same field declared. The compiler cannot determine which instance of the field to use. Ensure that you do not have a superclass and implemented interface that have the same field defined and compile again.

The following example illustrates this error.

public class Simple extends SuperClass implements SuperInterface{
   public static void main (String args[]){
      float x = var1; /*error: cannot determine which instance of 'var1'
                               to use */
   }
}

class SuperClass{
   float var1;
}

interface SuperInterface{
   float var1=6.0f;
}

J0271 - Expected 'delegate'

The compiler detected the multicast modifier but did not detect the delegate keyword. The multicast modifier can only be used in conjunction with the delegate keyword to create multicast delegates. Ensure that you have the delegate keyword in the declaration specified by the error message and compile again.

The following example illustrates this error.

public multicast void SimpleDelegate(String x, int y);
//error: the 'delegate' keyword is missing after the 'multicast' modifier
public class Simple{
   //Do something here
}

J0272 - A multicast delegate cannot return a value

The compiler detected a return type other than void for a multicast delegate declaration. Although delegates can return a value other than void, multicast delegates cannot return a value other than void. Ensure that the multicast delegate declaration specified by the error returns void and compile again.

The following example illustrates this error.

multicast delegate int SimpleDelegate(int x, int y);
//error: cannot declare multicast delegate with non-void return type
public class Simple{
   public int method1(int x, int y){
      //Do something here
   }

   public static void main (String args[]){
      Simple smp = new Simple;
      SimpleDelegate sd = new SimpleDelegate(smp.method1);
   }
}

J0273

The compiler detected an attempt to cast the return value of a method call to void. Casting a method call to void is not allowed in the Java language. Remove the void cast for the method call specified by the error and compile again.

The following examples illustrates this error.

public class Simple{
   public void method1(){
      //Do something meaningful here
   }
   public static void main (String args[]){
      Simple smp = new Simple();
      (void) method1();
      //error: cannot cast method's return value to 'void'.
   }
}

J0274 - Expected 'identifier' within single comment preceding class 'identifier'

The compiler detected that the class, specified in the error message, was declared with either the @com.typeinfo or @com.transaction comment tag and a corresponding @com.register comment tag was not found within the same comment. This error can occur when an @com.register comment tag is declared but is within a separate comment. Ensure that an @com.register comment tag is defined within the same comment as the @com.typeinfo or @com.transaction comment tags defined for the class specified in the error message and compile again.

The following example illustrates this error.

/** @com.register ( clsid=AE032C46-E6A0-11d0-8C83-00C04FC2AAE7) */
/** @com.typeinfo(attrid=31415926-5358-9793-2384-612345678901,
value="Help") */
public class Simple{
   /error: the '@com.register' tag is ignored since it is in a separate
           comment */
}

/** @com.register ( clsid=AE032C46-E6A0-11d0-8C83-00C04FC2AAE7)
    @com.typeinfo(attrid=31415926-5358-9793-2384-612345678901,
value="Help")*/
public class Simple2{
   //This comment is OK. It combines both tags in a single comment.
}

J0275 - Class or interface name 'identifier' conflicts with package 'identifier'

The specified class or interface name conflicts with a package name. This error can be caused by declaring a class or interface within a package with the same name as a subpackage. Rename either the subpackage or the class or interface that is causing the ambiguity and compile again.

The following example illustrates this error.

//located in a file called Plastic.java
package Boxes.Dishes;
public class Plastic{
   //do something here
}

//located in a file called Dishes.java
package Boxes;
public class Dishes{
   //error: the name 'Dishes' is also the name of the subpackage
}

J0276 to J0499 – Not used

These error messages are currently not used.

J0500 - #error 'user defined error'

This error message is generated when there is a #error conditional compilation directive in the program.

The following example illustrates this error.

#define DEBUG
public class Simple{
   public void method1(){
      #if DEBUG
         #error You should not be running in debug mode here!
         //error: displayed when 'DEBUG' is defined
      #endif
   }
}


J5001-J5016

 Microsoft SDK for Java

J5001-J5020

J5001 | J5002 | J5003
J5004 | J5005 | J5006
J5007 | J5008 | J5009
J5010 | J5011 | J5012
J5013 | J5014 | J5015
J5016 | J5017 | J5018
J5019 | J5020 |

J5001 - Local variable 'identifier' is initialized but never used

The compiler detected an initialized variable that was never referenced in any class code. This message occurs at warning level 3 or greater.

The following sample illustrates this warning.

public class Simple {

   public int method1() {

      int i = 1;
      return 1;
      // warning: 'i' is never used
   }
}

J5002 - Compiler option 'identifier' is not supported

The compiler that detected an unsupported command line option was specified. Check your compiler switch settings, and then try compiling again.

J5003 - Ignoring unknown compiler option 'identifier'

The compiler detected an unknown option specified on the jvc command line. This warning most likely occurs when a typographical error exists. For example, specifying /W4 on the command line will cause this warning because the warning level option must use a lowercase 'w'.

J5004 - Missing argument for compiler option 'identifier'

The compiler detected a valid command line option, but the required argument was not specified. Check your compiler switch settings and try compiling again.

J5005 - Package 'identifier' was already implicitly imported

The compiler detected an import statement for a package that was already implicitly imported, such as java.lang. This message occurs at warning level 1 or greater.

J5006 - 'private protected' not supported, using 'protected'

The compiler detected use of the modifier combination private protected. This combination is now obsolete and has been replaced by protected. This message occurs at warning level 1 or greater.

J5007 - Not used

This error message is currently not used.

J5008 - Not used

This error message is currently not used.

J5009 - Not used

This error message is currently not used.

J5010 - Not used

This error message is currently not used.

J5011 - Not used

This error message is currently not used.

J5012 - Not used

This error message is currently not used.

J5013 - Not used

This error message is currently not used.

J5014 - 'identifier' has been deprecated by the author of 'identifier'

The method or class referenced has been marked as deprecated. Deprecated methods or classes are marked by the creator of the source code as outdated and subject to removal. To keep code stable, avoid calling functions that have been flagged as deprecated.

J5015 - The parameter 'identifier' in an @com.parameters declaration does not match the corresponding argument 'identifier'

A COM interface parameter declaration does not match the method that implements the interface. This error could indicate inconsistent data types or mismatched parameter locations.

The following sample illustrates this warning.

/** @com.interface(iid=31415926-5358-9793-2384-612345678901, dual) */
interface ExampleInterface
{
/**
@com.method(dispid=306)
@com.parameters([type=BOOLEAN] when, on)
*/
public String Method1(boolean on, int when); //Error, on and when
                                             // have changed order.
}

J5016 - This 'instanceof' operator will always be true

The compiler determined that the specified instanceof expression will always evaluate to true. This could occur when instanceof is used to determine if a subclass instance is a member of a base class or an implemented interface. Although it is not an error to use the operator in this way, it is not useful because the expression will always evaluate to true.

The following sample illustrates this warning.

interface I {}
class X {}
class Y extends X implements I {}
public class Simple{
   void f()
   {
      Y y = new Y();
      X x = new X();
      Object o;
      // These statements result in J5016 warnings.
      if (y instanceof X){
         // y is of type Y, which extends X, so this is always true
      }
      if (y instanceof I){
         // type Y implements I, so this is always true.
      }
      if (x instanceof Object){
         // everything is of type Object
      }
   }
}

J5017 – Not used

This error message is currently not used.

J5018 – Class, interface, or package name contains characters not in the ASCII character set

The compiler detected a character that is not in the ASCII character set used for a class, interface, or package name. Some computer systems may not support this character. To ensure that your class, interface, or package name can be interpreted by virtual machines (VM) on other computer systems, change the invalid character to a valid character from the ASCII character set and compile again.

J5019 – Public member of COM-exposed class or interface contains characters not in the ASCII character set

The compiler detected a character that is not in the ASCII character set used for a method or field that is accessible to other languages via COM. Other languages may not support this character. To ensure that your member name can be accessed from other languages, change the character to a valid character from the ASCII character set and compile again.

J5020 - Directive @'identifier' ignored -- extensions are turned off

The Microsoft compiler for Java (jvc.exe) now disables Microsoft language extensions by default. This warning occurs when a program that uses the @com, @dll, or @security directives is compiled without enabling Microsoft language extensions. To compile code that uses Microsoft extensions, use the /x- option with jvc.

If you receive this warning, the .class file generated may not function properly. You should recompile using the /x- option. Failure to do so may result in the following error message when running your application:

Caught exception: java.lang.UnsatisfiedLinkError:Simple.MessageBox
Possible causes: If you are trying to use J/Direct (@dll.import),
check your compiler version (for JVC, requires 4336 or greater).
If you are trying to use RNI, there are new requirements: see
documentation. Probably wrong version of Java compiler.

Compiling with the /x- option generates a message warning that the use of Microsoft extensions results in compiled code that will run only on Windows systems with the Microsoft virtual machine installed and may not run on other virtual machines. You can disable this message by using the /nomessage option with jvc. For example:

jvc /x- /nomessage Test.java


J5021-J5500

J5021 | J5022 | J5023
J5024 | J5025-J5499 | J5500

J5021 - Package 'identifier' should not be defined in directory 'identifier'

The compiler detected a package statement in your source file but the directory name where the source file resides does not match the package statement. Although the source code will compile, other source files will not be able to reference classes, interfaces, and delegates defined in this source file using the package name.

The following example illustrates this warning.

//source file resides in c:\files\simple
package boxes; //warning: package 'boxes' does not match directory name
'simple'
public class NotSimple{
  //warning: this class is not accessible using the current package name
}

J5022 - Referenced class file 'filename' may be older than 'filename'

The compiler detected a class file, which is referenced by the source file being compiled, that is out of date or not found. This warning usually occurs when automatic re-compilation of referenced classes has been disabled (using the ref- compiler option). If you are compiling within Visual J++, the ref- option is passed to the compiler by default. If any of your source files reference a class file that is not in your project and the file is out of date with its source, you will need to update the referenced class files. You can either recompile the external class files to make them up to date, add the external files to your project, or add the ref compiler option. You can add the ref compiler option by entering it in the Additional Compiler Options text box in the Compile tab of the Project Settings dialog box.

J5023 - File 'filename' has more than 65535 lines--debug information may be incorrect

The compiler attempted to place debugging information in a source file that contains more than 65535 lines of code. Your code may compile, however; not all the debugging code needed for your application will be contained in this file. Reduce the size of your source file so that the debugging information can be added and compile again.

J5024 - Package 'identifier' was already imported

The compiler detected a package imported more than once in the specified source file. Although this will not cause the compiler to fail, you should remove the extra import statement for the package specified in the warning message.

J5025 to J5499 – Not used

These error messages are currently not used.

J5500 - #warning 'user defined warning'

This warning message is generated when there is a #warning conditional compilation directive in the program.

The following example illustrates this error.

#define DEBUG
public class Simple{
   public void method1(){
      #if DEBUG
         #warning You are compiling for debug mode
         //warning: displayed when 'DEBUG' is defined
      #endif
   }
}


Microsoft Packages Reference

The following Microsoft packages are in the Microsoft SDK for Java:

com.ms.activeX Package provides access to Microsoft® ActiveX® controls.

com.ms.awt Package provides access to Microsoft® Win32® window-management and graphics features.

com.ms.com Package provides access to Component Object Model (COM) services from Java.

com.ms.debug Package contains routines for debugging the Microsoft virtual machine.

com.ms.directX Package provides access to Microsoft® DirectX® services and features.

com.ms.dll Package provides additional support for Microsoft® J/Direct™, the technology that allows access to Microsoft® Windows® DLLs.

com.ms.ie Package provides the classes and interfaces needed by Java programs and applets to access and host the web browser for Microsoft® Windows®.

com.ms.io Package provides access to file dialog boxes, specialized input and output streams, and a class for manipulating path strings.

com.ms.io.clientstorage Package provides access to client storage management and enforcement of client storage limitations.

com.ms.lang Package provides access to Microsoft® Win32® system-level features.

com.ms.license Package provides classes that support Java object licensing files.

com.ms.net.wininet Package contains implementations of URL sockets.

com.ms.object Package provides classes and interfaces used to facilitate data transfer.

com.ms.object.dragdrop Package provides classes and interfaces for implementing visual drag-and-drop operations.

com.ms.security Package provides access to classes that control the security system.

com.ms.security.auditing Package provides an interface for supplying information about an audited security request to a security auditor.

com.ms.security.permissions Package provides access to classes that represent permission and request objects that are used to perform security checks.

com.ms.service Package provides access to Microsoft® Windows NT® system services.

com.ms.util Package provides access to version control, task manager, and timer services from Java.

com.ms.util.InputMethod Package provides access to Input Method Editor (IME) Java components.

com.ms.vm Package provides a class that implements a weak reference to an object. A weak reference tracks an object without preventing it from being garbage-collected.

com.ms.wfc.app provides classes that encapsulate Windows application operations, such as threads, messaging, and access to the Clipboard and the registry.

com.ms.wfc.core provides core component model classes.

com.ms.wfc.data provides basic data access using the ActiveX Data Objects (ADO) object model. Also provides classes that support data formatting.

com.ms.wfc.data.ui provides classes that implement and support data-bound controls.

com.ms.wfc.html provides access to the Dynamic HTML object model from Java classes. This includes both client and server applications.

com.ms.wfc.io provides classes for working with data streams.

com.ms.wfc.ui provides user interface component classes.

com.ms.wfc.util provides miscellaneous utility classes.

com.ms.win32 Package provides direct, low-overhead access to commonly used Windows APIs. These classes use the J/Direct feature.

com.ms.xml.dso Package provides a Data Source Object (DSO) applet class that can be used to provide data for data binding using Microsoft® XML files.

com.ms.xml.om Package provides classes that implement the Microsoft® XML Object Model in Java.

com.ms.xml.parser Package provides the Microsoft® XML Parser, which is a validating XML parser written in Java.

com.ms.xml.util Package provides base classes for Microsoft® XML object technology, including input and output stream objects specifically designed for XML.


com.ms.ActiveX Package Overview

Microsoft Packages Overview

You can use the classes and interfaces in the com.ms.activeX package to host Microsoft® ActiveX® controls and ActiveX Automation objects, to use ActiveX streams, and to access helper functions.

This package contains the following:

Classes

Interfaces

Hierarchy

Overview of Classes

The ActiveXControl class provides methods that enable you to host an ActiveX control. You can create the control using the ActiveXControl constructor and then call other methods in the class to set its properties, retrieve its properties, and invoke its methods. The Hosting an ActiveX Control section of this document further describes how you can host an ActiveX control in your Java application.

The ActiveXControlListener interface, when used with the ActiveXControl.addActiveXControlListener method, allows you to register a listener for an ActiveX control so that the listener will be notified when the ActiveX control has been created. Any listeners must implement the ActiveXControlListener interface, which contains a single method called controlCreated. When an ActiveX control is created, the Microsoft VM calls the controlCreated method on the listener object.

The ActiveXInputStream and ActiveXOutputStream classes wrap IStream objects that are obtained from COM objects. Instances of these classes are compatible with other Java classes that take java.io.InputStream and java.io.OutputStream objects as parameters. These classes are also used by the Microsoft VM to wrap IStream objects that it obtains from ActiveX containers like Microsoft® Visual Basic®. Once the object is wrapped, the VM can use the java.io serialization classes that work only with InputStream and OutputStream objects.

The ActiveXToolkit class contains methods that allow you to create a FontX object, given an IUnknown interface. You can also use the methods in this class to retrieve the IUnknown interface of a Font object and to create a Java color from an OLE_COLOR.

Hosting an ActiveX Control

There are two ways two host an ActiveX control in a Java application. One way is to use the jactivex tool to generate a Java wrapper for the ActiveX control. The other is to use the ActiveXControl classes directly.

Generating a Java Wrapper for an ActiveX Control

Using the ActiveXControl Class to Host an ActiveX Control

Generating a Java Wrapper for an ActiveX Control

You can run the jactivex tool on the ActiveX control to generate Java source code for the control. When you compile the .java files emitted by jactivex, you get .class files that you can import. You can then use the control just as you would any other Java object. For example, suppose you have obtained a control called MyControl that has a method called MyMethod. After you run the jactivex tool on this control and compile the resulting files, you could use the object in the following way:

   import MyControl.*;
   import java.awt.*;

   // create the control
   MyControl c = new MyControl();

   //add the control to the layout
   add("Center", c);
   ...

   // call MyMethod
   c.MyMethod(...);

For more information about using jactivex to host an ActiveX control, see Using the Raw Native Interface and the jactivex section of the Tools Reference.

Using the ActiveXControl Class to Host an ActiveX Control

The other way to host an ActiveX control involves using the methods in the ActiveX control class. To create the control, you would pass the CLSID or ProgID to the ActiveXControl constructor. You can then invoke methods, retrieve properties, or set properties of the control. Again, suppose you have a control called MyControl that has a method called MyMethod. You can create the control and add it to the layout, as shown in the following example:

   import MyControl.*;
   import com.ms.activeX.ActiveXControl;
   import java.awt.*;

   // create the control
   ActiveXControl c = new ActiveXControl("MyControl");

   // add the control to the layout
   add("Center", c);

   // do something interesting
   ...

Invoking Methods of an ActiveX Control

Suppose MyControl has a method called MyMethod that you want to call. Let's assume that MyMethod takes three parameters: a String, an integer, and a boolean. The ActiveXControl.invoke method allows you to call MyMethod. The invoke method takes as a parameter an array of Variants that contains the arguments to the method you want to call. The arguments are passed to the control through IDispatch.

This example shows how you could create and initialize an array of Variants called args and call MyMethod by passing args to the invoke method.

   Variant args[] = new Variant[3};
   args[0] = new Variant("String arg");
   args[1] = new Variant(100);
   args[2] = new Variant(true);
   c.invoke("MyMethod", args);

Retrieving Properties of an ActiveX Control

You can also use the ActiveXControl class to retrieve properties from an object. To do this, call the ActiveXControl.getProperty method. If MyControl had a property called MyProperty, you could retrieve its value in the following way:

   // Create the control as before
   ActiveXControl c = new ActiveXControl("MyControl");
   ...

   // Retrieve a property
   Variant propvalue = c.getProperty("MyProperty");

Initializing an ActiveX Control Using Property Bags

You can call the setProperty method of the ActiveXControl class to set a property of an ActiveX control. If the setProperty method is called before the addNotify method is called, the setProperty method places properties in the property bag of the control. This gives the control a mechanism for setting its default state. After the control has been called on addNotify, the setProperty method is invoked using IDispatch.

The following example shows how to initialize two properties of MyControl using the setProperty method to place the properties in the property bag:

   ActiveXControl c = new ActiveXControl("MyControl");
   c.setProperty("MyProperty", true);
   c.setProperty("MyOtherProperty", 1);
   add("Center", c);

Sinking Events from ActiveX Objects

Using the jactivex tool, you can gain access to the event interface of the ActiveX object. For example, suppose you have a control called MyControl that has an event interface called MyEventInterface. As an example, this interface might have a method called theEvent, which needs to be implemented by any class that wants to sink theEvent from MyControl.

A Java object can sink events from the ActiveX object by using the com.ms.com.ConnectionPointCookie class, as follows:

import MyControl.*;
import com.ms.activeX.ActiveXControl;
import com.ms.com.ConnectionPointCookie;

public class MyEventSinker implements MyEventInterface {

   ...

   MyControl c = new MyControl;
   Eventcookie = new ConnectionPointCookie(c, this,
                 Class.forName("MyControl.MyEventInterface");

   // hold onto Eventcookie as long as you want the connection to exist
   ...

   public void theEvent(String x){

      // do something interesting
      ...
   }
}


Classes (com.ms.ActiveX Package)

 Microsoft SDK for Java

com.ms.ActiveX Package Classes

The com.ms.ActiveX package contains the following classes:

ActiveXComponent Class provides basic Microsoft® ActiveX® control functionality.

ActiveXControl Class exposes methods, properties, and events used to host Microsoft® ActiveX® controls.

ActiveXInputStream Class provides access to methods that manipulate input streams.

ActiveXOutputStream Class provides access to methods that manipulate output streams.

ActiveXToolkit Class provides a toolkit of Component Object Model (COM) functions.


Interfaces (com.ms.ActiveX Package)

 Microsoft SDK for Java

com.ms.ActiveX Package Interfaces

The com.ms.ActiveX package contains the following interfaces:

ActiveXControlListener Interface provides a method that notifies an object after a Microsoft® ActiveX® control has been created.

ActiveXControlServices Interface represents a standard system service that is available for Java components hosted inside ActiveX containers.


Hierarchy (com.ms.ActiveX Package)

 Microsoft SDK for Java

com.ms.ActiveX Package Hierarchy

The com.ms.ActiveX package has the following hierarchy:

Object
  |
  +--ActiveXToolkit

Canvas
  |
  +--ActiveXComponent
     |
     +--ActiveXControl (Serializable, HeavyComponent)

InputStream
  |
  +--ActiveXInputStream

OutputStream
  |
  +--ActiveXOutputStream

ActiveXControlListener
ActiveXControlServices


ActiveXComponent Class (com.ms.ActiveX Package)

 Microsoft SDK for Java

ActiveXComponent Class

The ActiveXComponent Class of the com.ms.ActiveX package provides basic Microsoft® ActiveX® control functionality. Its methods allow you to create ActiveXComponent objects, to set or retrieve the CLSID (class identifier) that identifies the class of the object, and to get the IUnknown interface of an ActiveXComponent object. The ActiveXControl class extends this class.

public class ActiveXComponent extends Canvas
{
  // Constructors
      public ActiveXComponent();
  public ActiveXComponent(String c);
  public ActiveXComponent(IUnknown punk);

  // Methods
  public Iunknown createInstance(String c);
  public IUnknown createInstance();
  public void createInstance(IUnknown punk);
  public void enableEvents();
  public String getCLSID();
  protected IAXComponent getHost();
  public IUnknown getObject();
  public Variant getProperty(String propertyname);
  public Variant invoke(String methodname, Variant args[]);
  public void setCLSID(String c);
  public void setProperty(String name, Variant value);
}

Hierarchy

Canvas
  |
  +--ActiveXComponent


Constructors (ActiveXComponent Class)

 Microsoft SDK for Java

ActiveXComponent Class Constructors

The ActiveXComponent Class contains the following constructors:

ActiveXComponent()
ActiveXComponent(String c)
ActiveXComponent(IUnknown punk)

ActiveXComponent()

Creates a new ActiveXComponent object.

Syntax

public ActiveXComponent();

ActiveXComponent(String c)

Creates a new ActiveXComponent object whose class is identified by the CLSID or ProgID (programatic identifier).

Syntax

public ActiveXComponent(String c);

Parameters

c The CLSID (or ProgID) of the object that is created. The CLSID must be in the form "{xxx...xxx}", where x represents a numeric character between 0 and 9, inclusive.

ActiveXComponent(IUnknown punk)

Creates a new ActiveXComponent object using the identity of a pre-existing COM object.

Syntax

public ActiveXComponent(IUnknown punk);

Parameters

punk The identity of the COM object.


Methods (ActiveXComponent Class)

 Microsoft SDK for Java

ActiveXComponent Class Methods

The ActiveXComponent Class contains the following methods:

createInstance creates a new instance of the ActiveXComponent class.
enableEvents wires events for an object.
getCLSID retrieves the CLSID (or ProgID) of the ActiveXComponent object.
getHost retrieves the interface of the ActiveXComponent host.
getObject retrieves the IUnknown interface of an ActiveXComponent object.
getProperty invokes a property to retrieve the property value.
invoke invokes a method on the ActiveX control.
setCLSID sets the CLSID or (ProgID) of the ActiveXComponent object.
setProperty sets a variant property of the ActiveX control.


createInstance (ActiveXComponent Class)

 Microsoft SDK for Java

createInstance

The createInstance method of the ActiveXComponent Class contains the following signatures:

createInstance(String c)
createInstance()
createInstance(IUnknown punk)

createInstance(String c)

Creates a new instance of the ActiveXComponent class.

Syntax

public IUnknown createInstance(String c);

Return Value

Returns the IUnknown interface of the new object.

Parameters

c The CLSID (or ProgID) of the object that is created. The CLSID must be in the form "{xxx...xxx}", where x represents a numeric character between 0 and 9, inclusive.

createInstance()

Creates a new ActiveXComponent object with the CLSID that was previously set by the constructor or by the setCLSID method.

Syntax

public IUnknown createInstance();

Return Value

Returns the IUnknown interface of the new object.

createInstance(IUnknown punk)

Creates a new ActiveXComponent object using the identity of a pre-existing COM object.

Syntax

public void createInstance(IUnknown punk);

Parameters

punk The identity of the COM object.


enableEvents (ActiveXComponent Class)

 Microsoft SDK for Java

enableEvents

This method of the ActiveXComponent Class wires events for an object. When an object derives from the ActiveXComponent class, this method should be implemented using an instance of ConnectionPointCookie to sink an event.

Syntax

public void enableEvents();


getCLSID (ActiveXComponent Class)

 Microsoft SDK for Java

getCLSID

This method of the ActiveXComponent Class retrieves the CLSID (or ProgID) of the ActiveXComponent object.

Syntax

public String getCLSID();

Return Value

Returns the CLSID (or ProgID) for the component.


getHost (ActiveXComponent Class)

 Microsoft SDK for Java

getHost

This method of the ActiveXComponent Class retrieves the interface of the ActiveXComponent host.

Syntax

protected IAXComponent getHost();

Return Value

Returns the interface of the ActiveXComponent host.


getObject (ActiveXComponent Class)

 Microsoft SDK for Java

getObject

This method of the ActiveXComponent Class retrieves the IUnknown interface of an ActiveXComponent object.

Syntax

public IUnknown getObject();

Return Value

Returns the IUnknown interface of the ActiveXComponent object.


getProperty (ActiveXComponent Class)

 Microsoft SDK for Java

getProperty

This method of the ActiveXComponent Class invokes a property to retrieve the property value.

Syntax

public Variant getProperty(String propertyname);

Return Value

Returns the value of the property.

Parameters

propertyname The name of the property whose value will be retrieved.

Exceptions

IllegalArgumentException if propertyname is null.


invoke (ActiveXComponent Class)

 Microsoft SDK for Java

invoke

This method of the ActiveXComponent Class invokes a method on the ActiveX control.

Syntax

public Variant invoke(String methodname, Variant args[]);

Return Value

Returns the value returned by the invoked method.

Parameters

methodname | The name of the method to invoke.
args | The argument list for the method.

Exceptions

IllegalArgumentException if methodname is null.


setCLSID (ActiveXComponent Class)

 Microsoft SDK for Java

setCLSID

This method of the ActiveXComponent Class sets the CLSID or (ProgID) of the ActiveXComponent object.

Syntax

public void setCLSID(String c);

Parameters

c The new CLSID (or ProgID) of the object. The CLSID must be in the form "{xxx...xxx}", where x represents a numeric character between 0 and 9, inclusive.


setProperty (ActiveXComponent Class)

 Microsoft SDK for Java

setProperty

This method of the ActiveXComponent Class sets a variant property of the ActiveX control.

Syntax

public void setProperty(String name, Variant value);

Parameters

name | The name of the property to set.
value | The value of the property.

Exceptions

IllegalArgumentException if name is null.


ActiveXControl Class (com.ms.ActiveX Package)

 Microsoft SDK for Java

ActiveXControl Class

The ActiveXControl Class of the com.ms.ActiveX package exposes methods, properties, and events used to host Microsoft® ActiveX® controls. Instances of the ActiveXControl class are objects that enable Java components to host ActiveX controls.

public class ActiveXControl extends ActiveXComponent
             implements Serializable, HeavyComponent
{
  // Fields
  public static final int CURRENCY;
  public static final int DATE;
  public static final int DOUBLE;

  // Constructors
  public ActiveXControl();
  public ActiveXControl(String clsid);
  public ActiveXControl(IUnknown punk);

  // Methods
  public void activate();
  public void activateNoGUI();
  public void addActiveXControlListener(
        ActiveXControlListener listener);
  protected void createControl(String clsid) throws Exception;
  protected void createControl(IUnknown punk) throws Exception;
  protected void finalize() throws Throwable;
  public Dimension getMinimumSize();
  public Dimension getPreferredSize();
  public boolean isFocusTraversable();
  public synchronized void processComponentEvent(
        ComponentEvent event);
  public void processFocusEvent(FocusEvent event);
  public void removeActiveXControlListener(
        ActiveXControlListener listener);
  public void removeNotify();
  public void setBackground(Color c);
  public void setDesignMode(boolean b);
  public void setFont(Font f);
  public void setForeground(Color c);
  public void setProperty(String name, String value);
  public void setProperty(String name, int value);
  public void setProperty(String name, short value);
  public void setProperty(String name, boolean value);
  public void setProperty(String name, long value, int flag);
  public void setProperty(String name, double value);
  public void setProperty(String name, double value, int flag);
  public void setProperty(String name, float value);
  public void setProperty(String name, Variant value);
  public void showPropertyDialog();
}

Hierarchy

Canvas
  |
  +--ActiveXComponent
     |
     +--ActiveXControl


Constructors (ActiveXControl Class)

 Microsoft SDK for Java

ActiveXControl Class Constructors

The ActiveXControl Class contains the following constructors:

ActiveXControl()
ActiveXControl(String clsid)
ActiveXControl(IUnknown punk)

ActiveXControl()

Creates an ActiveXControl object that is a container for an ActiveX control. To add a control to the container, you can call the createControl method.

Syntax

public ActiveXControl();

ActiveXControl(String clsid)

Creates an ActiveXControl object that is a container for an ActiveX control. This method hosts the control specified by the CLSID (class identifier) or ProgID (programatic identifier).

Syntax

public ActiveXControl(String clsid);

Parameters

clsid Identifies the CLSID (or ProgID) for the ActiveX control. The CLSID is in the form "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}", where x is a valid hexadecimal number.

ActiveXControl(IUnknown punk)

Creates an ActiveXControl object that is a container for an ActiveX control. This method hosts a control that has already been created.

Syntax

public ActiveXControl(IUnknown punk);

Parameters

punk The identity of the ActiveX control.


Methods (ActiveXControl Class)

 Microsoft SDK for Java

ActiveXControl Class Methods

The ActiveXControl Class contains the following methods:

activate tells the control to become in-place active.
activateNoGUI activates a non-GUI control.
addActiveXControlListener adds an ActiveXControlListener object that listens to events sourced by the ActiveXControl class.
createControl creates an ActiveXControl object that is a container for an ActiveX control.
finalize removes the ActiveX control from memory.
getMinimumSize retrieves the minimum size of the ActiveXControl object.
getPreferredSize retrieves the preferred size of the ActiveXControl object.
isFocusTraversable tells the window manager that we want focus.
processComponentEvent processes the events from the component.
processFocusEvent processes focus events.
removeActiveXControlListener removes an ActiveXControlListener object from the list of interested listeners.
removeNotify destroys the component's peer.
setBackground sets the background color of the component.
setDesignMode tells the ActiveX control to go into design mode.
setFont sets the font of the component.
setForeground sets the foreground color of the component.
setProperty sets a string property of the ActiveX control.
showPropertyDialog queries an ActiveX control for its property pages and displays the property dialog box.


activate (ActiveXControl Class)

 Microsoft SDK for Java

activate

This method of the ActiveXControl Class tells the control to become in-place active.

Syntax

public void activate();

Note By default, a control is activated at addNotify time. Therefore, if an ActiveXControl object needs properties for initialization, calls to the setProperty method should be made before addNotify time.


activateNoGUI (ActiveXControl Class)

 Microsoft SDK for Java

activateNoGUI

This method of the ActiveXControl Class activates a non-GUI control. By default, all ActiveX controls are assumed to have UI. However, the negotiation for such a control happens at addNotify time when an object is added to a layout. You should call this method to activate a control that does not have GUI representation.

Syntax

public void activateNoGUI();


addActiveXControlListener (ActiveXControl Class)

 Microsoft SDK for Java

addActiveXControlListener

This method of the ActiveXControl Class adds an ActiveXControlListener object that listens to events sourced by the ActiveXControl class.

Syntax

public void addActiveXControlListener(ActiveXControlListener listener);

Parameters

listener The ActiveXControlListener object that will sink events.


createControl (ActiveXControl Class)

 Microsoft SDK for Java

createControl

The createControl method of the ActiveXControl Class contains the following signatures:

createControl(String clsid)
createControl(IUnknown punk)

createControl(String clsid)

Creates an ActiveXControl object that is a container for an ActiveX control. This method hosts the control specified by the CLSID (or ProgID).

Syntax

protected void createControl(String clsid) throws Exception;

Parameters

clsid Identifies the CLSID (or ProgID) for the ActiveX control. The CLSID is in the form "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}", where "x" is a valid hexadecimal number.

Remarks

This method is used to defer the hosting of an ActiveX control, and is typically used when a control host was created using the ActiveXControl () constructor or when extending the ActiveXControl class.

Exceptions

Exception if there is an error when initializing the control.

NullPointerException if clsid is null or if the IUnknown for the ActiveX control is not valid.

createControl(IUnknown punk)

Creates an ActiveXControl object that is a container for an ActiveX control. This method hosts a control that has already been created.

Syntax

protected void createControl(IUnknown punk) throws Exception;

Parameters

punk The identity of the ActiveX control.

Remarks

This method is used to defer the hosting of an ActiveX control, and is typically used when a control host was created using the ActiveXControl() constructor or when extending the ActiveXControl class.

Exceptions

Exception if there is an error when initializing the control.

NullPointerException if punk is null.


finalize (ActiveXControl Class)

 Microsoft SDK for Java

finalize

This method of the ActiveXControl Class removes the ActiveX control from memory. This method is called by the garbage collector.

Syntax

protected void finalize() throws Throwable;


getMinimumSize (ActiveXControl Class)

 Microsoft SDK for Java

getMinimumSize

This method of the ActiveXControl Class retrieves the minimum size of the ActiveXControl object.

Syntax

public Dimension getMinimumSize();

Return Value

Returns the object's minimum size, which is the same as its preferred size, measured in pixels.


getPreferredSize (ActiveXControl Class)

 Microsoft SDK for Java

getPreferredSize

This method of the ActiveXControl Class retrieves the preferred size of the ActiveXControl object.

Syntax

public Dimension getPreferredSize();

Return Value

Returns the preferred width and height of the object, measured in pixels.


isFocusTraversable (ActiveXControl Class)

 Microsoft SDK for Java

isFocusTraversable

This method of the ActiveXControl Class tells the window manager to put an object in the focus traversing list.

Syntax

public boolean isFocusTraversable();

Return Value

Returns true if the object is placed in the focus traversing list.


processComponentEvent (ActiveXControl Class)

 Microsoft SDK for Java

processComponentEvent

This method of the ActiveXControl Class processes the events from the component. It determines when the object has been resized, shown, or hidden.

Syntax

public synchronized void processComponentEvent(ComponentEvent event);

Parameters

event The ComponentEvent that was fired by the container.


processFocusEvent (ActiveXControl Class)

 Microsoft SDK for Java

processFocusEvent

This method of the ActiveXControl Class processes focus events. When the focus is gained, the ActiveX control will become UI-active.

Syntax

public void processFocusEvent(FocusEvent event);

Parameters

event The FocusEvent object that was generated by the window manager.


removeActiveXControlListener (ActiveXControl Class)

 Microsoft SDK for Java

removeActiveXControlListener

This method of the ActiveXControl Class removes an ActiveXControlListener object from the list of interested listeners. After this method is called, the component will no longer be notified on control hosting events.

Syntax

public void removeActiveXControlListener(ActiveXControlListener listener);

Parameters

listener The ActiveXControlListener object that will be removed.


removeNotify (ActiveXControl Class)

 Microsoft SDK for Java

removeNotify

This method of the ActiveXControl Class destroys the component's peer.

Syntax

public void removeNotify();

!WARNING You should never call this method directly.


setBackground (ActiveXControl Class)

 Microsoft SDK for Java

setBackground

This method of the ActiveXControl Class sets the background color of the component. This method notifies the control that the background color has changed.

Syntax

public void setBackground(Color c);

Parameters

c The new color of the background.


setDesignMode (ActiveXControl Class)

 Microsoft SDK for Java

setDesignMode

This method of the ActiveXControl Class tells the ActiveX control to go into design mode.

Syntax

public void setDesignMode(boolean b);

Parameters

b The value that indicates whether the control should be notified that it is in design mode. If the value is true, the control is notified that the container is in design mode. If the value is false (the default), the container notifies the control that it is in run mode.


setFont (ActiveXControl Class)

 Microsoft SDK for Java

setFont

This method of the ActiveXControl Class sets the font of the component. This method notifies the control that the font has changed.

Syntax

public void setFont(Font f);

Parameters

f The new font.


setForeground (ActiveXControl Class)

 Microsoft SDK for Java

setForeground

This method of the ActiveXControl Class sets the foreground color of the component. This method notifies the control that the foreground color has changed.

Syntax

public void setForeground(Color c);

Parameters

c The new color of the foreground.


setProperty (ActiveXControl Class)

 Microsoft SDK for Java

setProperty

The setProperty method of the ActiveXControl Class contains the following signatures:

setProperty(String name, String value)
setProperty(String name, int value)
setProperty(String name, short value)
setProperty(String name, boolean value)
setProperty(String name, long value, int flag)
setProperty(String name, double value)
setProperty(String name, double value, int flag)
setProperty(String name, float value)
setProperty(String name, Variant value)

setProperty(String name, String value)

Sets a string property of the ActiveX control.

Syntax

public void setProperty(String name, String value);

Parameters

name | The name of the property that is set.
value | The string value of the property.

setProperty(String name, int value)

Sets an integer property of the ActiveX control.

Syntax

public void setProperty(String name, int value);

Parameters

name | The name of the property that is set.
value | The integer value of the property

setProperty(String name, short value)

Sets a short integer property of the ActiveX control.

Syntax

public void setProperty(String name, short value);

Parameters

name | The name of the property that is set.
value | The short integer value of the property.

setProperty(String name, boolean value)

Sets a boolean property of the ActiveX control.

Syntax

public void setProperty(String name, boolean value);

Parameters

name | The name of the property that is set.
value | The boolean value of the property.

setProperty(String name, long value, int flag)

Sets a currency property of the ActiveX control.

Syntax

public void setProperty(String name, long value, int flag);

Parameters

name | The name of the property that is set.
value | The value of the property
flag | Indicates how to set the property. If the value is CURRENCY, the property type is set to indicate currency; otherwise, the method returns without setting a property.

setProperty(String name, double value)

Sets a double property of the ActiveX control.

Syntax

public void setProperty(String name, double value);

Parameters

name | The name of the property that is set
value | The value of the property.

setProperty(String name, double value, int flag)

Sets a double or a date property of the ActiveX control.

Syntax

public void setProperty(String name, double value, int flag);

Parameters

name | The name of the property that is set.
value | The double value of the property
flag | The value that determines how to set the property type. If the value is DATE, the property type is set to indicate a date; if the value is DOUBLE, the property type is set to indicate a double.

setProperty(String name, float value)

Sets a float property of the ActiveX control.

Syntax

public void setProperty(String name, float value);

Parameters

name | The name of the property that is set.
value | The float value of the property.

setProperty(String name, Variant value)

Sets a variant property of the ActiveX control.

Syntax

public void setProperty(String name, Variant value);

Parameters

name | The name of the property to set.
value | The value of the property.

Overrides

setProperty(String,Variant) in ActiveXComponent.


showPropertyDialog (ActiveXControl Class)

 Microsoft SDK for Java

showPropertyDialog

This method of the ActiveXControl Class queries an ActiveX control for its property pages and displays the property dialog box.

Syntax

public void showPropertyDialog();


Fields (ActiveXControl Class)

 Microsoft SDK for Java

ActiveXControl Class Fields

The ActiveXControl Class contains the following fields.

CURRENCY | Indicates the currency variant type.
DATE | Indicates the date variant type.
DOUBLE | Indicates the double variant type.


ActiveXInputStream Class (com.ms.ActiveX Package)

 Microsoft SDK for Java

ActiveXInputStream Class

The ActiveXInputStream Class of the com.ms.ActiveX package provides access to methods that manipulate input streams.

public class ActiveXInputStream extends InputStream
{
  // Constructors
  public ActiveXInputStream(IStream stream);

  // Methods
  public int available() throws IOException;
  public void close() throws IOException;
  public int read() throws IOException;
  public int read(byte b[], int off, int len) throws IOException;
  public long skip(long n) throws IOException;
}

You can create an input stream, read bytes from it, skip a specified number of bytes in the stream, see how many bytes are available to read, and close an input stream using the methods in this class.

Hierarchy

InputStream
  |
  +--ActiveXInputStream


Constructors (ActiveXInputStream Class)

 Microsoft SDK for Java

ActiveXInputStream Class Constructors

The ActiveXInputStream Class contains the following constructor:

ActiveXInputStream(IStream stream)

Creates an ActiveXInputStream object.

Syntax

public ActiveXInputStream(IStream stream);

Parameters

stream The IStream interface for the new object.


Methods (ActiveXInputStream Class)

 Microsoft SDK for Java

ActiveXInputStream Class Methods

The ActiveXInputStream Class contains the following methods:

available determines the number of bytes that can be read from the input stream without blocking.
close closes the input stream and releases the IStream interface associated with the stream.
read reads the next byte of data from the input stream.
skip skips over and discards bytes of data from the input stream and returns the number of bytes actually skipped.


available (ActiveXInputStream Class)

 Microsoft SDK for Java

available

This method of the ActiveXInputStream Class determines the number of bytes that can be read from the input stream without blocking.

Syntax

public int available() throws IOException;

Return Value

Returns the number of bytes that can be read from the input stream without blocking.

Exceptions

IOException if an I/O error occurs.


close (ActiveXInputStream Class)

 Microsoft SDK for Java

close

This method of the ActiveXInputStream Class closes the input stream and releases the IStream interface associated with the stream.

Syntax

public void close() throws IOException;

Exceptions

IOException if an I/O error occurs.


read (ActiveXInputStream Class)

 Microsoft SDK for Java

read

The read method of the ActiveXInputStream Class contains the following signatures:

read()
read(byte b[], int off, int len)

read()

Reads the next byte of data from the input stream. The value of the byte is returned as an integer 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.

Syntax

public int read() throws IOException;

Return Value

Returns the next byte of data, or -1 if the end of the stream is reached.

Exceptions

IOException if an I/O error occurs.

read(byte b[], int off, int len)

Reads bytes of data from the input stream into an array of bytes. This method blocks until some input is available.

Syntax

public int read(byte b[], int off, int len) throws IOException;

Return Value

Returns the total number of bytes read into the buffer; returns -1 if there is no more data because the end of the file has been reached.

Parameters

b | The buffer into which the data is read.
off | The starting offset of the data.
len | The maximum number of bytes to read.

Exceptions

IOException if an I/O error occurs.


skip (ActiveXInputStream Class)

 Microsoft SDK for Java

skip

This method of the ActiveXInputStream Class skips over and discards bytes of data from the input stream and returns the number of bytes actually skipped.

Syntax

public long skip(long n) throws IOException;

Return Value

Returns the number of bytes skipped.

Parameters

n The number of bytes to skip.

Remarks

If there are fewer than n bytes remaining before the end of the stream, this method skips the number of bytes remaining. The current read position is set to the end of the file and the number of bytes skipped is returned.

Exceptions

IOException if an I/O error occurs.


ActiveXOutputStream Class (com.ms.ActiveX Package)

 Microsoft SDK for Java

ActiveXOutputStream Class

The ActiveXOutputStream Class of the com.ms.ActiveX package provides access to methods that manipulate output streams. You can create an output stream, write bytes to it, flush the output stream, and close it by using the methods in this class.

public class ActiveXOutputStream extends OutputStream
{
  // Constructors
  public ActiveXOutputStream(IStream stream);

  // Methods
  public void close() throws IOException;
  public void flush() throws IOException;
  public void write(int b) throws IOException;
  public void write(byte b[], int off, int len) throws IOException;
}

Hierarchy

OutputStream
  |
  +--ActiveXOutputStream


Constructors (ActiveXOutputStream Class)

 Microsoft SDK for Java

ActiveXOutputStream Class Constructors

The ActiveXOutputStream Class contains the following constructor:

ActiveXOutputStream(IStream stream)

Creates an ActiveXOutputStream object that has the specified IStream interface.

Syntax

public ActiveXOutputStream(IStream stream);

Parameters

stream The IStream interface of the object.


Methods (ActiveXOutputStream Class)

 Microsoft SDK for Java

ActiveXOutputStream Class Methods

The ActiveXOutputStream Class contains the following methods:

close closes the output stream and releases the IStream interface associated with the stream.
flush flushes the output stream and forces buffered output bytes to be written out.
write writes a byte to the output stream.


close (ActiveXOutputStream Class)

 Microsoft SDK for Java

close

This method of the ActiveXOutputStream Class closes the output stream and releases the IStream interface associated with the stream.

Syntax

public void close() throws IOException;

Exceptions

IOException if an I/O error occurs.


flush (ActiveXOutputStream Class)

 Microsoft SDK for Java

flush

This method of the ActiveXOutputStream Class flushes the output stream and forces buffered output bytes to be written out.

Syntax

public void flush() throws IOException;

Exceptions

IOException if an I/O error occurs.


write (ActiveXOutputStream Class)

 Microsoft SDK for Java

write

The write method of the ActiveXOutputStream Class contains the following signatures:

write(int b)
write(byte b[], int off, int len)

write(int b)

Writes a byte to the output stream.

Syntax

public void write(int b) throws IOException;

Parameters

b The byte to write to the output stream.

Exceptions

IOException if an I/O error occurs.

write(byte b[], int off, int len)

Writes a specified number of bytes from a byte array to the output stream, beginning with the byte at offset off in the array.

Syntax

public void write(byte b[], int off, int len) throws IOException;

Parameters

b | The bytes to write.
off | The starting offset in the array.
len | The number of bytes to write.

Exceptions

IOException if an I/O error occurs.


ActiveXToolkit Class (com.ms.ActiveX Package)

 Microsoft SDK for Java

ActiveXToolkit Class

The ActiveXToolkit Class of the com.ms.ActiveX package provides a toolkit of Component Object Model (COM) functions.

public class ActiveXToolkit
{
  // Methods
  static public java.awt.Color getColorFromOLECOLOR(int colorindex);
  static public FontX getFontX(Object punk);
  static public Object getIUnknownFont(Font font);
}


Methods (ActiveXToolkit Class)

 Microsoft SDK for Java

ActiveXToolkit Class Methods

The ActiveXToolkit Class contains the following methods:

getColorFromOLECOLOR creates a Java color from an OLE_COLOR.
getFontX creates a FontX object, given an IUnknown interface.
getIUnknownFont retrieves the IUnknown interface of a Font object that represents a Java font.


getColorFromOLECOLOR (ActiveXToolkit Class)

 Microsoft SDK for Java

getColorFromOLECOLOR

This method of the ActiveXToolkit Class creates a Java color from an OLE_COLOR.

Syntax

static public java.awt.Color getColorFromOLECOLOR(int colorindex);

Return Value

Returns the Java color that is derived from the OLE_COLOR.

Parameters

colorindex The OLE_COLOR that the Java color is created from.


getFontX (ActiveXToolkit Class)

 Microsoft SDK for Java

getFontX

This method of the ActiveXToolkit Class creates a FontX object, given an IUnknown interface. This method obtains the font for the object by using QueryInterface on IUnknown to query for the IFont interface.

Syntax

static public FontX getFontX(Object punk);

Return Value

Returns a FontX object obtained by querying IUnknown for the IFont interface. If punk is null, null is returned.

Parameters

punk The IUnknown interface that is queried for the IFont interface.


getIUnknownFont (ActiveXToolkit Class)

 Microsoft SDK for Java

getIUnknownFont

This method of the ActiveXToolkit Class retrieves the IUnknown interface of a Font object that represents a Java font.

Syntax

static public Object getIUnknownFont(Font font);

Return Value

Returns the IUnknown interface of an Font object that represents a Java font.

Parameters

font The Font object that represents a Java font.


ActiveXControlListener Interface (com.ms.ActiveX Package)

 Microsoft SDK for Java

ActiveXControlListener Interface

The ActiveXControlListener Interface of the com.ms.ActiveX package provides a method that notifies an object after a Microsoft® ActiveX® control has been created. After the control has been created, it is safe to call methods on the ActiveX control.

public interface ActiveXControlListener extends java.util.EventListener
{
  // Methods
  public void controlCreated(Object target);
}

Hierarchy

EventListener
  |
  +--ActiveXControlListener


Methods (ActiveXControlListener Interface)

 Microsoft SDK for Java

ActiveXControlListener Interface Methods

The ActiveXControlListener Interface contains the following method:

controlCreated notifies an object after an ActiveX control has been created.


controlCreated (ActiveXControlListener Interface)

 Microsoft SDK for Java

controlCreated

This method of the ActiveXControlListener Interface notifies an object after an ActiveX control has been created. After such notification, it is safe to call methods on the ActiveX control.

Syntax

public void controlCreated(Object target);

Parameters

target The ActiveX control that was created.


ActiveXControlServices Interface (com.ms.ActiveX Package)

 Microsoft SDK for Java

ActiveXControlServices Interface

The ActiveXControlServices Interface of the com.ms.ActiveX package represents a standard system service that is available for Java components hosted inside Microsoft® ActiveX® containers.

public interface ActiveXControlServices
{
  // Methods
  public Object getClientSite();
}

The ActiveXControlServices system service can be obtained by using the queryService method of the com.ms.object.IServiceObjectProvider interface to query a site object.

A Java component must implement the com.ms.object.ISiteable interface to obtain an object that implements the com.ms.object.ISite interface. This site object can be queried for the ActiveXControlServices service when the Java component is hosted from an ActiveX container, such as Microsoft® Visual Basic®.


Methods (ActiveXControlServices Interface)

 Microsoft SDK for Java

ActiveXControlServices Interface Methods

The ActiveXControlServices Interface contains the following method:

getClientSite retrieves the ActiveX client site object.


getClientSite (ActiveXControlServices Interface)

 Microsoft SDK for Java

getClientSite

This method of the ActiveXControlServices Interface retrieves the ActiveX client site object. This object might implement any number of standard ActiveX site interfaces, such as IOleClientSite or IOleInPlaceSite. The client site object can be used as a bridge between an ActiveX container and a Java component that it is hosting.

Syntax

public Object getClientSite();


com ms awt Package Overview

 Microsoft SDK for Java

com.ms.awt Package Overview

Microsoft Packages Overview

The com.ms.awt package provides access to Microsoft® Win32® system-level features that are not available in the standard java.awt package.

Microsoft has completely reimplemented AWT for the Microsoft® Win32® platform. This reimplementation removes AWT's dependency on the Microsoft Foundation Classes (MFC), eliminates overhead, and reduces performance problems. Microsoft® ActiveX® Controls can now also be hosted as JavaBeans.

This package contains the following:

Classes

Interfaces

Hierarchy


Classes (com.ms.awt Package)

 Microsoft SDK for Java

com.ms.awt Package Classes

The com.ms.awt package contains the following classes:

CursorX Class implements an extended cursor object.

Device Class manages information associated with a generic device.

DeviceException Class signals that a com.ms.awt.Device-related exception has occurred.

DisplayDevice Class handles display devices.

FocusEvent Class manages component-level focus events.

FontMetricsX Class provides an extended font metrics implementation specific to the Microsoft VM.

FontX Class creates a font object that defines the font family, font face, style, and size.

GraphicsX Class provides a graphics implementation specifically for the Microsoft virtual machine (Microsoft VM).

ImageX Class encapsulates an extended image object.

Mat2 Class defines a transformation matrix that can be used with outline font methods.

PointFx Class defines the x- and y-coordinates of a point on the outline of a TrueType® character.

PrinterDevice Class handles printer devices.

WDragSession Class is an AWT drag-and-drop implementation using the object and dragdrop protocols.

Win32SystemResourceDecoder Class is used to utilize Win32 system resource (.res) files.

WinEvent Class provides a raw API that enables Java objects to use Microsoft® Active Accessibility®.

WPrintGraphics Class encapsulates a print graphics context for a printable page.

WPrintJob Class creates Microsoft® Win32® WPrintJob objects that handle printing.


Interfaces (com.ms.awt Package)

 Microsoft SDK for Java

com.ms.awt Package Interfaces

The com.ms.awt package contains the following interfaces:

HeavyComponent Interface is implemented by Java classes that require a Microsoft® Win32® system window (an HWND) for operations that access the native operating system.


Hierarchy (com.ms.awt Package)

 Microsoft SDK for Java

com.ms.awt Package Hierarchy

The com.ms.awt package has the following hierarchy:

Object
  |
  +--Device
  |  |
  |  +--DisplayDevice
  |  |
  |  +--PrinterDevice
  |
  +--Mat2
  |
  +--PointFx
  |
  +--WinEvent (com.ms.ui.IWinEvent)

Cursor
  |
  +--CursorX

Exception
  |
  +--DeviceException

FocusEvent
  |
  +--FocusEvent

FxFontMetrics
  |
  +--FontMetricsX

FxFont
  |
  +--FontX

FxGraphics
  |
  +--GraphicsX (PeerConstants, PaintSurface)
     |
     +--WPrintGraphics (PrintGraphics)

Image
  |
  +--ImageX

DragHelper
  |
  +--WDragSession (DragSession)

Win32ResourceDecoder
  |
  +--Win32SystemResourceDecoder

PrintJob
  |
  +--WPrintJob

HeavyComponent


CursorX Class (com.ms.awt Package)

 Microsoft SDK for Java

CursorX Class

The CursorX Class of the com.ms.awt package implements an extended cursor object.

public class CursorX extends Cursor
{
  // Constructors
  public CursorX(Image img, int x, int y);

  // Methods
  public int getType();
}

Note For the Microsoft SDK for Java, version 2.02 and later, images must be 32-by-32 pixels to be used successfully with CursorX objects.

Hierarchy

Cursor
  |
  +--CursorX


Constructors (CursorX Class)

 Microsoft SDK for Java

CursorX Class Constructors

The CursorX Class contains the following constructor:

CursorX(Image img, int x, int y)

Creates an extended cursor object with a default type from a specified image.

Syntax

public CursorX(Image img, int x, int y);

Parameters

img | The Image to create the cursor from.
x | The x-coordinate of the point that acts as the cursor's hot spot.
y | The y-coordinate of the point that acts as the cursor's hot spot.


Methods (CursorX Class)

 Microsoft SDK for Java

CursorX Class Methods

The CursorX Class contains the following method:

getType retrieves the current CursorX object's type.


getType (CursorX Class)

 Microsoft SDK for Java

getType

This method of the CursorX Class retrieves the current CursorX object's type.

Syntax

public int getType();

Return Value

Returns the cursor type. All CursorX objects are created with a java.awt.Cursor.DEFAULT_CURSOR type, and will return 0.


Device Class (com.ms.awt Package)

 Microsoft SDK for Java

Device Class

The Device Class of the com.ms.awt package manages information associated with a generic device.

The DisplayDevice and PrinterDevice classes are derived from the Device class.

public class Device
{
  // Fields
  public static final int BLTALIGNMENT;
  public final static int CC_CHORD;
  public final static int CC_CIRCLES;
  public final static int CC_ELLIPSES;
  public final static int CC_INTERIORS;
  public final static int CC_NONE;
  public final static int CC_PIE;
  public final static int CC_ROUNDRECT;
  public final static int CC_STYLED;
  public final static int CC_WIDE;
  public final static int CC_WIDESTYLED;
  public final static int CP_NONE;
  public final static int CP_RECTANGLE;
  public final static int CP_REGION;
  public static final int DESKTOPHORZRES;
  public static final int DESKTOPVERTRES;
  public final static int DT_CHARSTREAM;
  public final static int DT_DISPFILE;
  public final static int DT_METAFILE;
  public final static int DT_PLOTTER;
  public final static int DT_RASCAMERA;
  public final static int DT_RASDISPLAY;
  public final static int DT_RASPRINTER;
  public final static int LC_INTERIORS;
  public final static int LC_MARKER;
  public final static int LC_NONE;
  public final static int LC_POLYLINE;
  public final static int LC_POLYMARKER;
  public final static int LC_STYLED;
  public final static int LC_WIDE;
  public final static int LC_WIDESTYLED;
  public final static int PC_INTERIORS;
  public final static int PC_NONE;
  public final static int PC_PATHS;
  public final static int PC_POLYGON;
  public final static int PC_POLYPOLYGON;
  public final static int PC_RECTANGLE;
  public final static int PC_SCANLINE;
  public final static int PC_STYLED;
  public final static int PC_TRAPEZOID;
  public final static int PC_WIDE;
  public final static int PC_WIDESTYLED;
  public final static int PC_WINDPOLYGON;
  public final static int RC_BANDING;
  public final static int RC_BIGFONT;
  public final static int RC_BITBLT;
  public final static int RC_BITMAP64;
  public final static int RC_DEVBITS;
  public final static int RC_DI_BITMAP;
  public final static int RC_DIBTODEV;
  public final static int RC_FLOODFILL;
  public final static int RC_GDI20_OUTPUT;
  public final static int RC_GDI20_STATE;
  public final static int RC_NONE;
  public final static int RC_OP_DX_OUTPUT;
  public final static int RC_PALETTE;
  public final static int RC_SAVEBITMAP;
  public final static int RC_SCALING;
  public final static int RC_STRETCHBLT;
  public final static int RC_STRETCHDIB;
  public final static int TC_CP_STROKE;
  public final static int TC_CR_90;
  public final static int TC_CR_ANY;
  public final static int TC_EA_DOUBLE;
  public final static int TC_IA_ABLE;
  public final static int TC_OP_CHARACTER;
  public final static int TC_OP_STROKE;
  public final static int TC_RA_ABLE;
  public final static int TC_RESERVED;
  public final static int TC_SA_CONTIN;
  public final static int TC_SA_DOUBLE;
  public final static int TC_SA_INTEGER;
  public final static int TC_SCROLLBLT;
  public final static int TC_SF_X_YINDEP;
  public final static int TC_SO_ABLE;
  public final static int TC_UA_ABLE;
  public final static int TC_VA_ABLE;
  public static final int VREFRESH;

  // Constructors
  protected Device();

  // Methods
  public Dimension getAspectRatio();
  public int getAspectRatioXY();
  public void getBasics(int hdc) throws DeviceException;
  public int getBitsPerPixel();
  public int getClipCapabilities();
  public int getColorResolution();
  public int getCurveCapabilities();
  public final static Device getDeviceFromGraphics(
        Graphics g) throws DeviceException;
  public Dimension getDeviceSize();
  protected int getDisplayContext(Graphics g)
        throws DeviceException;
  public int getDriverVersion();
  public int getLineCapabilities();
  public Dimension getLogicalPixelsPerInch();
  public int getNumberOfBrushes();
  public int getNumberOfColors();
  public int getNumberOfFonts();
  public int getNumberOfMarkers();
  public int getNumberOfPens();
  public int getPaletteReserved();
  public int getPaletteSize();
  public Dimension getPixelRes();
  public int getPlanes();
  public int getPolygonCapabilities();
  public int getRasterCapabilities();
  public int getTechnology();
  public int getTextCapabilities();
}


Constructors (Device Class)

 Microsoft SDK for Java

Device Class Constructors

The Device Class contains the following constructor:

Device()

A constructor for the abstract class.

Syntax

protected Device();


Methods (Device Class)

 Microsoft SDK for Java

Device Class Methods

The Device Class contains the following methods:

getAspectRatio retrieves the device aspect ratio in terms of a Dimension data type.
getAspectRatioXY retrieves the device aspect ratio in terms of an integer.
getBasics retrieves the basic information set (common to all devices types) from the native system.
getBitsPerPixel retrieves the device number of bits per pixel.
getClipCapabilities retrieves the clipping capabilities of the device.
getColorResolution retrieves a device's color resolution.
getCurveCapabilities retrieves the curve capabilities of the device.
getDeviceFromGraphics retrieves a device, given a graphics context.
getDeviceSize retrieves the physical device size as a Dimension.
getDisplayContext retrieves a display context usable on the device.
getDriverVersion retrieves the device driver version number.
getLineCapabilities retrieves the line capabilities of the device.
getLogicalPixelsPerInch retrieves a device's logical pixels per inch.
getNumberOfBrushes retrieves the number of brushes used by the device.
getNumberOfColors retrieves the number of colors used by the device.
getNumberOfFonts retrieves the number of fonts used by the device.
getNumberOfMarkers retrieves the number of markers used by the device.
getNumberOfPens retrieves the number of pens used by the device.
getPaletteReserved retrieves a reserved device palette.
getPaletteSize retrieves a device palette size.
getPixelRes retrieves the device's pixel resolution (in pixels per inch).
getPlanes retrieves the number of planes used by the device.
getPolygonCapabilities retrieves the polygon capabilities of the device.
getRasterCapabilities retrieves the device raster capabilities.
getTechnology retrieves the device technology.
getTextCapabilities retrieves the text capabilities of the device.


getAspectRatio (Device Class)

 Microsoft SDK for Java

getAspectRatio

This method of the Device Class retrieves the device aspect ratio in terms of a Dimension data type.

Syntax

public Dimension getAspectRatio();

Return Value

Returns a Dimension that defines the device aspect ratio.


getAspectRatioXY (Device Class)

 Microsoft SDK for Java

getAspectRatioXY

This method of the Device Class retrieves the device aspect ratio in terms of an integer.

Syntax

public int getAspectRatioXY();

Return Value

Returns an integer that defines the device aspect ratio.


getBasics (Device Class)

 Microsoft SDK for Java

getBasics

This method of the Device Class retrieves the basic information set (common to all devices types) from the native system. The information set includes the driver version, pixel resolution, curve, line, polygon, and raster capabilities, color resolution, logical pixels per inch, and so on.

Syntax

public void getBasics(int hdc) throws DeviceException;

Parameters

hdc The device context.

Exceptions

com.ms.awt.DeviceException


getBitsPerPixel (Device Class)

 Microsoft SDK for Java

getBitsPerPixel

This method of the Device Class retrieves the device number of bits per pixel.

Syntax

public int getBitsPerPixel();

Return Value

Returns the bits per pixel.


getClipCapabilities (Device Class)

 Microsoft SDK for Java

getClipCapabilities

This method of the Device Class retrieves the clipping capabilities of the device.

Syntax

public int getClipCapabilities();

Return Value

Returns one of the clipping capabilities flags as shown in the following table.

CP_NONE CP_RECTANGLE CP_REGION


getColorResolution (Device Class)

 Microsoft SDK for Java

getColorResolution

This method of the Device Class retrieves a device's color resolution.

Syntax

public int getColorResolution();

Return Value

Returns the color resolution.


getCurveCapabilities (Device Class)

 Microsoft SDK for Java

getCurveCapabilities

This method of the Device Class retrieves the curve capabilities of the device.

Syntax

public int getCurveCapabilities();

Return Value

Returns one or a combination of the curve capabilities flags as shown in the following table.

CC_NONE | CC_CIRCLES
CC_PIE | CC_CHORD
CC_ELLIPSES | CC_WIDE
CC_STYLED | CC_WIDESTYLED
CC_INTERIORS | CC_ROUNDRECT


getDeviceFromGraphics (Device Class)

 Microsoft SDK for Java

getDeviceFromGraphics

This method of the Device Class retrieves a device, given a graphics context. The device created is an instance of the DisplayDevice or the PrinterDevice class.

Syntax

public final static Device getDeviceFromGraphics(Graphics g) throws DeviceException;

Parameters

g An extended graphics context, either a com.ms.fx.FxGraphics or a GraphicsX object.

Exceptions

com.ms.awt.DeviceException if the graphics context is not valid.


getDeviceSize (Device Class)

 Microsoft SDK for Java

getDeviceSize

This method of the Device Class retrieves the physical device size as a Dimension.

Syntax

public Dimension getDeviceSize();

Return Value

Returns a Dimension that defines the physical size of the device.


getDisplayContext (Device Class)

 Microsoft SDK for Java

getDisplayContext

This method of the Device Class retrieves a display context usable on the device. If the display device is something other than a monitor (a printer, for example), the device context is obtained from the native peer object.

Syntax

protected int getDisplayContext(Graphics g) throws DeviceException;

Return Value

Returns zero if the device is the screen; otherwise, returns the handle of the device context.

Parameters

g The Graphics object to get the context for.

Exceptions

com.ms.awt.DeviceException if the graphics context is not an instance of the com.ms.fx.FxGraphics or GraphicsX graphics classes.


getDriverVersion (Device Class)

 Microsoft SDK for Java

getDriverVersion

This method of the Device Class retrieves the device driver version number.

Syntax

public int getDriverVersion();

Return Value

Returns the driver version.


getLineCapabilities (Device Class)

 Microsoft SDK for Java

getLineCapabilities

This method of the Device Class retrieves the line capabilities of the device.

Syntax

public int getLineCapabilities();

Return Value

Returns one or a combination of the line capabilities flags as shown in the following table.

LC_NONE | LC_POLYLINE
LC_MARKER | LC_POLYMARKER
LC_WIDE | LC_STYLED
LC_WIDESTYLED | LC_INTERIORS


getLogicalPixelsPerInch (Device Class)

 Microsoft SDK for Java

getLogicalPixelsPerInch

This method of the Device Class retrieves a device's logical pixels per inch.

Syntax

public Dimension getLogicalPixelsPerInch();

Return Value

Returns a device's logical pixels per inch.


getNumberOfBrushes (Device Class)

 Microsoft SDK for Java

getNumberOfBrushes

This method of the Device Class retrieves the number of brushes used by the device.

Syntax

public int getNumberOfBrushes();

Return Value

Returns the number of brushes.


getNumberOfColors (Device Class)

 Microsoft SDK for Java

getNumberOfColors

This method of the Device Class retrieves the number of colors used by the device.

Syntax

public int getNumberOfColors();

Return Value

Returns the number of colors.


getNumberOfFonts (Device Class)

 Microsoft SDK for Java

getNumberOfFonts

This method of the Device Class retrieves the number of fonts used by the device.

Syntax

public int getNumberOfFonts();

Return Value

Returns the number of fonts.


getNumberOfMarkers (Device Class)

 Microsoft SDK for Java

getNumberOfMarkers

This method of the Device Class retrieves the number of markers used by the device.

Syntax

public int getNumberOfMarkers();

Return Value

Returns the number of markers.


getNumberOfPens (Device Class)

 Microsoft SDK for Java

getNumberOfPens

This method of the Device Class retrieves the number of pens used by the device.

Syntax

public int getNumberOfPens();

Return Value

Returns the number of pens.


getPaletteReserved (Device Class)

 Microsoft SDK for Java

getPaletteReserved

This method of the Device Class retrieves a reserved device palette.

Syntax

public int getPaletteReserved();

Return Value

Returns the reserved palette.


getPaletteSize (Device Class)

 Microsoft SDK for Java

getPaletteSize

This method of the Device Class retrieves a device palette size.

Syntax

public int getPaletteSize();

Return Value

Returns the size of the palette.


getPixelRes (Device Class)

 Microsoft SDK for Java

getPixelRes

This method of the Device Class retrieves the device's pixel resolution (in pixels per inch).

Syntax

public Dimension getPixelRes();

Return Value

Returns the pixel resolution.


getPlanes (Device Class)

 Microsoft SDK for Java

getPlanes

This method of the Device Class retrieves the number of planes used by the device.

Syntax

public int getPlanes();

Return Value

Returns the number of planes.


getPolygonCapabilities (Device Class)

 Microsoft SDK for Java

getPolygonCapabilities

This method of the Device Class retrieves the polygon capabilities of the device.

Syntax

public int getPolygonCapabilities();

Return Value

Returns one or a combination of the polygon capabilities flags shown in the following table.

PC_NONE | PC_POLYGON
PC_RECTANGLE | PC_WINDPOLYGON
PC_TRAPEZOID | PC_SCANLINE
PC_WIDE | PC_STYLED
PC_WIDESTYLED | PC_INTERIORS
PC_POLYPOLYGON | PC_PATHS


getRasterCapabilities (Device Class)

 Microsoft SDK for Java

getRasterCapabilities

This method of the Device Class retrieves the device raster capabilities.

Syntax

public int getRasterCapabilities();

Return Value

Returns one or a combination of the raster capabilities flags shown in the following table.

RC_NONE | RC_BITBLT
RC_BANDING | RC_SCALING
RC_BITMAP64 | RC_GDI20_OUTPUT
RC_GDI20_STATE | RC_SAVEBITMAP
RC_DI_BITMAP | RC_PALETTE
RC_DIBTODEV | RC_BIGFONT
RC_STRETCHBLT | RC_FLOODFILL
RC_STRETCHDIB | RC_OP_DX_OUTPUT
RC_DEVBITS |


getTechnology (Device Class)

 Microsoft SDK for Java

getTechnology

This method of the Device Class retrieves the device technology.

Syntax

public int getTechnology();

Return Value

Returns one of the device technology flags shown in the following table.

DT_PLOTTER | DT_RASDISPLAY
DT_RASPRINTER | DT_RASCAMERA
DT_CHARSTREAM | DT_METAFILE
DT_DISPFILE |


getTextCapabilities (Device Class)

 Microsoft SDK for Java

getTextCapabilities

This method of the Device Class retrieves the text capabilities of the device.

Syntax

public int getTextCapabilities();

Return Value

Returns one or a combination of the text capabilities flags shown in the following table.

TC_OP_CHARACTER | TC_CP_STROKE
TC_OP_STROKE | TC_RESERVED
TC_CR_ANY | TC_CR_90
TC_SF_X_YINDEP | TC_SA_DOUBLE
TC_SA_CONTIN | TC_SA_INTEGER
TC_EA_DOUBLE | TC_IA_ABLE
TC_SO_ABLE | TC_UA_ABLE
TC_RA_ABLE | TC_VA_ABLE
TC_SCROLLBLT |


Fields (Device Class)

 Microsoft SDK for Java

Device Class Fields

The Device Class contains the fields shown in the following table.

BLTALIGNMENT | The preferred blit alignment.
CC_CHORD | A curve capabilities flag that indicates chord arcs are supported.
CC_CIRCLES | A curve capabilities flag that indicates circles are supported.
CC_ELLIPSES | A curve capabilities flag that indicates ellipses are supported.
CC_INTERIORS | A curve capabilities flag that indicates interiors are supported.
CC_NONE | A curve capabilities flag that indicates curves are not supported.
CC_PIE | A curve capabilities flag that indicates pie wedge shapes are supported.
CC_ROUNDRECT | A curve capabilities flag that indicates rounded rectangles are supported.
CC_STYLED | A curve capabilities flag that indicates styled lines are supported.
CC_WIDE | A curve capabilities flag that indicates wide lines are supported.
CC_WIDESTYLED | A curve capabilities flag that indicates wide styled lines are supported.
CP_NONE | A clipping capabilities flag that indicates clipping of output is not supported.
CP_RECTANGLE | A clipping capabilities flag that indicates output is clipped to rectangles.
CP_REGION | A clipping capabilities flag that indicates output is clipped to Region.
DESKTOPHORZRES | The desktop's horizontal resolution.
DESKTOPVERTRES | The desktop's vertical resolution.
DT_CHARSTREAM | The device technology flag for a character stream.
DT_DISPFILE | The device technology flag for a display file.
DT_METAFILE | The device technology flag for a metafile.
DT_PLOTTER | The device technology flag for a vector plotter (typically used in CAD).
DT_RASCAMERA | The device technology flag for a raster camera.
DT_RASDISPLAY | The device technology flag for a raster display.
DT_RASPRINTER | The device technology flag for a raster printer.
LC_INTERIORS | A line capabilities flag that indicates interiors are supported.
LC_MARKER | A line capabilities flag that indicates marker lines are supported.
LC_NONE | A line capabilities flag that indicates lines are not supported.
LC_POLYLINE | A line capabilities flag that indicates polylines are supported.
LC_POLYMARKER | A line capabilities flag that indicates polylinemarkers are supported.
LC_STYLED | A line capabilities flag that indicates styled lines are supported.
LC_WIDE | A line capabilities flag that indicates wide lines are supported.
LC_WIDESTYLED | A line capabilities flag that indicates wide styled lines are supported.
PC_INTERIORS | A polygonal capabilities flag that indicates interiors are supported.
PC_NONE | A polygonal capabilities flag that indicates polygonals are not supported.
PC_PATHS | A polygonal capabilities flag that indicates paths are supported.
PC_POLYGON | A polygonal capabilities flag that indicates polygons are supported.
PC_POLYPOLYGON | A polygonal capabilities flag that indicates poly-polygons are supported.
PC_RECTANGLE | A polygonal capabilities flag that indicates rectangles are supported.
PC_SCANLINE | A polygonal capabilities flag that indicates scan lines are supported.
PC_STYLED | A polygonal capabilities flag that indicates styled borders are supported.
PC_TRAPEZOID | A polygonal capabilities flag that indicates trapezoids are supported.
PC_WIDE | A polygonal capabilities flag that indicates wide borders are supported.
PC_WIDESTYLED | A polygonal capabilities flag that indicates wide styled borders are supported.
PC_WINDPOLYGON | A polygonal capabilities flag that indicates winding polygonals are supported.
RC_BANDING | A raster capabilities flag that indicates the device requires banding support.
RC_BIGFONT | A raster capabilities flag that indicates the device supports fonts greater than 64K.
RC_BITBLT | A raster capabilities flag that indicates the device can transfer bitmaps.
RC_BITMAP64 | A raster capabilities flag that indicates the device can support bitmaps larger than 64K.
RC_DEVBITS | A raster capabilities flag that indicates the device supports device bitmaps.
RC_DI_BITMAP | A raster capabilities flag that indicates the device supports setDIBits and getDIBits Windows functions.
RC_DIBTODEV | A raster capabilities flag that indicates the device supports the SetDIBitsToDevice and getDIBitsToDevice Windows function.
RC_FLOODFILL | A raster capabilities flag that indicates the device supports flood fill operations.
RC_GDI20_OUTPUT | A raster capabilities flag that indicates the device supports Windows version 2.0 features.
RC_GDI20_STATE | A raster capabilities flag that indicates the device includes a state block in the device context.
RC_NONE | A raster capabilities flag that indicates the device has no raster capabilities.
RC_OP_DX_OUTPUT | A raster capabilities flag that indicates the device supports device opaque and dx arrays.
RC_PALETTE | A raster capabilities flag that specifies a palette-based device.
RC_SAVEBITMAP | A raster capabilities flag that indicates the device can save bitmaps locally.
RC_SCALING | A raster capabilities flag that indicates the device supports scaling.
RC_STRETCHBLT | A raster capabilities flag that indicates the device supports StretchBlt operations.
RC_STRETCHDIB | A raster capabilities flag that indicates the device supports the StretchDIBits Windows function.
TC_CP_STROKE | A text capabilities flag that indicates the device can clip device fonts to a pixel boundary.
TC_CR_90 | A text capabilities flag that indicates 90-degree character rotation is supported. Fonts are rotated only 90 degrees at a time.
TC_CR_ANY | A text capabilities flag that indicates any degree character rotation is supported.
TC_EA_DOUBLE | A text capabilities flag that indicates the device can make device fonts bold. If this bit is not set for printer drivers, the GDI (graphics device interface) attempts to create bold device fonts by printing them twice.
TC_IA_ABLE | A text capabilities flag that indicates the device can make device fonts italic. If this bit is not set, the GDI assumes that italics are not available.
TC_OP_CHARACTER | A text capabilities flag that indicates the device can place device fonts at any pixel location. This is required for any device with device fonts.
TC_OP_STROKE | A text capabilities flag that indicates the device can omit any stroke of a device font.
TC_RA_ABLE | A text capabilities flag that indicates that the GDI should enumerate any raster or TrueType® fonts that are available for this device in response to a call to the EnumFonts or EnumFontFamilies Microsoft® Windows® functions. If this bit is not set, GDI-supplied raster or TrueType® fonts are not enumerated when these functions are called.
TC_RESERVED | A reserved text capabilities flag.
TC_SA_CONTIN | A text capabilities flag that indicates the device can scale device fonts by any amount, but still preserve the x and y ratios.
TC_SA_DOUBLE | A text capabilities flag that indicates can double the size of device fonts.
TC_SA_INTEGER | A text capabilities flag that the device can scale device fonts in any integer multiple.
TC_SCROLLBLT | A text capabilities flag that indicates text scrolling is not performed with blitting operations.
TC_SF_X_YINDEP | A text capabilities flag that indicates the device can scale device fonts separately in x and y directions.
TC_SO_ABLE | A text capabilities flag that indicates the device can strikeout device fonts. If this bit is not set, GDI creates strikethroughs for device fonts.
TC_UA_ABLE | A text capabilities flag that indicates the device can underline device fonts. If this bit is not set, the GDI creates underlines for device fonts.
TC_VA_ABLE | A text capabilities flag that indicates that GDI should enumerate any vector fonts available for this device in response to a call to the EnumFonts or EnumFontFamilies Windows functions. This is significant for vector devices only (that is, for plotters). Display drivers (which must be able to use raster fonts) and raster printer drivers always enumerate vector fonts, because GDI rasterizes vector fonts before sending them to the driver.
VREFRESH | The current vertical refresh rate of the display device.


DeviceException Class (com.ms.awt Package)

 Microsoft SDK for Java

DeviceException Class

The DeviceException Class of the com.ms.awt package signals that a com.ms.awt.Device-related exception has occurred.

public class DeviceException extends Exception
{
  // Constructors
  public DeviceException(String msg);
}

Hierarchy

Exception
  |
  +--DeviceException


Constructors (DeviceException Class)

 Microsoft SDK for Java

DeviceException Class Constructors

The DeviceException Class contains the following constructor:

DeviceException(String msg)

Creates a DeviceException object with a String that describes the exception in detail.

Syntax

public DeviceException(String msg);

Parameters

msg The detailed message.


DisplayDevice Class (com.ms.awt Package)

 Microsoft SDK for Java

DisplayDevice Class

The DisplayDevice Class of the com.ms.awt package handles display devices.

public class DisplayDevice extends Device
{
  // Constructors
  public DisplayDevice(Graphics g) throws DeviceException;

  // Methods
  public int getBltAlignment();
  public Dimension getDesktopResolution();
  public int getVerticalRefresh();
}

Hierarchy

Device
  |
  +--DisplayDevice


Constructors (DisplayDevice Class)

 Microsoft SDK for Java

DisplayDevice Class Constructors

The DisplayDevice Class contains the following constructor:

DisplayDevice(Graphics g)

Creates a display device object.

Syntax

public DisplayDevice(Graphics g) throws DeviceException;

Parameters

g The graphics object that the device is created for.

Exceptions

com.ms.awt.DeviceException if the graphics object is not an instance of the com.ms.fx.FxGraphics or the GraphicsX class.


Methods (Display DeviceClass)

 Microsoft SDK for Java

DisplayDevice Class Methods

The DisplayDevice Class contains the following methods:

getBltAlignment retrieves the blit alignment.
getDesktopResolution retrieves the display device desktop resolution.
getVerticalRefresh retrieves the device vertical refresh rate.


getBltAlignment (Display DeviceClass)

 Microsoft SDK for Java

getBltAlignment

This method of the DisplayDevice Class retrieves the blit alignment.

Syntax

public int getBltAlignment();

Return Value

Returns the blit alignment.


getDesktopResolution (Display DeviceClass)

 Microsoft SDK for Java

getDesktopResolution

This method of the DisplayDevice Class retrieves the display device desktop resolution.

Syntax

public Dimension getDesktopResolution();

Return Value

Returns the dimensions of the desktop resolution. This is commonly one of the resolutions shown in the following table.

480 x 640
600 x 800
768 x 1024
864 x 1152
1024 x 1280


getVerticalRefresh (Display DeviceClass)

 Microsoft SDK for Java

getVerticalRefresh

This method of the DisplayDevice Class retrieves the device vertical refresh rate.

Syntax

public int getVerticalRefresh();

Return Value

Returns the vertical refresh rate (in MHz).


FocusEvent Class (com.ms.awt Package)

 Microsoft SDK for Java

FocusEvent Class

The FocusEvent Class of the com.ms.awt package manages component-level focus events. This class is similar to the java.awt.event.FocusEvent class, except that it also incorporates the target component of a component focus event.

public class FocusEvent extends java.awt.event.FocusEvent
{
  // Constructors
  public FocusEvent(Component source, int id, Component other,
        boolean temporary);
  public FocusEvent(Component source, int id, Component other);

  // Methods
  public Component getOtherComponent();
  public String paramString();
}

Hierarchy

FocusEvent
  |
  +--FocusEvent


Constructors (FocusEvent Class)

 Microsoft SDK for Java

FocusEvent Class Constructors

The FocusEvent Class contains the following constructors:

FocusEvent(Component source, int id, Component other,boolean temporary)
FocusEvent(Component source, int id, Component other)

FocusEvent(Component source, int id, Component other,boolean temporary)

Creates a FocusEvent object by using the component that received the focus, the component that lost focus, the identifier of the focus event, and whether the focus event is temporary or permanent.

Syntax

public FocusEvent(Component source, int id, Component other, boolean temporary);

Parameters

source | The component that generates the event.
other | The target component.
id | The identifier of the focus event. This may be either FOCUS_LOST or FOCUS_GAINED. If the identifier is FOCUS_GAINED, the other component is the component that loses focus. If the identifier is FOCUS_LOST, the other component is the component that gains focus. However, if the application is currently gaining or losing focus, the identifier may be null.
temporary | Set to true if the focus change is a temporary one. Set to false if the focus change is a permanent one.

FocusEvent(Component source, int id, Component other)

Creates a FocusEvent object by using the component that received the focus, the component that lost focus, and the identifier of the focus event. A FocusEvent created with this constructor is permanent (by default).

Syntax

public FocusEvent(Component source, int id, Component other);

Parameters

source | The component that generates the event.
other | The target component.
id | The identifier of the focus event. This may be either FOCUS_LOST or FOCUS_GAINED. If the identifier is FOCUS_GAINED, the other component is the component that loses focus. If the identifier is FOCUS_LOST, the other component is the component that gains focus. However, if the application is currently gaining or losing focus, the identifier may be null.


Methods (FocusEvent Class)

 Microsoft SDK for Java

FocusEvent Class Methods

The FocusEvent Class contains the following methods:

getOtherComponent retrieves the target component involved in the focus shift.
paramString describes the focus event.


getOtherComponent (FocusEvent Class)

 Microsoft SDK for Java

getOtherComponent

This method of the FocusEvent Class retrieves the target component involved in the focus shift.

Syntax

public Component getOtherComponent();

Return Value

Returns the other component involved in the focus change (if any).


paramString (FocusEvent Class)

 Microsoft SDK for Java

paramString

This method of the FocusEvent Class describes the focus event.

Syntax

public String paramString();

Return Value

Returns a string that describes the focus event ("FOCUS_LOST other= other", for example).


FontMetricsX Class (com.ms.awt Package)

 Microsoft SDK for Java

FontMetricsX Class

The FontMetricsX Class of the com.ms.awt package provides an extended font metrics implementation specific to the Microsoft virtual machine (Microsoft VM). For more information on the methods in this class, see the com.ms.fx.FxFontMetrics class in the Microsoft SDK for AFC.

public class FontMetricsX extends FxFontMetrics
{
}

Hierarchy

FxFontMetrix
  |
  +--FontMetricsX


FontX Class (com.ms.awt Package)

 Microsoft SDK for Java

FontX Class

The FontX Class of the com.ms.awt package creates a font object that defines the font family, font face, style, and size. The FontX class also supports TrueType® fonts.

public class FontX extends FxFont
{
  // Fields
  public static final int EMBEDDED;
  public static final int OUTLINE;
  public static final int STRIKEOUT;
  public static final int UNDERLINE;

  // Constructors
  public FontX();
  public FontX(String name, int style, int size);
  public FontX(String name, int style, int size, boolean bEmbed);
  public FontX(String name, int style, int size, int xFlags);

  // Methods
  public boolean equals(Object obj);
  public static String[] getAttributeList();
  public static String[] getAttributeList(String face);
  public int getFlags();
  public static int getFlagsVal(String face, String attribute);
  public static Font getFont(String face, int style, int size, int flags);
  public static Font getFont(String face, Vector v, int size);
  public static String[] getFontList();
  public static int getStyleVal(String face, String attribute);
  public boolean isTypeable(int language);
  public static boolean matchFace(String face);
  public String toString();
}

With JDK 1.1, fonts are mapped with a font properties file, and you can obtain different fonts by editing this file. However, the Microsoft implementation does not support this type of font association. You can obtain desired fonts with FontX objects; they are created with Win32 font names.

Hierarchy

FxFont
  |
  +--FontX


Constructors (FontX Class)

 Microsoft SDK for Java

FontX Class Constructors

The FontX Class contains the following constructors:

FontX()
FontX(String name, int style, int size)
FontX(String name, int style, int size, boolean bEmbed)
FontX(String name, int style, int size, int xFlags)

FontX()

Creates a nondescript font (12-point Dialog).

Syntax

public FontX();

FontX(String name, int style, int size)

Creates a new font with the specified name, style, and point size. This constructor is used to access system fonts on the Microsoft® Win32® platform not otherwise available in Java (for example, the "symbol" font).

Syntax

public FontX(String name, int style, int size);

Parameters

name | The name of the font face.
style | The font style, which can be a combination of BOLD, ITALIC, and PLAIN.
size | The point size of the font.

FontX(String name, int style, int size, boolean bEmbed)

Creates a new font with the specified name, style, and point size; specifies whether the font is embedded.

Syntax

public FontX(String name, int style, int size, boolean bEmbed);

Parameters

name | The name of the font face.
style | The font style, which can be a combination of BOLD, ITALIC, and PLAIN.
size | The point size of the font.
bEmbed | Set to true if the font is embedded, false otherwise.

FontX(String name, int style, int size, int xFlags)

Creates an extended font.

Syntax

public FontX(String name, int style, int size, int xFlags);

Parameters

name | The name of the font face.
style | The font style, which can be a combination of BOLD, ITALIC, and PLAIN.
size | The point size of the font.
xFlags | An extended style, which can be one of the following values: EMBEDDED UNDERLINE STRIKEOUT OUTLINE


Methods (FontX Class)

 Microsoft SDK for Java

FontX Class Methods

The FontX Class contains the following methods:

equals checks that the argument is not null (is either a font or a FontX object) and has the same name, same style, and same point size as this FontX object.
getAttributeList retrieves a list of the attributes that the current font supports.
getFlags retrieves the extended flags of a FontX object.
getFlagsVal retrieves a value for the flags associated with the given face.
getFont retrieves a font if an exact match is made, given the font face, style, size, and any specified flags.
getFontList retrieves a list of the names of the font faces available.
getStyleVal retrieves a value for the style associated with the given face.
isTypeable checks whether the font can be typed in the given language.
matchFace compares the current font face to the specified face.
toString returns a string that specifies the family, font face, style, and size of the given font.


equals (FontX Class)

 Microsoft SDK for Java

equals

This method of the FontX Class checks that the argument is not null (is either a Font or a FontX object) and has the same name, same style, and same point size as this FontX object.

Syntax

public boolean equals(Object obj);

Return Value

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

Parameters

obj The object to be compared with the FontX object.


getAttributeList (FontX Class)

 Microsoft SDK for Java

getAttributeList

The getAttributeList method of the FontX Class contains the following signatures:

getAttributeList()
getAttributeList(String face)

getAttributeList()

Retrieves a list of the attributes that the current font supports.

Syntax

public static String[] getAttributeList();

Return Value

Returns an array of strings describing the attributes the font supports.

getAttributeList(String face)

Retrieves a list of the attributes this font supports, given the font face.

Syntax

public static String[] getAttributeList(String face);

Return Value

Returns an array of strings describing the attributes the font supports.

Parameters

face The current font face.


getFlags (FontX Class)

 Microsoft SDK for Java

getFlags

This method of the FontX Class retrieves the extended flags of a FontX object.

Syntax

public int getFlags();

Return Value

Returns a one or a combination of these extended styles: EMBEDDED, STRIKEOUT, UNDERLINE, and OUTLINE.


getFlagsVal (FontX Class)

 Microsoft SDK for Java

getFlagsVal

This method of the FontX Class retrieves a value for the flags associated with the given face.

Syntax

public static int getFlagsVal(String face, String attribute);

Return Value

Returns a value for the face name flags.

Parameters

face | The current font face.
attribute | A string that contains the attributes (for example, "Rotatable") of the font.


getFont (FontX Class)

 Microsoft SDK for Java

getFont

The getFont method of the FontX Class contains the following signatures:

getFont(String face, int style, int size, int flags)
getFont(String face, Vector v, int size)

getFont(String face, int style, int size, int flags)

Retrieves a font if an exact match is made, given the font face, style, size, and any specified flags.

Syntax

public static Font getFont(String face, int style, int size, int flags);

Return Value

Returns the Font that is the exact match to the given parameters.

Parameters

face | The font face.
style | The font style.
size | The font size, in points.
flags | One or more of the following font flags: EMBEDDED STRIKEOUT UNDERLINE OUTLINE

getFont(String face, Vector v, int size)

Retrieves a font if an exact match is made, given the font face, vector, and size.

Syntax

public static Font getFont(String face, Vector v, int size);

Return Value

Returns the Font that is the exact match to the given parameters.

Parameters

face | The font face.
v | A list of style names.
size | The font size, in points.


getFontList (FontX Class)

 Microsoft SDK for Java

getFontList

This method of the FontX Class retrieves a list of the names of the font faces available.

Syntax

public static String[] getFontList();

Return Value

Returns a string array containing the names of available font faces.


getStyleVal (FontX Class)

 Microsoft SDK for Java

getStyleVal

This method of the FontX Class retrieves a value for the style associated with the given face.

Syntax

public static int getStyleVal(String face, String attribute);

Return Value

Returns a value for the face name style.

Parameters

face | The current font face.
attribute | A string that contains the attributes of the font (for example, "Rotatable").


isTypeable (FontX Class)

 Microsoft SDK for Java

isTypeable

This method of the FontX Class checks whether the font can be typed in the given language.

Syntax

public boolean isTypeable(int language);

Return Value

Returns true if the font can be typed; otherwise, returns false.

Parameters

language The identifier of the language to be checked.


matchFace (FontX Class)

 Microsoft SDK for Java

matchFace

This method of the FontX Class compares the current font face to the specified face.

Syntax

public static boolean matchFace(String face);

Return Value

Returns true if the current face is the same as the specified face; otherwise, returns false.

Parameters

face The name of the font face to compare to the current font face.


toString (FontX Class)

 Microsoft SDK for Java

toString

This method of the FontX Class returns a string that specifies the family, font face, style, and size of the given font.

Syntax

public String toString();

Return Value

Returns a string having the following format:

class[family=family-name,name=font-name,style=bold/italic,size=size]


Fields (FontX Class)

 Microsoft SDK for Java

FontX Class Fields

The FontX Class contains the following fields.

EMBEDDED | Indicates the new font should be linked to a privately embedded font. Note This is only significant for fonts that are loaded by non-Java objects. Fonts that are loaded by Java objects are automatically embedded.
OUTLINE | Indicates that the text drawn by using the new font should be drawn by using the outline of the glyph. This is only supported by certain fonts in the system, and only GraphicsX will support this feature. Trying to draw outline fonts using a Win32Graphics object will result in the glyph being drawn normally.
STRIKEOUT | Indicates that text drawn using the new font should be struckthrough.
UNDERLINE | Indicates that text drawn using the new font should be underlined.


GraphicsX Class (com.ms.awt Package)

 Microsoft SDK for Java

GraphicsX Class

The GraphicsX Class of the com.ms.awt package provides a graphics implementation specifically for the Microsoft VM. This class is not used directly in applets or applications, and is not cross-platform.

public class GraphicsX extends FxGraphics implements
            PeerConstants, PaintSurface
{
  // Constructors
  public GraphicsX(int hdc);

  // Methods
  public void drawCharsWithoutFxFont(char data[], int offset,
        int length, int x, int y, Rectangle optionRect,
        int options, int dx[], int dy[]);
  public void drawNativeEdge(int X, int Y, int W, int H, int edges, int flags);
  public void drawNativeFocusRect(int X, int Y, int W, int H, Color bkColor)
  public void drawOutlinePolygon(int xOrig, int yOrig,
        OutlinePolygon op);
  public void drawPixels(int[] pels, int len);
  public void drawScanLines(boolean xChanging, int[] points,
        int offset, int nPoints);
  public void drawStringWithoutFxFont(String str,int x, int y,
        Rectangle optionRect, int options, int[] dx,int[] dy);
  public Device getDevice() throws DeviceException;
  public int gethdc();
  public Point getTranslation();
  public void setTextBackgroundColor(Color c);
}

The GraphicsX methods are implemented only for the Microsoft virtual machine. All other graphics methods are defined in the com.ms.fx.FxGraphics class and the java.awt.Graphics class.

Hierarchy

FxGraphics
  |
  +--GraphicsX


Constructors (GraphicsX Class)

 Microsoft SDK for Java

GraphicsX Class Constructors

The GraphicsX Class contains the following constructor:

GraphicsX(int hdc)

Creates a graphics object for a user-supplied display context.

Syntax

public GraphicsX(int hdc);

Parameters

hdc The display context to create the graphics object for.


Methods (GraphicsX Class)

 Microsoft SDK for Java

GraphicsX Class Methods

The GraphicsX Class contains the following methods:

drawCharsWithoutFxFont uses a native peer graphics object to draw the given character array using the supplied advancement lists.
drawNativeEdge draws one or more edges of rectangle.
drawNativeFocusRect draws a focus rectangle that indicates that a specified control has the input focus.
drawOutlinePolygon draws an outline polygon.
drawPixels draws a given list of pixels.
drawScanLines draws fast lines, either horizontally or vertically.
drawStringWithoutFxFont uses a native peer graphics object to draw the given string using the supplied advancement lists.
getDevice retrieves an an instance of a device class that the graphics object draws on.
gethdc retrieves the Win32 display context handle.
getTranslation retrieves the origin Point used in a translate operation on a graphics context, after the translation is complete.
setTextBackgroundColor sets the text background color.


drawCharsWithoutFxFont (GraphicsX Class)

 Microsoft SDK for Java

drawCharsWithoutFxFont

This method of the GraphicsX Class uses a native peer graphics object to draw the given character array using the supplied advancement lists. This method is used by a com.ms.fx.FxFont object if it needs to be able to draw and then process a character array.

Syntax

public void drawCharsWithoutFxFont(char data[], int offset, int length, int x, int y, Rectangle optionRect, int options, int dx[], intdy[]);

Parameters

str | The string to draw.
x | The x-coordinate of the point where the string is drawn.
y | The y-coordinate of the point where the string is drawn.
optionRect | The optional rectangle used for clipping and opaquing.
options | The options for this method.
dx | An array of destination x values.
dy | An array of destination y values.

See Also

com.ms.fx.FxGraphics (Microsoft SDK for AFC)


drawOutlinePolygon (GraphicsX Class)

 Microsoft SDK for Java

drawOutlinePolygon

This method of the GraphicsX Class draws an outline polygon.

Syntax

public void drawOutlinePolygon(int xOrig, int yOrig, OutlinePolygon op);

Parameters

xOrig | The horizontal starting point for the shape.
yOrig | The vertical starting point for the shape.
op | The OutlinePolygon to draw.

See Also

com.ms.fx.OutlinePolygon (Microsoft SDK for AFC)


drawPixels (GraphicsX Class)

 Microsoft SDK for Java

drawPixels

This method of the GraphicsX Class draws a given list of pixels.

Syntax

public void drawPixels(int[] pels, int len);

Parameters

pels | An array of pixels.
len | The length of the array.


drawScanLines (GraphicsX Class)

 Microsoft SDK for Java

drawScanLines

This method of the GraphicsX Class draws fast lines, either horizontally or vertically.

Syntax

public void drawScanLines(boolean xChanging, int[] points, int offset, int nPoints);

Parameters

xChanging | The direction that the line is drawn, either vertically or horizontally.
points | An array of points.
offset | The offset to use.
nPoints | The number of points in the array.


drawStringWithoutFxFont (GraphicsX Class)

 Microsoft SDK for Java

drawStringWithoutFxFont

This method of the GraphicsX Class uses a native peer graphics object to draw the given string using the supplied advancement lists. This method is used by a com.ms.fx.FxFont object if it needs to be able to draw and then process a string.

Syntax

public void drawStringWithoutFxFont(String str,int x, int y, Rectangle optionRect, int options, int[] dx,int[] dy);

Parameters

str | The string to draw.
x | The x-coordinate of the point where the string is drawn.
y | The y-coordinate of the point where the string is drawn.
optionRect | The optional rectangle used for clipping and opaquing.
options | The options for this method.
dx | An array of destination x values.
dy | An array of destination y values.

See Also

com.ms.fx.FxGraphics (Microsoft SDK for AFC)


getDevice (GraphicsX Class)

 Microsoft SDK for Java

getDevice

This method of the GraphicsX Class retrieves an an instance of a device class that the graphics object draws on.

Syntax

public Device getDevice() throws DeviceException;

Return Value

Returns an instance of the either the DisplayDevice or the PrinterDevice class.

Exceptions

com.ms.awt.DeviceException


gethdc (GraphicsX Class)

 Microsoft SDK for Java

gethdc

This method of the GraphicsX Class retrieves the Win32 display context handle. This is useful when the graphics object is used with a Microsoft® DirectDraw® surface, printer or Microsoft® ActiveX® object (graphics objects created for components do not have consistent HDC values).

Syntax

public int gethdc();

Return Value

Returns the Win32 display context handle.


getTranslation (GraphicsX Class)

 Microsoft SDK for Java

getTranslation

This method of the GraphicsX Class retrieves the origin Point used in a translate operation on a graphics context, after the translation is complete.

Syntax

public Point getTranslation();

Return Value

Returns the origin for the translation.


setTextBackgroundColor (GraphicsX Class)

 Microsoft SDK for Java

setTextBackgroundColor

This method of the GraphicsX Class sets the text background color. This is used for opaquing text.

Syntax

public void setTextBackgroundColor(Color c);

Parameters

c The Color to set the text background to.


ImageX Class (com.ms.awt Package)

 Microsoft SDK for Java

ImageX Class

The ImageX Class of the com.ms.awt package encapsulates an extended image object.

public class ImageX extends com.ms.awt.image.Image
{
  // Constructors
  public ImageX(Component c, int w, int h);
  public ImageX(ImageProducer producer);

  // Methods
  public int getCursor(int x, int y);
  public Graphics getGraphics();
  public int getIcon();
}

This class provides the getCursor and getIcon methods, which retrieve Win32 images for cursors and icons, respectively.

Hierarchy

Image
  |
  +--ImageX


Constructors (ImageX Class)

 Microsoft SDK for Java

ImageX Class Constructors

The ImageX Class contains the following constructors:

ImageX(Component c, int w, int h)
ImageX(ImageProducer producer)

ImageX(Component c, int w, int h)

Creates an image for offscreen rendering to be used with the specified Component.

Syntax

public ImageX(Component c, int w, int h);

Parameters

c | The Component that uses the image.
w | The width of the image (in pixels).
h | The height of the image (in pixels).

ImageX(ImageProducer producer)

Creates an image from an ImageProducer object.

Syntax

public ImageX(ImageProducer producer);

Parameters

producer The ImageProducer object to create the image for.


Methods (ImageX Class)

 Microsoft SDK for Java

ImageX Class Methods

The ImageX Class contains the following methods:

getCursor retrieves an ImageRepresentation of a native Win32 cursor based on the current ImageX object.
getGraphics creates a graphics context for drawing to an off-screen image.
getIcon retrieves an ImageRepresentation of a native Win32 icon based on the current ImageX object.


getCursor (ImageX Class)

 Microsoft SDK for Java

getCursor

This method of the ImageX Class retrieves an ImageRepresentation of a native Win32 cursor based on the current ImageX object.

Syntax

public int getCursor(int x, int y);

Return Value

Returns the handle of a native cursor.

Parameters

x | The x-coordinate of the cursor's hot spot.
y | The y-coordinate of the cursor's hot spot.


getGraphics (ImageX Class)

 Microsoft SDK for Java

getGraphics

This method of the ImageX Class creates a graphics context for drawing to an off-screen image.

Syntax

public Graphics getGraphics();

Return Value

Returns a Graphics object.


getIcon (ImageX Class)

 Microsoft SDK for Java

getIcon

This method of the ImageX Class retrieves an ImageRepresentation of a native Win32 icon based on the current ImageX object.

Syntax

public int getIcon();

Return Value

Returns the handle of a native icon.


Mat2 Class (com.ms.awt Package)

 Microsoft SDK for Java

Mat2 Class

The Mat2 Class of the com.ms.awt package defines a transformation matrix that can be used with outline font methods.

public class Mat2
{
  // Fields
  public float em11;
  public float em12;
  public float em21;
  public float em22;
}

The identity matrix produces a transformation, in which the transformed graphical object is identical to the source object. In the identity matrix, the value of em11 and em22 is 1. The value of em12 and em21 is 0.


Fields (Mat2 Class)

 Microsoft SDK for Java

Mat2 Class Fields

The Mat2 Class contains the following fields.

em11 | The M11 component of a 3-by-3 transformation matrix.
em12 | The M12 component of a 3-by-3 transformation matrix.
em21 | The M21 component of a 3-by-3 transformation matrix.
em22 | The M22 component of a 3-by-3 transformation matrix.


PointFx Class (com.ms.awt Package)

 Microsoft SDK for Java

PointFx Class

The PointFx Class of the com.ms.awt package defines the x and y-coordinates of a point on the outline of a TrueType® character.

public class PointFx
{
  // Fields
  public float x;
  public float y;

  // Constructors
  public PointFx(float newX, float newY);
  public PointFx();
}


Constructors (PointFx Class)

 Microsoft SDK for Java

PointFx Class Constructors

The PointFx Class contains the following constructors:

PointFx(float newX, float newY)
PointFx()

PointFx(float newX, float newY)

Creates an initialized point object.

Syntax

public PointFx(float newX, float newY);

Parameters

newX | The x-coordinate.
newY | The y-coordinate.

PointFx()

Creates an uninitialized point object.

Syntax

public PointFx();


Fields (PointFx Class)

 Microsoft SDK for Java

PointFx Class Fields

The PointFx Class contains the following fields.

x | The x-coordinate of a point on the outline of a TrueType® character.
y | The y-coordinate of a point on the outline of a TrueType® character.


PrinterDevice Class (com.ms.awt Package)

 Microsoft SDK for Java

PrinterDevice Class

The PrinterDevice Class of the com.ms.awt package handles printer devices.

public class PrinterDevice extends Device
{
  // Constructors
  public PrinterDevice(Graphics g) throws DeviceException;

  // Methods
  public Dimension getPhysicalOffset();
  public Dimension getPhysicalSize();
  public Dimension getScalingFactor();
}

Hierarchy

Device
  |
  +--PrinterDevice


Constructors (PrinterDevice Class)

 Microsoft SDK for Java

PrinterDevice Class Constructors

The PrinterDevice Class contains the following constructor:

PrinterDevice(Graphics g)

Creates a printer device object.

Syntax

public PrinterDevice(Graphics g) throws DeviceException;

Parameters

g The graphics object that the device is created for.

Exceptions

com.ms.awt.DeviceException if the graphics object is not an instance of the FxGraphics or the GraphicsX extended graphics class.


Methods (PrinterDevice Class)

 Microsoft SDK for Java

PrinterDevice Class Methods

The PrinterDevice Class contains the following methods:

getPhysicalOffset retrieves the physical offset of the printer device.
getPhysicalSize retrieves the physical size of the device.
getScalingFactor retrieves the scaling factor.


getPhysicalOffset (PrinterDevice Class)

 Microsoft SDK for Java

getPhysicalOffset

This method of the PrinterDevice Class retrieves the physical offset of the printer device.

Syntax

public Dimension getPhysicalOffset();

Return Value

Returns the Dimension of the offset.


getPhysicalSize (PrinterDevice Class)

 Microsoft SDK for Java

getPhysicalSize

This method of the PrinterDevice Class retrieves the physical size of the device.

Syntax

public Dimension getPhysicalSize();

Return Value

Returns the Dimension of the device.


getScalingFactor (PrinterDevice Class)

 Microsoft SDK for Java

getScalingFactor

This method of the PrinterDevice Class retrieves the scaling factor.

Syntax

public Dimension getScalingFactor();

Return Value

Returns the scaling factor.


WDragSession Class (com.ms.awt Package)

 Microsoft SDK for Java

WDragSession Class

The WDragSession Class of the com.ms.awt package is an extension of the DragHelper Class. It implements the drag-and-drop APIs presented in the com.ms.object and com.ms.object.dragdrop Java packages for AWT objects.

public class WDragSession extends DragHelper implements
            DragSession
{
  // Methods
  public static void beginDrag(TransferSession session);
  public static void beginDrag(MetaObject data, int available);
  public static void beginDrag(MetaObject data, int available, int preferred);
  public static void beginDrag(DragSource source, MetaObject data,
        int available);
  public static void beginDrag(DragSource source, MetaObject data,
        int available, int preferred);
  public static void beginDrag(DragSource source, TransferSession session);
}

The WDragSession class is similar to the AFC-based implementation in the UIDragDrop class. The dragdrop APIs work for both AWT and Microsoft AFC, but are implemented slightly different. For information on implementing this functionality using AFC and a UIDragDrop object, see the Microsoft SDK for AFC.

The following example shows how you can implement drag-and-drop functionality using AWT and a WDragSession object:

Example

import java.awt.*;
import com.ms.object.*;
import com.ms.object.dragdrop.*;
import com.ms.awt.WDragSession;

class DragMeAWT extends Canvas
{
//...
    public boolean mouseDown(Event e, int x, int y)
    {
        ObjectBag data = new ObjectBag();
        data.addObject(null, null, Color.red);
        WDragSession.beginDrag(data, Transfer.COPY | Transfer.LINK);

        return true;
    }
}

Use the beginDrag methods to start a drag-and-drop operation. All beginDrag methods act on two parameters, a DragSource object, and a TransferSession. Several of the beginDrag methods accept various TransferSession constructor parameters to simplify drag session creation.

Hierarchy

DragHelper
  |
  +--WDragSession


Methods (WDragSession Class)

 Microsoft SDK for Java

WDragSession Class Methods

The WDragSession Class contains the following method:

beginDrag starts a drag session by obtaining a TransferSession object and acting on it.


beginDrag (WDragSession Class)

 Microsoft SDK for Java

beginDrag

The beginDrag method of the WDragSession Class contains the following signatures:

beginDrag(TransferSession session)
beginDrag(MetaObject data, int available)
beginDrag(MetaObject data, int available, int preferred)
beginDrag(DragSource source, MetaObject data, int available)
beginDrag(DragSource source, MetaObject data, int available, int preferred)
beginDrag(DragSource source, TransferSession session)

beginDrag(TransferSession session)

Starts a drag session by obtaining a TransferSession object and acting on it. The drag session has an undefined DragSource object. Drag-and-drop TransferSession implementations must support Transfer.MOVE.

Syntax

public static void beginDrag(TransferSession session);

Parameters

session The TransferSession object that is used during the current drag operation.

beginDrag(MetaObject data, int available)

Starts a drag session by obtaining a TransferSession object and acting on it.

Syntax

public static void beginDrag(MetaObject data, int available);

The drag session has an undefined DragSource object. Drag-and-drop TransferSession implementations must support Transfer.MOVE.

Parameters

data | A MetaObject used to create a TransferSession object. It is used in the current drag session.
available | The transfer effects that are available for the created TransferSession. These include NONE, COPY, MOVE, and LINK.

beginDrag(MetaObject data, int available, int preferred)

Starts a drag session by obtaining a TransferSession object and acting on it.

Syntax

public static void beginDrag(MetaObject data, int available, int preferred);

The drag session has an undefined DragSource object. Drag-and-drop TransferSession implementations must support Transfer.MOVE.

Parameters

data | A MetaObject used to create a TransferSession object. It is used in the current drag session.
available | The transfer effects that are available for the created TransferSession. These include NONE, COPY, MOVE, and LINK.
preferred | The preferred transfer effects for the current TransferSession.

beginDrag(DragSource source, MetaObject data, int available)

Starts a drag session by obtaining a TransferSession object and acting on it.

Syntax

public static void beginDrag(DragSource source, MetaObject data, int available);

Drag-and-drop TransferSession implementations must support Transfer.MOVE.

Parameters

source | A DragSource object that provides custom cursor behavior for the drag session.
data | A MetaObject used to create a TransferSession object. It is used in the current drag session.
available | The transfer effects that are available for the created TransferSession. These include NONE, COPY, MOVE, and LINK.

beginDrag(DragSource source, MetaObject data, int available, int preferred)

Starts a drag session by obtaining a TransferSession object and acting on it.

Syntax

public static void beginDrag(DragSource source, MetaObject data, int available, int preferred);

Drag-and-drop TransferSession implementations must support Transfer.MOVE.

Parameters

source | A DragSource object that provides custom cursor behavior for the drag session.
data | A MetaObject used to create a TransferSession object. It is used in the current drag session.
available | The transfer effects that are available for the created TransferSession. These include NONE, COPY, MOVE, and LINK.
preferred | The preferred transfer effects for the current TransferSession.

beginDrag(DragSource source, TransferSession session)

Starts a drag session by obtaining a TransferSession object and acting on it.

Syntax

public static void beginDrag(DragSource source, TransferSession session);

Drag-and-drop TransferSession implementations must support Transfer.MOVE.

Parameters

source | A DragSource object that provides custom cursor behavior for the drag session.
session | The TransferSession object that is used during the current drag operation.


Win32SystemResourceDecoder Class (com.ms.awt Package)

 Microsoft SDK for Java

Win32SystemResourceDecoder Class

The Win32SystemResourceDecoder Class of the com.ms.awt package is used to utilize Win32 system resource (.res) files.

public class Win32SystemResourceDecoder extends Win32ResourceDecoder
{
  // Constructors
  public Win32SystemResourceDecoder() throws FileNotFoundException;
  public Win32SystemResourceDecoder(String filename)
        throws FileNotFoundException;

  // Methods
  public byte[] getBytes(int type, int strId)
        throws ResourceFormattingException;
  public byte[] getBytes(int type, String name)
        throws ResourceFormattingException;
  public UIDialog getDialog(int dlgId);
  public UIDialog getDialog(String dlgname);
  public int getLocale();
  public String getString(int strId);
  public void populateDialog(UIDialog dlg, int dlgId, int language);
  public void populateDialog(UIDialog dlg, String dlgname,
        int language);
  public void setLocale(int locale);
}

Hierarchy

Win32ResourceDecoder
  |
  +--Win32SystemResourceDecoder


Constructors (Win32SystemResourceDecoder Class)

 Microsoft SDK for Java

Win32SystemResourceDecoder Class Constructors

The Win32SystemResourceDecoder Class contains the following constructors:

Win32SystemResourceDecoder()
Win32SystemResourceDecoder(String filename)

Win32SystemResourceDecoder()

Creates a resource decoder object that attaches to the Microsoft virtual machine resource handler (vmhelper.dll). This is the resource handler the object obtains resources from.

Syntax

public Win32SystemResourceDecoder() throws FileNotFoundException;

Exceptions

FileNotFoundException if vmhelper.dll cannot be found.

Win32SystemResourceDecoder(String filename)

Creates a resource decoder object that attaches to the user specified resource handler.

Syntax

public Win32SystemResourceDecoder(String filename) throws FileNotFoundException;

Parameters

filename The resource handler file that the object attaches to and obtains resources from.

Exceptions

FileNotFoundException if file name is invalid or cannot be found.


Methods (Win32SystemResourceDecoder Class)

 Microsoft SDK for Java

Win32SystemResourceDecoder Class Methods

The Win32SystemResourceDecoder Class contains the following methods:

getBytes retrieves a byte block of the specified resource type, with the given identifier.
getDialog retrieves a UIDialog object with the specified dialog identifier from native resources.
getLocale retrieves the current locale.
getString retrieves a string resource with the specified string identifier.
populateDialog fills an existing dialog box, in the current locale with the specified identifier, with the data and/or controls as specified in the resource.
setLocale sets the current locale.


getBytes (Win32SystemResourceDecoder Class)

 Microsoft SDK for Java

getBytes

The getBytes method of the Win32SystemResourceDecoder Class contains the following signatures:

getBytes(int type, int strId)
getBytes(int type, String name)

getBytes(int type, int strId)

Retrieves a byte block of the specified resource type, with the given identifier.

Syntax

public byte[] getBytes(int type, int strId) throws ResourceFormattingException;

Return Value

Returns a bytes block that contains the resource type.

Parameters

type | The resource type.
srtId | The resource identifier.

Exceptions

ResourceFormattingException if the resource type or identifier are invalid.

getBytes(int type, String name)

Retrieves a byte block of the specified resource type, with the given name.

Syntax

public byte[] getBytes(int type, String name) throws ResourceFormattingException;

Return Value

Returns a bytes block that contains the resource type.

Parameters

type | The resource type.
name | The resource name.

Exceptions

ResourceFormattingException if the resource type or identifier are invalid.


getDialog (Win32SystemResourceDecoder Class)

 Microsoft SDK for Java

getDialog

The getDialog method of the Win32SystemResourceDecoder Class contains the following signatures:

getDialog(int dlgId)
getDialog(String dlgname)

getDialog(int dlgId)

Retrieves a UIDialog object with the specified dialog identifier from native resources.

Syntax

public UIDialog getDialog(int dlgId);

Return Value

Returns a com.ms.ui.UIDialog object, or null if one could not be created.

Parameters

dlgId The dialog identifier.

getDialog(String dlgname)

Retrieves a com.ms.ui.UIDialog object with the specified name from native resources.

Syntax

public UIDialog getDialog(String dlgname);

Return Value

Returns a com.ms.ui.UIDialog object, or null if one could not be created.

Parameters

dlgname The dialog name.


getLocale (Win32SystemResourceDecoder Class)

 Microsoft SDK for Java

getLocale

This method of the Win32SystemResourceDecoder Class retrieves the current locale.

Syntax

public int getLocale();

Return Value

Returns the current locale.

See Also

setLocale


getString (Win32SystemResourceDecoder Class)

 Microsoft SDK for Java

getString

This method of the Win32SystemResourceDecoder Class retrieves a string resource with the specified string identifier.

Syntax

public String getString(int strId);

Return Value

Returns the requested string resource, or null if one could not be created.

Parameters

strId The identifier of the string resource.


populateDialog (Win32SystemResourceDecoder Class)

 Microsoft SDK for Java

populateDialog

The populateDialog method of the Win32SystemResourceDecoder Class contains the following signatures:

populateDialog(UIDialog dlg, int dlgId, int language)
populateDialog(UIDialog dlg, String dlgname, int language)

populateDialog(UIDialog dlg, int dlgId, int language)

Fills an existing dialog box, in the current locale with the specified identifier, with the data and/or controls as specified in the resource. This is useful for classes that are derived from com.ms.ui.UIDialog.

Syntax

public void populateDialog(UIDialog dlg, int dlgId, int language);

Parameters

dlg | The dialog object to populate.
dlgId | The identifier of the dialog resource containing the components.
language | The language of the resources.

Remarks

Currently, this method is not implemented.

populateDialog(UIDialog dlg, String dlgname, int language)

Fills an existing dialog box, in the current locale with the specified name, with the data and/or controls as specified in the resource. This is useful for classes which are derived from com.ms.ui.UIDialog.

Syntax

public void populateDialog(UIDialog dlg, String dlgname, int language);

Parameters

dlg | The dialog object to populate.
dlgname | The name of the dialog resource containing the components.
language | The language of the resources.

Remarks

Currently, this method is not implemented.


setLocale (Win32SystemResourceDecoder Class)

 Microsoft SDK for Java

setLocale

This method of the Win32SystemResourceDecoder Class sets the current locale.

Syntax

public void setLocale(int locale);

Parameters

locale The current locale.

Remarks

Currently, this method is not implemented.

See Also

getLocale


WinEvent Class (com.ms.awt Package)

 Microsoft SDK for Java

WinEvent Class

The WinEvent Class of the com.ms.awt package provides a raw API that enables Java objects to use Microsoft® Active Accessibility®. However, it is recommended that you use the com.ms.ui.UIWinEvent class, which provides essentially the same API and contains all the needed constants as well.

public class WinEvent implements com.ms.ui.IWinEvent
{
  // Constructors
  public WinEvent();

  // Methods
  public Object getObject(int id);
  public void notify(int event, Object obj);
}


Constructors (WinEvent Class)

 Microsoft SDK for Java

WinEvent Class Constructors

The WinEvent Class contains the following constructor:

WinEvent()

Creates a new WinEvent object.

Syntax

public WinEvent();


Methods (WinEvent Class)

 Microsoft SDK for Java

WinEvent Class Methods

The WinEvent Class contains the following methods:

getObject retrieves an object with a specified identifier.
notify generates an event notification that is propagated to any currently associated listener objects.


getObject (WinEvent Class)

 Microsoft SDK for Java

getObject

This method of the WinEvent Class retrieves an object with a specified identifier.

Syntax

public Object getObject(int id);

Return Value

Returns The object, or null if the identifier is invalid.

Parameters

id The identifier of the object to find.


notify (WinEvent Class)

 Microsoft SDK for Java

notify

This method of the WinEvent Class generates an event notification that is propagated to any currently associated listener objects.

Syntax

public void notify(int event, Object obj);

Parameters

event | The event to send.
obj | The Java object that posted the event.


WPrintGraphics Class (com.ms.awt Package)

 Microsoft SDK for Java

WPrintGraphics Class

The WPrintGraphics Class of the com.ms.awt package encapsulates a print graphics context for a printable page.

public class WPrintGraphics extends GraphicsX implements
            PrintGraphics
{
  // Constructors
  public WPrintGraphics(WPrintJob pjob);

  // Methods
  public Graphics create();
  public void dispose();
  public PrintJob getPrintJob();
}

Hierarchy

FxGraphics
  |
  +--GraphicsX
     |
     +--WPrintGraphics


Constructors (WPrintGraphics Class)

 Microsoft SDK for Java

WPrintGraphics Class Constructors

The WPrintGraphics Class contains the following constructor:

WPrintGraphics(WPrintJob pjob)

Creates a print graphics object based on a WPrintJob object.

Syntax

public WPrintGraphics(WPrintJob pjob);

Parameters

pjob The WPrintJob object that the new object is based on.


Methods (WPrintGraphics Class)

 Microsoft SDK for Java

WPrintGraphics Class Methods

The WPrintGraphics Class contains the following methods:

create creates a new WPrintGraphics object based on the current one.
dispose disposes the graphics object after it is no longer being referenced.
getPrintJob retrieves the PrintJob associated with the print graphics object.


create (WPrintGraphics Class)

 Microsoft SDK for Java

create

This method of the WPrintGraphics Class creates a new WPrintGraphics object based on the current one.

Syntax

public Graphics create();

Return Value

Returns a new WPrintGraphics object.


dispose (WPrintGraphics Class)

 Microsoft SDK for Java

dispose

This method of the WPrintGraphics Class disposes the graphics object after it is no longer being referenced.

Syntax

public void dispose();


getPrintJob (WPrintGraphics Class)

 Microsoft SDK for Java

getPrintJob

This method of the WPrintGraphics Class retrieves the PrintJob associated with the print graphics object.

Syntax

public PrintJob getPrintJob();

Return Value

Returns the PrintJob associated with the print graphics object.


WPrintJob Class (com.ms.awt Package)

 Microsoft SDK for Java

WPrintJob Class

The WPrintJob Class of the com.ms.awt package creates Win32 WPrintJob objects that handle printing.

public class WPrintJob extends PrintJob
{
  // Constructors
  public WPrintJob(String title) throws IOException;

  // Methods
  public void end();
  public Graphics getGraphics();
  public Dimension getPageDimension();
  public int getPageResolution();
  public boolean lastPageFirst();
  public void setPageDimensions(int width, int height);
}

This class is similar to the java.awt.PrintJob class, but includes the setPageDimensions method and other improvements.

Printing in Java is performed with this and other printing classes, and with the java.awt.Toolkit class. The following example shows how to use Toolkit to print from an applet:

Example

Toolkit tools = getToolkit();
WPrintJob wpj = (WPrintJob)tools.getPrintJob(null, "Print?", null);
if(wpj != null)
{
     Graphics g = wpj.getGraphics();
     if(g != null)
     {
          paint(g);
          g.dispose();
     }
wpj.end();
}

Hierarchy

PrintJob
  |
  +--WPrintJob


Constructors (WPrintJob Class)

 Microsoft SDK for Java

WPrintJob Class Constructors

The WPrintJob Class contains the following constructor:

WPrintJob(String title)

Creates a Win32 print job object with the specified title.

Syntax

public WPrintJob(String title) throws IOException;

Parameters

title The name of the print job.


Methods (WPrintJob Class)

 Microsoft SDK for Java

WPrintJob Class Methods

The WPrintJob Class contains the following methods:

end ends the print job and performs cleanup operations.
getGraphics retrieves a Graphics object that will draw to the next page.
getPageDimension retrieves the dimensions of the page (in pixels).
getPageResolution retrieves the resolution of the page (in pixels per inch).
lastPageFirst determines if the last page should be printed first.
setPageDimensions sets the logical page dimensions and enables you to effectively use a mapping mode (like GDI).


end (WPrintJob Class)

 Microsoft SDK for Java

end

This method of the WPrintJob Class ends the print job and performs cleanup operations.

Syntax

public void end();


getGraphics (WPrintJob Class)

 Microsoft SDK for Java

getGraphics

This method of the WPrintJob Class retrieves a Graphics object that will draw to the next page. The page is flushed to the printer when the graphics object calls the dispose method.

Syntax

public Graphics getGraphics();

Return Value

Returns a Graphics object that draws to the printer.


getPageDimension (WPrintJob Class)

 Microsoft SDK for Java

getPageDimension

This method of the WPrintJob Class retrieves the dimensions of the page (in pixels).

Syntax

public Dimension getPageDimension();

Return Value

Returns the Dimension of the page (in pixels). If the setPageDimensions has not been called, the Dimension object returned is a default Dimension.


getPageResolution (WPrintJob Class)

 Microsoft SDK for Java

getPageResolution

This method of the WPrintJob Class retrieves the resolution of the page (in pixels per inch).

Syntax

public int getPageResolution();

Return Value

Returns the page resolution.


lastPageFirst (WPrintJob Class)

 Microsoft SDK for Java

lastPageFirst

This method of the WPrintJob Class determines if the last page should be printed first.

Syntax

public boolean lastPageFirst();

Return Value

Returns true if the last page should be printed first.


setPageDimensions (WPrintJob Class)

 Microsoft SDK for Java

setPageDimensions

This method of the WPrintJob Class sets the logical page dimensions and enables you to effectively use a mapping mode (like GDI).

Syntax

public void setPageDimensions(int width, int height);

Parameters

width | The width of the page (in pixels).
height | The height of the page (in pixels).


HeavyComponent Interface (com.ms.awt Package)

 Microsoft SDK for Java

HeavyComponent Interface

The HeavyComponent Interface of the com.ms.awt package is implemented by Java classes that require a Microsoft® Win32® system window (an HWND) for operations that access the native operating system. Java applets and applications that interact with the native system can use this interface with a java.awt.Canvas object to request a system window.

public interface HeavyComponent
{
  // Methods
  public boolean needsHeavyPeer();
}

The HeavyComponent interface is not cross-platform.

Currently, this interface only supports java.awt.Canvas objects. When a Canvas object that implements HeavyComponent is created, needsHeavyPeer is called to determine whether the Canvas object requires a Win32 window.

For example, the HeavyComponent interface is used for the Microsoft® ActiveX® component support. Java objects implement HeavyComponent and are assigned a heavy peer, and the ActiveX Control is hosted in that window.


Methods (HeavyComponent Interface)

 Microsoft SDK for Java

HeavyComponent Interface Methods

The HeavyComponent Interface contains the following method:

needsHeavyPeer is called by a Java object that implements the HeavyComponent interface to request a Win32 window (HWND).


needsHeavyPeer (HeavyComponent Interface)

 Microsoft SDK for Java

needsHeavyPeer

This method of the HeavyComponent Interface is called by a Java object that implements the HeavyComponent interface to request a Win32 window (HWND).

Syntax

public boolean needsHeavyPeer();

Note The HeavyComponent interface only supports java.awt.Canvas objects.

Return Value

Returns true if the Java object requires a Win32 system window; otherwise, returns false.


drawNativeEdge (GraphicsX Class)

 Microsoft SDK for Java

drawNativeEdge

This method of the GraphicsX Class draws one or more edges of rectangle.

Syntax

public void drawNativeEdge(int X, int Y, int W, int H, int edges, int flags);

Parameters

X | The x coordinate of the rectangle's upper left corner.
Y | The y coordinate of the rectangle's upper left corner.
W | The width of the rectangle.
H | The height of the rectangle.
edges | Specifies the type of inner and outer edge to draw.
flags | Specifies the type of border.

Remarks

This method was added as of versions 2925 through 3167 of the Microsoft virtual machine.


drawNativeFocusRect (GraphicsX Class)

 Microsoft SDK for Java

drawNativeFocusRect

This method of the GraphicsX Class draws a focus rectangle that indicates that a specified control has the input focus.

Syntax

public void drawNativeFocusRect(int X, int Y, int W, int H, Color bkColor);

Parameters

X | The x coordinate of the focus rectangle's upper left corner.
Y | The y coordinate of the focus rectangle's upper left corner.
W | The width of the focus rectangle.
H | The height of the focus rectangle.
bkColor | The background color.

Remarks

This method was added as of versions 2925 through 3167 of the Microsoft virtual machine.


com.ms.com Package Overview

Microsoft Packages Overview

The classes and interfaces in the com.ms.com package allow you to implement and use Component Object Model (COM) objects from Java. Used in conjunction with the jactivex and javareg tools, the classes in this package allow you to benefit from Java/COM integration provided by the Microsoft VM. This overview explains how COM objects can be implemented in Java and describes some of the most frequently used classes in the com.ms.com package. This discussion also covers mixing Java and native code.

This package contains the following:

Classes

Interfaces

Hierarchy

COM Objects and Java

The Microsoft VM supports two levels of integration with Component Object Model (COM) objects. High-level integration involves converting Microsoft® ActiveX® controls to JavaBeans components and exposing JavaBeans components as ActiveX controls. Low-level Java/COM integration refers to accessing COM objects by their vtable methods, which is useful when you need to marshal data types that are not handled by IDispatch.

Every Java class automatically implements IUnknown and IDispatch. This fact makes every Java object a COM object. The IDispatch interface implements a dispinterface that contains the public methods of the class's default interface. At runtime, the Microsoft VM automatically provides type information for this IDispatch implementation. To implement a simple Automation object in Java, you place it in the class path and run javareg to register it. No IDLs, type libraries, or Wizards are required.

The IUnknown interface is a placeholder for COM interfaces. Every Java version of a COM interface is derived from IUnknown. Therefore, you never call methods on IUnknown. If your Java program calls a COM method whose return type is IUnknown, you should cast the return value to the COM interface that you are expecting. If your program calls a COM method that takes a parameter of type IUnknown, you can pass any COM interface to the COM method.

Frequently Used Classes

com.ms.com.ComException communicates error information from a COM method to Java. The ComException class wraps the HRESULT error code that is returned by COM interface methods. ComException objects communicate error information from a COM method to Java when the COM method fails. This class defines a getHResult method that retrieves the error code from the ComException object.

com.ms.com.ComFailException is derived from the ComException class. Typically, you try to catch ComFailException objects so that you know when something has gone wrong during a call to a COM method. The documentation for the ComFailException class contains a list of the values of system-defined HRESULTs.

com.ms.com.ComSuccessException is derived from the ComException class. For ComSuccessException objects, the default value of the stored HRESULT is S_FALSE (0x00000001L). This value indicates the successful completion of a method that returns a Boolean value of false.

com.ms.com.Variant is used to bridge Java with ActiveX components that manipulate VARIANTs. Most of the methods found in this class belong to one of three categories:

to XXX methods

Attempt to coerce the Variant object to type XXX and return the converted value, but do not copy the result back to the Variant.

get XXX methods

Retrieve data from a Variant object of type XXX, succeeding only if the Variant object is already the correct type.

put XXX methods

Change the type of a Variant object and initialize it to a new value.

Dispatch enables Java programs to invoke methods and access the properties of any ActiveX component that supports the IDispatch interface. Each of the methods in this class performs one of the following functions:

getIDsOfNames methods

Maps methods or property names to dispids.

invokev methods

Invokes methods or accesses properties.

invokeSubv methods

Invokes subroutines.

Mixing Java and Native Code

The Microsoft virtual machine can treat COM objects as special Java classes. Java/COM integration allows any Java Bean to be an ActiveX control and any ActiveX control to be a JavaBean—all nearly automatically. COM integration is best for ActiveX controls or for calling APIs that are wrapped in COM objects. You can use COM objects in Java and use Java to write COM objects.

The ability to mix and match code written in different languages lets developers achieve the maximum benefit from the tools at their disposal.

There are many scenarios that require Java code to call code that is written in some other language. For example, a Java developer may want to do one of the following:

  • Provide efficient algorithms where performance is an issue.

  • Take advantage of the hardware present on the host computer.

  • Take advantage of the operating environment on the host computer.

  • Utilize the components available through other component technologies, such as COM (Component Object Model) that underlies Microsoft® ActiveX®.

Almost all class libraries, including the ones from JavaSoft's JDK, call code written in other languages to exploit some of these scenarios.

In the context of Java, any code that is not written in Java is called native code. This document does not deal with the pros and cons of using native code versus Java code. Rather, it attempts to describe the options available to a Java programmer who wants to call native code from Java.

The Microsoft virtual machine (Microsoft VM) provides four ways to call non-Java code from Java code. See the Integrating Java topics in the Programmer's Guide for details.

There are Java/COM integration samples in the subdirectories of %SDKDIR%\Samples\Com. For more information, see the COM Samples Overview. For information about other samples in the SDK, see the Samples Overview.


Classes (com.ms.com Package)

 Microsoft SDK for Java

com.ms.com Package Classes

The com.ms.com package contains the following classes:

_Guid Class represents globally unique identifiers (GUIDs), which are 128-bit integer values that are used to assign world-wide unique identifiers for COM interfaces and CoClasses.

BIND_OPTS Class contains parameters used during a moniker-binding operation; added as of versions 2925 through 3167 of the Microsoft virtual machine.

COAUTHIDENTITY represents a user name and password; added as of versions 2925 through 3167 of the Microsoft virtual machine.

COAUTHINFO specifies the authentication settings used while making a remote activation request from the client machine to the server machine; added as of versions 2925 through 3167 of the Microsoft virtual machine.

ComError Class signals errors in linking Java and Component Object Model (COM) objects.

ComException Class wraps an HRESULT, the return type for most methods in the Component Object Model (COM).

ComFailException Class wraps an HRESULT, the return type for most methods in the Component Object Model (COM).

ComLib Class contains routines that are used during Java Component Object Model (COM) integration.

ComSuccessException Class wraps an HRESULT, the return type used in most methods in the Component Object Model (COM).

CONNECTDATA Class is the type enumerated through the IEnumConnections.Next method; CONNECTDATA was added as of versions 2925 through 3167 of the Microsoft virtual machine.

ConnectionPointCookie Class provides methods for creating and closing a connection between a source and a sink object.

COSERVERINFO Class identifies a remote machine resource to the new or enhanced activation functions; added as of versions 2925 through 3167 of the Microsoft virtual machine.

CUnknown Class is the default class for Java-callable-wrappers for COM interfaces that are marshaled to Java interfaces.

Dispatch Class enables Java programs to invoke methods and access the properties of any Microsoft® ActiveX® Automation object.

DispatchProxy Class wraps a dispatchable object with a Java interface.

LicenseMgr Class works with the ILicenseMgr interface to enable you to use licensed Component Object Model (COM) components or controls in your Java application.

LICINFO Class describes the licensing behavior of a class factory that supports licensing.

MULTI_QI Class optimizes network performance by providing multiple interface pointers to remote activation functions; added as of versions 2925 through 3167 of the Microsoft virtual machine.

SafeArray Class wraps a Microsoft® ActiveX® Automation SAFEARRAY data structure.

STATSTG Class represents an STATSTG structure, which contains statistical information about an open storage, stream or byte array object.

StdCOMClassObject Class supports COM class objects.

Variant Class is used to bridge Java with Microsoft® ActiveX® components that manipulate VARIANT data types.

WrongThreadException Class represents objects that are thrown when a method call cannot be made because it was called on the wrong thread.


Interfaces (com.ms.com Package)

 Microsoft SDK for Java

com.ms.com Package Interfaces

The com.ms.com package contains the following interfaces:

ComContext Interface defines constants that specify the contexts that a Component Object Model (COM) class can run in.

IAccessible Interface provides methods that enable users to request selection and focus information, perform hit tests, and navigate by using object and child identifiers.

IAccessibleDefault Interface provides methods that enable users to request selection and focus information, perform hit tests, and navigate by using object and child identifiers.

IBindCtx Interface provides access to a bind context, which is an object that stores information about a particular moniker binding operation. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IClassFactory Interface deals with an entire class of objects, and so is implemented on the class object for a specific class of objects (identified by a CLSID). This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IClassFactory2 Interface enables a class factory object, in any sort of object server, to control object creation through licensing.

IConnectionPoint Interface supports connection points for connectable objects. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IConnectionPointContainer Interface supports connection points for connectable objects. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

ICreateErrorInfo Interface returns error information.

IEnumConnectionPoints Interface enumerates connection points. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IEnumConnections Interface enumerates the current connections for a connectable object. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IEnumMoniker Interface enumerates the components of a moniker or the monikers in a table of monikers. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IEnumSTATSTG Interface enumerates through an array of STATSTG structures. IEnumSTATSTG was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IEnumString Interface enumerates strings. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IEnumUnknown Interface enumerates objects with the IUnknown interface. IEnumUnknown was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IEnumVariant Interface provides methods for enumerating a collection of variants.

IErrorInfo Interface provides detailed contextual error information.

IExternalConnectionSink Interface allows Java objects exposed as Component Object Model (COM) objects to be notified of calls to the IExternalConnection interface.

ILockBytes Interface is used by a COM compound file storage object to give its root storage access to the physical device, while isolating the root storage from the details of accessing the physical storage. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IMarshal Interface enables a COM object to define and manage the marshaling of its interface pointers. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IMoniker Interface contains methods that allow you to use a moniker object, which contains information that uniquely identifies a COM object. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

ILicenseMgr Interface supports the use of licensed Component Object Model (COM) components or controls in a Java application.

IParseDisplayName Interface parses a displayable name string to convert it into a moniker for custom moniker implementations. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IPersist Interface defines a single method that supplies the CLSID of an object that can be stored persistently in the system. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IPersistFile Interface permits an object to be loaded from or saved to a disk file, rather than a storage object or stream. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IPersistStorage Interface enables a container application to pass a storage object to one of its contained objects and to load and save the storage object. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IPersistStream Interface provides methods for saving and loading objects that use a simple serial stream for their storage needs. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IPersistStreamInit Interface is implemented on any object that needs to support initialized stream-based persistence, regardless of whatever else the object does. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IPropertyNotifySink Interface provides methods that allow a sink object to receive notifications about property changes from another object.

IROTData Interface is implemented by monikers to enable the Running Object Table (ROT) to compare monikers against each other. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IRunningObjectTable Interface manages access to the Running Object Table (ROT), a globally accessible look-up table on each workstation. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

ISequentialStream Interface supports simplified sequential access to stream objects. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IServiceProvider Interface provides a method that locates a service specified by a GUID and returns the interface pointer for a requested interface on the service.

IStorage Interface supports the creation and management of structured storage objects. This interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

IStream Interface provides methods for reading and writing data to stream objects.

IUnknown Interface is used as the return type for Component Object Model (COM) methods that return arbitrary COM interfaces.

NoAutoScripting Interface when used in the implements clause of a class definition, this interface prevents the Microsoft VM from including its own IDispatch implementation for the class.

NoAutoMarshaling Interface an empty interface that flags that the free-threaded marshaler should be disabled.


Hierarchy (com.ms.com Package)

 Microsoft SDK for Java

com.ms.com Package Hierarchy

The com.ms.com package has the following hierarchy:

Object
  |
  +--_Guid
  |
  +--BIND_OPTS
  |
  +--COAUTHIDENTITY
  |
  +--COAUTHINFO
  |
  +--ComLib
  |
  +--CONNECTDATA
  |
  +--ConnectionPointCookie
  |
  +--COSERVERINFO
  |
  +--CUnknown
  |
  +--Dispatch
  |
  +--DispatchProxy
  |
  +--LicenseMgr (IUnknown, ILicenseMgr)
  |
  +--LICINFO
  |
  +--MULTI_QI
  |
  +--SafeArray
  |
  +--STATSTG
  |
  +--StdCOMClassObject
  |
  +--Variant

OutOfMemoryError
  |
  +--ComError

RuntimeException
  |
  +--ComException
  |  |
  |  +--ComFailException
  |  |
  |  +--ComSuccessException
  |
  +--WrongThreadException

Interfaces
ComContext
IAccessible
IUnknown
IAccessibleDefault
IBindCtx
IClassFactory
IClassFactory2
IConnectionPoint
IConnectionPointContainer
ICreateErrorInfo
IEnumConnectionPoints
IEnumConnections
IEnumMoniker
IEnumSTATSTG
IEnumString
IEnumVariant
IErrorInfo
IExternalConnectionSink
ILicenseMgr
ILockBytes
IMoniker
IParseDisplayName
IPersist
IPersistFile
IPersistStorage
IPropertyNotifySink
IROTData
IRunningObjectTable
ISequentialStream
IServiceProvider
IStorage
IStream
IUnknown
NoAutoScripting
NoAutoMarshaling


_Guid Class (com.ms.com Package)

 Microsoft SDK for Java

_Guid Class

The _Guid class of the com.ms.com package represents globally unique identifiers (GUIDs), which are 128-bit integer values that are used to assign world-wide unique identifiers for COM interfaces and CoClasses.

public final class _Guid
{
  // Constructors
  public _Guid(byte [] ba);
  public _Guid(int d1, short d2, short d3, byte b8, byte b9,
        byte b10, byte b11, byte b12, byte b13, byte b14,
        byte b15);
  public _Guid(String str);
  public _Guid();

  // Methods
  public boolean equals(Object g2);
  public int hashCode();
  public void set(byte [] ba);
  public void set(String str);
  public void set(int d1, short d2, short d3, byte b8, byte b9,
        byte b10, byte b11, byte b12, byte b13, byte b14,
        byte b15);
  public byte [] toByteArray();
  public String toString();
}


Constructors (_Guid Class)

 Microsoft SDK for Java

_Guid Class Constructors

The _Guid Class contains the following constructors:

_Guid(byte [] ba)
_Guid(int d1, short d2, short d3, byte b8, byte b9, byte b10, byte b11, byte b12, byte b13, byte b14, byte b15)
_Guid(String str)
_Guid()

_Guid(byte [] ba)

Constructs a new _Guid object, whose value matches the internal representation of the specified 16-element byte array.

Syntax

public _Guid(byte [] ba);

Parameters

ba The 16-element byte array.

CAUTION This constructor form is efficient but not endian-portable. Its use, therefore, is not recommended for cross-platform applications.

_Guid(int d1, short d2, short d3, byte b8, byte b9, byte b10, byte b11, byte b12, byte b13, byte b14, byte b15)

Constructs a new _Guid object whose value is specified by the internal representations of the parameters d1 through b15 in order.

Syntax

public _Guid(int d1, short d2, short d3, byte b8, byte b9, byte b10, byte b11, byte b12, byte b13, byte b14, byte b15);

Parameters

d1 | A 32-bit integer.
d2 | A 16-bit integer.
d3 | A 16-bit integer.
b8 | An 8-bit integer.
b9 | An 8-bit integer.
b10 | An 8-bit integer.
b11 | An 8-bit integer.
b12 | An 8-bit integer.
b13 | An 8-bit integer.
b14 | An 8-bit integer
b15 | An 8-bit integer.

_Guid(String str)

Constructs a new _Guid object from its string representation. The string representation is in the following form, in which each x denotes a hexadecimal digit:

{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

Syntax

public _Guid(String str);

Parameters

str The GUID string representation.

_Guid()

Constructs a new _Guid object, whose value is as follows:

{00000000-0000-0000-0000-000000000000}.

Syntax

public _Guid();


Methods (_Guid Class)

 Microsoft SDK for Java

_Guid Class Methods

The _Guid Class contains the following methods:

equals tests whether the GUID represented by the parameter g2 is equal to the GUID represented by the current _Guid object.
hashCode computes a hash code based on the value of the GUID.
set reinitializes an existing _Guid object from a 16-element byte array.
toByteArray converts a GUID to a 16-element byte array.
toString converts a GUID to its registry string representation.


equals (_Guid Class)

 Microsoft SDK for Java

equals

This method of the _Guid Class tests whether the GUID represented by the parameter g2 is equal to the GUID represented by the current _Guid object. Two GUIDs are equal only if each of the 128 bits in the two GUIDs are equal.

Syntax

public boolean equals(Object g2);

Return Value

Returns true if each of the 128 bits in the two GUIDs are equal; otherwise, returns false.

Parameters

g2 The object whose GUID is being compared against the current _Guid object.


hashCode (_Guid Class)

 Microsoft SDK for Java

hashCode

This method of the _Guid Class computes a hash code based on the value of the GUID.

Syntax

public int hashCode();

Return Value

Returns an integer hash code.


set (_Guid Class)

 Microsoft SDK for Java

set

The set method of the _Guid Class contains the following signatures:

set(byte [] ba)
set(String str)
set(int d1, short d2, short d3, byte b8, byte b9, byte b10, byte b11, byte b12, byte b13, byte b14, byte b15)

set(byte [] ba)

Reinitializes an existing _Guid object from a 16-element byte array.

Syntax

public void set(byte [] ba)

Parameters

ba A 16-element byte array.

CAUTION This method of reinitialization is not endian-portable.

set(String str)

Reinitializes an existing _Guid from its registry string representation. The string representation is in the following form, in which each x denotes a hexadecimal digit:

{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

Syntax

public void set(String str);

Parameters

str The registry string representation.

set(int d1, short d2, short d3, byte b8, byte b9, byte b10, byte b11, byte b12, byte b13, byte b14, byte b15)

Reinitializes an existing _Guid object so that its value is specified by the internal representations of the parameters d1 through b15 in order.

Syntax

public void set(int d1, short d2, short d3, byte b8, byte b9, byte b10, byte b11, byte b12, byte b13, byte b14, byte b15);

Parameters

d1 | A 32-bit integer.
d2 | A 16-bit integer.
d3 | A 16-bit integer.
b8 | An 8-bit integer.
b9 | An 8-bit integer.
b10 | An 8-bit integer.
b11 | An 8-bit integer.
b12 | An 8-bit integer.
b13 | An 8-bit integer.
b14 | An 8-bit integer.
b15 | An 8-bit integer.


toByteArray (_Guid Class)

 Microsoft SDK for Java

toByteArray()

This method of the _Guid Class converts a GUID to a 16-element byte array.

Syntax

public byte [] toByteArray();

Return Value

Returns a 16-element byte array that represents the GUID.

CAUTION The byte array representation is not endian-portable; it cannot be used to transmit GUIDs between processors.


toString (_Guid Class)

 Microsoft SDK for Java

toString

This method of the _Guid Class converts a GUID to its registry string representation.

Syntax

public String toString();

Return Value

Returns the registry string representation of the GUID.


BIND_OPTS Class (com.ms.com Package)

 Microsoft SDK for Java

BIND_OPTS Class

The BIND_OPTS class of the com.ms.com package contains parameters used during a moniker-binding operation. A BIND_OPTS structure is stored in a bind context; the same bind context is used by each component of a composite moniker during binding, allowing the same parameters to be passed to all components of a composite moniker. For more information about bind contexts, see IBindCtx.

A moniker client typically does not need to specify values for the fields of this structure. Other COM library functions do this for you. For example, the CreateBindCtx function creates a bind context with the bind options set to default values that are suitable for most situations; the BindMoniker function does the same thing when creating a bind context for use in binding a moniker. If you want to modify the values of these bind options, pass a BIND_OPTS structure to IBindCtx.SetBindOptions. Moniker implementers can pass a BIND_OPTS structure to IBindCtx.GetBindOptions to retrieve the values of these bind options.

Note The BIND_OPTS class was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public class BIND_OPTS
{
  //  Members
  public int cbStruct
  public int grfFlags;
  public int grfMode;
  public int dwTickCountDeadline;
}

Members

cbStruct | The size of this structure in bytes.
grfFlags | The flags that control aspects of moniker-binding operations.
grfMode | The flags that should be used when opening the file that contains the object identified by the moniker. The values are taken from the STGM enumeration. The binding operation uses these flags in the call to IPersistFile.Load when loading the file. If the object is already running, these flags are ignored by the binding operation.
dwTickCountDeadline | Clock time in milliseconds by which the caller would like the binding operation to be completed. This member lets the caller limit the execution time of an operation when speed is of primary importance. A value of 0 (zero) indicates that there is no deadline. Callers most often use this capability when calling IMoniker.GetTimeOfLastChange, though it can be usefully applied to other operations as well.


COAUTHIDENTITY (com.ms.com Package)

 Microsoft SDK for Java

COAUTHIDENTITY Class

The COAUTHIDENTITY class of the com.ms.com package represents a user name and password. A pointer to a COAUTHIDENTITY structure is a member of COAUTHINFO, which specifies authentication settings for remote activation requests.

Note The COAUTHIDENTITY class was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public class COAUTHIDENTITY
{
  // Members
  public String user;
  private int userLength;
  public String domain;
  private int domainLength;
  public String password;
  private int passwordLength;
  public int flags;
}

Members

user | The string containing the user's name.
userLength | The length of the User string, without the terminating NULL.
domain | The string containing the domain or workgroup name.
domainLength | The length of the Domain string, without the terminating NULL.
password | The string containing the user's password in the domain or workgroup.
passwordLength | The length of the Password string, without the terminating NULL.
flags | The value indicating that the strings are ANSI (0x1) or Unicode(0x2).


COAUTHINFO Class (com.ms.com Package)

 Microsoft SDK for Java

COAUTHINFO Class

The COAUTHINFO class of the com.ms.com package specifies the authentication settings used while making a remote activation request from the client machine to the server machine.

Note The COAUTHINFO class was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public class COAUTHINFO
{
  // Members
  public int dwAuthnSvc;
  public int dwAuthzSvc;
  public String pwszServerPrincName;
  public int dwAuthnLevel;
  public int dwImpersonationLevel;
  public COAUTHIDENTITY pAuthIdentityData;
  public int dwCapabilities;
}

Members

[in] dwAuthnSvc | A single DWORD value from the list of RPC_C_AUTHN_xxx constants indicating the authentication service to use. It may be RPC_C_AUTHN_NONE if no authentication is required. RPC_C_AUTHN_WINNT is the default and RPC_C_AUTHN_GSS_KERBEROS is also supported.
[in] dwAuthzSvc | A single DWORD value from the list of RPC_C_AUTHZ_xxx constants indicating the authorization service to use. If you are using the Microsoft® Windows NT® authentication service, use RPC_C_AUTHZ_NONE.
pwszServerPrincName | Pointer to a WCHAR string that indicates the server principal name to use with the authentication service. If you are using RPC_C_AUTHN_WINNT, the principal name must be NULL.
[in] dwAuthnLevel | A single DWORD value from the list of RPC_C_AUTHN_LEVEL_xxx constants indicating the authentication level to use.
[in] dwImpersonationLevel | Specifies the impersonation level to use. This value must be RPC_C_IMP_LEVEL_IMPERSONATE.
pAuthIdentityData | Pointer to a COAUTHIDENTITY structure that establishes a non-default client identity. If NULL, the actual identity of the client is used. Values of structure members are authentication-service specific. This value must be NULL if dwAuthnSvc is not NTLMSSP or Kerberos.
[in] dwCapabilities | A DWORD defining flags that indicate the further capabilities of this proxy.


ComError Class (com.ms.com Package)

 Microsoft SDK for Java

ComError Class

signals errors in linking Java and Component Object Model (COM) objects. ComError extends the OutOfMemoryError class to achieve backward compatibility with Microsoft SDK for Java 1.0.

public class ComError extends OutOfMemoryError
{
  // Constructors
  public ComError();
  public ComError(String s);
}

Hierarchy

OutOfMemoryError
  |
  +--ComError


Constructors (ComError Class)

 Microsoft SDK for Java

ComError Class Constructors

The ComError Class contains the following constructors:

ComError()
ComError(String s)

ComError()

Creates an empty ComError object.

Syntax

public ComError();

ComError(String s)

Creates a ComError object that contains a specific detail message.

Syntax

public ComError(String s);

Parameters

s The detail message that describes the exception.


ComException Class (com.ms.com Package)

 Microsoft SDK for Java

ComException Class

The ComException Class of the com.ms.com package is a subclass of java.lang.RuntimeException. It wraps an HRESULT, the return type for most methods in the Component Object Model (COM).

public abstract class ComException extends RuntimeException
{
  // Fields
  protected int hr;
  protected int m_helpContext;
  protected String m_helpFile;
  protected String m_source;

  // Constructors
  public ComException(int hr);
  public ComException(int hr, String description);
  public ComException(int hr, String source, String helpFile,
        int helpContext);
  public ComException(int hr, String description, String source,
        String helpFile, int helpContext);
  public ComException();
  public ComException(String description);

  // Methods
  public int getHelpContext();
  public String getHelpFile();
  public int getHResult();
  public String getSource();
}

When you call COM methods from Java, you catch ComException objects to handle error conditions. Because ComException is derived from the RuntimeException class, the compiler does not check whether methods throw ComException objects. Use your discretion as to when you should use try-catch blocks.

When implementing COM classes that use Java, ComException objects are thrown to signal error conditions. Because ComException is an abstract class, a ComException object cannot be constructed directly. However, ComFailException objects and ComSuccessException objects are constructed using ComException constructors.

Hierarchy

RuntimeException
  |
  +--ComException


Constructors (ComException Class)

 Microsoft SDK for Java

ComException Class Constructors

The ComException contains the following constructors:

ComException(int hr)
ComException(int hr, String description)
ComException(int hr, String source, String helpFile,int helpContext)
ComException(int hr, String description, String source, String helpFile, int helpContext)
ComException()
ComException(String description)

ComException(int hr)

Creates a ComException object that contains the specified HRESULT.

Syntax

public ComException(int hr);

Parameters

hr The HRESULT value.

ComException(int hr, String description)

Creates a ComException object that contains an HRESULT and a description.

Syntax

public ComException(int hr, String description);

Parameters

hr | The HRESULT value that is returned.
description | The detail description.

ComException(int hr, String source, String helpFile, int helpContext)

Creates a ComException object that contains the HRESULT, source, Help file, and help context.

Syntax

public ComException(int hr, String source, String helpFile, int helpContext);

Parameters

hr | The HRESULT value that is returned.
source | The source of the ComException object.
helpFile | The Help file that explains the ComException object.
helpContext | The identifier that indicates the context of the exception.

ComException(int hr, String description, String source, String helpFile, int helpContext)

Creates a ComException object that contains the specified HRESULT, description, source, Help file, and Help context.

Syntax

public ComException(int hr, String description, String source, String helpFile, int helpContext);

Parameters

hr | The HRESULT value to be returned.
description | The detail description.
source | The source of the ComException object.
helpFile | The Help file that explains the ComException object.
helpContext | The identifier that indicates the context of the exception.

ComException()

Creates and stores an uninitialized ComException object.

Syntax

public ComException();

ComException(String description)

Creates and stores a ComException object that contains the detail description.

Syntax

public ComException(String description);

Parameters

description The detail description.


Methods (ComException Class)

 Microsoft SDK for Java

ComException Class Methods

The ComException contains the following methods:

getHelpContext retrieves the Help context of the ComException object.
getHelpFile retrieves the Help file that explains the ComException object.
getHResult retrieves the HRESULT returned by the COM method.
getSource retrieves the source of the ComException object.


getHelpContext (ComException Class)

 Microsoft SDK for Java

getHelpContext

This method of the ComException Class retrieves the Help context of the ComException object. The Help context is an identifier that indicates the context of the exception.

Syntax

public int getHelpContext();

Return Value

Returns the Help context of the ComException object.


getHelpFile (ComException Class)

 Microsoft SDK for Java

getHelpFile

This method of the ComException Class retrieves the Help file that explains the ComException object.

Syntax

public String getHelpFile();

Return Value

Returns the Help file that explains the ComException object.


getHResult (ComException Class)

 Microsoft SDK for Java

getHResult

This method of the ComException Class retrieves the HRESULT returned by the COM method. To catch a ComException object thrown by a COM method, call this method.

Syntax

public int getHResult();

Return Value

Returns the HRESULT returned by the COM method.


getSource (ComException Class)

 Microsoft SDK for Java

getSource

This method of the ComException Class retrieves the source of the ComException object.

Syntax

public String getSource();

Return Value

Returns the source of the ComException object.


Fields (ComException Class)

 Microsoft SDK for Java

ComException Class Fields

The ComException Class contains the following fields.

hr | The HRESULT value.
m_helpContext | The identifier used by the Help file that indicates the context of the exception.
m_helpFile | The Help file that explains the ComException object.
m_source | The source of the ComException object.


ComFailException Class (com.ms.com Package)

 Microsoft SDK for Java

ComFailException Class

The ComFailException Class of the com.ms.com package wraps an HRESULT, the return type for most methods in the Component Object Model (COM).

public class ComFailException extends ComException
{
  // Constructors
  public ComFailException(int hr);
  public ComFailException(int hr, String message);
  public ComFailException(int hr, String source, String helpFile,
        int helpContext);
  public ComFailException(int hr, String description,
        String source, String helpFile, int helpContext);
  public ComFailException();
  public ComFailException(String message);
}

The default value of the HRESULT stored in a ComFailException object is E_FAIL (0x80004005L). The values of system-defined HRESULTs can be found in WINERROR.H, which is included with the MSDN™ Library. For information on component-specific errors, refer to the documentation associated with the component.

For system-defined errors, the detail description stored in the ComException object is the string returned by the Microsoft® Win32® API function, FormatMessage. This function returns a brief description of the error. This description can be retrieved by calling the getMessage method that is defined by the Throwable class.

The following table lists some common HRESULT values.

Common HRESULT values

Error | Meaning | Value
E_UNEXPECTED | Unexpected failure. | 0x8000FFFF
E_NOTIMPL | Not implemented. | 0x80004001
E_OUTOFMEMORY | Ran out of memory. | 0x8007000E
E_INVALIDARG | One or more arguments are invalid. | 0x80070057
E_NOINTERFACE | No such interface supported. | 0x80004002
E_POINTER | Invalid pointer. | 0x80004003
E_HANDLE | Invalid handle. | 0x80070006
E_ABORT | Operation aborted. | 0x80004004
E_FAIL | Unspecified error. | 0x80004005
E_ACCESSDENIED | General access denied error. | 0x80070005
E_NOTIMPL | Not implemented. | 0x80000001
DISP_E_UNKNOWNINTERFACE | Unknown interface. | 0x80020001
DISP_E_MEMBERNOTFOUND | Member not found. | 0x80020003
DISP_E_PARAMNOTFOUND | Parameter not found. | 0x80020004
DISP_E_TYPEMISMATCH | Type mismatch. | 0x80020005
DISP_E_UNKNOWNNAME | Unknown name. | 0x80020006
DISP_E_NONAMEDARGS | No named arguments. | 0x80020007
DISP_E_BADVARTYPE | Bad variable type. | 0x80020008
DISP_E_EXCEPTION | Exception occurred. | 0x80020009
DISP_E_OVERFLOW | Out of present range. | 0x8002000A
DISP_E_BADINDEX | Invalid index. | 0x8002000B
DISP_E_UNKNOWNLCID | Memory is locked. | 0x8002000C
DISP_E_ARRAYISLOCKED | Memory is locked. | 0x8002000D
DISP_E_BADPARAMCOUNT | Invalid number of parameters. | 0x8002000E
DISP_E_PARAMNOTOPTIONAL | Parameter not optional. | 0x8002000F
DISP_E_BADCALLEE | Invalid callee. | 0x80020010
DISP_E_NOTACOLLECTION | Does not support a collection. | 0x80020011

Hierarchy

java.lang.RuntimeException
  |
  +--ComException
     |
     +--ComFailException


Constructors (ComFailException Class)

 Microsoft SDK for Java

ComFailException Class Constructors

The ComFailException Class contains the following constructors:

ComFailException(int hr)
ComFailException(int hr, String message)
ComFailException(int hr, String source, String helpFile)
ComFailException(int hr, String description, String source, String helpFile, int helpContext)
ComFailException()
ComFailException(String message)

ComFailException(int hr)

Creates a ComFailException object that contains the specified HRESULT.

Syntax

public ComFailException(int hr);

Parameters

hr The HRESULT value that is returned.

ComFailException(int hr, String message)

Creates a ComFailException object that contains the specified HRESULT and detail description.

Syntax

public ComFailException(int hr, String message);

Parameters

hr | The HRESULT value that is returned.
message | The detail description.

ComFailException(int hr, String source, String helpFile)

Creates a ComFailException object that contains the specified HRESULT, source, help file, and help context.

Syntax

public ComFailException(int hr, String source, String helpFile, int helpContext);

Parameters

hr | The HRESULT value that is returned.
source | The source of the ComFailException object.
helpFile | The Help file for the ComFailException object.
helpContext | The identifier that indicates the context of the exception.

ComFailException(int hr, String description, String source, String helpFile, int helpContext)

Creates a ComFailException object that contains the specified HRESULT, description, source, Help file, and help context.

Syntax

public ComFailException(int hr, String description, String source, String helpFile, int helpContext);

Parameters

hr | The HRESULT value that is returned.
description | The detail description.
source | The source of the ComFailException object.
helpFile | The Help file for the ComFailException object.
helpContext | The identifier that indicates the context of the exception.

ComFailException()

Creates a ComFailException object. The default value of the HRESULT stored in the object is E_FAIL (0x80004005L).

Syntax

public ComFailException();

ComFailException(String message)

Creates a ComFailException object that contains the specified detail description. The default value of the HRESULT stored in the object is E_FAIL (0x80004005L).

Syntax

public ComFailException(String message);

Parameters

message The detail description.


ComLib Class (com.ms.com Package)

 Microsoft SDK for Java

ComLib Class

The ComLib Class of the com.ms.com package contains routines that are used during Java Component Object Model (COM) integration. All ComLib methods are static; therefore, you can use this class without instantiating it.

public class ComLib
{
  // Methods
  public native static void declareMessagePumpThread();
  public static native void executeOnContext(Object objectWithContext,
        Runnable runnable);
  public static native void freeUnusedLibraries();
  public static _Guid getGuidOf(Class cl);
  public static native boolean isEqualUnknown(Object o1, Object o2);
  public native static int jcdwClassOffsetOf(Class cls,
        String fieldName);
  public native static int jcdwClassSizeOf(Class cls);
  public native static int jcdwOffsetOf(Object jcdw,
        String fieldName);
  public native static int jcdwSizeOf(Object jcdw);
  public native static Object makeProxyRef(Object o);
  public static boolean ownsCleanup(Object structObj);
  public static native int ptrRelease(int ptr);
  public static native Object ptrToStruct(Class structClass,
        int ptr, boolean fFreeIndirectNativeMemory);
  public static native Object ptrToUnknown(Class unknownClass, int ptr,
        boolean isFreeThreaded);
  public native static void release(Object o);
  protected static native void setDataWrapperSize(
        Object DataWrapper, int cb);
  public native static boolean supportsInterface(Object pComObject,
        _Guid iid);
  public static native void startMTAThread(Thread thd);
  public static native void threadStartMTA(Thread thd);
  public static native int unknownToPtr(Object obj, _Guid iid);

  // Fields
  public static final _Guid IID_IUnknown;
  public static final _Guid IID_IDispatch;
}


Methods (ComLib Class)

 Microsoft SDK for Java

ComLib Class Methods

The ComLib Class contains the following methods:

declareMessagePumpThread enables apartment model hosting.
executeOnContext marshals to the context bound to the supplied object and executes the run() method of the supplied object that implements Runnable.
freeUnusedLibraries releases all unused libraries on the current thread and the virtual machine's host single-threaded apartment thread.
getGuidOf returns the GUID from the @com.class or @com.interface attributed class.
isEqualUnknown compares the COM identity of two Java objects. If the two objects have equal IUnknown* pointers, they have the same COM identity.
jcdwClassOffsetOf retrieves the offset of a COM data structure that represents an instance of a Java proxy class.
jcdwClassSizeOf retrieves the size (measured in bytes) of a COM data structure that represents instances of the class.
jcdwOffsetOf retrieves the offset of a COM data structure (measured in bytes) that is represented by a Java proxy.
jcdwSizeOf retrieves the size of a COM data structure (measured in bytes) that is represented by a Java proxy.
makeProxyRef increments the reference count on a COM object.
ownsCleanup determines whether Java is responsible for doing cleanup tasks for the COM object.
ptrRelease releases a reference on the interface, given a raw COM interface pointer.
ptrToStruct maps a raw pointer onto a structure.
ptrToUnknown maps a raw pointer to a Java-callable wrapper.
release forces Java to release all outstanding reference counts on a native COM object.
setDataWrapperSize allocates and binds memory to an existing data wrapper.
startMTAThread initializes the thread inside the multi-threaded COM apartment. This method replaces ThreadStartMTA.
supportsInterface determines whether a COM object supports a particular interface by using that object's QueryInterface method.
ThreadStartMTA initializes a thread without initializing COM. This method is deprecated. It is replaced by startMTAThread.
unknownToPtr maps a COM object to a raw pointer to a specified interface.


declareMessagePumpThread (ComLib Class)

 Microsoft SDK for Java

declareMessagePumpThread

This method of the ComLib Class enables apartment model hosting.

Syntax

public native static void declareMessagePumpThread();


executeOnContext (ComLib Class)

 Microsoft SDK for Java

executeOnContext

This method of the ComLib Class marshals to the context bound to the supplied object and executes the run() method of the supplied object that implements Runnable.

Syntax

public static native void executeOnContext(Object objectWithContext, Runnable runnable);

Parameters

objectWithContext | Object used to identify context to run on.
runnable | Task to execute when in the appropriate context.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


freeUnusedLibraries (ComLib Class)

 Microsoft SDK for Java

freeUnusedLibraries

This method of the ComLib class releases all unused libraries on the current thread and the virtual machine's host single-threaded apartment thread.

Syntax

public static native void freeUnusedLibraries();


getGuidOf (ComLib class)

 Microsoft SDK for Java

getGuidOf

This method of the ComLib class returns the GUID from the @com.class or @com.interface attributed class, which can then be used for J/Direct operations or other ComLib services.

Syntax

public static _Guid getGuidOf(Class cl);

Return Value

The _Guid of the class if it was declared with @com.class or @com.interface; otherwise null.

Parameters

cl The class for which to return the GUID.

Remarks

This method was added as of versions 2925 through 3167 of the Microsoft virtual machine.


isEqualUnknown (ComLib Class)

 Microsoft SDK for Java

isEqualUnknown

This method of the ComLib class compares the COM identity of two Java objects. If the two objects have equal IUnknown* pointers, they have the same COM identity.

Syntax

public static native boolean isEqualUnknown(Object o1, Object o2);

Return Value

Returns true if the two objects have the same COM identity; otherwise, returns false.

Parameters

o1 | The first object to be compared.
o2 | The second object to be compared.


jcdwClassOffsetOf (ComLib Class)

 Microsoft SDK for Java

jcdwClassOffsetOf

This method of the ComLib Class retrieves the offset of a COM data structure that represents an instance of a Java proxy class. The offset is measured in bytes.

Syntax

public native static int jcdwClassOffsetOf(Class cls, String fieldName);

Return Value

Returns the offset of a COM data structure, measured in bytes.

Parameters

cls | The class object for a Java proxy to a COM data structure.
fieldName | The name of the COM-mapped field.


jcdwClassSizeOf (ComLib Class)

 Microsoft SDK for Java

jcdwClassSizeOf

This method of the ComLib Class retrieves the size (measured in bytes) of a COM data structure that represents instances of the class.

Syntax

public native static int jcdwClassSizeOf(Class cls);

Return Value

Returns the size of a COM data structure, measured in bytes.

Parameters

cls The class object for a Java proxy to a COM data structure.


jcdwOffsetOf (ComLib Class)

 Microsoft SDK for Java

jcdwOffsetOf

This method of the ComLib Class retrieves the offset of a COM data structure (measured in bytes) that is represented by a Java proxy.

Syntax

public native static int jcdwOffsetOf(Object jcdw, String fieldName);

Return Value

Returns the COM data structure offset, measured in bytes.

Parameters

jcdw | The Java proxy to a data structure.
fieldName | The name of the COM-mapped field.


jcdwSizeOf (ComLib Class)

 Microsoft SDK for Java

jcdwSizeOf

This method of the ComLib Class retrieves the size of a COM data structure (measured in bytes) that is represented by a Java proxy.

Syntax

public native static int jcdwSizeOf(Object jcdw);

Return Value

Returns the size of a COM data structure, measured in bytes.

Parameters

jcdw The Java proxy to a data structure.


makeProxyRef (ComLib Class)

 Microsoft SDK for Java

makeProxyRef

This method of the ComLib Class increments the reference count on a COM object.

Syntax

public native static Object makeProxyRef(Object o);

Return Value

Returns a Java callable wrapper that holds a reference to the COM object. When the returned JCW is garbage collected, the reference is dropped.

Parameters

o Any Java object that can be mapped to a COM object.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


ownsCleanup (ComLib Class)

 Microsoft SDK for Java

ownsCleanup

This method of the ComLib Class determines whether Java is responsible for doing cleanup tasks for the COM object.

Syntax

public static boolean ownsCleanup(Object structObj);

Return Value

Returns true if the object is owned by Java; otherwise, returns false.

Parameters

structObj The COM object that is being checked.


ptrRelease (ComLib Class)

 Microsoft SDK for Java

ptrRelease

This method of the ComLib Class releases a reference on an interface, given a raw COM interface pointer.

Syntax

public static native int ptrRelease(int ptr);

Return Value

Returns nothing.

Parameters

ptr A raw COM interface pointer.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


ptrToStruct (ComLib Class)

 Microsoft SDK for Java

ptrToStruct

This method of the ComLib Class maps a raw pointer onto a structure. This method simulates a C-style cast of an arbitrary pointer to a structure.

Syntax

public static native Object ptrToStruct(Class structClass, int ptr, boolean fFreeIndirectNativeMemory);

Return Value

Returns an instance of structClass.

Parameters

structClass | The structure to map the raw pointer to. This class must have been declared using @com.struct.
ptr | The raw pointer to be mapped.
fFreeIndirectNativeMemory | If true, the native memory used for any reference fields (strings, interfaces, and so on) are released appropriately.

Remarks

This method was added as of versions 2925 through 3167 of the Microsoft virtual machine.


ptrToUnknown (ComLib Class)

 Microsoft SDK for Java

ptrToUnknown

This method of the ComLib Class maps a raw pointer to a Java-callable wrapper. This method simulates a C-style cast of an arbitrary pointer to an interface pointer.

Syntax

public static native Object ptrToUnknown(Class unknownClass, int ptr, boolean isFreeThreaded);

Return Value

An instance of interfaceClass.

Parameters

unknownClass | The class that is to be mapped to.
ptr | The raw interface pointer that is mapped.
isFreeThreaded | Indicates whether the object is free or apartment threaded.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


release (ComLib Class)

 Microsoft SDK for Java

release

This method of the ComLib Class forces Java to release all outstanding reference counts on a native COM object. After releasing the reference counts, any attempts to use the COM object through this Java proxy results in an UnsatisfiedLinkError. If the specified object does not wrap a native COM object, this method succeeds but does nothing.

Syntax

public native static void release(Object o);

Parameters

o The Java proxy of a native COM object.

Remarks

If the Java proxy wraps a non–thread-safe native COM object that was created on another thread, the actual release of the object can occur after the release method has returned.


setDataWrapperSize (ComLib Class)

 Microsoft SDK for Java

setDataWrapperSize

This method of the ComLib Class allocates and binds memory to an existing data wrapper.

Syntax

protected static native void setDataWrapperSize(Object DataWrapper, int b);

Parameters

DataWrapper | The wrapper that memory is allocated and bound to.
cb | The memory (measured in bytes) that is bound to the data wrapper.


startMTAThread (ComLib Class)

 Microsoft SDK for Java

startMTAThread

This method of the ComLib Class is similar to the java.lang.Thread.start method. The difference is that Thread.start initializes the thread as a separate single-threaded COM apartment, while startMTAThread initializes the thread inside the multi-threaded COM apartment.

This method replaces ThreadStartMTA, which did not automatically call CoInitializeEx and is now deprecated. startMTAThread calls CoInitializeEx automatically. If you use threadStartMTA and use Microsoft® J/Direct™ to call CoInitializeEx, the Microsoft VM detects this and tags the thread as being inside the MTA to allow proper marshaling.

Syntax

public static native void startMTAThread(Thread thd);

Parameters

thd The Thread to start.

Exceptions

IllegalThreadStateException if the thread was already started.

See Also

java.lang.Thread.run()

java.lang.Thread.stop()

Remarks

This method was added as of versions 2925 through 3167 of the Microsoft virtual machine.


supportsInterface (ComLib Class)

 Microsoft SDK for Java

supportsInterface

This method of the ComLib Class determines whether a COM object supports a particular interface by using that object's QueryInterface method. The interface is not returned because Java interfaces exist only at compile time and are not distinguishable from the main object at run time.

Syntax

public native static boolean supportsInterface(Object pComObject, _Guid id);

Return Value

Returns true if the interface is supported; otherwise, returns false.

Parameters

pComObject | Any Java object that can be mapped to a COM object.
iid | The identifier of the interface to query for.


threadStartMTA (ComLib Class)

 Microsoft SDK for Java

threadStartMTA

Deprecated and replaced by startMTAThread. If you use threadStartMTA and use J/Direct to call CoInitializeEx, the VM detects this and tags the thread as being inside the MTA to allow proper marshaling.

This method of the ComLib Class initializes a thread without initializing COM. This means that the thread's run method must explicitly initialize COM as single-threaded or multi-threaded apartment, using J/Direct to call CoInitializeEx, as demonstrated below:

import com.ms.com.*;
public class RunInMTA implements Runnable
{
    /** @dll.import("ole32", auto) */
    private static native void CoInitializeEx(int pvReserved, int flags);
    /** @dll.import("ole32", auto) */
    private static native void CoUninitialize();
    private static final int COINIT_MULTITHREADED = 0;
    public void run() {
        CoInitializeEx(0, COINIT_MULTITHREADED);
        //  Do work.
        CoUninitialize();
    }
    public static void main(String args[]) {
        Thread t = new Thread(new RunInMTA());
        ComLib.threadStartMTA(t);
    }
}

This method is similar to the Thread.start method, but Thread.start initializes the thread as a separate single-threaded COM apartment.

Syntax

public static native void threadStartMTA(Thread thd);

Parameters

thd The Thread to start.

Exceptions

IllegalThreadStateException if the thread was already started.


unknownToPtr (ComLib Class)

 Microsoft SDK for Java

unknownToPtr

This method of the ComLib Class maps a COM object to a raw pointer to a specified interface, incrementing the object's reference count in the process. The returned interface pointer is callable on the current thread.

Syntax

public static native int unknownToPtr(Object obj, _Guid iid);

Parameters

obj | Any Java object that can be mapped to a COM object.
iid | The IID of the interface to map to.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


Fields (ComLib Class)

 Microsoft SDK for Java

ComLib Class Fields

The ComLib class has the following fields.

IID_IUnknown | Gives the interface identifier (IID) of IUnknown.
IID_IDispatch | Gives the interface identifier (IID) of IDispatch.


ComSuccessException Class (com.ms.com Package)

 Microsoft SDK for Java

ComSuccessException Class

The ComSuccessException Class of the com.ms.com package extends ComException. It wraps an HRESULT, the return type used in most methods in the Component Object Model (COM).

public class ComSuccessException extends ComException
{
  // Constructors
  public ComSuccessException(int hr);
  public ComSuccessException(int hr, String message);
  public ComSuccessException(int hr, String source,
        String helpFile, int helpContext);
  public ComSuccessException(int hr, String description,
        String source, String helpFile, int helpContext);
  public ComSuccessException();
  public ComSuccessException(String message);
}

In a ComSuccessException object, the default value of the stored HRESULT is S_FALSE (0x00000001L). This value indicates the successful completion of a method that returns a boolean value of false.

Note To return an S_OK value when implementing a COM method in Java, code the method to return as it normally would. No special code is required.

Hierarchy

RuntimeException
  |
  +--ComException
     |
     +--ComSuccessException


Constructors (ComSuccessException Class)

 Microsoft SDK for Java

ComSuccessException Class Constructors

The ComSuccessException Class contains the following constructors:

ComSuccessException(int hr)
ComSuccessException(int hr, String message)
ComSuccessException(int hr, String source, String helpFile, int helpContext)
ComSuccessException(int hr, String description, String source, String helpFile, int helpContext)
ComSuccessException()
ComSuccessException(String message)

ComSuccessException(int hr)

Creates a ComSuccessException object that contains the specified HRESULT.

Syntax

public ComSuccessException(int hr);

Parameters

hr The HRESULT that a COM method returns.

ComSuccessException(int hr, String message)

Creates a ComSuccessException object that contains the specified HRESULT and a detail description.

Syntax

public ComSuccessException(int hr, String message);

Parameters

hr | The HRESULT that a COM method returns.
message | The detail description.

ComSuccessException(int hr, String source, String helpFile, int helpContext)

Creates a ComSuccessException object that contains the specified HRESULT, a detail description, a Help file, and the Help context.

Syntax

public ComSuccessException(int hr, String source, String helpFile, int helpContext);

Parameters

hr | The HRESULT that a COM method returns.
source | The detail description.
helpFile | The Help file for the ComSuccessException object.
helpContext | The identifier that indicates the context of the exception.

ComSuccessException(int hr, String description, String source, String helpFile, int helpContext)

Creates a ComSuccessException object that contains the specified HRESULT, detail description, source, a Help file, and Help context.

Syntax

public ComSuccessException(int hr, String description, String source, String helpFile, int helpContext);

Parameters

hr | The HRESULT that the COM method returns.
description | The detail description.
source | The source of the ComSuccessException.
helpFile | The Help file for the ComSuccessException object.
helpContext | The identifier that indicates the context of the exception.

ComSuccessException()

Creates a ComSuccessException object. The default value of the HRESULT stored in the object is S_FALSE (0x00000001L). This value indicates the successful completion of a method that returns a boolean value of false.

Syntax

public ComSuccessException();

ComSuccessException(String message)

Creates a ComSuccessException object that contains the specified detail description. The default value of the HRESULT stored in the object is S_FALSE (0x00000001L). This value indicates the successful completion of a method that returns a boolean value of false.

Syntax

public ComSuccessException(String message);

Parameters

message The detail description.


CONNECTDATA Class (com.ms.com package)

 Microsoft SDK for Java

CONNECTDATA Class

The CONNECTDATA class of the com.ms.com package is the type enumerated through the IEnumConnections.Next method. Each instance describes a connection to a given connection point.

Note The CONNECTDATA class was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public final class CONNECTDATA
{
  // Fields
  public IUnknown pUnk;
  public int dwCookie;
}


Fields (CONNECTDATA Class)

 Microsoft SDK for Java

CONNECTDATA Class Fields

The CONNECTDATA Class contains the following fields.

pUnk | The pointer to the IUnknown interface on a connected advisory sink.
dwCookie | The connection where this value equals the token returned from IConnectionPoint.Advise.


ConnectionPointCookie Class (com.ms.com Package)

 Microsoft SDK for Java

ConnectionPointCookie Class

The ConnectionPointCookie Class of the com.ms.com package provides methods for creating and closing a connection between a source and a sink object.

public class ConnectionPointCookie
{
  // Constructors
  public ConnectionPointCookie(Object source, Object sink,
        Class connectionInterface);

  // Methods
  public native synchronized void disconnect();
  protected void finalize();
}


Constructors (ConnectionPoint Cookie Class)

 Microsoft SDK for Java

ConnectionPoint Cookie Class Constructors

The ConnectionPointCookie Class contains the following constructor:

ConnectionPointCookie(Object source, Object sink, Class connectionInterface)

Creates a connection between the source and the sink object by using the connection interface identifier (IID).

Syntax

public ConnectionPointCookie(Object source, Object sink, Class connectionInterface);

Parameters

source | The source object that is used to make the interface connection.
sink | The sink object that is used to make the interface connection.
connectionInterface | The connection interface that is used to connect the source and the sink objects.


Methods (ConnectionPoint Cookie Class)

 Microsoft SDK for Java

ConnectionPointCookie Class Methods

The ConnectionPointCookie Class contains the following methods:

disconnect explicitly closes the connection between the source and the sink objects.
finalize closes the connection between the source and the sink objects by calling the ConnectionPointCookie object's disconnect method.


disconnect (ConnectionPoint Cookie Class)

 Microsoft SDK for Java

disconnect

This method of the ConnectionPointCookie Class explicitly closes the connection between the source and the sink objects. The connection is closed independently of the garbage collection process.

Syntax

public native synchronized void disconnect();


finalize (ConnectionPoint Cookie Class)

 Microsoft SDK for Java

finalize

This method of the ConnectionPointCookie Class closes the connection between the source and the sink objects by calling the ConnectionPointCookie object's disconnect method. When the object is no longer in processing scope, the Microsoft VM ensures that appropriate cleanup occurs by calling this method.

Syntax

protected void finalize();


COSERVERINFO Class (com.ms.com Package)

 Microsoft SDK for Java

COSERVERINFO Class

The COSERVERINFO class of the com.ms.com package identifies a remote computer resource to the new or enhanced activation functions.

Note The COSERVERINFO class was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public class COSERVERINFO
{
  // Members
  public int dwReserved1;
  public String pwszName;
  public COAUTHINFO pAuthInfo;
  public int dwReserved2;
}

Members

dwReserved1 | Reserved for future use. Must be 0 (zero).
pwszName | The pointer to the name of the computer to be used.
pAuthInfo | Set to a pointer to a COAUTHINFO data type to override the default activation security for remote computer activations. Otherwise, set to NULL to indicate that default values should be used.
dwReserved2 | Reserved for future use. Must be 0 (zero).


CUnknown Class (com.ms.com Package)

 Microsoft SDK for Java

CUnknown Class

The CUnknown class of the com.ms.com package is the default class for Java-callable-wrappers (JCWs) for COM interfaces that are marshaled to Java interfaces. It commonly appears in stack traces and when printing out the return value of some COM operations. It can be used in calls to com.ms.com.Dispatch if it wraps a COM object that implements IDispatch.

public class CUnknown{
}


Dispatch Class (com.ms.com Package)

 Microsoft SDK for Java

Dispatch Class

The Dispach Class of the com.ms.com package enables Java programs to invoke methods and access the properties of any Microsoft® ActiveX® Automation object. (ActiveX Automation objects are ActiveX components that support the IDispatch interface.) Methods in the Dispatch class are static; it is never necessary to instantiate this class.

public class Dispatch
{
  // Fields
  public static final int DISPID_ABOUTBOX;
  public static final int DISPID_AMBIENT_APPEARANCE;
  public static final int DISPID_AMBIENT_AUTOCLIP;
  public static final int DISPID_AMBIENT_BACKCOLOR;
  public static final int DISPID_AMBIENT_CHARSET;
  public static final int DISPID_AMBIENT_CODEPAGE;
  public static final int DISPID_AMBIENT_DISPLAYASDEFAULT;
  public static final int DISPID_AMBIENT_DISPLAYNAME;
  public static final int DISPID_AMBIENT_FONT;
  public static final int DISPID_AMBIENT_FORECOLOR;
  public static final int DISPID_AMBIENT_LOCALEID;
  public static final int DISPID_AMBIENT_MESSAGEREFLECT;
  public static final int DISPID_AMBIENT_PALETTE;
  public static final int DISPID_AMBIENT_SCALEUNITS;
  public static final int DISPID_AMBIENT_SHOWGRABHANDLES;
  public static final int DISPID_AMBIENT_SHOWHATCHING;
  public static final int DISPID_AMBIENT_SUPPORTSMNEMONICS;
  public static final int DISPID_AMBIENT_TEXTALIGN;
  public static final int DISPID_AMBIENT_TRANSFERPRIORITY;
  public static final int DISPID_AMBIENT_UIDEAD;
  public static final int DISPID_AMBIENT_USERMODE;
  public static final int DISPID_APPEARANCE;
  public static final int DISPID_AUTOSIZE;
  public static final int DISPID_BACKCOLOR;
  public static final int DISPID_BACKSTYLE;
  public static final int DISPID_BORDERCOLOR;
  public static final int DISPID_BORDERSTYLE;
  public static final int DISPID_BORDERVISIBLE;
  public static final int DISPID_BORDERWIDTH;
  public static final int DISPID_CAPTION;
  public static final int DISPID_CLICK;
  public static final int DISPID_COLLECT;
  public static final int DISPID_CONSTRUCTOR;
  public static final int DISPID_DBLCLICK;
  public static final int DISPID_DESTRUCTOR;
  public static final int DISPID_DOCLICK;
  public static final int DISPID_DRAWMODE;
  public static final int DISPID_DRAWSTYLE;
  public static final int DISPID_DRAWWIDTH;
  public static final int DISPID_ENABLED;
  public static final int DISPID_ERROREVENT;
  public static final int DISPID_EVALUATE;
  public static final int DISPID_FILLCOLOR;
  public static final int DISPID_FILLSTYLE;
  public static final int DISPID_FONT;
  public static final int DISPID_FORECOLOR;
  public static final int DISPID_HWND;
  public static final int DISPID_KEYDOWN;
  public static final int DISPID_KEYPRESS;
  public static final int DISPID_KEYUP;
  public static final int DISPID_MOUSEDOWN;
  public static final int DISPID_MOUSEICON;
  public static final int DISPID_MOUSEMOVE;
  public static final int DISPID_MOUSEPOINTER;
  public static final int DISPID_MOUSEUP;
  public static final int DISPID_NEWENUM;
  public static final int DISPID_PICTURE;
  public static final int DISPID_PROPERTYPUT;
  public static final int DISPID_READYSTATE;
  public static final int DISPID_READYSTATECHANGE;
  public static final int DISPID_REFRESH;
  public static final int DISPID_TABSTOP;
  public static final int DISPID_TEXT;
  public static final int DISPID_UNKNOWN;
  public static final int DISPID_VALID;
  public static final int DISPID_VALUE;
  public static final int fdexNameCaseSensitive;
  public static final int Get;
  public static final int LOCALE_SYSTEM_DEFAULT;
  public static final int Method;
  public static final int Put;
  public static final int PutRef;

  // Methods
  public static Variant call(Object pDispatch, String dispName);
  public static Variant call(Object pDispatch, String dispName,
        Object o0);
  public static Variant call(Object pDispatch, String dispName,
        Object o0, Object o1);
  public static Variant call(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2);
  public static Variant call(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2, Object o3);
  public static Variant call(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2, Object o3, Object o4);
  public static Variant call(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5);
  public static Variant call(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5, Object o6);
  public static Variant call(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5, Object o6, Object o7);
  public static Variant call(Object pDispatch, int dispid);
  public static Variant call(Object pDispatch, int dispid,
        Object o0);
  public static Variant call(Object pDispatch, int dispid,
        Object o0, Object o1);
  public static Variant call(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2);
  public static Variant call(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2, Object o3);
  public static Variant call(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2, Object o3, Object o4);
  public static Variant call(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5);
  public static Variant call(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5, Object o6);
  public static Variant call(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5, Object o6, Object o7);
  public static Variant callN(Object pDispatch, String dispName,
        Object oArg[]);
  public static Variant callN(Object pDispatch, int dispid,
        Object oArg[]);
  public static Variant callN_casesensitive(Object pDispatch,
        String dispName, Object oArg[]);
  public static void callSub(Object pDispatch, String dispName);
  public static void callSub(Object pDispatch, String dispName,
        Object o0);
  public static void callSub(Object pDispatch, String dispName,
        Object o0, Object o1);
  public static void callSub(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2);
  public static void callSub(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2, Object o3);
  public static void callSub(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2, Object o3, Object o4);
  public static void callSub(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5);
  public static void callSub(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5, Object o6);
  public static void callSub(Object pDispatch, String dispName,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5, Object o6, Object o7);
  public static void callSub(Object pDispatch, int dispid);
  public static void callSub(Object pDispatch, int dispid,
        Object o0);
  public static void callSub(Object pDispatch, int dispid,
        Object o0, Object o1);
  public static void callSub(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2);
  public static void callSub(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2, Object o3);
  public static void callSub(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2, Object o3, Object o4);
  public static void callSub(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5);
  public static void callSub(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5, Object o6);
  public static void callSub(Object pDispatch, int dispid,
        Object o0, Object o1, Object o2, Object o3, Object o4,
        Object o5, Object o6, Object o7);
  public static void callSubN(Object pDispatch, String dispName,
        Object oArg[]);
  public static void callSubN(Object pDispatch, int dispid,
        Object oArg[]);
  public static Variant get(Object pDispatch, String dispName);
  public static Variant get(Object pDispatch, int dispid);
  public static Variant get_casesensitive(Object pDispatch,
        String dispName);
  public static int getIDOfName(Object pDispatch, String dispName);
  public static int[] getIDsOfNames(Object pDispatch, _Guid iid,
        int lcid, String dispNames[]);
  public static Variant invoke(Object pDispatch, _Guid iid,
        String dispName, int dispID, int lcid, int wFlags, Object
        oArg[], int uArgErr[]);
  public static Variant invoke(Object pDispatch, String dispName,
        int wFlags, Object oArg[], int uArgErr[]);
  public static Variant invoke(Object pDispatch, int dispid,
        int wFlags, Object oArg[], int uArgErr[]);
  public static void invokeSub(Object pDispatch, _Guid iid,
        String dispName, int dispID, int lcid, int wFlags, Object
        oArg[], int uArgErr[]);
  public static void invokeSub(Object pDispatch, String dispName,
        int wFlags, Object oArg[], int uArgErr[]);
  public static void invokeSub(Object pDispatch, int dispid,
        int wFlags, Object oArg[], int uArgErr[]);
  public static void invokeSubv(Object pDispatch, _Guid iid, String
        dispName, int dispID, int lcid, int wFlags, Variant
        vArg[], int uArgErr[]);
  public static void invokeSubv(Object pDispatch, String dispName,
        int wFlags, Variant vArg[], int uArgErr[]);
  public static void invokeSubv(Object pDispatch, int dispid,
        int wFlags, Variant vArg[], int uArgErr[]);
  public static Variant invokev(Object pDispatch, _Guid iid, String
        dispName, int dispID, int lcid, int wFlags, Variant
        vArg[], int uArgErr[]);
  public static Variant invokev(Object pDispatch, String dispName,
        int wFlags, Variant vArg[], int uArgErr[], int wFlagsEx);
  public static Variant invokev(Object pDispatch, String dispName,
        int wFlags, Variant vArg[], int uArgErr[]);
  public static Variant invokev(Object pDispatch, int dispid,
        int wFlags, Variant vArg[], int uArgErr[]);
  public static void put(Object pDispatch, String dispName,
        Object val);
  public static void put(Object pDispatch, int dispid, Object val);
  public static void put_casesensitive(Object pDispatch,
        String dispName, Object val);
  public static void putRef(Object pDispatch, String dispName,
        Object val);
  public static void putRef(Object pDispatch, int dispid,
        Object val);
}

Dispatch Class Methods

Although the Dispatch Class includes a large number of methods, three basic methods define its capabilities.

getIDsOfNames

Maps methods or property names to dispids.

invokev

Invokes methods or accesses properties.

invokeSubv

Invokes subroutines.

If one of these methods does not accomplish a given task, neither will any of the other methods in the Dispatch class. Each of the other methods in the class has the same function as one of the three basic methods; however, each of the other methods supplies (wraps) commonly used default parameters for ease of use.

The following table describes the parameters required by the invokev and invokeSubv methods and specifies default values that aren't mentioned in the wrapper method documentation.

Parameters and Default Values

Object pDispatch | Either a Java object that wraps an ActiveX Automation object or a Variant object that can be coerced to such an object by the Variant.toDispatch method. There is no default value for this parameter; every wrapper method requires it.
_Guid iid | The IID of the interface that is invoked. (The interface must derive from IDispatch.) If the value is missing or null, the value of IID_IDispatch is used.
String dispName | The name of the method or property that is invoked. If the value is null, dispID is used to determine the method or property.
int dispID | Indicates the method or property that is invoked. This parameter is ignored if dispName is null.
int lcid | Indicates the locale identifier. Wrapper methods automatically pass Dispatch.LOCALE_SYSTEM_DEFAULT for this value.
int wFlags | Indicates the type of access: must be Dispatch.Method, Dispatch.Get, Dispatch.Put or Dispatch.PutRef. Most of the wrapper methods provide a fixed access that is indicated by the method name: Get methods default to DISPATCH_PROPERTYGET; Put methods default to DISPATCH_PROPERTYPUT; Call methods default to DISPATCH_METHOD.
Variant vArg | The parameters of the method or property accessor. No default value.
int uArgErr[] | If the Automation object rejects a parameter, this array receives the index of the offending parameter; it must be null or a one-element integer array.

Most wrapper methods accept objects other than Variant objects. These objects are converted to the appropriate variant type according to the rules shown in the following table.

Object Conversion Rules

Original Type | Converted Type
null | Converted to VT_EMPTY.
Variant | Passed as is.
Integer | Converted to VT_I4.
String | Converted to VT_BSTR.
Boolean | Converted to VT_BOOL.
Double | Converted to VT_R8.
Float | Converted to VT_R4.
SafeArray | Converted to VT_BYREF|VT_ARRAY|*.
other | Converted to VT_DISPATCH.


Methods (Dispatch Class)

 Microsoft SDK for Java

Dispatch Class Methods

The Dispatch Class contains the following methods:

call invokes a method (that has no parameters) on an ActiveX Automation object.
callN invokes a method on a Microsoft® ActiveX® Automation object.
callN_casesensitive invokes a method on an ActiveX Automation object.
callSub invokes a subroutine (that has no parameters) on an ActiveX Automation object.
callSubN invokes a method on an ActiveX Automation object.
get accesses a property on an ActiveX Automation object.
get_casesensitive accesses a property on an ActiveX Automation object.
getIDOfName maps the name of a dispmember to its dispid.
getIDsOfNames maps the names of a dispmember and its parameter names to their dispids.
invoke invokes a method or accesses a property on an ActiveX Automation object.
invokeSub invokes a subroutine or sets a property on an ActiveX Automation object.
invokeSubv invokes a subroutine or sets a property on an ActiveX Automation object.
invokev invokes a method or accesses a property on an ActiveX Automation object.
put sets a property on an ActiveX Automation object.
put_casesensitive sets a property on an ActiveX Automation object.
putRef sets a property on an ActiveX Automation object.


call (Dispatch Class)

 Microsoft SDK for Java

call

The call method of the Dispatch Class contains the following signatures:

call(Object pDispatch, String dispName)
call(Object pDispatch, String dispName, Object o0)
call(Object pDispatch, String dispName, Object o0, Object o1)
call(Object pDispatch, String dispName, Object o0, Object o1, Object o2)
call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3)
call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4)
call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5)
call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6)
call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7)
call(Object pDispatch, int dispid)
call(Object pDispatch, int dispid, Object o0)
call(Object pDispatch, int dispid, Object o0, Object o1)
call(Object pDispatch, int dispid, Object o0, Object o1, Object o2)
call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3)
call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4)
call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5)
call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6)
call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7)

call(Object pDispatch, String DispName)

Invokes a method (that has no parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, String dispName);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.

call(Object pDispatch, String dispName, Object o0)

Invokes a method (that has one parameter) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, String dispName, Object o0);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.

call(Object pDispatch, String dispName, Object o0, Object o1)

Invokes a method (that has two parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, String dispName, Object o0, Object o1);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.

call(Object pDispatch, String dispName, Object o0, Object o1, Object o2)

Invokes a method (that has three parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.

call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3)

Invokes a method (that has four parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.

call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4)

Invokes a method (that has five parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.

call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5)

Invokes a method (that has six parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.

call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6)

Invokes a method (that has seven parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.
o6 | A parameter of the invoked method.

call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7)

Invokes a method (that has eight parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6,

        Object o7);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.
o6 | A parameter of the invoked method.
o7 | A parameter of the invoked method.

call(Object pDispatch, int dispid)

Invokes a method (that has no parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, int dispid);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.

call(Object pDispatch, int dispid, Object o0)

Invokes a method (that has one parameter) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, int dispid, Object o0);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.

call(Object pDispatch, int dispid, Object o0, Object o1)

Invokes a method (that has two parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, int dispid, Object o0, Object o1);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.

call(Object pDispatch, int dispid, Object o0, Object o1, Object o2)

Invokes a method (that has three parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.

call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3)

Invokes a method (that has four parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | Identifies the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.

call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4)

Invokes a method (that has five parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.

call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5)

Invokes a method (that has six parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.

call(Object pDispatch, int dispid, Object o0,Object o1, Object o2, Object o3, Object o4, Object o5, Object o6)

Invokes a method (that has seven parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.
o6 | A parameter of the invoked method.

call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7)

Invokes a method (that has eight parameters) on an ActiveX Automation object.

Syntax

public static Variant call(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6,

        Object o7);

Return Value

Returns the Variant returned by the invoked method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.
o6 | A parameter of the invoked method.
o7 | A parameter of the invoked method.


callN (Dispatch Class)

 Microsoft SDK for Java

callN

The callN method of the Dispatch Class contains the following signatures:

callN(Object pDispatch, String dispName, Object oArg[])
callN(Object pDispatch, int dispid, Object oArg[])

callN(Object pDispatch, String dispName, Object oArg[])

Invokes a method on an ActiveX Automation object.

Syntax

public static Variant callN(Object pDispatch, String dispName, Object oArg[]);

Return Value

Returns the Variant returned by the method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispname | The name of the invoked method.
oArg | The parameters of the invoked method.

callN(Object pDispatch, int dispid, Object oArg[])

Invokes a method on an ActiveX Automation object.

Syntax

public static Variant callN(Object pDispatch, int dispid, Object oArg[]);

Return Value

Returns the Variant returned by the method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
oArg | The parameters of the invoked method.


callN_casesensitive (Dispatch Class)

 Microsoft SDK for Java

callN_casesensitive

This method of the Dispatch Class invokes a method on an ActiveX Automation object.

This method requires the object to support IDispatchEx. Only IDispatchEx supports case-sensitive name lookups.

Syntax

public static Variant callN_casesensitive(Object pDispatch, String dispName, Object oArg[]);

Return Value

Returns the Variant returned by the method.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispname | The name of the invoked method. This name is case-sensitive.
oArg | The parameters of the invoked method.


callSub (Dispatch Class)

 Microsoft SDK for Java

callSub

The callSub method of the Dispatch Class contains the following signatures:

callSub(Object pDispatch, String dispName)
callSub(Object pDispatch, String dispName, Object o0)
callSub(Object pDispatch, String dispName, Object o0, Object o1)
callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2)
callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3)
callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4)
callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5)
callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6)
callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7)
callSub(Object pDispatch, int dispid)
callSub(Object pDispatch, int dispid, Object o0)
callSub(Object pDispatch, int dispid, Object o0, Object o1)
callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2)
callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3)
callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4)
callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5)
callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6)
callSub(Object pDispatch, int dispid Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7)

callSub(Object pDispatch, String dispName)

Invokes a subroutine (that has no parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, String dispName);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.

callSub(Object pDispatch, String dispName, Object o0)

Invokes a subroutine (that has one parameter) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, String dispName, Object o0);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.

callSub(Object pDispatch, String dispName, Object o0, Object o1)

Invokes a subroutine (that has two parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, String dispName, Object o0, Object o1);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.

callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2)

Invokes a subroutine (that has three parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.

callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3)

Invokes a subroutine (that has four parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.

callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4)

Invokes a subroutine (that has five parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.

callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5)

Invokes a subroutine (that has six parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.

callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6)

Invokes a subroutine (that has seven parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.
o6 | A parameter of the invoked method.

callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7)

Invokes a subroutine (that has eight parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, String dispName, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6,

        Object o7);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.
o6 | A parameter of the invoked method.
o7 | A parameter of the invoked method.

callSub(Object pDispatch, int dispid)

Invokes a subroutine (that has no parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, int dispid);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.

callSub(Object pDispatch, int dispid, Object o0)

Invokes a subroutine (that has one parameter) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, int dispid, Object o0);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.

callSub(Object pDispatch, int dispid, Object o0, Object o1)

Invokes a subroutine (that has two parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, int dispid, Object o0, Object o1);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.

callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2)

Invokes a subroutine (that has three parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.

callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3)

Invokes a subroutine (that has four parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.

callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4)

Invokes a subroutine (that has five parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.

callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5)

Invokes a subroutine (that has six parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.

callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6)

Invokes a subroutine (that has seven parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.
o6 | A parameter of the invoked method.

callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6, Object o7)

Invokes a subroutine (that has eight parameters) on an ActiveX Automation object.

Syntax

public static void callSub(Object pDispatch, int dispid, Object o0, Object o1, Object o2, Object o3, Object o4, Object o5, Object o6,

        Object o7);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
o0 | A parameter of the invoked method.
o1 | A parameter of the invoked method.
o2 | A parameter of the invoked method.
o3 | A parameter of the invoked method.
o4 | A parameter of the invoked method.
o5 | A parameter of the invoked method.
o6 | A parameter of the invoked method.
o7 | A parameter of the invoked method.


callSubN (Dispatch Class)

 Microsoft SDK for Java

callSubN

The callSubN method of the Dispatch Class contains the following signatures:

callSubN(Object pDispatch, String dispName, Object oArg[])
callSubN(Object pDispatch, int dispid, Object oArg[])

callSubN(Object pDispatch, String dispName, Object oArg[])

Invokes a method on an ActiveX Automation object.

Syntax

public static void callSubN(Object pDispatch, String dispName, Object oArg[]);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method.
oArg | The parameters of the invoked method.

callSubN(Object pDispatch, int dispid, Object oArg[])

Invokes a method on an ActiveX Automation object.

Syntax

public static void callSubN(Object pDispatch, int dispid, Object oArg[]);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the invoked method.
oArg | The parameters for the invoked method.


get (Dispatch Class)

 Microsoft SDK for Java

get

The get method of the Dispatch Class contains the following signatures:

get(Object pDispatch, String dispName)
get(Object pDispatch, int dispid)

get(Object pDispatch, String dispName)

Accesses a property on an ActiveX Automation object.

Syntax

public static Variant get(Object pDispatch, String dispName);

Return Value

Returns the value of the property.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the property that is accessed.

get(Object pDispatch, int dispid)

Accesses a property on an ActiveX Automation object.

Syntax

public static Variant get(Object pDispatch, int dispid);

Return Value

Returns the value of the property.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the property that is accessed.


get_casesensitive (Dispatch Class)

 Microsoft SDK for Java

get_casesensitive

This method of the Dispatch Class accesses a property on an ActiveX Automation object.

This method requires the object to support IDispatchEx. Only IDispatchEx supports case-sensitive name lookups.

Syntax

public static Variant get_casesensitive(Object pDispatch, String ispName);

Return Value

Returns the value of the property.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the property that is accessed.


getIDOfName (Dispatch Class)

 Microsoft SDK for Java

getIDOfName

This method of the Dispatch Class maps the name of a dispmember to its dispid. This method is a direct wrapper around the IDispatch::GetIDsOfNames call.

Syntax

public static int getIDOfName(Object pDispatch, String dispName);

Return Value

Returns the dispid that corresponds to the specified name.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name that is resolved.

Exceptions

A ComFailException is thrown if the name is not recognized by the object.


getIDsOfNames (Dispatch Class)

 Microsoft SDK for Java

getIDsOfNames

This method of the Dispatch Class maps the names of a dispmember and parameter names to their dispids. This method is a direct wrapper around the IDispatch::GetIDsOfNames call.

Syntax

public static int[] getIDsOfNames(Object pDispatch, _Guid iid, int lcid, String dispNames[]);

Return Value

Returns an array of resolved dispids.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
iid | The interface to query; if null, the interface identifier defaults to IID_IDispatch.
lcid | The locale identifier.
dispNames | The array of names to resolve.

Exceptions

A ComFailException is thrown if a name is not recognized by the object.


invoke (Dispatch Class)

 Microsoft SDK for Java

invoke

The invoke method of the Dispatch Class contains the following signatures:

invoke(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Object oArg[], int uArgErr[])
invoke(Object pDispatch, String dispName, int wFlags, Object oArg[], int uArgErr[])
invoke(Object pDispatch, int dispid, int wFlags, Object oArg[], int uArgErr[])

invoke(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Object oArg[], int uArgErr[])

Invokes a method or accesses a property on an ActiveX Automation object. This method is essentially a direct wrapper around the IDispatch::Invoke method. The difference between this method and invokev is that this method accepts arbitrary objects rather than Variant objects as arguments to the invoked method.

Syntax

public static Variant invoke(Object pDispatch, _Guid iid, String ispName, int dispID, int lcid, int wFlags, Object oArg[], int uArgErr[]);

Return Value

Returns the Variant object returned by the method or property access.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
iid | The identifier of the interface that is called. If the value is null, defaults to IID_IDispatch.
dispName | The name of the method or property that is invoked. If the value is null, dispID is used.
dispID | The identifier of the method or property. Unless dispName is null, this parameter is ignored.
lcid | The locale ID.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
oArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.

invoke(Object pDispatch, String dispName, int wFlags, Object oArg[], int uArgErr[])

Invokes a method or accesses a property on an ActiveX Automation object. This method is essentially a direct wrapper around the IDispatch::Invoke method. This method is easier to call than the full invokev method and enables you to pass arbitrary objects rather than Variants. However, the method does not enable you to specify the interface IID or the locale, and the method must be identified by name.

Syntax

public static Variant invoke(Object pDispatch, String dispName, int Flags, Object oArg[], int uArgErr[]);

Return Value

Returns the Variant returned by the method or property access.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the method or property.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
oArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.

invoke(Object pDispatch, int dispid, int wFlags, Object oArg[], int uArgErr[])

Invokes a method or accesses a property on an ActiveX Automation object. This method is essentially a direct wrapper around the IDispatch::Invoke method. This method is easier to call than the full invokev method because it allows you to pass arbitrary objects rather than Variant objects. However, this method does not enable you to specify the interface IID or the locale, and the method must be identified by dispid.

Syntax

public static Variant invoke(Object pDispatch, int dispid, int wFlags, Object oArg[], int uArgErr[]);

Return Value

Returns the Variant object returned by the method or property access.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the method or property.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
oArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.


invokeSub (Dispatch Class)

 Microsoft SDK for Java

invokeSub

The invokesub method of the Dispatch Class contains the following signatures:

invokeSub(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Object oArg[], int uArgErr[])
invokeSub(Object pDispatch, String dispName, int wFlags, Object oArg[], int uArgErr[])
invokeSub(Object pDispatch, int dispid, int wFlags, Object oArg[], int uArgErr[])

invokeSub(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Object oArg[], int uArgErr[])

Invokes a subroutine or sets a property on an ActiveX Automation object. The difference between this method and invoke is that this method accepts arbitrary objects rather than Variant objects as arguments to the invoked method. This method is very similar to invokev, but it does not accept a return value from the method.

Note Some language implementations do not invoke subroutines as if they were functions. If the invoked method does not return a value, use invokeSub.

Syntax

public static void invokeSub(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Object oArg[], int uArgErr[]);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
iid | The identifier of the interface that is called. If the value is null, the interface identifier defaults to IID_IDispatch.
dispName | The name of the method or property that is invoked. If the value is null, dispID is used.
dispID | The identifier of the method or property. Unless dispName is null, this parameter is ignored.
lcid | The locale ID.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
oArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.

invokeSub(Object pDispatch, String dispName, int wFlags, Object oArg[], int uArgErr[])

Invokes a subroutine or sets a property on an ActiveX Automation object. This method is very similar to invokev, but it does not accept a return value from the method. Some language implementations do not invoke subroutines as if they were functions. This method is easier to call than the full invokeSub method and enables you to pass arbitrary objects rather than Variant objects. However, the method does not enable you to specify the interface identifier or the locale, and the method must be identified by name.

Note If the invoked method does not return a value, use invokeSub to avoid problems.

Syntax

public static void invokeSub(Object pDispatch, String dispName, int wFlags, Object oArg[], int uArgErr[]);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the method or property.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
oArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.

invokeSub(Object pDispatch, int dispid, int wFlags, Object oArg[], int uArgErr[])

Invokes a subroutine or sets a property on an ActiveX Automation object. This method is very similar to invokev, but it does not accept a return value from the method. Some language implementations do not invoke subroutines as if they were functions. If the method does not return a value, use invokeSub to avoid problems. This method is easier to call than the full invokeSub(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Object oArg[], int uArgErr[]) method and enables you to pass arbitrary objects rather than Variant objects. However, the method does not enable you to specify the interface IID or the locale, and the method must be identified by dispid.

Syntax

public static void invokeSub(Object pDispatch, int dispid, int wFlags, Object oArg[], int uArgErr[]);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the method or property.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
oArg | The arguments to the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.


invokeSubv (Dispatch Class)

 Microsoft SDK for Java

invokeSubv

The invokeSubv method of the Dispatch Class contains the following signatures:

invokeSubv(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Variant vArg[], int uArgErr[])
invokeSubv(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[])
invokeSubv(Object pDispatch, int dispid, int wFlags, Variant vArg[], int uArgErr[])

invokeSubv(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Variant vArg[], int uArgErr[])

Invokes a subroutine or sets a property on an ActiveX Automation object. This method is very similar to invokev, but it does not accept a return value from the method.

Syntax

public static void invokeSubv(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Variant vArg[], int uArgErr[]);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
iid | The identifier of the interface that is called. If the value is null, this parameter defaults to IID_IDispatch.
dispName | The name of the method or property that is invoked. If the value is null, dispID is used.
dispID | The identifier of the method or property. Unless dispName is null, this parameter is ignored.
lcid | The locale ID.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
vArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.

Remarks

This method is very similar to invokev, but it does not accept a return value from the method. Some language implementations distinguish between functions and subroutines; subroutines written in such languages cannot be called as if they were functions. If the invoked method does not return a value, use invokeSubv to avoid this problem.

invokeSubv(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[])

Invokes a subroutine or sets a property on an ActiveX Automation object. This method is easier to call than the full invokeSubv method, but it does not allow you to specify the interface IID or the locale, and the method must be identified by name.

Syntax

public static void invokeSubv(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[]);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the method or property.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
vArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.

Remarks

This method is very similar to invokev, but it does not accept a return value from the method. Some language implementations distinguish between functions and subroutines; subroutines written in such languages cannot be called as if they were functions. If the invoked method does not return a value, use invokeSubv to avoid this problem.

invokeSubv(Object pDispatch, int dispid, int wFlags, Variant vArg[], int uArgErr[])

Invokes a subroutine or sets a property on an ActiveX Automation object. This method is very similar to invokev, but it does not accept a return value from the method. Some language implementations do not invoke subroutines as if they were functions. If the invoked method does not return a value, use invokeSubv to avoid problems. This method is easier to call than the full invokeSubv method. However, it does not enable you to specify the interface identifier or the locale, and the method must be identified by dispid.

Syntax

public static void invokeSubv(Object pDispatch, int dispid, int wFlags, Variant vArg[], int uArgErr[]);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispID | The identifier of the method or property.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
vArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.


invokev (Dispatch Class)

 Microsoft SDK for Java

invokev

The invokev method of the Dispatch Class contains the following signatures:

invokev(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Variant vArg[], int uArgErr[])
invokev(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[], int wFlagsEx)
invokev(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[])
invokev(Object pDispatch, int dispid, int wFlags, Variant vArg[], int uArgErr[])

invokev(Object pDispatch, _Guid iid, String dispName, int dispID, int lcid, int wFlags, Variant vArg[], int uArgErr[])

Invokes a method or accesses a property on an ActiveX Automation object. This method is essentially a direct wrapper around the IDispatch::Invoke method.

Syntax

public static Variant invokev(Object pDispatch, _Guid iid, String , int dispID, int lcid, int wFlags, Variant vArg[], int uArgErr[]);

Return Value

Returns the Variant returned by the method or property access.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
iid | The identifier of the interface that is called. If the value is null, it defaults to IID_IDispatch.
dispName | The name of the method or property that is invoked. If the value is null, dispID is used.
dispID | The identifier that identifies the method or property; ignored unless dispName is null.
lcid | The locale ID.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
vArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.

invokev(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[], int wFlagsEx)

Invokes a method or accesses a property on an ActiveX Automation object. This method is essentially a direct wrapper around the IDispatch::Invoke method. This method is easier to call than the full invokev method. It does not, however, enable you to specify the IID or the locale, and the method must be identified by name.

Syntax

public static Variant invokev(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[], int wFlagsEx);

Return Value

Returns the variant that is returned by the method or property access.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the invoked method or property.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
vArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.
wFlagsEx | The extended flags that are passed to IDispatchEx.

invokev(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[])

Invokes a method or accesses a property on an ActiveX Automation object. This method is essentially a direct wrapper around the IDispatch::Invoke method. This method is easier to call than the full invokev method. However, it does not enable specifying the interface IID or the locale, and the method must be identified by name.

Syntax

public static Variant invokev(Object pDispatch, String dispName, int wFlags, Variant vArg[], int uArgErr[]);

Return Value

Returns the Variant returned by the method or property access.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the method or property.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
vArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.

invokev(Object pDispatch, int dispid, int wFlags, Variant vArg[], int uArgErr[])

Invokes a method or accesses a property on an ActiveX Automation object. This method is essentially a direct wrapper around the IDispatch::Invoke method. This method is easier to call than the full invokev method. However, it does not enable you to specify the interface IID or the locale, and the method must be identified by dispid.

Syntax

public static Variant invokev(Object pDispatch, int dispid, int wFlags, Variant vArg[], int uArgErr[]);

Return Value

Returns the Variant object returned by the method or property access.

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispID | The identifier of the method or property.
wFlags | The type of access, which must be Dispatch.Method, Dispatch.Get, Dispatch.Put, or Dispatch.PutRef.
vArg | The arguments of the method or property.
uArgErr | An optional one-element array. If an error occurs, uArgErr receives the index of the offending parameter.


put (Dispatch Class)

 Microsoft SDK for Java

put

The put method of the Dispatch Class contains the following signatures:

put(Object pDispatch, String dispName, Object val)
put(Object pDispatch, int dispid, Object val)

put(Object pDispatch, String dispName, Object val)

Sets a property on an ActiveX Automation object.

Syntax

public static void put(Object pDispatch, String dispName, Object val);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the property that is set by this method.
val | The value to assign to the property.

put(Object pDispatch, int dispid, Object val)

Sets a property on an ActiveX Automation object.

Syntax

public static void put(Object pDispatch, int dispid, Object val);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the property that is set by this method.
val | The value to assign to the property.


put_casesensitive (Dispatch Class)

 Microsoft SDK for Java

put_casesensitive

This method of the Dispatch Class sets a property on an ActiveX Automation object.

This method requires the object to support IDispatchEx. Only IDispatchEx supports case-sensitive name lookups.

Syntax

public static void put_casesensitive(Object pDispatch, String dispName, Object val);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the property that is set by this method.
val | The value to assign to the property.


putRef (Dispatch Class)

 Microsoft SDK for Java

putRef

The putRef method of the Dispatch Class contains the following signatures:

putRef(Object pDispatch, String dispName, Object val)
putRef(Object pDispatch, int dispid, Object val)

putRef(Object pDispatch, String dispName, Object val)

Sets an object property on an ActiveX Automation object.

Syntax

public static void putRef(Object pDispatch, String dispName, Object val);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispName | The name of the property that is set by this method.
val | The value to assign to the property.

putRef(Object pDispatch, int dispid, Object val)

Sets an object property on an ActiveX Automation object.

Syntax

public static void putRef(Object pDispatch, int dispid, Object val);

Parameters

pDispatch | The Java proxy of the ActiveX Automation object.
dispid | The identifier of the property that is set by this method.
val | The value to assign to the property.


Fields (Dispatch Class)

 Microsoft SDK for Java

Dispatch Class Fields

The Dispatch Class contains the following fields.

DISPID_ABOUTBOX | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_APPEARANCE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_AUTOCLIP | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_BACKCOLOR | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_CHARSET | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_CODEPAGE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_DISPLAYASDEFAULT | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_DISPLAYNAME | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_FONT | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_FORECOLOR | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_LOCALEID | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_MESSAGEREFLECT | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_PALETTE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_SCALEUNITS | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_SHOWGRABHANDLES | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_SHOWHATCHING | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_SUPPORTSMNEMONICS | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_TEXTALIGN | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_TRANSFERPRIORITY | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_UIDEAD | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AMBIENT_USERMODE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_APPEARANCE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_AUTOSIZE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_BACKCOLOR | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_BACKSTYLE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_BORDERCOLOR | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_BORDERSTYLE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_BORDERVISIBLE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_BORDERWIDTH | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_CAPTION | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_CLICK | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_COLLECT | A standard DISPID defined in OLECTL.H in the MSDN™ Library .
DISPID_CONSTRUCTOR | The DISPID that indicates the constructor function.
DISPID_DBLCLICK | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_DESTRUCTOR | The DISPID that indicates the destructor function.
DISPID_DOCLICK | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_DRAWMODE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_DRAWSTYLE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_DRAWWIDTH | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_ENABLED | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_ERROREVENT | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_EVALUATE | The DISPID that indicates the evaluate method.
DISPID_FILLCOLOR | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_FILLSTYLE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_FONT | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_FORECOLOR | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_HWND | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_KEYDOWN | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_KEYPRESS | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_KEYUP | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_MOUSEDOWN | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_MOUSEICON | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_MOUSEMOVE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_MOUSEPOINTER | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_MOUSEUP | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_NEWENUM | The DISPID that indicates the _NEWENUM property.
DISPID_PICTURE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_PROPERTYPUT | The DISPID that indicates the parameter that receives the value of an assignment in a PROPERTYPUT.
DISPID_READYSTATE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_READYSTATECHANGE | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_REFRESH | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_TABSTOP | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_TEXT | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_UNKNOWN | The DISPID returned by IDispatch::GetIDsOfNames to indicate that a member or parameter name was not found.
DISPID_VALID | A standard DISPID defined in OLECTL.H in the MSDN™ Library.
DISPID_VALUE | The DISPID that indicates the default member for the object.
fdexNameCaseSensitive | The value that corresponds to IDispatchEx flag fdexNameCaseSensitive
Get | The value that corresponds to the ActiveX constant DISPATCH_GET.
LOCALE_SYSTEM_DEFAULT | The value that corresponds to the ActiveX constant LOCALE_SYSTEM_DEFAULT; it functions as the default value for locale-id.
Method | The value that corresponds to the ActiveX constant DISPATCH_METHOD.
Put | The value that corresponds to the ActiveX constant DISPATCH_PUT.
PutRef | The value that corresponds to the ActiveX constant DISPATCH_PUTREF.


DispatchProxy Class (com.ms.com Package)

 Microsoft SDK for Java

DispatchProxy Class

The DispatchProxy Class of the com.ms.com package wraps a dispatchable object with a Java interface.

public final class DispatchProxy
{
  // Constructors
  public DispatchProxy(Class exposedInterface, Object dispatch);
  public DispatchProxy(Class exposedInterface, Object dispatch,
        _Guid iid, Method dispIDMethods[], int dispIDs[]);
  public DispatchProxy(Class exposedInterface, Object dispatch,
        _Guid iid, Method dispIDMethods[], int dispIDs[], boolean
        filterNonDispatchErrors);

  // Methods
  public void disconnectAsEventSink();
  protected native void finalize();
  public Class getExposedInterface();
  public Object getUnderlyingObject();
}


Constructors (DispatchProxy Class)

 Microsoft SDK for Java

DispatchProxy Class Constructors

The DispatchProxy Class contains the following constructors:

DispatchProxy(Class exposedInterface, Object dispatch)
DispatchProxy(Class exposedInterface, Object dispatch, _Guid iid, Method dispIDMethods[], int dispIDs[])
DispatchProxy(Class exposedInterface, Object dispatch, _Guid iid, Method dispIDMethods[], int dispIDs[], boolean filterNonDispatchErrors)

DispatchProxy(Class exposedInterface, Object dispatch)

Allocates a new DispatchProxy object.

Syntax

public DispatchProxy(Class exposedInterface, Object dispatch);

Parameters

exposedInterface | The signature of the IDispatch call.
dispatch | The object that IDispatch calls.

Remarks

Calls against the object on the exposed interface are translated to IDispatch::Invoke calls on the supplied dispatchable object. For this constructor, the first call to each method calls IDispatch::GetIDsOfNames to find the DISPID of the method, which is then cached. The IDispatch calls are made on the object's IID_IDispatch identity.

DispatchProxy(Class exposedInterface, Object dispatch, _Guid iid, Method dispIDMethods[], int dispIDs[])

Allocates a new DispatchProxy object. All calls against this object on the exposed interface are translated to IDispatch::Invoke calls on the supplied dispatchable object.

The parameters dispIDMethods and DispIDs supply lists of methods and DISPIDs. These lists are used to pre-assign the DISPIDs to the methods in the exposed interface. Unassigned methods call IDispatch::GetIDsOfNames to find the DISPID of the method, which is then cached. IDispatch calls are made on the supplied interface identifier, which defaults to IID_IDispatch.

Syntax

public DispatchProxy(Class exposedInterface, Object dispatch, _Guid iid, Method dispIDMethods[], int dispIDs[]);

Parameters

exposedInterface | The signature of the IDispatch call.
dispatch | The object that IDispatch calls.
iid | The supplied interface identifier, which defaults to IID_IDispatch.
dispIDMethods | The list of methods used to pre-assign the DISPIDs to the methods of the exposed interface.
dispIDs | The list of DISPIDs used to pre-assign the DISPIDs to the methods of the exposed interface.

DispatchProxy(Class exposedInterface, Object dispatch, _Guid iid, Method dispIDMethods[], int dispIDs[], boolean filterNonDispatchErrors)

Allocates a new DispatchProxy object. All calls against this object on the exposed interface are translated to IDispatch::Invoke calls on the supplied dispatchable object.

The parameters dispIDMethods and DispIDs supply lists of methods and DISPIDs. These lists are used to pre-assign the DISPIDs to the methods in the exposed interface. Unassigned methods call IDispatch::GetIDsOfNames to find the DISPID of the method, which is then cached. IDispatch calls are made on the supplied interface identifier, which defaults to IID_IDispatch.

Syntax

public DispatchProxy(Class exposedInterface, Object dispatch, _Guid iid, Method dispIDMethods[], int dispIDs[],

        boolean filterNonDspatchErrors);

Parameters

exposedInterface | The signature of the IDispatch call.
dispatch | The object that IDispatch calls.
iid | The dispatch interface identifier, which defaults to IID_IDispatch if null is passed.
dispIDMethods | The list of methods used to pre-assign the DISPIDs to the methods of the exposed interface.
dispIDs | The list of DISPIDs used to pre-assign the DISPIDs to the methods of the exposed interface.
filterNonDispatchErrors | Indicates whether an error HRESULT besides DISP_E_EXCEPTION should generate Java exceptions when calling IDispatch.


Methods (DispatchProxy Class)

 Microsoft SDK for Java

DispatchProxy Class Methods

The DispatchProxy Class contains the following methods:

disconnectAsEventSink disconnects the current object from the underlying object.
finalize releases native resources associated with the current object.
getExposedInterface retrieves the Java interface that is used as the template for IDispatch calls.
getUnderlyingObject retrieves the underlying dispatch object that is called by IDispatch.


disconnectAsEventSink (DispatchProxy Class)

 Microsoft SDK for Java

disconnectAsEventSink

This method of the DispatchProxy Class disconnects the current object from the underlying object. (The underlying object is the object that was originally passed to the DispatchProxy constructor via the dispatch parameter.)

Syntax

public void disconnectAsEventSink();


finalize (DispatchProxy Class)

 Microsoft SDK for Java

finalize

This method of the DispatchProxy Class releases native resources associated with the current object.

Syntax

protected native void finalize();


getExposedInterface (DispatchProxy Class)

 Microsoft SDK for Java

getExposedInterface

This method of the DispatchProxy Class retrieves the Java interface that is used as the template for IDispatch calls.

Syntax

public Class getExposedInterface();

Return Value

Returns the Java interface that is used as the template for IDispatch calls.


getUnderlyingObject (DispatchProxy Class)

 Microsoft SDK for Java

getUnderlyingObject

This method of the DispatchProxy Class retrieves the underlying dispatch object that is called by IDispatch. This object was passed to the DispatchProxy constructor via the dispatch parameter.

Syntax

public Object getUnderlyingObject();

Return Value

Returns the underlying dispatchable object.


LicenseMgr Class (com.ms.com Package)

 Microsoft SDK for Java

LicenseMgr Class

The LicenseMgr Class of the com.ms.com package works with the ILicenseMgr interface to enable you to use licensed Component Object Model (COM) components or controls in your Java application.

public final class LicenseMgr implements IUnknown,ILicenseMgr
{
  // Methods
  public native IUnknown createFromPackage(int index,
        IUnknown punkOuter, int ctxFlags);
  public native IUnknown createInstance(String clsid,
        IUnknown punkOuter, int ctxFlags);
  public native IUnknown createWithLic(String lic, String clsid,
        IUnknown punkOuter, int ctxFlags);
  public native void setPackage(String url);
}

Example

In the LicenseMgr class, methods are not called directly. Instead, you create an instance of LicenseMgr and use the ILicenseMgr interface to manipulate the instance, as in the following example:

ILicenseMgr licmgr = (ILicenseMgr)new LicenseMgr();
   // use licmgr interface

For more information on how to use licensed COM components, see the ILicenseMgr interface.


Methods (LicenseMgr Class)

 Microsoft SDK for Java

LicenseMgr Class Methods

The LicenseMgr contains the following methods:

createFromPackage creates a package.
createInstance creates an instance of a specific COM class.
createWithLic creates an instance of a licensed control.
setPackage sets the package for a specific URL.


createFromPackage (LicenseMgr Class)

 Microsoft SDK for Java

createFromPackage

This method of the LicenseMgr Class creates a package. This method cannot be invoked directly. You must first cast the LicenseMgr object to the ILicenseMgr interface and invoke the method through the interface.

Syntax

public native IUnknown createFromPackage(int index, IUnknown punkOuter, int ctxFlags);

Return Value

Returns the newly created package.

Parameters

index | The index of the package.
punkOuter | The aggregating object if the object is created as part of an aggregate; otherwise, the value is null.
ctxFlags | The ComContext value that represents the context that the new object should be created in.


createInstance (LicenseMgr Class)

 Microsoft SDK for Java

createInstance

This method of the LiscenseMgr Class creates an instance of a specific COM class. This method cannot be invoked directly. You must first cast the LicenseMgr object to the ILicenseMgr interface and invoke the method through the interface.

Syntax

public native IUnknown createInstance(String clsid, IUnknown punkOuter, int ctxFlags);

!WARNING In general, this method should not be called. The best way to create an instance of a COM class is to use the new operator on the Java wrapper generated by the jactivex tool.

Return Value

Returns an instance of the specified COM class.

Parameters

clsid | The class identifier (CLSID) of the instantiated COM class.
punkOuter | The aggregating object if the object is being created as part of an aggregate; otherwise, the value is null.
ctxFlags | The ComContext value that represents the context that the new object is created in.

Exceptions

com.ms.com.ComFailException if an error occurs while instantiating the class.


createWithLic (LicenseMgr Class)

 Microsoft SDK for Java

createWithLic

This method of the LicenseMgr Class creates an instance of a licensed control. This method cannot be invoked directly. You must first cast the LicenseMgr object to the ILicenseMgr interface and invoke the method through the interface.

Syntax

public native IUnknown createWithLic(String lic, String clsid, IUnknown punkOuter, int ctxFlags);

Return Value

Returns a new instance of the specified licensed COM class.

Parameters

lic | The license for the instantiated COM class.
clsid | The class identifier (CLSID) of the instantiated COM class.
punkOuter | The aggregating object if the object is being created as part of an aggregate; otherwise, the value is null.
ctxFlags | The ComContext value that represents the context that the new object is created in.

Exceptions

com.ms.com.ComFailException if an error occurs while instantiating the class.


setPackage (LicenseMgr Class)

 Microsoft SDK for Java

setPackage

This method of the LicenseMgr Class sets the package for a specific URL. This method cannot be invoked directly. You must first cast the LicenseMgr object to the ILicenseMgr interface and invoke the method through the interface.

Syntax

public native void setPackage(String url);

Parameters

url The Uniform Resource Locator (URL) of the package.


LICINFO Class (com.ms.com package)

 Microsoft SDK for Java

LICINFO Class

The LICINFO class of the com.ms.com package describes the licensing behavior of a class factory that supports licensing.

public class LICINFO
{
  // Fields
  public int cbLicInfo;
  public boolean fLicVerified;
  public boolean fRuntimeKeyAvail;
}


Fields (LICINFO Class)

 Microsoft SDK for Java

LICINFO Class Fields

The LICINFO class has the following fields.

Field | Description
cbLicInfo | Size of the LICINFO structure. Default is 12.
fLicVerified | Determines whether a full machine license exists so that calls to CreateInstance and RequestLicKey will succeed. If TRUE, the full machine license exists. Thus, objects can be created freely. and a license key is available if fRuntimeKeyAvail is also TRUE. If FALSE, this class factory cannot create any instances of objects on this machine unless the proper license key is passed to CreateInstanceLic.
fRuntimeKeyAvail | Determines whether this class factory allows the creation of its objects on a unlicensed machine through the use of a license key. If TRUE, RequestLicKey can be called to obtain the key. If FALSE, objects can be created only on a fully licensed machine.


MULTI_QI Class (com.ms.com package)

 Microsoft SDK for Java

MULTI_QI Class

The MULTI_QI class of the com.ms.com package optimizes network performance by providing multiple interface pointers to remote activation functions. This is better than providing a single IID as input and a single pointer to the requested interface on the object as output, as do local computer activation functions. This allows a set of pointers to interfaces to be returned from the same object in a single round-trip to the server. In network scenarios, requesting multiple interfaces at the time of object construction can save considerable time over using a number of calls to the QueryInterface method for unique interfaces, each of which would require a round-trip to the server.

Note The MULTI_QI class was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public class MULTI_QI
{
  // Members
  public _Guid pIID;
  public IUnknown pItf;
  public int hr;
}

Members

[in] pIID | The pointer to an interface identifier.
[out] pItf | The pointer to the interface requested in pIID. Must be set to NULL on entry.
[out] hr | The return value of the QueryInterface call made to satisfy the request for the interface requested in pIID. Common return values are S_OK and E_NOINTERFACE. Must be set to 0 (zero) on entry.


SafeArray Class (com.ms.com Package)

 Microsoft SDK for Java

SafeArray Class

The SafeArray Class of the com.ms.com Package wraps a Microsoft® ActiveX® Automation data structure. It bridges Java with the Automation object by wrapping a pointer to the native SAFEARRAY data structure. It does not duplicate the array data in Java form. This approach minimizes translation overhead but imposes extra rules on SafeArray usage.

public final class SafeArray
{
  // Constructors
  public SafeArray(int vt);
  public SafeArray(int vt, int celems);
  public SafeArray(int vt, int celems1, int celems2);
  public SafeArray(int vt, int lbounds[], int celems[]);
  public SafeArray(String s);
  public native int getPhysicalSafeArray();

  // Methods
  public native String asString();
  public Object clone();
  public void destroy();
  protected void finalize();
  public void fromBooleanArray(boolean ja[]);
  public void fromByteArray(byte ja[]);
  public void fromCharArray(char ja[]);
  public void fromDoubleArray(double ja[]);
  public void fromFloatArray(float ja[]);
  public void fromIntArray(int ja[]);
  public void fromShortArray(short ja[]);
  public void fromStringArray(String ja[]);
  public void fromVariantArray(Variant ja[]);
  public native boolean getBoolean(int sa_idx);
  public boolean getBoolean(int sa_idx1, int sa_idx2);
  public void getBooleans(int sa_idx, int nelems, boolean ja[], int
        ja_start);
  public byte getByte(int sa_idx);
  public byte getByte(int sa_idx1, int sa_idx2);
  public void getBytes(int sa_idx, int nelems, byte ja[],
        int ja_start);
  public char getChar(int sa_idx);
  public char getChar(int sa_idx1, int sa_idx2);
  public void getChars(int sa_idx, int nelems, char ja[],
        int ja_start);
  public native double getDouble(int sa_idx);
  public double getDouble(int sa_idx1, int sa_idx2);
  public void getDoubles(int sa_idx, int nelems, double ja[],
        int ja_start);
  public int getElemSize();
  public int getFeatures();
  public native float getFloat(int sa_idx);
  public float getFloat(int sa_idx1, int sa_idx2);
  public void getFloats(int sa_idx, int nelems, float ja[],
        int ja_start);
  public native int getInt(int sa_idx);
  public int getInt(int sa_idx1, int sa_idx2);
  public void getInts(int sa_idx, int nelems, int ja[],
        int ja_start);
  public int getLBound();
  public int getLBound(int dim);
  public int getNumDim();
  public int getNumLocks();
  public short getShort(int sa_idx);
  public short getShort(int sa_idx1, int sa_idx2);
  public void getShorts(int sa_idx, int nelems, short ja[],
        int ja_start);
  public String getString(int sa_idx);
  public String getString(int sa_idx1, int sa_idx2);
  public void getStrings(int sa_idx, int nelems, String ja[],
        int ja_start);
  public int getUBound();
  public int getUBound(int dim);
  public Variant getVariant(int sa_idx);
  public Variant getVariant(int sa_idx1, int sa_idx2);
  public void getVariants(int sa_idx, int nelems, Variant ja[], int
        ja_start);
  public int getvt();
  public void reinit(SafeArray sa);
  public void reinterpretType(int vt);
  public native void setBoolean(int idx, boolean val);
  public void setBoolean(int idx1, int idx2, boolean val);
  public void setBooleans(int sa_idx, int nelems, boolean ja[], int
        ja_start);
  public void setByte(int idx, byte val);
  public void setByte(int idx1, int idx2, byte val);
  public void setBytes(int sa_idx, int nelems, byte ja[],
        int ja_start);
  public void setChar(int idx, char val);
  public void setChar(int idx1, int idx2, char val);
  public void setChars(int sa_idx, int nelems, char ja[],
        int ja_start);
  public native void setDouble(int idx, double val);
  public void setDouble(int idx1, int idx2, double val);
  public void setDoubles(int sa_idx, int nelems, double ja[],
        int ja_start);
  public native void setFloat(int idx, float val);
  public void setFloat(int idx1, int idx2, float val);
  public void setFloats(int sa_idx, int nelems, float ja[],
        int ja_start);
  public native void setInt(int idx, int val);
  public void setInt(int idx1, int idx2, int val);
  public void setInts(int sa_idx, int nelems, int ja[],
        int ja_start);
  public void setShort(int idx, short val);
  public void setShort(int idx1, int idx2, short val);
  public void setShorts(int sa_idx, int nelems, short ja[],
        int ja_start);
  public void setString(int idx, String val);
  public void setString(int idx1, int idx2, String val);
  public void setStrings(int sa_idx, int nelems, String ja[],
        int ja_start);
  public void setVariant(int idx, Variant val);
  public void setVariant(int idx1, int idx2, Variant val);
  public void setVariants(int sa_idx, int nelems, Variant ja[], int
        ja_start);
  public boolean[] toBooleanArray();
  public byte[] toByteArray();
  public char[] toCharArray();
  public double[] toDoubleArray();
  public float[] toFloatArray();
  public int[] toIntArray();
  public short[] toShortArray();
  public String toString();
  public String[] toStringArray();
  public Variant[] toVariantArray();
}

The rules for using this class are simple, but they must be followed:

  1. A Java method that receives a SafeArray object as a parameter can use that object only for the duration of the method call. If a longer-term copy is needed, either the SafeArray object must be converted to a Java array, or the clone method must be used to create an independent copy of the object.

  2. If a Java method returns a SafeArray object, that object is owned by the caller; the Java method must no longer use that SafeArray instance. The simplest way to follow this rule is to have the called method construct a new SafeArray object each time it is called.

In addition to maintaining a pointer to a native SAFEARRAY data structure, a SafeArray instance separately maintains the exact variant type of SAFEARRAY data structure elements. The variant type is determined by an argument to the SafeArray class constructor or is bound into the .java file by the jactivex tool. The system class com.ms.com.Variant defines public constants (Variant.VariantXXX) for all the valid variant types. It is important to note that neither the VariantByref nor the VariantArray modifier should be set in the element variant type; setting either of these modifiers will cause a run-time error to occur.

The SAFEARRAY data structure does not have reference counts, so the process of creating and destroying SAFEARRAY data structures cannot be made completely transparent to the Java programmer. Therefore, the SafeArray class can only be loaded by a trusted applet.

SafeArrays of type VT_UNKNOWN or VT_DISPATCH can be manipulated by using variant-typed manipulators and then extracting the COM object from the variant, as in the following example:

SafeArray sa;
   Object elem = sa.getVariant(index).toObject();

However, support for this technique is limited to cases where the variant was obtained from an object whose threading model is either free or both. In most other cases, a WrongThreadException is thrown. The conflicting requirements of COM's apartment threading model and Java's non-message-based model preclude an efficient representation of SafeArrays of Objects.

Note for JavaTLB users: The JavaTLB tool (which has been superceded by the jactivex tool) emits an older class file format that does not provide the exact variant type. This means in some cases, the SAFEARRAY data structure will not provide enough information to determine an exact variant type. In this case, the virtual machine will choose a default variant type based on the following heuristics:

  • SAFEARRAY data structures with elements of type VT_BSTR, VT_UNKNOWN, VT_DISPATCH or VT_VARIANT are explicitly flagged as such in the SAFEARRAY data structure; thus, these will always marshal correctly.

  • If not explicitly flagged, a SAFEARRAY data structure whose element size is 1 is presumed to be of type VT_UI1. Similarly, if the element size is 2, the SAFEARRAY is presumed to be of type VT_I2. If the element size is 4, type VT_I4 is presumed, and if the element size is 8, VT_R8 is presumed. Otherwise, a ClassCastException is thrown.

  • If a variant type other than the default is needed, the interface .java files must either be rebuilt using the jactivex tool or the reinterpretType method must be used to override the default variant type.


Constructors (SafeArray Class)

 Microsoft SDK for Java

SafeArray Class Constructors

The SafeArray Class contains the following constructors:

SafeArray(int vt)
SafeArray(int vt, int celems)
SafeArray(int vt, int celems1, int celems2)
SafeArray(int vt, int lbounds[], int celems[])
SafeArray(String s)
getPhysicalSafeArray()

SafeArray(int vt)

Creates a SafeArray instance that wraps the NULL pointer. The main purpose of this constructor is to pass NULL to Component Object Model (COM) methods that accept SAFEARRAYs.

Syntax

public SafeArray(int vt);

The variant type of the element must be one of the Variant.VariantXXX constants. Neither the VariantByref nor the VariantArray modifier should be set in the element variant type; setting either of these modifiers will cause a run-time error to occur.

Parameters

vt The variant type of the element.

SafeArray(int vt, int celems)

Creates a one-dimensional SafeArray object. Valid indexes range from zero (inclusive) to celems (exclusive). Note that this convention follows the C language practice of indicating the number of elements rather than the Microsoft® Visual Basic® convention of indicating the upper bound.

The variant type of the element must be one of the Variant.VariantXXX constants. Neither the VariantArray nor the VariantByref modifier can be set.

Syntax

public SafeArray(int vt, int celems);

Parameters

vt | The variant type of the element.
celems | The number of elements.

SafeArray(int vt, int celems1, int celems2)

Creates a two-dimensional SafeArray object.

Syntax

public SafeArray(int vt, int celems1, int celems2);

The constructor follows the C language practice of indicating the number of elements rather than the Microsoft® Visual Basic® convention of indicating the upper bound.

The expression:

new SafeArray(Variant.VariantVariant, 21, 11);

is equivalent to the Visual Basic declaration:

Example

Option Base 0
Dim A(20, 10)

The variant type of the element must be one of the Variant.VariantXXX constants. Neither the VariantByref nor the VariantArray modifier should be set in the element variant type; setting either of these modifiers will cause a run-time error to occur.

Parameters

vt | The variant type of the element.
celems1 | The number of elements in the first dimension.
celems2 | The number of elements in the second dimension.

SafeArray(int vt, int lbounds[], int celems[])

Creates a SafeArray object of arbitrary shape.

Syntax

public SafeArray(int vt, int lbounds[], int celems[]);

The lbounds array indicates the lower bound of each dimension. The celems array (which must have the same length as lbounds) gives the number of elements that are in each dimension. If lbounds is null, all the lower bound values default to zero. The variant type of the element must be one of the Variant.VariantXXX constants. Neither the VariantArray nor VariantByref modifier can be set.

The following Java code creates a 3-dimensional SafeArray:

Example

int lbounds[] = {-1,-3, -4};
int celems[] = {10, 20, 30};
SafeArray A = new SafeArray(Variant.VariantVariant, lbounds,
celems);

This Visual Basic declaration creates an array with the same shape as the SafeArray created above:

Dim A(-1 To 8, -3 To 16, -4 To 25)

Parameters

vt | The variant type of the element.
lbounds | The lower bounds of each dimension.
celems | The number of elements in each dimension.

SafeArray(String s)

Creates a VT_UI1 SafeArray object from a string.

Syntax

public SafeArray(String s);

Each character of the string occupies two elements of the array to form a single Unicode character. The array is not null terminated. This constructor corresponds to the standard Automation conversion from VT_BSTR to VT_ARRAY|VT_UI1.

Parameters

s The string used to initialize the new SafeArray object.

getPhysicalSafeArray()

Retrieves the linear address of the actual SAFEARRAY data structure, which is packaged as a Java integer. This method is provided only to aid in debugging. Other than displaying information, there are no useful operations that can be performed with this value from Java.

Syntax

public native int getPhysicalSafeArray();

Return Value

Returns the linear address of the represented SAFEARRAY.


Methods (SafeArray Class)

 Microsoft SDK for Java

SafeArray Class Methods

The SafeArray Class contains the following methods:

asString converts a VT_UI1 SafeArray to a string.
clone creates an exact and independent duplicate of the SafeArray object.
destroy invokes the Win32 function SafeArrayDestroy.
finalize performs cleanup tasks before garbage collection.
fromBooleanArray initializes SafeArray elements from a Java array.
fromByteArray initializes SafeArray elements from a Java array.
fromCharArray initializes SafeArray elements from a Java array.
fromDoubleArray initializes SafeArray elements from a Java array.
fromFloatArray initializes SafeArray elements from a Java array.
fromIntArray initializes SafeArray elements from a Java array.
fromShortArray initializes SafeArray elements from a Java array.
fromStringArray initializes SafeArray elements from a Java array.
fromVariantArray initializes SafeArray elements from a Java array.
getBoolean extracts an element of a one-dimensional SafeArray as a boolean.
getBooleans extracts multiple elements as booleans.
getByte extracts an element of a one-dimensional SafeArray as a byte.
getBytes extracts multiple elements as bytes.
getChar extracts an element of a one-dimensional SafeArray as a character.
getChars extracts multiple elements of a SafeArray as characters.
getDouble extracts an element of a one-dimensional SafeArray as a double.
getDoubles extracts multiple elements of a SafeArray as doubles.
getElemSizeretrieves the size of a single element.
getFeatures retrieves the contents of the fFeatures bitmask.
getFloat extracts an element of a one-dimensional SafeArray as a float.
getFloats extracts multiple elements of a SafeArray as floats.
getInt extracts an element of a one-dimensional SafeArray as an integer.
getInts extracts multiple elements of the SafeArray as integers.
getLBound retrieves the smallest valid index of the array's first dimension.
getNumDim obtains the number of SafeArray dimensions.
getNumLocks retrieves the number of outstanding locks on the SafeArray object.
getShort extracts an element of a one-dimensional SafeArray as a short integer.
getShorts extracts multiple elements as short integers.
getString extracts an element of a one-dimensional SafeArray as a string.
getStrings extracts multiple elements of a SafeArray as strings.
getUBound returns the largest valid index of the array's first dimension.
getVariant extracts an element of a one-dimensional SafeArray as a Variant.
getVariants extracts multiple elements as Variant objects.
getvt retrieves the variant type of the SafeArray elements.
reinit reinitializes the SafeArray object.
reinterpretType forces the SafeArray to interpret elements as another variant type.
setBoolean sets an element of a one-dimensional SafeArray.
setBooleans sets multiple elements of a SafeArray.
setByte sets an element of a one-dimensional SafeArray.
setBytes sets multiple elements of a SafeArray.
setChar sets an element of a one-dimensional SafeArray.
setChars sets multiple elements.
setDouble sets an element of a one-dimensional SafeArray.
setDoubles sets multiple elements of a SafeArray.
setFloat sets an element of a one-dimensional SafeArray.
setFloats sets multiple elements of a SafeArray.
setInt sets an element of a one-dimensional SafeArray.
setInts sets multiple elements of a SafeArray.
setShort sets an element of a one-dimensional SafeArray.
setShorts sets multiple elements of a SafeArray.
setString sets an element of a one-dimensional SafeArray.
setStrings sets multiple elements of a SafeArray.
setVariant sets an element of a one-dimensional SafeArray.
setVariants sets multiple elements of a SafeArray.
toBooleanArray converts an entire SafeArray to a Java array.
toByteArray converts an entire SafeArray to a Java array.
toCharArray converts an entire SafeArray to a Java array.
toDoubleArray converts an entire SafeArray to a Java array.
toFloatArray converts an entire SafeArray to a Java array.
toIntArray converts an entire SafeArray to a Java array.
toShortArray converts the entire SafeArray to a Java array.
toString defines the printed representation of a SafeArray object.
toStringArray converts an entire SafeArray to a Java array.
toVariantArray converts an entire SafeArray to a Java array.


asString (SafeArray Class)

 Microsoft SDK for Java

asString

This method of the SafeArray Class converts a VT_UI1 SafeArray to a string. This method corresponds to the VariantChangeType conversion from VT_ARRAY|VT_UI1 to VT_BSTR.

Syntax

public native String asString();

Return Value

Returns the converted value.


clone (SafeArray Class)

 Microsoft SDK for Java

clone

This method of the SafeArray Class creates an exact and independent duplicate of the SafeArray object. This method is a wrapper around the Microsoft® Win32® SafeArrayCopy function.

Syntax

public Object clone();

Return Value

Returns a new SafeArray object that contains an independent duplicate.


destroy (SafeArray Class)

 Microsoft SDK for Java

destroy

This method of the SafeArray Class invokes the Win32 function SafeArrayDestroy.

Syntax

public void destroy();

Caution This is a potentially dangerous routine that should be used with extreme caution. It is not necessary to invoke this method when following standard COM memory ownership rules. This is because the Java/COM integration subsystem and the Java garbage collector work together to ensure correct disposal of SafeArrays.


finalize (SafeArray Class)

 Microsoft SDK for Java

finalize

This method of the SafeArray Class performs cleanup tasks before garbage collection.

Syntax

protected void finalize();


fromBooleanArray (SafeArray Class)

 Microsoft SDK for Java

fromBooleanArray

This method of the SafeArray Class initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Syntax

public void fromBooleanArray(boolean ja[]);

Note If you are modifying a large number of elements, it might be more efficient to use fromCharArray rather than fromBooleanArray. Since boolean SafeArrays use two bytes per element, the fromBooleanArray method cannot optimize itself to a memory copy (memcpy).

Parameters

ja The Java array that contains the new values.


fromByteArray (SafeArray Class)

 Microsoft SDK for Java

fromByteArray

This method of the SafeArray Class initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

Syntax

public void fromByteArray(byte ja[]);

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

ja The Java array that contains the new values.


fromCharArray (SafeArray Class)

 Microsoft SDK for Java

fromCharArray

This method of the SafeArray Class initializes SafeArray elements from a Java array.

Syntax

public void fromCharArray(char ja[]);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

ja The Java array that contains the new values.


fromDoubleArray (SafeArray Class)

 Microsoft SDK for Java

fromDoubleArray

This method of the SafeArray Class initializes SafeArray elements from a Java array.

Syntax

public void fromDoubleArray(double ja[]);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Parameters

ja The Java array that contains the new values.


fromFloatArray (SafeArray Class)

 Microsoft SDK for Java

fromFloatArray

This method of the SafeArray Class initializes SafeArray elements from a Java array.

Syntax

public void fromFloatArray(float ja[]);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Parameters

ja The Java array that contains the new values.


fromIntArray (SafeArray Class)

 Microsoft SDK for Java

fromIntArray

This method of the SafeArray Class initializes SafeArray elements from a Java array.

Syntax

public void fromIntArray(int ja[]);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

ja The Java array that contains the new values.


fromShortArray (SafeArray Class)

 Microsoft SDK for Java

fromShortArray

This method of the SafeArray Class initializes SafeArray elements from a Java array.

Syntax

public void fromShortArray(short ja[]);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Parameters

ja The Java array that contains the new values.


fromStringArray (SafeArray Class)

 Microsoft SDK for Java

fromStringArray

This method of the SafeArray Class initializes SafeArray elements from a Java array.

Syntax

public void fromStringArray(String ja[]);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Parameters

ja The Java array that contains the new values.


fromVariantArray (SafeArray Class)

 Microsoft SDK for Java

fromVariantArray

This method of the SafeArray Class initializes SafeArray elements from a Java array.

Syntax

public void fromVariantArray(Variant ja[]);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note Although Variantjsdk_ref_com_Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is a SafeArray of Variants.

Parameters

ja The Java array that contains the new values.


getBoolean (SafeArray Class)

 Microsoft SDK for Java

getBoolean

The getBoolean method of the SafeArray Class contains the following signatures:

getBoolean(int sa_idx)
getBoolean(int sa_idx1, int sa_idx2)

getBoolean(int sa_idx)

Extracts an element of a one-dimensional SafeArray as a boolean.

Syntax

public native boolean getBoolean(int sa_idx);

Return Value

Returns the converted element value.

Parameters

sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if sa_idx is not between the lower bound and the upper bound of the array (inclusive).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

getBoolean(int sa_idx1, int sa_idx2)

Extracts an element of a two-dimensional SafeArray as a boolean.

Syntax

public boolean getBoolean(int sa_idx1, int sa_idx2);

Return Value

Returns the converted element value.

Parameters

sa_idx1 | The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1).
sa_idx2 | The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if neither index is between the lower bound and the upper bound of the array (inclusive).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.


getBooleans (SafeArray Class)

 Microsoft SDK for Java

getBooleans

This method of the SafeArray Class extracts multiple elements as booleans.

Syntax

public void getBooleans(int sa_idx, int nelems, boolean ja[], int ja_start);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note If you extract a large number of elements, it might be more efficient to use getChars rather than getBooleans. Since boolean SafeArray objects use two bytes per element, the getBooleans method cannot optimize itself to a memory copy (memcpy).

Parameters

sa_idx | The index of the first element to retrieve. This index is always zero-based.
nelems | The number of elements to retrieve.
ja | The Java array that receives the values.
ja_start | The index of the first element in ja that receives a value.


getByte (SafeArray Class)

 Microsoft SDK for Java

getByte

The getByte method of the SafeArray Class contains the following signatures:

getByte(int sa_idx)
getByte(int sa_idx1, int sa_idx2)

getByte(int sa_idx)

Extracts an element of a one-dimensional SafeArray as a byte.

Syntax

public byte getByte(int sa_idx);

Return Value

Returns the converted element value.

Parameters

sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if sa_idx lies outside the defined range (LBound() to UBound()).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

getByte(int sa_idx1, int sa_idx2)

Extracts an element of a two-dimensional SafeArray as a byte.

Syntax

public byte getByte(int sa_idx1, int sa_idx2);

Return Value

Returns the converted element value.

Parameters

sa_idx1 | The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1).
sa_idx2 | The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.


getBytes (SafeArray Class)

 Microsoft SDK for Java

getBytes

This method of the SafeArray Class extracts multiple elements as bytes.

Syntax

public void getBytes(int sa_idx, int nelems, byte ja[], int ja_start);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to retrieve. This index is always zero-based.
nelems | The number of elements to retrieve.
ja | Java The array that receives the values.
ja_start | The index of the first element in ja that receives a value.


getChar (SafeArray Class)

 Microsoft SDK for Java

getChar

The getChar method of the SafeArray Class contains the following signatures:

getChar(int sa_idx)
getChar(int sa_idx1, int sa_idx2)

getChar(int sa_idx)

Extracts an element of a one-dimensional SafeArray as a character.

Syntax

public char getChar(int sa_idx);

Return Value

Returns the converted element value.

Parameters

sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if sa_idx lies outside the defined range (LBound() to UBound()).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

getChar(int sa_idx1, int sa_idx2)

Extracts an element of a two-dimensional array as a character.

Syntax

public char getChar(int sa_idx1, int sa_idx2);

Return Value

Returns the converted element value.

Parameters

sa_idx1 | The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1).
sa_idx2 | The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.


getChars (SafeArray Class)

 Microsoft SDK for Java

getChars

This method of the SafeArray Class Extracts multiple elements of a SafeArray as characters.

Syntax

public void getChars(int sa_idx, int nelems, char ja[], int ja_start);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to retrieve. This index is always zero-based.
nelems | The number of elements to retrieve.
ja | The Java array that receives the values.
ja_start | The index of the first element in ja that receives a value.


getDouble (SafeArray Class)

 Microsoft SDK for Java

getDouble

The getDouble method of the SafeArray Class contains the following signatures:

getDouble(int sa_idx)
getDouble(int sa_idx1, int sa_idx2)

getDouble(int sa_idx)

This method of the SafeArray Class extracts an element of a one-dimensional SafeArray as a double.

Syntax

public native double getDouble(int sa_idx);

Return Value

Returns the converted element value.

Parameters

sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx lies outside the defined range (LBound() to UBound()).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

getDouble(int sa_idx1, int sa_idx2)

This method of the SafeArray Class extracts an element of a two-dimensional SafeArray as a double.

Syntax

public double getDouble(int sa_idx1, int sa_idx2);

Return Value

Returns the converted element value.

Parameters

sa_idx1 | The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1).
sa_idx2 | The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.


getDoubles (SafeArray Class)

 Microsoft SDK for Java

getDoubles

This method of the SafeArray Class extracts multiple elements of a SafeArray as doubles.

Syntax

public void getDoubles(int sa_idx, int nelems, double ja[], int ja_start);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to retrieve. This index is always zero-based.
nelems | The number of elements to retrieve.
ja | The Java array that receives the values.
ja_start | The index of the first element in ja that receives a value.


getElemSize (SafeArray Class)

 Microsoft SDK for Java

getElemSize

This method of the SafeArray Class retrieves the size of a single element.

Syntax

public int getElemSize();

Return Value

Returns the size of a single element, measured in bytes.


getFeatures (SafeArray Class)

 Microsoft SDK for Java

getFeatures

This method of the SafeArray Class retrieves the contents of the fFeatures bitmask. This bitmask (defined as part of the OLE SAFEARRAY data structure) provides various types of information about the SAFEARRAY.

Syntax

public int getFeatures();

Return Value

Returns the fFeatures field.


getFloat (SafeArray Class)

 Microsoft SDK for Java

getFloat

The getFloat method of the SafeArray Class contains the following signatures:

getFloat(int sa_idx)
getFloat(int sa_idx1, int sa_idx2)

getFloat(int sa_idx)

Extracts an element of a one-dimensional SafeArray as a float.

Syntax

public native float getFloat(int sa_idx);

Return Value

Returns the converted element value.

Parameters

sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx lies outside the defined range (LBound()..UBound()).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

getFloat(int sa_idx1, int sa_idx2)

This method of the SafeArray Class extracts an element of a two-dimensional SafeArray as a float.

Syntax

public float getFloat(int sa_idx1, int sa_idx2);

Return Value

Returns the converted element value.

Parameters

sa_idx1 | The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1).
sa_idx2 | The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.


getFloats (SafeArray Class)

 Microsoft SDK for Java

getFloats

This method of the SafeArray Class extracts multiple elements of a SafeArray as floats.

Syntax

public void getFloats(int sa_idx, int nelems, float ja[], int ja_start);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to retrieve. This index is always zero-based.
nelems | The number of elements to retrieve.
ja | The Java array that receives the values.
ja_start | The index of the first element in ja that receives a value.


getInt (SafeArray Class)

 Microsoft SDK for Java

getInt

The getInt method of the SafeArray Class contains the following signatures:

getInt(int sa_idx)
getInt(int sa_idx1, int sa_idx2)

getInt(int sa_idx)

Extracts an element of a one-dimensional SafeArray as an integer.

Syntax

public native int getInt(int sa_idx);

Return Value

Returns the converted element value.

Parameters

sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions

ClassCastException if the SafeArray element cannot be converted to the correct type using the Win32 VariantChangeType function.

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx lies outside the defined range (LBound() to UBound()).

getInt(int sa_idx1, int sa_idx2)

Extracts an element of a two-dimensional array as an integer.

Syntax

public int getInt(int sa_idx1, int sa_idx2);

Return Value

Returns the converted element value.

Parameters

sa_idx1 | The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1).
sa_idx2 | The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.


getInts (SafeArray Class)

 Microsoft SDK for Java

getInts

This method of the SafeArray Class extracts multiple elements of the SafeArray as integers.

Syntax

public void getInts(int sa_idx, int nelems, int ja[], int ja_start);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to retrieve. This index is always zero-based.
nelems | The number of elements to retrieve.
ja | The Java array that receives the values.
ja_start | The index of the first element in ja that receives a value.


getLBound (SafeArray Class)

 Microsoft SDK for Java

getLBound

The getLBound method of the SafeArray Class contains the following signatures:

getLBound()
getLBound(int dim)

getLBound()

Retrieves the smallest valid index of the array's first dimension. This method is identical to the Visual Basic LBound function.

Syntax

public int getLBound();

Return Value

Returns the smallest valid index.

getLBound(int dim)

Retrieves the smallest valid index of an arbitrary dimension. (Dimensions are numbered, starting with 1.) This method is identical to the Visual Basic LBound function.

Syntax

public int getLBound(int dim);

Return Value

Returns the smallest valid index.

Parameters

dim The dimension.


getNumDim (SafeArray Class)

 Microsoft SDK for Java

getNumDim

This method of the SafeArray Class obtains the number of SafeArray dimensions.

Syntax

public int getNumDim();

Return Value

Returns the number of dimensions in the SafeArray (2 for two-dimensional SafeArrays, for example).


getNumLocks (SafeArray Class)

 Microsoft SDK for Java

getNumLocks

This method of the SafeArray Class retrieves the number of outstanding locks on the SafeArray object. This value (which is usually zero) is only useful for debugging purposes.

Syntax

public int getNumLocks();

Return Value

Returns the outstanding lock count.


getShort (SafeArray Class)

 Microsoft SDK for Java

getShort

The getShort method of the SafeArray Class contains the following signatures:

getShort(int sa_idx)
getShort(int sa_idx1, int sa_idx2)

getShort(int sa_idx)

Extracts an element of a one-dimensional SafeArray as a short integer.

Syntax

public short getShort(int sa_idx);

Return Value

Returns the converted element value.

Parameters

sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx lies outside the defined range (LBound() to UBound()).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

getShort(int sa_idx1, int sa_idx2)

Extracts an element of a two-dimensional SafeArray as a short integer.

Syntax

public short getShort(int sa_idx1, int sa_idx2);

Return Value

Returns the converted element value.

Parameters

sa_idx1 | The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1).
sa_idx2 | The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.


getShorts (SafeArray Class)

 Microsoft SDK for Java

getShorts

This method of the SafeArray Class extracts multiple elements as short integers.

Syntax

public void getShorts(int sa_idx, int nelems, short ja[], int ja_start);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to retrieve. This index is always zero-based.
nelems | The number of elements to retrieve.
ja | The Java array that receives the values.
ja_start | The index of the first element in ja that receives a value.


getString (SafeArray Class)

 Microsoft SDK for Java

getString

The getString method of the SafeArray Class contains the following signatures:

getString(int sa_idx)
getString(int sa_idx1, int sa_idx2)

getString(int sa_idx)

Extracts an element of a one-dimensional SafeArray as a string.

Syntax

public String getString(int sa_idx);

Return Value

Returns the converted element value.

Parameters

sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx does not lie between the lower bound and the upper bound of the array (inclusive).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

getString(int sa_idx1, int sa_idx2)

Extracts an element of a two-dimensional SafeArray as a string.

Syntax

public String getString(int sa_idx1, int sa_idx2);

Return Value

Returns the converted element value.

Parameters

sa_idx1 | The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1).
sa_idx2 | The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions

IndexOutOfBoundsException if the array is not two-dimensional or if either index does not lie between the lower bound and the upper bound of the array (inclusive).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.


getStrings (SafeArray Class)

 Microsoft SDK for Java

getStrings

This method of the SafeArray Class extracts multiple elements of a SafeArray as strings.

Syntax

public void getStrings(int sa_idx, int nelems, String ja[], int ja_start);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Parameters

sa_idx | The index of the first element to retrieve. This index is always zero-based.
nelems | The number of elements to retrieve.
ja | The Java array that receives the values.
ja_start | The index of the first element in ja that receives a value.


getUBound (SafeArray Class)

 Microsoft SDK for Java

getUBound

The getUBound method of the SafeArray Class contains the following signatures:

getUBound()
getUBound(int dim)

getUBound()

Returns the largest valid index of the array's first dimension. This method is identical to the Microsoft® Visual Basic® UBound function.

Syntax

public int getUBound();

Return Value

Returns the largest valid index.

getUBound(int dim)

Retrieves the largest valid index of an arbitrary dimension. (Dimensions are numbered starting with 1.) This method is identical to the Visual Basic UBound function.

Syntax

public int getUBound(int dim);

Return Value

Returns the largest valid index.

Parameters

dim The dimension.


getVariant (SafeArray Class)

 Microsoft SDK for Java

getVariant

The getVariant method of the SafeArray Class contains the following signatures:

getVariant(int sa_idx)
getVariant(int sa_idx1, int sa_idx2)

getVariant(int sa_idx)

Extracts an element of a one-dimensional SafeArray as a Variant.

Syntax

public Variant getVariant(int sa_idx);

Note Although the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant,and then to coerce the Variant. This is true even if the SafeArray is a SafeArray of Variant.

Return Value

Returns the converted element value.

Parameters

sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx does not lie between the lower bound of the array and the upper bound of the array (inclusive).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

getVariant(int sa_idx1, int sa_idx2)

Extracts an element of a two-dimensional SafeArray as a Variant.

Syntax

public Variant getVariant(int sa_idx1, int sa_idx2);

Note Although the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant, and then to coerce the Variant. This is true even if the SafeArray is a SafeArray of Variants.

Return Value

Returns the converted element value.

Parameters

sa_idx1 | The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1).
sa_idx2 | The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.


getVariants (SafeArray Class)

 Microsoft SDK for Java

getVariants

This method of the SafeArray Class extracts multiple elements as Variant objects. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order.

Syntax

public void getVariants(int sa_idx, int nelems, Variant ja[], int ja_start);

No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note Although the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant, and then to coerce the Variant. This is true even if the SafeArray is a SafeArray of Variants.

Parameters

sa_idx | The index of the first element to retrieve. This index is always zero-based.
nelems | The number of elements to retrieve.
ja | The Java array that receives the values.
ja_start | The index of the first element in ja that receives a value.


getvt (SafeArray Class)

 Microsoft SDK for Java

getvt

This method of the SafeArray Class retrieves the variant type of the SafeArray elements. This corresponds to a public constant, com.ms.com.VariantXXX.

Syntax

public int getvt();

Note If JavaTLB is used to generate the Java method information that passes a SafeArray from COM to Java, the variant type might be inexact. (The element size, however, will always be correct.) JavaTLB has been superceded by the jactivex tool, which binds the exact variant type into the .class file.

Return Value

Returns the variant type of the element.


reinit (SafeArray Class)

 Microsoft SDK for Java

reinit

This method of the SafeArray Class reinitializes the SafeArray object.

Syntax

public void reinit(SafeArray sa);

Parameters

sa The SafeArray object that is reinitialized.


reinterpretType (SafeArray Class)

 Microsoft SDK for Java

reinterpretType

This method of the SafeArray Class forces the SafeArray to interpret elements as another variant type.

Syntax

public void reinterpretType(int vt);

Parameters

vt The new variant type of the element.


setBoolean (SafeArray Class)

 Microsoft SDK for Java

setBoolean

The setBoolean method of the SafeArray Class contains the following signatures:

setBoolean(int idx, boolean val)
setBoolean(int idx1, int idx2, boolean val)

setBoolean(int idx, boolean val)

Sets an element of a one-dimensional SafeArray.

Syntax

public native void setBoolean(int idx, boolean val);

Parameters

idx | The element index, which ranges from index of the lower bound to the index of the upper bound.
val | The new element value.

Exceptions

IndexOutOfBoundsException if the array is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

setBoolean(int idx1, int idx2, boolean val)

Sets an element of a two-dimensional SafeArray.

Syntax

public void setBoolean(int idx1, int idx2, boolean val);

Parameters

idx1 | The first dimension index of the element to set, which ranges from LBound(1) to UBound(1).
idx2 | The second dimension index of the element to set, which ranges from LBound(2) to UBound(2).
val | The new element value.

Exceptions

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.


setBooleans (SafeArray Class)

 Microsoft SDK for Java

setBooleans

This method of the SafeArray Class sets multiple elements of a SafeArray.

Syntax

public void setBooleans(int sa_idx, int nelems, boolean ja[], int ja_start);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Note If you are modifying a large number of elements, it might be more efficient to use setChars rather than setBooleans. Since boolean SafeArrays use two bytes per element, the setBooleans method cannot optimize itself to a memory copy (memcpy).

Parameters

sa_idx | The index of the first element to set. This index is always zero-based.
nelems | The number of elements to set.
ja | The Java array that contains the new values.
ja_start | The index of first element in ja to use.


setByte (SafeArray Class)

 Microsoft SDK for Java

setByte

The setByte method of the SafeArray Class contains the following signatures:

setByte(int idx, byte val)
setByte(int idx1, int idx2, byte val)

setByte(int idx, byte val)

Sets an element of a one-dimensional SafeArray.

Syntax

public void setByte(int idx, byte val);

Parameters

idx | The index of the element to set, which ranges from the lower bound to the upper bound of the SafeArray.
val | The new element value.

Exceptions

IndexOutOfBoundsException if the array is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

setByte(int idx1, int idx2, byte val)

Sets an element of a two-dimensional SafeArray.

Syntax

public void setByte(int idx1, int idx2, byte val);

Parameters

idx1 | The first dimension index of the element to set, which ranges from LBound(1) to UBound(1).
idx2 | The second dimension index of the element to set, which ranges from LBound(2) to UBound(2).
val | The new element value.

Exceptions

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.


setBytes (SafeArray Class)

 Microsoft SDK for Java

setBytes

This method of the SafeArray Class sets multiple elements of a SafeArray.

Syntax

public void setBytes(int sa_idx, int nelems, byte ja[], int ja_start);

If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimize to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to set. This index is always zero-based.
nelems | The number of elements to set.
ja | The Java array that contains the new values.
ja_start | The index of the first element in ja to use.


setChar (SafeArray Class)

 Microsoft SDK for Java

setChar

The setChar method of the SafeArray Class contains the following signatures:

setChar(int idx, char val)
setChar(int idx1, int idx2, char val)

setChar(int idx, char val)

Sets an element of a one-dimensional SafeArray.

Syntax

public void setChar(int idx, char val);

Parameters

idx | The index of the element to set, which ranges from the lower bound to the upper bound of the SafeArray.
val | The new element value.

Exceptions

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

setChar(int idx1, int idx2, char val)

Sets an element of a two-dimensional SafeArray.

Syntax

public void setChar(int idx1, int idx2, char val);

Parameters

idx1 | The first dimension index of the element to set, which ranges from LBound(1) to UBound(1).
idx2 | The second dimension index of the element to set, which ranges from LBound(2) to UBound(2).
val | The new element value.

Exceptions

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.


setChars (SafeArray Class)

 Microsoft SDK for Java

setChars

This method of the SafeArray Class sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Syntax

public void setChars(int sa_idx, int nelems, char ja[], int ja_start);

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to set. This index is always zero-based.
nelems | The number of elements to set.
ja | The Java array that contains the new values.
ja_start | The index of the first element in ja that is used.


setDouble (SafeArray Class)

 Microsoft SDK for Java

setDouble

The setDouble method of the SafeArray Class contains the following signatures:

setDouble(int idx, double val)
setDouble(int idx1, int idx2, double val)

setDouble(int idx, double val)

Sets an element of a one-dimensional SafeArray.

Syntax

public native void setDouble(int idx, double val);

Parameters

idx | The element index, which ranges from the lower bound to the upper bound of the SafeArray.
val | The new element value.

Exceptions

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

setDouble(int idx1, int idx2, double val)

Sets an element of a two-dimensional SafeArray.

Syntax

public void setDouble(int idx1, int idx2, double val);

Parameters

idx1 | The first dimension index of the element to set, which ranges from LBound(1) to UBound(1).
idx2 | The second dimension index of the element to set, which ranges from LBound(2) to UBound(2).
val | The new element value

Exceptions

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.


setDoubles (SafeArray Class)

 Microsoft SDK for Java

setDoubles

This method of the SafeArray Class sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Syntax

public void setDoubles(int sa_idx, int nelems, double ja[], int ja_start);

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to set. This index is always zero-based.
nelems | The number of elements to set.
ja | The Java array that provides the values.
ja_start | The index of the first element to use in ja.


setFloat (SafeArray Class)

 Microsoft SDK for Java

setFloat

The setFloat method of the SafeArray Class contains the following signatures:

setFloat(int idx, float val)
setFloat(int idx1, int idx2, float val)

setFloat(int idx, float val)

Sets an element of a one-dimensional SafeArray.

Syntax

public native void setFloat(int idx, float val);

Parameters

idx | The element index, which ranges from index of the lower bound to the index of the upper bound.
val | The new element value.

Exceptions

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if idx is not between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

setFloat(int idx1, int idx2, float val)

Sets an element of a two-dimensional array.

Syntax

public void setFloat(int idx1, int idx2, float val);

Parameters

idx1 | The first dimension index of the element to set, which ranges from LBound(1) to UBound(1).
idx2 | The second dimension index of the element to set, which ranges from LBound(2) to UBound(2).
val | The new element value.

Exceptions

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.


setFloats (SafeArray Class)

 Microsoft SDK for Java

setFloats

This method of the SafeArray Class sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element set in the SafeArray is located sa_idx elements away from index zero.

Syntax

public void setFloats(int sa_idx, int nelems, float ja[], int ja_start);

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to set. This index is always zero-based.
nelems | The number of elements to set.
ja | The Java array that contains the new values.
ja_start | The index of the first element in ja to use.


setInt (SafeArray Class)

 Microsoft SDK for Java

setInt

The setInt method of the SafeArray Class contains the following signatures:

setInt(int idx, int val)
setInt(int idx1, int idx2, int val)

setInt(int idx, int val)

Sets an element of a one-dimensional SafeArray.

Syntax

public native void setInt(int idx, int val);

Parameters

idx | The element index, which ranges from the index of the lower bound to the index of the upper bound.
val | The new element value.

Exceptions

IndexOutOfBoundsException is thrown if the SafeArray is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

setInt(int idx1, int idx2, int val)

Sets an element of a two-dimensional SafeArray.

Syntax

public void setInt(int idx1, int idx2, int val);

Parameters

idx1 | The first dimension index of the element to set, which ranges from LBound(1) to UBound(1).
idx2 | The second dimension index of the element to set, which ranges from LBound(2) to UBound(2).
val | The new element value.

Exceptions

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.


setInts (SafeArray Class)

 Microsoft SDK for Java

setInts

This method of the SafeArray Class sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Syntax

public void setInts(int sa_idx, int nelems, int ja[], int ja_start);

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to set. This index is always zero-based.
nelems | The number of elements to set.
ja | The Java array that provides the values.
ja_start | The index of the first element in ja.


setShort (SafeArray Class)

 Microsoft SDK for Java

setShort

The setShort method of the SafeArray Class contains the following signatures:

setShort(int idx, short val)
setShort(int idx1, int idx2, short val)

setShort(int idx, short val)

Sets an element of a one-dimensional SafeArray.

Syntax

public void setShort(int idx, short val);

Parameters

idx | The element index, which ranges from index of the lower bound to the index of the upper bound.
val | The new element value.

Exceptions

IndexOutOfBoundsException if the array is not one-dimensional or if idx is not between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

setShort(int idx1, int idx2, short val)

Sets an element of a two-dimensional SafeArray.

Syntax

public void setShort(int idx1, int idx2, short val);

Parameters

idx1 | The first dimension index of the element to set, which ranges from LBound(1) to UBound(1).
idx2 | The second dimension index of the element to set, which ranges from LBound(2) to UBound(2).
val | The new element value.

Exceptions

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.


setShorts (SafeArray Class)

 Microsoft SDK for Java

setShorts

This method of the SafeArray Class sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element set in the SafeArray is located sa_idx elements away from index zero.

Syntax

public void setShorts(int sa_idx, int nelems, short ja[], int ja_start);

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Parameters

sa_idx | The index of the first element to set. This index is always zero-based.
nelems | The number of elements to set.
ja | The Java array that contains the new values.
ja_start | The index of the first element in ja to use.


setString (SafeArray Class)

 Microsoft SDK for Java

setString

The setString method of the SafeArray Class contains the following signatures:

setString(int idx, String val)
setString(int idx1, int idx2, String val)

setString(int idx, String val)

Sets an element of a one-dimensional SafeArray.

Syntax

public void setString(int idx, String val);

Parameters

idx | The element index, which ranges from index of the lower bound to the index of the upper bound.
val | The new element value.

Exceptions

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

IndexOutOfBoundsException if the array is not one-dimensional or if idx is not between the lower bound and the upper bound of the SafeArray (inclusive).

setString(int idx1, int idx2, String val)

Sets an element of a two-dimensional SafeArray.

Syntax

public void setString(int idx1, int idx2, String val);

Parameters

idx1 | The first dimension index of the element to set, which ranges from LBound(1) to UBound(1).
idx2 | The second dimension index of the element to set, which ranges from LBound(2) to UBound(2).
val | The new element value.

Exceptions

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.


setStrings (SafeArray Class)

 Microsoft SDK for Java

setStrings

This method of the SafeArray Class sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Syntax

public void setStrings(int sa_idx, int nelems, String ja[], int ja_start);

Parameters

sa_idx | The index of the first element to set. This index is always zero-based.
nelems | The number of elements to set.
ja | The Java array that contains the new values.
ja_start | The index of the first element to use in ja.


setVariant (SafeArray Class)

 Microsoft SDK for Java

setVariant

The setVariant method of the SafeArray Class contains the following signatures:

setString(int idx, String val)
setString(int idx1, int idx2, String val)

setVariant(int idx, Variant val)

Sets an element of a one-dimensional SafeArray.

Syntax

public void setVariant(int idx, Variant val);

Note Although Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is a SafeArray of Variants.

Parameters

idx | The element index, which ranges from the index of the lower bound to the index of the upper bound.
val | The new element value.

Exceptions

IndexOutOfBoundsException if the array is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

setVariant(int idx1, int idx2, Variant val)

Sets an element of a two-dimensional SafeArray.

Syntax

public void setVariant(int idx1, int idx2, Variant val);

Note Although Variantjsdk_ref_com_Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is a SafeArray of Variants.

Parameters

idx1 | The first element index, which ranges from LBound(1) to UBound(1).
idx2 | The first element index, which ranges from LBound(2) to UBound(2).
val | The new element value.

Exceptions

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.


setVariants (SafeArray Class)

 Microsoft SDK for Java

setVariants

This method of the SafeArray Class sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Syntax

public void setVariants(int sa_idx, int nelems, Variant ja[], int ja_start);

Note Although the Variantjsdk_ref_com_Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is a SafeArray of Variants.

Parameters

sa_idx | The index of the first element to set. This index is always zero-based.
nelems | The number of elements to set.
ja | The Java array that provides the values.
ja_start | The index of the first element to use in ja.


toBooleanArray (SafeArray Class)

 Microsoft SDK for Java

toBooleanArray

This method of the SafeArray Class converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Syntax

public boolean[] toBooleanArray();

Note If you are extracting a large number of elements, it might be more efficient to use toCharArray rather than toBooleanArray. Since SafeArray objects use two bytes per element, the toBooleanArray method cannot optimize itself to a memory copy (memcpy).

Return Value

Returns the flattened contents of the array.


toByteArray (SafeArray Class)

 Microsoft SDK for Java

toByteArray

This method of the SafeArray Class converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Syntax

public byte[] toByteArray();

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value

Returns the flattened contents of the array.


toCharArray (SafeArray Class)

 Microsoft SDK for Java

toCharArray

This method of the SafeArray Class converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Syntax

public char[] toCharArray();

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value

Returns the flattened contents of the array.


toDoubleArray (SafeArray Class)

 Microsoft SDK for Java

toDoubleArray

This method of the SafeArray Class converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Syntax

public double[] toDoubleArray();

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value

Returns the flattened contents of the array.


toFloatArray (SafeArray Class)

 Microsoft SDK for Java

toFloatArray

This method of the SafeArray Class converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Syntax

public float[] toFloatArray();

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value

Returns the flattened contents of the array.


toIntArray (SafeArray Class)

 Microsoft SDK for Java

toIntArray

This method of the SafeArray Class converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Syntax

public int[] toIntArray();

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method will optimize to a straight memory copy (memcpy).

Return Value

Returns the flattened contents of the array.


toShortArray (SafeArray Class)

 Microsoft SDK for Java

toShortArray

This method of the SafeArray Class converts the entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Syntax

public short[] toShortArray();

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value

Returns the flattened contents of the array.


toString (SafeArray Class)

 Microsoft SDK for Java

toString

This method of the SafeArray Class defines the printed representation of a SafeArray object.

Syntax

public String toString();

Return Value

Returns the printed representation.


toStringArray (SafeArray Class)

 Microsoft SDK for Java

toStringArray

This method of the SafeArray Class converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is stored in element zero of the Java array.

Syntax

public String[] toStringArray();

Return Value

Returns the flattened contents of the array.


toVariantArray (SafeArray Class)

 Microsoft SDK for Java

toVariantArray

This method of the SafeArray Class converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Syntax

public Variant[] toVariantArray();

Note Although the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant, and then coerce the Variant. This is true even if the SafeArray is a SafeArray of Variants.

Return Value

Returns the flattened contents of the array.


STATSTG Class (com.ms.com Package)

 Microsoft SDK for Java

STATSTG Class

The STATSG Class of the com.ms.com Package represents an STATSTG structure, which contains statistical information about an open storage, stream or byte array object.

public final class STATSTG
{
  // Methods
  public _Guid getCLSID();
  public void setCLSID(_Guid clsid)

  // Fields
  public long atime;
  public long cbSize;
  public byte clsid_b0;
  public byte clsid_b1;
  public byte clsid_b10;
  public byte clsid_b11;
  public byte clsid_b12;
  public byte clsid_b13;
  public byte clsid_b14;
  public byte clsid_b15;
  public byte clsid_b2;
  public byte clsid_b3;
  public byte clsid_b4;
  public byte clsid_b5;
  public byte clsid_b6;
  public byte clsid_b7;
  public byte clsid_b8;
  public byte clsid_b9;
  public int clsid_data1;
  public short clsid_data2;
  public short clsid_data3;
  public long ctime;
  public int grfLocksSupported;
  public int grfMode;
  public int grfStateBits;
  public long mtime;
  public String pwcsName;
  public int reserved;
  public final static int STGTY_LOCKBYTES;
  public final static int STGTY_PROPERTY;
  public final static int STGTY_STORAGE;
  public final static int STGTY_STREAM;
  public int type;
}


Methods (STATSTG class)

 Microsoft SDK for Java

STATSTG Class Methods

The STATSTG Class contains the following methods:

getCLSID gets the CLSID field.
setCLSID sets the CLSID field.


getCLSID (STATSTG class)

 Microsoft SDK for Java

getCLSID

This method of the STATSTG class gets the CLSID field.

Syntax

public _Guid getCLSID();

Remarks

This method was added as of versions 2925 through 3167 of the Microsoft virtual machine.


setCLSID (STATSTG class)

 Microsoft SDK for Java

setCLSID

This method of the STATSTG class sets the CLSID field.

Syntax

public void setCLSID(_Guid clsid)

Parameters

clsid The CLSID field to be set.

Remarks

This method was added as of versions 2925 through 3167 of the Microsoft virtual machine.


Fields (STATSTG Class)

 Microsoft SDK for Java

STATSTG Class Fields

The STATSTG Class contains the following fields.

atime | The last access time for the storage, stream, or byte array.
cbSize | The size, in bytes, of the stream or byte array.
clsid_b0 | A byte field of the CLSID structure that represents the class identifier.
clsid_b1 | A byte field of the CLSID structure that represents the class identifier.
clsid_b10 | A byte field of the CLSID structure that represents the class identifier.
clsid_b11 | A byte field of the CLSID structure that represents the class identifier.
clsid_b12 | A byte field of the CLSID structure that represents the class identifier.
clsid_b13 | A byte field of the CLSID structure that represents the class identifier.
clsid_b14 | A byte field of the CLSID structure that represents the class identifier.
clsid_b15 | A byte field of the CLSID structure that represents the class identifier.
clsid_b2 | A byte field of the CLSID structure that represents the class identifier.
clsid_b3 | A byte field of the CLSID structure that represents the class identifier.
clsid_b4 | A byte field of the CLSID structure that represents the class identifier.
clsid_b5 | A byte field of the CLSID structure that represents the class identifier.
clsid_b6 | A byte field of the CLSID structure that represents the class identifier.
clsid_b7 | A byte field of the CLSID structure that represents the class identifier.
clsid_b8 | A byte field of the CLSID structure that represents the class identifier.
clsid_b9 | A byte field of the CLSID structure that represents the class identifier.
clsid_data1 | An integer field of the CLSID structure that represents the class identifier.
clsid_data2 | A short integer field of the CLSID structure that represents the class identifier.
clsid_data3 | A short integer field of the CLSID structure that represents the class identifier.
ctime | The creation time for the storage, stream, or byte array.
grfLocksSupported | The types of region locking supported by the stream or byte array. The value must be LOCK_WRITE, LOCK_EXCLUSIVE, or LOCK_ONLYONCE. This member is not used for storage objects.
grfMode | The access mode specified when the object was opened. This member is valid only in calls to Stat methods.
grfStateBits | The current state bits of the storage object. This member is not valid for streams or byte arrays. It is the value most recently set by the IStorage::SetStateBits method.
mtime | The last modification time for the storage, stream, or byte array.
pwcsName | The name of the structure.
reserved | Reserved.
STGTY_LOCKBYTES | The value indicating that the storage element is a byte array object.
STGTY_PROPERTY | The value indicating that the storage element is a property storage object.
STGTY_STORAGE | The value indicating that the storage element is a storage object.
STGTY_STREAM | The value indicating that the storage element is a stream object.
type | The type of storage object described by the structure. The value must be STGTY_STORAGE, STGTY_STREAM, STGTY_LOCKBYTES, or STGTY_PROPERTY.


StdCOMClassObject Class (com.ms.com package)

 Microsoft SDK for Java

StdCOMClassObject Class

The StdCOMClassObject class of the com.ms.com package supports the implementation of custom COM class objects.

public abstract class StdCOMClassObject
{
  // Methods
  protected IUnknown createInstanceImpl(IUnknown punkOuter);
  protected IUnknown createControlImpl(IUnknown punkOuter);
  protected void lockServerImpl(boolean lock);
}

See the COM Class Object sample in %SDKDIR%\Samples\COM\COMClassObject for a demonstration of implementing a custom COM class object and implementing a small client that co-creates the object through the Java interface.

See Also

Creating a Custom Class Object


Methods (StdCOMClassObject Class)

 Microsoft SDK for Java

StdCOMClassObject Class Methods

The StdCOMClassObject class has the following methods:

createInstanceImpl creates an instance of the class with the specified controlling unknown. The instance will support the ActiveX control interfaces.
createControlImpl creates an instance of the class with the specified controlling unknown.
lockServerImpl locks the class object in memory.


createInstanceImpl (StdCOMClassObject Class)

 Microsoft SDK for Java

createInstanceImpl

This method of the StdCOMClassObject class creates an instance of the class with the specified controlling unknown. This method may be used in an implementation of IClassFactory's CreateInstance method.

Syntax

protected IUnknown createInstanceImpl(IUnknown punkOuter);

Return Value

Parameters

punkOuter Determines whether the object is being aggregated into another object.


createControlImpl (StdCOMClassObject Class)

 Microsoft SDK for Java

createControlImpl

This method of the StdCOMClassObject class creates an instance of the class with the specified controlling unknown. The instance will support the ActiveX control interfaces. The appropriate ActiveX control wrapper is added (Beans or WFC) depending on the class type.This method may be used in an implementation of IClassFactory's CreateInstance method.

Syntax

protected IUnknown createControlImpl(IUnknown punkOuter);

Return Value

Parameters

punkOuter Determines whether the object is being aggregated into another object.


lockServerImpl (StdCOMClassObject Class)

 Microsoft SDK for Java

lockServerImpl

This method of the StdCOMClassObject class locks the class object in memory. This method may be used in an implementation of IClassFactory's LockServer method.

Syntax

protected void lockServerImpl(boolean lock);

Parameters

lock Determines whether to lock the object.


Variant Class (com.ms.com Package)

 Microsoft SDK for Java

Variant Class

The Variant Class of the com.ms.com Package is used to bridge Java with Microsoft® ActiveX® components that manipulate VARIANT data types.

public final class Variant
{
  // Fields
  public static final short VariantArray;
  public static final short VariantBoolean;
  public static final short VariantByref;
  public static final short VariantByte;
  public static final short VariantCurrency;
  public static final short VariantDate;
  public static final short VariantDispatch;
  public static final short VariantDouble;
  public static final short VariantEmpty;
  public static final short VariantError;
  public static final short VariantFloat;
  public static final short VariantInt;
  public static final short VariantNull;
  public static final short VariantObject;
  public static final short VariantShort;
  public static final short VariantString;
  public static final short VariantTypeMask;
  public static final short VariantVariant;

  // Constructors
  public Variant();
  public Variant(int val);
  public Variant(double val);
  public Variant(boolean val);
  public Variant(String val);
  public Variant(SafeArray val, boolean fByRef);
  public Variant(Object value);
  public Variant(int vartype, int val);
  public Variant(int vartype, boolean val);
  public Variant(int vartype, double val);
  public Variant(int vartype, Object val);
  public Variant(Object value, boolean unwrapScriptObjects);

  // Methods
  public native void changeType(short vartype);
  public void changeType(int vartype);
  public Object clone();
  public Variant cloneIndirect();
  protected void finalize();
  public native boolean getBoolean();
  public native boolean getBooleanRef();
  public byte getByte();
  public native byte getByteRef();
  public long getCurrency();
  public native long getCurrencyRef();
  public double getDate();
  public native double getDateRef();
  public native Object getDispatch();
  public native Object getDispatchRef();
  public double getDouble();
  public native double getDoubleRef();
  public void getEmpty();
  public int getError();
  public native int getErrorRef();
  public float getFloat();
  public native float getFloatRef();
  public int getInt();
  public native int getIntRef();
  public void getNull();
  public native Object getObject();
  public native Object getObjectRef();
  public short getShort();
  public native short getShortRef();
  public native String getString();
  public native String getStringRef();
  public native Variant[] getVariantArray();
  public native Variant[] getVariantArrayRef();
  public short getvt();
  public void noParam();
  public void putBoolean(boolean val);
  public native void putBooleanRef(boolean val);
  public void putByte(byte val);
  public native void putByteArray(Object ba);
  public native void putByteRef(byte val);
  public native void putCharArray(Object ca);
  public void putCurrency(long val);
  public native void putCurrencyRef(long val);
  public void putDate(double val);
  public native void putDateRef(double val);
  public native void putDispatch(Object val);
  public native void putDispatchRef(Object val);
  public void putDouble(double val);
  public native void putDoubleRef(double val);
  public void putEmpty();
  public void putError(int val);
  public native void putErrorRef(int val);
  public void putFloat(float val);
  public native void putFloatRef(float val);
  public void putInt(int val);
  public native void putIntRef(int val);
  public void putNull();
  public native void putObject(Object val);
  public native void putObjectRef(Object val);
  public void putSafeArray(SafeArray sa);
  public void putSafeArrayRef(SafeArray sa);
  public void putShort(short val);
  public native void putShortRef(short val);
  public native void putString(String val);
  public native void putStringRef(String val);
  public native void putVariantArray(Variant v[]);
  public native void putVariantArrayRef(Variant v[]);
  public native boolean toBoolean() throws ClassCastException;
  public native byte toByte() throws ClassCastException;
  public native Object toByteArray();
  public native Object toCharArray();
  public native long toCurrency() throws ClassCastException;
  public native double toDate() throws ClassCastException;
  public native Object toDispatch() throws ClassCastException;
  public native double toDouble() throws ClassCastException;
  public native int toError() throws ClassCastException;
  public native float toFloat() throws ClassCastException;
  public native int toInt() throws ClassCastException;
  public native Object toObject() throws ClassCastException;
  public SafeArray toSafeArray() throws ClassCastException;
  public native Object toScriptObject() throws ClassCastException;
  public native short toShort() throws ClassCastException;
  public String toString();
  public native Variant[] toVariantArray();
  public void VariantClear();
}

Most Variant methods fall into one of three categories:

  • toXXX methods, which attempt to coerce the Variant object to type XXX and return the converted value. The results of the coercion are not copied back to the Variant object. Coercion is performed by using the Microsoft® Win32® VariantChangeType function. If the Variant object cannot be converted to the requested type, a ClassCastException is thrown.

  • getXXX methods, which succeed only if the Variant object is already the correct type. If not, a ClassCastException is thrown.

  • putXXX methods, which change the type of a Variant object and initialize it to a new value. In general, it is better to construct and initialize the Variant object atomically by using an overloaded constructor rather than to use one of these methods.


Constructors (Variant Class)

 Microsoft SDK for Java

Variant Class Constructors

The Variant Class contains the following constructors:

Variant()
Variant(int val)
Variant(double val)
Variant(boolean val)
Variant(string val)
Variant(SafeArray val, boolean fByRef)
Variant(object value)
Variant(int vartype, int val)
Variant(int vartype, boolean val)
Variant(int vartype, double val)
Variant(int vartype, Object val)
Variant(Object value, boolean unwrapScriptObjects)

Variant()

Creates a Variant object of type VT_EMPTY.

Syntax

public Variant();

Variant(int val)

Creates a Variant object of type VT_I4.

Syntax

public Variant(int val);

Parameters

val The initial value of the Variant object.

Variant(double val)

Creates a Variant object of type VT_R8.

Syntax

public Variant(double val);

Parameters

val The initial value of the Variant object.

Variant(boolean val)

Creates a Variant object of type VT_BOOL.

Syntax

public Variant(boolean val);

Parameters

val The initial value of the Variant object.

Variant(string val)

Creates a Variant object of type VT_BSTR.

Syntax

public Variant(String val);

Parameters

val The initial value of the Variant object.

Variant(SafeArray val, boolean fByRef)

Creates a Variant object of type VT_ARRAY or VT_BYREF|VT_ARRAY. Typically, fByRef is set to true when you create a Variant object to pass as a parameter, and it is false when you create a Variant object that is used as a return value.

Syntax

public Variant(SafeArray val, boolean fByRef);

Parameters

val | The initial SafeArray value.
fByRef | Indicates how to set the VT_BYREF modifier.

Remarks

If fByRef is true, any changes made to the SAFEARRAY data structure through the new Variant object will be visible to the SafeArray instance used to initialize the Variant object.

If fByRef is false, the method revokes the SafeArray instance's ownership. Any further operations on that instance will throw an exception. This is because ownership of the SAFEARRAY data structure has been transferred to the new Variant object. To retrieve any changes made through the Variant object, you must call the toSafeArray method to obtain a new proxy.

Variant(object value)

Creates a Variant object of type VT_DISPATCH or VT_BYREF|VT_ARRAY.

Syntax

public Variant(Object value);

If the argument is a Java SafeArray object, this constructor is equivalent to the following code:

Variant(value, true)

Otherwise, this constructor creates a VT_DISPATCH.

Parameters

value The initial value.

Variant(int vartype, int val)

Creates a Variant object of the type indicated by vartype. The type can be VariantShort, VariantInt, or VariantByte. The VariantByref modifier can be set on any of these types.

Syntax

public Variant(int vartype, int val);

Parameters

vartype | The variant type.
val | The initial value.

Variant(int vartype, boolean val)

Creates a Variant object of the type indicated by vartype. The type can be VariantBoolean, or VariantByref|VariantBoolean.

Syntax

public Variant(int vartype, boolean val);

Parameters

vartype | The variant type.
val | The initial value.

Variant(int vartype, double val)

Creates a Variant object of the type indicated by vartype. The type can be VariantDouble, VariantFloat, or VariantDate. The VariantByref modifier can be set on any of these types.

Syntax

public Variant(int vartype, double val);

Parameters

vartype | The variant type.
val | The initial value.

Variant(int vartype, Object val)

Creates a Variant object of the type indicated by vartype. The type can be VariantString, VariantObject, or VariantDispatch. The VariantByref modifier can be set on any of these types.

Syntax

public Variant(int vartype, Object val);

Parameters

vartype | The variant type.
val | The initial value.

Variant(Object value, boolean unwrapScriptObjects)

If unwrapScriptObjects is set to true, this constructor creates an object of the type indicated by value, which can be types VT_BOOL, VT_BSTR, or VT_R8. Otherwise, this constructor creates a VT_DISPATCH.

Syntax

public Variant(Object value, boolean unwrapScriptObjects);

Parameters

value | The initial value.
unwrapScriptObjects | Indicates whether script objects are to be unwrapped.

Remarks

This constructor was added as of versions 2437 through 2925 of the Microsoft virtual machine.


Methods (Variant Class)

 Microsoft SDK for Java

Variant Class Methods

The Variant Class contains the following methods:

changeType invokes the Win32 VariantChangeType function.
clone invokes the Win32 VariantCopy function.
cloneIndirect invokes the Win32 VariantCopyInd function.
finalize performs cleanup before garbage collection.
getBoolean retrieves the value of a VT_BOOL Variant.
getBooleanRef retrieves the referenced value of a VT_BYREF|VT_BOOL Variant.
getByte retrieves the value of a VT_UI1 Variant.
getByteRef retrieves the referenced value of a VT_BYREF|VT_UI1 Variant.
getCurrency retrieves the value of a VT_CY Variant
getCurrencyRef retrieves the referenced value of a VT_BYREF|VT_CY Variant.
getDate retrieves the value of a VT_DATE Variant.
getDateRef retrieves the referenced value of a VT_BYREF|VT_DATE Variant.
getDispatch retrieves the value of a VT_DISPATCH Variant.
getDispatchRef retrieves the referenced value of a VT_BYREF|VT_DISPATCH Variant.
getDouble retrieves the value of a VT_R8 Variant
getDoubleRef retrieves the referenced value of a VT_BYREF|VT_R8 Variant object.
getEmpty verifies that the variant type is VT_EMPTY.
getError retrieves the value of a VT_ERROR Variant.
getErrorRef retrieves the referenced value of a VT_BYREF|VT_ERROR Variant.
getFloat retrieves the value of a VT_R4 Variant.
getFloatRef retrieves the referenced value of a VT_BYREF|VT_R4 Variant object.
getInt retrieves the value of a VT_I4 Variant.
getIntRef retrieves the referenced value of a VT_BYREF|VT_I4 Variant object.
getNull verifies that the variant type is VT_NULL.
getObject retrieves the value of a VT_UNKNOWN Variant
getObjectRef retrieves the referenced value of a VT_BYREF|VT_UNKNOWN Variant.
getShort retrieves the value of a VT_I2 Variant.
getShortRef retrieves the referenced value of a VT_BYREF|VT_I2 Variant object.
getString retrieves the value of a VT_BSTR Variant.
getStringRef retrieves the referenced value of a VT_BYREF|VT_BSTR Variant.
getVariantArray retrieves the value of a VT_ARRAY|VT_VARIANT Variant.
getVariantArrayRef retrieves the referenced value of a VT_BYREF|VT_ARRAY|VT_VARIANT Variant.
getvt extracts the variant type of the Variant object.
noParam sets a Variant object to represent a missing optional parameter.
putBoolean sets the Variant object to type VT_BOOL and clears the previous contents.
putBooleanRef replaces a value referenced by a VT_BYREF|VT_BOOL Variant object.
putByte sets the Variant object to be type VT_UI1 and clears the previous contents.
putByteArray sets a Variant object to type VT_ARRAY|VT_UI1 and clears the previous contents.
putByteRef replaces a value referenced by a VT_BYREF|VT_UI1 Variant object.
putCharArray sets Variant to type VT_ARRAY|VT_I2 and clears the previous contents.
putCurrency sets the Variant object to type VT_CY and clears the previous contents.
putCurrencyRef eplaces a value referenced by a VT_BYREF|VT_CY Variant object.
putDate sets the Variant object to type VT_DATE and clears the previous contents.
putDateRef replaces a value referenced by a VT_BYREF|VT_DATE Variant object.
putDispatch sets the Variant object to type VT_DISPATCH and clears the previous contents.
putDispatchRef replaces a value referenced by a VT_BYREF|VT_DISPATCH Variant object.
putDouble sets the Variant object to type VT_R8 and clears the previous contents.
putDoubleRef replaces a value referenced by a VT_BYREF|VT_R8 Variant object.
putEmpty sets the Variant object to type VT_EMPTY and clears the previous contents.
putError sets the Variant object to type VT_ERROR and clears the previous contents.
putErrorRef replaces a value referenced by a VT_BYREF|VT_ERROR Variant.
putFloat sets the Variant object to type VT_R4 and clears the previous contents.
putFloatRef replaces a value referenced by a VT_BYREF|VT_R4 Variant object.
putInt sets the Variant object to type VT_I4 and clears the previous contents.
putIntRef replaces a value referenced by a VT_BYREF|VT_I4 Variant object.
putNull sets the Variant object to type VT_NULL and clears the previous contents.
putObject sets the Variant object to be type VT_UNKNOWN and clears the previous contents.
putObjectRef replaces a value referenced by a VT_BYREF|VT_UNKNOWN Variant object.
putSafeArray sets the Variant object to type SAFEARRAY and clears the previous contents.
putSafeArrayRef replaces a SafeArray object referenced by the Variant.
putShort sets the Variant object to type VT_I2 and clears the previous contents.
putShortRef replaces a value referenced by a VT_BYREF|VT_I2 Variant object.
putString sets the Variant object to type VT_BSTR and clears the previous contents.
putStringRef replaces a value referenced by a VT_BYREF|VT_BSTR Variant object.
putVariantArray sets a Variant object to a typeVT_ARRAY|VT_VARIANT Variant object, which holds a zero-based, one-dimensional SafeArray.
putVariantArrayRef replaces a SAFEARRAY data structure, which is referenced by a VT_BYREF|VT_ARRAY|VT_VARIANT Variant.
toBoolean coerces the Variant object to a VT_BOOL and returns the coerced result.
toByte coerces the Variant object to a VT_UI1 and returns the coerced result.
toByteArray retrieves the value of a VT_ARRAY|VT_UI1 or VT_BYREF|VT_ARRAY|VT_UI1 as a one-dimensional byte[] array.
toCharArray retrieves the value of a VT_ARRAY|VT_I2 or VT_BYREF|VT_ARRAY|VT_I2 as a one-dimensional char[] array.
toCurrency coerces the Variant object to a VT_CY and returns the coerced result.
to Date coerces the Variant object to a VT_DATE and returns the coerced result.
toDispatch coerces the Variant object to a VT_DISPATCH and returns the coerced result.
toDouble coerces the Variant object to a VT_R8 and returns the coerced result.
toError coerces the Variant object to a VT_ERROR and returns the coerced result.
toFloat coerces the Variant object to a VT_R4 and returns the coerced result.
toInt coerces the Variant object to a VT_I4 and returns the coerced result.
toObject coerces the Variant object to a VT_UNKNOWN and returns the coerced result.
toSafeArray extracts a SafeArray object from a Variant object that has the VT_ARRAY modifier set.
toScriptObject coerces the Variant object to a VT_UNKNOWN, VT_BSTR, VT_BOOL, or VT_R8 and returns the coerced result.
toShort coerces the Variant object to a VT_I2 and returns the coerced result.
toString coerces the Variant object to a VT_BSTR and returns the coerced result.
toVariantArray retrieves the value of either a VT_ARRAY|VT_VARIANT or VT_BYREF|VT_ARRAY|VT_VARIANT Variant.
VariantClear forces the Microsoft® Win32® VariantClear function to be called and resets the Variant object to VT_EMPTY.


changeType (Variant Class)

 Microsoft SDK for Java

changeType

The changeType method of the Variant Class contains the following signatures:

changeType(short vartype)
changeType(int vartype)

changeType(short vartype)

Invokes the Win32 VariantChangeType function.

Syntax

public native void changeType(short vartype);

changeType(int vartype)

Invokes the Win32 VariantChangeType function.

Syntax

public void changeType(int vartype);


clone (Variant Class)

 Microsoft SDK for Java

clone

This method of the Variant Class invokes the Win32 VariantCopy function.

Syntax

public Object clone();

Return Value

Returns the cloned Variant object.


cloneIndirect (Variant Class)

 Microsoft SDK for Java

cloneIndirect

This method of the Variant Class invokes the Win32 VariantCopyInd function.

Syntax

public Variant cloneIndirect();

Return Value

Returns the cloned Variant object.


finalize (Variant Class)

 Microsoft SDK for Java

finalize

This method of the Variant Class performs cleanup before garbage collection.

Syntax

protected void finalize();


getBoolean (Variant Class)

 Microsoft SDK for Java

getBoolean

This method of the Variant Class retrieves the value of a VT_BOOL Variant.

Syntax

public native boolean getBoolean();

Return Value

Returns the Variant object's value, which is converted to a Java boolean.

Exceptions

ClassCastException if the variant type is not VT_BOOL.


getBooleanRef (Variant Class)

 Microsoft SDK for Java

getBooleanRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_BOOL Variant.

Syntax

public native boolean getBooleanRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java boolean.

Exceptions

ClassCastException if the Variant is of any other type.


getByte (Variant Class)

 Microsoft SDK for Java

getByte

This method of the Variant Class retrieves the value of a VT_UI1 Variant.

Syntax

public byte getByte();

Return Value

Returns the Variant object's value, which is converted to a Java byte.

Exceptions

ClassCastException if the variant type is not VT_UI1.


getByteRef (Variant Class)

 Microsoft SDK for Java

getByteRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_UI1 Variant.

Syntax

public native byte getByteRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java byte.

Exceptions

ClassCastException if the Variant is of any other type.


getCurrency (Variant Class)

 Microsoft SDK for Java

getCurrency

This method of the Variant Class retrieves the value of a VT_CY Variant.

Syntax

public long getCurrency();

Return Value

Returns the Variant object's value, which is converted to a Java long.

Exceptions

ClassCastException if the variant type is not VT_CY.


getCurrencyRef (Variant Class)

 Microsoft SDK for Java

getCurrencyRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_CY Variant.

Syntax

public native long getCurrencyRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java long.

Exceptions

ClassCastException if the Variant is of any other type.


getDate (Variant Class)

 Microsoft SDK for Java

getDate

This method of the Variant Class retrieves the value of a VT_DATE Variant.

Syntax

public double getDate();

Return Value

Returns the Variant object's value, which is converted to a Java double.

Exceptions

ClassCastException if the variant type is not VT_DATE.


getDateRef (Variant Class)

 Microsoft SDK for Java

getDateRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_DATE Variant.

Syntax

public native double getDateRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java double.

Exceptions

ClassCastException if the Variant is of any other type.


getDispatch (Variant Class)

 Microsoft SDK for Java

getDispatch

This method of the Variant Class retrieves the value of a VT_DISPATCH Variant.

Syntax

public native Object getDispatch();

Return Value

Returns the Variant object's value, which is converted to a Java object.

Exceptions

ClassCastException if the variant type is not VT_DISPATCH.


getDispatchRef (Variant Class)

 Microsoft SDK for Java

getDispatchRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_DISPATCH Variant.

Syntax

public native Object getDispatchRef();

Return Value

Returns the Variantobject's referenced value, which is converted to a Java object.

Exceptions

ClassCastException if the Variant is of any other type.


getDouble (Variant Class)

 Microsoft SDK for Java

getDouble

This method of the Variant Class retrieves the value of a VT_R8 Variant.

Syntax

public double getDouble();

Return Value

Returns the Variant object's value, which is converted to a Java double.

Exceptions

ClassCastException if the variant type is not VT_R8.


getDoubleRef (Variant Class)

 Microsoft SDK for Java

getDoubleRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_R8 Variant object.

Syntax

public native double getDoubleRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java double.

Exceptions

ClassCastException if the Variant is of any other type.


getEmpty (Variant Class)

 Microsoft SDK for Java

getEmpty

This method of the Variant Class verifies that the variant type is VT_EMPTY. This method has no other purpose; there is no value associated with a null Variant.

Syntax

public void getEmpty();

Exceptions

ClassCastException if the variant type is not VT_EMPTY.


getError (Variant Class)

 Microsoft SDK for Java

getError

This method of the Variant Class retrieves the value of a VT_ERROR Variant.

Syntax

public int getError();

Return Value

Returns the Variant object's value, which is converted to a Java integer.

Exceptions

ClassCastException if the variant type is not VT_ERROR.


getErrorRef (Variant Class)

 Microsoft SDK for Java

getErrorRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_ERROR Variant.

Syntax

public native int getErrorRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java integer.

Exceptions

ClassCastException if the Variant is of any other type.


getFloat (Variant Class)

 Microsoft SDK for Java

getFloat

This method of the Variant Class retrieves the value of a VT_R4 Variant.

Syntax

public float getFloat();

Return Value

Returns the Variant object's value, which is converted to a Java float.

Exceptions

ClassCastException if the variant type is not VT_R4.


getFloatRef (Variant Class)

 Microsoft SDK for Java

getFloatRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_R4 Variant object.

Syntax

public native float getFloatRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java float.

Exceptions

ClassCastException if the Variant is of any other type.


getInt (Variant Class)

 Microsoft SDK for Java

getInt

This method of the Variant Class retrieves the value of a VT_I4 Variant.

Syntax

public int getInt();

Return Value

Returns the Variant object's value converted to a Java integer.

Exceptions

ClassCastException if the variant type is not VT_I4.


getIntRef (Variant Class)

 Microsoft SDK for Java

getIntRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_I4 Variant object.

Syntax

public native int getIntRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java integer.

Exceptions

ClassCastException if the Variant is of any other type.


getNull (Variant Class)

 Microsoft SDK for Java

getNull

This method of the Variant Class verifies that the variant type is VT_NULL. This method has no other purpose; there is no value associated with a null Variant.

Syntax

public void getNull();

Exceptions

ClassCastException if the variant type is not VT_NULL.


getObject (Variant Class)

 Microsoft SDK for Java

getObject

This method of the Variant Class retrieves the value of a VT_UNKNOWN Variant.

Syntax

public native Object getObject();

Return Value

Returns the Variant object's value, which is converted to a Java object.

Exceptions

ClassCastException if the variant type is not VT_UNKNOWN.


getObjectRef (Variant Class)

 Microsoft SDK for Java

getObjectRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_UNKNOWN Variant.

Syntax

public native Object getObjectRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java object.

Exceptions

ClassCastException if the Variant is of any other type.


getShort (Variant Class)

 Microsoft SDK for Java

getShort

This method of the Variant Class retrieves the value of a VT_I2 Variant.

Syntax

public short getShort();

Return Value

Returns the Variant object's value, which is converted to a Java short.

Exceptions

ClassCastException if the variant type is not VT_I2.


getShortRef (Variant Class)

 Microsoft SDK for Java

getShortRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_I2 Variant object.

Syntax

public native short getShortRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java short.

Exceptions

ClassCastException if the Variant is of any other type.


getString (Variant Class)

 Microsoft SDK for Java

getString

This method of the Variant Class retrieves the value of a VT_BSTR Variant.

Syntax

public native String getString();

Return Value

Returns the Variant object's value, which is converted to a Java string.

Exceptions

ClassCastException if the variant type is not VT_BSTR.


getStringRef (Variant Class)

 Microsoft SDK for Java

getStringRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_BSTR Variant.

Syntax

public native String getStringRef();

Return Value

Returns the Variant object's referenced value, which is converted to a Java string.

Exceptions

ClassCastException if the Variant is of any other type.


getVariantArray (Variant Class)

 Microsoft SDK for Java

getVariantArray

This method of the Variant Class retrieves the value of a VT_ARRAY|VT_VARIANT Variant. The embedded array must be one-dimensional. This is an "expensive" method, which has been superceded by the toSafeArray method.

Syntax

public native Variant[] getVariantArray();

Return Value

Returns the Variant's value converted to a Java array of Variants.


getVariantArrayRef (Variant Class)

 Microsoft SDK for Java

getVariantArrayRef

This method of the Variant Class retrieves the referenced value of a VT_BYREF|VT_ARRAY|VT_VARIANT Variant. The embedded array must be one-dimensional. This is an "expensive" method, which has been superceded by the toSafeArray method.

Syntax

public native Variant[] getVariantArrayRef();

Return Value

Returns the Variant's referenced value converted to a Java array of Variant objects.


getvt (Variant Class)

 Microsoft SDK for Java

getvt

This method of the Variant Class extracts the variant type of the Variant object.

Syntax

public short getvt();

Return Value

Returns the variant type.


noParam (Variant Class)

 Microsoft SDK for Java

noParam

This method of the Variant Class sets a Variant object to represent a missing optional parameter. This method is equivalent to the expression.

putError(0x80020004) //DISP_E_PARAMNOTFOUND

Syntax

public void noParam();


putBoolean (Variant Class)

 Microsoft SDK for Java

putBoolean

This method of the Variant Class sets the Variant object to type VT_BOOL and clears the previous contents.

Syntax

public void putBoolean(boolean val);

Note The preferred way to create a VT_BOOL Variant is to use the following expression:

new Variant(val)

Parameters

val The new value.


putBooleanRef (Variant Class)

 Microsoft SDK for Java

putBooleanRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_BOOL Variant object.

Syntax

public native void putBooleanRef(boolean val);

Note This method can also be used to initialize a Variant, but the preferred method is to use the following expression:

new Variant(Variant.VariantByref|Variant.VariantBoolean,val).

Parameters

val The new value.


putByte (Variant Class)

 Microsoft SDK for Java

putByte

This method of the Variant Class sets the Variant object to be type VT_UI1 and clears the previous contents.

Syntax

public void putByte(byte val);

Note The preferred way to create a VT_UI1 Variant is to use the following expression:

new Variant(Variant.VariantByte, val)

Parameters

val The new value.


putByteArray (Variant Class)

 Microsoft SDK for Java

putByteArray

This method of the Variant Class sets a Variant object to type VT_ARRAY|VT_UI1 and clears the previous contents.

Syntax

public native void putByteArray(Object ba);

Parameters

ba The initial values of the elements, which must be byte[].


putByteRef (Variant Class)

 Microsoft SDK for Java

putByteRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_UI1 Variant object.

Syntax

public native void putByteRef(byte val);

Note This method can also be used to initialize a Variant, but the preferred method is to use the following expression:

new Variant(Variant.VariantByref|Variant.VariantByte,val)

Parameters

val The new value.


putCharArray (Variant Class)

 Microsoft SDK for Java

putCharArray

This method of the Variant Class sets Variant to type VT_ARRAY|VT_I2 and clears the previous contents.

Syntax

public native void putCharArray(Object ca);

Parameters

ca The initial values of the elements, which must be char[].


putCurrency (Variant Class)

 Microsoft SDK for Java

putCurrency

This method of the Variant Class sets the Variant object to type VT_CY and clears the previous contents.

Syntax

public void putCurrency(long val);

Parameters

val The new value.


putCurrencyRef (Variant Class)

 Microsoft SDK for Java

putCurrencyRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_CY Variant object.

Syntax

public native void putCurrencyRef(long val);

Parameters

val The new value.


putDate (Variant Class)

 Microsoft SDK for Java

putDate

This method of the Variant Class sets the Variant object to type VT_DATE and clears the previous contents.

Syntax

public void putDate(double val);

Note The preferred way to create a VT_DATE Variant is to use the following expression:

new Variant(Variant.VariantDate, val)

Parameters

val The new value.


putDateRef (Variant Class)

 Microsoft SDK for Java

putDateRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_DATE Variant object.

Syntax

public native void putDateRef(double val);

Note This method can also be used to initialize a Variant, but the preferred method is to use the following expression:

new Variant(Variant.VariantByref|Variant.VariantDate,val)

Parameters

val The new value.


putDispatch (Variant Class)

 Microsoft SDK for Java

putDispatch

This method of the Variant Class sets the Variant object to type VT_DISPATCH and clears the previous contents.

Syntax

public native void putDispatch(Object val);

Note The preferred way to create a VT_DISPATCH Variant is to use the following expression:

new Variant(val)

Parameters

val The new value.


putDispatchRef (Variant Class)

 Microsoft SDK for Java

putDispatchRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_DISPATCH Variant object.

Syntax

public native void putDispatchRef(Object val);

Note This method can also be used to initialize a Variant, but the preferred method is to use the following expression:

new Variant(Variant.VariantByref|Variant.VariantDispatch,val)

Parameters

val The new value.


putDouble (Variant Class)

 Microsoft SDK for Java

putDouble

This method of the Variant Class sets the Variant object to type VT_R8 and clears the previous contents.

Syntax

public void putDouble(double val);

Note The preferred way to create a VT_R8 Variant is to use the following expression:

new Variant(val)

Parameters

val The new value.


putDoubleRef (Variant Class)

 Microsoft SDK for Java

putDoubleRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_R8 Variant object.

Syntax

public native void putDoubleRef(double val);

Note This method can also be used to initialize a Variant, but the preferred method is to use the following expression:

new Variant(Variant.VariantByref|Variant.VariantDouble,val)

Parameters

val The new value.


putEmpty (Variant Class)

 Microsoft SDK for Java

putEmpty

This method of the Variant Class sets the Variant object to type VT_EMPTY and clears the previous contents. The expression:

new Variant()

creates a new Variant object that is already type VT_EMPTY, so it is not necessary to invoke the putEmpty method on such an object.

Syntax

public void putEmpty();


putError (Variant Class)

 Microsoft SDK for Java

putError

This method of the Variant Class sets the Variant object to type VT_ERROR and clears the previous contents. This object is normally passed as a placeholder for a missing optional parameter.

Syntax

public void putError(int val);

Note The preferred way to generate a missing parameter is to use the following code:

Variant v = new Variant(val);
v.noParam();

Parameters

val new value.


putErrorRef (Variant Class)

 Microsoft SDK for Java

putErrorRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_ERROR Variant.

Syntax

public native void putErrorRef(int val);

Parameters

val The new value.


putFloat (Variant Class)

 Microsoft SDK for Java

putFloat

This method of the Variant Class sets the Variant object to type VT_R4 and clears the previous contents.

Syntax

public void putFloat(float val);

Note The preferred way to create a VT_R4 Variant is to use the following expression:

new Variant(Variant.VariantFloat, val)

Parameters

val The new value.


putFloatRef (Variant Class)

 Microsoft SDK for Java

putFloatRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_R4 Variant object.

Syntax

public native void putFloatRef(float val);

Note This method can also be used to initialize a Variant, but the preferred method is to use the following expression:

new Variant(Variant.VariantByref|Variant.VariantFloat,val)

Parameters

val The new value.


putInt (Variant Class)

 Microsoft SDK for Java

putInt

This method of the Variant Class sets the Variant object to type VT_I4 and clears the previous contents.

Syntax

public void putInt(int val);

Note The preferred way to create a VT_I4 Variant is to use the following expression:

new Variant(val)

Parameters

val The new value.


putIntRef (Variant Class)

 Microsoft SDK for Java

putIntRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_I4 Variant object.

Syntax

public native void putIntRef(int val);

Note This method can also be used to initialize a Variant, but the preferred method is to use the following expression:

new Variant(Variant.VariantByref|Variant.VariantInt,val)

Parameters

val The new value.


putNull (Variant Class)

 Microsoft SDK for Java

putNull

This method of the Variant Class sets the Variant object to type VT_NULL and clears the previous contents.

Syntax

public void putNull();


putObject (Variant Class)

 Microsoft SDK for Java

putObject

This method of the Variant Class sets the Variant object to be type VT_UNKNOWN and clears the previous contents.

Syntax

public native void putObject(Object val);

Note The preferred way to create a VT_UNKNOWN Variant is to use the following expression:

new Variant(Variant.VariantObject, val)

Parameters

val The new value.


putObjectRef (Variant Class)

 Microsoft SDK for Java

putObjectRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_UNKNOWN Variant object.

Syntax

public native void putObjectRef(Object val);

Note This method can also be used to initialize a Variant, but the preferred method is to use the following expression:

new Variant(Variant.VariantByref|Variant.VariantObject, val)

Parameters

val The new value.


putSafeArray (Variant Class)

 Microsoft SDK for Java

putSafeArray

This method of the Variant Class sets the Variant object to type SAFEARRAY and clears the previous contents. This method sets the variant type to VT_ARRAY.

Syntax

public void putSafeArray(SafeArray sa);

Parameters

sa The SafeArray object.


putSafeArrayRef (Variant Class)

 Microsoft SDK for Java

putSafeArrayRef

This method of the Variant Class replaces a SafeArray object referenced by the Variant. This method sets the variant type to VT_BYREF|VT_ARRAY.

Syntax

public void putSafeArrayRef(SafeArray sa);

Parameters

sa The new SafeArray.


putShort (Variant Class)

 Microsoft SDK for Java

putShort

This method of the Variant Class sets the Variant object to type VT_I2 and clears the previous contents.

Syntax

public void putShort(short val);

Note The preferred way to create a VT_I2 Variant is to use the following expression:

new Variant(Variant.VariantShort, val)

Parameters

val The new value.


putShortRef (Variant Class)

 Microsoft SDK for Java

putShortRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_I2 Variant object.

Syntax

public native void putShortRef(short val);

Note This method can also be used to initialize a Variant, but the preferred method is to use the following expression:

new Variant(Variant.VariantByref|Variant.VariantShort,val)

Parameters

val The new value.


putString (Variant Class)

 Microsoft SDK for Java

putString

This method of the Variant Class sets the Variant object to type VT_BSTR and clears the previous contents.

Syntax

public native void putString(String val);

Note The preferred way to create a VT_BSTR Variant is to use the following expression:

new Variant(val)

Parameters

val The new value.


putStringRef (Variant Class)

 Microsoft SDK for Java

putStringRef

This method of the Variant Class replaces a value referenced by a VT_BYREF|VT_BSTR Variant object.

Syntax

public native void putStringRef(String val);

Note This method can also be used to initialize a Variant, but the preferred method is use the following expression:

new Variant(Variant.VariantByref|Variant.VariantString,val)

Parameters

val The new value.


putVariantArray (Variant Class)

 Microsoft SDK for Java

putVariantArray

This method of the Variant Class sets a Variant object to a typeVT_ARRAY|VT_VARIANT Variant object, which holds a zero-based, one-dimensional SafeArray.

Syntax

public native void putVariantArray(Variant v[]);

Parameters

v Provides initial values for the SAFEARRAY elements.


putVariantArrayRef (Variant Class)

 Microsoft SDK for Java

putVariantArrayRef

This method of the Variant Class replaces a SAFEARRAY data structure, which is referenced by a VT_BYREF|VT_ARRAY|VT_VARIANT Variant.

Syntax

public native void putVariantArrayRef(Variant v[]);

Note This method can also be used to initialize a Variant object, but the preferred method is to pass a SafeArray object to the Variant constructor.

Parameters

v Provides initial values for the SAFEARRAY elements.


toBoolean (Variant Class)

 Microsoft SDK for Java

toBoolean

This method of the Variant Class coerces the Variant object to a VT_BOOL and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native boolean toBoolean() throws ClassCastException;

Return Value

Returns the coerced value that is converted to a Java boolean.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toByte (Variant Class)

 Microsoft SDK for Java

toByte

This method of the Variant Class coerces the Variant object to a VT_UI1 and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native byte toByte() throws ClassCastException;

Return Value

Returns the coerced value that is converted to a Java byte.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toByteArray (Variant Class)

 Microsoft SDK for Java

toByteArray

This method of the Variant Class retrieves the value of a VT_ARRAY|VT_UI1 or VT_BYREF|VT_ARRAY|VT_UI1 as a one-dimensional byte[] array. This method has been superceded by the toSafeArray method.

Syntax

public native Object toByteArray();

Return Value

Returns a byte array.


toCharArray (Variant Class)

 Microsoft SDK for Java

toCharArray

This method of the Variant Class retrieves the value of a VT_ARRAY|VT_I2 or VT_BYREF|VT_ARRAY|VT_I2 as a one-dimensional char[] array. This method has been superceded by the toSafeArray method.

Syntax

public native Object toCharArray();

Return Value

Returns a character array.


toCurrency (Variant Class)

 Microsoft SDK for Java

toCurrency

This method of the Variant Class coerces the Variant object to a VT_CY and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native long toCurrency() throws ClassCastException;

Return Value

Returns the coerced value converted to a Java long.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toDate (Variant Class)

 Microsoft SDK for Java

toDate

This method of the Variant Class coerces the Variant object to a VT_DATE and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native double toDate() throws ClassCastException;

Return Value

Returns the coerced value that is converted to a Java double.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toDispatch (Variant Class)

 Microsoft SDK for Java

toDispatch

This method of the Variant Class coerces the Variant object to a VT_DISPATCH and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native Object toDispatch() throws ClassCastException;

Return Value

Returns the coerced value that is converted to a Java object.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toDouble (Variant Class)

 Microsoft SDK for Java

toDouble

This method of the Variant Class coerces the Variant object to a VT_R8 and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native double toDouble() throws ClassCastException;

Return Value

Returns the coerced value converted to a Java double.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toError (Variant Class)

 Microsoft SDK for Java

toError

This method of the Variant Class coerces the Variant object to a VT_ERROR and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native int toError() throws ClassCastException;

Return Value

Returns the coerced value that is converted to a Java integer.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toFloat (Variant Class)

 Microsoft SDK for Java

toFloat

This method of the Variant Class coerces the Variant object to a VT_R4 and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native float toFloat() throws ClassCastException;

Return Value

Returns the coerced value converted to a Java float.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toInt (Variant Class)

 Microsoft SDK for Java

toInt

This method of the Variant Class coerces the Variant object to a VT_I4 and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native int toInt() throws ClassCastException;

Return Value

Returns the coerced value converted to a Java integer.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toObject (Variant Class)

 Microsoft SDK for Java

toObject

This method of the Variant Class coerces the Variant object to a VT_UNKNOWN and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native Object toObject() throws ClassCastException;

Return Value

Returns the coerced value that is converted to a Java object.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toSafeArray (Variant Class)

 Microsoft SDK for Java

toSafeArray

This method of the Variant Class extracts a SafeArray object from a Variant object that has the VT_ARRAY modifier set. This operation does not create an independent SafeArray object, so it can be used to modify the elements of the SafeArray object that is referenced by the Variant.

Syntax

public SafeArray toSafeArray() throws ClassCastException;

Return Value

Returns the coerced value that is converted to a Java SafeArray object.

Exceptions

ClassCastException if the object's type cannot be coerced.


toScriptObject (Variant Class)

 Microsoft SDK for Java

toScriptObject

This method of the Variant Class coerces the Variant object to a VT_UNKNOWN, VT_BSTR, VT_BOOL, or VT_R8 and returns the coerced result.

Syntax

public native Object toScriptObject() throws ClassCastException;

Return Value

Returns the coerced value converted to a Java type as follows:

VT_BSTR is converted to java.lang.String.

VT_BOOL is converted to java.lang.boolean.

Numeric types convertible by Variant.changetype to VT_R8 are converted to java.lang.double.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


toShort (Variant Class)

 Microsoft SDK for Java

toShort

This method of the Variant Class coerces the Variant object to a VT_I2 and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public native short toShort() throws ClassCastException;

Return Value

Returns the coerced value converted to a Java short.

Exceptions

ClassCastException if the Variant object's type cannot be coerced.


toString (Variant Class)

 Microsoft SDK for Java

toString

This method of the Variant Class coerces the Variant object to a VT_BSTR and returns the coerced result. The results of the coercion are not stored in the Variant.

Syntax

public String toString();

Return Value

Returns the coerced value that is converted to a Java string.

Remarks

Unlike the other toXXX methods, no exception is thrown if the variant cannot be coerced to a string. Instead, the toString method of the Object class is called. This is because toString is also the method used for diagnostic printing of all Java objects.


toVariantArray (Variant Class)

 Microsoft SDK for Java

toVariantArray

This method of the Variant Class retrieves the value of either a VT_ARRAY|VT_VARIANT or VT_BYREF|VT_ARRAY|VT_VARIANT Variant. The embedded array must be one-dimensional. This is an "expensive" method, which has been superceded by the toSafeArray method.

Syntax

public native Variant[] toVariantArray();

Return Value

Returns the coerced value converted to a Java array of Variants.


VariantClear (Variant Class)

 Microsoft SDK for Java

VariantClear

This method of the Variant Class forces the Microsoft® Win32® VariantClear function to be called and resets the Variant object to VT_EMPTY.

Syntax

public void VariantClear();


Fields (Variant Class)

 Microsoft SDK for Java

Variant Class Fields

The Variant Class contains the following fields.

VariantArray | Corresponds to the VT_ARRAY modifier.
VariantBoolean | Corresponds to the VT_BOOL variant type.
VariantByref | Corresponds to the VT_BYREF modifier.
VariantByte | Corresponds to the VT_UI1 variant type.
VariantCurrency | Corresponds to the VT_CY variant type.
VariantDate | Corresponds to the VT_DATE variant type.
VariantDispatch | Corresponds to the VT_DISPATCH variant type.
VariantDouble | Corresponds to the VT_R8 variant type.
VariantEmpty | Corresponds to the VT_EMPTY variant type.
VariantError | Corresponds to the VT_ERROR variant type.
VariantFloat | Corresponds to the VT_R4 variant type.
VariantInt | Corresponds to the VT_I4 variant type.
VariantNull | Corresponds to the VT_NULL variant type.
VariantObject | Corresponds to the VT_UNKNOWN variant type.
VariantShort | Corresponds to the VT_I2 variant type.
VariantString | Corresponds to the VT_BSTR variant type.
VariantTypeMask | Masks off variant type modifiers.
VariantVariant | Corresponds to the VT_VARIANT variant type.


WrongThreadException Class (com.ms.com Package)

 Microsoft SDK for Java

WrongThreadException Class

The WrongThreadException Class of the com.ms.com package represents objects that are thrown when a method call cannot be made because it was called on the wrong thread. Typically, WrongThreadException objects are thrown when an operation invokes an Apartment Model Component Object Model (COM) object on the wrong thread.

public class WrongThreadException extends RuntimeException
{
  // Constructors
  public WrongThreadException();
  public WrongThreadException(String s);
}

Hierarchy

RuntimeException
  |
  +--WrongThreadException


Constructors (WrongThreadException Class)

 Microsoft SDK for Java

WrongThreadException Class Constructors

The WrongThreadException Class contains the following constructors:

WrongThreadException()
WrongThreadException(String s)

WrongThreadException()

Creates an instance of the WrongThreadException class.

Syntax

public WrongThreadException();

WrongThreadException(String s)

Creates an instance of the WrongThreadException class that contains a description of the exception.

Syntax

public WrongThreadException(String s);

Parameters

s A description of the exception.


ComContext Interface (com.ms.com Package)

 Microsoft SDK for Java

ComContext Interface

The ComContext Interface of the com.ms.com package defines constants that specify the contexts that a Component Object Model (COM) class can run in.

public interface ComContext
{
  // Fields
  public static final int INPROC_HANDLER;
  public static final int INPROC_HANDLER16;
  public static final int INPROC_HANDLERX86;
  public static final int INPROC_SERVER;
  public static final int INPROC_SERVER16;
  public static final int INPROC_SERVERX86;
  public static final int LOCAL_SERVER;
  public static final int REMOTE_SERVER;
}


Fields (ComContext Interface)

 Microsoft SDK for Java

ComContext Interface Fields

The ComContext Interface contains the following fields.

INPROC_HANDLER | A handler DLL that runs in the same process as the caller.
INPROC_HANDLER16 | A 16-bit handler DLL that runs in the same process as the caller.
INPROC_HANDLERX86 | An x86 handler DLL that runs in the same process as the caller.
INPROC_SERVER | A server DLL that runs in the same process as the caller.
INPROC_SERVER16 | A 16-bit server DLL that runs in the same process as the caller.
INPROC_SERVERX86 | An x86 server DLL that runs in the same process as the caller.
LOCAL_SERVER | A server .exe file that runs on the same computer as the caller but in a different process.
REMOTE_SERVER | A remote server .exe file that runs on a different computer than the caller does.


IAccessible Interface (com.ms.com Package)

 Microsoft SDK for Java

IAccessible Interface

The IAccessible Interface of the com.ms.com package provides methods that enable users to request selection and focus information, perform hit tests, and navigate by using object and child identifiers.

public interface IAccessible extends IUnknown
{
  // Fields
  public static final com.ms.com._Guid iid;

  // Methods
  public void accDoDefaultAction(Variant varChild);
  public Variant accHitTest(int xLeft, int yTop);
  public void accLocation(int[] pxLeft, int[] pyTop,
        int[] pcxWidth, int[] pcyHeight, Variant varChild);
  public Variant accNavigate(int navDir, Variant varStart);
  public void accSelect(int flagsSelect, Variant varChild);
  public Object getAccChild(Variant varChild);
  public int getAccChildCount();
  public String getAccDefaultAction(Variant varChild);
  public String getAccDescription(Variant varChild);
  public Variant getAccFocus();
  public String getAccHelp(Variant varChild);
  public int getAccHelpTopic(String[] pszHelpFile,
        Variant varChild);
  public String getAccKeyboardShortcut(Variant varChild);
  public String getAccName(Variant varChild);
  public Object getAccParent();
  public Variant getAccRole(Variant varChild);
  public Variant getAccSelection();
  public Variant getAccState(Variant varChild);
  public String getAccValue(Variant varChild);
  public void setAccName(Variant varChild, String pszName);
  public void setAccValue(Variant varChild, String pszValue);
}

Accessible objects maintain properties that help describe the object's appearance, nature, and purpose. The IAccessible interface extends methods that enable a client application to retrieve these properties. By using the information that these properties provide, an accessibility aid can determine useful information and convey it as needed.

In the following methods, the Variant object varChild identifies a child of the IAccessible object or indicates the object itself. The value of this parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").

If a container object does not support the IEnumVariant interface, its child ID numbers must be sequential positive integers starting with 1. If the object supports IEnumVariant, it can use any method to assign its child ID numbers.

Hierarchy

IUnknown
  |
  +--IAccessible


Methods (IAccessible Interface)

 Microsoft SDK for Java

IAccessible Interface Methods

The IAccessible Interface contains the following methods:

accDoDefaultAction performs the object's default action.
accHitTest retrieves the child object at a specified location on the screen.
accLocation retrieves the screen location of an accessibility object.
accNavigate retrieves the sibling or child object that is navigated to in a specified direction.
accSelect changes focus and modifies selection according to specified flags.
getAccChild retrieves a specified child object.
getAccChildCount retrieves the number of components in the parent container.
getAccDefaultAction retrieves the default action for a specified child object.
getAccDescription retrieves a description of the child object.
getAccFocus retrieves the child object that currently has the keyboard focus.
getAccHelp provides Help text associated with the object.
getAccHelpTopic retrieves the full path of the Help file associated with the object, as well as a value that identifies the Help file topic.
getAccKeyboardShortcut retrieves the keyboard shortcut that selects the object.
getAccName retrieves the name property of the child object.
getAccParent retrieves the parent object (the container) of the child object.
getAccRole retrieves the role property of a specified child object.
getAccSelection retrieves the selected children of the object.
getAccState retrieves the current state code of the object.
getAccValue retrieves the value property of the child object.
setAccName sets the name of a child object.
setAccValue sets the value of a child object.


accDoDefaultAction (IAccessible Interface)

 Microsoft SDK for Java

accDoDefaultAction

This method of the IAccessible Interface performs the object's default action.

Syntax

public void accDoDefaultAction(Variant varChild);

Parameters

varChild A value that identifies the child object whose default action is performed.


accHitTest (IAccessible Interface)

 Microsoft SDK for Java

accHitTest

This method of the IAccessible Interface retrieves the child object at a specified location on the screen. That is, a point on the screen is tested to see if there is a child object (a hit) located at that point.

Syntax

public Variant accHitTest(int xLeft, int yTop);

Return Value

Returns a Variant object that describes the child object located at the specified coordinates.

Parameters

xLeft | The x-coordinate of the point on the screen that is hit-tested.
yTop | The y-coordinate of the point on the screen that is hit-tested.


accLocation (IAccessible Interface)

 Microsoft SDK for Java

accLocation

This method of the IAccessible Interface retrieves the screen location of an accessibility object. The varChild parameter indicates whether this method will retrieve the coordinates of the container itself or of one of its children.

Syntax

public void accLocation(int[] pxLeft, int[] pyTop, int[] pcxWidth, int[] pcyHeight, Variant varChild);

Parameters

pxLeft | The retrieved x-coordinate of the object's screen location.
pyTop | The retrieved y-coordinate of the object's screen location.
pcxWidth | The object's retrieved width, measured in pixels.
pcyHeight | The object's retrieved height, measured in pixels.
varChild | A value that identifies the child object whose location is retrieved.


accNavigate (IAccessible Interface)

 Microsoft SDK for Java

accNavigate

This method of the IAccessible Interface retrieves the sibling or child object that is navigated to in a specified direction.

Syntax

public Variant accNavigate(int navDir, Variant varStart);

Return Value

Returns a Variant object that contains information about the object that is navigated to.

Parameters

navDir | The navigation code that specifies the navigation direction.
varStart | A Variant object that specifies the type of navigation desired. If the variant type is VT_EMPTY, the method retrieves a sibling object. If the variant type is VT_I4 and the value is CHILDID_SELF, the method retrieves a child object.


accSelect (IAccessible Interface)

 Microsoft SDK for Java

accSelect

This method of the IAccessible Interface changes focus and modifies selection according to specified flags.

Syntax

public void accSelect(int flagsSelect, Variant varChild);

Parameters

flagsSelect | The selection flags, which indicate how to change the focus and selection. They must be set to some combination of the following: SELFLAG_NONE, SELFLAG_TAKEFOCUS, SELFLAG_TAKESELECTION, SELFLAG_EXTENDSELECTION, SELFLAG_ADDSELECTION, and SELFLAG_REMOVESELECTION.
varChild | A value that identifies the child object that is selected.


getAccChild (IAccessible Interface)

 Microsoft SDK for Java

getAccChild

This method of the IAccessible Interface retrieves a specified child object.

Syntax

public Object getAccChild(Variant varChild);

Return Value

Returns the requested child object.

Parameters

varChild A Variant object that identifies the child to retrieve.


getAccChildCount (IAccessible Interface)

 Microsoft SDK for Java

getAccChildCount

This method of the IAccessible Interface retrieves the number of components in the parent container.

Syntax

public int getAccChildCount();

Return Value

Returns the number of components in the parent container.


getAccDefaultAction (IAccessible Interface)

 Microsoft SDK for Java

getAccDefaultAction

This method of the IAccessible Interface retrieves the default action for a specified child object.

Syntax

public String getAccDefaultAction(Variant varChild);

Return Value

Returns a string that describes the default action of the child object.

Parameters

varChild A value that identifies the child object for which the default action is requested.


getAccDescription (IAccessible Interface)

 Microsoft SDK for Java

getAccDescription

This method of the IAccessible Interface retrieves a description of the child object.

Syntax

public String getAccDescription(Variant varChild);

Return Value

Returns a description of the child object.

Parameters

varChild The value that identifies the child whose description is retrieved.


getAccFocus (IAccessible Interface)

 Microsoft SDK for Java

getAccFocus

This method of the IAccessible Interface retrieves the child object that currently has the keyboard focus. If the object itself has the keyboard focus, this method returns zero as a VT_14 type. If a child has the focus but isn't an accessible object, it returns the child ID as a VT_14 type. If a child has the focus and is an accessible object, this method returns its IDispatch interface.

Syntax

public Variant getAccFocus();

Return Value

Returns the Variant object that contains information about the retrieved child object.


getAccHelp (IAccessible Interface)

 Microsoft SDK for Java

getAccHelp

This method of the IAccessible Interface provides Help text associated with the object.

Syntax

public String getAccHelp(Variant varChild);

Return Value

Returns a string that describes the object's function.

Parameters

varChild A value that identifies the child object for which the Help text is requested.


getAccHelpTopic (IAccessible Interface)

 Microsoft SDK for Java

getAccHelpTopic

This method of the IAccessible Interface retrieves the full path of the Help file associated with the object, as well as a value that identifies the Help file topic. This method is not implemented at this time.

Syntax

public int getAccHelpTopic(String[] pszHelpFile, Variant varChild);

Return Value

Returns a value that identifies the object's Help topic.

Parameters

pszHelpFile | The retrieved Help file path for the object.
varChild | A value that identifies the child object for which the Help topic is requested.


getAccKeyboardShortcut (IAccessible Interface)

 Microsoft SDK for Java

getAccKeyboardShortcut

This method of the IAccessible Interface retrieves the keyboard shortcut that selects the object.

Syntax

public String getAccKeyboardShortcut(Variant varChild);

Return Value

Returns a string that describes a sequence of keystrokes for selecting the object.

Parameters

varChild A value that identifies the child object for which the keyboard shortcut is requested.

Exceptions

com.ms.com.ComFailException if the specified object is not valid.


getAccName (IAccessible Interface)

 Microsoft SDK for Java

getAccName

This method of the IAccessible Interface retrieves the name property of the child object.

Syntax

public String getAccName(Variant varChild);

Return Value

Returns the name of the child object.

Parameters

varChild The value that identifies the child whose name is retrieved.


getAccParent (IAccessible Interface)

 Microsoft SDK for Java

getAccParent

This method of the IAccessible Interface retrieves the parent object (the container) of the child object.

Syntax

public Object getAccParent();

Return Value

Returns the parent of the object.


getAccRole (IAccessible Interface)

 Microsoft SDK for Java

getAccRole

This method of the IAccessible Interface retrieves the role property of a specified child object.

Syntax

public Variant getAccRole(Variant varChild);

Return Value

Returns a Variant object that contains a role constant or a string that describes the object's role.

Parameters

varChild The value that identifies the child object whose role is requested.


getAccSelection (IAccessible Interface)

 Microsoft SDK for Java

getAccSelection

This method of the IAccessible Interface retrieves the selected children of the object.

Syntax

public Variant getAccSelection();

Return Value

Returns a Variant object that identifies the child object or objects that are selected.


getAccState (IAccessible Interface)

 Microsoft SDK for Java

getAccState

This method of the IAccessible Interface retrieves the current state code of the object.

Syntax

public Variant getAccState(Variant varChild);

Return Value

Returns a Variant object that describes the state of the object, either a string or a value equal to one or more of the object state constants.

Parameters

varChild The value that identifies the child object for which the state code is requested.


getAccValue (IAccessible Interface)

 Microsoft SDK for Java

getAccValue

This method of the IAccessible Interface retrieves the value property of the child object.

Syntax

public String getAccValue(Variant varChild);

Return Value

Returns the value of the child object.

Parameters

varChild The Variant object that identifies the child whose value is retrieved.


setAccName (IAccessible Interface)

 Microsoft SDK for Java

setAccName

This method of the IAccessible Interface sets the name of a child object.

Syntax

public void setAccName(Variant varChild, String pszName);

Parameters

varChild | A value that identifies the child object whose name is set by this method.
pszName | The child object's new name.


setAccValue (IAccessible Interface)

 Microsoft SDK for Java

setAccValue

This method of the IAccessible Interface sets the value of a child object.

Syntax

public void setAccValue(Variant varChild, String pszValue);

Parameters

varChild | The Variant object that identifies the child whose value is set by this method.
pszValue | The new value.


Fields (IAccessible Interface)

 Microsoft SDK for Java

IAccessible Interface Fields

The IAccessible Interface contains the following fields.

iid The interface identifier.


IAccessibleDefault Interface (com.ms.com Package)

 Microsoft SDK for Java

IAccessibleDefault Interface

The IAccessibleDefault Interface of the com.ms.com package provides methods that enable users to request selection and focus information, perform hit tests, and navigate by using object and child identifiers. IAccessibleDefault extends the IAccessible interface.

public interface IAccessibleDefault extends IAccessible
{
  // Fields
  public static final _Guid iid;

  // Methods
  public void accDoDefaultAction(Variant varChild);
  public Variant accHitTest(int xLeft, int yTop);
  public void accLocation(int[] pxLeft, int[] pyTop,
        int[] pcxWidth, int[] pcyHeight, Variant varChild);
  public Variant accNavigate(int navDir, Variant varStart);
  public void accSelect(int flagsSelect, Variant varChild);
  public Object getAccChild(Variant varChild);
  public int getAccChildCount();
  public String getAccDefaultAction(Variant varChild);
  public String getAccDescription(Variant varChild);
  public Variant getAccFocus();
  public String getAccHelp(Variant varChild);
  public int getAccHelpTopic(String[] pszHelpFile,
        Variant varChild);
  public String getAccKeyboardShortcut(Variant varChild);
  public String getAccName(Variant varChild);
  public Object getAccParent();
  public Variant getAccRole(Variant varChild);
  public Variant getAccSelection();
  public Variant getAccState(Variant varChild);
  public String getAccValue(Variant varChild);
  public void setAccName(Variant varChild, String pszName);
  public void setAccValue(Variant varChild, String pszValue);
}

In the following methods, the Variant object varChild identifies a child of the IAccessible object or indicates the object itself. This value of the parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").

If a container object does not support the IEnumVariant interface, its child ID numbers must be sequential positive integers starting with 1. If the object supports IEnumVariant, it can use any method to assign its child ID numbers.

Hierarchy

IUnknown
  |
  +--IAccessible
    |
    +--IAccessibleDefault


Methods (IAccessibleDefault Interface)

 Microsoft SDK for Java

IAccessibleDefault Interface Methods

The IAccessibleDefault Interface contains the following methods:

accDoDefaultAction performs the object's default action.
accHitTest retrieves the child object at a specified location on the screen.
accLocation retrieves the screen location of an accessibility object.
accNavigate retrieves the sibling or child object that is navigated to in a specified direction.
accSelect changes focus and modifies selection according to specified flags.
getAccChild retrieves a specified child object.
getAccChildCount retrieves the number of components in the parent container.
getAccDefaultAction retrieves the default action for a specified child object.
getAccDescription retrieves a description of the child object.
getAccFocus retrieves the child object that currently has the keyboard focus.
getAccHelp provides Help text associated with the object.
getAccHelpTopic retrieves the full path of the Help file associated with the object, as well as a value that identifies the Help file topic.
getAccKeyboardShortcut retrieves the keyboard shortcut that selects the object.
getAccName retrieves the name property of the child object.
getAccParent retrieves the parent object (the container) of the child object.
getAccRole retrieves the role property of a specified child object.
getAccSelection retrieves the selected children of the object.
getAccState retrieves the current state code of the object.
getAccValue retrieves the value property of the child object.
setAccName sets the name of a child object.
setAccValue sets the value of a child object.


accDoDefaultAction (IAccessibleDefault Interface)

 Microsoft SDK for Java

accDoDefaultAction

This method of the IAccessibleDefault Interface performs the object's default action.

Syntax

public void accDoDefaultAction(Variant varChild);

Parameters

varChild A value that identifies the child object whose default action is performed.

Overrides

accDoDefaultAction(Variant) in IAccessible.


accHitTest (IAccessibleDefault Interface)

 Microsoft SDK for Java

accHitTest

This method of the IAccessibleDefault Interface retrieves the child object at a specified location on the screen. That is, a point on the screen is tested to see if there is a child object (a hit) located at that point.

Syntax

public Variant accHitTest(int xLeft, int yTop);

Return Value

Returns a Variant object that describes the child object located at the specified coordinates.

Parameters

xLeft | The x-coordinate of the point on the screen that is hit-tested.
yTop | The y-coordinate of the point on the screen that is hit-tested

Overrides

accHitTest(int,int) in IAccessible.


accLocation (IAccessibleDefault Interface)

 Microsoft SDK for Java

accLocation

This method of the IAccessibleDefault Interface retrieves the screen location of an accessibility object. The varChild parameter indicates whether this method will retrieve the coordinates of the container itself or of one of its children.

Syntax

public void accLocation(int[] pxLeft, int[] pyTop, int[] pcxWidth, int[] pcyHeight, Variant varChild);

Parameters

pxLeft | The retrieved x-coordinate of the object's screen location.
pyTop | The retrieved y-coordinate of the object's screen location.
pcxWidth | The object's retrieved width, measured in pixels.
pcyHeight | The object's retrieved height, measured in pixels.
varChild | A value that identifies the child object whose location is retrieved.

Overrides

accLocation(int[],int[],int[],int[],Variant) in IAccessible.


accNavigate (IAccessibleDefault Interface)

 Microsoft SDK for Java

accNavigate

This method of the IAccessibleDefault Interface retrieves the sibling or child object that is navigated to in a specified direction.

Syntax

public Variant accNavigate(int navDir, Variant varStart);

Return Value

Returns a Variant object that contains information about the object that is navigated to.

Parameters

navDir | The navigation code that specifies the navigation direction.
varStart | The Variant object that specifies the type of navigation needed. If the variant type is VT_EMPTY, the method retrieves a sibling object. If the variant type is VT_I4 and the value is CHILDID_SELF, the method retrieves a child object.

Overrides

accNavigate(int,Variant) in IAccessible.


accSelect (IAccessibleDefault Interface)

 Microsoft SDK for Java

accSelect

This method of the IAccessibleDefault Interface changes focus and modifies selection according to specified flags.

Syntax

public void accSelect(int flagsSelect, Variant varChild);

Parameters

flagsSelect | The selection flags, which indicate how to change the focus and selection. They must be set to some combination of the following: SELFLAG_NONE, SELFLAG_TAKEFOCUS, SELFLAG_TAKESELECTION, SELFLAG_EXTENDSELECTION, SELFLAG_ADDSELECTION, and SELFLAG_REMOVESELECTION.
varChild | A value that identifies the child object that is selected.

Overrides

accSelect(int,Variant) in IAccessible.


getAccChild (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccChild

This method of the IAccessibleDefault Interface retrieves a specified child object.

Syntax

public Object getAccChild(Variant varChild);

Return Value

Returns the requested child object.

Parameters

varChild A Variant object that identifies the child to retrieve.

Overrides

getAccChild(Variant) in IAccessible.


getAccChildCount (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccChildCount

This method of the IAccessibleDefault Interface retrieves the number of components in the parent container.

Syntax

public int getAccChildCount();

Return Value

Returns the number of components in the parent container.

Overrides

getAccChildCount() in IAccessible.


getAccDefaultAction (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccDefaultAction

This method of the IAccessibleDefault Interface retrieves the default action for a specified child object.

Syntax

public String getAccDefaultAction(Variant varChild);

Return Value

Returns a string that describes the default action of the child object.

Parameters

varChild A value that identifies the child object that the default action is requested for.

Overrides

getAccDefaultAction(Variant) in IAccessible.


getAccDescription (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccDescription

This method of the IAccessibleDefault Interface retrieves a description of the child object.

Syntax

public String getAccDescription(Variant varChild);

Return Value

Returns a description of the child object.

Parameters

varChild The value that identifies the child whose description is retrieved.

Overrides

getAccDescription(Variant) in IAccessible.


getAccFocus (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccFocus

This method of the IAccessibleDefault Interface retrieves the child object that currently has the keyboard focus. If the object itself has the keyboard focus, this method returns zero as a VT_14 type. If a child has the focus but isn't an accessible object, it returns the child ID as a VT_14 type. If a child has the focus and is an accessible object, this method returns its IDispatch interface.

Syntax

public Variant getAccFocus();

Return Value

Returns the Variant object that contains information about the retrieved child object.

Overrides

getAccFocus() in IAccessible.


getAccHelp (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccHelp

This method of the IAccessibleDefault Interface provides Help text associated with the object.

Syntax

public String getAccHelp(Variant varChild);

Return Value

Returns a string that describes the object's function.

Parameters

varChild A value that identifies the child object that the Help text is requested for.

Overrides

getAccHelp(Variant) in IAccessible.


getAccHelpTopic (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccHelpTopic

This method of the IAccessibleDefault Interface retrieves the full path of the Help file associated with the object, as well as a value that identifies the Help file topic. This method is not implemented at this time.

Syntax

public int getAccHelpTopic(String[] pszHelpFile, Variant varChild);

Return Value

Returns a value that identifies the object's Help topic.

Parameters

pszHelpFile | The retrieved Help file path for the object.
varChild | A value that identifies the child object that the Help topic is requested for.

Overrides

getAccHelpTopic(String[],Variant) in IAccessible.


getAccKeyboardShortcut (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccKeyboardShortcut

This method of the IAccessibleDefault Interface retrieves the keyboard shortcut that selects the object.

Syntax

public String getAccKeyboardShortcut(Variant varChild);

Return Value

Returns a string that describes a sequence of keystrokes for selecting the object.

Parameters

varChild A value that identifies the child object that the keyboard shortcut is requested for.

Overrides

getAccKeyboardShortcut(Variant) in IAccessible.

Exceptions

com.ms.com.ComFailException if the specified object is not valid.


getAccName (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccName

This method of the IAccessibleDefault Interface retrieves the name property of the child object.

Syntax

public String getAccName(Variant varChild);

Return Value

Returns the name of the child object.

Parameters

varChild The value that identifies the child whose name is retrieved.

Overrides

getAccName(Variant) in IAccessible.


getAccParent (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccParent

This method of the IAccessibleDefault Interface retrieves the parent object (the container) of the child object.

Syntax

public Object getAccParent();

Return Value

Returns the parent of the object.

Overrides

getAccParent() in IAccessible.


getAccRole (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccRole

This method of the IAccessibleDefault Interface retrieves the role property of a specified child object.

Syntax

public Variant getAccRole(Variant varChild);

Return Value

Returns a Variant object that contains a role constant or a string that describes the object's role.

Parameters

varChild The value that identifies the child object whose role is requested.

Overrides

getAccRole(Variant) in IAccessible.


getAccSelection (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccSelection

This method of the IAccessibleDefault Interface retrieves the selected children of the object.

Syntax

public Variant getAccSelection();

Return Value

Returns a Variant object that identifies the object or objects that are selected.

Overrides

getAccSelection() in IAccessible.


getAccState (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccState

This method of the IAccessibleDefault Interface retrieves the current state code of the object.

Syntax

public Variant getAccState(Variant varChild);

Return Value

Returns a Variant that describes the state of the object, either a string or a value equal to one or more of the object state constants.

Parameters

varChild The value that identifies the child object that the state code is requested for.

Overrides

getAccState(Variant) in IAccessible.


getAccValue (IAccessibleDefault Interface)

 Microsoft SDK for Java

getAccValue

This method of the IAccessibleDefault Interface retrieves the value property of the child object.

Syntax

public String getAccValue(Variant varChild);

Return Value

Returns the value of the child object.

Parameters

varChild The Variant object that identifies the child whose value is retrieved.

Overrides

getAccValue(Variant) in IAccessible.


setAccName (IAccessibleDefault Interface)

 Microsoft SDK for Java

setAccName

This method of the IAccessibleDefault Interface sets the name of a child object.

Syntax

public void setAccName(Variant varChild, String pszName);

Parameters

varChild | A value that identifies the child object whose name is set by this method.
pszName | The child object's new name.

Overrides

setAccName(Variant,String) in IAccessible.


setAccValue (IAccessibleDefault Interface)

 Microsoft SDK for Java

setAccValue

This method of the IAccessibleDefault Interface sets the value of a child object.

Syntax

public void setAccValue(Variant varChild, String pszValue);

Parameters

varChild | The Variant object that identifies the child whose value is set by this method.
pszValue | The new value.

Overrides

setAccValue(Variant,String) in IAccessible.


Fields (IAccessibleDefault Interface)

 Microsoft SDK for Java

Interface IAccessibleDefault Fields

The IAccessibleDefault Interface contains the following field.

iid The interface identifier.


IBindCtx Interface (com.ms.com Package)

 Microsoft SDK for Java

IBindCtx Interface

The IBindCtx Interface of the com.ms.com package provides access to a bind context, which is an object that stores information about a particular moniker binding operation. You pass a bind context as a parameter when calling many methods of IMoniker and in certain functions related to monikers.

Note The IBindCtx interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IBindCtx extends IUnknown
{
  // Methods
  public IEnumString EnumObjectParam();
  public void GetBindOptions(BIND_OPTS pbindopts);
  public IUnknown GetObjectParam(String pszKey);
  public IRunningObjectTable GetRunningObjectTable();
  public void RegisterObjectBound(IUnknown punk);
  public void RegisterObjectParam(String pszKey, IUnknown punk);
  public void ReleaseBoundObjects();
  public void RevokeObjectBound(IUnknown punk);
  public boolean RevokeObjectParam(String pszKey);
  public void SetBindOptions(BIND_OPTS pbindopts);

IUnknown
  |
  +--IClassFactory


Methods (IBindCtx Interface)

 Microsoft SDK for Java

IBindCtx Interface Methods

The IBindCtx interface has the following methods:

EnumObjectParam enumerates all the string keys in the table.
GetBindOptions retrieves the binding options.
GetObjectParam returns the object associated with a given string key.
GetRunningObjectTable retrieves a pointer to the Running Object Table.
RegisterObjectBound registers an object with the bind context.
RegisterObjectParam associates an object with a string key.
ReleaseBoundObjects releases all registered objects.
RevokeObjectBound revokes an object's registration.
RevokeObjectParam revokes association between an object and a string key.
SetBindOptions sets the binding options.


EnumObjectParam (IBindCtx Interface)

 Microsoft SDK for Java

EnumObjectParam

This method of the IBindCtx interface supplies a pointer to an IEnumString interface on an enumerator that can return the keys of the bind context's string-keyed table of pointers.

Syntax

public IEnumString EnumObjectParam();

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK -- An enumerator was successfully created and the pointer supplied.


GetBindOptions (IBindCtx Interface)

 Microsoft SDK for Java

GetBindOptions

This method of the IBindCtx interface returns the binding options stored in this bind context.

Syntax

public void GetBindOptions(BIND_OPTS pbindopts);

Return Values

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK -- The stored binding options were successfully returned.

Parameters

[in, out] pbindopts The pointer to an initialized BIND_OPTS structure on entry that receives the current binding parameters on return.


GetObjectParam (IBindCtx Interface)

 Microsoft SDK for Java

GetObjectParam

This method of the IBindCtx interface retrieves the pointer associated with the specified key in the bind context's string-keyed table of pointers.

Syntax

public IUnknown GetObjectParam(String pszKey);

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK -- The pointer associated with the specified key was successfully returned.

Parameters

[in] pszKey The pointer to a zero-terminated wide character string (two bytes per character) containing the key to search for. Key string comparison is case-sensitive.


GetRunningObjectTable (IBindCtx Interface)

 Microsoft SDK for Java

GetRunningObjectTable

This method of the IBindCtx interface provides an interface pointer to the Running Object Table (ROT) for the computer on which this bind context is running.

Syntax

public IRunningObjectTable GetRunningObjectTable();

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK -- A pointer to the ROT was returned successfully.


RegisterObjectBound (IBindCtx Interface)

 Microsoft SDK for Java

RegisterObjectBound

This method of the IBindCtx interface calls IUnknown::AddRef on the specified object to ensure that the object remains active until the bind context is released. The method stores a pointer to the object in the bind context's internal list of pointers.

Syntax

public void RegisterObjectBound(IUnknown punk);

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK -- The object was successfully registered.

Parameters

[in] punk The pointer to the IUnknown interface on the object that is being registered as bound.


RegisterObjectParam (IBindCtx Interface)

 Microsoft SDK for Java

RegisterObjectParam

This method of the IBindCtx interface stores an IUnknown pointer on the specified object under the specified key in the bind context's string-keyed table of pointers. The method must call IUnknown::AddRef on the stored pointer.

Syntax

public void RegisterObjectParam(String pszKey, IUnknown punk);

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK -- The pointer was successfully registered under the specified string.

Parameters

[in] pszKey | The pointer to a zero-terminated wide character string (two bytes per character) containing the key under which the object is being registered. Key string comparison is case-sensitive.
[in] punk | The pointer to the IUnknown interface on the object that is to be registered.


ReleaseBoundObjects (IBindCtx Interface)

 Microsoft SDK for Java

ReleaseBoundObjects

This method of the IBindCtx interface Releases all pointers to all objects that were previously registered by calls to RegisterObjectBound.

Syntax

public void ReleaseBoundObjects();

Return Values

S_OK -- The objects were released successfully.


RevokeObjectBound (IBindCtx Interface)

 Microsoft SDK for Java

RevokeObjectBound

This method of the IBindCtx interface releases the IUnknown pointer to the specified object and removes that pointer from the bind context's internal list of pointers. This undoes a previous call to RegisterObjectBound for the same object.

Syntax

public void RevokeObjectBound(IUnknown punk);

Return Values

S_OK -- The object was released successfully.

MK_E_NOTBOUND -- Indicates that punk was not previously registered with a call to RegisterObjectBound.

Parameters

[in] punk The pointer to the IUnknown interface on the object to be released.


RevokeObjectParam (IBindCtx Interface)

 Microsoft SDK for Java

RevokeObjectParam

This method of the IBindCtx interface removes the specified key and its associated pointer from the bind context's string-keyed table of objects. The key must have previously been inserted into the table with a call to RegisterObjectParam.

Syntax

public boolean RevokeObjectParam(String pszKey);

Return Values

S_OK -- The specified key was successfully removed from the table.

S_FALSE -- No object has been registered with the specified key.

Parameters

[in] pszKey The pointer to a zero-terminated wide character string (two bytes per character) containing the key to remove. Key string comparison is case-sensitive.


SetBindOptions (IBindCtx Interface)

 Microsoft SDK for Java

SetBindOptions

This method of the IBindCtx interface specifies new values for the binding parameters stored in the bind context. Subsequent binding operations can call GetBindOptions to retrieve the parameters.

Syntax

public void SetBindOptions(BIND_OPTS pbindopts);

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK -- The parameters were stored successfully.

Parameters

[in] pbindopts The pointer to a BIND_OPTS structure containing the binding parameters.


IClassFactory Interface (com.ms.com Package)

 Microsoft SDK for Java

IClassFactory Interface

The IClassFactory Interface of the com.ms.com package deals with an entire class of objects, and so is implemented on the class object for a specific class of objects (identified by a CLSID).

You must implement this interface for every class that you register in the system registry and to which you assign a CLSID, so objects of that class can be created.

Note The IClassFactory interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IClassFactory extends IUnknown
{
  // Methods
  public IUnknown CreateInstance(IUnknown pUnkOuter, _Guid riid);
  public void LockServer(boolean fLock);
}

IUnknown
  |
  +--IClassFactory


Methods (IClassFactory Interface)

 Microsoft SDK for Java

IClassFactory Interface Methods

The IClassFactory Interface contains the following methods:

CreateInstance
LockServer


CreateInstance (IClassFactory Interface)

 Microsoft SDK for Java

CreateInstance

This method of the IClassFactory Interface creates an uninitialized object of a specified CLSID.

Syntax

public IUnknown CreateInstance(IUnknown pUnkOuter, _Guid riid);

Return Values

This method supports the standard return values E_UNEXPECTED, E_OUTOFMEMORY, and E_INVALIDARG, as well as the following:

S_OK -- The specified object was created.

CLASS_E_NOAGGREGATION -- The pUnkOuter parameter was non-NULL and the object does not support aggregation.

Parameters

[in] pUnkOuter | If the object is being created as part of an aggregate, this is a pointer to the controlling IUnknown interface of the aggregate. Otherwise, pUnkOuter must be NULL.
[in] riid | Reference to the identifier of the interface to be used to communicate with the newly created object. If pUnkOuter is NULL, riid is frequently the IID of the initializing interface; if pUnkOuter is non-NULL, riid must be IID_IUnknown (defined in the header as the IID for IUnknown).


LockServer (IClassFactory Interface)

 Microsoft SDK for Java

LockServer

This method of the IClassFactory Interface locks the object's server in memory, allowing new objects to be created more quickly.

Syntax

public void LockServer(boolean fLock);

Return Values

This method supports the standard return values E_FAIL, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK -- The specified object was either locked (fLock = TRUE) or unlocked from memory (fLock = FALSE).

Parameters

[in]fLock If TRUE, increments the lock count; if FALSE, decrements the lock count.


IClassFactory2 Interface (com.ms.com package)

 Microsoft SDK for Java

IClassFactory2 Interface

This interface of the com.ms.com package enables a class factory object in any kind of server to control object creation through licensing. This extension to IClassFactory enables a class factory executing on a licensed machine to provide a license key that can be used later to create an object instance on an unlicensed machine. Such considerations are important for objects like controls that are used to build applications on a licensed machine. Subsequently, the application built must be able to run on an unlicensed machine. The license key gives only that one client application the right to create objects through IClassFactory2 when a full machine license does not exist.

public interface IClassFactory2 extends IClassFactory
{
  // Methods
  public IUnknown CreateInstance(IUnknown pUnkOuter, _Guid riid);
  public IUnknown CreateInstanceLic(IUnknown pUnkOuter,
    IUnknown pUnkReserved, _Guid riid, String bstrKey);
  public LICINFO GetLicInfo();
  public void LockServer(boolean fLock);
  public String RequestLicKey(int dwReserved);
}


Methods (IClassFactory2 Interface)

 Microsoft SDK for Java

IClassFactory2 Interface Methods

The IClassFactory2 interface has the following methods that are unique to it (CreateInstance and LockServer are inherited from IClassFactory and are described there):

CreateInstanceLic creates an instance of the licensed object given a license key from RequestLicKey.
GetLicInfo fills a LICINFO structure with information on the licensing capabilities of this class factory.
RequestLicKey creates and returns a license key that the caller can save and use later in calls to CreateInstanceLic.


CreateInstanceLic (IClassFactory2 Interface)

 Microsoft SDK for Java

CreateInstanceLic

This method of the IClassFactory2 interface creates an instance of the licensed object given a license key from RequestLicKey.

Syntax

public IUnknown CreateInstanceLic(IUnknown pUnkOuter, IUnknown pUnkReserved, _Guid riid, String bstrKey);

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The license was successfully created.

E_NOTIMPL

This method is not implemented because objects can only be created on fully licensed machines through CreateInstance.

E_POINTER

The pointers passed in bstrKey are not valid. For example, it may be NULL.

E_NOINTERFACE

The object can be created (and the license key is valid) except the object does not support the interface specified by riid.

CLASS_E_NOAGGREGATION

The pUnkOuter parameter is non-NULL, but this object class does not support aggregation.

CLASS_E_NOTLICENSED

The key provided in bstrKey is not a valid license key.

Parameters

pUnkOuter | [in] Pointer to the controlling IUnknown interface on the outer unknown if this object is being created as part of an aggregate. If the object is not part of an aggregate, this parameter must be NULL.
pUnkReserved | [in] Unused. Must be NULL.
riid | [in] Reference to the identifier of the interface to be used to communicate with the newly created object.
bstrKey | [in] Run-time license key previously obtained from RequestLicKey that is required to create an object.


GetLicInfo (IClassFactory2 Interface)

 Microsoft SDK for Java

GetLicInfo

This method of the IClassFactory2 interface fills a LICINFO structure with information on the licensing capabilities of this class factory.

Syntax

public LICINFO GetLicInfo();

Return Value

This method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK

The LICINFO structure was successfully filled in.


RequestLicKey (IClassFactory2 Interface)

 Microsoft SDK for Java

RequestLicKey

This method of the IClassFactory2 interface creates and returns a license key that the caller can save and use later in calls to CreateInstanceLic.

Syntax

public String RequestLicKey(int dwReserved);

Return Value

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The license key was successfully created.

E_NOTIMPL

This class factory does not support run-time license keys.

CLASS_E_NOTLICENSED

This class factory supports run-time licensing, but the current machine itself is not licensed. Thus, a run-time key is not available on this machine.

Parameters

dwReserved [in] Unused. Must be zero.


IConnectionPoint Interface (com.ms.com package)

 Microsoft SDK for Java

IConnectionPoint Interface

This interface of the com.ms.com package supports connection points for connectable objects.

To create a connectable object, you need to implement objects that provide four related interfaces:

  • IConnectionPoint

  • IConnectionPointContainer

  • IEnumConnectionPoints

  • IEnumConnections

IConnectionPointContainer indicates the existence of the outgoing interfaces, and provides access to an enumerator sub-object with the IEnumConnectionPoints interface. It also provides a connection point sub-object with the IConnectionPoint interface. The IConnectionPoint interface provides access to an enumerator sub-object with the IEnumConnections interface.

Note The IConnectionPoint interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IConnectionPoint extends IUnknown
{
  // Methods
  public _Guid GetConnectionInterface();
  public IConnectionPointContainer GetConnectionPointContainer();
  public int Advise(IUnknown pUnkSink);
  public void Unadvise(int dwCookie);
  public IEnumConnections EnumConnections();
}


Methods (IConnectionPoint interface)

 Microsoft SDK for Java

IConnectionPoint Interface Methods

The IConnectionPoint interface contains the following methods:

GetConnectionInterface returns the IID of the outgoing interface managed by this connection point.
GetConnectionPointContainer returns the parent (connectable) object's IConnectionPointContainer interface pointer.
Advise creates a connection between a connection point and a client's sink, where the sink implements the outgoing interface supported by this connection point.
Unadvise terminates a notification previously set up with Advise.
EnumConnections returns an object to enumerate the current advisory connections for this connection point.


Advise (IConnectionPoint interface)

 Microsoft SDK for Java

Advise

This method of the IConnectionPoint interface establishes a connection between the connection point object and the client's sink.

Syntax

public int Advise(IUnknown pUnkSink);

Parameters

[in] pUnkSink The pointer to the IUnknown interface on the client's advise sink. The client's sink receives outgoing calls from the connection point.


EnumConnections (IConnectionPoint interface)

 Microsoft SDK for Java

EnumConnections

This method of the IConnectionPoint interface creates an enumerator object to iterate through the current connections for this connection point.

Syntax

public IEnumConnections EnumConnections();


GetConnectionInterface (IConnectionPoint interface)

 Microsoft SDK for Java

GetConnectionInterface

This method of the IConnectionPoint interface retrieves the IID of the outgoing interface managed by this connection point.

Syntax

public _Guid GetConnectionInterface();


GetConnectionPointContainer (IConnectionPoint interface)

 Microsoft SDK for Java

GetConnectionPointContainer

This method of the IConnectionPoint interface retrieves the IConnectionPointContainer interface pointer for the parent connectable object.

Syntax

public IConnectionPointContainer GetConnectionPointContainer();


Unadvise (IConnectionPoint interface)

 Microsoft SDK for Java

Unadvise

This method of the IConnectionPoint interface terminates an advisory connection previously established through Advise.

Syntax

public void Unadvise(int dwCookie);

Parameters

[in] dwCookie Identifies the connection to terminate.


IConnectionPointContainer Interface (com.ms.com package)

 Microsoft SDK for Java

IConnectionPointContainer Interface

The IConnectionPointContainer interface of the com.ms.com package supports connection points for connectable objects.

To create a connectable object, you need to implement objects that provide four related interfaces:

  • IConnectionPointContainer

  • IEnumConnectionPoints

  • IConnectionPoint

  • IEnumConnections

IConnectionPointContainer indicates the existence of the outgoing interfaces, and provides access to an enumerator sub-object with the IEnumConnectionPoints interface. It also provides a connection point sub-object with the IConnectionPoint interface. The IConnectionPoint interface provides access to an enumerator sub-object with the IEnumConnections interface.

Note The IConnectionPointContainer interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IConnectionPointContainer extends IUnknown
{
  // Methods
  public IEnumConnectionPoints EnumConnectionPoints();
  public IConnectionPoint FindConnectionPoint(_Guid riid);
}


Methods (IConnectionPointContainer interface)

 Microsoft SDK for Java

IConnectionPointContainer Interface Methods

The IConnectionPointContainer interface contains the following methods:

EnumConnectionPoints returns an object to enumerate all the connection points supported in the connectable object.
FindConnectionPoint returns a pointer to the IConnectionPoint interface for a specified connection point.


EnumConnectionPoints (IConnectionPointContainer interface)

 Microsoft SDK for Java

EnumConnectionPoints

This method of the IConnectionPointContainer interface creates an enumerator object to iterate through all the connection points supported in the connectable object, one connection point per outgoing IID.

Syntax

public IEnumConnectionPoints EnumConnectionPoints();


FindConnectionPoint (IConnectionPointContainer interface)

 Microsoft SDK for Java

FindConnectionPoint

This method of the IConnectionPointContainer interface returns a pointer to the IConnectionPoint interface of a connection point for a specified IID if that IID describes a supported outgoing interface.

Syntax

public IConnectionPoint FindConnectionPoint(_Guid riid);

Parameters

[in] riid Interface identifier of the outgoing interface whose connection point object is being requested.


ICreateErrorInfo Interface (com.ms.com package)

 Microsoft SDK for Java

ICreateErrorInfo Interface

This interface of the com.ms.com package returns error information.

public interface ICreateErrorInfo extends IUnknown
{
  // Methods
  public void SetDescription(String szDescription);
  public void SetGUID(_Guid rguid);
  public void SetHelpContext(int dwHelpContext);
  public void SetHelpFile(String szHelpFile);
  public void SetSource(String szSource);
}


Methods (ICreateErrorInfo Interface)

 Microsoft SDK for Java

ICreateErrorInfo Interface Methods

The ICreateErrorInfo interface has the following methods:

SetDescription sets the textual description of the error.
SetGUID sets the GUID for the interface that defined the error.
SetHelpContext sets the Help context ID for the error.
SetHelpFile sets the path of the Help file that describes the error.
SetSource sets the ProgID for the class or application that returned the error.


SetDescription (ICreateErrorInfo Interface)

 Microsoft SDK for Java

SetDescription

This method of the ICreateErrorInfo interface sets the textual description of the error.

Syntax

public void SetDescription(String szDescription);

Parameters

szDescription A brief zero-terminated string that describes the error.


SetGUID (ICreateErrorInfo Interface)

 Microsoft SDK for Java

SetGUID

This method of the ICreateErrorInfo interface sets the GUID for the interface that defined the error.

Syntax

public void SetGUID(_Guid rguid);

Parameters

rguid The GUID of the interface that defined the error, or GUID_NULL if the error was defined by the operating system.


SetHelpContext (ICreateErrorInfo Interface)

 Microsoft SDK for Java

SetHelpContext

This method of the ICreateErrorInfo interface sets the Help context ID for the error.

Syntax

public void SetHelpContext(int dwHelpContext);

Parameters

dwHelpContext The Help context ID for the error.


SetHelpFile (ICreateErrorInfo Interface)

 Microsoft SDK for Java

SetHelpFile

This method of the ICreateErrorInfo interface sets the path of the Help file that describes the error.

Syntax

public void SetHelpFile(String szHelpFile);

Parameters

szHelpFile The fully qualified path of the Help file that describes the error.


SetSource (ICreateErrorInfo Interface)

 Microsoft SDK for Java

SetSource

This method of the ICreateErrorInfo interface sets the ProgID for the class or application that returned the error.

Syntax

public void SetSource(String szSource);

Parameters

szSource A ProgID in the form progname.objectname.


IEnumConnectionPoints interface (com.ms.com package)

 Microsoft SDK for Java

IEnumConnectionPoints Interface

This interface of the com.ms.com package enumerates connection points.

To create a connectable object, you need to implement objects that provide four related interfaces:

  • IEnumConnectionPoints

  • IConnectionPointContainer

  • IConnectionPoint

  • IEnumConnections

IConnectionPointContainer indicates the existence of the outgoing interfaces, and provides access to an enumerator sub-object with the IEnumConnectionPoints interface. It also provides a connection point sub-object with the IConnectionPoint interface. The IConnectionPoint interface provides access to an enumerator sub-object with the IEnumConnections interface.

Note The IEnumConnectionPoints interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IEnumConnectionPoints extends IUnknown
{
  // Methods
  public IEnumConnectionPoints Clone();
  public void Next(int celt, IConnectionPoint[] rgelt, int[] pceltFetched);
  public void Reset();
  public void Skip(int celt);
}


Methods (IEnumConnectionPoints interface)

 Microsoft SDK for Java

IEnumConnectionPoints Interface Methods

The IEnumConnectionPoints interface contains the following methods:

Clone creates another connection point enumerator with the same state as the current enumerator to iterate over the same list.
Next enumerates the next IConnectionPoint pointers in the enumerator's list.
Reset instructs the enumerator to position itself at the beginning of the list of elements.
Skip instructs the enumerator to skip the next celt elements in the enumeration.


Clone (IEnumConnectionPoints interface)

 Microsoft SDK for Java

Clone

This method of the IEnumConnectionPoints interface creates another connection point enumerator with the same state as the current enumerator to iterate over the same list. This method makes it possible to record a point in the enumeration sequence to return to that point at a later time.

Syntax

public IEnumConnectionPoints Clone();


Next (IEnumConnectionPoints interface)

 Microsoft SDK for Java

Next

This method of the IEnumConnectionPoints interface enumerates the next IConnectionPoint pointers in the enumerator's list.

Syntax

public void Next(int celt, IConnectionPoint[] rgelt, int[] pceltFetched);

Parameters

[in] celt | The number of IConnectionPoint values returned in the rgelt array.
[out] rgelt | The array to receive enumerated connection points.
[out] pceltFetched | The pointer to the actual number of connection points returned in rgelt array.


Reset (IEnumConnectionPoints interface)

 Microsoft SDK for Java

Reset

This method of the IEnumConnectionPoints interface instructs the enumerator to position itself at the beginning of the list of elements.

Syntax

public void Reset();


Skip (IEnumConnectionPoints interface)

 Microsoft SDK for Java

Skip

This method of the IEnumConnectionPoints interface instructs the enumerator to skip the next celt elements in the enumeration so that the next call to Next will not return those elements.

Syntax

public void Skip(int celt);

Parameters

[in] celt The number of elements to skip.


IEnumConnections interface (com.ms.com package)

 Microsoft SDK for Java

IEnumConnections Interface

This interface of the com.ms.com package enumerates the current connections for a connectable object.

To create a connectable object, you need to implement objects that provide four related interfaces:

  • IEnumConnections

  • IEnumConnectionPoints

  • IConnectionPointContainer

  • IConnectionPoint

IConnectionPointContainer indicates the existence of the outgoing interfaces, and provides access to an enumerator sub-object with the IEnumConnectionPoints interface. It also provides a connection point sub-object with the IConnectionPoint interface. The IConnectionPoint interface provides access to an enumerator sub-object with the IEnumConnections interface.

Note The IEnumConnections interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IEnumConnections extends IUnknown
{
  // Methods
  public IEnumConnections Clone();
  public void Next(int celt, CONNECTDATA[] rgelt, int[] pceltFetched);
  public void Reset();
  public void Skip(int celt);
}


Methods (IEnumConnections interface)

 Microsoft SDK for Java

IEnumConnections Interface Methods

The IEnumConnections interface has the following methods:

Clone creates another connection point enumerator with the same state as the current enumerator to iterate over the same list.
Next enumerates the next CONNECTDATA pointers in the enumerator's list.
Reset instructs the enumerator to position itself at the beginning of the list of elements.
Skip instructs the enumerator to skip the next celt elements in the enumeration.


Clone (IEnumConnections interface)

 Microsoft SDK for Java

Clone

This method of the IEnumConnections interface creates another connection point enumerator with the same state as the current enumerator to iterate over the same list. This method makes it possible to record a point in the enumeration sequence to return to that point at a later time.

Syntax

public IEnumConnections Clone();


Next (IEnumConnections interface)

 Microsoft SDK for Java

Next

This method of the IEnumConnectionPoints interface enumerates the next CONNECTDATA pointers in the enumerator's list.

Syntax

public void Next(int celt, CONNECTDATA[] rgelt, int[] pceltFetched);

Parameters

[in] celt | The number of CONNECTDATA values returned in the rgelt array.
[out] rgelt | The array to receive enumerated connection points.
[out] pceltFetched | The pointer to the actual number of connection points returned in rgelt array.


Reset (IEnumConnections interface)

 Microsoft SDK for Java

Reset

This method of the IEnumConnectionPoints interface instructs the enumerator to position itself at the beginning of the list of elements.

Syntax

public void Reset();


Skip (IEnumConnections interface)

 Microsoft SDK for Java

Skip

This method of the IEnumConnections interface instructs the enumerator to skip the next celt elements in the enumeration so that the next call to Next will not return those elements.

Syntax

public void Skip(int celt);

Parameters

[in] celt The number of elements to skip.


IEnumMoniker Interface (com.ms.com. Package)

 Microsoft SDK for Java

IEnumMoniker Interface

The IEnumMoniker Interface of the com.ms.com package enumerates the components of a moniker or the monikers in a table of monikers.

OLE defines two interfaces that supply an IEnumMoniker interface pointer:

  • The IMoniker.Enum method gets a pointer to an IEnumMoniker implementation that can enumerate forward or backward through the components of the moniker.

  • The IRunningObjectTable.EnumRunning method returns a pointer to an IEnumMoniker implementation that can enumerate the monikers registered in a Running Object Table (ROT).

Note The IEnumMoniker interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IEnumMoniker extends IUnknown
{
  // Methods
  public IEnumMoniker Clone();
  public void Next(int celt, IMoniker[] rgelt, int[] pceltFetched);
  public void Reset();
  public void Skip(int celt);
}

IUnknown
  |
  +--IEnumMoniker


Methods (IEnumMoniker Interface)

 Microsoft SDK for Java

IEnumMoniker Interface Methods

The IEnumMoniker interface has the following methods:

Clone creates another enumerator that contains the same enumeration state as the current one.
Next retrieves a specified number of items in the enumeration sequence.
Skip skips over a specified number of items in the enumeration sequence.
Reset resets the enumeration sequence to the beginning.


Clone (IEnumMoniker Interface)

 Microsoft SDK for Java

Clone

This method of the IEnumMoniker interface creates another enumerator that contains the same enumeration state as the current one. Using this function, a client can record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

Syntax

public IEnumMoniker Clone();

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED.


next (IEnumMoniker Interface)

 Microsoft SDK for Java

Next

This method of the IEnumMoniker interface retrieves the next celt items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through pceltFetched (unless the caller passed in NULL for that parameter).

Syntax

public void Next(int celt, IMoniker[] rgelt, int[] pceltFetched);

Return Values

S_OK if the number of elements supplied is celt; S_FALSE otherwise.

Parameters

[in] celt | The number of elements being requested.
[out] rgelt | The array of size celt (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.
[in, out] pceltFetched | The pointer to the number of elements actually supplied in rgelt. The caller can pass in NULL if celt is one.


Reset (IEnumMoniker Interface)

 Microsoft SDK for Java

Reset

This method of the IEnumMoniker interface resets the enumeration sequence to the beginning.

Syntax

public void Reset();

Return Value

S_OK


Skip (IEnumMoniker Interface)

 Microsoft SDK for Java

Skip

This method of the IEnumMoniker interface skips over the next specified number of elements in the enumeration sequence.

Syntax

public void Skip(int celt);

Return Value

S_OK if the number of elements skipped is celt; otherwise S_FALSE.

Parameters

[in] celt The number of elements to be skipped.


IEnumSTATSTG Interface (com.ms.com. Package)

 Microsoft SDK for Java

IEnumSTATSTG Interface

The IEnumSTATSTG interface of the com.ms.com package enumerates through an array of STATSTG structures, which contain statistical information about an open storage, stream, or byte array object.

Note The IEnumSTATSTG interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IEnumSTATSTG extends IUnknown
{
  // Methods
  public IEnumSTATSTG Clone()
  public void Next(int celt, STATSTG[] rgelt, int[] pceltFetched);
  public void Reset();
  public void Skip(int celt);
;
}

IUnknown
  |
  +--IEnumSTATSTG


Methods (IEnumSTATSTG Interface)

 Microsoft SDK for Java

IEnumSTATSTG Interface Methods

The IEnumSTATSTG interface has the following methods:

Clone creates another enumerator that contains the same enumeration state as the current one.
Next retrieves a specified number of items in the enumeration sequence.
Reset resets the enumeration sequence to the beginning.
Skip skips over a specified number of items in the enumeration sequence.


Clone (IEnumSTATSTG Interface)

 Microsoft SDK for Java

Clone

This method of the IEnumSTATSTG interface creates another enumerator that contains the same enumeration state as the current one. Using this function, a client can record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

Syntax

public IEnumSTATSTG Clone();

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED.


Next (IEnumSTATSTG Interface)

 Microsoft SDK for Java

Next

This method of the IEnumSTATSTG interface retrieves the next celt items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through pceltFetched (unless the caller passed in NULL for that parameter).

Syntax

public void Next(int celt, STATSTG[] rgelt, int[] pceltFetched);

Return Values

S_OK if the number of elements supplied is celt; S_FALSE otherwise.

Parameters

[in] celt | The number of elements being requested.
[out] rgelt | The array of size celt (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.
[in, out] pceltFetched | The pointer to the number of elements actually supplied in rgelt. The caller can pass in NULL if celt is one.


Reset (IEnumSTATSTG Interface)

 Microsoft SDK for Java

Reset

This method of the IEnumSTATSTG interface resets the enumeration sequence to the beginning.

Syntax

public void Reset();

Return Value

S_OK


Skip (IEnumSTATSTG Interface)

 Microsoft SDK for Java

Skip

This method of the IEnumSTATSTG interface skips over the next specified number of elements in the enumeration sequence.

Syntax

public void Skip(int celt);

Return Value

S_OK if the number of elements skipped is celt; otherwise S_FALSE.

Parameters

[in] celt The number of elements to be skipped.


IEnumString Interface (com.ms.com. Package)

 Microsoft SDK for Java

IEnumString Interface

The IEnumString Interface of the com.ms.com package enumerates strings.

Note The IEnumString interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IEnumString extends IUnknown
{
  // Methods
  public IEnumString Clone();
  public void Next(int celt, String[] rgelt, int[] pceltFetched);
  public void Reset();
  public void Skip(int celt);
}

IUnknown
  |
  +--IEnumString


Methods (IEnumString Interface)

 Microsoft SDK for Java

IEnumString Interface Methods

The IEnumString interface has the following methods:

Clone creates another enumerator that contains the same enumeration state as the current one.
Next retrieves a specified number of items in the enumeration sequence.
Reset resets the enumeration sequence to the beginning.
Skip skips over a specified number of items in the enumeration sequence.


Clone (IEnumString Interface)

 Microsoft SDK for Java

Clone

This method of the IEnumString interface creates another enumerator that contains the same enumeration state as the current one. Using this function, a client can record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

Syntax

public IEnumString Clone();

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED.


Next (IEnumString Interface)

 Microsoft SDK for Java

Next

This method of the IEnumString interface retrieves the next celt items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through pceltFetched (unless the caller passed in NULL for that parameter).

Syntax

public void Next(int celt, String[] rgelt, int[] pceltFetched);

Return Values

S_OK if the number of elements supplied is celt; S_FALSE otherwise.

Parameters

[in] celt | The number of elements being requested.
[out] rgelt | The array of size celt (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.
[in, out] pceltFetched | The pointer to the number of elements actually supplied in rgelt. The caller can pass in NULL if celt is one.


Reset (IEnumString Interface)

 Microsoft SDK for Java

Reset

This method of the IEnumString interface resets the enumeration sequence to the beginning.

Syntax

public void Reset();

Return Value

S_OK


Skip (IEnumString Interface)

 Microsoft SDK for Java

Skip

This method of the IEnumString interface skips over the next specified number of elements in the enumeration sequence.

Syntax

public void Skip(int celt);

Return Value

S_OK if the number of elements skipped is celt; otherwise S_FALSE.

Parameters

[in] celt Number of elements to be skipped.


IEnumUnknown Interface (com.ms.com. Package)

 Microsoft SDK for Java

IEnumUnknown Interface

The IEnumUnknown interface of the com.ms.com package enumerates strings.

Note The IEnumUnknown interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IEnumUnknown extends IUnknown
{
  // Methods
  public IEnumString Clone();
  public void Next(int celt, String[] rgelt, int[] pceltFetched);
  public void Reset();
  public void Skip(int celt);
}

IUnknown
  |
  +--IEnumUnknown


Methods (IEnumUnknown Interface)

 Microsoft SDK for Java

IEnumUnknown Interface Methods

The IEnumUnknown interface has the following methods:

Clone creates another enumerator that contains the same enumeration state as the current one.
Next retrieves a specified number of items in the enumeration sequence.
Reset resets the enumeration sequence to the beginning.
Skip skips over a specified number of items in the enumeration sequence.


Clone (IEnumUnknown Interface)

 Microsoft SDK for Java

Clone

This method of the IEnumUnknown interface creates another enumerator that contains the same enumeration state as the current one. Using this function, a client can record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

Syntax

public IEnumString Clone();

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED.


Next (IEnumUnknown Interface)

 Microsoft SDK for Java

Next

This method of the IEnumUnknown interface retrieves the next celt items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through pceltFetched (unless the caller passed in NULL for that parameter).

Syntax

public void Next(int celt, String[] rgelt, int[] pceltFetched);

Return Values

S_OK if the number of elements supplied is celt; S_FALSE otherwise.

Parameters

[in] celt | The number of elements being requested.
[out] rgelt | The array of size celt (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.
[in, out] pceltFetched | The pointer to the number of elements actually supplied in rgelt. The caller can pass in NULL if celt is one.


Reset (IEnumUnknown Interface)

 Microsoft SDK for Java

Reset

This method of the IEnumUnknown interface resets the enumeration sequence to the beginning.

Syntax

public void Reset();

Return Value

S_OK


Skip (IEnumUnknown Interface)

 Microsoft SDK for Java

Skip

This method of the IEnumUnknown interface skips over the next specified number of elements in the enumeration sequence.

Syntax

public void Skip(int celt);

Return Value

S_OK if the number of elements skipped is celt; otherwise S_FALSE.

Parameters

[in] celt The number of elements to be skipped.


IEnumVariant Interface (com.ms.com Package)

 Microsoft SDK for Java

IEnumVariant Interface

The IEnumVariant Interface of the com.ms.com package provides methods for enumerating a collection of variants. You do not need to know the specific type (or types) of elements in the collection. This interface wraps the Component Object Model (COM) interface, IEnumVARIANT.

public interface IEnumVariant extends IUnknown
{
  // Methods
  public IEnumVariant Clone();
  public void Next(int celt, Variant[] rgvar, int[] pceltFetched);
  public void Reset();
  public void Skip(int celt);
}

IUnknown
  |
  +--IEnumVariant


Methods (IEnumVariant Interface)

 Microsoft SDK for Java

IEnumVariant Interface Methods

The IEnumVariant interface contains the following methods:

Clone clones the IEnumVariant object.
Next retrieves elements from the enumeration sequence.
Reset resets the index to the start of the enumeration.
Skip skips elements in the enumeration.


Clone (IEnumVariant Interface)

 Microsoft SDK for Java

Clone

This method of the IEnumVariant Interface clones the IEnumVariant object.

Syntax

public IEnumVariant Clone();

Return Value

Returns an IEnumVariant object identical to the current object.


Next (IEnumVariant Interface)

 Microsoft SDK for Java

Next

This method of the IEnumVariant Interface retrieves elements from the enumeration sequence.

Syntax

public void Next(int celt, Variant[] rgvar, int[] pceltFetched);

Parameters

celt | The number of elements to retrieve.
rgvar | The elements retrieved.
pceltFetched | The number of elements retrieved.


Reset (IEnumVariant Interface)

 Microsoft SDK for Java

Reset

This method of the IEnumVariant Interface resets the index to the start of the enumeration.

Syntax

public void Reset();


Skip (IEnumVariant Interface)

 Microsoft SDK for Java

Skip

This method of the IEnumVariant Interface skips elements in the enumeration.

Syntax

public void Skip(int celt);

Parameters

celt The number of elements to skip.


IErrorInfo Interface (com.ms.com package)

 Microsoft SDK for Java

IErrorInfo Interface

The IErrorInfo Interface of the com.ms.com package provides detailed contextual error information.

public interface IErrorInfo extends IUnknown
{
  // Methods
  public String GetDescription();
  public _Guid GetGUID();
  public int GetHelpContext();
  public String GetHelpFile();
  public String GetSource();
}


Methods (IErrorInfo Interface)

 Microsoft SDK for Java

IErrorInfo Interface Methods

The IErrorInfo interface has the following methods:

GetDescription retrieves a textual description of the error.
GetGUID retrieves the globally unique identifier (GUID) for the interface that defined the error.
GetHelpContext retrieves the Help context identifier (ID) for the error.
GetHelpFile retrieves the path of the Help file that describes the error.
GetSource retrieves the programmatic identifier (ProgID) for the class or application that returned the error.


GetDescription (IErrorInfo Interface)

 Microsoft SDK for Java

GetDescription

This method of the IErrorInfo interface retrieves a textual description of the error.

Syntax

public String GetDescription();

Return Value

Retrieves a string that is the error description.


GetGUID (IErrorInfo Interface)

 Microsoft SDK for Java

GetGUID

This method of the IErrorInfo interface retrieves the globally unique identifier (GUID) for the interface that defined the error.

Syntax

public _Guid GetGUID();

Return Value

Retrieves a GUID.


GetHelpContext (IErrorInfo Interface)

 Microsoft SDK for Java

GetHelpContext

This method of the IErrorInfo interface retrieves the Help context identifier (ID) for the error.

Syntax

public int GetHelpContext();

Return Value

Retrieves an integer that is the Help context ID.


GetHelpFile (IErrorInfo Interface)

 Microsoft SDK for Java

GetHelpFile

This method of the IErrorInfo interface retrieves the path of the Help file that describes the error.

Syntax

public String GetHelpFile();

Return Value

Retrieves a string that is the path of a Help file.


GetSource (IErrorInfo Interface)

 Microsoft SDK for Java

GetSource

This method of the IErrorInfo interface retrieves the programmatic identifier (ProgID) for the class or application that returned the error.

Syntax

public String GetSource();

Return Value

Retrieves a string that is a ProgID.


IExternalConnectionSink Interface (com.ms.com Package)

 Microsoft SDK for Java

IExternalConnectionSink Interface

The IExternalConnectionSink Interface of the com.ms.com package allows Java objects exposed as Component Object Model (COM) objects to be notified of calls to the IExternalConnection interface. The methods in this interface are notifications, not overrides. The virtual machine always processes the IExternalConnection methods first to manage the lifetime of the objects.

public interface IExternalConnectionSink
{
  // Methods
  public void OnAddConnection(int exconn, int reserved, int refcount);
  public void OnReleaseConnection(int exconn, int reserved,
    boolean fLastReleaseCloses, int refcount);
}


Methods (IExternalConnectionSink Interface)

 Microsoft SDK for Java

IExternalConnectionSink Interface Methods

The IExternalConnectionSink interface contains the following methods:

OnAddConnection notifies the object that a connection has been added.
OnReleaseConnection notifies the object that a connection has been released.


OnAddConnection (IExternalConnectionSink Interface)

 Microsoft SDK for Java

OnAddConnection

This method of the IExternalConnectionSink Interface notifies the object that a connection has been added. Both exconn and reserved correspond to the similarly named parameters of the IExternalConnection::AddConnection method.

Syntax

public void OnAddConnection(int exconn, int reserved, int refcount);

Caution The value of refcount is advisory only; it is guaranteed to be zero if and only if the last external lock on the object has been released. However, refcount can be printed out for diagnostic purposes.

Parameters

exconn | The type of external connection.
reserved | Used by Microsoft® ActiveX® to pass connection information.
refcount | The new reference count of the COM proxy.


OnReleaseConnection (IExternalConnectionSink Interface)

 Microsoft SDK for Java

OnReleaseConnection

This method of the IExternalConnectionSink Interface notifies the object that a connection has been released. Both exconn and reserved correspond to the similarly named parameters of the IExternalConnection::AddConnection method.

Syntax

public void OnReleaseConnection(int exconn, int reserved, boolean fLastReleaseCloses, int refcount);

Caution The value of refcount is advisory only; it is guaranteed to be zero if and only if the last external lock on the object has been released. However, refcount can be printed out for diagnostic purposes.

Parameters

exconn | The type of external connection.
reserved | Used by ActiveX to pass connection information.
refcount | The new reference count of the COM proxy.
fLastReleaseCloses | If set to true and if refcount is zero, the close action for the object is initiated.


ILicenseMgr Interface (com.ms.com Package)

 Microsoft SDK for Java

ILicenseMgr Interface

The ILicenseMgr Interface of the com.ms.com package supports the use of licensed Component Object Model (COM) components or controls in a Java application.

public interface ILicenseMgr extends IUnknown
{
  // Methods
  public IUnknown createFromPackage(int index, IUnknown punkOuter,
        int ctxFlags);
  public IUnknown createInstance(String clsid, IUnknown punkOuter,
        int ctxFlags);
  public IUnknown createWithLic(String lic, String clsid,
        IUnknown punkOuter, int ctxFlags);
  public void setPackage(String url);
}

A licensed control cannot be instantiated except by legal users. Using a design-time license, however, enables you to embed the control in your applications. When you distribute the application, a run-time license allows the control to be instantiated when the application is run.

An HTML page containing licensed controls must include an associated license package (.lpk) file, which stores the run-time control licenses. Use the License Package Authoring Tool (lpk_tool.exe) included with the Microsoft® ActiveX® SDK to create a .lpk file. For further information on the ActiveX licensing scheme, refer to the ActiveX SDK.

To use the ILicenseMgr class with a licensed control, call the createWithLic method and specify the license string explicitly to create an instance of the control.

An example of a licensed component is the _DBEngine component in Data Access Objects (DAO). You must use the ILicenseMgr class when you use DAO.

Note For compatibility with the Microsoft SDK for Java 1.0, the following methods instantiate all COM objects on the main apartment thread of the process. Because of the significant thread-switching overhead, these methods should not be used unless the object requires licensing information.

Hierarchy

IUnknown
  |
  +--ILicenseMgr


Methods (ILicenseMgr Interface)

 Microsoft SDK for Java

ILicenseMgr Interface Methods

The ILicenseMgr Interface contains the following methods:

createFromPackage creates a package.
createInstance creates an instance of the specified COM class.
createWithLic creates a new instance of a licensed COM class.
setPackage sets the package specified by the URL.


createFromPackage (ILicenseMgr Interface)

 Microsoft SDK for Java

createFromPackage

This method of the ILicenseMgr Interface creates a package.

Syntax

public IUnknown createFromPackage(int index, IUnknown punkOuter, int ctxFlags);

Return Value

Returns the new package.

Parameters

index | The index of the package.
punkOuter | The aggregating object if the object is created as part of an aggregate; otherwise, null.
ctxFlags | The ComContext value that represents the context that the new object is created in.


createInstance (ILicenseMgr Interface)

 Microsoft SDK for Java

createInstance

This method of the ILicenseMgr Interface creates an instance of the specified COM class.

Syntax

public IUnknown createInstance(String clsid, IUnknown punkOuter, int ctxFlags);

Warning In general, this method should not be called. The best way to create an instance of a COM class is to use the new operator on the Java wrapper generated by the jactivex tool.

Return Value

Returns an instance of the specified COM class.

Parameters

clsid | The class identifier (CLSID) of the instantiated COM class.
punkOuter | The aggregating object if the object is being created as part of an aggregate; otherwise, null.
ctxFlags | The ComContext value that represents the context that the new object is created in.

Exceptions

com.ms.com.ComFailException if there is an error instantiating the class.


createWithLic (ILicenseMgr Interface)

 Microsoft SDK for Java

createWithLic

This method of the ILicenseMgr Interface creates a new instance of a licensed COM class.

Syntax

public IUnknown createWithLic(String lic, String clsid, IUnknown punkOuter, int ctxFlags);

Return Value

Returns a new instance of the specified licensed COM class.

Parameters

lic | The license for the COM class that is instantiated.
clsid | The class identifier (CLSID) of the instantiated COM class.
punkOuter | The aggregating object if the object is being created as part of an aggregate; otherwise, null.
ctxFlags | The value that represents the context that the new object is created in.

Remarks

You can create an instance of the _DBEngine licensed component without having to specify the license or the class identifier (CLSID). The following example shows a helper class with a single method called create that wraps a call to createWithLic:

Example

import dao3032.*;
import com.ms.com.*;
public class dao_dbengine

{
  static public _DBEngine create()
  {
  _DBEngine result;
  ILicenseMgr mgr = new LicenseMgr();
  result = (_DBEngine) mgr.createWithLic(
  "mjgcqcejfchcijecpdhckcdjqigdejfccjri",   // BSTR lic
  "{00025E15-0000-0000-C000-000000000046}", // BSTR clsid,
     null,ComContext.INPROC_SERVER); // IUnknown* punkOuter,
                                     // ComContext ctxFlags
    return result;
    }
}

Exceptions

com.ms.com.ComFailException if there is an error instantiating the class.


setPackage (ILicenseMgr Interface)

 Microsoft SDK for Java

setPackage

This method of the ILicenseMgr Interface sets the package specified by the URL.

Syntax

public void setPackage(String url);

Parameters

url The Uniform Resource Locator (URL) of the package.


ILockBytes Interface (com.ms.com Package)

 Microsoft SDK for Java

ILockBytes Interface

The ILockBytes interface of the com.ms.com package is implemented on a byte array object that is backed by some physical storage, such as a disk file, global memory, or a database. It is used by a COM compound file storage object to give its root storage access to the physical device, while isolating the root storage from the details of accessing the physical storage.

Most applications will not implement the ILockBytes interface because COM provides file-based and memory-based implementations of ILockBytes. If you choose to implement your own ILockBytes interface, you should consider providing custom marshaling by implementing the IMarshal interface as part of your byte array object. The reason for this is that when the COM-provided implementations of IStorage and IStream are marshaled to another process, their ILockBytes interface pointers are also marshaled to the other process. The default marshaling mechanism creates a proxy byte array object (which includes the ILockBytes interface) that transmits method calls back to the original byte array object. Custom marshaling can improve efficiency by creating a remote byte array object that can directly access the byte array.

Note The ILockBytes interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface ILockBytes extends IUnknown
{
  // Methods
  public int ReadAt(long ulOffset, byte buf[], int off, int len);
  public int WriteAt(long ulOffset, byte buf[], int off, int len);
  public void Flush();
  public void SetSize(long cb);
  public void LockRegion(long libOffset, long cb, int dwLockType);
  public void UnlockRegion(long libOffset, long cb, int dwLockType);
  public void Stat(com.ms.com.STATSTG pstatstg, int grfStatFlag);
}

IUnknown
  |
  +--ILockBytes


Methods (ILockBytes Interface)

 Microsoft SDK for Java

ILockBytes Interface Methods

The ILockBytes interface contains the following methods:

ReadAt reads a specified number of bytes starting at a specified offset from the beginning of the byte array.
WriteAt writes a specified number of bytes to a specified location in the byte array.
Flush ensures that any internal buffers maintained by the byte array object are written out to the backing storage.
SetSize changes the size of the byte array.
LockRegion restricts access to a specified range of bytes in the byte array.
UnlockRegion removes the access restriction on a range of bytes previously restricted with ILockBytes.LockRegion.
Stat retrieves a com.ms.com.STATSTG structure for this byte array object.


Flush (ILockBytes Interface)

 Microsoft SDK for Java

Flush

This method of the ILockBytes interface ensures that any internal buffers maintained by the ILockBytes implementation are written out to the underlying physical storage.

Syntax

public void Flush();

Return Values

S_OK -- the flush operation was successful.

STG_E_ACCESSDENIED -- the caller does not have permission to access the byte array.

STG_E_MEDIUMFULL -- the flush operation is not completed because there is no space left on the storage device.

E_FAIL -- general failure writing data.

STG_E_TOOMANYFILESOPEN -- under certain circumstances, Flush does a dump-and-close to flush, which can lead to a return value of STG_E_TOOMANYFILESOPEN if no file handles are available.

STG_E_INVALIDHANDLE -- an underlying file has been prematurely closed, or the correct floppy disk has been replaced by an invalid one.


LockRegion (ILockBytes Interface)

 Microsoft SDK for Java

LockRegion

This method of the ILockBytes interface restricts access to a specified range of bytes in the byte array.

Syntax

public void LockRegion(long libOffset, long cb, int dwLockType);

Return Values

S_OK -- the specified range of bytes was locked.

STG_E_INVALIDFUNCTION -- locking is not supported at all or the specific type of lock requested is not supported.

STG_E_ACCESSDENIED -- access denied because the caller has insufficient permission, or another caller has the file open and locked.

STG_E_LOCKVIOLATION -- access denied because another caller has the file open and locked.

STG_E_INVALIDHANDLE -- an underlying file has been prematurely closed, or the correct disk has been replaced by an invalid one.

Parameters

[in] libOffset | Specifies the byte offset for the beginning of the range.
[in] cb | Specifies, in bytes, the length of the range to be restricted.
[in] dwLockType | Specifies the type of restrictions being requested on accessing the range.


ReadAt

This method of the ILockBytes interface reads a specified number of bytes starting at a specified offset from the beginning of the byte array object.

Syntax

public int ReadAt(long ulOffset, byte buf[], int off, int len);

Return Values

S_OK -- indicates that the specified number of bytes were read, or the maximum number of bytes were read up to the end of the byte array.

E_FAIL -- data could not be read from the byte array.

E_PENDING -- asynchronous storage only: part or all the data to be read is currently unavailable.

STG_E_ACCESSDENIED -- the caller does not have permission to access the byte array.

STG_E_READFAULT -- the number of bytes to be read does not equal the number of bytes that were actually read.

Parameters

ulOffset | Specifies the starting row from the beginning of the database.
buf | The buffer that the bytes are read into.
off | The offset in the byte array to begin reading from.
len | The number of bytes to read.


SetSize (ILockBytes Interface)

 Microsoft SDK for Java

SetSize

This method of the ILockBytes interface changes the size of the byte array.

Syntax

public void SetSize(long cb);

Return Values

S_OK -- the size of the byte array was successfully changed.

STG_E_ACCESSDENIED -- the caller does not have permission to access the byte array.

STG_E_MEDIUMFULL -- the byte array size is not changed because there is no space left on the storage device.

Parameters

[in] cb
Specifies the new size of the byte array as a number of bytes.


Stat (ILockBytes Interface)

 Microsoft SDK for Java

Stat

This method of the ILockBytes interface retrieves a STATSTG structure containing information for this byte array object.

Syntax

public void Stat(com.ms.com.STATSTG pstatstg, int grfStatFlag);

Return Values

S_OK -- the STATSTG structure was successfully returned at the specified location.

E_OUTOFMEMORY -- the STATSTG structure was not returned due to a lack of memory for the name field in the structure.

STG_E_ACCESSDENIED -- the STATSTG structure was not returned because the caller did not have access to the byte array.

STG_E_INSUFFICIENTMEMORY -- the STATSTG structure was not returned due to a lack of memory.

STG_E_INVALIDFLAG -- the value for the grfStateFlag parameter is not valid.

STG_E_INVALIDPOINTER -- the value for the pStatStg parameter is not valid.

Parameters

[out] pstatstg | Points to a STATSTG structure in which this method places information about this byte array object. The pointer is NULL if an error occurs.
[in] grfStatFlag | Specifies whether this method should supply the pwcsName member of the STATSTG structure through values taken from the STATFLAG enumeration. If the STATFLAG_NONAME is specified, the pwcsName member of STATSTG is not supplied, thus saving a memory allocation operation. The other possible value, STATFLAG_DEFAULT, indicates that all STATSTG members be supplied.


UnlockRegion (ILockBytes Interface)

 Microsoft SDK for Java

UnlockRegion

This method of the ILockBytes interface removes the access restriction on a previously locked range of bytes.

Syntax

public void UnlockRegion(long libOffset, long cb, int dwLockType);

Return Values

S_OK -- the byte range was unlocked.

STG_E_INVALIDFUNCTION -- locking is not supported at all or the specific type of lock requested is not supported.

STG_E_LOCKVIOLATION -- the requested unlock cannot be granted.

Parameters

[in] libOffset | Specifies the byte offset for the beginning of the range.
[in] cb | Specifies, in bytes, the length of the range that is restricted.
[in] dwLockType | Specifies the type of access restrictions previously placed on the range.


WriteAt (ILockBytes Interface)

 Microsoft SDK for Java

WriteAt

This method of the ILockBytes interface writes the specified number of bytes starting at a specified offset from the beginning of the byte array.

Syntax

public int WriteAt(long ulOffset, byte buf[], int off, int len);

Return Values

S_OK -- indicates that the specified number of bytes were written.

E_FAIL -- a general failure occurred during the write.

E_PENDING -- asynchronous storage only: part or all of the data to be written is currently unavailable.

STG_E_ACCESSDENIED -- the caller does not have sufficient permissions for writing this byte array.

STG_E_WRITEFAULT -- the number of bytes to be written does not equal the number of bytes that were actually written.

STG_E_MEDIUMFULL -- the write operation was not completed because there is no space left on the storage device. The actual number of bytes written is still returned.

Parameters

ulOffset | Specifies the starting row from the beginning of the database.
buf | The buffer that the bytes are written into.
off | The offset in the byte array to begin writing to.
len | The number of bytes to be written.


IMarshal Interface (com.ms.com Package)

 Microsoft SDK for Java

IMarshal Interface

The IMarshal interface of the com.ms.com package enables a COM object to define and manage the marshaling of its interface pointers. The alternative is to use COM's default implementation, which is the preferred choice in all but a few special cases.

Note The IMarshal interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IMarshal extends IUnknown
{
  // Methods
  public _Guid GetUnmarshalClass(_Guid riid, IUnknown pv,
    int dwDestContext, int pvDestContext, int mshlflags);
  public int GetMarshalSizeMax(_Guid riid, IUnknown pv,
    int dwDestContext, int pvDestContext, int mshlflags);
  public void MarshalInterface(IStream pStm, _Guid riid, IUnknown pv,
    int dwDestContext, int pvDestContext, int mshlflags);
  public IUnknown UnmarshalInterface(IStream pStm, _Guid riid);
  public void ReleaseMarshalData(IStream pStm);
  public void DisconnectObject(int dwReserved);
}

IUnknown
  |
  +--IMarshal


Methods (IMarshal Interface)

 Microsoft SDK for Java

IMarshal Interface Methods

The IMarshal interface contains the following methods:

GetUnmarshalClass returns the CLSID of unmarshaling code.
GetMarshalSizeMax returns size of the buffer needed during marshaling.
MarshalInterface marshals an interface pointer.
UnmarshalInterface unmarshals an interface pointer.
ReleaseMarshalData destroys a marshaled data packet.
DisconnectObject severs all connections.


DisconnectObject (IMarshal Interface)

 Microsoft SDK for Java

DisconnectObject

This method of the IMarshal interface forcibly releases all external connections to an object. The object's server calls the object's implementation of this method prior to shutting down.

Syntax

public void DisconnectObject(int dwReserved);

Parameters

[in] dwReserved Reserved for future use; must be 0 (zero). To ensure compatibility with future use, DisconnectObject must not check for 0 (zero).


GetMarshalSizeMax (IMarshal Interface)

 Microsoft SDK for Java

GetMarshalSizeMax

This method of the IMarshal interface returns an upper bound on the number of bytes needed to marshal the specified interface pointer on the specified object.

Syntax

public int GetMarshalSizeMax(_Guid riid, IUnknown pv, int dwDestContext, int pvDestContext, int mshlflags);

Parameters

[in] riid | The reference to the identifier of the interface to be marshaled.
[in] pv | The pointer to the interface to be marshaled; can be NULL if the caller does not have a pointer to the desired interface.
[in] dwDestContext | The destination context where the specified interface is to be unmarshaled. Values for dwDestContext come from the enumeration MSHCTX. Currently, unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).
[in] pvDestContext | Reserved for future use; must be NULL.
[in] mshlflags | Specifies whether the data to be marshaled is to be transmitted back to the client process (the normal case) or written to a global table, where it can be retrieved by multiple clients. Valid values come from the MSHLFLAGS enumeration.


GetUnmarshalClass (IMarshal Interface)

 Microsoft SDK for Java

GetUnmarshalClass

This method of the IMarshal interface returns the CLSID that COM uses to locate the DLL containing the code for the corresponding proxy. COM loads this DLL to create an uninitialized instance of the proxy.

Syntax

public _Guid GetUnmarshalClass(_Guid riid, IUnknown pv, int dwDestContext, int pvDestContext, int mshlflags);

Return Values

Returns S_OK if successful; otherwise, S_FALSE.

Parameters

[in] riid | The reference to the identifier of the interface to be marshaled.
[in] pv | The pointer to the interface to be marshaled; can be NULL if the caller does not have a pointer to the desired interface.
[in] dwDestContext | The destination context where the specified interface is to be unmarshaled. Values for dwDestContext come from the enumeration MSHCTX. Currently, unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).
[in] pvDestContext | Reserved for future use; must be NULL.
[in] mshlflags | Specifies whether the data to be marshaled is to be transmitted back to the client process (the normal case) or written to a global table, where it can be retrieved by multiple clients. Valid values come from the MSHLFLAGS enumeration.


MarshalInterface (IMarshal Interface)

 Microsoft SDK for Java

MarshalInterface

This method of the IMarshal interface writes into a stream the data required to initialize a proxy object in some client process.

Syntax

public void MarshalInterface(IStream pStm, _Guid riid, IUnknown pv, int dwDestContext, int pvDestContext, int mshlflags);

Parameters

[in] pStm | The pointer to the stream to be used during marshaling.
[in] riid | The reference to the identifier of the interface to be marshaled. This interface must be derived from the IUnknown interface.
[in] pv | The pointer to the interface to be marshaled; can be NULL if the caller does not have a pointer to the desired interface.
[in] dwDestContext | The destination context where the specified interface is to be unmarshaled. Values for dwDestContext come from the enumeration MSHCTX. Currently, unmarshaling can occur either in another apartment of the current process (MSHCTX_INPROC) or in another process on the same computer as the current process (MSHCTX_LOCAL).
[in] pvDestContext | Reserved for future use; must be NULL.
[in] mshlflags | Specifies whether the data to be marshaled is to be transmitted back to the client process (the normal case) or written to a global table, where it can be retrieved by multiple clients. Valid values come from the MSHLFLAGS enumeration.


ReleaseMarshalData (IMarshal Interface)

 Microsoft SDK for Java

ReleaseMarshalData

This method of the IMarshal interface destroys a marshaled data packet.

Syntax

public void ReleaseMarshalData(IStream pStm);

Parameters

[in] pStm The pointer to the stream to be used during marshaling.


UnmarshalInterface (IMarshal Interface)

 Microsoft SDK for Java

UnmarshalInterface

This method of the IMarshal interface initializes a newly created proxy and returns an interface pointer to that proxy.

Syntax

public IUnknown UnmarshalInterface(IStream pStm, _Guid riid);

Parameters

[in] pStm | The pointer to the stream to be used during marshaling.
[in] riid | Reference to the identifier of the interface to be marshaled. This interface must be derived from the IUnknown interface.


IMoniker Interface (com.ms.com Package)

 Microsoft SDK for Java

IMoniker Interface

The IMoniker interface of the com.ms.com package contains methods that allow you to use a moniker object, which contains information that uniquely identifies a COM object. An object that has a pointer to the moniker object's IMoniker interface can locate, activate, and get access to the identified object without having any other specific information on where the object is actually located in a distributed system.

Like a path to a file in a file system, a moniker contains information that allows a COM object to be located and activated. Monikers can identify any type of COM object, from a document object stored in a file to a selection within an embedded object. COM provides a set of moniker classes that allow you to create moniker objects identifying the objects most commonly found in the system. For example, there might be an object representing a range of cells in a spreadsheet, which is itself embedded in a text document stored in a file. In a distributed system, this object's moniker would identify the location of the object's system, the file's physical location on that system, the storage of the embedded object within that file, and, finally, the location of the range of cells within the embedded object.

A moniker object supports the IMoniker interface, which is derived from the IPersistStream interface, and uniquely identifies a single object in the system. Once an object providing a moniker has created the moniker object, this information cannot be changed within that object. If the moniker provider changes the information, it can only do so by creating a new moniker object, which would then uniquely identify the object in question.

Monikers have two important capabilities:

  • Monikers can be saved to a persistent storage. When a moniker is loaded back into memory, it still identifies the same object.

  • Monikers support an operation called "binding," which is the process of locating the object named by the moniker, activating it (loading it into memory) if it is not already active, and returning a pointer to a requested interface on that object.

Monikers are used as the basis for linking in COM. A linked object contains a moniker that identifies its source. When the user activates the linked object to edit it, the moniker is bound; this loads the link source into memory.

Note The IMoniker interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IMoniker extends com.ms.com.IPersistStream
{
  // Methods
  public IUnknown BindToObject(IBindCtx pbc, IMoniker pmkToLeft,
    _Guid riidResult);
  public IUnknown BindToStorage(IBindCtx pbc, IMoniker pmkToLeft,
    _Guid riid);
  public IMoniker Reduce(IBindCtx pbc, int dwReduceHowFar,
    IMoniker[] ppmkToLeft);
  public IMoniker ComposeWith(IMoniker pmkRight,
    boolean fOnlyIfNotGeneric);
  public IEnumMoniker Enum(boolean fForward);
  public boolean IsEqual(IMoniker pmkOtherMoniker);
  public int Hash();
  public boolean IsRunning(IBindCtx pbc, IMoniker pmkToLeft,
    IMoniker pmkNewlyRunning);
  public long GetTimeOfLastChange(IBindCtx pbc, IMoniker pmkToLeft);
  public IMoniker Inverse();
  public void CommonPrefixWith(IMoniker pmkOther, IMoniker[] ppmkPrefix);
  public void RelativePathTo(IMoniker pmkOther, IMoniker[] ppmkRelPath);
  public String GetDisplayName(IBindCtx pbc, IMoniker pmkToLeft);
  public IMoniker ParseDisplayName(IBindCtx pbc, IMoniker pmkToLeft,
    String pszDisplayName, int[] pchEaten);
  public boolean IsSystemMoniker(int[] pdwMksys);
}

IUnknown
  |
  +--IPersistStream
  |  |
  |  +--IMoniker


Methods (IMoniker Interface)

 Microsoft SDK for Java

IMoniker Interface Methods

The IMoniker interface has the following methods:

BindToObject binds to the object named by the moniker.
BindToStorage binds to the object's storage.
Reduce reduces the moniker to simplest form.
ComposeWith composes with another moniker.
Enum enumerates component monikers.
IsEqual compares with another moniker.
Hash returns a hash value.
IsRunning checks whether object is running.
GetTimeOfLastChange returns time the object was last changed.
Inverse returns the inverse of the moniker.
CommonPrefixWith finds the prefix that the moniker has in common with another moniker.
RelativePathTo constructs a relative moniker between the moniker and another.
GetDisplayName returns the display name.
ParseDisplayName converts a display name into a moniker.
IsSystemMoniker checks whether moniker is one of the system-supplied types.


BindToObject (IMoniker Interface)

 Microsoft SDK for Java

BindToObject

This method of the IMoniker interface uses the moniker to bind to the object it identifies. The binding process involves finding the object, putting it into the running state if necessary, and supplying the caller with a pointer to a specified interface on the identified object.

Syntax

public IUnknown BindToObject(IBindCtx pbc, IMoniker pmkToLeft, _Guid riidResult);

Return Values

The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the following:

S_OK -- The binding operation was successful.

MK_E_NOOBJECT -- The object identified by this moniker, or some object identified by the composite moniker of which this moniker is a part, could not be found.

MK_E_EXCEEDEDDEADLINE -- The binding operation could not be completed within the time limit specified by the bind context's BIND_OPTS structure.

MK_E_CONNECTMANUALLY -- The binding operation requires assistance from the end user. The most common reasons for returning this value are that a password is needed or that a floppy needs to be mounted. When this value is returned, retrieve the moniker that caused the error with a call to IBindCtx.GetObjectParam with the key "ConnectManually". You can then call IMoniker.GetDisplayName to get the display name, display a dialog box that communicates the desired information, such as instructions to mount a floppy or a request for a password, and then retry the binding operation.

MK_E_INTERMEDIATEINTERFACENOTSUPPORTED -- An intermediate object was found but it did not support an interface required to complete the binding operation. For example, an item moniker returns this value if its container does not support the IOleItemContainer interface.

STG_E_ACCESSDENIED -- Unable to access the storage object.

Parameters

[in] pbc | Pointer to the IBindCtx interface on the bind context object, which is used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.
[in] pmkToLeft | If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.
[in] riidResult | IID of the interface the client wishes to use to communicate with the object that the moniker identifies.


BindToStorage (IMoniker Interface)

 Microsoft SDK for Java

BindToStorage

This method of the IMoniker interface retrieves an interface pointer to the storage that contains the object identified by the moniker. Unlike the IMoniker.BindToObject method, this method does not activate the object identified by the moniker.

Syntax

public IUnknown BindToStorage(IBindCtx pbc, IMoniker pmkToLeft, _Guid riid);

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK -- The binding operation was successful.

MK_E_NOSTORAGE -- The object identified by this moniker does not have its own storage.

MK_E_EXCEEDEDDEADLINE -- The operation could not be completed within the time limit specified by the bind context's BIND_OPTS structure.

MK_E_CONNECTMANUALLY -- The operation was unable to connect to the storage, possibly because a network device could not be connected to.

MK_E_INTERMEDIATEINTERFACENOTSUPPORTED -- An intermediate object was found but it did not support an interface required for an operation.

STG_E_ACCESSDENIED -- Unable to access the storage object.

Parameters

[in] pbc | Pointer to the IBindCtx interface on the bind context object to be used during this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.
[in] pmkToLeft | If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.
[in] riid | Reference to the identifier of the storage interface requested.


ComposeWith (IMoniker Interface)

 Microsoft SDK for Java

ComposeWith

This method of the IMoniker interface combines the current moniker with another moniker, creating a new composite moniker.

Syntax

public IMoniker ComposeWith(IMoniker pmkRight, boolean fOnlyIfNotGeneric);

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK -- The monikers were successfully combined.

MK_E_NEEDGENERIC -- Indicates that fOnlyIfNotGeneric was TRUE, but the monikers could not be composed together without creating a generic composite moniker.

Parameters

[in] pmkRight | Pointer to the IMoniker interface on the moniker to compose onto the end of this moniker.
[in] fOnlyIfNotGeneric | If TRUE, the caller requires a non-generic composition, so the operation should proceed only if pmkRight is a moniker class that this moniker can compose with in some way other than forming a generic composite. If FALSE, the method can create a generic composite if necessary.


CommonPrefixWith (IMoniker Interface)

 Microsoft SDK for Java

CommonPrefixWith

This method of the IMoniker interface creates a new moniker based on the common prefix that this moniker (the one comprising the data of this moniker object) shares with another moniker.

Syntax

public IMoniker CommonPrefixWith(IMoniker pmkRight, boolean fOnlyIfNotGeneric);

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK -- A common prefix exists.

MK_S_NOPREFIX -- No common prefix exists.

MK_S_US -- The two monikers are identical.

MK_E_NOTBINDABLE -- This method was called on a relative moniker. It is not meaningful to take the common prefix on a relative moniker.

Parameters

pmkRight | Pointer to the IMoniker interface on the moniker to compose onto the end of this moniker.
fOnlyIfNotGeneric | If TRUE, the caller requires a non-generic prefix, so the operation should proceed only if pmkRight is a moniker class that this moniker can work with in some way other than forming a generic prefix. If FALSE, the method can create a generic prefix if necessary.

Note ppmkPrefix is not returned, because this method can return many successful HRESULTs. This requires a throw in Java, which disallows return values.


Enum (IMoniker Interface)

 Microsoft SDK for Java

Enum

This method of the IMoniker interface supplies a pointer to an enumerator that can enumerate the components of a composite moniker.

Syntax

public IEnumMoniker Enum(boolean fForward);

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK -- Indicates success.

Parameters

[in] fForward If TRUE, enumerates the monikers from left to right. If FALSE, enumerates from right to left.


GetDisplayName (IMoniker Interface)

 Microsoft SDK for Java

GetDisplayName

This method of the IMoniker interface gets the display name, which is a user-readable representation of this moniker.

Syntax

public String GetDisplayName(IBindCtx pbc, IMoniker pmkToLeft);

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK -- The display name was successfully supplied.

MK_E_EXCEEDEDDEADLINE -- The binding operation could not be completed within the time limit specified by the bind context's BIND_OPTS structure.

E_NOTIMPL -- There is no display name.

Parameters

[in] pbc | Pointer to the IBindCtx interface on the bind context to be used in this operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.
[in] pmkToLeft | If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.


GetTimeOfLastChange (IMoniker Interface)

 Microsoft SDK for Java

GetTimeOfLastChange

This method of the IMoniker interface provides a number representing the time the object identified by this moniker was last changed. To be precise, the time returned is the earliest time COM can identify after which no change has occurred, so this time may be later than the time of the last change to the object.

Syntax

public long GetTimeOfLastChange(IBindCtx pbc, IMoniker pmkToLeft);

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK -- The method successfully returned a time.

MK_E_EXCEEDEDDEADLINE -- The binding operation could not be completed within the time limit specified by the bind context's BIND_OPTS structure.

MK_E_CONNECTMANUALLY -- The operation was unable to connect to the storage for this object, possibly because a network device could not be connected to.

MK_E_UNAVAILABLE -- The time of the change is unavailable, and will not be available no matter what deadline is used.

Parameters

[in] pbc | Pointer to the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.
[in] pmkToLeft | If the moniker is part of a composite moniker, pointer to the moniker to the left of this moniker. This parameter is primarily used by moniker Implementers to enable cooperation between the various components of a composite moniker. Moniker clients should pass NULL.


Hash (IMoniker Interface)

 Microsoft SDK for Java

Hash

This method of the IMoniker interface calculates a 32-bit integer using the internal state of the moniker.

Syntax

public int Hash();

Return Value

S_OK -- Successfully received a 32-bit integer hash value.


Inverse (IMoniker Interface)

 Microsoft SDK for Java

Inverse

This method of the IMoniker interface provides a moniker that, when composed to the right of this moniker or one of similar structure, will destroy it (the moniker will compose to nothing).

Syntax

public IMoniker Inverse();

Return Values

The method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK -- The inverse moniker has been returned successfully.

MK_E_NOINVERSE -- The moniker class does not have an inverse.


IsEqual (IMoniker Interface)

 Microsoft SDK for Java

IsEqual

This method of the IMoniker interface compares this moniker with a specified moniker and indicates whether they are identical.

Syntax

public boolean IsEqual(IMoniker pmkOtherMoniker);

Return Values

S_OK -- The two monikers are identical.

S_FALSE -- The two monikers are not identical.

Parameters

[in] pmkOtherMoniker Pointer to the IMoniker interface on the moniker to be used for comparison with this one (the one from which this method is called).


IsRunning (IMoniker Interface)

 Microsoft SDK for Java

IsRunning

This method of the IMoniker interface determines whether the object identified by this moniker is currently loaded and running.

Syntax

public boolean IsRunning(IBindCtx pbc, IMoniker pmkToLeft, IMoniker pmkNewlyRunning);

Return Values

The method supports the standard return value E_UNEXPECTED, as well as the following:

S_OK -- The moniker is running.

S_FALSE -- The moniker is not running.

Parameters

[in] pbc | Pointer to the IBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.
[in] pmkToLeft | Pointer to the IMoniker interface on the moniker to the left of this moniker if this moniker is part of a composite. This parameter is primarily used by moniker Implementers to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL.
[in] pmkNewlyRunning | Pointer to the IMoniker interface on the moniker most recently added to the Running Object Table (ROT). This can be NULL. If non-NULL, the implementation can return the results of calling IMoniker.IsEqual on the pmkNewlyRunning parameter, passing the current moniker. This parameter is intended to enable IMoniker.IsRunning implementations that are more efficient than just searching the ROT, but the implementation can choose to ignore pmkNewlyRunning without causing any harm.


IsSystemMoniker (IMoniker Interface)

 Microsoft SDK for Java

IsSystemMoniker

This method of the IMoniker interface indicates whether this moniker is of one of the system-supplied moniker classes.

Syntax

public boolean IsSystemMoniker(int[] pdwMksys);

Return Values

S_OK -- The moniker is a system moniker.

S_FALSE -- The moniker is not a system moniker.

Parameters

[out] pdwMksys Pointer to an integer that is one of the values from the MKSYS enumeration, and refers to one of the COM moniker classes. This parameter cannot be NULL.


ParseDisplayName (IMoniker Interface)

 Microsoft SDK for Java

ParseDisplayName

This method of the IMoniker interface reads as many characters of the specified display name as it understands and builds a moniker corresponding to the portion read. This procedure is known as "parsing" the display name.

Syntax

public IMoniker ParseDisplayName(IBindCtx pbc, IMoniker pmkToLeft, String pszDisplayName, int[] pchEaten);

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK -- The parsing operation was completed successfully.

MK_E_SYNTAX -- An error in the syntax of the input components (pmkToLeft, this moniker, and pszDisplayName). For example, a file moniker returns this error if pmkToLeft is non-NULL, and an item moniker returns it if pmkToLeft is NULL.

IMoniker.BindToObject errors -- Parsing display names may cause binding. Thus, any error associated with this function may be returned.

Parameters

[in] pbc | Pointer to the IBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.
[in] pmkToLeft | Pointer to the IMoniker interface on the moniker that has been built out of the display name up to this point.
[in] pszDisplayName | Pointer to a zero-terminated string containing the remaining display name to be parsed. For Win32 applications, the LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.
[out] pchEaten | Pointer to the number of characters in pszDisplayName that were consumed in this step.


Reduce (IMoniker Interface)

 Microsoft SDK for Java

Reduce

This method of the IMoniker interface returns a reduced moniker; that is, another moniker that refers to the same object as this moniker but can be bound with equal or greater efficiency.

Syntax

public IMoniker Reduce(IBindCtx pbc, int dwReduceHowFar, IMoniker[] ppmkToLeft);

Return Values

The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the following:

S_OK -- This moniker was reduced.

MK_S_REDUCED_TO_SELF -- This moniker could not be reduced any further, so ppmkReduced indicates this moniker.

MK_E_EXCEEDEDDEADLINE -- The operation could not be completed within the time limit specified by the bind context's BIND_OPTS structure.

Parameters

[in] pbc | Pointer to the IBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.
[in] dwReduceHowFar | DWORD that specifies how far this moniker should be reduced.
[in, out] ppmkToLeft | On entry, address of IMoniker* pointer variable that contains the interface pointer to moniker to the left of this moniker. This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL. On return, *ppmkToLeft is usually set to NULL, indicating no change in the original moniker to the left. In rare situations, *ppmkToLeft indicates a moniker, indicating that the previous moniker to the left should be disregarded and the moniker returned through *ppmkToLeft is the replacement.


RelativePathTo (IMoniker Interface)

 Microsoft SDK for Java

RelativePathTo

This method of the IMoniker interface supplies a moniker that, when composed onto the end of this moniker (or one with a similar structure), yields the specified moniker.

Syntax

public void RelativePathTo(IMoniker pmkOther, IMoniker[] ppmkRelPath);

Return Values

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK -- A meaningful relative path has been returned.

MK_S_HIM -- No common prefix is shared by the two monikers and the moniker returned in ppmkRelPath is pmkOther.

MK_E_NOTBINDABLE -- This moniker is a relative moniker, such as an item moniker. This moniker must be composed with the moniker of its container before a relative path can be determined.

Parameters

[in] pmkOther | Pointer to the IMoniker interface on the moniker to which a relative path should be taken.
[out] ppmkRelPath | Address of IMoniker* pointer variable that receives the interface pointer to the relative moniker.

Note ppmkRelPath is not returned, because this method can return many successful HRESULTs. This requires a throw in Java, which disallows return values.


IParseDisplayName Interface (com.ms.com Package)

 Microsoft SDK for Java

IParseDisplayName Interface

The IParseDisplayName interface of the com.ms.com package parses a displayable name string to convert it into a moniker for custom moniker implementations. Display name parsing is necessary when the end user inputs a string to identify a component.

Note The IParseDisplayName interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IParseDisplayName extends IUnknown
{
  // Methods
  public IMoniker ParseDisplayName(IBindCtx pbc, String pszDisplayName, int[] pchEaten);
}

IUnknown
  |
  +--IParseDisplayName


Methods (IParseDisplayName Interface)

 Microsoft SDK for Java

IParseDisplayName Interface Methods

The IParseDisplayName interface has the following method:

ParseDisplayName parses the display name to extract a component of the string that it can convert into a moniker.


ParseDisplayName (IParseDisplayName Interface)

 Microsoft SDK for Java

ParseDisplayName

This method of the IParseDisplayName interface parses the display name to extract a component of the string that it can convert into a moniker by using the maximum number of characters from the left side of the string.

Syntax

public IMoniker ParseDisplayName(IBindCtx pbc, String pszDisplayName, int[] pchEaten);

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK -- The parse operation was successful.

MK_E_SYNTAX -- Syntax error in the display name. Parsing failed because szDisplayName could only be partially resolved into a moniker. In this case, *pchEaten has the number of characters that were successfully parsed into a moniker prefix. The parameter ppmkOut should be NULL.

MK_E_NOOBJECT -- The display name does not identify a component in this namespace.

E_INVALIDARG -- One or more parameters are invalid.

Parameters

[in] pbc | The pointer to the bind context to be used in this binding operation.
[in] pszDisplayName | The pointer to a zero-terminated string containing the display name to be parsed. For Microsoft® Win32® applications, the LPOLESTR type indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.
[out] pchEaten | The pointer to the number of characters in the display name.


IPersist Interface (com.ms.com Package)

 Microsoft SDK for Java

IPersist Interface

The IPersist interface of the com.ms.com package defines a single method that supplies the CLSID of an object that can be stored persistently in the system. A call to this method can allow the object to specify which object handler to use in the client process as it is used in the OLE default implementation of marshaling.

Note The IPersist interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IPersist extends IUnknown
{
  // Methods
  public _Guid GetClassID();
}

IUnknown
  |
  +--IPersist


Methods (IPersist Interface)

 Microsoft SDK for Java

IPersist Interface Methods

The IPersist interface has the following methods:

GetClassID retrieves the class identifier (CLSID) of an object.


GetClassID

This method of the IPersist interface retrieves the CLSID of an object. The CLSID is a unique value that identifies the code that can manipulate the persistent data.

Syntax

public _Guid GetClassID();

Return Value

S_OK -- The CLSID was successfully retrieved.

E_FAIL -- The CLSID could not be retrieved.


IPersistFile Interface (com.ms.com Package)

 Microsoft SDK for Java

IPersistFile Interface

The IPersistFile interface of the com.ms.com package permits an object to be loaded from or saved to a disk file, rather than a storage object or stream. Because the information needed to open a file varies greatly from one application to another, the implementation of Load on the object must also open its disk file.

The IPersistFile interface inherits its definition from IPersist, so all implementations must also include IPersist.GetClassID.

Note The IPersistFile interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IPersistFile extends IPersist
{
  // Methods
  public boolean IsDirty();
  public void Load(String pszFileName, int dwMode);
  public void Save(String pszFileName, int fRemember);
  public void SaveCompleted(String pszFileName);
  public void GetCurFile(String[] ppszFileName);
}

IUnknown
  |
  +--IPersist
  |  |
  |  +--IPersistFile


Methods (IPersistFile Interface)

 Microsoft SDK for Java

IPersistFile Interface Methods

The IPersistFile interface has the following methods:

IsDirty checks an object for changes since it was last saved to its current file.
Load opens the specified file and initializes an object from the file contents.
Save saves the object into the specified file.
SaveCompleted notifies the object that it can revert from NoScribble mode to Normal mode.
GetCurFile gets the current name of the file associated with the object.


GetCurFile (IPersistFile interface)

 Microsoft SDK for Java

GetCurFile

This method of the IPersistFile interface retrieves either the absolute path to the object's current working file or, if there is no current working file, the object's default file name prompt.

Syntax

public void GetCurFile(String[] ppszFileName);

Return Value

S_OK -- A valid absolute path was successfully returned.

S_FALSE -- The default save prompt was returned.

E_OUTOFMEMORY -- The operation failed due to insufficient memory.

E_FAIL -- The operation failed due to some reason other than insufficient memory.

Parameters

[out] ppszFileName Points to the location of a pointer to a zero-terminated string containing the path for the current file or the default file name prompt (such as *.txt). If an error occurs, ppszFileName is set to NULL.


IsDirty (IPersistFile interface)

 Microsoft SDK for Java

IsDirty

This method of the IPersistFile interface checks an object for changes since it was last saved to its current file.

Syntax

public boolean IsDirty();

Return Value

S_OK -- The object has changed since it was last saved.

S_FALSE -- The object has not changed since the last save.


Load (IPersistFile interface)

 Microsoft SDK for Java

Load

This method of the IPersistFile interface opens the specified file and initializes an object from the file contents.

Syntax

public void Load(String pszFileName, int dwMode);

Return Value

S_OK -- The object was successfully loaded.

E_OUTOFMEMORY -- The object could not be loaded due to a lack of memory.

E_FAIL -- The object could not be loaded for some reason other than a lack of memory.

Parameters

[in] pszFileName | Points to a zero-terminated string containing the absolute path of the file to open.
[in] dwMode | Specifies some combination of the values from the STGM enumeration to indicate the access mode to use when opening the file. This method can treat this value as a suggestion, adding more restrictive permissions if necessary. If dwMode is 0 (zero), the implementation should open the file using whatever default permissions are used when a user opens the file.


Save (IPersistFile interface)

 Microsoft SDK for Java

Save

This method of the IPersistFile interface saves a copy of the object into the specified file.

Syntax

public void Save(String pszFileName, int fRemember);

Return Value

S_OK -- The object was successfully saved.

E_FAIL -- The file was not saved.

Parameters

[in] pszFileName | Points to a zero-terminated string containing the absolute path of the file to which the object should be saved. If pszFileName is NULL, the object should save its data to the current file, if there is one.
[in] fRemember | Indicates whether the pszFileName parameter is to be used as the current working file. If TRUE, pszFileName becomes the current file and the object should clear its dirty flag after the save. If FALSE, this save operation is a Save A Copy As ... operation. In this case, the current file is unchanged and the object should not clear its dirty flag. If pszFileName is NULL, the implementation should ignore the fRemember flag.


SaveCompleted (IPersistFile interface)

 Microsoft SDK for Java

SaveCompleted

This method of the IPersistFile interface notifies the object that it can write to its file. It does this by notifying the object that it can revert from NoScribble mode (in which it must not write to its file), to Normal mode (in which it can). The component enters NoScribble mode when it receives an Save call.

Syntax

public void SaveCompleted(String pszFileName);

Return Value

S_OK -- Returned in all cases.

Parameters

[in] pszFileName Points to the absolute path of the file where the object was previously saved.


IPersistStorage Interface (com.ms.com Package)

 Microsoft SDK for Java

IPersistStorage Interface

The IPersistStorage interface of the com.ms.com package enables a container application to pass a storage object to one of its contained objects and to load and save the storage object. This interface supports the structured storage model, in which each contained object has its own storage that is nested within the container's storage.

The IPersistStorage contract inherits its definition from IPersist, so all implementations must also include the GetClassID method of IPersist.

Note The IPersistStorage interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IPersistStorage extends IPersist
{
  // Methods
  public boolean IsDirty();
  public void InitNew(IStorage pstg);
  public void Load(IStorage pstg);
  public void Save(IStorage pStgSave, boolean fSameAsLoad);
  public void SaveCompleted(IStorage pStgNew);
  public void HandsOffStorage();
}

IUnknown
  |
  +--IPersist
  |  |
  |  +--IPersistStorage


Methods (IPersistStorage Interface)

 Microsoft SDK for Java

IPersistStorage Interface Methods

The IPersistStorage interface has the following methods:

IsDirty indicates whether the object has changed since it was last saved to its current storage.
InitNew initializes a new storage object.
Load initializes an object from its existing storage.
Save saves an object, and any nested objects that it contains, into the specified storage object. The object enters NoScribble mode.
SaveCompleted notifies the object that it can revert from NoScribble or HandsOff mode, in which it must not write to its storage object, to Normal mode in which it can.
HandsOffStorage instructs the object to release all storage objects that have been passed to it by its container and to enter HandsOffAfterSave or HandsOffFromNormal mode.


HandsOffStorage (IPersistStorage interface)

 Microsoft SDK for Java

HandsOffStorage

This method of the IPersistStorage interface instructs the object to release all storage objects that have been passed to it by its container and to enter HandsOff mode, in which the object cannot do anything and the only operation that works is a close operation.

Syntax

public void HandsOffStorage();

Return Value

S_OK -- The object has successfully entered HandsOff mode.


InitNew (IPersistStorage interface)

 Microsoft SDK for Java

InitNew

This method of the IPersistStorage interface initializes a new object, providing a pointer to the storage to be used for the object.

Syntax

public void InitNew(IStorage pstg);

Return Value

S_OK -- The new storage object was successfully initialized.

CO_E_ALREADYINITIALIZED -- The object has already been initialized by a previous call to either the IPersistStorage.Load method or the IPersistStorage.InitNew method.

E_OUTOFMEMORY -- The storage object was not initialized due to a lack of memory.

E_FAIL -- The storage object was not initialized for some reason other than a lack of memory.

Parameters

[in] pstg The IStorage pointer to the new storage object to be initialized. The container creates a nested storage object in its storage object (see CreateStorage). Then, the container calls the WriteClassStg function to initialize the new storage object with the object class identifier (CLSID).


IsDirty (IPersistStorage interface)

 Microsoft SDK for Java

IsDirty

This method of the IPersistStorage interface indicates whether the object has changed since it was last saved to its current storage.

Syntax

public boolean IsDirty();

Return Value

S_OK -- The object has changed since it was last saved.

S_FALSE -- The object has not changed since the last save.


Load (IPersistStorage interface)

 Microsoft SDK for Java

Load

This method of the IPersistStorage interface loads an object from its existing storage.

Syntax

public void Load(IStorage pstg);

Return Value

S_OK -- The object was successfully loaded.

CO_E_ALREADYINITIALIZED -- The object has already been initialized by a previous call to the IPersistStorage.Load method or the IPersistStorage.InitNew method.

E_OUTOFMEMORY -- The object was not loaded due to lack of memory.

E_FAIL -- The object was not loaded due to some reason besides a lack of memory.

Parameters

[in] pstg The IStorage pointer to the existing storage from which the object is to be loaded.


Save (IPersistStorage interface)

 Microsoft SDK for Java

Save

This method of the IPersistStorage interface saves an object, and any nested objects that it contains, into the specified storage. The object is placed in NoScribble mode, and it must not write to the specified storage until it receives a call to its IPersistStorage.SaveCompleted method.

Syntax

public void Save(IStorage pStgSave, boolean fSameAsLoad);

Return Value

S_OK -- The object was successfully saved.

STG_E_MEDIUMFULL -- The object was not saved because of a lack of space on the disk.

E_FAIL -- The object could not be saved due to errors other than a lack of disk space.

Parameters

[in] pStgSave The IStorage pointer to the storage into which the object is to be saved.
[in] fSameAsLoad Indicates whether the specified storage is the current one, which was passed to the object by one of the following calls:
  • InitNew when it was created.

  • Load when it was loaded.

  • SaveCompleted when it was saved to a storage different from its current storage.

This parameter is set to FALSE when performing a Save As or Save A Copy To operation or when performing a full save. In the latter case, this method saves to a temporary file, deletes the original file, and renames the temporary file.

This parameter is set to TRUE to perform a full save in a low-memory situation or to perform a fast incremental save in which only the dirty components are saved.


SaveCompleted (IPersistStorage interface)

 Microsoft SDK for Java

SaveCompleted

This method of the IPersistStorage interface notifies the object that it can revert from NoScribble or HandsOff mode, in which it must not write to its storage object, to Normal mode, in which it can. The object enters NoScribble mode when it receives an Save call.

Syntax

public void SaveCompleted(IStorage pStgNew);

Return Value

S_OK -- The object was successfully returned to Normal mode.

E_OUTOFMEMORY -- The object remained in HandsOff mode or NoScribble mode due to a lack of memory. Typically, this error occurs when the object is not able to open the necessary streams and storage objects in pStgNew.

E_INVALIDARG -- The pStgNew parameter is not valid. Typically, this error occurs if pStgNew is NULL when the object is in HandsOff mode.

E_UNEXPECTED -- The object is in Normal mode, and there was no previous call to Save or HandsOffStorage.

Parameters

[in] pStgNew The IStorage pointer to the new storage object, if different from the storage object prior to saving. This pointer can be NULL if the current storage object does not change during the save operation. If the object is in HandsOff mode, this parameter must be non-NULL.


IPersistStream Interface (com.ms.com Package)

 Microsoft SDK for Java

IPersistStream Interface

The IPersistStream interface of the com.ms.com package provides methods for saving and loading objects that use a simple serial stream for their storage needs. The IPersistStream interface inherits from the IPersist interface, and so includes IPersist.GetClassID.

IPersistStream is used to support OLE moniker implementations. Each of the OLE-provided moniker interfaces provides an IPersistStream implementation through which the moniker saves or loads itself. An instance of the OLE generic composite moniker class calls the IPersistStream methods of its component monikers to load or save the components in the proper sequence in a single stream.

OLE containers with embedded and linked component objects use the IPersistStorage interface instead.

Note The IPersistStream interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IPersistStream extends IPersist
{
  // Methods
  public boolean IsDirty();
  public void Load(IStream pstm);
  public void Save(IStream pstm, boolean fClearDirty);
  public long GetSizeMax();
}

IUnknown
  |
  +--IPersist
  |  |
  |  +--IPersistStream


Methods (IPersistStream Interface)

 Microsoft SDK for Java

IPersistStream Interface Methods

The IPersistStream interface has the following methods:

IsDirty checks the object for changes since it was last saved.
Load initializes an object from the stream where it was previously saved.
Save saves an object into the specified stream and indicates whether the object should reset its dirty flag.
GetSizeMax returns the size in bytes of the stream needed to save the object.


GetSizeMax (IPersistStream Interface)

 Microsoft SDK for Java

GetSizeMax

This method of the IPersistStream interface returns the size in bytes of the stream needed to save the object.

Syntax

public long GetSizeMax();

Return Value

S_OK -- The size was successfully returned.


IsDirty (IPersistStream Interface)

 Microsoft SDK for Java

IsDirty

This method of the IPersistStream interface checks whether an object has changed since it was last saved so you can avoid losing information in objects that have not yet been saved. The dirty flag for an object is conditionally cleared in the IPersistStream.Save method.

Syntax

public boolean IsDirty();

Return Value

S_OK -- The object has changed since it was last saved.

S_FALSE -- The object has not changed since the last save.


Load (IPersistStream Interface)

 Microsoft SDK for Java

Load

This method of the IPersistStream interface loads an object from the stream where it was previously. The seek pointer is set as it was in the most recent IPersistStream.Save method. This method can seek and read from the stream, but cannot write to it.

On exit, the seek pointer should be left in the same position as it was on exit from Save, immediately past the end of the data.

Syntax

public void Load(IStream pstm);

Return Value

S_OK -- The object was successfully loaded.

E_OUTOFMEMORY -- The object was not loaded due to a lack of memory.

E_FAIL -- The object was not loaded due to some reason other than a lack of memory.

Parameters

[in] pstm The IStream pointer to the stream from which the object should be loaded.


Save (IPersistStream Interface)

 Microsoft SDK for Java

Save

This method of the IPersistStream interface saves an object to the specified stream.

Syntax

public void Save(IStream pstm, boolean fClearDirty);

Return Value

S_OK -- The object was successfully saved to the stream.

STG_E_CANTSAVE -- The object could not save itself to the stream.

STG_E_MEDIUMFULL -- The object could not be saved because there is no space left on the storage device.

Parameters

[in] pstm | IStream pointer to the stream into which the object should be saved.
[in] fClearDirty | Indicates whether to clear the dirty flag after the save is complete. If TRUE, the flag should be cleared. If FALSE, the flag should be left unchanged.


IPersistStreamInit Interface (com.ms.com package)

 Microsoft SDK for Java

IPersistStreamInit Interface

The IPersistStreamInit interface of the com.ms.com package is implemented on any object that needs to support initialized stream-based persistence, regardless of whatever else the object does.

Note The IPersistStreamInit interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IPersistStreamInit extends IPersist
{
  // Methods
  public _Guid GetClassID();
  public boolean IsDirty();
  public void Load(IStream pstm);
  public void Save(IStream pstm, boolean fClearDirty);
  public long GetSizeMax();
  public void InitNew();
}

IUnknown
  |
  +--IPersist
  |  |
  |  +--IPersistStream
  |  |  |
  |  |  +--IPersistStreamInit


Methods (IPersistStreamInit interface)

 Microsoft SDK for Java

IPersistStreamInit Interface Methods

The IPersistStreamInit interface contains the following methods:

GetClassID retrieves the class identifier (CLSID) of an object.
IsDirty checks the object for changes since it was last saved.
Load initializes an object from the stream where it was previously saved.
Save saves an object into the specified stream and indicates whether the object should reset its dirty flag.
GetSizeMax returns the size in bytes of the stream needed to save the object.
InitNew initializes the object to a default state.


GetClassID (IPersistStreamInit interface)

 Microsoft SDK for Java

GetClassID

This method of the IPersistStreamInit interface retrieves the class identifier (CLSID) of an object. The CLSID is a unique value that identifies the code that can manipulate the persistent data.

Syntax

public _Guid GetClassID();

Return Value

S_OK -- The CLSID was successfully retrieved.

E_FAIL -- The CLSID could not be retrieved.


GetSizeMax (IPersistStreamInit Interface)

 Microsoft SDK for Java

GetSizeMax

This method of the IPersistStreamInit interface returns the size in bytes of the stream needed to save the object.

Syntax

public long GetSizeMax();

Return Value

S_OK -- The size was successfully returned.


InitNew (IPersistStreamInit Interface)

 Microsoft SDK for Java

InitNew

This method of the IPersistStreamInit interface initializes the object to a default state.

Syntax

public void InitNew();

Return Values

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

S_OK -- The object successfully initialized itself.

E_NOTIMPL -- The object requires no default initialization. This error code is allowed because an object may choose to implement IPersistStreamInit simply for orthogonality or in anticipation of a future need for this method.


IsDirty (IPersistStreamInit Interface)

 Microsoft SDK for Java

IsDirty

This method of the IPersistStreamInit interface checks whether an object has changed since it was last saved so you can avoid losing information in objects that have not yet been saved. The dirty flag for an object is conditionally cleared in the IPersistStreamInit.Save method.

Syntax

public boolean IsDirty();

Return Value

S_OK -- The object has changed since it was last saved.

S_FALSE -- The object has not changed since the last save.


Load (IPersistStreamInit Interface)

 Microsoft SDK for Java

Load

This method of the IPersistStreamInit interface loads an object from the stream where it was previously loaded. The seek pointer is set as it was in the most recent IPersistStreamInit.Save method. This method can seek and read from the stream, but cannot write to it.

On exit, the seek pointer should be left in the same position as it was on exit from Save, immediately past the end of the data.

Syntax

public void Load(IStream pstm);

Return Value

S_OK -- The object was successfully loaded.

E_OUTOFMEMORY -- The object was not loaded due to a lack of memory.

E_FAIL -- The object was not loaded due to some reason other than a lack of memory.

Parameters

[in] pstm The IStream pointer to the stream from which the object should be loaded.


Save (IPersistStreamInit Interface)

 Microsoft SDK for Java

Save

This method of the IPersistStreamInit interface saves an object to the specified stream.

Syntax

public void Save(IStream pstm, boolean fClearDirty);

Return Value

S_OK -- The object was successfully saved to the stream.

STG_E_CANTSAVE -- The object could not save itself to the stream.

STG_E_MEDIUMFULL -- The object could not be saved because there is no space left on the storage device.

Parameters

[in] pstm | The IStream pointer to the stream into which the object should be saved.
[in] fClearDirty | Indicates whether to clear the dirty flag after the save is complete. If TRUE, the flag should be cleared. If FALSE, the flag should be left unchanged.


IPropertyNotifySink Interface (com.ms.com Package)

 Microsoft SDK for Java

IPropertyNotifySink Interface

The IPropertyNotifySink interface of the com.ms.com package provides methods that allow a sink object to receive notifications about property changes from another object.

public interface IPropertyNotifySink extends IUnknown
{
  // Fields
  public static final _Guid iid,
     (short)0xeff1,
     (short)0x101a,
     (byte)0x84,
     (byte)0xed,
     (byte)0x0,
     (byte)0xaa,
     (byte)0x0,
     (byte)0x34,
     (byte)0x1d,
     (byte)0x7);

  // Methods
  public void OnChanged(int dispID);
  public void OnRequestEdit(int dispID);
}


Methods (IPropertyNotifySink Interface)

 Microsoft SDK for Java

IPropertyNotifySink Interface Methods

The IPropertyNotifySink Interface contains the following methods:

OnChanged notifies a sink object that a bindable property has changed.
OnRequestEdit notifies a sink object that a requestedit property is about to change.


OnChanged (IPropertyNotifySink Interface)

 Microsoft SDK for Java

OnChanged

This method of the IPropertyNotifySink Interface notifies a sink object that a bindable property has changed.

Syntax

public void OnChanged(int dispID);

Parameters

dispID The identifier of the object that is notified.


OnRequestEdit (IPropertyNotifySink Interface)

 Microsoft SDK for Java

OnRequestEdit

This method of the IPropertyNotifySink Interface notifies a sink object that a requestedit property is about to change.

Syntax

public void OnRequestEdit(int dispID);

Parameters

dispID The identifier of the object that is notified.

Remarks

On return from a call to this method, the notifying object cannot override the action specified by the sink object. For example, if the sink object does not allow the property change, the notifying object cannot make the change.


Fields (IPropertyNotifySink Interface)

 Microsoft SDK for Java

IPropertyNotifySink Interface Fields

The IPropertyNotifySink Interface contains the following field.

iid The interface identifier.


IROTData Interface (com.ms.com Package)

 Microsoft SDK for Java

IROTData Interface

The IROTData interface of the com.ms.com package is implemented by monikers to enable the Running Object Table (ROT) to compare monikers against each other.

The ROT uses the IROTData interface to test whether two monikers are equal. The ROT must do this when, for example, it checks whether a specified moniker is registered as running.

Note The IROTData interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IROTData extends IUnknown
{
  // Methods
  public int GetComparisonData(byte[] pbData, int cbMax);


Methods (IROTData Interface)

 Microsoft SDK for Java

IROTData Interface Methods

The IROTData interface has the following method:

GetComparisonData retrieves data from a moniker that can be used to test the moniker for equality against another moniker.


GetComparisonData (IROTData interface)

 Microsoft SDK for Java

GetComparisonData

This method of the IROTData interface retrieves data from a moniker that can be used to test the moniker for equality against another moniker.

Syntax

public int GetComparisonData(byte[] pbData, int cbMax);

Return Values

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK -- The comparison data was successfully returned.

Parameters

[out] pbData | The pointer to a buffer that receives the comparison data.
[in] cbMax | The length of the buffer (in bytes).


IRunningObjectTable Interface (com.ms.com Package)

 Microsoft SDK for Java

IRunningObjectTable Interface

The IRunningObjectTable interface of the com.ms.com package manages access to the Running Object Table (ROT), a globally accessible look-up table on each workstation. A workstation's ROT keeps track of those objects that can be identified by a moniker and that are currently running on the workstation. When a client tries to bind a moniker to an object, the moniker checks the ROT to see if the object is already running; this allows the moniker to bind to the current instance instead of loading a new one.

The ROT contains entries of the form:

(pmkObjectName, pUnkObject)

The pmkObjectName element is a pointer to the moniker that identifies the running object. The pUnkObject element is a pointer to the running object itself. During the binding process, monikers consult the pmkObjectName entries in the ROT to see if an object is already running.

Objects that can be named by monikers must be registered with the ROT when they are loaded and their registration must be revoked when they are no longer running.

Note The IRunningObjectTable interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IRunningObjectTable extends IUnknown
{
  // Methods
  public void Register(int grfFlags, IUnknown punkObject,
    IMoniker pmkObjectName, int[] pdwRegister);
  public void Revoke(int dwRegister);
  public boolean IsRunning(IMoniker pmkObjectName);
  public IUnknown GetObject(IMoniker pmkObjectName);
  public void NoteChangeTime(int dwRegister, long pfiletime);
  public long GetTimeOfLastChange(IMoniker pmkObjectName);
  public IEnumMoniker EnumRunning();


Methods (IRunningObjectTable Interface)

 Microsoft SDK for Java

IRunningObjectTable Interface Methods

The IRunningObjectTable interface has the following methods:

Register registers an object with the ROT.
Revoke revokes an object's registration with the ROT.
IsRunning checks whether an object is running.
GetObject returns a pointer to an object given its moniker.
NoteChangeTime notifies the ROT that an object has changed.
GetTimeOfLastChange returns the time an object was last changed.
EnumRunning returns an enumerator for the ROT.


EnumRunning (IRunningObjectTable Interface)

 Microsoft SDK for Java

EnumRunning

This method of the IRunningObjectTable interface creates and returns a pointer to an enumerator that can list the monikers of all the objects currently registered in the Running Object Table (ROT).

Syntax

public IEnumMoniker EnumRunning();

Return Value

This method supports the standard return value E_OUTOFMEMORY, as well as the following:

S_OK -- An enumerator was successfully returned.


GetObject (IRunningObjectTable Interface)

 Microsoft SDK for Java

GetObject

This method of the IRunningObjectTable interface determines whether the object identified by the specified moniker is running, and if it is, retrieves a pointer to that object. This method looks for the moniker in the Running Object Table (ROT), and retrieves the pointer registered there.

Syntax

public IUnknown GetObject(IMoniker pmkObjectName);

Return Value

S_OK -- Indicates that pmkObjectName was found in the ROT and a pointer was returned.

S_FALSE -- There is no entry for pmkObjectName in the ROT, or that the object it identifies is no longer running (in which case, the entry is revoked).

Parameters

[in] pmkObjectName The pointer to the moniker to search for in the Running Object Table.


GetTimeOfLastChange (IRunningObjectTable Interface)

 Microsoft SDK for Java

GetTimeOfLastChange

This method of the IRunningObjectTable interface returns the time that an object was last modified. The object must have previously been registered with the Running Object Table (ROT). This method looks for the last change time recorded in the ROT.

Syntax

public long GetTimeOfLastChange(IMoniker pmkObjectName);

Return Value

S_OK -- The last change time was successfully retrieved.

S_FALSE -- There is no entry for pmkObjectName in the ROT, or that the object it identifies is no longer running (in which case, the entry is revoked).

Parameters

[in] pmkObjectName The pointer to the IMoniker interface on the moniker to search for in the ROT.


IsRunning (IRunningObjectTable Interface)

 Microsoft SDK for Java

IsRunning

This method of the IRunningObjectTable interface determines whether the object identified by the specified moniker is currently running. This method looks for the moniker in the Running Object Table (ROT).

Syntax

public boolean IsRunning(IMoniker pmkObjectName);

Return Value

S_OK -- The object identified by pmkObjectName is running.

S_FALSE -- There is no entry for pmkObjectName in the ROT, or that the object it identifies is no longer running (in which case, the entry is revoked).

Parameters

[in] pmkObjectName The pointer to the IMoniker interface on the moniker to search for in the ROT.


NoteChangeTime (IRunningObjectTable Interface)

 Microsoft SDK for Java

NoteChangeTime

This method of the IRunningObjectTable interface records the time that a running object was last modified. The object must have previously been registered with the Running Object Table (ROT). This method stores the time of last change in the ROT.

Syntax

public void NoteChangeTime(int dwRegister, long pfiletime);

Return Value

This method supports the standard return value E_INVALIDARG, as well as the following:

S_OK -- The change time was recorded successfully.

Parameters

[in] dwRegister | Value identifying the ROT entry of the changed object. This value was previously returned by Register.
[in] pfiletime | Pointer to a FILETIME structure containing the object's last change time.


Register (IRunningObjectTable Interface)

 Microsoft SDK for Java

Register

This method of the IRunningObjectTable interface registers an object and its identifying moniker in the Running Object Table (ROT).

Syntax

public void Register(int grfFlags, IUnknown punkObject, IMoniker pmkObjectName, int[] pdwRegister);

Return Value

This method supports the standard return values E_INVALIDARG and E_OUTOFMEMORY, as well as the following:

S_OK -- The object was successfully registered.

MK_S_MONIKERALREADYREGISTERED -- The moniker/object pair was successfully registered, but that another object (possibly the same object) has already been registered with the same moniker.

Parameters

[in] grfFlags | Specifies whether the ROT's reference to punkObject is weak or strong and controls access to the object through its entry in the ROT. (See the following remarks.)
[in] punkObject | The pointer to the object that is being registered as running.
[in] pmkObjectName | The pointer to the moniker that identifies punkObject.
[out] pdwRegister | Pointer to a 32-bit value that can be used to identify this ROT entry in subsequent calls to Revoke or NoteChangeTime. The caller cannot specify NULL for this parameter. If an error occurs, pdwRegister is set to 0 (zero).

Remarks

This method registers a pointer to an object under a moniker that identifies the object. The moniker is used as the key when the table is searched with GetObject.

The grfFlags parameter accepts two flag settings:

  • ROTFLAGS_REGISTRATIONKEEPSALIVE. When set, indicates a strong registration for the object.

  • ROTFLAGS_ALLOWANYCLIENT. When set, any client can connect to the running object through its entry in the ROT. When not set, only clients in the window station that registered the object can connect to it.

When an object is registered, the ROT always calls AddRef on the object. For a weak registration (ROTFLAGS_REGISTRATIONKEEPSALIVE not set), the ROT will release the object whenever the last strong reference to the object is released. For a strong registration (ROTFLAGS_REGISTRATIONKEEPSALIVE set), the ROT prevents the object from being destroyed until the object's registration is explicitly revoked.

A server registered as either LocalService or RunAs can set the ROTFLAGS_ALLOWANYCLIENT flag in its call to Register to allow any client to connect to it. A server setting this bit must have its executable name in the AppID section of the registry that refers to the AppID for the executable. An "activate as activator" server (not registered as LocalService or RunAs) must not set this flag in its call to Register.

Registering a second object with the same moniker, or re-registering the same object with the same moniker, creates a second entry in the ROT. In this case, Register returns MK_S_MONIKERALREADYREGISTERED. Each call to Register must be matched by a call to Revoke because even duplicate entries have different pdwRegister identifiers. A problem with duplicate registrations is that there is no way to determine which object will be returned if the moniker is specified in a subsequent call to IsRunning.


Revoke (IRunningObjectTable Interface)

 Microsoft SDK for Java

Revoke

This method of the IRunningObjectTable interface removes from the Running Object Table (ROT) an entry that was previously registered by a call to Register.

Syntax

public void Revoke(int dwRegister);

Return Value

This method supports the standard return value E_INVALIDARG, as well as the following:

S_OK -- The object's registration was successfully revoked.

Parameters

[in] dwRegister The value identifying the ROT entry to revoke. This value was previously returned by Register.


ISequentialStream Interface (com.ms.com Package)

 Microsoft SDK for Java

ISequentialStream Interface

The ISequentialStream interface of the com.ms.com package supports simplified sequential access to stream objects.

Note The ISequentialStream interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface ISequentialStream extends IUnknown
{
  // Methods
  public int Read(byte buf[], int off, int len);
  public int Write(byte buf[], int off, int len);
}

Hierarchy

IUnknown
  |
  +--ISequentialStream


Methods (ISequentialStream Interface)

 Microsoft SDK for Java

ISequentialStream Interface Methods

The ISequentialStream interface contains the following methods:

Read reads a specified number of bytes from the stream object into memory starting at the current seek pointer.
Write writes a specified number of bytes into the stream object starting at the current seek pointer.


Read (ISequentialStream Interface)

 Microsoft SDK for Java

Read

This method of the ISequentialStream interface reads a specified number of bytes from the stream object into memory starting at the current seek pointer.

Syntax

public int Read(byte buf[], int off, int len);

Return Values

S_OK -- The data was successfully read from the stream object.

S_FALSE -- The data could not be read from the stream object.

E_PENDING -- Asynchronous storage only: Part or all of the data to be read is currently unavailable.

STG_E_ACCESSDENIED -- The caller does not have sufficient permissions for reading this stream object.

STG_E_INVALIDPOINTER -- One of the pointer values is invalid.

STG_E_REVERTED -- The object has been invalidated by a revert operation above it in the transaction tree.

Parameters

buf | The buffer that the bytes are read into.
off | The offset in the stream to begin reading from.
len | The number of bytes to read.


Write (ISequentialStream Interface)

 Microsoft SDK for Java

Write

This method of the ISequentialStream interface writes a specified number of bytes into the stream object starting at the current seek pointer.

Syntax

public int Write(byte buf[], int off, int len);

Return Values

S_OK -- The data was successfully written to the stream object.

E_PENDING -- Asynchronous storage only: Part or all of the data to be written is currently unavailable.

STG_E_MEDIUMFULL -- The write operation was not completed because there is no space left on the storage device.

STG_E_ACCESSDENIED -- The caller does not have sufficient permissions for writing to this stream object.

STG_E_CANTSAVE -- Data cannot be written for reasons other than no access or space.

STG_E_INVALIDPOINTER -- One of the pointer values is invalid.

STG_E_REVERTED -- The object has been invalidated by a revert operation above it in the transaction tree.

STG_E_WRITEFAULT -- The write operation was not completed due to a disk error. This value is also returned when attempting to write to a stream that was opened in simple mode (using the STGM_SIMPLE flag).

Parameters

buf | The buffer to write from.
off | The offset in the array to begin writing from.
len | The number of bytes to write.


IServiceProvider Interface (com.ms.com Package)

 Microsoft SDK for Java

IServiceProvider Interface

The IServiceProvider Interface of the com.ms.com package provides a method that locates a service specified by a GUID and returns the interface pointer for a requested interface on the service.

public interface IServiceProvider extends IUnknown
{
  // Fields
  public static final _Guid iid;

  // Methods
  public void QueryService(_Guid guidService, _Guid riid, Object[] ppvObject);
}

An object that provides services could implement the IServiceProvider interface as a general way to supply its clients with pointers to the interfaces on the service.

Sometimes, the QueryService method returns an interface pointer from an object other than the site object. This happens when a service is provided through a separate control or through some other object that the client communicates with.

This interface wraps the Component Object Model (COM) IServiceProvider interface.

Hierarchy

IUnknown
  |
  +--IServiceProvider


Methods (IServiceProvider Interface)

 Microsoft SDK for Java

IServiceProvider Interface Methods

The IServiceProvider Interface contains the following method:

QueryService retrieves the interface pointer for a requested interface on a service.


QueryService (IServiceProvider Interface)

 Microsoft SDK for Java

QueryService

This method of the IServiceProvider Interface retrieves the interface pointer for a requested interface on a service.

Syntax

public void QueryService(_Guid guidService, _Guid riid, Object[] ppvObject);

Parameters

guidService | The GUID for the service.
riid | The identifier of the requested interface.
ppvObject | The returned interface.


Fields (IServiceProvider Interface)

 Microsoft SDK for Java

IServiceProvider Interface Fields

The IServiceProvider Interface contains the following field.

iid The interface identifier.


IStorage Interface (com.ms.com Package)

 Microsoft SDK for Java

IStorage Interface

The IStorage interface of the com.ms.com package supports the creation and management of structured storage objects. Structured storage allows hierarchical storage of information within a single file, and is often referred to as "a file system within a file." Elements of a structured storage object are storages and streams. Storages are analogous to directories, and streams are analogous to files. Within a structured storage there will be a primary storage object that may contain substorages, possibly nested, and streams. Storages provide the structure of the object, and streams contain the data, which is manipulated through the IStream interface.

The IStorage interface provides methods for creating and managing the root storage object, child storage objects, and stream objects. These methods can create, open, enumerate, move, copy, rename, or delete the elements in the storage object.

An application must release its IStorage pointers when it is done with the storage object to de-allocate memory used. There are also methods for changing the date and time of an element.

Note The IStorage interface was added as of versions 2925 through 3167 of the Microsoft virtual machine.

public interface IStorage extends IUnknown
{
  // Methods
  public IStream CreateStream(String pwcsName, int grfMode,
    int reserved1, int reserved2);
  public IStream OpenStream(String pwcsName, int reserved1,
    int grfMode, int reserved2);
  public IStorage CreateStorage(String pwcsName, int grfMode,
    int reserved1, int reserved2);
  public IStorage OpenStorage(String pwcsName, IStorage pstgPriority,
    int grfMode, String[] snbExclude, int reserved);
  public void CopyTo(_Guid[] rgiidExclude, String[] snbExclude,
    IStorage pstgDest);
  public void MoveElementTo(String pwcsName, IStorage pstgDest,
    String pwcsNewName, int grfFlags);
  public void Commit(int grfCommitFlags);
  public void Revert();
  public IEnumSTATSTG EnumElements(int reserved1, int reserved2,
    int reserved3);
  public void DestroyElement(String pwcsName);
  public void RenameElement(String pwcsOldName, String pwcsNewName);
  public void SetElementTimes(String pwcsName, long[] pctime,
    long[] patime, long[] pmtime);
  public void SetClass(_Guid clsid);
  public void SetStateBits(int grfStateBits, int grfMask);
  public STATSTG Stat(int grfStatFlag);
}


Methods (IStorage Interface)

 Microsoft SDK for Java

IStorage Interface Methods

The IStorage interface has the following methods:

CreateStream creates and opens a stream object with the specified name contained in this storage object.

OpenStream opens an existing stream object within this storage object using the specified access permissions in grfMode.

CreateStorage creates and opens a new storage object within this storage object.

OpenStorage opens an existing storage object with the specified name according to the specified access mode.

CopyTo copies the entire contents of this open storage object into another storage object. The layout of the destination storage object may differ.

MoveElementTo copies or moves a substorage or stream from this storage object to another storage object.

Commit reflects changes for a transacted storage object to the parent level.

Revert discards all changes that have been made to the storage object since the last commit operation.

EnumElements returns an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object.

DestroyElement removes the specified storage or stream from this storage object.

RenameElement renames the specified storage or stream in this storage object.

SetElementTimes sets the modification, access, and creation times of the indicated storage element, if supported by the underlying file system.

SetClass assigns the specified CLSID to this storage object.

SetStateBits stores up to 32 bits of state information in this storage object.

Stat returns the STATSTG structure for this open storage object.


Commit (IStorage interface)

 Microsoft SDK for Java

Commit

This method of the IStorage interface ensures that any changes made to a storage object open in transacted mode are reflected in the parent storage; for a root storage, reflects the changes in the actual device, for example, a file on disk. For a root storage object opened in direct mode, this method has no effect except to flush all memory buffers to the disk. For non-root storage objects in direct mode, this method has no effect.

Syntax

public void Commit(int grfCommitFlags);

Return Value

S_OK -- Changes to the storage object were successfully committed to the parent level. If STGC_CONSOLIDATE was specified, the storage was successfully consolidated, or the storage was already too compact to consolidate further.

STG_S_MULTIPLEOPENS -- The commit operation succeeded, but the storage could not be consolidated because it had been opened multiple times using the STGM_NOSNAPSHOT flag.

STG_S_CANNOTCONSOLIDATE -- The commit operation succeeded, but the storage could not be consolidated due to an incorrect storage mode. For compound files, the storage may have been opened using the STGM_NOSCRATCH flag, or the storage may not be the outermost transacted level.

STG_S_CONSOLIDATIONFAILED -- The commit operation succeeded, but the storage could not be consolidated due to an internal error (for example, a memory allocation failure).

E_PENDING -- Asynchronous storage only: Part or all of the data to be committed is currently unavailable.

STG_E_INVALIDFLAG -- The value for the grfCommitFlags parameter is not valid.

STG_E_INVALIDPARAMETER -- One of the parameters was not valid.

STG_E_NOTCURRENT -- Another open instance of the storage object has committed changes. As a result, the current commit operation may overwrite previous changes.

STG_E_MEDIUMFULL -- No space left on device to commit.

STG_E_TOOMANYOPENFILES -- The commit operation could not be completed because there are too many open files.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

Parameters

[in] grfCommitFlags Controls how the changes are committed to the storage object.


CopyTo (IStorage interface)

 Microsoft SDK for Java

CopyTo

This method of the IStorage interface copies the entire contents of an open storage object to another storage object.

Syntax

public void CopyTo(_Guid[] rgiidExclude, String[] snbExclude, IStorage pstgDest);

Return Value

S_OK -- The storage object was successfully copied.

E_PENDING -- Asynchronous storage only: Part or all of the data to be copied is currently unavailable.

STG_E_ACCESSDENIED -- The destination storage object is a child of the source storage object.

STG_E_INSUFFICIENTMEMORY -- The copy was not completed due to a lack of memory.

STG_E_INVALIDPOINTER -- The pointer specified for the storage object was invalid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

STG_E_TOOMANYOPENFILES -- The copy was not completed because there are too many open files.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_MEDIUMFULL

The copy was not completed because the storage medium is full.

Parameters

[in] rgiidExclude | An array of interface identifiers that either the caller knows about and does not want to be copied or that the storage object does not support but whose state the caller will later explicitly copy. The array can include IStorage, indicating that only stream objects are to be copied, and IStream, indicating that only storage objects are to be copied. An array length of zero indicates that only the state exposed by the IStorage object is to be copied; all other interfaces on the object are to be ignored. Passing NULL indicates that all interfaces on the object are to be copied.
snbExclude | [in] A string name block that specifies a block of storage or stream objects that are not to be copied to the destination. These elements are not created at the destination. If IID_IStorage is in the rgiidExclude array, this parameter is ignored. This parameter may be NULL.
pstgDest | [in] Points to the open storage object into which this storage object is to be copied. The destination storage object can be a different implementation of the IStorage interface from the source storage object. Thus, CopyTo can only use publicly available methods of the destination storage object. If pstgDest is open in transacted mode, it can be reverted by calling its Revert method.


CreateStorage (IStorage interface)

 Microsoft SDK for Java

CreateStorage

This method of the IStorage interface creates and opens a new storage object nested within this storage object.

Syntax

public IStorage CreateStorage(String pwcsName, int grfMode, int reserved1, int reserved2);

Return Value

S_OK -- The storage object was created successfully.

E_PENDING -- Asynchronous storage only: Part or all the necessary data is currently unavailable.

STG_E_ACCESSDENIED -- Insufficient permissions to create storage object.

STG_E_FILEALREADYEXISTS -- The name specified for the storage object already exists in the storage object and the grfmode flag includes the flag STGM_FAILIFTHERE.

STG_E_INSUFFICIENTMEMORY -- The storage object was not created due to a lack of memory.

STG_E_INVALIDFLAG -- The value specified for the grfMode flag is not a valid STGM enumeration value.

STG_E_INVALIDFUNCTION -- The specified combination of grfMode flags is not supported.

STG_E_INVALIDNAME -- Invalid value for pwcsName.

STG_E_INVALIDPOINTER -- The pointer specified for the storage object was invalid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES -- The storage object was not created because there are too many open files.

STG_S_CONVERTED -- The existing stream with the specified name was replaced with a new storage object containing a single stream called CONTENTS. The new storage object will be added.

Parameters

pwcsName | [in] Points to a wide character string that contains the name of the newly created storage object. This name can be used later to reopen the storage object.
grfMode | [in] Specifies the access mode to use when opening the newly created storage object. For descriptions of the possible values, see the STGM enumeration values.
reserved1 | [in] Reserved for future use; must be 0 (zero).
reserved2 | [in] Reserved for future use; must be 0 (zero).


CreateStream (IStorage interface)

 Microsoft SDK for Java

CreateStream

This method of the IStorage interface creates and opens a stream object with the specified name contained in this storage object. All elements within a storage object—both streams and other storage objects—are kept in the same namespace.

Syntax

public IStream CreateStream(String pwcsName, int grfMode, int reserved1, int reserved2);

Return Value

S_OK -- The new stream was successfully created

E_PENDING -- Asynchronous storage only: Part or all the necessary data is currently unavailable.

STG_E_ACCESSDENIED -- Insufficient permissions to create stream.

STG_E_FILEALREADYEXISTS -- The name specified for the stream already exists in the storage object and the grfMode flag includes the flag STGM_FAILIFTHERE.

STG_E_INSUFFICIENTMEMORY -- The stream was not created due to a lack of memory.

STG_E_INVALIDFLAG -- The value specified for the grfMode flag is not a valid STGM enumeration value.

STG_E_INVALIDFUNCTION -- The specified combination of grfMode flags is not supported. For example, this method was called without the STGM_SHARE_EXCLUSIVE flag.

STG_E_INVALIDNAME -- Invalid value for pwcsName.

STG_E_INVALIDPOINTER -- The pointer specified for the stream object was invalid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES -- The stream was not created because there are too many open files.

Parameters

pwcsName | [in] Points to a wide character string that contains the name of the newly created stream. This name can be used later to open or reopen the stream.
grfMode | [in] Specifies the access mode to use when opening the newly created stream. For descriptions of the possible values, see the STGM enumeration values.
reserved1 | [in] Reserved for future use; must be 0 (zero).
reserved2 | [in] Reserved for future use; must be 0 (zero).


DestroyElement (IStorage interface)

 Microsoft SDK for Java

DestroyElement

This method of the IStorage interface removes the specified storage or stream from this storage object.

Syntax

public void DestroyElement(String pwcsName);

Return Value

S_OK -- The element was successfully removed.

E_PENDING -- Asynchronous storage only: Part or all of the element's data is currently unavailable.

STG_E_ACCESSDENIED -- The caller does not have sufficient permissions for removing the element.

STG_E_FILENOTFOUND -- The element with the specified name does not exist.

STG_E_INSUFFICIENTMEMORY -- The element was not removed due to a lack of memory.

STG_E_INVALIDNAME -- Invalid value for pwcsName.

STG_E_INVALIDPOINTER -- The pointer specified for the element was invalid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES -- The element was not removed because there are too many open files.

Parameters

pwcsName [in] Points to a wide character string that contains the name of the storage or stream to be removed.


EnumElements (IStorage interface)

 Microsoft SDK for Java

EnumElements

This method of the IStorage interface retrieves a pointer to an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object.

Syntax

public IEnumSTATSTG EnumElements(int reserved1, int reserved2, int reserved3);

Return Value

S_OK -- The enumerator object was successfully returned.

E_PENDING -- Asynchronous storage only: Part or all the element's data is currently unavailable.

STG_E_INSUFFICIENTMEMORY -- The enumerator object could not be created due to lack of memory.

STG_E_INVALIDPARAMETER -- One of the parameters was not valid.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

Parameters

reserved1 | [in] Reserved for future use; must be 0 (zero).
reserved2 | [in] Reserved for future use; must be 0 (zero).
reserved3 | [in] Reserved for future use; must be 0 (zero).


MoveElementTo (IStorage interface)

 Microsoft SDK for Java

MoveElementTo

This method of the IStorage interface copies or moves a substorage or stream from this storage object to another storage object.

Syntax

public void MoveElementTo(String pwcsName, IStorage pstgDest, String pwcsNewName, int grfFlags);

Return Value

S_OK -- The storage object was successfully copied or moved.

E_PENDING -- Asynchronous storage only: Part or all the element's data is currently unavailable.

STG_E_ACCESSDENIED -- The destination storage object is a child of the source storage object.

STG_E_FILENOTFOUND -- The element with the specified name does not exist.

STG_E_FILEALREADYEXISTS -- The specified file already exists.

STG_E_INSUFFICIENTMEMORY -- The copy or move was not completed due to a lack of memory.

STG_E_INVALIDFLAG -- The value for the grfFlags parameter is not valid.

STG_E_INVALIDNAME -- Invalid value for pwcsName.

STG_E_INVALIDPOINTER -- The pointer specified for the storage object was invalid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES -- The copy or move was not completed because there are too many open files.

Parameters

pwcsName | [in] Points to a wide character string that contains the name of the element in this storage object to be moved or copied.
pstgDest | [in] IStorage pointer to the destination storage object.
pwcsNewName | [in] Points to a wide character string that contains the new name for the element in its new storage object.
grfFlags | [in] Specifies whether the operation should be a move (STGMOVE_MOVE) or a copy (STGMOVE_COPY).


OpenStorage (IStorage interface)

 Microsoft SDK for Java

OpenStorage

This method of the IStorage interface opens an existing storage object with the specified name in the specified access mode.

Syntax

public IStorage OpenStorage(String pwcsName, IStorage pstgPriority, int grfMode, String[] snbExclude, int reserved);

Return Value

S_OK -- The storage object was opened successfully.

E_PENDING -- Asynchronous storage only: Part or all the storage's data is currently unavailable.

STG_E_ACCESSDENIED -- Insufficient permissions to open storage object.

STG_E_FILENOTFOUND -- The storage object with the specified name does not exist.

STG_E_INSUFFICIENTMEMORY -- The storage object was not opened due to a lack of memory.

STG_E_INVALIDFLAG -- The value specified for the grfMode flag is not a valid STGM enumeration value.

STG_E_INVALIDFUNCTION -- The specified combination of grfMode flags is not supported.

STG_E_INVALIDNAME -- Invalid value for pwcsName.

STG_E_INVALIDPOINTER -- The pointer specified for the storage object was invalid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES -- The storage object was not created because there are too many open files.

STG_S_CONVERTED -- The existing stream with the specified name was replaced with a new storage object containing a single stream called CONTENTS. In direct mode, the new storage is immediately written to disk. In transacted mode, the new storage is written to a temporary storage in memory and later written to disk when it is committed.

Parameters

pwcsName | [in] Points to a wide character string that contains the name of the storage object to open. It is ignored if pstgPriority is non-NULL.
pstgPriority | [in] Must be NULL. A non-NULL value will return STG_E_INVALIDPARAMETER.
grfMode | [in] Specifies the access mode to use when opening the storage object. For descriptions of the possible values, see the STGM enumeration values. Whatever other modes you may choose, you must at least specify STGM_SHARE_EXCLUSIVE when calling this method.
snbExclude | [in] Must be NULL. A non-NULL value will return STG_E_INVALIDPARAMETER.
reserved | [in] Reserved for future use; must be 0 (zero).


OpenStream (IStorage interface)

 Microsoft SDK for Java

OpenStream

This method of the IStorage interface opens an existing stream object within this storage object in the specified access mode.

Syntax

public IStream OpenStream(String pwcsName, int reserved1, int grfMode, int reserved2);

Return Value

S_OK -- The stream was successfully opened.

E_PENDING -- Asynchronous storage only: Part or all the stream's data is currently unavailable.

STG_E_ACCESSDENIED -- Insufficient permissions to open stream.

STG_E_FILENOTFOUND -- The stream with specified name does not exist.

STG_E_INSUFFICIENTMEMORY -- The stream was not opened due to a lack of memory.

STG_E_INVALIDFLAG -- The value specified for the grfMode flag is not a valid STGM enumeration value.

STG_E_INVALIDFUNCTION -- The specified combination of grfMode flags is not supported. For example, if this method was called without the STGM_SHARE_EXCLUSIVE flag.

STG_E_INVALIDNAME -- Invalid value for pwcsName.

STG_E_INVALIDPOINTER -- The pointer specified for the stream object was invalid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES -- The stream was not opened because there are too many open files.

Parameters

pwcsName | [in] Points to a wide character string that contains the name of the stream to open.
reserved1 | [in] Reserved for future use; must be 0 (zero).
grfMode | [in] Specifies the access mode to be assigned to the open stream. For descriptions of the possible values, see the STGM enumeration values. Whatever other modes you may choose, you must at least specify STGM_SHARE_EXCLUSIVE when calling this method in the compound file implementation.
reserved2 | [in] Reserved for future use; must be 0 (zero).


RenameElement (IStorage interface)

 Microsoft SDK for Java

RenameElement

This method of the IStorage interface renames the specified substorage or stream in this storage object.

Syntax

public void RenameElement(String pwcsOldName, String pwcsNewName);

Return Value

S_OK -- The element was successfully renamed.

E_PENDING -- Asynchronous storage only: Part or all the element's data is currently unavailable.

STG_E_ACCESSDENIED -- The caller does not have sufficient permissions for renaming the element.

STG_E_FILENOTFOUND -- The element with the specified old name does not exist.

STG_E_FILEALREADYEXISTS -- The element specified by the new name already exists.

STG_E_INSUFFICIENTMEMORY -- The element was not renamed due to a lack of memory.

STG_E_INVALIDNAME -- Invalid value for one of the names.

STG_E_INVALIDPOINTER -- The pointer specified for the element was invalid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES -- The element was not renamed because there are too many open files.

Parameters

pwcsOldName | [in] Points to a wide character string that contains the name of the substorage or stream to be changed.
pwcsNewName | [in] Points to a wide character string that contains the new name for the specified substorage or stream.


Revert (IStorage interface)

 Microsoft SDK for Java

Revert

This method of the IStorage interface discards all changes that have been made to the storage object since the last commit.

Syntax

public void Revert();

Return Value

S_OK -- The revert operation was successful.

E_PENDING -- Asynchronous storage only: Part or all the storage's data is currently unavailable.

STG_E_INSUFFICIENTMEMORY -- The revert operation could not be completed due to a lack of memory.

STG_E_TOOMANYOPENFILES -- The revert operation could not be completed because there are too many open files.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.


SetClass (IStorage interface)

 Microsoft SDK for Java

SetClass

This method of the IStorage interface assigns the specified CLSID to this storage object.

Syntax

public void SetClass(_Guid clsid);

Return Value

S_OK -- The CLSID was successfully assigned.

E_PENDING -- Asynchronous storage only: Part or all the storage's data is currently unavailable.

STG_E_ACCESSDENIED -- The caller does not have sufficient permissions for assigning a class identifier to the storage object.

STG_E_MEDIUMFULL -- Not enough space was left on device to complete the operation.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

Parameters

clsid [in] The class identifier (CLSID) that is to be associated with the storage object.


SetElementTimes (IStorage interface)

 Microsoft SDK for Java

SetElementTimes

This method of the IStorage interface sets the modification, access, and creation times of the specified storage element, if supported by the underlying file system.

Syntax

public void SetElementTimes(String pwcsName, long[] pctime, long[] patime, long[] pmtime);

Return Value

S_OK -- The time values were successfully set.

E_PENDING -- Asynchronous storage only: Part or all the element's data is currently unavailable.

STG_E_ACCESSDENIED -- The caller does not have sufficient permissions for changing the element.

STG_E_FILENOTFOUND -- The element with the specified name does not exist.

STG_E_INSUFFICIENTMEMORY -- The element was not changed due to a lack of memory.

STG_E_INVALIDNAME -- Invalid value for the element name.

STG_E_INVALIDPOINTER -- The pointer specified for the element was invalid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

STG_E_TOOMANYOPENFILES -- The element was not changed because there are too many open files.

STG_E_REVERTED -- The storage object has been invalidated by a revert operation above it in the transaction tree.

Parameters

pwcsName | [in] The name of the storage object element whose times are to be modified. If NULL, the time is set on the root storage rather than one of its elements.
pctime | [in] Either the new creation time for the element or NULL if the creation time is not to be modified.
patime | [in] Either the new access time for the element or NULL if the access time is not to be modified.
pmtime | [in] Either the new modification time for the element or NULL if the modification time is not to be modified.


SetStateBits (IStorage interface)

 Microsoft SDK for Java

SetStateBits

This method of the IStorage interface stores up to 32 bits of state information in this storage object.

Syntax

public void SetStateBits(int grfStateBits, int grfMask);

Return Value

S_OK -- The state information was successfully set.

E_PENDING -- Asynchronous storage only: Part or all of the storage's data is currently unavailable.

STG_E_ACCESSDENIED -- The caller does not have sufficient permissions for changing this storage object.

STG_E_INVALIDFLAG -- The value for the grfStateBits or grfMask parameters are not valid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

Parameters

grfStateBits | [in] Specifies the new values of the bits to set. No legal values are defined for these bits; they are all reserved for future use and must not be used by applications.
grfMask | [in] A binary mask indicating which bits in grfStateBits are significant in this call.


Stat (IStorage interface)

 Microsoft SDK for Java

Stat

This method of the IStorage interface retrieves the STATSTG structure for this open storage object.

Syntax

public STATSTG Stat(int grfStatFlag);

Return Value

S_OK -- The STATSTG structure was successfully returned at the specified location.

E_PENDING -- Asynchronous storage only: Part or all the storage's data is currently unavailable.

STG_E_ACCESSDENIED -- The caller does not have sufficient permissions for accessing statistics for this storage object.

STG_E_INSUFFICIENTMEMORY -- The STATSTG structure was not returned due to a lack of memory.

STG_E_INVALIDFLAG -- The value for the grfStateFlag parameter is not valid.

STG_E_INVALIDPARAMETER -- One of the parameters was invalid.

Parameters

grfStatFlag [in] Specifies that some of the fields in the STATSTG structure are not returned, thus saving a memory allocation operation. Values are taken from the STATFLAG enumeration.


IStream (com.ms.com Package)

 Microsoft SDK for Java

IStream Interface

The IStream interface of the com.ms.com package provides methods for reading and writing data to stream objects. Each stream has its own access rights and seek pointer.

public interface IStream extends IUnknown
{
  // Fields
  public static final _Guid iid;
  public static final int LOCK_EXCLUSIVE;
  public static final int LOCK_ONLYONCE;
  public static final int LOCK_WRITE;
  public static final int STATFLAG_DEFAULT;
  public static final int STATFLAG_NONAME;
  public static final int STATFLAG_NOOPEN;
  public static final int STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE;
  public static final int STGC_DEFAULT;
  public static final int STGC_ONLYIFCURRENT;
  public static final int STGC_OVERWRITE;
  public static final int STREAM_SEEK_CUR;
  public static final int STREAM_SEEK_END;
  public static final int STREAM_SEEK_SET;

  // Methods
  public IStream Clone();
  public void Commit(int grfCommitFlags);
  public void CopyTo(IStream pstm, long cb, long[] pcbRead,
        long[] pcbWritten);
  public void LockRegion(long libOffset, long cb, int dwLockType);
  public int Read(byte buf[], int off, int len);
  public void Revert();
  public long Seek(long dlibMove, int dwOrigin);
  public void SetSize(long libNewSize);
  public void Stat(STATSTG pstatstg, int grfStatFlag);
  public void UnlockRegion(long libOffset, long cb, int dwLockType);
  public int Write(byte buf[], int off, int len);
}

The main difference between a stream object and an MS-DOS file is that streams are opened through an IStream interface pointer instead of using a file handle. Simple data can be written directly to a stream. Usually, however, streams are elements nested within a storage object.

This interface wraps the Component Object Model (COM) IStream interface.

Hierarchy

IUnknown
  |
  +--IStream


Methods (IStream Interface)

 Microsoft SDK for Java

IStream Interface Methods

The IStream Interface contains the following methods:

Clone creates a new stream object with its own seek pointer that references the same bytes as the original stream.

Commit ensures that any changes made to a stream object opened in transacted mode are reflected in the parent storage object.

CopyTo copies a specific number of bytes from the current seek pointer in the stream to the current seek pointer in another stream.

LockRegion restricts access to a range of bytes in the stream.

Read reads bytes from the stream object into a byte array, starting at a specified offset from the current seek pointer.

Revert discards all changes made to a transacted stream since the last Commit call.

Seek changes the seek pointer to a new location relative to the beginning of the stream, the end of the stream, or the current seek pointer.

SetSize changes the size of the stream object.

Stat retrieves the STATSTG structure for the current stream. (This structure contains statistical information about the current stream.)

UnlockRegion removes the access restriction on a range of bytes that was previously restricted with the LockRegion method.

write writes bytes from a byte array into the stream object, starting at a specified offset from the current seek pointer.


Clone (IStream Interface)

 Microsoft SDK for Java

Clone

This method of the IStream Interface creates a new stream object with its own seek pointer that references the same bytes as the original stream.

Syntax

public IStream Clone();

Return Value

Returns the new stream object.

Remarks

Because both the original object and its clone access the same data, changes written to one object are immediately visible in the other.


Commit (IStream Interface)

 Microsoft SDK for Java

Commit

This method of the IStream Interface ensures that any changes made to a stream object opened in transacted mode are reflected in the parent storage object.

Syntax

public void Commit(int grfCommitFlags);

Parameters

grfCommitFlags Flags that indicate conditions for the commit operation; the value must be STGC_DEFAULT or some combination of the following: STGC_OVERWRITE, STGC_ONLYIFCURRENT, and STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE.


CopyTo (IStream Interface)

 Microsoft SDK for Java

CopyTo

This method of the IStream Interface copies a specific number of bytes from the current seek pointer in the stream to the current seek pointer in another stream.

Syntax

public void CopyTo(IStream pstm, long cb, long[] pcbRead, long[] pcbWritten);

Parameters

pstm | The stream that is copied to.
cb | The number of bytes to copy.
pcbRead | A pointer to the number of bytes actually read.
pcbWritten | A pointer to the number of bytes actually written.


LockRegion (IStream Interface)

 Microsoft SDK for Java

LockRegion

This method of the IStream Interface restricts access to a range of bytes in the stream.

Syntax

public void LockRegion(long libOffset, long cb, int dwLockType);

Parameters

libOffset | The offset of the current seek pointer (measured in bytes) that indicates where to start the restriction.
cb | The number of bytes to restrict.
dwLocktype | A flag that indicates the type of restriction that is placed; the value must be LOCK_WRITE, LOCK_EXCLUSIVE, or LOCK_ONLYONCE.


Read (IStream Interface)

 Microsoft SDK for Java

Read

This method of the IStream Interface reads bytes from the stream object into a byte array, starting at a specified offset from the current seek pointer.

Syntax

public int Read(byte buf[], int off, int len);

Return Value

Returns the number of bytes actually read.

Parameters

buf | The buffer that the bytes are read into.
off | The offset in the stream to begin reading from.
len | The number of bytes to read.


Revert (IStream Interface)

 Microsoft SDK for Java

Revert

This method of the IStream Interface discards all changes made to a transacted stream since the last Commit call.

Syntax

public void Revert();

Remarks

This method has no effect on streams open in direct mode or streams using the OLE compound file Revert implementation.


Seek (IStream Interface)

 Microsoft SDK for Java

Seek

This method of the IStream Interface changes the seek pointer to a new location relative to the beginning of the stream, the end of the stream, or the current seek pointer.

Syntax

public long Seek(long dlibMove, int dwOrigin);

Return Value

Returns the new seek pointer of the stream.

Parameters

dlibMove | The offset relative to dwOrigin.
dwOrigin | The origin of the offset; must be STREAM_SEEK_CUR, STREAM_SEEK_END, or STREAM_SEEK_SET.


SetSize (IStream Interface)

 Microsoft SDK for Java

SetSize

This method of the IStream Interface changes the size of the stream object.

Syntax

public void SetSize(long libNewSize);

Parameters

libNewSize The new size of the stream, measured in bytes.


Stat (IStream Interface)

 Microsoft SDK for Java

Stat

This method of the IStream Interface retrieves the STATSTG structure for the current stream. (This structure contains statistical information about the current stream.)

Syntax

public void Stat(STATSTG pstatstg, int grfStatFlag);

Parameters

pstatstg | A STATSTG structure that contains the returned statistical information.
grfStatFlag | A flag that indicates whether to return a name in the STATSTG structure; the value must be STATFLAG_DEFAULT or STATFLAG_NONAME.


UnlockRegion (IStream Interface)

 Microsoft SDK for Java

UnlockRegion

This method of the IStream Interface removes the access restriction on a range of bytes that was previously restricted with the LockRegion method.

Syntax

public void UnlockRegion(long libOffset, long cb, int dwLockType);

Parameters

libOffset | The offset of the current seek pointer (measured in bytes) that indicates where to start removing the restriction.
cb | The number of bytes removed from the restriction.
dwlockType | A flag that indicates the type of restriction removed; the value must be LOCK_WRITE, LOCK_EXCLUSIVE, or LOCK_ONLYONCE.


Write (IStream Interface)

 Microsoft SDK for Java

Write

This method of the IStream Interface writes bytes from a byte array into the stream object, starting at a specified offset from the current seek pointer.

Syntax

public int Write(byte buf[], int off, int len);

Return Value

Returns The number of bytes actually written.

Parameters

buf | The buffer to write from.
off | The offset in the array to begin writing from.
len | The number of bytes to write.


Fields (IStream Interface)

 Microsoft SDK for Java

IStream Interface Fields

The IStream Interface contains the following fields.

iid | The interface identifier.
LOCK_EXCLUSIVE | Indicates a type of locking for the LockRegion and UnlockRegion methods. If this type of lock is granted, writing to the specified range of bytes is prohibited to everyone except for the owner, who was granted the lock.
LOCK_ONLYONCE | Indicates a type of locking for the LockRegion and UnlockRegion methods. If this type of lock is granted, other LOCK_ONLYONCE locks cannot be obtained on the range.
LOCK_WRITE | Indicates a type of locking for the LockRegion and UnlockRegion methods. If this type of lock is granted, the specified range of bytes can be opened and read any number of times. Writing to the locked range, however, is prohibited to everyone except the owner, who was granted the lock.
STATFLAG_DEFAULT | Indicates that the name field should be included in the STATSTG structure returned by the Stat method.
STATFLAG_NONAME | Indicates that the name field should not be included in the STATSTG structure returned by the Stat method.
STATFLAG_NOOPEN |
STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE | Specifies that changes are committed to a write-behind disk cache, but that the cache is not saved to the disk. Caution The cache is eventually written to disk, but usually not until after the write operation has already returned. You risk losing data if a problem occurs before the cache is saved and the data in the cache is lost.
STGC_DEFAULT | Specifies the default condition for the Commit method. This value indicates that none of the other values apply.
STGC_ONLYIFCURRENT | Specifies that the commit operation occurs only if there have been no changes to the saved storage object since the user most recently opened the storage object. Prevents multiple users of a storage object from overwriting one another's changes.
STGC_OVERWRITE | Specifies that the Commit method can overwrite existing data to reduce overall space requirements. Caution This value is not recommended for typical use because it is not as robust as the default case. Data loss can occur when the STGC_OVERWRITE value is specified and the commit operation fails due to some reason other than lack of space.
STREAM_SEEK_CUR | Specifies that the origin of the offset in the Seek method is the location of the current seek pointer.
STREAM_SEEK_END | Specifies that the origin of the offset in the Seek method is the end of the stream.
STREAM_SEEK_SET | Specifies that the origin of the offset in the Seek method is the beginning of the stream.


IUnknown Interface (com.ms.com Package)

 Microsoft SDK for Java

IUnknown Interface

The IUnknown interface of the com.ms.com package is used as the return type for Component Object Model (COM) methods that return arbitrary COM interfaces. To achieve backward compatibility, the jactivex tool is used to translate references in the IUnknown COM interface to the IUnknown Java interface.

public interface IUnknown
{
}


NoAutoScripting Interface (com.ms.com Package)

 Microsoft SDK for Java

NoAutoScripting Interface

When used in the implements clause of a class definition, the NoAutoScripting interface of the com.ms.com package prevents the Microsoft VM from including its own IDispatch implementation for the class.

public interface NoAutoScripting
{
}

Example

// A.func is exposed to scripting engines such as
// VB or VBScript, which operate on IDispatch
objects.

class A
{
  public void func() {
    ...
  }
}

// B.func is not exposed to scripting engines.

class B implements com.ms.com.NoAutoScripting
{
  public void func() {
    ...
  }
}

See Also

Compiler Directives Reference


NoAutoMarshaling Interface (com.ms.com Package)

 Microsoft SDK for Java

NoAutoMarshaling Interface

The NoAutoMarshaling interface of the com.ms.com package is an empty interface which is used to flag that the free-threaded marshaler should be disabled.

If a class implements NoAutoMarshaling, then the VM will not expose COM's free-threaded marshaler on the COM wrapper for any objects of that class. Also, the WFC bridge automatically turns on this flag for its controls.

WFC's support for hosting ActiveX controls uses this interface. It is also useful in scenerios like creating COM local servers, where you want to place a Java COM object in a particular apartment.

public interface NoAutoMarshaling
{
}

See Also

Compiler Directives Reference


com.ms.debug Package Overview

Microsoft Packages Overview

The com.ms.debug package contains routines for debugging the Microsoft virtual machine.

This package contains the following:

Classes

Hierarchy


Classes (com.ms.debug Package)

 Microsoft SDK for Java

com.ms.debug Package Classes

The com.ms.debug package contains the following class:

Debugger class contains routines for debugging the Microsoft virtual machine; added as of versions 2437 through 2925 of the Microsoft virtual machine.


Hierarchy (com.ms.debug Package)

 Microsoft SDK for Java

com.ms.debug Package Hierarchy

The com.ms.debug package has the following hierarchy:

Object
  |
  +-- Debugger


Debugger Class (com.ms.debug Package)

 Microsoft SDK for Java

Debugger Class

The Debugger class of the com.ms.debug package contains routines for debugging the Microsoft virtual machine.

public final class Debugger
{
  // Methods
  public static native void breakpoint ();
  public static String ExecutionModeltoString (int em);
  public static native int getExecutionModelOfCaller (int depth);
  public static String getExecutionModelStringOfCaller (int depth);
  public static String getExecutionModelStringOfCaller ();
  public static native int getInitialExecutionModelOfMethod (java.lang.reflect.Method m);
  public static native boolean isDebugging ();
  public static boolean isDebugThread (Thread t);
  public static boolean isDebugThread ();
  public static void setDebugThread (Thread t, boolean candebug);
  public static void setDebugThread (boolean candebug);

  // Fields
  public static final int EXEC_MODEL_INTERPRETED;
  public static final int EXEC_MODEL_NATIVE;
  public static final int EXEC_MODEL_COM;
  public static final int EXEC_MODEL_JIT;
  public static final int EXEC_MODEL_FAST_INTERPRETED;
}

Remarks

The Debugger class was added as of versions 2437 through 2925 of the Microsoft virtual machine.


Methods (Debugger Class)

 Microsoft SDK for Java

Debugger Class Methods

The Debugger Class contains the following methods:

breakpoint causes a breakpoint in the current process at the location of the caller of this function.
ExecutionModeltoString returns a string describing an EXEC_MODEL_XXX constant.
getExecutionModelOfCaller queries about the execution model of a caller at the specified stack depth.
getExecutionModelStringOfCaller returns a string describing the execution model of a caller.
getInitialExecutionModelOfMethod queries about the default execution model of a method.
isDebugging determines whether or not a debugger is attached to the current process.
isDebugThread checks the debug state of a thread.
setDebugThread marks or clears the debug state of a thread.


breakpoint (Debugger class)

 Microsoft SDK for Java

breakpoint

This method of the Debugger class causes a breakpoint in the current process at the location of the caller of this function. A breakpoint occurs only if a debugger is attached.

Syntax

public static native void breakpoint ();


ExecutionModeltoString (Debugger class)

 Microsoft SDK for Java

ExecutionModeltoString

This method of the Debugger Class returns a string describing an EXEC_MODEL_XXX constant. These constants are returned by getExecutionModelOfCaller and getInitialExecutionModelOfMethod.

Syntax

public static String ExecutionModeltoString (int em);

Parameters

em The EXEC_MODEL_XXX constant to be returned as a string.


getExecutionModelOfCaller (Debugger class)

 Microsoft SDK for Java

getExecutionModelOfCaller

This method of the Debugger Class queries about the execution model of a caller at the specified stack depth.

Syntax

public static native int getExecutionModelOfCaller (int depth);

Return Value

One of the EXEC_MODEL_XXX constants.

Parameters

depth The specified stack depth.


getExecutionModelStringOfCaller (Debugger class)

 Microsoft SDK for Java

getExecutionModelStringOfCaller

The getExecutionModelStringOfCaller method of the Debugger Class contains the following signatures:

getExecutionModelStringOfCaller (int depth)
getExecutionModelStringOfCaller ()

getExecutionModelStringOfCaller (int depth)

Returns a string describing the execution model of a caller at the specified stack depth.

Syntax

public static String getExecutionModelStringOfCaller (int depth)

Parameters

depth The specified stack depth.

getExecutionModelStringOfCaller ()

Returns a string describing the execution model of the caller of this function.

Syntax

public static String getExecutionModelStringOfCaller ()


getInitialExecutionModelOfMethod (Debugger class)

 Microsoft SDK for Java

getInitialExecutionModelOfMethod

This method of the Debugger Class queries about the default execution model of a method. The actual execution model used may vary at any time.

Syntax

public static native int getInitialExecutionModelOfMethod (java.lang.reflect.Method m);

Return Value

One of the EXEC_MODEL_XXX constants.

Parameters

m The method to get the execution model for.


isDebugging (Debugger class)

 Microsoft SDK for Java

isDebugging

This method of the Debugger Class determines if a debugger is attached to the current process.

Syntax

public static native boolean isDebugging ();

Return Value

True if a debugger is attached.


isDebugThread (Debugger class)

 Microsoft SDK for Java

isDebugThread

This method of the Debugger class contains the following signatures:

isDebugThread(Thread t)
isDebugThread()

isDebugThread(Thread t)

Checks the debug state of a thread.

Syntax

public static boolean isDebugThread (Thread t)

Parameters

t The thread to check for debug state.

isDebugThread()

Checks the debug state of the current thread.

Syntax

public static boolean isDebugThread ()


setDebugThread (Debugger class)

 Microsoft SDK for Java

setDebugThread

This method of the Debugger Class contains the following signatures:

setDebugThread (Thread t, boolean candebug)
setDebugThread (boolean candebug)

setDebugThread (Thread t, boolean candebug)

Marks or clears the debug state of a thread. Debug events such as exceptions, breakpoints, and so on will not trigger the debugger if this is set on the thread. This state is not re-entrant; that is, a single setDebugThread(false) overrides all instances of setDebugThread(true).

Syntax

public static void setDebugThread (Thread t, boolean candebug)

Parameters

t | The thread for which to mark or clear the debug state of a thread.
candebug | The flag that indicates the debug state.

setDebugThread (boolean candebug)

Marks or clears the debug state of the current thread.

Syntax

public static void setDebugThread (boolean candebug)

Parameters

candebug The flag that indicates the debug state of the current thread.


Fields (Debugger Class)

 Microsoft SDK for Java

Debugger Class Fields

The Debugger class contains the following fields. The strings are those returned by ExecutionModeltoString.

Field Name | Integer Constant | Return String
EXEC_MODEL_INTERPRETED | 1 | "interpreted"
EXEC_MODEL_NATIVE | 2 | "native"
EXEC_MODEL_COM | 3 | "COM"
EXEC_MODEL_JIT | 4 | "JIT-compiled"
EXEC_MODEL_FAST_INTERPRETED | 5 | "fast-interpreted"


com.ms.directX Package Overview

Microsoft Packages Overview

The com.ms.directX package provides the classes and interfaces needed by Java programs and applets to access the services and features of the DirectX® Component Object Model (COM) interface for Microsoft® Windows®.

This package contains the following:

Classes

Interfaces

Hierarchy

Note The SDK for Java does not explain how to use the DirectX classes. For information about how to use DirectX, see the DirectX Software Development Kit (SDK). In some cases, you may need to refer to the MSDN™ Library for full details about selected structures.

Important Unlike their counterparts in COM, DirectX methods in Java do not return HRESULT error values. At best, a method will indicate whether a call to it succeeded or failed; the exact cause of an error is not available. Although you can catch the ComException exception to determine whether a DirectX method failed, the getHResult method of this exception does not specify the exact cause of the error.


Classes (com.ms.directX Package)

 Microsoft SDK for Java

com.ms.directX Package Classes

The com.ms.directX package contains the following classes:

_Guid Class specifies a globally unique identifier in the initialize method.

D3dDeviceDesc Class contains a description of the current device.

D3dExecuteBufferDesc Class describes the execute buffer for such methods as createExecuteBuffer and lock.

D3dExecuteData Class specifies data for the execute method.

D3dFindDeviceResult Class contains a description of the current device.

D3dFindDeviceSearch Class contains a description of a device to search for.

D3dLightDesc Class defines the light type in calls to methods such as setLight and getLight.

D3dLVertex Class defines an untransformed and lit vertex (screen coordinates with color).

D3dMaterialDesc Class specifies material properties in calls to the getMaterial and setMaterial methods.

D3dMatrix Class describes a matrix for such methods as Direct3dDevice.getMatrix and Direct3dDevice.setMatrix.

D3dPickRecord Class returns information about picked primitives in an execute buffer for the getPickRecords method.

D3dRect Class is a rectangle definition.

D3dRMBox Class defines the bounding box retrieved by the Direct3dRMMesh.getBox and Direct3dRMMeshBuilder.getBox methods.

D3dRMImage Class describes an image that is attached to a texture by the Direct3dRM.createTexture method.

D3dRMPickDesc Class contains the pick position and face and group identifiers of the objects retrieved by the getPick method.

D3dRMQuaternion Class describes the rotation used by the addRotateKey method.

D3dRMVector4d Class describes the screen coordinates used as the destination of a transformation by the transform method and as the source of a transformation by the inverseTransform method.

D3dRMVertex Class defines an untransformed and unlit vertex (model coordinates with normal direction vector).

D3dStats Class contains statistics used by the getStats method.

D3dTLVertex Class defines a transformed and lit vertex (screen coordinates with color).

D3dTriangle Class describes a base type for all triangles.

D3dVector Class defines a vector for many Direct3D and Direct3DRM methods and classes.

D3dVertex Class defines an untransformed and unlit vertex (screen coordinates with color).

D3dViewportDesc Class defines the visible 3D volume and the 2D screen area that a 3D volume projects onto for the getViewport and setViewport methods.

DDBltFx Class passes blit operations to the bltFx method.

DDCaps Class represents the capabilities of the hardware exposed through the DirectDraw object.

DDCapsFx Class represents the capabilities of the hardware exposed through the DirectDraw object.

DDColorKey Class describes a source color key, destination color key or color space.

DDPixelFormat Class describes the pixel format of a DirectDrawSurface object for the getPixelFormat method.

DDSurfaceDesc Class contains a description of the surface to be created.

Direct3d Class creates Direct3D objects and sets up the environment.

Direct3dDevice Class retrieves and sets the capabilities of Microsoft® Direct3D® devices.

Direct3dExecuteBuffer Class sets up and controls a Direct3D execute buffer.

Direct3dLight Class retrieves and sets the capabilities of lights.

Direct3dMaterial Class retrieves and set the properties of materials.

Direct3dRM Class creates Direct3dRM objects and works with system-level variables.

Direct3dRMAnimation Class animates the position, orientation, and scaling of visuals, lights, and viewports.

Direct3dRMAnimationSet Class groups Direct3dRMAnimation objects together, which can simplify the playback of complex animation sequences.

Direct3dRMArray Class organizes groups of objects.

Direct3dRMDevice Class interacts with the output device.

Direct3dRMDeviceArray Class organizes device objects.

Direct3dRMFace Class interacts with a single polygon in a mesh.

Direct3dRMFaceArray Class organizes faces in a mesh.

Direct3dRMFrame Class interacts with frames—an object's frame of reference.

Direct3dRMFrameArray Class organizes frame objects.

Direct3dRMLight Class interacts with light objects.

Direct3dRMLightArray Class organizes light objects.

Direct3dRMMaterial Class interacts with material objects.

Direct3dRMMesh Class interacts with groups of meshes.

Direct3dRMMeshBuilder Class interacts with mesh objects.

Direct3dRMObject Class works with the object superclass of Direct3dRM objects.

Direct3dRMPickArray Class organizes pick objects.

Direct3dRMTexture Class works with textures, which are rectangular arrays of pixels.

Direct3dRMUserVisual Class manages user visual objects.

Direct3dRMViewport Class works with viewport objects.

Direct3dRMViewportArray Class organizes viewport objects.

Direct3dRMVisual Class creates shadows or adds visuals to a frame.

Direct3dRMVisualArray Class organizes groups of visual objects.

Direct3dRMWinDevice Class responds to window messages in a window procedure.

Direct3dRMWrap Class works with wrap objects.

Direct3dTexture Class retrieves and sets texture properties.

Direct3dViewport Class retrieves and sets the properties of viewports.

DirectDraw Class creates Microsoft® DirectDraw® objects and works with system-level variables.

DirectDrawBitmap Class creates and manages bitmaps.

DirectDrawClipper Class manages clip lists.

DirectDrawPalette Class creates Microsoft® DirectDraw® palette objects and works with system-level variables.

DirectDrawSurface Class creates Microsoft® DirectDraw® surface objects and works with system-level variables.

DirectInput Class

DirectPlay2 Class creates Microsoft® DirectPlay®2 objects and works with system-level variables.

DirectPlayLobby Class

DirectSound Class creates DirectSound objects and sets up the environment.

DirectSound3dBuffer Class

DirectSound3dListener Class

DirectSoundBuffer Class creates DirectSoundBuffer objects and sets up the environment.

DirectSoundResource Class loads wave format objects.

DPCaps Class contains the capabilities of a DirectPlay object after a call to the getCaps or getPlayerCaps methods.

DPSessionDesc Class contains a description of the capabilities of an DirectPlay session.

DS3dBuffer Class

DS3dListener Class

DSBCaps Class specifies the capabilities of a DirectSound buffer object, for use by the getCaps method.

DSBufferDesc Class describes the necessary characteristics of a new DirectSoundBuffer object.

DSCaps Class specifies the capabilities of a DirectSound device for use by the getCaps method.

DSCursors Class contains the play and write positions in a DirectSoundBuffer object.

DSResourceDesc Class contains information about a loaded resource.

JoyCaps Class

JoyInfo Class

PaletteEntry Class specifies a color palette entry when creating palettes using the createPalette method.

Rect Class specifies the corners of a rectangle.

WaveFormatEx Class specifies the format of data in a sound buffer.


Interfaces (com.ms.directX Package)

 Microsoft SDK for Java

com.ms.directX Package Interfaces

The com.ms.directX package contains the following interfaces:

DirectXConstants Interface defines all the constants used in DirectX for Java.

Id3dEnumDevicesCallback Interface is used with enumDevices method to set the callback function to be called for each device.

Id3drmCallback Interface is used with Direct3dRMObject.addDestroyCallback and Direct3dRMObject.deleteDestroyCallback to set or remove the callback function to be called when an object is destroyed.

IDeviceUpdateCallback Interface is used with addUpdateCallback and deleteUpdateCallback to set or remove the callback function that is called whenever a device is updated.

IDirect3d Interface

For a description of methods and parameters, see Direct3d.

IDirect3dDevice Interface

For a description of methods and parameters, see Direct3dDevice

IDirect3dExecuteBuffer Interface

For a description of methods and parameters, see Direct3dExecuteBuffer.

IDirect3dLight Interface

For a description of methods and parameters, see Direct3dLight

IDirect3dMaterial Interface

For a description of methods and parameters, see Direct3dMaterial.

IDirect3dRM Interface

For a description of methods and parameters, see Direct3dRM.

IDirect3dRMAnimation Interface

For a description of methods and parameters, see Direct3dRMAnimation.

IDirect3dRMAnimationSet Interface

For a description of methods and parameters, see Direct3dRMAnimationSet.

IDirect3dRMArray Interface

For a description of methods and parameters, see Direct3dRMArray.

IDirect3dRMDevice Interface

For a description of methods and parameters, see Direct3dRMDevice.

IDirect3dRMDeviceArray Interface

For a description of methods and parameters, see Direct3dRMDeviceArray.

IDirect3dRMFace Interface

For a description of methods and parameters, see Direct3dRMFace.

IDirect3dRMFaceArray Interface

For a description of methods and parameters, see Direct3dRMFaceArray.

IDirect3dRMFrame Interface

For a description of methods and parameters, see Direct3dRMFrame.

IDirect3dRMFrameArray Interface

For a description of methods and parameters, see Direct3dRMFrameArray.

IDirect3dRMLight Interface

For a description of methods and parameters, see Direct3dRMLight.

IDirect3dRMLightArray Interface

For a description of methods and parameters, see Direct3dRMLightArray.

IDirect3dRMMaterial Interface

For a description of methods and parameters, see Direct3dRMMaterial.

IDirect3dRMMesh Interface

For a description of methods and parameters, see Direct3dRMMesh.

IDirect3dRMMeshBuilder Interface

For a description of methods and parameters, see Direct3dRMMeshBuilder.

IDirect3dRMObject Interface

For a description of methods and parameters, see Direct3dRMObject.

IDirect3dRMPickArray Interface

For a description of methods and parameters, see Direct3dRMPickArray.

IDirect3dRMTexture Interface

For a description of methods and parameters, see Direct3dRMTexture.

IDirect3dRMUserVisual Interface

For a description of methods and parameters, see Direct3dRMUserVisual.

IDirect3dRMViewport Interface

For a description of methods and parameters, see Direct3dRMViewport.

IDirect3dRMViewportArray Interface

For a description of methods and parameters, see Direct3dRMViewportArray.

IDirect3dRMVisual Interface

For a description of methods and parameters, see Direct3dRMVisual.

IDirect3dRMVisualArray Interface

For a description of methods and parameters, see Direct3dRMVisualArray.

IDirect3dRMWinDevice Interface

For a description of methods and parameters, see Direct3dRMWinDevice.

IDirect3dRMWrap Interface

For a description of methods and parameters, see Direct3dRMWrap.

IDirect3dTexture Interface

For a description of methods and parameters, see Direct3dTexture.

IDirect3dViewport Interface

For a description of methods and parameters, see Direct3dViewport.

IDirectDraw Interface

For a description of methods and parameters, see DirectDraw.

IDirectDrawBitmap Interface

For a description of methods and parameters, see DirectDrawBitmap.

IDirectDrawClipper Interface

For a description of methods and parameters, see DirectDrawClipper.

IDirectDrawPalette Interface

For a description of methods and parameters, see DirectDrawPalette.

IDirectDrawSurface Interface

For a description of methods and parameters, see DirectDrawSurface.

IDirectInput Interface

For a description of methods and parameters, see DirectInput.

IDirectPlay2 Interface

For a description of methods and parameters, see DirectPlay2.

IDirectPlayLobby Interface

For a description of methods and parameters, see DirectPlayLobby.

IDirectSound Interface

For a description of methods and parameters, see DirectSound.

IDirectSound3dBuffer Interface

For a description of methods and parameters, see DirectSound3dBuffer.

IDirectSound3dListener Interface

For a description of methods and parameters, see DirectSound3dListener.

IDirectSoundBuffer Interface

For a description of methods and parameters, see DirectSoundBuffer.

IDirectSoundResource Interface

For a description of methods and parameters, see DirectSoundResource.

IEnumAddressCallback Interface

IEnumAddressTypesCallback Interface

IEnumerateObjectsCallback Interface is used with Direct3dRM.enumerateObjects to set the callback function to be called for each active Direct3dRM object.

IEnumLocalApplicationsCallback Interface

IEnumModesCallback Interface is used with enumDisplayModes to set the callback function to be called for each display mode exposed by the hardware.

IEnumPlayersCallback2 Interface is used with the DirectPlay2.enumGroupPlayers, DirectPlay2.enumGroups, and DirectPlay2.enumPlayers methods to set the callback function to be called for each group or player.

IEnumServiceProvidersCallback Interface is used with the DirectPlay2.enumServiceProviders method to enumerate service providers installed on the system.

IEnumSessionsCallback2 Interface is used with DirectPlay2.enumSessions to set the callback function to be called for each active session.

IEnumSoundDriversCallback Interface

IEnumSurfacesCallback Interface is used with DirectDraw.enumSurfaces and DirectDrawSurface.enumAttachedSurfaces to set the callback function to be called for each specified surface.

IEnumTextureFormatsCallback Interface is used with Direct3dDevice.enumTextureFormats to set the callback function to be called for each texture format for a device.

IEnumZOrdersCallback Interface is used with DirectDrawSurface.enumOverlayZOrders to set the callback function to be called for each overlay on the given surface.

IFrameMoveCallback Interface is used with Direct3dRMFrame.addMoveCallback and Direct3dRMFrame.deleteMoveCallback to set or remove the callback function to be called when a frame is moved.

ILoadCallback Interface is used with Direct3dRM.loadFromFileByPos to set the callback function to be called when an object is loaded.

ILoadTextureCallback Interface is used with methods, such as Direct3dRM.loadFromFileByPos to set the callback function to be called when loading a texture.

IUserVisualCallback Interface is used with Direct3dRM.createUserVisual and Direct3dRMUserVisual.init to set the callback function to be called to render an application-defined visual.


Hierarchy (com.ms.directX Package)

 Microsoft SDK for Java

com.ms.directX Package Hierarchy

The com.ms.directX package has the following hierarchy:

Object
  |
  +--D3dLVertex
  |
  +--D3dDeviceDesc
  |
  +--D3dExecuteBufferDesc
  |
  +--D3dExecuteData
  |
  +--D3dFindDeviceResult
  |
  +--D3dFindDeviceSearch
  |
  +--D3dLightDesc
  |
  +--_Guid
  |
  +--D3dMaterialDesc
  |
  +--D3dMatrix
  |
  +--D3dPickRecord
  |
  +--D3dRect
  |
  +--D3dRMBox
  |
  +--D3dRMImage
  |
  +--D3dRMPickDesc
  |
  +--D3dRMQuaternion
  |
  +--D3dRMVector4d
  |
  +--D3dRMVertex
  |
  +--D3dStats
  |
  +--D3dTLVertex
  |
  +--D3dTriangle
  |
  +--D3dVector
  |
  +--D3dVertex
  |
  +--D3dViewportDesc
  |
  +--DDBltFx
  |
  +--DDCaps
  |
  +--DDCapsFx
  |
  +--DDColorKey
  |
  +--DDPixelFormat
  |
  +--DDSurfaceDesc
  |
  +--DPCaps
  |
  +--DPSessionDesc
  |
  +--DS3dBuffer
  |
  +--DS3dListener
  |
  +--DSBCaps
  |
  +--DSBufferDesc
  |
  +--DSCaps
  |
  +--DSCursors
  |
  +--DSResourceDesc
  |
  +--JoyCaps
  |
  +--JoyInfo
  |
  +--PaletteEntry
  |
  +--Rect
  |
  +--WaveFormatEx
  |
  +--Direct3dRMArray (IDirect3dRMArray)
  |
  +--Direct3dDevice (IDirect3dDevice)
  |
  +--Direct3dExecuteBuffer (IDirect3dExecuteBuffer)
  |
  +--Direct3dLight (IDirect3dLight)
  |
  +--Direct3dMaterial (IDirect3dMaterial)
  |
  +--Direct3dRM (IDirect3dRM)
  |
  +--Direct3dRMAnimation (IDirect3dRMAnimation)
  |
  +--Direct3dRMAnimationSet (IDirect3dRMAnimationSet)
  |
  +--Direct3d (IDirect3d)
  |
  +--Direct3dRMDevice (IDirect3dRMDevice)
  |
  +--Direct3dRMDeviceArray (IDirect3dRMDeviceArray)
  |
  +--Direct3dRMFace (IDirect3dRMFace)
  |
  +--Direct3dRMFaceArray (IDirect3dRMFaceArray)
  |
  +--Direct3dRMFrame (IDirect3dRMFrame)
  |
  +--Direct3dRMFrameArray (IDirect3dRMFrameArray)
  |
  +--Direct3dRMLight (IDirect3dRMLight)
  |
  +--Direct3dRMLightArray (IDirect3dRMLightArray)
  |
  +--Direct3dRMMaterial (IDirect3dRMMaterial)
  |
  +--Direct3dRMMesh (IDirect3dRMMesh)
  |
  +--Direct3dRMMeshBuilder (IDirect3dRMMeshBuilder)
  |
  +--Direct3dRMObject (IDirect3dRMObject)
  |
  +--Direct3dRMPickArray (IDirect3dRMPickArray)
  |
  +--Direct3dRMTexture (IDirect3dRMTexture)
  |
  +--Direct3dRMUserVisual (IDirect3dRMUserVisual)
  |
  +--Direct3dRMViewport (IDirect3dRMViewport)
  |
  +--Direct3dRMViewportArray (IDirect3dRMViewportArray)
  |
  +--Direct3dRMVisual (IDirect3dRMVisual)
  |
  +--Direct3dRMVisualArray (IDirect3dRMVisualArray)
  |
  +--Direct3dRMWinDevice (IDirect3dRMWinDevice)
  |
  +--Direct3dRMWrap (IDirect3dRMWrap)
  |
  +--Direct3dTexture (IDirect3dTexture)
  |
  +--Direct3dViewport (IDirect3dViewport)
  |
  +--DirectDraw (IDirectDraw)
  |
  +--DirectDrawBitmap (IDirectDrawBitmap)
  |
  +--DirectDrawClipper (IDirectDrawClipper)
  |
  +--DirectDrawPalette (IDirectDrawPalette)
  |
  +--DirectDrawSurface (IDirectDrawSurface)
  |
  +--DirectInput (IDirectInput)
  |
  +--DirectPlay2 (IDirectPlay2)
  |
  +--DirectPlayLobby (IDirectPlayLobby)
  |
  +--DirectSound (IDirectSound)
  |
  +--DirectSound3dBuffer (IDirectSound3dBuffer)
  |
  +--DirectSound3dListener (IDirectSound3dListener)
  |
  +--DirectSoundBuffer (IDirectSoundBuffer)
  |
  +--DirectSoundResource (IDirectSoundResource)

IDirect3dRMFace
IDirect3dDevice
IDirect3dExecuteBuffer
IDirect3dLight
IDirect3dMaterial
IDirect3dRM
IDirect3dRMAnimation
IDirect3dRMAnimationSet
IDirect3dRMArray
IDirect3dRMDevice
IDirect3dRMDeviceArray
IDirect3d
IDirect3dRMFaceArray
IDirect3dRMFrame
IDirect3dRMFrameArray
IDirect3dRMLight
IDirect3dRMLightArray
IDirect3dRMMaterial
IDirect3dRMMesh
IDirect3dRMMeshBuilder
IDirect3dRMObject
IDirect3dRMPickArray
IDirect3dRMTexture
IDirect3dRMUserVisual
IDirect3dRMViewport
IDirect3dRMViewportArray
IDirect3dRMVisual
IDirect3dRMVisualArray
IDirect3dRMWinDevice
IDirect3dRMWrap
IDirect3dTexture
IDirect3dViewport
IDirectDraw
IDirectDrawBitmap
IDirectDrawClipper
IDirectDrawPalette
IDirectDrawSurface
IDirectInput
IDirectPlay2
IDirectPlayLobby
IDirectSound
IDirectSound3dBuffer
IDirectSound3dListener
IDirectSoundBuffer
IDirectSoundResource
DirectXConstants
Id3drmCallback
IDeviceUpdateCallback
IEnumAddressCallback
IEnumAddressTypesCallback
Id3dEnumDevicesCallback
IEnumerateObjectsCallback
IEnumLocalApplicationsCallback
IEnumModesCallback
IEnumPlayersCallback2
IEnumServiceProvidersCallback
IEnumSessionsCallback2
IEnumSoundDriversCallback
IEnumSurfacesCallback
IEnumTextureFormatsCallback
IEnumZOrdersCallback
IFrameMoveCallback
ILoadCallback
ILoadTextureCallback
IUserVisualCallback


_Guid Class (com.ms.directX Package)

 Microsoft SDK for Java

_Guid Class

The _Guid Class of the com.ms.directX package specifies a globally unique identifier in the initialize method.

public final class _Guid
{
  // Fields
  public int data1;
  public short data2;
  public short data3;
  public Generic data4;
}


Fields (_Guid Class)

 Microsoft SDK for Java

_Guid Class Fields

The _Guid Class contains the following fields.

data1 | A data member for a globally unique identifier (GUID).
data2 | A data member for a globally unique identifier (GUID).
data3 | A data member for a globally unique identifier (GUID).
data4 | A data member for a globally unique identifier (GUID).


D3dDeviceDesc Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dDeviceDesc Class

The D3dDeviceDesc Class of the com.ms.directX package contains a description of the current device. This class is used to query the current device by such methods as getCaps.

public final class D3dDeviceDesc
{
  // Fields
  public int clipping;
  public int dcmColorModel;
  public int devCaps;
  public int deviceRenderBitDepth;
  public int deviceZBufferBitDepth;
  public int dlcLightingCaps;
  public int dlcLightingModel;
  public int dlcLightingNumber;
  public int dtcTransformCaps;
  public int flags;
  public int maxBufferSize;
  public int maxVertexCount;
}

See Also

Direct3dDevice


Fields (D3dDeviceDesc Class)

 Microsoft SDK for Java

D3dDeviceDesc Class Fields

The D3dDeviceDesc Class contains the following fields.

clipping | TRUE if the device can perform 3D clipping.
dcmColorModel | One value of D3DCOLOR_ type, specifying the color model for the device.
devCaps | One or more values of D3DDEVCAPS_ type, specifying the capabilities of the device.
deviceRenderBitDepth | A value of DDBD_ type (in the range DDBD_8 through DDBD_32), specifying the device's rendering bit-depth.
deviceZBufferBitDepth | A value of DDBD_ type (in the range DDBD_8 through DDBD_32), specifying the device's z-buffer bit-depth.
dlcLightingCaps | A value of D3DLIGHTCAPS_ type, specifying the lighting capabilities of the device.
dlcLightingModel | A value of D3DLIGHTINGMODEL_ type, specifying the lighting capabilities of the device.
dlcLightingNumber | Number of lights that can be handled.
dtcTransformCaps | A value indicating the transformation capabilities of the device. Can be zero or D3DTRANSFORMCAPS_CLIP to specify the system clips while transforming.
flags | One or more values of D3DDD_ type, specifying the fields of this class that contain valid data.
maxBufferSize | Maximum size of the execute buffer for this device. If this field is 0, the application can use any size.
maxVertexCount | Maximum vertex count for this device.


D3dExecuteBufferDesc Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dExecuteBufferDesc Class

The D3dExecuteBufferDesc Class of the com.ms.directX package describes the execute buffer for such methods as createExecuteBuffer and lock.

public final class D3dExecuteBufferDesc
{
  // Fields
  public int bufferSize;
  public int caps;
  public int flags;
}

See Also

Direct3dDevice, Direct3dExecuteBuffer


Fields (D3dExecuteBufferDesc Class)

 Microsoft SDK for Java

D3dExecuteBufferDesc Class Fields

The D3dExecuteBufferDesc Class contains the following fields.

bufferSize | Size of the execute buffer, in bytes.
caps | A value of D3DDEBCAPS_ type, specifying the location in memory of the execute buffer.
flags | One or more values of D3DDEB_ type, identifying the fields of this class that contain valid data.


D3dExecuteData Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dExecuteData Class

The D3dExecuteData Class of the com.ms.directX package specifies data for the execute method. When this method is called and the transformation has been done, the instruction list starting at the value specified in the instructionOffset field is parsed and rendered.

public final class D3dExecuteData
{
  // Fields
  public int flags;
  public int homogenousVertexOffset;
  public int instructionLength;
  public int instructionOffset;
  public int status;
  public int vertexCount;
  public int vertexOffset;
  public int x1;
  public int x2;
  public int y1;
  public int y2;
}

See Also

Direct3dDevice.


Fields (D3dExecuteData Class)

 Microsoft SDK for Java

D3dExecuteData Class Fields

The D3dExecuteData Class contains the following fields.

flags |
homogenousVertexOffset | Offset into the list of vertices for the homogeneous vertex used when the application is supplying screen coordinate data that needs clipping.
instructionLength | Length of the instructions to execute.
instructionOffset | Offset into the list of instructions to execute.
status | Value storing the screen extent of the rendered geometry for use after the transformation is complete.
vertexCount | Number of vertices to execute.
vertexOffset | Offset into the list of vertices.
x1 |
x2
y1
y2


D3dFindDeviceResult Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dFindDeviceResult Class

The D3dFindDeviceResult Class of the com.ms.directX package contains a description of the current device. This class is used to query the current device by such methods as Direct3dDevice.getCaps and Direct3d.findDevice.

public final class D3dFindDeviceResult
{
  // Fields
  public int clipping;
  public int dcmColorModel;
  public int devCaps;
  public int deviceRenderBitDepth;
  public int deviceZBufferBitDepth;
  public int dlcLightingCaps;
  public int dlcLightingModel;
  public int dlcLightingNumber;
  public int dtcTransformCaps;
  public int flags;
  public int lineAlphaCmpCaps;
  public int lineDestBlendCaps;
  public int lineMiscCaps;
  public int lineRasterCaps;
  public int lineShadeCaps;
  public int lineSrcBlendCaps;
  public int lineStippleHeight;
  public int lineStippleWidth;
  public int lineTextureAddressCaps;
  public int lineTextureBlendCaps;
  public int lineTextureCaps;
  public int lineTextureFilterCaps;
  public int lineZCmpCaps;
  public int maxBufferSize;
  public int maxVertexCount;
  public int triAlphaCmpCaps;
  public int triDestBlendCaps;
  public int triMiscCaps;
  public int triRasterCaps;
  public int triShadeCaps;
  public int triSrcBlendCaps;
  public int triStippleHeight;
  public int triStippleWidth;
  public int triTextureAddressCaps;
  public int triTextureBlendCaps;
  public int triTextureCaps;
  public int triTextureFilterCaps;
  public int triZCmpCaps;

  // Methods
  public _Guid GetGuid();
}


Methods (D3dFindDeviceResult Class)

 Microsoft SDK for Java

D3dFindDeviceResult Class Methods

The D3dFindDeviceResult Class contains the following method:

GetGuid retrieves the globally unique identifier (GUID) for the device.


GetGuid (D3dFindDeviceResult Class)

 Microsoft SDK for Java

GetGuid

This method of the D3dFindDeviceResult Class retrieves the globally unique identifier (GUID) for the device.

Syntax

public _Guid GetGuid();

Return Value

Returns the globally unique identifier.


Fields (D3dFindDeviceResult Class)

 Microsoft SDK for Java

D3dFindDeviceResult Class Fields

The D3dFindDeviceResult Class contains the following fields.

clipping | TRUE if the hardware device can perform 3D clipping.
dcmColorModel | One value of D3DCOLOR_ type, specifying the color model for the hardware device.
devCaps | One or more flags of D3DDEVCAPS_ type, specifying the capabilities of the hardware device.
deviceRenderBitDepth | The device's rendering bit depth. This can be one or more of the following DirectDraw bit depth constants: DDBD_8, DDBD_16, DDBD_24, or DDBD_32.
deviceZBufferBitDepth | The device's z-buffer bit depth. This can be one or more of the following DirectDraw bit depth constants: DDBD_8, DDBD_16, DDBD_24, or DDBD_32.
dlcLightingCaps | A value of D3DLIGHTCAPS_ type, specifying the lighting capabilities of the hardware device.
dlcLightingModel | A value of D3DLIGHTINGMODEL_ type, specifying the lighting capabilities of the hardware device.
dlcLightingNumber | Number of lights that can be handled.
dtcTransformCaps | A value indicating the transformation capabilities of the hardware device. Can be zero or D3DTRANSFORMCAPS_CLIP to specify the system clips while transforming.
flags | Flags identifying the members of this class that contain valid data. These flags are D3DDD_ constants.
lineAlphaCmpCaps | Alpha-test comparison functions that a driver can perform. This member can be any of the combinations valid for lineZCmpCaps.
lineDestBlendCaps | Destination blending capabilities. This member can be any of the combinations valid for lineSrcBlendCaps.
lineMiscCaps | The general capabilities for this primitive. This can be one or more of the D3DPMISCCAPS_ types.
lineRasterCaps | Information on raster-drawing capabilities. This can be one or more of the D3DPRASTERCAPS_ types.
lineShadeCaps | Shading operations that the device can perform. It is assumed, in general, that if a device supports a given command (such as D3DOP_TRIANGLE) at all, it supports the D3DSHADE_FLAT mode (as specified in D3DSHADEMODE). This flag specifies whether the driver can also support Gouraud and Phong shading and whether alpha color components are supported for each of the three color-generation modes. When alpha components are not supported in a given mode, the alpha value of colors generated in that mode is implicitly 255. This is the maximum possible alpha (that is, the alpha component is at full intensity).The color, specular highlights, fog, and alpha interpolants of a triangle each have capability flags that an application can use to find out how they are implemented by the device driver. These are modified by the shade mode, color model, and by whether the alpha component of a color is blended or stippled. This member can be one or more of D3DPSHADECAPS_ types.
lineSrcBlendCaps | Source blending capabilities. This member can be one or more of the D3DPBLENDCAPS_ types.
lineStippleHeight | The maximum height of the supported stipple (up to 32-by-32).
lineStippleWidth | The maximum width of the supported stipple (up to 32-by-32).
lineTextureAddressCaps | Texture-addressing capabilities. This member can be one or more of the D3DPTADDRESSCAPS_ types.
lineTextureBlendCaps | Texture-blending capabilities. This member can be one or more of the D3DPTBLENDCAPS_ types.
lineTextureCaps | Miscellaneous texture-mapping capabilities. This member can be one or more of the D3DPTEXTURECAPS_ types.
lineTextureFilterCaps | Texture-mapping capabilities. This member can be one or more of the D3DPTFILTERCAPS_ types.
lineZCmpCaps | The z-buffer comparison functions that a driver can perform. This member can be one or more of the D3DPCMPCAPS_ types.
maxBufferSize | The maximum size of the execute buffer for this device. If this member is 0, the application can use any size buffer.
maxVertexCount | The maximum vertex count for the device.
triAlphaCmpCaps | Alpha-test comparison functions that a driver can perform. This member can be any of the combinations valid for lineZCmpCaps.
triDestBlendCaps | Destination blending capabilities. This member can be any of the combinations valid for triSrcBlendCaps.
triMiscCaps | The general capabilities for this primitive. This member can be one or more of the D3DPMISCCAPS_ types.
triRasterCaps | Information on raster-drawing capabilities. This can be one or more of the D3DPRASTERCAPS_ types.
triShadeCaps | Shading operations that the device can perform. It is assumed, in general, that if a device supports a given command (such as D3DOP_TRIANGLE) at all, it supports the D3DSHADE_FLAT mode (as specified in D3DSHADEMODE). This flag specifies whether the driver can also support Gouraud and Phong shading and whether alpha color components are supported for each of the three color-generation modes. When alpha components are not supported in a given mode, the alpha value of colors generated in that mode is implicitly 255. This is the maximum possible alpha (that is, the alpha component is at full intensity).The color, specular highlights, fog, and alpha interpolants of a triangle each have capability flags that an application can use to find out how they are implemented by the device driver. These are modified by the shade mode, color model, and by whether the alpha component of a color is blended or stippled. This member can be one or more of D3DPSHADECAPS_ types.
triSrcBlendCaps | Source blending capabilities. This member can be one or more of the D3DPBLENDCAPS_ types.
triStippleHeight | The maximum width and height of the supported stipple (up to 32-by-32).
triStippleWidth |
triTextureAddressCaps | Texture-addressing capabilities. This member can be one or more of the D3DPTADDRESSCAPS_ types.
triTextureBlendCaps | Texture-blending capabilities. This member can be one or more of the D3DPTBLENDCAPS_ types.
triTextureCaps | Miscellaneous texture-mapping capabilities. This member can be one or more of the D3DPTEXTURECAPS_ types.
triTextureFilterCaps | Texture-mapping capabilities. This member can be one or more of the D3DPTFILTERCAPS_ types.
triZCmpCaps | The z-buffer comparison functions that a driver can perform. This member can be one or more of the D3DPCMPCAPS_ types.


D3dFindDeviceSearch Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dFindDeviceSearch Class

The D3dFindDeviceSearch Class of the com.ms.directX package contains a description of a device to search for.

public final class D3dFindDeviceSearch
{
  // Fields
  public int alphaCmpCaps;
  public int caps;
  public int dcmColorModel;
  public int destBlendCaps;
  public int flags;
  public int hardware;
  public int miscCaps;
  public int rasterCaps;
  public int shadeCaps;
  public int srcBlendCaps;
  public int stippleHeight;
  public int stippleWidth;
  public int textureAddressCaps;
  public int textureBlendCaps;
  public int textureCaps;
  public int textureFilterCaps;
  public int zCmpCaps;

  // Methods
  public _Guid getGuid();
  public void setGuid(_Guid g);
}

See Also

com.ms.directX.D3dFindDeviceResult


Methods (D3dFindDeviceSearch Class)

 Microsoft SDK for Java

D3dFindDeviceSearch Class Methods

The D3dFindDeviceSearch Class contains the following methods:

getGuid retrieves the globally unique identifier (GUID) for the device.
setGuid is currently not implemented.


getGuid (D3dFindDeviceSearch Class)

 Microsoft SDK for Java

getGuid

This method of the D3dFindDeviceSearch Class retrieves the globally unique identifier (GUID) for the device.

Syntax

public _Guid getGuid();

Return Value

Returns the globally unique identifier.


setGuid (D3dFindDeviceSearch Class)

 Microsoft SDK for Java

setGuid

This method of the D3dFindDeviceSearch Class is currently not implemented.

Syntax

public void setGuid(_Guid g);

Parameters

_Guid The globally unique identifier.


Fields (D3dFindDeviceSearch Class)

 Microsoft SDK for Java

D3dFindDeviceSearch Class Fields

The D3dFindDeviceSearch Class contains the following fields.

alphaCmpCaps | One or more values of D3DPCMPCAPS_ type, specifying the alpha-test comparison functions that the driver can perform.
caps | One or more flags of D3DDEVCAPS_ type, specifying the capabilities of the device.
dcmColorModel | One value of D3DCOLOR_ type, specifying whether the device to find should use the ramp or RGB color model.
destBlendCaps | One or more values of D3DPBLENDCAPS_ type, specifying the destination blending capabilities.
flags | One or more values of D3DFDS_ type, defining the type of device the application wants to find.
hardware | Flag specifying whether the device to find is implemented as hardware or software. If this member is true, the device to search for has hardware rasterization and can also provide other hardware acceleration. Applications that use this flag should set the D3DFDS_HARDWARE bit in the flags field.
miscCaps | One or more values of D3DPMISCCAPS_ type, specifying the general capabilities for primitives.
rasterCaps | One or more values of D3DPRASTERCAPS_ type, specifying information on raster-drawing capabilities.
shadeCaps | One or more values of D3DPSHADECAPS_ type, specifying the shading operations that the device can perform.It is assumed, in general, that if a device supports a given command (such as D3DOP_TRIANGLE) at all, it supports the D3DSHADE_FLAT mode. This flag specifies whether the driver can also support Gouraud and Phong shading and whether alpha color components are supported for each of the three color-generation modes. When alpha components are not supported in a given mode, the alpha value of colors generated in that mode is implicitly 255. This is the maximum possible alpha (that is, the alpha component is at full intensity). The color, specular highlights, fog, and alpha interpolants of a triangle each have capability flags that an application can use to find out how they are implemented by the device driver. These are modified by the shade mode, color model, and by whether the alpha component of a color is blended or stippled.
srcBlendCaps | One or more values of D3DPBLENDCAPS_ type, specifying the source blending capabilities.
stippleHeight | Maximum height of the supported stipple (up to 32).
stippleWidth | Maximum width of the supported stipple (up to 32).
textureAddressCaps | One or more values of D3DPTADDRESSCAPS_ type, specifying texture-addressing capabilities.
textureBlendCaps | One or more values of D3DPTBLENDCAPS_ type, specifying texture-blending capabilities.
textureCaps | One or more values of D3DPTEXTURECAPS_ type, specifying miscellaneous texture-mapping capabilities.
textureFilterCaps | One or more values of D3DPTFILTERCAPS_ type, specifying texture-mapping capabilities.
zCmpCaps | One or more values of D3DPCMPCAPS_ type, specifying the z-buffer comparison functions that the driver can perform.


D3dLightDesc Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dLightDesc Class

The D3dLightDesc Class of the com.ms.directX package defines the light type in calls to methods such as setLight and getLight.

public final class D3dLightDesc
{
  // Fields
  public float attenuation0;
  public float attenuation1;
  public float attenuation2;
  public float colorA;
  public float colorB;
  public float colorG;
  public float colorR;
  public float directionx;
  public float directiony;
  public float directionz;
  public int dltType;
  public float falloff;
  public float phi;
  public float positionx;
  public float positiony;
  public float positionz;
  public float range;
  public float theta;
}


Fields (D3dLightDesc Class)

 Microsoft SDK for Java

D3dLightDesc Class Fields

The D3dLightDesc Class contains the following fields.

attenuation0 | Constant light intensity. Specifies a light level that does not decrease between the light and the cutoff point given by the range field.
attenuation1 | Light intensity that decreases linearly. The light intensity is 50 percent of this value halfway between the light and the cutoff point given by the range field.
attenuation2 | Light intensity that decreases according to a quadratic attenuation factor.
colorA | The alpha element of the color of the light.
colorB | The blue element of the color of the light.
colorG | The green element of the color of the light.
colorR | The red element of the color of the light.
directionx | The x axis element of the direction of the light in world space.
directiony | The y axis element of the direction of the light in world space.
directionz | The z axis element of the direction of the light in world space.
dltType | Type of the light source. This is one value of light type.
falloff | Decrease in illumination between the umbra (the angle specified by the theta field) and the outer edge of the penumbra (the angle specified by the phi field).
phi | Angle, in radians, defining the outer edge of the spotlight's penumbra. Points outside this cone are not lit by the spotlight.
positionx | The x axis element of the position of the light in world space.
positiony | The y axis element of the position of the light in world space.
positionz | The z axis element of the position of the light in world space.
range | Distance beyond which the light has no effect.
theta | Angle, in radians, of the spotlight's umbra—that is, the fully illuminated spotlight cone.


D3dLVertex Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dLVertex Class

The D3dLVertex Class of the com.ms.directX package defines an untransformed and lit vertex (screen coordinates with color).

public final class D3dLVertex
{
  // Fields
  public int color;
  public int specular;
  public float tu;
  public float tv;
  public float x;
  public float y;
  public float z;

  // Constructors
  public D3dLVertex();
  public D3dLVertex(float x, float y, float z, int color,
        int specular, float tu, float tv);
}


Constructors (D3dLVertex Class)

 Microsoft SDK for Java

D3dLVertex Class Constructors

The D3dLVertex Class contains the following constructors:

D3dLVertex()
D3dLVertex(float x, float y, float z, int color, int specular, float tu, float tv)

D3dLVertex()

Creates a D3dLVertex object with fields uninitialized.

Syntax

public D3dLVertex();

D3dLVertex(float x, float y, float z, int color, int specular, float tu, float tv)

Creates a D3dLVertex object with fields set to values specified by the user.

Syntax

public D3dLVertex(float x, float y, float z, int color, int specular, float tu, float tv);

Parameters

x | A float value that initializes the x field.
y | A float value that initializes the y field.
z | A float value that initializes the z field.
color | An int value that initializes the color field.
specular | An int value that initializes the specular field.
tu | A float value that initializes the tu field.
tv | A float value that initializes the tv field.


Fields (D3dLVertex Class)

 Microsoft SDK for Java

D3dLVertex Class Fields

The D3dLVertex Class contains the following fields.

color | Value describing the color component of the vertex.
specular | Value describing the specular component of the vertex.
tu | Value describing the texture coordinates of the vertex.
tv | Value describing the texture coordinates of the vertex.
x | The x screen coordinate of the vertex.
y | The y screen coordinate of the vertex.
z | The z screen coordinate of the vertex.


D3dMaterialDesc Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dMaterialDesc Class

The D3dMaterialDesc Class of the com.ms.directX package specifies material properties in calls to the getMaterial and setMaterial methods.

public final class D3dMaterialDesc
{
  // Fields
  public float ambientA;
  public float ambientB;
  public float ambientG;
  public float ambientR;
  public float diffuseA;
  public float diffuseB;
  public float diffuseG;
  public float diffuseR;
  public float dvPower;
  public float emissiveA;
  public float emissiveB;
  public float emissiveG;
  public float emissiveR;
  public float power;
  public int rampSize;
  public float specularA;
  public float specularB;
  public float specularG;
  public float specularR;
  public int textureHandle;
}

See Also

Direct3dMaterial


Fields (D3dMaterialDesc Class)

 Microsoft SDK for Java

D3dMaterialDesc Class Fields

The D3dMaterialDesc Class contains the following fields.

ambientA | The alpha element of the material's ambient color.
ambientB | The blue element of the material's ambient color.
ambientG | The green element of the material's ambient color.
ambientR | The red element of the material's ambient color.
diffuseA | The alpha element of the material's diffuse color.
diffuseB | The blue element of the material's diffuse color.
diffuseG | The green element of the material's diffuse color.
diffuseR | The red element of the material's diffuse color.
dvPower | The sharpness of specular highlights.
emissiveA | The alpha element of the material's emissive color.
emissiveB | The blue element of the material's emissive color.
emissiveG | The green element of the material's emissive color.
emissiveR | The red element of the material's emissive color.
power | Value specifying the sharpness of specular highlights.
rampSize | Size of the color ramp. For the monochromatic (ramp) driver, this value must be less than or equal to 1 for materials assigned to the background; otherwise, the background is not displayed. This behavior also occurs when a texture that is assigned to the background has an associated material whose rampSize field is greater than 1.
specularA | The alpha element of the material's specular color.
specularB | The blue element of the material's specular color.
specularG | The green element of the material's specular color.
specularR | The red element of the material's specular color.
textureHandle | The handle of the texture map.


D3dMatrix Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dMatrix Class

The D3dMatrix Class of the com.ms.directX package describes a matrix for such methods as Direct3dDevice.getMatrix and Direct3dDevice.setMatrix.

public final class D3dMatrix
{
  // Fields
  public float _11;
  public float _12;
  public float _13;
  public float _14;
  public float _21;
  public float _22;
  public float _23;
  public float _24;
  public float _31;
  public float _32;
  public float _33;
  public float _34;
  public float _41;
  public float _42;
  public float _43;
  public float _44;

  // Constructors
  public D3dMatrix(float _11, float _12, float _13, float _14,
        float _21, float _22, float _23, float _24, float _31,
        float _32, float _33, float _34, float _41, float _42,
        float _43, float _44);
}

In Direct3D, the _44 element of a projection matrix cannot be a negative number. If your application needs to use a negative value in this location, it should scale the entire projection matrix by -1, instead.

See Also

Direct3dDevice


Constructors (D3dMatrix Class)

 Microsoft SDK for Java

D3dMatrix Class Constructors

The D3dMatrix Class contains the following constructor:

D3dMatrix(float _11, float _12, float _13, float _14, float _21, float _22, float _23, float _24, float _31, float _32, float _33, float _34, float _41, float _42, float _43, float _44)

Creates a D3dMatrix object with members set to values specified by the user.

Syntax

public D3dMatrix(float _11, float _12, float _13, float _14, float _21, float _22, float _23, float _24, float _31, float _32, float _33, float _34, float _41, float _42, float _43, float _44);


Fields (D3dMatrix Class)

 Microsoft SDK for Java

D3dMatrix Class Fields

The D3dMatrix Class contains the following fields.

_11 | Floating point type used in the matrix.
_12 | Floating point type used in the matrix.
_13 | Floating point type used in the matrix.
_14 | Floating point type used in the matrix.
_21 | Floating point type used in the matrix.
_22 | Floating point type used in the matrix.
_23 | Floating point type used in the matrix.
_24 | Floating point type used in the matrix.
_31 | Floating point type used in the matrix.
_32 | Floating point type used in the matrix.
_33 | Floating point type used in the matrix.
_34 | Floating point type used in the matrix.
_41 | Floating point type used in the matrix.
_42 | Floating point type used in the matrix.
_43 | Floating point type used in the matrix.
_44 | Floating point type used in the matrix.


D3dPickRecord Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dPickRecord Class

The D3dPickRecord Class of the com.ms.directX package returns information about picked primitives in an execute buffer for the getPickRecords method.

public final class D3dPickRecord
{
  // Fields
  public int offset;
  public byte opcode;
  public byte pad;
  public float z;
}

See Also

Direct3dDevice.


Fields (D3dPickRecord Class)

 Microsoft SDK for Java

D3dPickRecord Class Fields

The D3dPickRecord Class contains the following fields.

offset | Offset from the start of the execute buffer in which the picked primitive was found.
opcode | Opcode of the picked primitive.
pad | Pad byte.
z | Depth of the picked primitive.


D3dRect Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dRect Class

The D3dRect class of the com.ms.directX package is a rectangle definition.

public final class D3dRect
{
  // Fields
  public int x1;
  public int x2;
  public int y1;
  public int y2;
}

See Also

Direct3dDevice, Direct3dViewport.


Fields (D3dRect Class)

 Microsoft SDK for Java

D3dRect Class Fields

The D3dRect Class contains the following fields.

x1 | The x-coordinate of the upper-left corner of the rectangle.
x2 | The x-coordinate of the lower-right corner of the rectangle.
y1 | The y-coordinate of the upper-left corner of the rectangle.
y2 | The y-coordinate of the lower-right corner of the rectangle.


D3dRMBox Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dRMBox Class

The D3dRMBox Class of the com.ms.directX package defines the bounding box retrieved by the Direct3dRMMesh.getBox and Direct3dRMMeshBuilder.getBox methods.

public final class D3dRMBox
{
  // Fields
  public float xMax;
  public float xMin;
  public float yMax;
  public float yMin;
  public float zMax;
  public float zMin;
}


Fields (D3dRMBox Class)

 Microsoft SDK for Java

D3dRMBox Class Fields

The D3dRMBox Class contains the following fields.

xMax | Value defining the x-coordinate of the box's maximum bounds.
xMin | Value defining the x-coordinate of the box's minimum bounds.
yMax | Value defining the y-coordinate of the box's maximum bounds.
yMin | Value defining the y-coordinate of the box's minimum bounds.
zMax | Value defining the z coordinate of the box's maximum bounds.
zMin | Value defining the z coordinate of the box's minimum bounds.


D3dRMImage Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dRMImage Class

The D3dRMImage Class of the com.ms.directX package describes an image that is attached to a texture by the Direct3dRM.createTexture method. The Direct3dRMTexture.getImage method returns this image.

public final class D3dRMImage
{
  // Fields
  public int alpha_mask;
  public int aspectX;
  public int aspectY;
  public int blue_mask;
  public int bytes_per_line;
  public int depth;
  public int green_mask;
  public int height;
  public int palette_size;
  public int red_mask;
  public int rgb;
  public int width;
}

See Also

Direct3dRM, Direct3dRMTexture.


Fields (D3dRMImage Class)

 Microsoft SDK for Java

D3dRMImage Class Fields

The D3dRMImage Class contains the following fields.

alpha_mask | If rgb is true, these fields are masks for the red, green, and blue parts of a pixel. Otherwise, they are masks for the significant bits of the red, green, and blue elements in the palette. For example, most SVGA displays use 64 intensities of red, green, and blue, so the masks should all be set to 0xfc.
aspectX | X aspect ratio for nonsquare pixels.
aspectY | Y aspect ratio for nonsquare pixels.
blue_mask | Bitmask dependant on rgb.
bytes_per_line | Number of bytes of memory for a scanline. This value must be a multiple of four.
depth | Bits per pixel.
green_mask | Bitmask dependant on rgb.
height | Height of the image, in pixels.
palette_size | Number of entries in the palette.
red_mask | Bitmask dependant on rgb.
rgb | If this field false, pixels are indices into a palette. Otherwise, pixels encode RGB values.
width | Width of the image, in pixels.


D3dRMPickDesc Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dRMPickDesc Class

The D3dRMPickDesc Class of the com.ms.directX package contains the pick position and face and group identifiers of the objects retrieved by the getPick method.

public final class D3dRMPickDesc
{
  // Fields
  public int faceIdx;
  public int groupIdx;
  public float x;
  public float y;
  public float z;
}

See Also

Direct3dRMPickedArray


Fields (D3dRMPickDesc Class)

 Microsoft SDK for Java

D3dRMPickDesc Class Fields

The D3dRMPickDesc Class contains the following fields.

faceIdx | Face index of the retrieved object.
groupIdx | Group index of the retrieved object.
x | Value describing the x-coordinate of the retrieved object's position.
y | Value describing the y-coordinate of the retrieved object's position.
z | Value describing the z coordinate of the retrieved object's position.


D3dRMQuaternion Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dRMQuaternion Class

The D3dRMQuaternion Class of the com.ms.directX package describes the rotation used by the addRotateKey method. It is also used in several of Direct3D's mathematical functions. Quaternions are an alternative to the matrix methods that are typically used for 3D rotations.

public final class D3dRMQuaternion
{
  // Fields
  public float s;
  public float x;
  public float y;
  public float z;
}

See Also

Direct3dRMAnimation


Fields (D3dRMQuaternion Class)

 Microsoft SDK for Java

D3dRMQuaternion Class Fields

The D3dRMQuaternion Class contains the following fields.

s | A fourth element added to the x, y and z values that define a vector.
x | The x component of the vector.
y | The y component of the vector.
z | The z component of the vector.


D3dRMVector4d Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dRMVector4d Class

The D3dRMVector4d Class of the com.ms.directX package describes the screen coordinates used as the destination of a transformation by the transform method and as the source of a transformation by the inverseTransform method.

public final class D3dRMVector4d
{
  // Fields
  public float w;
  public float x;
  public float y;
  public float z;
}

See Also

Direct3dRMViewport


Fields (D3dRMVector4d Class)

 Microsoft SDK for Java

D3dRMVector4d Class Fields

The D3dRMVector4d Class contains the following fields.

w | Homogenous w.
x | The x screen coordinate of the vector.
y | The y screen coordinate of the vector.
z | The z screen coordinate of the vector.


D3dRMVertex Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dRMVertex Class

The D3dRMVertex Class of the com.ms.directX package defines an untransformed and unlit vertex (model coordinates with normal direction vector).

public final class D3dRMVertex
{
  // Fields
  public int color;
  public float nx;
  public float ny;
  public float nz;
  public float tu;
  public float tv;
  public float x;
  public float y;
  public float z;
}


Fields (D3dRMVertex Class)

 Microsoft SDK for Java

D3dRMVertex Class Fields

The D3dRMVertex Class contains the following fields.

color | Vertex color.
nx | Value describing the normal x-coordinate of the vertex.
ny | Value describing the normal y-coordinate of the vertex.
nz | Value describing the normal z coordinate of the vertex.
tu | Value describing the texture u coordinate of the vertex.
tv | Value describing the texture v coordinate of the vertex.
x | Value describing the homogeneous x-coordinate of the vertex.
y | Value describing the homogeneous y-coordinate of the vertex.
z | Value describing the homogeneous z coordinate of the vertex.


D3dStats Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dStats Class

The D3dStats Class of the com.ms.directX package contains statistics used by the getStats method.

public final class D3dStats
{
  // Fields
  public int linesDrawn;
  public int pointsDrawn;
  public int spansDrawn;
  public int trianglesDrawn;
  public int verticesProcessed;
}

See Also

Direct3dDevice


Fields (D3dStats Class)

 Microsoft SDK for Java

D3dStats Class Fields

The D3dStats Class contains the following fields.

linesDrawn | Number of lines drawn since the device was created.
pointsDrawn | Number of points drawn since the device was created.
spansDrawn | Number of spans drawn since the device was created.
trianglesDrawn | Number of triangles drawn since the device was created.
verticesProcessed | Number of vertices processed since the device was created.


D3dTLVertex Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dTLVertex Class

The D3dTLVertex Class of the com.ms.directX package defines a transformed and lit vertex (screen coordinates with color).

public final class D3dTLVertex
{
  // Fields
  public int color;
  public float rhw;
  public int specular;
  public float sx;
  public float sy;
  public float sz;
  public float tu;
  public float tv;

  // Constructors
  public D3dTLVertex();
  public D3dTLVertex(float sx, float sy, float sz, float rhw,
        int color, int specular float tu, float tv);
}


Constructors (D3dTLVertex Class)

 Microsoft SDK for Java

D3dTLVertex Class Constructors

The D3dTLVertex Class contains the following constructors:

D3dTLVertex()
D3dTLVertex(float sx, float sy, float sz, float rhw, int color, int specular float tu, float tv)

D3dTLVertex()

Creates a D3dTLVertex object with uninitialized fields.

Syntax

public D3dTLVertex();

D3dTLVertex(float sx, float sy, float sz, float rhw, int color, int specular float tu, float tv)

Creates a D3dTLVertex object with fields set to values specified by the user.

Syntax

public D3dTLVertex(float sx, float sy, float sz, float rhw, int color, int specular float tu, float tv);

Parameters

sx | A float that initializes the sx field.
sy | A float that initializes the sy field.
sz | A float that initializes the sz field.
rhw | A float that initializes the rhw field.
color | An int that initializes the color field.
specular | An int that initializes the specular field.
tu | A float that initializes the tu field.
tv | A float that initializes the tv field.


Fields (D3dTLVertex Class)

 Microsoft SDK for Java

D3dTLVertex Class Fields

The D3dTLVertex Class contains the following fields.

color | Value describing the color component of the vertex.
rhw | The value that is the reciprocal of homogenous w. This value is 1 divided by the distance from the origin to the object along the z-axis.
specular | Value describing the specular component of the vertex.
sx | The x screen coordinate of the vertex.
sy | The y screen coordinate of the vertex.
sz | The z screen coordinate of the vertex.
tu | Value describing the texture u-coordinate of the vertex.
tv | Value describing the texture v-coordinate of the vertex.


D3dTriangle Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dTriangle Class

The D3dTriangle Class of the com.ms.directX package describes a base type for all triangles. The triangle is the main rendering primitive.

public final class D3dTriangle
{
  // Fields
  public char flags;
  public char v1;
  public char v2;
  public char v3;

  // Constructors
  public D3dTriangle(int v1, int v2, int v3, short flags);
  public D3dTriangle(short v1, short v2, short v3, short flags);
}


Constructors (D3dTriangle Class)

 Microsoft SDK for Java

D3dTriangle Class Constructors

The D3dTriangle Class contains the following constructors:

D3dTriangle(int v1, int v2, int v3, short flags)
D3dTriangle(short v1, short v2, short v3, short flags)

D3dTriangle(int v1, int v2, int v3, short flags)

Creates a D3dTriangle object with the members passed as ints and a short (flags) cast to chars.

Syntax

public D3dTriangle(int v1, int v2, int v3, short flags);

Parameters

v1 | The v1 field cast as an int.
v2 | The v2 field cast as an int.
v3 | The v3 field cast as an int.
flags | The flags field cast as a short.

D3dTriangle(short v1, short v2, short v3, short flags)

Creates a D3dTriangle object with the members passed as shorts cast to chars.

Syntax

public D3dTriangle(short v1, short v2, short v3, short flags);

Parameters

v1 | The v1 field cast as a short.
v2 | The v2 field cast as a short.
v3 | The v3 field cast as a short.
flags | The flags field cast as a short.


Fields (D3dTriangle Class)

 Microsoft SDK for Java

D3dTriangle Class Fields

The D3dTriangle Class contains the following fields.

flags Flags describing which edges of the triangle to enable (this information is useful only in wire-frame mode). This value can be a combination of the following edge and strip flags:

Edge Flags
D3DTRIFLAG_EDGEENABLE1

Edge defined by v1-v2.

D3DTRIFLAG_EDGEENABLE2

Edge defined by v2-v3.

D3DTRIFLAG_EDGEENABLE3

Edge defined by v3-v1.

D3DTRIFLAG_EDGEENABLETRIANGLE

All edges.

Strip and Fan Flags
D3DTRIFLAG_EVEN

The v1-v2 edge of the current triangle is adjacent to the v3-v1 edge of the previous triangle; that is, v1 is the previous v1, and v2 is the previous v3.

D3DTRIFLAG_ODD

The v1-v2 edge of the current triangle is adjacent to the v2-v3 edge of the previous triangle; that is, v1 is the previous v3, and v2 is the previous v2.

D3DTRIFLAG_START

Begin the strip or fan, loading all three vertices.

D3DTRIFLAG_STARTFLAT(len)

If this triangle is culled, also cull the specified number of subsequent triangles. This length must be greater than zero and less than 30.
v1 | Vertex describing the triangle.
v2 | Vertex describing the triangle.
v3 | Vertex describing the triangle.


D3dVector Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dVector Class

The D3dVector Class of the com.ms.directX package defines a vector for many Direct3D and Direct3DRM methods and classes.

public final class D3dVector
{
  // Fields
  public float x;
  public float y;
  public float z;
}


Fields (D3dVector Class)

 Microsoft SDK for Java

D3dVector Class Fields

The D3dVector Class contains the following fields.

x | The x component of the vector.
y | The y component of the vector.
z | The z component of the vector.


D3dVertex Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dVertex Class

The D3dVertex Class of the com.ms.directX package defines an untransformed and unlit vertex (screen coordinates with color).

public final class D3dVertex
{
  // Fields
  public float nx;
  public float ny;
  public float nz;
  public float tu;
  public float tv;
  public float x;
  public float y;
  public float z;

  // Constructors
  public D3dVertex();
  public D3dVertex(float x, float y, float z, float nx, float ny,
        float nz, float tu, float tv);
}


Constructors (D3dVertex Class)

 Microsoft SDK for Java

D3dVertex Class Constructors

The D3dVertex Class contains the following constructors:

D3dVertex()
D3dVertex(float x, float y, float z, float nx, float ny, float nz, float tu, float tv)

D3dVertex()

Creates a D3dVertex object with fields uninitialized.

Syntax

public D3dVertex();

D3dVertex(float x, float y, float z, float nx, float ny, float nz, float tu, float tv)

Creates a D3dVertex object with fields set to values specified by the user.

Syntax

public D3dVertex(float x, float y, float z, float nx, float ny, float nz, float tu, float tv);

Parameters

x | A floating point value that sets the x field.
y | A floating point value that sets the y field.
x | A floating point value that sets the z field.
nx | A floating point value that sets the nx field.
ny | A floating point value that sets the ny field.
nz | A floating point value that sets the nz field.
tu | A floating point value that sets the tu field.
tv | A floating point value that sets the tv field.


Fields (D3dVertex Class)

 Microsoft SDK for Java

D3dVertex Class Fields

The D3dVertex Class contains the following fields.

nx | Value describing the normal x-coordinate of the vertex.
ny | Value describing the normal y-coordinate of the vertex.
nz | Value describing the normal z coordinate of the vertex.
tu | Value describing the texture u coordinate of the vertex.
tv | Value describing the texture v coordinate of the vertex.
x | Value describing the homogeneous x-coordinate of the vertex.
y | Value describing the homogeneous y-coordinate of the vertex.
z | Value describing the homogeneous z coordinate of the vertex.


D3dViewportDesc Class (com.ms.directX Package)

 Microsoft SDK for Java

D3dViewportDesc Class

The D3dViewportDesc Class of the com.ms.directX package defines the visible 3D volume and the 2D screen area that a 3D volume projects onto for the getViewport and setViewport methods.

public final class D3dViewportDesc
{
  // Fields
  public int height;
  public float maxX;
  public float maxY;
  public float maxZ;
  public float minZ;
  public float scaleX;
  public float scaleY;
  public int width;
  public int x;
  public int y;
}

When the viewport is changed, the driver builds a new transformation matrix.

The coordinates and dimensions of the viewport are given, relative to the top-left of the device.

See Also

Direct3dViewport


Fields (D3dViewportDesc Class)

 Microsoft SDK for Java

D3dViewportDesc Class Fields

The D3dViewportDesc Class contains the following fields.

height | The height of the viewport.
maxX | Value describing the maximum homogeneous x-coordinate.
maxY | Value describing the maximum homogeneous y-coordinate.
maxZ | Value describing the maximum homogeneous z-coordinate.
minZ | Value describing the minimum homogeneous z-coordinate.
scaleX | Values describing the scaling quantities homogeneous to the screen.
scaleY | Values describing the scaling quantities homogeneous to the screen.
width | The width of the viewport.
x | The x-coordinate of the top-left corner of the viewport.
y | The y-coordinate of the top-left corner of the viewport.


DDBltFx Class (com.ms.directX Package)

 Microsoft SDK for Java

DDBltFx Class

The DDBltFx Class of the com.ms.directX package passes blit operations to the bltFx method. The information in this class includes raster operations, effects, and override information.

public final class DDBltFx
{
  // Fields
  public int alphaDestConst;
  public int alphaDestConstBitDepth;
  public int alphaEdgeBlend;
  public int alphaEdgeBlendBitDepth;
  public int alphaSrcConst;
  public int alphaSrcConstBitDepth;
  public int ddfx;
  public int ddrop;
  public int destColorSpaceHighValue;
  public int destColorSpaceLowValue;
  public int fillValue;
  public int rop;
  public int rotationAngle;
  public int srcColorSpaceHighValue;
  public int srcColorSpaceLowValue;
  public int zbufferBaseDest;
  public int zbufferHigh;
  public int zbufferLow;
  public int zbufferOpCode;
  public int zDestConst;
  public int zDestConstBitDepth;
  public int zSrcConst;
  public int zSrcConstBitDepth;
}

See Also

DirectDrawSurface


Fields (DDBltFx Class)

 Microsoft SDK for Java

DDBltFx Class Fields

The DDBltFx Class contains the following fields.

alphaDestConst | Constant used as the alpha channel destination.
alphaDestConstBitDepth | Bit depth of the destination alpha constant.
alphaEdgeBlend | Alpha constant used for edge blending.
alphaEdgeBlendBitDepth | Bit depth of the constant for an alpha edge blend.
alphaSrcConst | Constant used as the alpha channel source.
alphaSrcConstBitDepth | Bit depth of the source alpha constant.
ddfx | One or more values of DDBLTFX_ type, specifying FX operations.
ddrop | Specifies the DirectDraw raster operations.
destColorSpaceHighValue | The destination high value of the color range that is to be used as the color key.
destColorSpaceLowValue | The destination low value of the color range that is to be used as the color key.
fillValue | Color used to fill a surface when DDBLT_COLORFILL is specified. This value can be either an RGB triple or a palette index, depending on the surface type.
rop | Specifies the Win32 raster operations.
rotationAngle | Rotation angle for the blit.
srcColorSpaceHighValue | The source high value of the color range that is to be used as the color key.
srcColorSpaceLowValue | The source low value of the color range that is to be used as the color key.
zbufferBaseDest | Destination base value of a z-buffer.
zbufferHigh | High limit of a z-buffer.
zbufferLow | Low limit of a z-buffer.
zbufferOpCode | Z-buffer compares.
zDestConst | Constant used as the z-buffer destination.
zDestConstBitDepth | Bit depth of the destination z-constant.
zSrcConst | Constant used as the z-buffer source.
zSrcConstBitDepth | Bit depth of the source z-constant.


DDCaps Class (com.ms.directX Package)

 Microsoft SDK for Java

DDCaps Class

The DDCaps Class of the com.ms.directX package represents the capabilities of the hardware exposed through the DirectDraw object.

public final class DDCaps
{
  // Fields
  public int alignBoundaryDest;
  public int alignBoundarySrc;
  public int alignSizeDest;
  public int alignSizeSrc;
  public int alignStrideAlign;
  public int alphaBltConstBitDepths;
  public int alphaBltPixelBitDepths;
  public int alphaBltSurfaceBitDepths;
  public int alphaOverlayConstBitDepths;
  public int alphaOverlayPixelBitDepths;
  public int alphaOverlaySurfaceBitDepths;
  public int caps;
  public int caps2;
  public int colorkeyCaps;
  public int currVisibleOverlays;
  public int ddsCaps;
  public int fxAlphaCaps;
  public int fxCaps;
  public int maxVisibleOverlays;
  public int numFourCCCodes;
  public int palCaps;
  public int rops1;
  public int rops2;
  public int rops3;
  public int rops4;
  public int rops5;
  public int rops6;
  public int rops7;
  public int rops8;
  public int stereovisionCaps;
  public int vidMemFree;
  public int vidMemTotal;
  public int zbufferBitDepths;
}

This class contains the ddsCaps field that describes what kinds of DirectDrawSurface objects can be created. It might not be possible to simultaneously create all the surfaces described by these capabilities. This class is used with the DirectDraw.getCaps and DirectDrawPalette.getCaps methods.

Note The original DDCaps class is a combination of the current DDCaps and DDCapsFx classes.


Fields (DDCaps Class)

 Microsoft SDK for Java

DDCaps Class Fields

The DDCaps Class contains the following fields.

alignBoundaryDest | Destination rectangle alignment.
alignBoundarySrc | Source rectangle alignment.
alignSizeDest | Destination rectangle byte size.
alignSizeSrc | Source rectangle byte size.
alignStrideAlign | Stride alignment.
alphaBltConstBitDepths | DDBD_2, DDBD_4, or DDBD_8. (Indicates 2-, 4-, or 8-bits per pixel.)
alphaBltPixelBitDepths | DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicates 1-, 2-, 4-, or 8-bits per pixel.)
alphaBltSurfaceBitDepths | DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicates 1-, 2-, 4-, or 8-bits per pixel.)
alphaOverlayConstBitDepths | DDBD_2, DDBD_4, or DDBD_8. (Indicates 2-, 4-, or 8-bits per pixel.)
alphaOverlayPixelBitDepths | DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicates 1-, 2-, 4-, or 8-bits per pixel.)
alphaOverlaySurfaceBitDepths | DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicates 1-, 2-, 4-, or 8-bits per pixel.)
caps | One or more values of DDCaps_ type, specifying driver-specific capabilities.
caps2 | One or more values of DDCaps2_ type, specifying driver-specific capabilities.
colorkeyCaps | One or more values of DDCKEYCAPS_ type, specifying color-key capabilities.
currVisibleOverlays | Current number of visible overlays.
ddsCaps | One or more values of DDSCAPS_ type, specifying general capabilities.
fxAlphaCaps | One or more values of DDFXALPHACAPS_ type, specifying driver-specific alpha capabilities.
fxCaps | One or more values of DDFXCAPS_ type, specifying driver-specific stretching and effects capabilities.
maxVisibleOverlays | Maximum number of visible overlays.
numFourCCCodes | Number of FourCC codes.
palCaps | One or more values of DDPCAPS_ type, specifying palette capabilities.
rops1 | Raster operations supported.
rops2 | Raster operations supported.
rops3 | Raster operations supported.
rops4 | Raster operations supported.
rops5 | Raster operations supported.
rops6 | Raster operations supported.
rops7 | Raster operations supported.
rops8 | Raster operations supported.
stereovisionCaps | One or more values of DDSVCAPS_ type, specifying stereo vision capabilities.
vidMemFree | Amount of free display memory.
vidMemTotal | Total amount of display memory.
zbufferBitDepths | DDBD_8, DDBD_16, DDBD_24, or DDBD_32. (Indicates 8-, 16-, 24-, or 32-bits per pixel.)


DDCapsFx Class (com.ms.directX Package)

 Microsoft SDK for Java

DDCapsFx Class

The DDCapsFx Class of the com.ms.directX package represents the capabilities of the hardware exposed through the DirectDraw object.

public final class DDCapsFx
{
  // Fields
  public int maxHwCodecStretch;
  public int maxLiveVideoStretch;
  public int maxOverlayStretch;
  public int minHwCodecStretch;
  public int minLiveVideoStretch;
  public int minOverlayStretch;
  public int ssbCaps;
  public int ssbCFXCaps;
  public int ssbCKeyCaps;
  public int ssbRops1;
  public int ssbRops2;
  public int ssbRops3;
  public int ssbRops4;
  public int ssbRops5;
  public int ssbRops6;
  public int ssbRops7;
  public int ssbRops8;
  public int svbCaps;
  public int svbCKeyCaps;
  public int svbFXCaps;
  public int svbRops1;
  public int svbRops2;
  public int svbRops3;
  public int svbRops4;
  public int svbRops5;
  public int svbRops6;
  public int svbRops7;
  public int svbRops8;
  public int vsbCaps;
  public int vsbCKeyCaps;
  public int vsbFXCaps;
  public int vsbRops1;
  public int vsbRops2;
  public int vsbRops3;
  public int vsbRops4;
  public int vsbRops5;
  public int vsbRops6;
  public int vsbRops7;
  public int vsbRops8;
}

It might not be possible to simultaneously create all the surfaces described by these capabilities. This class is used with the DirectDraw.getCaps and DirectDrawPalette.getCaps methods.

Note The original DDCaps class is a combination of the current DDCaps and DDCapsFx classes.


Fields (DDCapsFx Class)

 Microsoft SDK for Java

DDCapsFx Class Fields

The DDCapsFx Class contains the following fields.

maxHwCodecStretch | Maximum hardware codec stretch factor multiplied by 1000. For example 1.3 = 1300.
maxLiveVideoStretch | Maximum live video stretch factor multiplied by 1000. For example, 1.3 = 1300.
maxOverlayStretch | Maximum overlay stretch factor multiplied by 1000. For example, 1.3 = 1300.
minHwCodecStretch | Minimum hardware codec stretch factor multiplied by 1000.
minLiveVideoStretch | Minimum live video stretch factor multiplied by 1000.
minOverlayStretch | Minimum overlay stretch factor multiplied by 1000.
ssbCaps | Driver-specific capabilities for system-memory-to-system-memory blits.
ssbCFXCaps | Driver FX capabilities for system-memory-to-system-memory blits.
ssbCKeyCaps | Driver color-key capabilities for system-memory-to-system-memory blits.
ssbRops1 | Raster operations supported for system-memory-to-system-memory blits.
ssbRops2 | Raster operations supported for system-memory-to-system-memory blits.
ssbRops3 | Raster operations supported for system-memory-to-system-memory blits.
ssbRops4 | Raster operations supported for system-memory-to-system-memory blits.
ssbRops5 | Raster operations supported for system-memory-to-system-memory blits.
ssbRops6 | Raster operations supported for system-memory-to-system-memory blits.
ssbRops7 | Raster operations supported for system-memory-to-system-memory blits.
ssbRops8 | Raster operations supported for system-memory-to-system-memory blits.
svbCaps | Driver-specific capabilities for system-memory-to-display-memory blits.
svbCKeyCaps | Driver color-key capabilities for system-memory-to-display-memory blits.
svbFXCaps | Driver FX capabilities for system-memory-to-display-memory blits.
svbRops1 | Raster operations supported for system-memory-to-display-memory blits.
svbRops2 | Raster operations supported for system-memory-to-display-memory blits.
svbRops3 | Raster operations supported for system-memory-to-display-memory blits.
svbRops4 | Raster operations supported for system-memory-to-display-memory blits.
svbRops5 | Raster operations supported for system-memory-to-display-memory blits.
svbRops6 | Raster operations supported for system-memory-to-display-memory blits.
svbRops7 | Raster operations supported for system-memory-to-display-memory blits.
svbRops8 | Raster operations supported for system-memory-to-display-memory blits.
vsbCaps | Driver-specific capabilities for display-memory-to-system-memory blits.
vsbCKeyCaps | Driver color-key capabilities for display-memory-to-system-memory blits.
vsbFXCaps | Driver FX capabilities for display-memory-to-system-memory blits.
vsbRops1 | Supports raster operations for display-memory-to-system-memory blits.
vsbRops2 | Supports raster operations for display-memory-to-system-memory blits.
vsbRops3 | Supports raster operations for display-memory-to-system-memory blits.
vsbRops4 | Supports raster operations for display-memory-to-system-memory blits.
vsbRops5 | Supports raster operations for display-memory-to-system-memory blits.
vsbRops6 | Supports raster operations for display-memory-to-system-memory blits.
vsbRops7 | Supports raster operations for display-memory-to-system-memory blits.
vsbRops8 | Supports raster operations for display-memory-to-system-memory blits.


DDColorKey Class (com.ms.directX Package)

 Microsoft SDK for Java

DDColorKey Class

The DDColorKey Class of the com.ms.directX package describes a source color key, destination color key or color space.

public final class DDColorKey
{
  // Fields
  public int colorSpaceHighValue;
  public int colorSpaceLowValue;
}

A color key is specified if the low and high range values are the same. This class is used with the getColorKey and setColorKey methods.


Fields (DDColorKey Class)

 Microsoft SDK for Java

DDColorKey Class Fields

The DDColorKey Class contains the following fields.

colorSpaceHighValue | High value, inclusive, of the color range that is to be used as the color key.
colorSpaceLowValue | Low value, inclusive, of the color range that is to be used as the color key.


DDPixelFormat Class (com.ms.directX Package)

 Microsoft SDK for Java

DDPixelFormat Class

The DDPixelFormat Class of the com.ms.directX package describes the pixel format of a DirectDrawSurface object for the getPixelFormat method.

public final class DDPixelFormat
{
  // Fields
  public int alphaBitDepth;
  public int alphaBitMask;
  public int blueBitMask;
  public int flags;
  public int fourCC;
  public int greenBitMask;
  public int redBitMask;
  public int rgbBitCount;
  public int uBitMask;
  public int vBitMask;
  public int yBitMask;
  public int yuvAlphaBitMask;
  public int yuvBitCount;
  public int zbufferBitDepth;
}


Fields (DDPixelFormat Class)

 Microsoft SDK for Java

DDPixelFormat Class Fields

The DDPixelFormat Class contains the following fields.

alphaBitDepth | Depth of alpha buffer.
alphaBitMask | Mask for alpha channel.
blueBitMask | Mask for blue bits.
flags Optional control flags. These include the following:

DDPF_ALPHA

The pixel format describes an alpha-only surface.

DDPF_ALPHAPIXELS

The surface has alpha channel information in the pixel format.

DDPF_COMPRESSED

The surface will accept pixel data in the specified format and compress it during the write operation.

DDPF_FOURCC

The FourCC code is valid.

DDPF_PALETTEINDEXED1

DDPF_PALETTEINDEXED2

DDPF_PALETTEINDEXED4

DDPF_PALETTEINDEXED8

The surface is 1-, 2-, 4-, or 8-bit color indexed.

DDPF_PALETTEINDEXEDTO8

The surface is 1-, 2-, or 4-bit color indexed to an 8-bit palette.

DDPF_RGB

The RGB data in the pixel format structure is valid.

DDPF_RGBTOYUV

The surface will accept RGB data and translate it during the write operation to YUV data. The format of the data to be written will be contained in the pixel format structure. The DDPF_RGB flag will be set.

DDPF_YUV

The YUV data in the pixel format structure is valid.

DDPF_ZBUFFER

The pixel format describes a z-buffer-only surface.
fourCC | FourCC code.
greenBitMask | Mask for green bits.
redBitMask | Mask for red bits.
rgbBitCount | RGB bits per pixel (4, 8, 16, 24, or 32).
uBitMask | Mask for U bits.
vBitMask | Mask for V bits.
yBitMask | Mask for Y bits.
yuvAlphaBitMask | Mask for alpha channel.
yuvBitCount | YUV bits per pixel (DDBD_4, DDBD_8, DDBD_16, DDBD_24, or DDBD_32).
zbufferBitDepth | Z-buffer bit depth (8, 16, 24, or 32).


DDSurfaceDesc Class (com.ms.directX Package)

 Microsoft SDK for Java

DDSurfaceDesc Class

The DDSurfaceDesc Class of the com.ms.directX package contains a description of the surface to be created. This class is passed to the createSurface method. The relevant fields differ for each potential type of surface.

public final class DDSurfaceDesc
{
  // Fields
  public int alphaBitDepth;
  public int alphaBitMask;
  public int backBufferCount;
  public int blueBitMask;
  public int colorkeyDestBltHigh;
  public int colorkeyDestBltLow;
  public int colorkeyDestOverlayHigh;
  public int colorkeyDestOverlayLow;
  public int colorkeySrcBltHigh;
  public int colorkeySrcBltLow;
  public int colorkeySrcOverlayHigh;
  public int colorkeySrcOverlayLow;
  public int ddsCaps;
  public int flags;
  public int fourCC;
  public int greenBitMask;
  public int height;
  public int mipmapCount;
  public int pitch;
  public int pixelFormatFlags;
  public int redBitMask;
  public int refreshRate;
  public int rgbBitCount;
  public int uBitMask;
  public int vBitMask;
  public int width;
  public int yBitMask;
  public int yuvAlphaBitMask;
  public int yuvBitCount;
  public int zbufferBitDepth;
}


Fields (DDSurfaceDesc Class)

 Microsoft SDK for Java

DDSurfaceDesc Class Fields

The DDSurfaceDesc Class contains the following fields.

alphaBitDepth | The depth of the alpha buffer.
alphaBitMask | The bitmask for the alpha channel.
backBufferCount | The number of back buffers.
blueBitMask | The bitmask for the blue bits.
colorkeyDestBltHigh | Color key for destination blit use.
colorkeyDestBltLow | Color key for destination blit use.
colorkeyDestOverlayHigh | Color key for destination overlay use.
colorkeyDestOverlayLow | Color key for destination overlay use.
colorkeySrcBltHigh | Color key for source blit use.
colorkeySrcBltLow | Color key for source blit use.
colorkeySrcOverlayHigh | Color key for source overlay use.
colorkeySrcOverlayLow | Color key for source overlay use.
ddsCaps | One or more values of DDSCAPS_ type specifying DirectDraw surface capabilities.
flags | One or more values of DDSD_ type.
fourCC | FourCC code.
greenBitMask | The bitmask for the green bits.
height | Height of the surface.
mipmapCount | The number of mipmap levels.
pitch | Distance to the start of the next line (return value only).
pixelFormatFlags | One or more values of DDPF_ type.
redBitMask | The bitmask for the red bits.
refreshRate | Used when the display mode is described.
rgbBitCount | The number of RGB bits per pixel (4, 8, 16, 24, or 32).
uBitMask | The bitmask for the U bits.
vBitMask | The bitmask for the V bits.
width | Width of the input surface.
yBitMask | The bitmask for the Y bits.
yuvAlphaBitMask | Mask for alpha channel.
yuvBitCount | The number of YUV bits per pixel (DDBD_4, DDBD_8, DDBD_16, DDBD_24, or DDBD_32).
zbufferBitDepth | Z-buffer bit depth (8, 16, 24, or 32).


Direct3d Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3d Class

Applications use the methods of the Direct3d Class of the com.ms.directX package to create Direct3D objects and set up the environment.

public class Direct3d implements IDirect3d
{
  // Methods
  public Direct3dLight createLight();
  public Direct3dMaterial createMaterial();
  public Direct3dViewport createViewport();
  public void enumDevices(Id3dEnumDevicesCallback fn, IUnknown p);
  public void findDevice(D3dFindDeviceSearch ds,
        D3dFindDeviceResult hresult, D3dFindDeviceResult sresult);
  public _Guid findDeviceForColorModel(int cm, int hardware);
  public void initialize(_Guid id);
  public int systemBpp();
}


Methods (Direct3d Class)

 Microsoft SDK for Java

Direct3d Class Methods

The Direct3d Class contains the following methods:

createLight allocates a Direct3dLight object.
createMaterial allocates a Direct3dMaterial object.
createViewport creates a Direct3dViewport object.
enumDevices enumerates all Direct3D device drivers installed on the system.
findDevice searches for and returns information about devices that match the given description.
findDeviceForColorModel finds a device with specified color model characteristics and retrieves a description of it.
initialize initializes the Direct3d object.
systemBpp returns the system bits-per-pixel value.


createLight (Direct3d Class)

 Microsoft SDK for Java

createLight

This method of the Direct3d Class allocates a Direct3dLight object.

Syntax

public Direct3dLight createLight();

Return Value

Returns the Direct3dLight object if successful; otherwise, returns null.


createMaterial (Direct3d Class)

 Microsoft SDK for Java

createMaterial

This method of the Direct3d Class allocates a Direct3dMaterial object.

Syntax

public Direct3dMaterial createMaterial();

Return Value

Returns the Direct3dMaterial object if successful; otherwise, returns null.


createViewport (Direct3d Class)

 Microsoft SDK for Java

createViewport

This method of the Direct3d Class creates a Direct3dViewport object. The viewport is associated with a Direct3DDevice object by using the addViewport method.

Syntax

public Direct3dViewport createViewport();

Return Value

Returns the Direct3dViewport object if successful; otherwise, returns null.


enumDevices (Direct3d Class)

 Microsoft SDK for Java

enumDevices

This method of the Direct3d Class enumerates all Direct3D device drivers installed on the system.

Syntax

public void enumDevices(Id3dEnumDevicesCallback fn, IUnknown p);

Parameters

fn | An interface containing a callback function that the enumeration procedure will call every time a match is found.
p | Application-defined data passed to the callback function.


findDevice (Direct3d Class)

 Microsoft SDK for Java

findDevice

This method of the Direct3d Class searches for and returns information about devices that match the given description.

Syntax

public void findDevice(D3dFindDeviceSearch ds, D3dFindDeviceResult hresult, D3dFindDeviceResult sresult);

Parameters

ds | The D3dFindDeviceSearch object that contains a description of the device(s) to search for.
hresult | The D3dFindDeviceSearch object that receives the hardware device results of the search.
sresult | The D3dFindDeviceResult object that receives the software device results of the search.


findDeviceForColorModel (Direct3d Class)

 Microsoft SDK for Java

findDeviceForColorModel

This method of the Direct3d Class finds a device with specified color model characteristics and retrieves a description of it.

Syntax

public _Guid findDeviceForColorModel(int cm, int hardware);

Parameters

cm | One value of D3DCOLOR_ type, specifying the color model to locate.
hardware | Set this value to 1 to specify that the device should be a hardware-only renderer; set to 0 for software only.


initialize (Direct3d Class)

 Microsoft SDK for Java

initialize

This method of the Direct3d Class initializes the Direct3d object.

Syntax

public void initialize(_Guid id);

Parameters

id A universally unique identifier (UUID).


systemBpp (Direct3d Class)

 Microsoft SDK for Java

systemBpp

This method of the Direct3d Class returns the system bits-per-pixel value.

Syntax

public int systemBpp();

Return Value

Returns the bits-per-pixel.


Direct3dDevice Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dDevice Class

Applications use the methods of the Direct3dDevice Class of the com.ms.directX package to retrieve and set the capabilities of Direct3D devices.

public class Direct3dDevice implements IDirect3dDevice
{
  // Methods
  public void addViewport(Direct3dViewport vport);
  public void beginScene();
  public Direct3dExecuteBuffer createExecuteBuffer(
        D3dExecuteBufferDesc ebufDesc);
  public int createMatrix();
  public void deleteMatrix(int hdl);
  public void deleteViewport(Direct3dViewport vport);
  public void endScene();
  public void enumTextureFormats(IEnumTextureFormatsCallback fn,
        IUnknown args);
  public void execute(Direct3dExecuteBuffer eb,
        Direct3dViewport vp, int flags);
  public void getCaps(D3dDeviceDesc hwDesc, D3dDeviceDesc helDesc);
  public Direct3d getDirect3D();
  public void getMatrix(int hdl, D3dMatrix mat);
  public void getPickRecords(int[] flags, D3dPickRecord val);
  public void getStats(D3dStats stat);
  public void initialize(Direct3d dev, _Guid g,
        D3dDeviceDesc devDesc);
  public Direct3dViewport nextViewport(Direct3dViewport vp1,
        int flags);
  public void pick(Direct3dExecuteBuffer eb,
        Direct3dViewport vport, int flags, D3dRect rectangle);
  public void setMatrix(int hdl, D3dMatrix mat);
  public void swapTextureHandles(Direct3dTexture tex1,
        Direct3dTexture tex2);
}


Methods (Direct3dDevice Class)

 Microsoft SDK for Java

Direct3dDevice Class Methods

The Direct3dDevice Class contains the following methods:

addViewport adds the specified viewport to the list of viewport objects associated with the device.
beginScene begins a scene.
createExecuteBuffer allocates an execute buffer for a display list.
createMatrix creates a matrix.
deleteMatrix deletes a matrix handle.
deleteViewport removes the specified viewport from the list of viewport objects associated with the device.
endScene ends a scene that was begun by calling the beginScene method.
enumTextureFormats queries the current driver for a list of supported texture formats.
execute executes a buffer.
getCaps retrieves the capabilities of the Direct3dDevice object.
getDirect3D retrieves the current Direct3djsdk_ref_directX_Direct3d object.
getMatrix retrieves a matrix from a matrix handle.
getPickRecords retrieves the pick records for a device.
getStats retrieves statistics about a device.
initialize initializes a Direct3dDevice object.
nextViewport enumerates the viewports associated with the device.
pick executes a buffer without performing any rendering, but returns a z-ordered list of offsets to the primitives that cover the rectangle specified by Rect.
setMatrix applies a matrix to a matrix handle.
swapTextureHandles swaps two texture handles.


addViewport (Direct3dDevice Class)

 Microsoft SDK for Java

addViewport

This method of the Direct3dDevice Class adds the specified viewport to the list of viewport objects associated with the device.

Syntax

public void addViewport(Direct3dViewport vport);

Parameters

vport The viewport object that should be associated with this Direct3dDevice object.


beginScene (Direct3dDevice Class)

 Microsoft SDK for Java

beginScene

This method of the Direct3dDevice Class begins a scene.

Syntax

public void beginScene();

Remarks

Applications must call this method before performing any rendering, and must call endScene when rendering is complete.

See Also

endScene


createExecuteBuffer (Direct3dDevice Class)

 Microsoft SDK for Java

createExecuteBuffer

This method of the Direct3dDevice Class allocates an execute buffer for a display list. The list can be read by hardware DMA into VRAM for processing. All display primitives in the buffer that have indices to vertices must also have those vertices in the same buffer.

Syntax

public Direct3dExecuteBuffer createExecuteBuffer( D3dExecuteBufferDesc ebufDesc);

Return Value

Returns the Direct3dExecuteBuffer if successful; otherwise, null.

Parameters

ebufDesc Describes the Direct3dExecuteBuffer object to be created. The call will fail if a buffer of at least the specified size cannot be created.

Remarks

The D3dExecuteBufferDesc object describes the execute buffer to be created. At a minimum, the application must specify the size required. If the application specifies DEBCAPS_VIDEO_MEMORY in the capabilities field, Direct3D will attempt to keep the execute buffer in video memory.

The application can use the lock method to request that the memory be moved. When this method returns, it will adjust the contents of the D3dExecuteBufferDesc object to indicate whether the data resides in system or video memory.


createMatrix (Direct3dDevice Class)

 Microsoft SDK for Java

createMatrix

This method of the Direct3dDevice Class creates a matrix.

Syntax

public int createMatrix();

Return Value

Returns a handle to the matrix that is created. The call will fail if a buffer of at least the size of the matrix cannot be created.

See Also

deleteMatrix, setMatrix


deleteMatrix (Direct3dDevice Class)

 Microsoft SDK for Java

deleteMatrix

This method of the Direct3dDevice Class deletes a matrix handle. This matrix handle must have been created by using the createMatrix method.

Syntax

public void deleteMatrix(int hdl);

Parameters

hdl Matrix handle to be deleted.

See Also

createMatrix, setMatrix


deleteViewport (Direct3dDevice Class)

 Microsoft SDK for Java

deleteViewport

This method of the Direct3dDevice Class removes the specified viewport from the list of viewport objects associated with the device.

Syntax

public void deleteViewport(Direct3dViewport vport);

Parameters

vport A viewport object that should be disassociated with this Direct3dDevice object.


endScene (Direct3dDevice Class)

 Microsoft SDK for Java

endScene

This method of the Direct3dDevice Class ends a scene that was begun by calling the beginScene method.

Syntax

public void endScene();

See Also

beginScene


enumTextureFormats (Direct3dDevice Class)

 Microsoft SDK for Java

enumTextureFormats

This method of the Direct3dDevice Class queries the current driver for a list of supported texture formats.

Syntax

public void enumTextureFormats(IEnumTextureFormatsCallback fn, IUnknown args);

Parameters

fn | Callback interface containing the function that the enumeration procedure will call for each texture format.
args | Application-defined data passed to the callback function.


execute (Direct3dDevice Class)

 Microsoft SDK for Java

execute

This method of the Direct3dDevice Class executes a buffer.

Syntax

public void execute(Direct3dExecuteBuffer eb, Direct3dViewport vp, int flags);

Parameters

eb | The Direct3dExecute buffer to be executed.
vp | The Direct3dViewport object that describes the transformation context, into which the execute buffer will be rendered.
Flags | A value of D3DEXECUTE_ type, specifying whether objects in the buffer should be clipped.


getCaps (Direct3dDevice Class)

 Microsoft SDK for Java

getCaps

This method of the Direct3dDevice Class retrieves the capabilities of the Direct3dDevice object.

Syntax

public void getCaps(D3dDeviceDesc hwDesc, D3dDeviceDesc helDesc);

hwDesc | The D3dDeviceDesc object that receives the hardware features of the device.
helDesc | The D3dDeviceDesc object that receives the software emulation being provided.

Remarks

This method does not retrieve the capabilities of the display device. To retrieve this information, use the getCaps method.


getDirect3D (Direct3dDevice Class)

 Microsoft SDK for Java

getDirect3D

This method of the Direct3dDevice Class retrieves the current Direct3d object.

Syntax

public Direct3d getDirect3D();

Return Value

Returns the Direct3d object if successful; otherwise, returns null.


getMatrix (Direct3dDevice Class)

 Microsoft SDK for Java

getMatrix

This method of the Direct3dDevice Class retrieves a matrix from a matrix handle. This matrix handle must have been created by using the createMatrix method.

Syntax

public void getMatrix(int hdl, D3dMatrix mat);

Parameters

hdl | Handle of the matrix to be retrieved.
mat | The D3dMatrix object that receives the matrix.

See Also

createMatrix, deleteMatrix, setMatrix


getPickRecords (Direct3dDevice Class)

 Microsoft SDK for Java

getPickRecords

This method of the Direct3dDevice Class retrieves the pick records for a device.

Syntax

public void getPickRecords(int[] flags, D3dPickRecord val);

Parameters

flags | Valid flags for this method.
val | The D3dPickRecord object that receives a pick record.


getStats (Direct3dDevice Class)

 Microsoft SDK for Java

getStats

This method of the Direct3dDevice Class retrieves statistics about a device.

Syntax

public void getStats(D3dStats stat);

Parameters

stat The D3dStats object that receives the statistics.


initialize (Direct3dDevice Class)

 Microsoft SDK for Java

initialize

This method of the Direct3dDevice Class initializes a Direct3dDevice object.

Syntax

public void initialize(Direct3d dev, _Guid g, D3dDeviceDesc devDesc);

Parameters

dev | The Direct3D device to use as an initializer.
g | The globally unique identifier (GUID) used as the interface identifier.
devDesc | The D3dDeviceDesc object describing the Direct3dDevice object to be initialized.


nextViewport (Direct3dDevice Class)

 Microsoft SDK for Java

nextViewport

This method of the Direct3dDevice Class enumerates the viewports associated with the device.

Syntax

public Direct3dViewport nextViewport(Direct3dViewport vp1, int flags);

Return Value

Returns the next Direct3dViewport object in the list of viewports associated with this Direct3DDevice object if successful; otherwise, returns null.

Parameters

vpl | A viewport in the list of viewports associated with this Direct3dDevice object.
flags | A value of D3DNEXT_ type, specifying which viewport to retrieve from the list of viewports. The default setting is D3DNEXT_NEXT.


pick (Direct3dDevice Class)

 Microsoft SDK for Java

pick

This method of the Direct3dDevice Class executes a buffer without performing any rendering, but returns a z-ordered list of offsets to the primitives that cover the rectangle specified by Rect.

This call fails if the Direct3dExecuteBuffer object is locked.

Syntax

public void pick(Direct3dExecuteBuffer eb, Direct3dViewport vport, int flags, D3dRect rectangle);

Parameters

eb | An execute buffer from which the z-ordered list is retrieved.
vport | A viewport in the list of viewports associated with this Direct3dDevice object.
flags | No flags are currently defined for this method.
Rect | The D3dRect object specifying the range of device coordinates to be picked.

Remarks

If the x1 and x2 fields of the object specified in the Rect parameter are equal, and the y1 and y2 members are equal, a single pixel is used for picking. The coordinates are specified in device-pixel space.

All Direct3dExecuteBuffer objects must be attached to a Direct3dDevice object for this method to succeed.

See Also

getPickRecords


setMatrix (Direct3dDevice Class)

 Microsoft SDK for Java

setMatrix

This method of the Direct3dDevice Class applies a matrix to a matrix handle. This matrix handle must have been created by using the createMatrix method.

Syntax

public void setMatrix(int hdl, D3dMatrix mat);

Parameters

hdl | Matrix handle to be set.
mat | The D3dMatrix object that describes the matrix to be set.

Remarks

Transformations inside the execute buffer include a handle of a matrix. The setMatrix method enables an application to change this matrix without having to lock and unlock the execute buffer.

See Also

createMatrix, getMatrix, deleteMatrix


swapTextureHandles (Direct3dDevice Class)

 Microsoft SDK for Java

swapTextureHandles

This method of the Direct3dDevice Class swaps two texture handles.

Syntax

public void swapTextureHandles(Direct3dTexture tex1, Direct3dTexture tex2);

Parameters

tex1 | The texture to be swapped.
tex2 | The texture to be swapped.

Remarks

This method is useful when an application is changing all the textures in a complicated object.


Direct3dExecuteBuffer Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dExecuteBuffer Class

Applications use the methods of the Direct3dExecuteBuffer Class of the com.ms.directX package to set up and control a Direct3D execute buffer.

public class Direct3dExecuteBuffer implements
            IDirect3dExecuteBuffer
{
  // Methods
  public int addLVertexData(D3dLVertex vertex, int bufferindex);
  public int addTLVertexData(D3dTLVertex vertex, int bufferindex);
  public int addVertexData(D3dVertex vertex, int bufferindex);
  public int exit(int bufferindex);
  public native void getDataAsArrayFloats(float[] d);
  public native void getDataAsArrayInts(int[] d);
  public void getExecuteData(D3dExecuteData data);
  public native int lineList(int cnt, char segs, int bufferindex);
  public void lock(D3dExecuteBufferDesc Desc);
  public native int matrixLoad(int hdest, int hsrc,
        int bufferindex);
  public native int matrixMultiply(int hsrc1, int hsrc2, int hdest,
        int bufferindex);
  public native int pointList(int cnt, char first, int bufferindex);
  public int processVertices(int cnt, int bufferindex);
  public int processVerticesData(int flags, int start, int dest,
        int cnt, int bufferindex);
  public native void setDataAsArrayFloats(float[] d);
  public native void setDataAsArrayInts(int[] d);
  public void setExecuteData(D3dExecuteData data);
  public int setStatus(int flags, int status, int x1, int y1,
        int x2, int y2, int bufferindex);
  public native int spanList(int cnt, char first, int bufferindex);
  public int stateLight(int cnt, int bufferindex);
  public int stateLightData(int flags, int Arg, int bufferindex);
  public int stateRender(int cnt, int bufferindex);
  public int stateRenderData(int flags, int Arg, int bufferindex);
  public int stateTransForm(int cnt, int bufferindex);
  public int stateTransFormData(int flags, int Arg,
        int bufferindex);
  public native int textureLoad(int hdest, int hsrc,
        int bufferindex);
  public int triangleList(int cnt, int bufferindex);
  public int triangleListData(D3dTriangle triangle,
        int bufferindex);
  public void unlock();
}

Note This class does not provide an initialize method. Use the Direct3dDevice.createExecuteBuffer method to create and initialize Direct3dExecuteBuffer objects.


Methods (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

Direct3dExecuteBuffer Class Methods

The Direct3dExecuteBuffer Class contains the following methods:

addLVertexData adds a lit, untransformed vertex to the execute buffer at the position indicated by the bufferindex.
addTLVertexData adds a lit and transformed vertex to the execute buffer at the position indicated by the bufferindex.
addVertexData adds an unlit, untransformed vertex to the execute buffer at the position indicated by bufferindex.
exit
getDataAsArrayFloats retrieves the data contained in the execute buffer as an array of float types.
getDataAsArrayInts retrieves the data contained in the execute buffer as an array of int types.
getExecuteData retrieves the execute data state of the Direct3dExecuteBuffer object.
lineList sets the number of LINE instructions that will proceed with this instruction in the execute buffer.
lock obtains the command data from the execute buffer.
matrixLoad loads a matrix.
matrixMultiply multiplies two matrices.
pointList sets the number of POINT instructions that will proceed with this instruction in the execute buffer.
processVertices sets the number of PROCESSVERTICES instructions that will proceed with this instruction in the execute buffer.
processVerticesData sets the data for the PROCESSVERTICES instruction in the execute buffer.
setDataAsArrayFloats sets the data in the execute buffer to the specified array of floats.
setDataAsArrayInts sets the data in the execute buffer to the specified array of ints.
setExecuteData sets the execute data state of the Direct3dExecuteBuffer object.
setStatus resets the status of the execute buffer.
spanList sets the number of SPAN instructions that will proceed with this instruction in the execute buffer.
stateLight sets the number of STATELIGHT instructions that will proceed with this instruction in the execute buffer.
stateLightData describes the transformation state for the STATELIGHT instruction.
stateRender sets the number of STATERENDER instructions in the execute buffer.
stateRenderData describes the render state for the STATERENDER instruction.
stateTransForm sets the number of STATETRANSFORM instructions that will proceed with this instruction in the execute buffer.
stateTransFormData describes the transformation state for the STATETRANSFORM instruction.
textureLoad loads a texture.
triangleList sets the number of TRIANGLE instructions that will proceed with this instruction in the execute buffer.
triangleListData describes the transformation state for the TRIANGLE instruction.
unlock releases access to the commands in the execute buffer.


addLVertexData (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

addLVertexData

This method of the Direct3dExecuteBuffer Class adds a lit, untransformed vertex to the execute buffer at the position indicated by the bufferindex.

Syntax

public int addLVertexData(D3dLVertex vertex, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

vertex | A D3dVertex object.
bufferindex | The position in the execute buffer to place the vertex.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


addTLVertexData (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

addTLVertexData

This method of the Direct3dExecuteBuffer Class adds a lit and transformed vertex to the execute buffer at the position indicated by the bufferindex.

Syntax

public int addTLVertexData(D3dTLVertex vertex, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

vertex | A D3dVertex object.
bufferindex | The position in the execute buffer to place the vertex.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


addVertexData (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

addVertexData

This method of the Direct3dExecuteBuffer Class adds an unlit, untransformed vertex to the execute buffer at the position indicated by bufferindex.

Syntax

public int addVertexData(D3dVertex vertex, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

vertex | A D3dVertex object
bufferindex | The position in the execute buffer to place the vertex.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


exit (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

exit

This is a method of the Direct3dExecuteBuffer Class.

Syntax

public int exit(int bufferindex);


getDataAsArrayFloats (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

getDataAsArrayFloats

This method of the Direct3dExecuteBuffer Class retrieves the data contained in the execute buffer as an array of float types.

Syntax

public native void getDataAsArrayFloats(float[] d);

Parameters

d The array of floats that the data is copied to.


getDataAsArrayInts (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

getDataAsArrayInts

This method of the Direct3dExecuteBuffer Class retrieves the data contained in the execute buffer as an array of int types.

Syntax

public native void getDataAsArrayInts(int[] d);

Parameters

d The array of ints that the data is copied to.


getExecuteData (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

getExecuteData

This method of the Direct3dExecuteBuffer Class retrieves the execute data state of the Direct3dExecuteBuffer object. The execute data is used to describe the contents of the object.

Syntax

public void getExecuteData(D3dExecuteData data);

Parameters

data The D3dExecuteData object that receives the current execute data state of the Direct3dExecuteBuffer object.

Remarks

This call fails if the Direct3dExecuteBuffer object is locked.

See Also

setExecuteData


lineList (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

lineList

This method of the Direct3dExecuteBuffer Class sets the number of LINE instructions that will proceed with this instruction in the execute buffer. This method emulates the similar macro found in the Direct3d d3dmacs.h header file.

Syntax

public native int lineList(int cnt, char segs, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

cnt | The number of instructions.
segs |
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


lock (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

lock

This method of the Direct3dExecuteBuffer Class obtains the command data from the execute buffer.

Syntax

public void lock(D3dExecuteBufferDesc Desc);

Parameters

Desc The D3dExecuteBufferDesc object.

Remarks

This method can obtain data from either system or video memory as specified by the caps field of Desc. The length of the array assigned to buffer must be set in the bufferSize field before making the call.

The application can use the lock method to request that Direct3D move the data between system or video memory.

This method fails if the Direct3dExecuteBuffer object is locked—that is, if another thread is accessing the buffer or if a Direct3dDevice.execute method that was issued on this buffer has not yet been completed.

See Also

unlock


matrixLoad (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

matrixLoad

This method of the Direct3dExecuteBuffer Class loads a matrix.

Syntax

public native int matrixLoad(int hdest, int hsrc, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

hdest | The handle of the destination matrix.
hsrc | The handle of a source matrix.
bufferindex | The position in the execute buffer to place the instruction.


matrixMultiply (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

matrixMultiply

This method of the Direct3dExecuteBuffer Class multiplies two matrices.

Syntax

public native int matrixMultiply(int hsrc1, int hsrc2, int hdest, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

hsrc1 | The handle of one of the matrices to multiply.
hsrc2 | The handle of one of the matrices to multiply.
hdest | The handle of a destination matrix to copy the result of the multiplication to.
bufferindex | The position in the execute buffer to place the instruction.


pointList (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

pointList

This method of the Direct3dExecuteBuffer Class sets the number of POINT instructions that will proceed with this instruction in the execute buffer. This method emulates the similar macro found in the Direct3d d3dmacs.h header file.

Syntax

public native int pointList(int cnt, char first, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

cnt | The number of instructions.
first |
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


processVertices (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

processVertices

This method of the Direct3dExecuteBuffer Class sets the number of PROCESSVERTICES instructions that will proceed with this instruction in the execute buffer.

Syntax

public int processVertices(int cnt, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

cnt | The number of instructions.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


processVerticesData (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

processVerticesData

This method of the Direct3dExecuteBuffer Class sets the data for the PROCESSVERTICES instruction in the execute buffer. This method describes how vertices in the execute buffer should be handled by the driver.

Syntax

public int processVerticesData(int flags, int start, int dest, int cnt, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

flags | The flags that indicate how the driver should process the vertices. These can be: D3DPROCESSVERTICES_COPY D3DPROCESSVERTICES_NOCOLOR D3DPROCESSVERTICES_OPMASK D3DPROCESSVERTICES_TRANSFORM D3DPROCESSVERTICES_TRANSFORMLIGHT D3DPROCESSVERTICES_UPDATEEXTENTS
start | The index of the first vertex in the source.
dest | The index of the first vertex in the local buffer.
cnt | The number of vertices to be processed.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


setDataAsArrayFloats (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

setDataAsArrayFloats

This method of the Direct3dExecuteBuffer Class sets the data in the execute buffer to the specified array of floats.

Syntax

public native void setDataAsArrayFloats(float[] d);

Parameters

d The array to set the data in the execute buffer to.


setDataAsArrayInts (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

setDataAsArrayInts

This method of the Direct3dExecuteBuffer Class sets the data in the execute buffer to the specified array of ints.

Syntax

public native void setDataAsArrayInts(int[] d);

Parameters

d The array to set the data in the execute buffer to.


setExecuteData (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

setExecuteData

This method of the Direct3dExecuteBuffer Class sets the execute data state of the Direct3dExecuteBuffer object. The execute data is used to describe the contents of the object.

Syntax

public void setExecuteData(D3dExecuteData data);

Parameters

data A D3dExecuteData object that describes the execute buffer layout.

Remarks

This call fails if the Direct3dExecuteBuffer object is locked.

See Also

getExecuteData


setStatus (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

setStatus

This method of the Direct3dExecuteBuffer Class resets the status of the execute buffer.

Syntax

public int setStatus(int flags, int status, int x1, int y1, int x2, int y2, int bufferindex);

Return Value

Returns the number of 32-bit values added to the buffer.

Parameters

flags Specifies whether the status, extents, or both are being set.

D3DSETSTATUS_STATUS

Sets the status.

D3DSETSTATUS_EXTENTS

Sets the extents specified by a given bounding box (x1,y1,x2,y2).

D3DSETSTATUS_ALL

Sets both the status and the extents.
status The clipping flags. This parameter can be one or more of the following flags:

D3DSTATUS_CLIPINTERSECTIONALL

Combination of all CLIPINTERSECTION flags.

Other CLIPINTERSECTION flags include D3DSTATUS_CLIPINTERSECTIONBACK, D3DSTATUS_CLIPINTERSECTIONBOTTOM, D3DSTATUS_CLIPINTERSECTIONFRONT, and D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5.

D3DSTATUS_CLIPUNIONALL

Combination of all CLIPUNION flags.

Other CLIPUNION flags include D3DSTATUS_CLIPUNIONBOTTOM, D3DSTATUS_CLIPUNIONTOP, D3DSTATUS_CLIPUNIONLEFT, and D3DSTATUS_CLIPUNIONRIGHT.

D3DSTATUS_DEFAULT

the default is a combination of D3DSTATUS_CLIPINTERSECTION and D3DSTATUS_ZNOTVISIBLE flags.

Basic clipping flags include D3DCLIP_BACK, D3DCLIP_LEFT, and D3DCLIP_TOP.
x1 | Defines a bounding box for all relevant vertices. The x-coordinate of the bounding box's upper-left corner.
x2 | The y-coordinate of the bounding box's upper-left corner.
y1 | The x-coordinate of the bounding box's lower-right corner.
y2 | The y-coordinate of the bounding box's lower-right corner.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The status is a rolling status and is updated during each execution. The bounding box specified can grow with each execution, but it does not shrink. It can be reset by calling this method again.

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


spanList (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

spanList

This method of the Direct3dExecuteBuffer Class sets the number of SPAN instructions that will proceed with this instruction in the execute buffer. This method emulates the similar macro found in the Direct3d d3dmacs.h header file.

Syntax

public native int spanList(int cnt, char first, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

cnt | The number of instructions.
first |
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


stateLight (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

stateLight

This method of the Direct3dExecuteBuffer Class sets the number of STATELIGHT instructions that will proceed with this instruction in the execute buffer. This method emulates the similar macro found in the Direct3d d3dmacs.h header file.

Syntax

public int stateLight(int cnt, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

cnt | The number of instructions.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


stateLightData (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

stateLightData

This method of the Direct3dExecuteBuffer Class describes the transformation state for the STATELIGHT instruction.

Syntax

public int stateLightData(int flags, int Arg, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

flags | One of the following values: D3DLIGHTSTATE_MATERIAL Defines the material used to compute the final color and intensity values during rasterization. D3DLIGHTSTATE_AMBIENT Sets the color and intensity of the current ambient light. D3DLIGHTSTATE_COLORMODEL One of the D3DCOLORMODEL types. D3DLIGHTSTATE_FOGMODE One of the D3DFOGMODE types. D3DLIGHTSTATE_FOGSTART Defines the starting value for fog. D3DLIGHTSTATE_FOGEND Defines the ending value for fog. D3DLIGHTSTATE_FOGDENSITY Defines the density setting for fog.
Arg | A value that is dependant on which flag is set.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


stateRender (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

stateRender

This method of the Direct3dExecuteBuffer Class sets the number of STATERENDER instructions in the execute buffer.

Syntax

public int stateRender(int cnt, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

cnt | The number of instructions.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


stateRenderData (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

stateRenderData

This method of the Direct3dExecuteBuffer Class describes the render state for the STATERENDER instruction.

Syntax

public int stateRenderData(int flags, int Arg, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

flags | The flags that describe the render state. For a complete listing of D3DRENDERSTATE_ flags, see DirectXConstants.
Arg | A value that is dependant on the D3DRENDERSTATE_ flag.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


stateTransForm (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

stateTransForm

This method of the Direct3dExecuteBuffer Class sets the number of STATETRANSFORM instructions that will proceed with this instruction in the execute buffer.

Syntax

public int stateTransForm(int cnt, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

cnt | The number of instructions.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


stateTransFormData (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

stateTransFormData

This method of the Direct3dExecuteBuffer Class describes the transformation state for the STATETRANSFORM instruction.

Syntax

public int stateTransFormData(int flags, int Arg, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

flags | Can be one of the following flags: D3DTRANSFORMSTATE_WORLD D3DTRANSFORMSTATE_VIEW D3DTRANSFORMSTATE_PROJECTION
Arg | The handle of the matrices for the world, view, and projection transformations. The default values for these are null.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


textureLoad (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

textureLoad

This method of the Direct3dExecuteBuffer Class loads a texture.

Syntax

public native int textureLoad(int hdest, int hsrc, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

hdest | The handle of the destination texture.
hsrc | The handle of a source texture.
bufferindex | The position in the execute buffer to place the instruction.


triangleList (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

triangleList

This method of the Direct3dExecuteBuffer Class sets the number of TRIANGLE instructions that will proceed with this instruction in the execute buffer. This method emulates the similar macro found in the Direct3d d3dmacs.h header file.

Syntax

public int triangleList(int cnt, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

cnt | The number of instructions.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


triangleListData (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

triangleListData

This method of the Direct3dExecuteBuffer Class describes the transformation state for the TRIANGLE instruction.

Syntax

public int triangleListData(D3dTriangle triangle, int bufferindex);

Return Value

Returns the number of 32-bit values added.

Parameters

triangle | The D3dTriangle object.
bufferindex | The position in the execute buffer to place the instruction.

Remarks

The execute buffer is treated as an array of 32-bit values, which is a collection of floats and ints that describe vertices and instructions. It is up to the user to manage the position of each item added to the buffer.


unlock (Direct3dExecuteBuffer Class)

 Microsoft SDK for Java

unlock

This method of the Direct3dExecuteBuffer Class releases access to the commands in the execute buffer. This must be done prior to calling the execute method for the buffer.

Syntax

public void unlock();

See Also

lock


Direct3dLight Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dLight Class

Applications use the methods of the Direct3dLight Class of the com.ms.directX package to retrieve and set the capabilities of lights

public class Direct3dLight implements IDirect3dLight
{
  // Methods
  public void getLight(D3dLightDesc light);
  public void setLight(D3dLightDesc light);
}

Note This class does not provide an initialize method. Use the Direct3d.createLight()method to create and initialize Direct3dLight objects.


Methods (Direct3dLight Class)

 Microsoft SDK for Java

Direct3dLight Class Methods

The Direct3dLight Class contains the following methods:

getLight retrieves the light information for the Direct3dLight object.
setLight sets the light information for the Direct3dLight object.


getLight (Direct3dLight Class)

 Microsoft SDK for Java

getLight

This method of the Direct3dLight Class retrieves the light information for the Direct3dLight object.

Syntax

public void getLight(D3dLightDesc light);

Parameters

light The D3dLightDesc object that receives the current light data.

See Also

setLight


setLight (Direct3dLight Class)

 Microsoft SDK for Java

setLight

This method of the Direct3dLight Class sets the light information for the Direct3dLight object.

Syntax

public void setLight(D3dLightDesc light);

Parameters

light The Direct3dLight object that contains the light data to set.

See Also

getLight


Direct3dMaterial Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dMaterial Class

Applications use the methods of the Direct3dMaterial Class of the com.ms.directX package to retrieve and set the properties of materials.

public class Direct3dMaterial implements IDirect3dMaterial
{
  // Methods
  public int getHandle(Direct3dDevice dev);
  public void getMaterial(D3dMaterialDesc mat);
  public void reserve();
  public void setMaterial(D3dMaterialDesc mat);
  public void unreserve();
}

Note This class does not provide an initialize method. Use the Direct3d.createMaterial()method to create and initialize Direct3dMaterial objects.


Methods (Direct3dMaterial Class)

 Microsoft SDK for Java

Direct3dMaterial Class Methods

The Direct3dMaterial Class contains the following methods:

getHandle obtains the material handle for the Direct3dMaterial object.
getMaterial retrieves the material data for the Direct3dMaterial object.
reserve is not currently implemented.
setMaterial sets the material data for the Direct3dMaterial object.
unreserve is not currently implemented.


getHandle (Direct3dMaterial Class)

 Microsoft SDK for Java

getHandle

This method of the Direct3dMaterial Class obtains the material handle for the Direct3dMaterial object. This handle is used in all Direct3D API calls where a material is to be referenced. A material can be used by only one device at a time.

If the device is destroyed, the material is disassociated from the device.

Syntax

public int getHandle(Direct3dDevice dev);

Return Value

Returns the material handle corresponding to the Direct3dMaterial object.

Parameters

dev The Direct3dDevice object in which the material is being used.


getMaterial (Direct3dMaterial Class)

 Microsoft SDK for Java

getMaterial

This method of the Direct3dMaterial Class retrieves the material data for the Direct3dMaterial object.

Syntax

public void getMaterial(D3dMaterialDesc mat);

Parameters

mat A D3dMaterialDesc object that receives the current material properties.

See Also

setMaterial


reserve (Direct3dMaterial Class)

 Microsoft SDK for Java

reserve

This method of the Direct3dMaterial Class is not currently implemented.

Syntax

public void reserve();


setMaterial (Direct3dMaterial Class)

 Microsoft SDK for Java

setMaterial

This method of the Direct3dMaterial Class sets the material data for the Direct3dMaterial object.

Syntax

public void setMaterial(D3dMaterialDesc mat);

Parameters

mat A D3dMaterialDesc object that contains the material properties to set.

See Also

getMaterial


unreserve (Direct3dMaterial Class)

 Microsoft SDK for Java

unreserve

This method of the Direct3dMaterial Class is not currently implemented.

Syntax

public void unreserve();


Direct3dRM Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRM Class

Applications use the methods of the Direct3dRM Class of the com.ms.directX package to create Direct3dRM objects and work with system-level variables.

public class Direct3dRM implements IDirect3dRM
{
  // Methods
  public void addSearchPath(String name);
  public Direct3dRMAnimation createAnimation();
  public Direct3dRMAnimationSet createAnimationSet();
  public int createColorRGB(float red, float green, float blue);
  public Direct3dRMDevice createDevice(int v1, int v2);
  public Direct3dRMDevice createDeviceFromClipper(DirectDrawClipper
        lpDDClipper, _Guid g, int width, int height);
  public Direct3dRMDevice createDeviceFromD3D(Direct3d direct3d,
        Direct3dDevice direct3dDevice));
  public Direct3dRMDevice createDeviceFromSurface(_Guid g,
        DirectDraw dd, DirectDrawSurface DDsBack);
  public Direct3dRMFace createFace();
  public Direct3dRMFrame createFrame(Direct3dRMFrame parent);
  public Direct3dRMLight createLight(int t, int c);
  public Direct3dRMLight createLightRGB(int lt, float vred,
        float vgreen, float vblue);
  public Direct3dRMMaterial createMaterial(float d);
  public Direct3dRMMesh createMesh();
  public Direct3dRMMeshBuilder createMeshBuilder();
  public Direct3dRMVisual createShadow(Direct3dRMVisual v,
        Direct3dRMLight l, float px, float py, float pz,
        float nx, float ny, float nz);
  public Direct3dRMVisual createShadowFromFrame(
        Direct3dRMFrame frame, Direct3dRMLight direct3dRMLight,
        float px, float py, float pz, float nx, float ny,
        float nz);
  public Direct3dRMVisual createShadowFromMesh(Direct3dRMMesh mesh,
        Direct3dRMLight direct3dRMLight, float px, float py,
        float pz, float nx, float ny, float nz);
  public Direct3dRMVisual createShadowFromMeshBuilder(
        Direct3dRMMeshBuilder mb, Direct3dRMLight l, float px,
        float py, float pz, float nx, float ny, float nz);
  public Direct3dRMTexture createTexture(D3dRMImage image,
        byte[] buffer1, byte[] pal);
  public Direct3dRMTexture createTextureFromSurface(
        DirectDrawSurface ddS);
  public Direct3dRMUserVisual createUserVisual(
        IUserVisualCallback fn, IUnknown Arg);
  public Direct3dRMViewport createViewport(Direct3dRMDevice dev,
        Direct3dRMFrame fr, int l, int t, int w, int h);
  public Direct3dRMWrap createWrap(int t, Direct3dRMFrame f,
        float ox, float oy, float oz, float dx, float dy,
        float dz, float ux, float uy, float uz, float ou,
        float ov, float su, float sv);
  public void enumerateObjects(IEnumerateObjectsCallback fn,
        IUnknown pArgs);
  public Direct3dRMDeviceArray getDevices();
  public Direct3dRMObject getNamedObject(String name);
  public String getSearchPath();
  public void loadFromFileByPos(String fnam, int[] id, _Guid g, int
        cnt, int options, ILoadCallback fn1, int[] arg1,
        ILoadTextureCallback fn2, int[] arg2, Direct3dRMFrame f);
  public Direct3dRMTexture loadTexture(String name);
  public Direct3dRMTexture loadTextureFromResource(int hnd);
  public void setDefaultTextureColors(int ds);
  public void setDefaultTextureShades(int ds);
  public void setSearchPath(String name);
  public void tick(float val);
  public void vectorAdd(D3dVector lpd, D3dVector lps1,
        D3dVector lps2);
  public void vectorCrossProduct(D3dvector lpd, D3dvector lps1,
        D3dvector lps2);
  public float vectorDotProduct(D3dVector lps1, D3dVector lps2);
  public float vectorModulus(D3dVector d);
  public void vectorNormalise(D3dvector d);
  public void vectorRandom(D3dVector d);
  public void vectorReflect(D3dVector lpd, D3dVector lpRay,
        D3dVector lpNorm);
  public void vectorRotate(D3dVector lpr, D3dVector lpv,
        D3dVector lpaxis, float theta);
  public void vectorScale(D3dVector lpd, D3dVector lps,
        float factor);
  public void vectorSubtract(D3dVector lpd, D3dVector lps1,
        D3dVector lps2);
}


Methods (Direct3dRM Class)

 Microsoft SDK for Java

Direct3dRM Class Methods

The Direct3dRM Class contains the following methods:

addSearchPath adds a list of directories to the end of the current file search path.
createAnimation creates an empty Direct3dRMAnimation object.
createAnimationSet creates an empty Direct3dRMAnimationSet object.
createColorRGB creates an RGB color value.
createDevice is not implemented on the Windows platform.
createDeviceFromClipper creates a Microsoft® Direct3DRM windows device by using a specified DirectDrawClipper object.
createDeviceFromD3D creates a Microsoft ®Direct3dRM Windows® device by using specified Direct3d objects.
createDeviceFromSurface creates a Microsoft® Windows® device for rendering from the specified DirectDraw surfaces.
createFace creates a Direct3dRMFace object.
createFrame creates a new child frame of the given parent frame.
createLight creates a new light source with the given type and color.
createLightRGB creates a new light source with the given type and color.
createMaterial creates a material with the given specular property.
createMesh creates a new mesh object with no faces.
createMeshBuilder creates a new mesh builder object.
createShadow creates a shadow by using the specified visual and light, projecting the shadow onto the specified plane.
createShadowFromFrame creates a shadow by using the specified frame and light, projecting the shadow onto the specified plane.
createShadowFromMesh creates a shadow by using the specified mesh and light, projecting the shadow onto the specified plane.
createShadowFromMeshBuilder creates a shadow by using the specified mesh builder and light, projecting the shadow onto the specified plane.
createTexture creates a texture from an image in memory.
createTextureFromSurface creates a texture from a specified DirectDraw surface.
createUserVisual creates an application-defined visual object, which can then be added to a scene and rendered by using an application-defined handler.
createViewport creates a viewport on a device with device coordinates (xPos, yPos) to (xPos + width, yPos + height).
createWrap creates a wrapping function that can be used to assign texture coordinates to faces and meshes.
enumerateObjects calls the callback function specified by the fn parameter on each of the active Direct3dRM objects.
getDevices returns all the Direct3dRM devices that have been created in the system.
getNamedObject retrieves a Direct3dRMObject object, given its name.
getSearchPath returns the current file search path.
loadFromFileByPos loads an object.
loadTexture loads a texture from the specified file.
loadTextureFromResource loads a texture from a specified resource.
setDefaultTextureColors sets the default colors to be used for a Direct3dRMTexture object.
setDefaultTextureShades sets the default shades to be used for an Direct3dRMTexture object.
setSearchPath sets the current file search path from a list of directories.
tick performs the Direct3dRM system heartbeat.
vectorAdd calculates the sum of two vectors.
vectorCrossProduct calculates the cross-product of two vectors.
vectorDotProduct calculates the dot-product of two vectors.
vectorModulus calculates the modulus of a vector.
vectorNormalise normalizes a vector.
vectorRandom randomizes a vector.
vectorReflect reflects a vector, given a vector ray and a vector normal.
vectorRotate rotates a vector, given a ray, vector, axis, and amount to rotate.
vectorScale scales one vector to another by a specified factor.
vectorSubtract subtracts one vector from another.


addSearchPath (Direct3dRM Class)

 Microsoft SDK for Java

addSearchPath

This method of the Direct3dRM Class adds a list of directories to the end of the current file search path.

Syntax

public void addSearchPath(String name);

Parameters

name A string specifying the path to add to the current search path.

Remarks

For Windows, the path should be a list of directories separated by semicolons (;).

See Also

setSearchPath


createAnimation (Direct3dRM Class)

 Microsoft SDK for Java

createAnimation

This method of the Direct3dRM Class creates an empty Direct3dRMAnimation object.

Syntax

public Direct3dRMAnimation createAnimation();

Return Value

Returns the Direct3dRMAnimation object if successful; otherwise, null.


createAnimationSet (Direct3dRM Class)

 Microsoft SDK for Java

createAnimationSet

This method of the Direct3dRM Class creates an empty Direct3dRMAnimationSet object.

Syntax

public Direct3dRMAnimationSet createAnimationSet();

Return Value

Returns the Direct3dRMAnimationSet object if successful; otherwise, null.


createColorRGB (Direct3dRM Class)

 Microsoft SDK for Java

createColorRGB

This method of the Direct3dRM Class creates an RGB color value.

Syntax

public int createColorRGB(float red, float green, float blue);

Return Value

Returns a color value.

Parameters

red | The red component of the color.
green | The green component of the color.
blue | The blue component of the color.


createDevice (Direct3dRM Class)

 Microsoft SDK for Java

createDevice

This method of the Direct3dRM Class is not implemented on the Windows platform.

Syntax

public Direct3dRMDevice createDevice(int v1, int v2);


createDeviceFromClipper (Direct3dRM Class)

 Microsoft SDK for Java

createDeviceFromClipper

This method of the Direct3dRM Class creates a Microsoft® Direct3DRM windows device by using a specified DirectDrawClipper object.

Syntax

public Direct3dRMDevice createDeviceFromClipper( DirectDrawClipper lpDDClipper, _Guid g, int width, int height);

Return Value

Returns the Direct3dRMDevice object if successful; otherwise, null.

Parameters

lpDDrawClipper | A DirectDrawClipper object.
g | A globally unique identifier (GUID). This parameter can be null.
width | The width of the device to be created.
height | The height of the device to be created.

Remarks

If the g parameter is null, the system searches for a device with a default set of device capabilities. This is the recommended way to create a Retained-Mode device because it always works, even if the user installs new hardware.

If a hardware device is not found, the monochromatic (ramp) software driver is loaded. An application should enumerate devices instead of specifying null for g if it has special needs that are not met by default settings.

If you are having palette problems using this method, try using the createDeviceFromD3D as an alternative.


createDeviceFromD3D (Direct3dRM Class)

 Microsoft SDK for Java

createDeviceFromD3D

This method of the Direct3dRM Class creates a Microsoft ®Direct3dRM Windows® device by using specified Direct3d objects. It is important that all objects are derived from the same DirectDraw object. In DirectX for Java, it is also important to use create methods to construct objects, rather than using new. Using new to create certain DirectX for Java objects creates uninitialized objects that can be difficult or impossible to manipulate.

See the createDeviceFromSurface method for a sample using standard techniques to create a Retain Mode object.

Syntax

public Direct3dRMDevice createDeviceFromD3D(Direct3d direct3d, Direct3dDevice direct3dDevice));

Return Value

Returns the Direct3dRMDevice object if successful; otherwise, null.

Parameters

direct3d | A Direct3D object.
direct3dDevice | A Direct3dDevice object.


createDeviceFromSurface (Direct3dRM Class)

 Microsoft SDK for Java

createDeviceFromSurface

This method of the Direct3dRM Class creates a Microsoft® Windows® device for rendering from the specified DirectDraw surfaces. It is important that all objects are derived from the same DirectDraw object. In DirectX for Java, it is also important to use create methods to construct objects, rather than using new. Using new to create certain DirectX for Java objects creates uninitialized objects that can be difficult or impossible to manipulate.

Syntax

public Direct3dRMDevice createDeviceFromSurface(_Guid g, DirectDraw dd, DirectDrawSurface DDsBack);

The following code example shows how to use the createDeviceFromSurface method and create appropriate objects without using new:

Example

int hw =0;  //depends on hardware
dd = new DirectDraw();
dd.setCooperativeLevel (this, DDSCL_NORMAL);

//Create a surface
ddsd = new DDSurfaceDesc();
ddsd.flags = DDSD_CAPS | DDSD_WIDTH | DDSD_HEIGHT;

if (hw==1){
ddsd.ddsCaps = DDSCAPS_3DDEVICE | DDSCAPS_OFFSCREENPLAIN
  | CAPS_VIDEOMEMORY;
}
else{
ddsd.ddsCaps = DDSCAPS_3DDEVICE | DDSCAPS_OFFSCREENPLAIN
  | DDSCAPS_SYSTEMMEMORY;
}
ddsd.width   = w;
ddsd.height  = h;
ddsOffscreen = dd.createSurface(ddsd);
d3d = dd.createD3D();

// Find the device's Guid for a device type specified by
// application info object - can be RGB or MONO
//
_Guid g = d3d.findDeviceForColorModel(D3DCOLOR_RGB, hw );
rmDevice = d3drm.createDeviceFromSurface(g, dd,ddsOffscreen);

Return Value

Returns the Direct3dRMDevice object if successful; otherwise, null.

Parameters

g | The globally unique identifier (GUID) used as the required device driver. If this parameter is null, the default device driver is used.
dd | The DirectDraw object that is the source of the DirectDraw surface.
DDsBack | The DirectDrawSurface object that represents the back buffer.


createFace (Direct3dRM Class)

 Microsoft SDK for Java

createFace

This method of the Direct3dRM Class creates a Direct3dRMFace object.

Syntax

public Direct3dRMFace createFace();

Return Value

Returns the Direct3dRMFace object if successful; otherwise, null.


createFrame (Direct3dRM Class)

 Microsoft SDK for Java

createFrame

This method of the Direct3dRM Class creates a new child frame of the given parent frame.

Syntax

public Direct3dRMFrame createFrame(Direct3dRMFrame parent);

Return Value

Returns the Direct3dRMFrame object if successful; otherwise, null.

Parameters

parent A frame object that is to be the parent of the new frame.

Remarks

The child frame inherits the motion attributes of its parent. For example, if the parent is moving with a given velocity, the child frame will also move with that velocity. Furthermore, if the parent is set rotating, the child frame will rotate about the origin of the parent. Frames that have no parent are called scenes. To create a scene, specify null as the parent. An application can create a frame with no parent, and then associate it with a parent frame later by using the addChild method.

See Also

com.ms.directX.Direct3dRMFrame


createLight (Direct3dRM Class)

 Microsoft SDK for Java

createLight

This method of the Direct3dRM Class creates a new light source with the given type and color.

Syntax

public Direct3dRMLight createLight(int t, int c);

Return Value

Returns the Direct3dRMLight object if successful; otherwise, null.

Parameters

t | One value of the D3DRMLIGHT_ type.
c | Color of the light.


createLightRGB (Direct3dRM Class)

 Microsoft SDK for Java

createLightRGB

This method of the Direct3dRM Class creates a new light source with the given type and color.

Syntax

public Direct3dRMLight createLightRGB(int lt, float vred, float vgreen, float vblue);

Return Value

Returns the Direct3dRMLight object if successful; otherwise, null.

Parameters

lt | One value of D3DRMLIGHT_ type.
vred | The red component of the color.
vgreen | The green component of the color.
vblue | The blue component of the color.


createMaterial (Direct3dRM Class)

 Microsoft SDK for Java

createMaterial

This method of the Direct3dRM Class creates a material with the given specular property.

Syntax

public Direct3dRMMaterial createMaterial(float d);

Return Value

Returns the Direct3dRMMaterial object if successful; otherwise, null.

Parameters

vPower Sharpness of the reflected highlights, with a value of 5 giving a metallic look and higher values giving a more "plastic" look to the rendered surface.


createMesh (Direct3dRM Class)

 Microsoft SDK for Java

createMesh

This method of the Direct3dRM Class creates a new mesh object with no faces. The mesh is not visible until it is added to a frame.

Syntax

public Direct3dRMMesh createMesh();

Return Value

Returns the Direct3dRMMesh object if successful; otherwise, null.


createMeshBuilder (Direct3dRM Class)

 Microsoft SDK for Java

createMeshBuilder

This method of the Direct3dRM Class creates a new mesh builder object.

Syntax

public Direct3dRMMeshBuilder createMeshBuilder();

Return Value

Returns the Direct3dRMMeshBuilder object if successful; otherwise, null.


createShadow (Direct3dRM Class)

 Microsoft SDK for Java

createShadow

This method of the Direct3dRM Class creates a shadow by using the specified visual and light, projecting the shadow onto the specified plane. The shadow is a visual that should be added to the frame that contains the visual.

Syntax

public Direct3dRMVisual createShadow(Direct3dRMVisual v, Direct3dRMLight , float px, float py, float pz, float nx, float ny, float nz);

Return Value

Returns the Direct3dRMVisual object if successful; otherwise, null.

Parameters

v | The Direct3dRMVisual object that is casting the shadow.
l | The Direct3dRMLight object that is the light source.
px | The x component of the plane that the shadow is to be projected on.
py | The y component of the plane that the shadow is to be projected on.
pz | The z component of the plane that the shadow is to be projected on.
nx | The x component of the normal to the plane that the shadow is to be projected on.
ny | The y component of the normal to the plane that the shadow is to be projected on.
nz | The z component of the normal to the plane that the shadow is to be projected on.


createShadowFromFrame (Direct3dRM Class)

 Microsoft SDK for Java

createShadowFromFrame

This method of the Direct3dRM Class creates a shadow by using the specified frame and light, projecting the shadow onto the specified plane. The shadow is a visual that should be added to the frame that contains the visual.

Syntax

public Direct3dRMVisual createShadowFromFrame(Direct3dRMFrame frame, Direct3dRMLight direct3dRMLight, float px, float py, float pz, float nx, float ny, float nz);

Return Value

Returns the Direct3dRMVisual object if successful; otherwise, null.

Parameters

frame | The Direct3dRMFrame object that is casting the shadow.
l | The Direct3dRMLight object that is the light source.
px | The x component of the plane that the shadow is to be projected on.
py | The y component of the plane that the shadow is to be projected on.
pz | The z component of the plane that the shadow is to be projected on.
nx | The x component of the normal to the plane that the shadow is to be projected on.
ny | The y component of the normal to the plane that the shadow is to be projected on.
nz | The z component of the normal to the plane that the shadow is to be projected on.


createShadowFromMesh (Direct3dRM Class)

 Microsoft SDK for Java

createShadowFromMesh

This method of the Direct3dRM Class creates a shadow by using the specified mesh and light, projecting the shadow onto the specified plane. The shadow is a visual that should be added to the frame that contains the visual.

Syntax

public Direct3dRMVisual createShadowFromMesh(Direct3dRMMesh mesh, Direct3dRMLight direct3dRMLight, float px, float py, float pz, float nx, float ny, float nz);

Return Value

Returns the Direct3dRMVisual object if successful; otherwise, null.

Parameters

mesh | The Direct3dRMMesh object that is casting the shadow.
l | The Direct3dRMLight object that is the light source.
px | The x component of the plane that the shadow is to be projected on.
py | The y component of the plane that the shadow is to be projected on.
pz | The z component of the plane that the shadow is to be projected on.
nx | The x component of the normal to the plane that the shadow is to be projected on.
ny | The y component of the normal to the plane that the shadow is to be projected on.
nz | The z component of the normal to the plane that the shadow is to be projected on.


createShadowFromMeshBuilder (Direct3dRM Class)

 Microsoft SDK for Java

createShadowFromMeshBuilder

This method of the Direct3dRM Class creates a shadow by using the specified mesh builder and light, projecting the shadow onto the specified plane. The shadow is a visual that should be added to the frame that contains the visual.

Syntax

public Direct3dRMVisual createShadowFromMeshBuilder( Direct3dRMMeshBuilder mb, Direct3dRMLight l, float px, float py, float pz, float nx, float ny,float nz);

Return Value

Returns the Direct3dRMVisual object if successful; otherwise, null.

Parameters

v | The Direct3dRMMeshBuilder object that is casting the shadow.
l | The Direct3dRMLight object that is the light source.
px | The x component of the plane that the shadow is to be projected on.
py | The y component of the plane that the shadow is to be projected on.
pz | The z component of the plane that the shadow is to be projected on.
nx | The x component of the normal to the plane that the shadow is to be projected on.
ny | The y component of the normal to the plane that the shadow is to be projected on.
nz | The z component of the normal to the plane that the shadow is to be projected on.


createTexture (Direct3dRM Class)

 Microsoft SDK for Java

createTexture

This method of the Direct3dRM Class creates a texture from an image in memory.

Syntax

public Direct3dRMTexture createTexture(D3dRMImage image, byte[] buffer1, byte[] pal);

Return Value

Returns the Direct3dRMTexture object if successful; otherwise, null.

Parameters

image | A Direct3dRMImage object describing the source for the texture.
buffer1 | The image buffer.
pal | The image palette.

Remarks

The memory associated with the image is used each time the texture is rendered (rather than the memory being copied into Direct3dRM's buffers). This allows the image to be used both as a rendering target and as a texture.


createTextureFromSurface (Direct3dRM Class)

 Microsoft SDK for Java

createTextureFromSurface

This method of the Direct3dRM Class creates a texture from a specified DirectDraw surface.

Syntax

public Direct3dRMTexture createTextureFromSurface(DirectDrawSurface ddS);

Return Value

Returns the Direct3dRMTexture object if successful; otherwise, null.

Parameters

ddS The DirectDrawSurface object containing the texture.


createUserVisual (Direct3dRM Class)

 Microsoft SDK for Java

createUserVisual

This method of the Direct3dRM Class creates an application-defined visual object, which can then be added to a scene and rendered by using an application-defined handler.

Syntax

public Direct3dRMUserVisual createUserVisual(IUserVisualCallback fn, IUnknown Arg);

Return Value

Returns the Direct3dRMUserVisual object if successful; otherwise, null.

Parameters

fn | A callback interface containing the application-defined callback function.
Arg | Application-defined data passed to the callback function.


createViewport (Direct3dRM Class)

 Microsoft SDK for Java

createViewport

This method of the Direct3dRM Class creates a viewport on a device with device coordinates (xPos, yPos) to (xPos + width, yPos + height).

Syntax

public Direct3dRMViewport createViewport(Direct3dRMDevice dev, Direct3dRMFrame fr, int l, int t, int w, int h);

Return Value

Returns the Direct3dRMViewport object if successful; otherwise, null.

Parameters

dev | The device that the viewport is to be created on.
fr | The frame that describes the position and direction of the view.
l | The x-coordinate of the upper-left corner of the viewport, in device coordinates.
t | The y-coordinate of the upper-left corner of the viewport, in device coordinates.
w | Width of the viewport, in device coordinates.
h | Height of the viewport, in device coordinates.

Remarks

The viewport displays objects in the scene that contains the camera, with the view direction and up vector taken from the camera.


createWrap (Direct3dRM Class)

 Microsoft SDK for Java

createWrap

This method of the Direct3dRM Class creates a wrapping function that can be used to assign texture coordinates to faces and meshes. The vector [ox oy oz] gives the origin of the wrap, [dx dy dz] gives its z-axis, and [ux uy uz] gives its y-axis. The 2D vectors [ou ov] and [su sv] give an origin and scale factor in the texture applied to the result of the wrapping function.

Syntax

public Direct3dRMWrap createWrap(int t, Direct3dRMFrame f, float ox, float oy, float oz, float dx, float dy, float dz, float ux, float uy, float uz, floatou, float ov, float su, float sv);

Return Value

Returns the Direct3dRMWrap object if successful; otherwise, null.

Parameters

t | One value of the D3DRMWRAP_ type.
f | The reference frame for the wrap.
ox | The x component of the wrap's origin.
oy | The y component of the wrap's origin.
oz | The z component of the wrap's origin
dx | The x component of the z-axis of the wrap.
dy | The y component of the z-axis of the wrap.
dz | The z component of the z-axis of the wrap.
ux | The x component of the y-axis of the wrap.
uy | The y component of the y-axis of the wrap.
uz | The z component of the y-axis of the wrap.
ou | Origin in the texture.
ov | Origin in the texture.
su | Scale factor in the texture.
sv | Scale factor in the texture.


enumerateObjects (Direct3dRM Class)

 Microsoft SDK for Java

enumerateObjects

This method of the Direct3dRM Class calls the callback function specified by the fn parameter on each of the active Direct3dRM objects.

Syntax

public void enumerateObjects(IEnumerateObjectsCallback fn, IUnknown pArgs);

Parameters

fn | A callback interface that contains an application-defined callback function to be called with each Direct3dRMObject object and the application-defined argument.
pArgs | Application-defined data passed to the callback function.


getDevices (Direct3dRM Class)

 Microsoft SDK for Java

getDevices

This method of the Direct3dRM Class returns all the Direct3dRM devices that have been created in the system.

Syntax

public Direct3dRMDeviceArray getDevices();

Return Value

Returns the Direct3dRMDeviceArray object if successful; otherwise, null.


getNamedObject (Direct3dRM Class)

 Microsoft SDK for Java

getNamedObject

This method of the Direct3dRM Class retrieves a Direct3dRMObject object, given its name.

Syntax

public Direct3dRMObject getNamedObject(String name);

Return Value

Returns the Direct3dRMObject object if successful; otherwise, null.

Parameters

name The name of the object to be searched for.


getSearchPath (Direct3dRM Class)

 Microsoft SDK for Java

getSearchPath

This method of the Direct3dRM Class returns the current file search path.

Syntax

public String getSearchPath();

Return Value

Returns a string specifying the search path.

See Also

setSearchPath


loadFromFileByPos (Direct3dRM Class)

 Microsoft SDK for Java

loadFromFileByPos

This method of the Direct3dRM Class loads an object. This method enables you to inspect an X file and decide what object to load, using the ILoadCallback interface.

Syntax

public void loadFromFileByPos(String fnam, int[] id, _Guid g, int cnt, int options, ILoadCallback fn1, int[] arg1, ILoadTextureCallbck fn2, int[] arg2, Direct3dRMFrame f);

The following example shows how this method can be used:

Example

//Indicate what type of objects will be sent to the callback.

IID_IDirect3DRMFrame.set(0xeb16cb03, (short)0xd271,(short) 0x11ce,
 (byte)0xac, (byte)0x48, (byte)0x0,(byte) 0x0,(byte) 0xc0, (byte)0x38,
 (byte)0x25, (byte)0xa1);
IID_IDirect3DRMMeshBuilder.set(0xa3a80d02, (short)0x6e12, (short)0x11cf,
 (byte)0xac, (byte)0x4a, (byte)0x0, (byte)0x0, (byte)0xc0, (byte)0x38,
 (byte)0x25, (byte)0xa1);
IID_IDirect3DRMAnimationSet.set(0xeb16cb0e, (short)0xd271,(short) 0x11ce,
 (byte)0xac, (byte)0x48, (byte)0x0, (byte)0x0, (byte)0xc0, (byte)0x38,
 (byte)0x25, (byte)0xa1);

// If you use 0, you will retrieve all objects.
d3drm.loadFromFileByPos(sFile,
    null, IID_IDirect3DRMFrame, 1,
    D3DRM_LOADFROMFILE, this,
    null, this,
    null, f_env);

public void callbackLoad(Direct3dRMObject obj, _Guid id, IUnknown Arg)
{
    String sType=obj.getClassName();
    if (sType.equals("Frame"))
    {
         Direct3dRMFrame f=obj.getd3drmFrame();
         f_env.addChild(f);
    }
    if (sType.equals("Builder"))
    {
         Direct3dRMMeshBuilder m=obj.getd3drmMeshBuilder();
         System.out.println("OK to convert");
         f_env.addVisualMeshBuilder(m);
    }
}
// other callbacks ...

Parameters

fnam | The name of the file that the object is loaded from.
id | The object position. The value of the first variable in the array gives the object's order in the file.
g | The interface identifier to be loaded.
cnt | The number of identifiers specified in the g parameter.
options | A load options type.
fn1 | The callback interface that contains a load callback function called when the system reads the specified object.
arg1 | Application-defined data passed to the load callback function.
fn2 | The callback interface that contains a load texture callback function called to load any textures used by an object that require special formatting. This parameter can be null.
arg2 | Application-defined data passed to the load texture callback function.
f | A parent frame. This information is useful when loading Direct3dRMAnimationSet or Direct3dRMFrame objects because otherwise, these objects would be created with a null parent. This value can be null.


loadTexture (Direct3dRM Class)

 Microsoft SDK for Java

loadTexture

This method of the Direct3dRM Class loads a texture from the specified file. This texture can have 8, 24, or 32 bits-per-pixel, and it should be in either the Windows bitmap (.bmp) or Portable Pixmap (.ppm) P6 format.

Syntax

public Direct3dRMTexture loadTexture(String name);

Return Value

Returns the Direct3dRMTexture object if successful; otherwise, null.

Parameters

name The name of the required .bmp or .ppm file.


loadTextureFromResource (Direct3dRM Class)

 Microsoft SDK for Java

loadTextureFromResource

This method of the Direct3dRM Class loads a texture from a specified resource. Because it is difficult to obtain resource handles, this method is rarely used in Java.

Syntax

public Direct3dRMTexture loadTextureFromResource(int hnd);

Return Value

Returns the Direct3dRMTexture object if successful; otherwise, null.

Parameters

hnd Handle of the resource.


setDefaultTextureColors (Direct3dRM Class)

 Microsoft SDK for Java

setDefaultTextureColors

This method of the Direct3dRM Class sets the default colors to be used for a Direct3dRMTexture object.

Syntax

public void setDefaultTextureColors(int ds);

Parameters

ds Number of colors.

Remarks

This method affects texture colors only when it is called before the createTexture method; it has no effect on textures that have already been created.


setDefaultTextureShades (Direct3dRM Class)

 Microsoft SDK for Java

setDefaultTextureShades

This method of the Direct3dRM Class sets the default shades to be used for an Direct3dRMTexture object.

Syntax

public void setDefaultTextureShades(int ds);

Parameters

ds The number of shades.

Remarks

This method affects texture shades only when it is called before the createTexture method; it has no effect on textures that have already been created.


setSearchPath (Direct3dRM Class)

 Microsoft SDK for Java

setSearchPath

This method of the Direct3dRM Class sets the current file search path from a list of directories.

Syntax

public void setSearchPath(String name);

Parameters

name A string specifying the path to set as the current search path.

Remarks

The default search path is taken from the value of the D3DPATH environment variable. If this is not set, the search path will be empty. When opening a file, the system first looks for the file in the current working directory, and then checks every directory in the search path.

See Also

getSearchPath


tick (Direct3dRM Class)

 Microsoft SDK for Java

tick

This method of the Direct3dRM Class performs the Direct3dRM system heartbeat. When this method is called, the positions of all moving frames are updated according to their current motion attributes, the scene is rendered to the current device, and relevant callback functions are called at their appropriate times. Control is returned when the rendering cycle is complete.

Syntax

public void tick(float val);

Parameters

val The velocity and rotation step for the setRotation and setVelocity methods.

Remarks

You can implement this method by using other Retained-Mode methods to allow more flexibility in rendering a scene.


vectorAdd (Direct3dRM Class)

 Microsoft SDK for Java

vectorAdd

This method of the Direct3dRM Class calculates the sum of two vectors.

Syntax

public void vectorAdd(D3dVector lpd, D3dVector lps1, D3dVector lps2);

Parameters

lpd | A D3dVector object that receives the sum of lps1 and lps2.
lps1 | A D3dVector object that contains a vector.
lps2 | A D3dVector object that contains a vector.


vectorCrossProduct (Direct3dRM Class)

 Microsoft SDK for Java

vectorCrossProduct

This method of the Direct3dRM Class calculates the cross-product of two vectors.

Syntax

public void vectorCrossProduct(D3dvector lpd, D3dvector lps1, D3dvector lps2);

Parameters

lpd | A D3dVector object that receives the cross product.
lps1 | A D3dVector object that contains a vector.
lps2 | A D3dVector object that contains a vector.


vectorDotProduct (Direct3dRM Class)

 Microsoft SDK for Java

vectorDotProduct

This method of the Direct3dRM Class calculates the dot-product of two vectors.

Syntax

public float vectorDotProduct(D3dVector lps1, D3dVector lps2);

Return Value

Returns the result of the operation.

Parameters

lps1 | A D3dVector object that contains a vector.
lps2 | A D3dVector object that contains a vector.


vectorModulus (Direct3dRM Class)

 Microsoft SDK for Java

vectorModulus

This method of the Direct3dRM Class calculates the modulus of a vector.

Syntax

public float vectorModulus(D3dVector d);

Return Value

Returns a float that is the remainder of the modulus operation.

Parameters

d The vector to mod.


vectorNormalise (Direct3dRM Class)

 Microsoft SDK for Java

vectorNormalise

This method of the Direct3dRM Class normalizes a vector.

Syntax

public void vectorNormalise(D3dvector d);

Parameters

d A D3dVector object that contains the vector to normalize. This object also receives the normalized vector.


vectorRandom (Direct3dRM Class)

 Microsoft SDK for Java

vectorRandom

This method of the Direct3dRM Class randomizes a vector.

Syntax

public void vectorRandom(D3dVector d);

Parameters

d A D3dVector object that contains the vector to randomize. This object also receives the randomized vector.


vectorReflect (Direct3dRM Class)

 Microsoft SDK for Java

vectorReflect

This method of the Direct3dRM Class reflects a vector, given a vector ray and a vector normal.

Syntax

public void vectorReflect(D3dVector lpd, D3dVector lpRay, D3dVector lpNorm);

Parameters

lpd | The resulting D3dVector from the operation.
lpRay | A D3dVector ray.
lpNorm | A D3dVector normal.


vectorRotate (Direct3dRM Class)

 Microsoft SDK for Java

vectorRotate

This method of the Direct3dRM Class rotates a vector, given a ray, vector, axis, and amount to rotate.

Syntax

public void vectorRotate(D3dVector lpr, D3dVector lpv, D3dVector lpaxis, float theta);

Parameters

lpr | A D3dVector ray.
lpv | A D3dVector vector.
lpaxis | A D3dVector axis.
theta | The amount to rotate the vector (in radians).


vectorScale (Direct3dRM Class)

 Microsoft SDK for Java

vectorScale

This method of the Direct3dRM Class scales one vector to another by a specified factor.

Syntax

public void vectorScale(D3dVector lpd, D3dVector lps, float factor);

Parameters

lpd | A D3dVector object that receives the result of the scaling operation.
lps | A D3dVector object that contains the source vector.
The | factor to scale lps by.


vectorSubtract (Direct3dRM Class)

 Microsoft SDK for Java

vectorSubtract

This method of the Direct3dRM Class subtracts one vector from another.

Syntax

public void vectorSubtract(D3dVector lpd, D3dVector lps1, D3dVector lps2);

Parameters

lpd | A D3dVector object that receives the result of the subtraction.
lps1 | A D3dVector object that contains a vector.
lps2 | A D3dVector object that contains a vector.


Direct3dRMAnimation Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMAnimation Class

Applications use the methods of the Direct3dRMAnimation Class of the com.ms.directX package to animate the position, orientation, and scaling of visuals, lights, and viewports.

public class Direct3dRMAnimation implements
            IDirect3dRMAnimation
{
  // Methods
  public void addPositionKey(float time, float x, float y, float z);
  public void addRotateKey(float time, D3dRMQuaternion q);
  public void addScaleKey(float time, float x, float y, float z);
  public void deleteKey(float time);
  public int getOptions();
  public void setFrame(Direct3dRMFrame frame);
  public void setOptions(int flags);
  public void setTime(float time);
}

The Direct3dRMAnimation class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName


Methods (Direct3dRMAnimation Class)

 Microsoft SDK for Java

Direct3dRMAnimation Class Methods

The Direct3dRMAnimation Class contains the following methods:

addPositionKey adds a position key to the animation.
addRotateKey adds a rotate key to the animation.
addScaleKey adds a scale key to the animation.
deleteKey removes a key from an animation.
getOptions retrieves animation options.
setFrame sets the frame for the animation.
setOptions sets the animation options.
setTime sets the current time for this animation.


addPositionKey (Direct3dRMAnimation Class)

 Microsoft SDK for Java

addPositionKey

This method of the Direct3dRMAnimation Class adds a position key to the animation.

Syntax

public void addPositionKey(float time, float x, float y, float z);

Parameters

time | The time in the animation to store the position key. The time units are arbitrary and zero-based; a key whose time value is 49 occurs exactly in the middle of an animation, whose last key has an time value of 99.
x | The x component of the position.
y | The y component of the position.
z | The z component of the position.

Remarks

The transformation applied by this method is a translation.


addRotateKey (Direct3dRMAnimation Class)

 Microsoft SDK for Java

addRotateKey

This method of the Direct3dRMAnimation Class adds a rotate key to the animation.

Syntax

public void addRotateKey(float time, D3dRMQuaternion q);

Parameters

time | The time in the animation to store the rotate key. The time units are arbitrary and zero-based; a key whose time value is 49 occurs exactly in the middle of an animation, whose last key has an time value of 99.
q | D3dRMQuaternion representing the rotation.

Remarks

This method applies a rotation transformation.

See Also

deleteKey


addScaleKey (Direct3dRMAnimation Class)

 Microsoft SDK for Java

addScaleKey

This method of the Direct3dRMAnimation Class adds a scale key to the animation.

Syntax

public void addScaleKey(float time, float x, float y, float z);

Parameters

time | The time in the animation to store the scale key. The time units are arbitrary and zero-based; a key whose time value is 49 occurs exactly in the middle of an animation, whose last key has an time value of 99.
x | The x component of the scale factor.
y | The y component of the scale factor.
z | The z component of the scale factor.

Remarks

This method applies a scaling transformation.

See Also

deleteKey


deleteKey (Direct3dRMAnimation Class)

 Microsoft SDK for Java

deleteKey

This method of the Direct3dRMAnimation Class removes a key from an animation.

Syntax

public void deleteKey(float time);

Parameters

time The time identifying the key that will be removed from the animation.


getOptions (Direct3dRMAnimation Class)

 Microsoft SDK for Java

getOptions

This method of the Direct3dRMAnimation Class retrieves animation options.

Syntax

public int getOptions();

Return Value

Returns the value of an animation option type describing the animation options.

See Also

setOptions


setFrame (Direct3dRMAnimation Class)

 Microsoft SDK for Java

setFrame

This method of the Direct3dRMAnimation Class sets the frame for the animation.

Syntax

public void setFrame(Direct3dRMFrame frame);

Parameters

frame The Direct3dRMFrame object to set for the animation.


setOptions (Direct3dRMAnimation Class)

 Microsoft SDK for Java

setOptions

This method of the Direct3dRMAnimation Class sets the animation options.

Syntax

public void setOptions(int flags);

Parameters

flags The value of animation option type describing the animation options.

See Also

getOptions


setTime (Direct3dRMAnimation Class)

 Microsoft SDK for Java

setTime

This method of the Direct3dRMAnimation Class sets the current time for this animation.

Syntax

public void setTime(float time);

Parameters

time The new current time for the animation. The time units are arbitrary and zero-based; a key, whose time value is 49, occurs exactly in the middle of an animation, whose last key has an time value of 99.


Direct3dRMAnimationSet Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMAnimationSet Class

Applications use the methods of the Direct3dRMAnimationSet Class of the com.ms.directX package to group Direct3dRMAnimation objects together, which can simplify the playback of complex animation sequences.

public class Direct3dRMAnimationSet implements
            IDirect3dRMAnimationSet
{
  // Methods
  public void addAnimation(Direct3dRMAnimation aid);
  public void deleteAnimation(Direct3dRMAnimation aid);
  public void loadFromFileByPos(String filename, int position,
        int flags, ILoadTextureCallback c, IUnknown pUser,
        Direct3dRMFrame f);
  public void setTime(float time);
}

The Direct3dRMAnimationSet class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

The Direct3dRMAnimationSet object is obtained by calling the createAnimationSet method.


Methods (Direct3dRMAnimationSet Class)

 Microsoft SDK for Java

Direct3dRMAnimationSet Class Methods

The Direct3dRMAnimationSet Class contains the following methods:

addAnimation adds an animation to the animation set.
deleteAnimation removes a previously added animation from the animation set.
loadFromFileByPos loads an animation set.
setTime sets the time for the animation set.


addAnimation (Direct3dRMAnimationSet Class)

 Microsoft SDK for Java

addAnimation

This method of the Direct3dRMAnimationSet Class adds an animation to the animation set.

Syntax

public void addAnimation(Direct3dRMAnimation aid);

Parameters

aid The Direct3dRMAnimation object to be added to the animation set.


deleteAnimation (Direct3dRMAnimationSet Class)

 Microsoft SDK for Java

deleteAnimation

This method of the Direct3dRMAnimationSet Class removes a previously added animation from the animation set.

Syntax

public void deleteAnimation(Direct3dRMAnimation aid);

Parameters

aid The Direct3dRMAnimation object to be removed from the animation set.


loadFromFileByPos (Direct3dRMAnimationSet Class)

 Microsoft SDK for Java

loadFromFileByPos

This method of the Direct3dRMAnimationSet Class loads an animation set.

Syntax

public void loadFromFileByPos(String filename, int position, int flags, ILoadTextureCallback c, IUnknown pUser, Direct3dRMFrame f);

Parameters

filename | The name of the file that the object is to be loaded from.
position | The position in the file to be loaded from. The value gives the object's order in the file. This parameter can be null.
flags | A load options type.
c | The callback interface that contains the load texture callback function called to load any textures used by the object that require special formatting. This parameter can be null.
pUser | Application-defined data passed to the load texture callback function.
f | The parent Direct3dRMFrame object. This prevents the frames referred to by the animation set from being created with a null parent.

Remarks

By default, this method loads the first animation set in the file specified by the objSource parameter.


setTime (Direct3dRMAnimationSet Class)

 Microsoft SDK for Java

setTime

This method of the Direct3dRMAnimationSet Class sets the time for the animation set.

Syntax

public void setTime(float time);

Parameters

time The new time.


Direct3dRMArray Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMArray Class

The Direct3dRMArray Class of the com.ms.directX package organizes groups of objects. Applications typically use array objects that are subsidiary to this class (rather than use this class directly).

public class Direct3dRMArray implements IDirect3dRMArray
{
  // Methods
  public int getSize();
}


Methods (Direct3dRMArray Class)

 Microsoft SDK for Java

Direct3dRMArray Class Methods

The Direct3dRMArray Class contains the following method:

getSize retrieves the number of objects associated with this array object.


getSize (Direct3dRMArray Class)

 Microsoft SDK for Java

getSize

This method of the Direct3dRMArray Class retrieves the number of objects associated with this array object.

Syntax

public int getSize();

Return Value

Returns the number of objects.


Direct3dRMDevice Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMDevice Class

Applications use the methods of the Direct3dRMDevice Class of the com.ms.directX package to interact with the output device.

public class Direct3dRMDevice implements IDirect3dRMDevice
{
  // Methods
  public void addUpdateCallback(IDeviceUpdateCallback fn,
        IUnknown args);
  public void deleteUpdateCallback(IDeviceUpdateCallback fn,
        IUnknown args);
  public int getBufferCount();
  public int getColorModel();
  public Direct3dRMWinDevice getd3drmWinDevice();
  public Direct3dDevice getDirect3DDevice();
  public int getDither();
  public int getHeight();
  public int getQuality();
  public int getShades();
  public int getTextureQuality();
  public int getTrianglesDrawn();
  public Direct3dRMViewportArray getViewports();
  public int getWidth();
  public int getWireframeOptions();
  public void init(int width, int height);
  public void setBufferCount(int count);
  public void setDither(int dith);
  public void setQuality(int q);
  public void setShades(int s);
  public void setTextureQuality(int d);
  public void update();
}

The Direct3dRMDevice class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

The Direct3dRMDevice object is obtained by calling the createDevice method.


Methods (Direct3dRMDevice Class)

 Microsoft SDK for Java

Direct3dRMDevice Class Methods

The Direct3dRMDevice Class contains the following methods:

addUpdateCallback adds a callback function that alerts the application when a change occurs to the device.
deleteUpdateCallback removes an update callback function that was added by calling the addUpdateCallback method.
getBufferCount retrieves the value set in a call to the setBufferCount method.
getColorModel retrieves the color model of a device.
getd3drmWinDevice retrieves the Microsoft® Windows® device associated with this Retained-Mode device.
getDirect3DDevice retrieves an Immediate-Mode device.
getDither retrieves the dither flag for the device.
getHeight retrieves the height, in pixels, of a device. This method is a convenience function.
getQuality retrieves the rendering quality for the device.
getShades retrieves the number of shades in a ramp of colors used for shading.
getTextureQuality retrieves the current texture quality parameter for the device.
getTrianglesDrawn retrieves the number of triangles drawn to a device since its creation.
getViewports constructs a Direct3dRMViewportArray object that represents the viewports currently constructed from the device.
getWidth retrieves the width, in pixels, of a device.
getWireframeOptions retrieves the wireframe options of a given device.
init is not implemented on the Windows platform.
setBufferCount sets the number of buffers currently being used by the application.
setDither sets the dither flag for the device.
setQuality sets the rendering quality of a device
setShades sets the number of shades in a ramp of colors used for shading.
setTextureQuality sets the texture quality for the device.
update copies the image that has been rendered to the display and provides a heartbeat function to the device driver.


addUpdateCallback (Direct3dRMDevice Class)

 Microsoft SDK for Java

addUpdateCallback

This method of the Direct3dRMDevice Class adds a callback function that alerts the application when a change occurs to the device. The system calls this callback function whenever the application calls the update method.

Syntax

public void addUpdateCallback(IDeviceUpdateCallback fn, IUnknown args);

Parameters

fn | The callback interface that contains an application-defined callback function.
args | Private data to be passed to the update callback function.

See Also

deleteUpdateCallback, update


deleteUpdateCallback (Direct3dRMDevice Class)

 Microsoft SDK for Java

deleteUpdateCallback

This method of the Direct3dRMDevice Class removes an update callback function that was added by calling the addUpdateCallback method.

Syntax

public void deleteUpdateCallback(IDeviceUpdateCallback fn, IUnknown args);

Parameters

fn | The callback interface that contains an application-defined callback function.
args | Private data that was passed to the update callback function.

See Also

addUpdateCallback, update


getBufferCount (Direct3dRMDevice Class)

 Microsoft SDK for Java

getBufferCount

This method of the Direct3dRMDevice Class retrieves the value set in a call to the setBufferCount method.

Syntax

public int getBufferCount();

Return Value

Returns the number of buffers—one for single-buffering, two for double-buffering, and so on.


getColorModel (Direct3dRMDevice Class)

 Microsoft SDK for Java

getColorModel

This method of the Direct3dRMDevice Class retrieves the color model of a device.

Syntax

public int getColorModel();

Return Value

Returns a value of D3DCOLOR_ type that describes the Direct3D color model (RGB or monochrome).


getd3drmWinDevice (Direct3dRMDevice Class)

 Microsoft SDK for Java

getd3drmWinDevice

This method of the Direct3dRMDevice Class retrieves the Microsoft® Windows® device associated with this Retained-Mode device.

Syntax

public Direct3dRMWinDevice getd3drmWinDevice();

Return Value

Returns the Direct3dRMWinDevice object if successful; otherwise, returns null.


getDirect3DDevice (Direct3dRMDevice Class)

 Microsoft SDK for Java

getDirect3DDevice

This method of the Direct3dRMDevice Class retrieves an Immediate-Mode device.

Syntax

public Direct3dDevice getDirect3DDevice();

Return Value

Returns the Direct3dDevice object if successful; otherwise, null.


getDither (Direct3dRMDevice Class)

 Microsoft SDK for Java

getDither

This method of the Direct3dRMDevice Class retrieves the dither flag for the device.

Syntax

public int getDither();

Return Value

Returns true if the dither flag is set; otherwise, returns false.


getHeight (Direct3dRMDevice Class)

 Microsoft SDK for Java

getHeight

This method of the Direct3dRMDevice Class retrieves the height, in pixels, of a device. This method is a convenience function.

Syntax

public int getHeight();

Return Value

Returns the height.


getQuality (Direct3dRMDevice Class)

 Microsoft SDK for Java

getQuality

This method of the Direct3dRMDevice Class retrieves the rendering quality for the device.

Syntax

public int getQuality();

Return Value

Returns one or more values of the render quality type.

See Also

setQuality


getShades (Direct3dRMDevice Class)

 Microsoft SDK for Java

getShades

This method of the Direct3dRMDevice Class retrieves the number of shades in a ramp of colors used for shading.

Syntax

public int getShades();

Return Value

Returns the number of shades.

See Also

setShades


getTextureQuality (Direct3dRMDevice Class)

 Microsoft SDK for Java

getTextureQuality

This method of the Direct3dRMDevice Class retrieves the current texture quality parameter for the device. Texture quality is relevant only for an RGB device.

Syntax

public int getTextureQuality();

Return Value

Returns a value of texture quality type.

See Also

setTextureQuality


getTrianglesDrawn (Direct3dRMDevice Class)

 Microsoft SDK for Java

getTrianglesDrawn

This method of the Direct3dRMDevice Class retrieves the number of triangles drawn to a device since its creation. This method is a convenience function.

Syntax

public int getTrianglesDrawn();

Return Value

Returns the number of triangles.

Remarks

The number of triangles includes those that were passed to the renderer, but were not drawn because they were backfacing. The number does not include triangles that were rejected for lying outside of the viewing frustum.


getViewports (Direct3dRMDevice Class)

 Microsoft SDK for Java

getViewports

This method of the Direct3dRMDevice Class constructs a Direct3dRMViewportArray object that represents the viewports currently constructed from the device.

Syntax

public Direct3dRMViewportArray getViewports();

Return Value

Returns the Direct3dRMViewportArray object if successful; otherwise, returns null.


getWidth (Direct3dRMDevice Class)

 Microsoft SDK for Java

getWidth

This method of the Direct3dRMDevice Class retrieves the width, in pixels, of a device. This method is a convenience function.

Syntax

public int getWidth();

Return Value

Returns the width.


getWireframeOptions (Direct3dRMDevice Class)

 Microsoft SDK for Java

getWireframeOptions

This method of the Direct3dRMDevice Class retrieves the wireframe options of a given device.

Syntax

public int getWireframeOptions();

Return Value

Returns a combination of values of D3DRMWIREFRAME_ type.


init (Direct3dRMDevice Class)

 Microsoft SDK for Java

init

This method of the Direct3dRMDevice Class is not implemented on the Windows platform.

Syntax

public void init(int width, int height);


setBufferCount (Direct3dRMDevice Class)

 Microsoft SDK for Java

setBufferCount

This method of the Direct3dRMDevice Class sets the number of buffers currently being used by the application.

Syntax

public void setBufferCount(int count);

Parameters

count Specifies the number of buffers— one for single-buffering, two for double-buffering, and so on. The default value is 1, which is correct only for single-buffered window operation.

Remarks

An application that employs double-buffering or triple-buffering must use this method to inform the system of how many buffers it is using so that the system can calculate how much of the window to clear and update on each frame.

See Also

getBufferCount


setDither (Direct3dRMDevice Class)

 Microsoft SDK for Java

setDither

This method of the Direct3dRMDevice Class sets the dither flag for the device.

Syntax

public void setDither(int dith);

Parameters

dith The new dithering mode for the device; the value can be true or false.

Remarks

By default, a device's dither flag is initially set to true.

See Also

getDither


setQuality (Direct3dRMDevice Class)

 Microsoft SDK for Java

setQuality

This method of the Direct3dRMDevice Class sets the rendering quality of a device

Syntax

public void setQuality(int q);

Parameters

q One or more values of the render quality type.

Remarks

The rendering quality is the maximum quality at which rendering can take place on the rendering surface of that device. Each mesh can have its own quality, but the maximum quality available for a mesh is that of the device. Different devices can have different qualities. For example, previewing devices usually have a lower quality, while devices used for final viewing usually have a higher quality.

By default, a device's rendering quality is initially set to D3DRMRENDER_FLAT.

See Also

getQuality


setShades (Direct3dRMDevice Class)

 Microsoft SDK for Java

setShades

This method of the Direct3dRMDevice Class sets the number of shades in a ramp of colors used for shading.

Syntax

public void setShades(int s);

Parameters

s The new number of shades. This parameter must be a power of 2.

Remarks

By default, a device's number of shades is initially set to 32.

See Also

getShades


setTextureQuality (Direct3dRMDevice Class)

 Microsoft SDK for Java

setTextureQuality

This method of the Direct3dRMDevice Class sets the texture quality for the device.

Syntax

public void setTextureQuality(int d);

Parameters

d One value of the texture quality type.

Remarks

By default, a device's texture quality is initially set to D3DRMTEXTURE_NEAREST.

See Also

getTextureQuality


update (Direct3dRMDevice Class)

 Microsoft SDK for Java

update

This method of the Direct3dRMDevice Class copies the image that has been rendered to the display and provides a heartbeat function to the device driver.

Syntax

public void update();

emarks

Each call to this method causes the system to call an application-defined callback function. To add a callback function, use the addUpdateCallback method.

See Also

addUpdateCallback, com.ms.directX.Direct3dRMViewport.forceupdate


Direct3dRMDeviceArray Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMDeviceArray Class

Applications use the methods of the Direct3dRMDeviceArray Class of the com.ms.directX package to organize device objects.

public class Direct3dRMDeviceArray implements
            IDirect3dRMDeviceArray
{
  // Methods
  public Direct3dRMDevice getElement(int index);
  public int getSize();
}

The Direct3dRMDeviceArray object is obtained by calling the getDevices method.


Methods (Direct3dRMDeviceArray Class)

 Microsoft SDK for Java

Direct3dRMDeviceArray Class Methods

The Direct3dRMDeviceArray Class contains the following methods:

getElement retrieves one of the Direct3dRMDevice objects associated with this object.
getSize retrieves the number of Direct3dRMDevice objects associated with this object.


getElement (Direct3dRMDeviceArray Class)

 Microsoft SDK for Java

getElement

This method of the Direct3dRMDeviceArray Class retrieves one of the Direct3dRMDevice objects associated with this object.

Syntax

public Direct3dRMDevice getElement(int index);

Return Value

Returns the Direct3dRMDevice object if successful; otherwise, returns null.

Parameters

index Identifies the object to return. Must be a value in the range 0 to one less than the number returned by the getSize method.


getSize (Direct3dRMDeviceArray Class)

 Microsoft SDK for Java

getSize

This method of the Direct3dRMDeviceArray Class retrieves the number of Direct3dRMDevice objects associated with this object.

Syntax

public int getSize();

Return Value

Returns the number of objects.


Direct3dRMFace Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMFace Class

Applications use the methods of the Direct3dRMFace Class of the com.ms.directX package to interact with a single polygon in a mesh.

public class Direct3dRMFace implements IDirect3dRMFace
{
  // Methods
  public void addVertex(float x, float y, float z);
  public void addVertexAndNormalIndexed(int vertex, int normal);
  public int getColor();
  public Direct3dRMMaterial getMaterial();
  public void getNormal(D3dVector val);
  public Direct3dRMTexture getTexture();
  public int getTextureCoordinateIndex(int which);
  public void getTextureCoordinates(int vertex, float[] u,
        float[] v);
  public void getTextureTopology(int[] u, int[] v);
  public void getVertex(int idx, D3dVector vert, D3dVector norm);
  public int getVertexCount();
  public int getVertexIndex(int which);
  public void getVertices(int vCount, D3dVector[] v, D3dVector[] n);
  public void getVerticesAsFloats(int[] vertex_cnt,
        D3dVector coord, D3dVector normals);
  public void getVerticesSize(int[] v_cnt);
  public void setColor(int c);
  public void setColorRGB(float r, float g, float b);
  public void setMaterial(Direct3dRMMaterial ref);
  public void setTexture(Direct3dRMTexture ref);
  public void setTextureCoordinates(int vertex, float u, float v);
  public void setTextureTopology(int wrap_u, int wrap_v);
}

The Direct3dRMFace class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

The Direct3dRMFace object is obtained by calling the createFace method.


Methods (Direct3dRMFace Class)

 Microsoft SDK for Java

Direct3dRMFace Class Methods

The Direct3dRMFace Class contains the following methods:

addVertex adds a vertex to a Direct3dRMFace object.
addVertexAndNormalIndexed adds a vertex and a normal to a Direct3dRMFace object by using an index for the vertex and an index for the normal in the containing mesh builder.
getColor retrieves the color of a Direct3dRMFace object.
getMaterial retrieves the material of a Direct3dRMFace object.
getNormal retrieves the normal vector of a Direct3dRMFace object.
getTexture retrieves the Direct3dRMTexture object applied to a Direct3dRMFace object.
getTextureCoordinateIndex retrieves the index of the vertex for texture coordinates in the face's mesh.
getTextureCoordinates retrieves the texture coordinates of a vertex in a Direct3dRMFace object.
getTextureTopology retrieves the texture topology of a Direct3dRMFace object.
getVertex retrieves the position and normal of a vertex in a Direct3dRMFace object.
getVertexCount retrieves the number of vertices in a Direct3dRMFace object.
getVertexIndex retrieves the index of the vertex in the face's mesh.
getVertices retrieves the position and normal vector of each vertex in a Direct3dRMFace object.
getVerticesAsFloats retrieves the position and normal vector of each vertex in a Direct3dRMFace object (as floats).
getVerticesSize retrieves the number of vertices associated with a Direct3dRMFacej object.
setColor sets a Direct3dRMFace object to a given color.
setColorRGB sets a Direct3dRMFace object to a given color.
setMaterial sets the material of a Direct3dRMFace object.
setTexture sets the texture of a Direct3dRMFace object.
setTextureCoordinates sets the texture coordinates of a specified vertex in a Direct3dRMFace object.
setTextureTopology sets the texture topology of a Direct3dRMFace object.


addVertex (Direct3dRMFace Class)

 Microsoft SDK for Java

addVertex

This method of the Direct3dRMFace Class adds a vertex to a Direct3dRMFace object.

Syntax

public void addVertex(float x, float y, float z);

Parameters

x | The x component of the position of the new vertex.
y | The y component of the position of the new vertex.
z | The z component of the position of the new vertex.


addVertexAndNormalIndexed (Direct3dRMFace Class)

 Microsoft SDK for Java

addVertexAndNormalIndexed

This method of the Direct3dRMFace Class adds a vertex and a normal to a Direct3dRMFace object by using an index for the vertex and an index for the normal in the containing mesh builder. The face, vertex, and normal must already be part of a Direct3dRMMeshBuilder object.

Syntax

public void addVertexAndNormalIndexed(int vertex, int normal);

Parameters

vertex | Index of the vertex to add.
normal | Index of the normal to add.


getColor (Direct3dRMFace Class)

 Microsoft SDK for Java

getColor

This method of the Direct3dRMFace Class retrieves the color of a Direct3dRMFace object.

Syntax

public int getColor();

Return Value

Returns the color.

See Also

setColor


getMaterial (Direct3dRMFace Class)

 Microsoft SDK for Java

getMaterial

This method of the Direct3dRMFace Class retrieves the material of a Direct3dRMFace object.

Syntax

public Direct3dRMMaterial getMaterial();

Return Value

Returns the Direct3dRMMaterial object if successful; otherwise, returns null.

See Also

setMaterial


getNormal (Direct3dRMFace Class)

 Microsoft SDK for Java

getNormal

This method of the Direct3dRMFace Class retrieves the normal vector of a Direct3dRMFace object.

Syntax

public void getNormal(D3dVector val);

Parameters

val The D3dVector object that receives the normal vector of the face.


getTexture (Direct3dRMFace Class)

 Microsoft SDK for Java

getTexture

This method of the Direct3dRMFace Class retrieves the Direct3dRMTexture object applied to a Direct3dRMFace object.

Syntax

public Direct3dRMTexture getTexture();

Return Value

Returns the Direct3dRMTexture object if successful; otherwise, returns null.

See Also

setTexture


getTextureCoordinateIndex (Direct3dRMFace Class)

 Microsoft SDK for Java

getTextureCoordinateIndex

This method of the Direct3dRMFace Class retrieves the index of the vertex for texture coordinates in the face's mesh. This index corresponds to the index specified in the which parameter.

Syntax

public int getTextureCoordinateIndex(int which);

Return Value

Returns the index.

Parameters

which The index within the face of the vertex.


getTextureCoordinates (Direct3dRMFace Class)

 Microsoft SDK for Java

getTextureCoordinates

This method of the Direct3dRMFace Class retrieves the texture coordinates of a vertex in a Direct3dRMFace object.

Syntax

public void getTextureCoordinates(int vertex, float[] u, float[] v);

Parameters

vertex | The index of the vertex.
u | The array variables that receive the texture u coordinates of the vertex.
v | The array variables that receive the texture v coordinates of the vertex.


getTextureTopology (Direct3dRMFace Class)

 Microsoft SDK for Java

getTextureTopology

This method of the Direct3dRMFace Class retrieves the texture topology of a Direct3dRMFace object.

Syntax

public void getTextureTopology(int[] u, int[] v);

Parameters

u | The array variables that are set or cleared, depending on how the cylindrical wrapping flags are set for the face.
v | The array variables that are set or cleared, depending on how the cylindrical wrapping flags are set for the face.

See Also

setTextureTopology


getVertex (Direct3dRMFace Class)

 Microsoft SDK for Java

getVertex

This method of the Direct3dRMFace Class retrieves the position and normal of a vertex in a Direct3dRMFace object.

Syntax

public void getVertex(int idx, D3dVector vert, D3dVector norm);

Parameters

idx | The index of the vertex.
vert | The D3dVector objects that receive the position of the vertex.
norm | The D3dVector objects that receive the normal of the vertex.


getVertexCount (Direct3dRMFace Class)

 Microsoft SDK for Java

getVertexCount

This method of the Direct3dRMFace Class retrieves the number of vertices in a Direct3dRMFace object.

Syntax

public int getVertexCount();

Return Value

Returns the number of vertices.


getVertexIndex (Direct3dRMFace Class)

 Microsoft SDK for Java

getVertexIndex

This method of the Direct3dRMFace Class retrieves the index of the vertex in the face's mesh. This index corresponds to the index specified in the which parameter.

Syntax

public int getVertexIndex(int which);

Return Value

Returns the index.

Parameters

which The index within the face of the vertex.


getVertices (Direct3dRMFace Class)

 Microsoft SDK for Java

getVertices

This method of the Direct3dRMFace Class retrieves the position and normal vector of each vertex in a Direct3dRMFace object.

Syntax

public void getVertices(int vCount, D3dVector[] v, D3dVector[] n);

Parameters

vCount | The number of vectors.
v | The D3dVector array that receives the vertices.
n | The D3dVector array that receives the normals.


getVerticesAsFloats (Direct3dRMFace Class)

 Microsoft SDK for Java

getVerticesAsFloats

This method of the Direct3dRMFace Class retrieves the position and normal vector of each vertex in a Direct3dRMFace object (as floats).

Syntax

public void getVerticesAsFloats(int[] vertex_cnt, D3dVector coord, D3dVector normals);

Parameters

vertex_cnt | The array variable that receives the number of floats of the vertices.
coord | The D3dVector objects that receive the positions vectors of the vertices.
normals | The D3dVector objects that receive the normal vectors of the vertices.


getVerticesSize (Direct3dRMFace Class)

 Microsoft SDK for Java

getVerticesSize

This method of the Direct3dRMFace Class retrieves the number of vertices associated with a Direct3dRMFace object.

Syntax

public void getVerticesSize(int[] v_cnt);

Parameters

v_cnt The array variable that receives the number of vertices.

See Also

getVertices


setColor (Direct3dRMFace Class)

 Microsoft SDK for Java

setColor

This method of the Direct3dRMFace Class sets a Direct3dRMFace object to a given color.

Syntax

public void setColor(int c);

Parameters

c The color to set.

See Also

getColor


setColorRGB (Direct3dRMFace Class)

 Microsoft SDK for Java

setColorRGB

This method of the Direct3dRMFace Class sets a Direct3dRMFace object to a given color.

Syntax

public void setColorRGB(float r, float g, float b);

Parameters

r | The red component of the color.
g | The green component of the color.
b | The blue component of the color.


setMaterial (Direct3dRMFace Class)

 Microsoft SDK for Java

setMaterial

This method of the Direct3dRMFace Class sets the material of a Direct3dRMFace object.

Syntax

public void setMaterial(Direct3dRMMaterial ref);

Parameters

ref The Direct3dRMMaterial object to set.

See Also

getMaterial


setTexture (Direct3dRMFace Class)

 Microsoft SDK for Java

setTexture

This method of the Direct3dRMFace Class sets the texture of a Direct3dRMFace object.

Syntax

public void setTexture(Direct3dRMTexture ref);

Parameters

ref The Direct3dRMTexture object to set.

See Also

getTexture


setTextureCoordinates (Direct3dRMFace Class)

 Microsoft SDK for Java

setTextureCoordinates

This method of the Direct3dRMFace Class sets the texture coordinates of a specified vertex in a Direct3dRMFace object.

Syntax

public void setTextureCoordinates(int vertex, float u, float v);

Parameters

vertex | Index of the vertex to be set. For example, if the face were a triangle, the possible vertex indices would be 0, 1, and 2.
u | The texture u coordinate to assign to the specified vertex.
v | The texture v coordinate to assign to the specified vertex.


setTextureTopology (Direct3dRMFace Class)

 Microsoft SDK for Java

setTextureTopology

This method of the Direct3dRMFace Class sets the texture topology of a Direct3dRMFace object.

Syntax

public void setTextureTopology(int wrap_u, int wrap_v);

Parameters

wrap_u | Specifies whether the texture has a cylindrical topology in the u dimension.
wrap_v | Specifies whether the texture has a cylindrical topology in the v dimension.

See Also

getTextureTopology


Direct3dRMFaceArray Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMFaceArray Class

Applications use the methods of the Direct3dRMFaceArray Class of the com.ms.directX package to organize faces in a mesh.

public class Direct3dRMFaceArray implements
            IDirect3dRMFaceArray
{
  // Methods
  public Direct3dRMFace getElement(int index);
  public int getSize();
}

The Direct3dRMFaceArray object is obtained by calling the getFaces method.


Methods (Direct3dRMFaceArray Class)

 Microsoft SDK for Java

Direct3dRMFaceArray Class Methods

The Direct3dRMFaceArray Class contains the following methods:

getElement returns one of the Direct3dRMFace objects associated with this object.
getSize returns the number of Direct3dRMFace objects associated with this object.


getElement (Direct3dRMFaceArray Class)

 Microsoft SDK for Java

getElement

This method of the Direct3dRMFaceArray Class returns one of the Direct3dRMFace objects associated with this object.

Syntax

public Direct3dRMFace getElement(int index);

Return Value

Returns the Direct3dRMFace object if successful; otherwise, returns null.

Parameters

index Identifies the object to return. Must be a value in the range of 0 to one less than the number returned by the getSize method.


getSize (Direct3dRMFaceArray Class)

 Microsoft SDK for Java

getSize

This method of the Direct3dRMFaceArray Class returns the number of Direct3dRMFace objects associated with this object.

Syntax

public int getSize();

Return Value

Returns the number of objects.


Direct3dRMFrame Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMFrame Class

Applications use the methods of the Direct3dRMFrame Class of the com.ms.directX package to interact with frames—an object's frame of reference.

public class Direct3dRMFrame implements IDirect3dRMFrame
{
  // Methods
  public void addChild(Direct3dRMFrame child);
  public void addLight(Direct3dRMLight val);
  public void addMoveCallback(IFrameMoveCallback fmC,
        IUnknown args);
  public void addRotation(int typ, float x, float y, float z, float
        theta);
  public void addScale(int typ, float sx, float sy, float sz);
  public void addTransform(int t, float[] val);
  public void addTranslation(int t, float x, float y, float z);
  public void addVisual(Direct3dRMVisual v);
  public void addVisualFrame(Direct3dRMFrame v);
  public void addVisualMesh(Direct3dRMMesh v);
  public void addVisualMeshBuilder(Direct3dRMMeshBuilder v);
  public void addVisualShadow(Direct3dRMShadow v);
  public void addVisualTexture(Direct3dRMTexture v);
  public void addVisualUserVisual(Direct3dRMUserVisual v);
  public void deleteChild(Direct3dRMFrame c);
  public void deleteLight(Direct3dRMLight l);
  public void deleteMoveCallback(IFrameMoveCallback fn,
        IUnknown args);
  public void deleteVisual(Direct3dRMVisual v);
  public void deleteVisualFrame(Direct3dRMFrame v);
  public void deleteVisualMesh(Direct3dRMMesh v);
  public void deleteVisualMeshBuilder(Direct3dRMMeshBuilder v);
  public void deleteVisualShadow(Direct3dRMShadow v);
  public void deleteVisualTexture(Direct3dRMTexture v);
  public void deleteVisualUserVisual(Direct3dRMUserVisual v);
  public Direct3dRMFrameArray getChildren();
  public int getColor();
  public Direct3dRMLightArray getLights();
  public int getMaterialMode();
  public void getOrientation(Direct3dRMFrame ref, D3dVector dir,
        D3dVector up);
  public Direct3dRMFrame getParent();
  public void getPosition(Direct3dRMFrame ref, D3dVector position);
  public void getRotation(Direct3dRMFrame ref, D3dVector axis,
        float[] theta);
  public Direct3dRMFrame getScene();
  public int getSceneBackground();
  public DirectDrawSurface getSceneBackgroundDepth();
  public int getSceneFogColor();
  public int getSceneFogEnable();
  public int getSceneFogMode();
  public void getSceneFogParams(float[] start, float[] end, float[]
        density);
  public int getSortMode();
  public Direct3dRMTexture getTexture();
  public void getTextureTopology(int[] u, int[] v);
  public void getTransform(float[] val);
  public void getVelocity(Direct3dRMFrame ref, D3dVector vel,
        int rotation);
  public Direct3dRMVisualArray getVisuals();
  public int getZbufferMode();
  public void inverseTransform(D3dVector d, D3dVector s);
  public void loadFromFileByPos(String filename, int position,
        int flags, ILoadTextureCallback c, IUnknown pUser);
  public void lookAt(Direct3dRMFrame tgt, Direct3dRMFrame ref,
        int val);
  public void move(float delta);
  public void setColor(int c);
  public void setColorRGB(float r, float g, float b);
  public void setMaterialMode(int val);
  public void setOrientation(Direct3dRMFrame reference, float dx,
        float dy, float dz, float ux, float uy, float uz);
  public void setPosition(Direct3dRMFrame reference, float x, float
        y, float z);
  public void setRotation(Direct3dRMFrame reference, float x, float
        y, float z, float theta);
  public void setSceneBackground(int c);
  public void setSceneBackgroundDepth(DirectDrawSurface s);
  public void setSceneBackgroundImage(Direct3dRMTexture i);
  public void setSceneBackgroundRGB(float r, float g, float b);
  public void setSceneFogColor(int c);
  public void setSceneFogEnable(int enable);
  public void setSceneFogMode(int c);
  public void setSceneFogParams(float s, float e, float d);
  public void setSortMode(int val);
  public void setTexture(Direct3dRMTexture t);
  public void setTextureTopology(int wrap_u, int wrap_v);
  public void setVelocity(Direct3dRMFrame reference, float x, float
        y, float z, int with_rotation);
  public void setZbufferMode(int val);
  public void transform(D3dVector d, D3dVector s);
}

The Direct3dRMFrame class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

The Direct3dRMFrame object is obtained by calling the createFrame method.


Methods (Direct3dRMFrame Class)

 Microsoft SDK for Java

Direct3dRMFrame Class Methods

The Direct3dRMFrame Class contains the following methods:

addChild adds a child frame to a frame hierarchy.
addLight adds a light to a frame.
addMoveCallback adds a callback function for special movement processing.
addRotation adds a rotation about (x, y, z) by the number of radians specified in theta.
addScale scales a frame's local transformation by (sx, sy, sz).
addTransform transforms the local coordinates of the frame by the given affine transformation according to the value of the t parameter.
addTranslation adds a translation by (x, y, z) to a frame's local coordinate system.
addVisual adds a visual object to a frame.
addVisualFrame adds a visual frame to the frame object.
addVisualMesh adds a visual mesh to the frame object.
addVisualMeshBuilder adds a mesh builder object to the frame object.
addVisualShadow adds a shadow object to the frame object.
addVisualTexture adds a texture object to the frame object.
addVisualUserVisual adds a user visual object to the frame object.
deleteChild removes a frame from the hierarchy.
deleteLight removes a light from a frame and destroys it if it is no longer referenced.
deleteMoveCallback removes a callback function that performed special motion processing.
deleteVisual removes a visual object from a frame and destroys it if it is no longer referenced.
deleteVisualFrame deletes a visual frame from the frame object.
deleteVisualMesh deletes a mesh object from the frame object.
deleteVisualMeshBuilder deletes a mesh builder object from the frame object.
deleteVisualShadow deletes a shadow object from the frame object.
deleteVisualTexture deletes a shadow object from the frame object.
deleteVisualUserVisual deletes a user visual object from the frame object.
getChildren retrieves a list of child frames in the form of a Direct3dRMFrameArray object.
getColor retrieves the color of the frame.
getLights retrieves a list of lights in the frame in the form of a Direct3dRMLightArray object.
getMaterialMode retrieves the material mode of the frame.
getOrientation retrieves the orientation of a frame relative to the given reference frame.
getParent retrieves the parent frame of the current frame.
getPosition retrieves the position of a frame, relative to the given reference frame.
getRotation retrieves the rotation of the frame, relative to the given reference frame.
getScene retrieves the root frame of the hierarchy containing the given frame.
getSceneBackground retrieves the background color of a scene.
getSceneBackgroundDepth retrieves the current background-depth buffer for the scene.
getSceneFogColor retrieves the fog color of a scene.
getSceneFogEnable returns whether fog is currently enabled for this scene.
getSceneFogMode retrieves the current fog mode for this scene.
getSceneFogParams retrieves the current fog parameters for this scene.
getSortMode retrieves the sorting mode used to process child frames.
getTexture retrieves the texture of the given frame.
getTextureTopology retrieves the topological properties of a texture when it is mapped onto objects in the given frame.
getTransform retrieves the local transformation of the frame as a 4-by-4 affine matrix.
getVelocity retrieves the velocity of the frame, relative to the given reference frame.
getVisuals retrieves a list of visuals in the frame.
getZbufferMode determines whether z-buffering is enabled or disabled.
inverseTransform transforms the vector in the s parameter in world coordinates to model coordinates, and returns the result in the d parameter.
loadFromFileByPos loads a Direct3dRMFrame object.
lookAt faces the frame toward the target frame (relative to the given reference frame) and locks the rotation by the given constraints.
move applies the rotations and velocities for all frames in the given hierarchy.
setColor sets the color of the frame. This color is used for meshes in the frame when the material mode is D3DRMMATERIAL_FROMFRAME.
setColorRGB sets the color of the frame.
setMaterialMode sets the material mode for a frame.
setOrientation aligns a frame so that its z-direction points along the direction vector [dx, dy, dz] and its y-direction aligns with the vector [ux, uy, uz].
setPosition sets the position of a frame, relative to the frame of reference.
setRotation sets a frame rotating by the given angle around the given vector at each call to the tick or move method.
setSceneBackground sets the background color of a scene.
setSceneBackgroundDepth specifies a background-depth buffer for a scene.
setSceneBackgroundImage specifies a background image for a scene.
setSceneBackgroundRGB sets the background color of a scene, using an RGB value.
setSceneFogColor sets the fog color of a scene.
setSceneFogEnable sets the fog enable state.
setSceneFogMode sets the fog mode.
setSceneFogParams sets the current fog parameters for the scene.
setSortMode sets the sorting mode used to process child frames.
setTexture sets the texture of the frame.
setTextureTopology defines the topological properties of the texture coordinates across objects in the frame.
setVelocity sets the velocity of the given frame relative to the reference frame.
setZbufferMode sets the z-buffer mode (that is, whether z-buffering is enabled or disabled).
transform transforms the vector in the s parameter, which is in model coordinates, into world coordinates.


addChild (Direct3dRMFrame Class)

 Microsoft SDK for Java

addChild

This method of the Direct3dRMFrame Class adds a child frame to a frame hierarchy.

Syntax

public void addChild(Direct3dRMFrame child);

Parameters

child The Direct3dRMFrame object that will be added as a child.

Remarks

If the frame being added as a child already has a parent, this method removes it from its previous parent before adding it to the new parent.

To preserve an object's transformation, use the getTransform method to retrieve the object's transformation before using the addChild method. Then, reapply the transformation after the frame is added.


addLight (Direct3dRMFrame Class)

 Microsoft SDK for Java

addLight

This method of the Direct3dRMFrame Class adds a light to a frame.

Syntax

public void addLight(Direct3dRMLight val);

Parameters

val The Direct3dRMLight object to be added to the frame.


addMoveCallback (Direct3dRMFrame Class)

 Microsoft SDK for Java

addMoveCallback

This method of the Direct3dRMFrame Class adds a callback function for special movement processing.

Syntax

public void addMoveCallback(IFrameMoveCallback fmC, IUnknown args);

Parameters

fmC | The callback interface that contains an application-defined callback function.
args | Application-defined data to be passed to the callback function.

See Also

move, deleteMoveCallback


addRotation (Direct3dRMFrame Class)

 Microsoft SDK for Java

addRotation

This method of the Direct3dRMFrame Class adds a rotation about (x, y, z) by the number of radians specified in theta.

Syntax

public void addRotation(int typ, float x, float y, float z, float theta);

Parameters

typ | A value of combine type that specifies how to combine the new rotation with any current frame transformation.
x | The axis about which to rotate.
y | The axis about which to rotate.
z | The axis about which to rotate.
theta | The angle of rotation, in radians.

Remarks

The specified rotation changes the matrix only for the frame identified by this object. This method changes the objects in the frame only once, unlike setRotation, which changes the matrix with every render tick.


addScale (Direct3dRMFrame Class)

 Microsoft SDK for Java

addScale

This method of the Direct3dRMFrame Class scales a frame's local transformation by (sx, sy, sz).

Syntax

public void addScale(int typ, float sx, float sy, float sz);

Parameters

typ | The value of combine type that specifies how to combine the new scale with any current frame transformation.
sz | The scale factor in the x direction.
sy | The scale factor in the y direction.
sz | The scale factor in the z direction.

Remarks

The specified transformation changes the matrix only for the frame identified by this object.


addTransform (Direct3dRMFrame Class)

 Microsoft SDK for Java

addTransform

This method of the Direct3dRMFrame Class transforms the local coordinates of the frame by the given affine transformation according to the value of the t parameter.

Syntax

public void addTransform(int t, float[] val);

Parameters

t | The value of combine type that specifies how to combine the new transformation with any current transformation.
val | The array variable that defines the transformation matrix to be combined.

Remarks

Although a 4-by-4 matrix is given, the last column must be the transpose of [0 0 0 1] for the transformation to be affine.

The specified transformation changes the matrix only for the frame identified by this Direct3dRMFrame object.


addTranslation (Direct3dRMFrame Class)

 Microsoft SDK for Java

addTranslation

This method of the Direct3dRMFrame Class adds a translation by (x, y, z) to a frame's local coordinate system.

Syntax

public void addTranslation(int t, float x, float y, float z);

Parameters

t | The value of combine type that specifies how to combine the new translation with any current translation.
x | The position change in the x direction.
y | The position change in the y direction.
z | The position change in the z direction.

Remarks

The specified translation changes the matrix only for the frame identified by this object.


addVisual (Direct3dRMFrame Class)

 Microsoft SDK for Java

addVisual

This method of the Direct3dRMFrame Class adds a visual object to a frame.

Syntax

public void addVisual(Direct3dRMVisual v);

Parameters

v The Direct3dRMVisual object to be added to the frame.

Remarks

Visual objects include meshes and textures. When a visual object is added to a frame, it becomes visible if the frame is in view. The visual object is referenced by the frame.


addVisualFrame (Direct3dRMFrame Class)

 Microsoft SDK for Java

addVisualFrame

This method of the Direct3dRMFrame Class adds a visual frame to the frame object.

Syntax

public void addVisualFrame(Direct3dRMFrame v);

Parameters

v The Direct3dRMFrame object to be added.


addVisualMesh (Direct3dRMFrame Class)

 Microsoft SDK for Java

addVisualMesh

This method of the Direct3dRMFrame Class adds a visual mesh to the frame object.

Syntax

public void addVisualMesh(Direct3dRMMesh v);

Parameters

v The Direct3dRMMesh object to be added.


addVisualMeshBuilder (Direct3dRMFrame Class)

 Microsoft SDK for Java

addVisualMeshBuilder

This method of the Direct3dRMFrame Class adds a mesh builder object to the frame object.

Syntax

public void addVisualMeshBuilder(Direct3dRMMeshBuilder v);

Parameters

v The Direct3dRMMeshBuilder object to be added.


addVisualShadow (Direct3dRMFrame Class)

 Microsoft SDK for Java

addVisualShadow

This method of the Direct3dRMFrame Class adds a shadow object to the frame object.

Syntax

public void addVisualShadow(Direct3dRMShadow v);

Parameters

v The Direct3dRMShadow object to be added.


addVisualTexture (Direct3dRMFrame Class)

 Microsoft SDK for Java

addVisualTexture

This method of the Direct3dRMFrame Class adds a texture object to the frame object.

Syntax

public void addVisualTexture(Direct3dRMTexture v);

Parameters

v The Direct3dRMTexture object to be added.


addVisualUserVisual (Direct3dRMFrame Class)

 Microsoft SDK for Java

addVisualUserVisual

This method of the Direct3dRMFrame Class adds a user visual object to the frame object.

Syntax

public void addVisualUserVisual(Direct3dRMUserVisual v);

Parameters

v The Direct3dRMUserVisual object to be added.


deleteChild (Direct3dRMFrame Class)

 Microsoft SDK for Java

deleteChild

This method of the Direct3dRMFrame Class removes a frame from the hierarchy. If the frame is not referenced, it is destroyed along with any child frames, lights, and meshes.

Syntax

public void deleteChild(Direct3dRMFrame c);

Parameters

c The Direct3dRMFrame object to be used as the child.


deleteLight (Direct3dRMFrame Class)

 Microsoft SDK for Java

deleteLight

This method of the Direct3dRMFrame Class removes a light from a frame and destroys it if it is no longer referenced. When a light is removed from a frame, it no longer affects meshes in the scene its frame was in.

Syntax

public void deleteLight(Direct3dRMLight l);

Parameters

l The Direct3dRMLight object to be removed.


deleteMoveCallback (Direct3dRMFrame Class)

 Microsoft SDK for Java

deleteMoveCallback

This method of the Direct3dRMFrame Class removes a callback function that performed special motion processing.

Syntax

public void deleteMoveCallback(IFrameMoveCallback fn, IUnknown args);

Parameters

fn | The callback interface that contains an application-defined callback function.
args | Application-defined data that was passed to the callback function.

See Also

addMoveCallback, move


deleteVisual (Direct3dRMFrame Class)

 Microsoft SDK for Java

deleteVisual

This method of the Direct3dRMFrame Class removes a visual object from a frame and destroys it if it is no longer referenced.

Syntax

public void deleteVisual(Direct3dRMVisual v);

Parameters

v The Direct3dRMVisual object to be removed.


deleteVisualFrame (Direct3dRMFrame Class)

 Microsoft SDK for Java

deleteVisualFrame

This method of the Direct3dRMFrame Class deletes a visual frame from the frame object.

Syntax

public void deleteVisualFrame(Direct3dRMFrame v);

Parameters

v The Direct3dRMFrame object to be deleted.


deleteVisualMesh (Direct3dRMFrame Class)

 Microsoft SDK for Java

deleteVisualMesh

This method of the Direct3dRMFrame Class deletes a mesh object from the frame object.

Syntax

public void deleteVisualMesh(Direct3dRMMesh v);

Parameters

v The Direct3dRMMesh object to be deleted.


deleteVisualMeshBuilder (Direct3dRMFrame Class)

 Microsoft SDK for Java

deleteVisualMeshBuilder

This method of the Direct3dRMFrame Class deletes a mesh builder object from the frame object.

Syntax

public void deleteVisualMeshBuilder(Direct3dRMMeshBuilder v);

Parameters

v The Direct3dRMMeshBuilder object to be deleted.


deleteVisualShadow (Direct3dRMFrame Class)

 Microsoft SDK for Java

deleteVisualShadow

This method of the Direct3dRMFrame Class deletes a shadow object from the frame object.

Syntax

public void deleteVisualShadow(Direct3dRMShadow v);

Parameters

v The Direct3dRMShadow object to be deleted.


deleteVisualTexture (Direct3dRMFrame Class)

 Microsoft SDK for Java

deleteVisualTexture

This method of the Direct3dRMFrame Class deletes a texture object from the frame object.

Syntax

public void deleteVisualTexture(Direct3dRMTexture v);

Parameters

v The Direct3dRMTexture object to be deleted.


deleteVisualUserVisual (Direct3dRMFrame Class)

 Microsoft SDK for Java

deleteVisualUserVisual

This method of the Direct3dRMFrame Class deletes a user visual object from the frame object.

Syntax

public void deleteVisualUserVisual(Direct3dRMUserVisual v);

Parameters

v The Direct3dRMUserVisual object to be deleted.


getChildren (Direct3dRMFrame Class)

 Microsoft SDK for Java

getChildren

This method of the Direct3dRMFrame Class retrieves a list of child frames in the form of a Direct3dRMFrameArray object.

Syntax

public Direct3dRMFrameArray getChildren();

Return Value

Returns the Direct3dRMFrameArray object if successful; otherwise, null.

See Also

com.ms.directX.Direct3dRMFrameArray


getColor (Direct3dRMFrame Class)

 Microsoft SDK for Java

getColor

This method of the Direct3dRMFrame Class retrieves the color of the frame.

Syntax

public int getColor();

Return Value

Returns the color of the Direct3dRMFrame object.

See Also

setColor


getLights (Direct3dRMFrame Class)

 Microsoft SDK for Java

getLights

This method of the Direct3dRMFrame Class retrieves a list of lights in the frame in the form of a Direct3dRMLightArray object.

Syntax

public Direct3dRMLightArray getLights();

Return Value

Returns the Direct3dRMLightArray object if successful; otherwise, null.

See Also

com.ms.directX.Direct3dRMLightArray


getMaterialMode (Direct3dRMFrame Class)

 Microsoft SDK for Java

getMaterialMode

This method of the Direct3dRMFrame Class retrieves the material mode of the frame.

Syntax

public int getMaterialMode();

Return Value

Returns a value of material mode type that specifies the current material mode.

See Also

setMaterialMode


getOrientation (Direct3dRMFrame Class)

 Microsoft SDK for Java

getOrientation

This method of the Direct3dRMFrame Class retrieves the orientation of a frame relative to the given reference frame.

Syntax

public void getOrientation(Direct3dRMFrame ref, D3dVector dir, D3dVector up);

Parameters

ref | The Direct3dRMFrame object to be used as the reference.
dir | The D3dVector objects that receive the directions of the frame's z-axis.
up | The D3dVector objects that receive the directions of the frame's y-axis.

See Also

setOrientation


getParent (Direct3dRMFrame Class)

 Microsoft SDK for Java

getParent

This method of the Direct3dRMFrame Class retrieves the parent frame of the current frame.

Syntax

public Direct3dRMFrame getParent();

Return Value

Returns the Direct3dRMFrame object if successful; null otherwise.

Remarks

If the current frame is the root, this method returns null.


getPosition (Direct3dRMFrame Class)

 Microsoft SDK for Java

getPosition

This method of the Direct3dRMFrame Class retrieves the position of a frame, relative to the given reference frame. (For example, this method retrieves the distance of the frame from the reference.) The distance is stored in the position parameter as a vector, rather than as a linear measure.

Syntax

public void getPosition(Direct3dRMFrame ref, D3dVector position);

Parameters

ref | The Direct3dRMFrame object to be used as the reference.
position | The D3dVector object that receives the frame's position.

See Also

setPosition


getRotation (Direct3dRMFrame Class)

 Microsoft SDK for Java

getRotation

This method of the Direct3dRMFrame Class retrieves the rotation of the frame, relative to the given reference frame.

Syntax

public void getRotation(Direct3dRMFrame ref, D3dVector axis, float[] theta);

Parameters

ref | The Direct3dRMFrame object to be used as the reference.
axis | The D3dVector object that receives the frame's axis of rotation.
theta | The array variable that receives the frame's rotation, in radians.

See Also

setRotation


getScene (Direct3dRMFrame Class)

 Microsoft SDK for Java

getScene

This method of the Direct3dRMFrame Class retrieves the root frame of the hierarchy containing the given frame.

Syntax

public Direct3dRMFrame getScene();

Return Value

Returns the Direct3dRMFrame object if successful; otherwise, null.


getSceneBackground (Direct3dRMFrame Class)

 Microsoft SDK for Java

getSceneBackground

This method of the Direct3dRMFrame Class retrieves the background color of a scene.

Syntax

public int getSceneBackground();

Return Value

Returns the color.


getSceneBackgroundDepth (Direct3dRMFrame Class)

 Microsoft SDK for Java

getSceneBackgroundDepth

This method of the Direct3dRMFrame Class retrieves the current background-depth buffer for the scene.

Syntax

public DirectDrawSurface getSceneBackgroundDepth();

Return Value

Returns the DirectDrawSurface object if successful; otherwise, returns null.

See Also

setSceneBackgroundDepth


getSceneFogColor (Direct3dRMFrame Class)

 Microsoft SDK for Java

getSceneFogColor

This method of the Direct3dRMFrame Class retrieves the fog color of a scene.

Syntax

public int getSceneFogColor();

Return Value

Returns the fog's color.


getSceneFogEnable (Direct3dRMFrame Class)

 Microsoft SDK for Java

getSceneFogEnable

This method of the Direct3dRMFrame Class returns whether fog is currently enabled for this scene.

Syntax

public int getSceneFogEnable();

Return Value

Returns true if fog is enabled, otherwise, returns false.


getSceneFogMode (Direct3dRMFrame Class)

 Microsoft SDK for Java

getSceneFogMode

This method of the Direct3dRMFrame Class retrieves the current fog mode for this scene.

Syntax

public int getSceneFogMode();

Return Value

Returns a value of the fog mode type that specifies the current fog mode.


getSceneFogParams (Direct3dRMFrame Class)

 Microsoft SDK for Java

getSceneFogParams

This method of the Direct3dRMFrame Class retrieves the current fog parameters for this scene.

Syntax

public void getSceneFogParams(float[] start, float[] end, float[] density);

Parameters

start | The array variables that receive the fog start values.
end | The array variables that receive the fog end values.
density | The array variables that receive the fog density values.


getSortMode (Direct3dRMFrame Class)

 Microsoft SDK for Java

getSortMode

This method of the Direct3dRMFrame Class retrieves the sorting mode used to process child frames.

Syntax

public int getSortMode();

Return Value

Returns a value of the D3DRMSORT_ type that specifies the sorting mode.

See Also

setSortMode


getTexture (Direct3dRMFrame Class)

 Microsoft SDK for Java

getTexture

This method of the Direct3dRMFrame Class retrieves the texture of the given frame.

Syntax

public Direct3dRMTexture getTexture();

Return Value

Returns the Direct3dRMTexture object if successful; otherwise, null.

See Also

setTexture


getTextureTopology (Direct3dRMFrame Class)

 Microsoft SDK for Java

getTextureTopology

This method of the Direct3dRMFrame Class retrieves the topological properties of a texture when it is mapped onto objects in the given frame.

Syntax

public void getTextureTopology(int[] u, int[] v);

Parameters

u | Array variable that is set to true if the texture is mapped in the u direction.
v | Array variable that is set to true if the texture is mapped in the v direction.

See Also

setTextureTopology


getTransform (Direct3dRMFrame Class)

 Microsoft SDK for Java

getTransform

This method of the Direct3dRMFrame Class retrieves the local transformation of the frame as a 4-by-4 affine matrix.

Syntax

public void getTransform(float[] val);

Parameters

val The array variable that receives the frame's transformation.


getVelocity (Direct3dRMFrame Class)

 Microsoft SDK for Java

getVelocity

This method of the Direct3dRMFrame Class retrieves the velocity of the frame, relative to the given reference frame.

Syntax

public void getVelocity(Direct3dRMFrame ref, D3dVector vel, int rotation);

Parameters

ref | The Direct3dRMFrame object to be used as the reference.
vel | A D3dVector object that receives the frame's velocity.
rotation | A flag specifying whether the rotational velocity of the object is taken into account when retrieving the linear velocity. If this parameter is true, the object's rotational velocity is included in the calculation.

See Also

setVelocity


getVisuals (Direct3dRMFrame Class)

 Microsoft SDK for Java

getVisuals

This method of the Direct3dRMFrame Class retrieves a list of visuals in the frame.

Syntax

public Direct3dRMVisualArray getVisuals();

Return Value

Returns the Direct3dRMVisualArray object if successful; otherwise, null.


getZbufferMode (Direct3dRMFrame Class)

 Microsoft SDK for Java

getZbufferMode

This method of the Direct3dRMFrame Class determines whether z-buffering is enabled or disabled.

Syntax

public int getZbufferMode();

Return Value

Returns one value of D3DRMZBUFFER_ type.

See Also

setZbufferMode


inverseTransform (Direct3dRMFrame Class)

 Microsoft SDK for Java

inverseTransform

This method of the Direct3dRMFrame Class transforms the vector in the s parameter in world coordinates to model coordinates, and returns the result in the d parameter.

Syntax

public void inverseTransform(D3dVector d, D3dVector s);

Parameters

d | A D3dVector object that receives the result of the transformation.
s | The D3dVector object that is the source of the transformation.

See Also

transform


loadFromFileByPos (Direct3dRMFrame Class)

 Microsoft SDK for Java

loadFromFileByPos

This method of the Direct3dRMFrame Class loads a Direct3dRMFrame object.

Syntax

public void loadFromFileByPos(String filename, int position, int flags, ILoadTextureCallback c, IUnknown pUser);

Parameters

filename | The name of the file containing the object to be loaded.
position | The position of the object to be loaded. This is a value that gives the object's order in the file. This parameter can be null.
flags | The value of the load options type.
c | The callback interface that contains a load texture callback function called to load any textures used by the object that require special formatting. This parameter can be null.
pUser | Application-defined data passed to the load texture callback function.

Remarks

By default, this method loads the first frame hierarchy in the file specified by the filename parameter. The frame that calls this method is used as the parent of the new frame hierarchy.


lookAt (Direct3dRMFrame Class)

 Microsoft SDK for Java

lookAt

This method of the Direct3dRMFrame Class faces the frame toward the target frame (relative to the given reference frame) and locks the rotation by the given constraints.

Syntax

public void lookAt(Direct3dRMFrame tgt, Direct3dRMFrame ref, int val);

Parameters

tgt | The Direct3dRMFrame objects to be used as the target.
ref | The Direct3dRMFrame objects to be used as the reference.
val | The value of frame constraint type that specifies the axis of rotation constrained.


move (Direct3dRMFrame Class)

 Microsoft SDK for Java

move

This method of the Direct3dRMFrame Class applies the rotations and velocities for all frames in the given hierarchy.

Syntax

public void move(float delta);

Parameters

delta The amount to change the velocity and rotation by.


setColor (Direct3dRMFrame Class)

 Microsoft SDK for Java

setColor

This method of the Direct3dRMFrame Class sets the color of the frame. This color is used for meshes in the frame when the material mode is D3DRMMATERIAL_FROMFRAME.

Syntax

public void setColor(int c);

Parameters

c New color for the frame.

See Also

getColor, setMaterialMode


setColorRGB (Direct3dRMFrame Class)

 Microsoft SDK for Java

setColorRGB

This method of the Direct3dRMFrame Class sets the color of the frame. This color is used for meshes in the frame when the material mode is D3DRMMATERIAL_FROMFRAME.

Syntax

public void setColorRGB(float r, float g, float b);

Parameters

r | The red component of a new color for the frame.
g | The green component of a new color for the frame.
b | The blue component of a new color for the frame. Each component of the color should be in the range of 0 to 1.

See Also

setMaterialMode


setMaterialMode (Direct3dRMFrame Class)

 Microsoft SDK for Java

setMaterialMode

This method of the Direct3dRMFrame Class sets the material mode for a frame. The material mode determines the source of material information for visuals rendered with the frame.

Syntax

public void setMaterialMode(int val);

Parameters

val The material mode type.

See Also

getMaterialMode


setOrientation (Direct3dRMFrame Class)

 Microsoft SDK for Java

setOrientation

This method of the Direct3dRMFrame Class aligns a frame so that its z-direction points along the direction vector [dx, dy, dz] and its y-direction aligns with the vector [ux, uy, uz].

Syntax

public void setOrientation(Direct3dRMFrame reference, float dx, float dy, float dz, float ux, float uy, float uz);

Parameters

reference | The Direct3dRMFrame object to be used as the reference.
dx | The new z axis for the frame.
dy | The new z axis for the frame.
dz | The new z axis for the frame.
ux | The new y axis for the frame.
uy | The new y axis for the frame.
uz | The new y axis for the frame.

Remarks

The default orientation of a frame has a direction vector of [0, 0, 1] and an up vector of [0, 1, 0].

If [ux, uy, uz] is parallel to [dx, dy, dz], no action is taken; otherwise, the [ux, uy, uz] vector passed is projected onto the plane that is perpendicular to [dx, dy, dz].

See Also

getOrientation


setPosition (Direct3dRMFrame Class)

 Microsoft SDK for Java

setPosition

This method of the Direct3dRMFrame Class sets the position of a frame, relative to the frame of reference. This method places the frame a distance of [x, y, z] from the reference. When a child frame is created within a parent frame, it is placed at [0, 0, 0] in the parent frame.

Syntax

public void setPosition(Direct3dRMFrame reference, float x, float y, float z);

Parameters

reference | The Direct3dRMFrame object to be used as the reference.
x | The x-coordinate of the new position for the frame.
y | The y-coordinate of the new position for the frame.
z | The z coordinate of the new position for the frame.

See Also

getPosition


setRotation (Direct3dRMFrame Class)

 Microsoft SDK for Java

setRotation

This method of the Direct3dRMFrame Class sets a frame rotating by the given angle around the given vector at each call to the tick or move method. The direction vector [x, y, z] is defined in the reference frame.

Syntax

public void setRotation(Direct3dRMFrame reference, float x, float y, float z, float theta);

Parameters

reference | The Direct3dRMFrame object to be used as the reference.
x | The x element of the vector, about which rotation occurs.
y | The y element of the vector, about which rotation occurs.
z | The z element of the vector, about which rotation occurs.
theta | The rotation angle, in radians.

Remarks

The specified rotation changes the matrix with every render tick, unlike the addRotation method, which changes the objects in the frame only once.

See Also

addRotation, getRotation


setSceneBackground (Direct3dRMFrame Class)

 Microsoft SDK for Java

setSceneBackground

This method of the Direct3dRMFrame Class sets the background color of a scene.

Syntax

public void setSceneBackground(int c);

Parameters

c New color for the background.


setSceneBackgroundDepth (Direct3dRMFrame Class)

 Microsoft SDK for Java

setSceneBackgroundDepth

This method of the Direct3dRMFrame Class specifies a background-depth buffer for a scene.

Syntax

public void setSceneBackgroundDepth(DirectDrawSurface s);

Parameters

s A DirectDrawSurface object that will store the new background depth for the scene.

Remarks

The image must have a depth of 16. If the image and viewport sizes are different, the image is scaled first. For best performance when animating the background-depth buffer, the image should be the same size as the viewport. This enables the depth buffer to be updated directly from the image memory without incurring extra overhead.

See Also

getSceneBackgroundDepth


setSceneBackgroundImage (Direct3dRMFrame Class)

 Microsoft SDK for Java

setSceneBackgroundImage

This method of the Direct3dRMFrame Class specifies a background image for a scene.

Syntax

public void setSceneBackgroundImage(Direct3dRMTexture i);

Parameters

i A Direct3dRMTexture object that will contain the new background scene.

Remarks

If the image is a different size or color depth than the viewport, the image will first be scaled or converted to the correct depth. For best performance when animating the background, the image should be the same size and color depth. This enables the background to be rendered directly from the image memory without incurring any extra overhead.


setSceneBackgroundRGB (Direct3dRMFrame Class)

 Microsoft SDK for Java

setSceneBackgroundRGB

This method of the Direct3dRMFrame Class sets the background color of a scene, using an RGB value.

Syntax

public void setSceneBackgroundRGB(float r, float g, float b);

Parameters

r | The red component of the new color for the background.
g | The green component of the new color for the background.
b | The blue component of the new color for the background.


setSceneFogColor (Direct3dRMFrame Class)

 Microsoft SDK for Java

setSceneFogColor

This method of the Direct3dRMFrame Class sets the fog color of a scene.

Syntax

public void setSceneFogColor(int c);

Parameters

c The new color for the fog.


setSceneFogEnable (Direct3dRMFrame Class)

 Microsoft SDK for Java

setSceneFogEnable

This method of the Direct3dRMFrame Class sets the fog enable state.

Syntax

public void setSceneFogEnable(int enable);

Parameters

enable The new fog enable state.


setSceneFogMode (Direct3dRMFrame Class)

 Microsoft SDK for Java

setSceneFogMode

This method of the Direct3dRMFrame Class sets the fog mode.

Syntax

public void setSceneFogMode(int c);

Parameters

c The fog mode type.

See Also

setSceneFogParams


setSceneFogParams (Direct3dRMFrame Class)

 Microsoft SDK for Java

setSceneFogParams

This method of the Direct3dRMFrame Class sets the current fog parameters for the scene.

Syntax

public void setSceneFogParams(float s, float e, float d);

Parameters

s | The fog start point for linear fog mode.
e | The fog end point for linear fog mode. These settings determine the distance from the camera at which the fog effects first become visible and the distance at which the fog reaches its maximum density.
d | The fog density for the exponential fog modes.. This value should be in the range of 0 through 1.

See Also

setSceneFogMode


setSortMode (Direct3dRMFrame Class)

 Microsoft SDK for Java

setSortMode

This method of the Direct3dRMFrame Class sets the sorting mode used to process child frames. You can use this method to change the properties of hidden-surface-removal algorithms.

Syntax

public void setSortMode(int val);

Parameters

val One value of the D3DRMSORT_ type, specifying the sorting mode.

Remarks

By default, a frame's initial sort mode is D3DRMSORT_FROMPARENT.

See Also

getSortMode


setTexture (Direct3dRMFrame Class)

 Microsoft SDK for Java

setTexture

This method of the Direct3dRMFrame Class sets the texture of the frame.

Syntax

public void setTexture(Direct3dRMTexture t);

Parameters

t The Direct3dRMTexture object to be used.

Remarks

The texture is used for meshes in the frame when the material mode is D3DRMMATERIAL_FROMFRAME. To disable the frame's texture, use a null texture.

See Also

getTexture, setMaterialMode


setTextureTopology (Direct3dRMFrame Class)

 Microsoft SDK for Java

setTextureTopology

This method of the Direct3dRMFrame Class defines the topological properties of the texture coordinates across objects in the frame.

Syntax

public void setTextureTopology(int wrap_u, int wrap_v);

Parameters

wrap_u | A variable that is set to true to map the texture in the u-direction.
wrap_v | A variable that is set to true to map the texture in the v-directions.

See Also

getTextureTopology


setVelocity (Direct3dRMFrame Class)

 Microsoft SDK for Java

setVelocity

This method of the Direct3dRMFrame Class sets the velocity of the given frame relative to the reference frame. The frame will be moved by the vector [x, y, z], with respect to the reference frame at each successive call to the tick or move method.

Syntax

public void setVelocity(Direct3dRMFrame reference, float x, float y, float z, int with_rotation);

Parameters

reference | The Direct3dRMFrame object to be used as the reference.
x | The x component of the new velocity for the frame.
y | The y component of the new velocity for the frame.
z | The z component of the new velocity for the frame.
with_rotation | A flag specifying whether the rotational velocity of the object is taken into account when setting the linear velocity. If with_rotation is true, the object's rotational velocity is included in the calculation.

See Also

getVelocity


setZbufferMode (Direct3dRMFrame Class)

 Microsoft SDK for Java

setZbufferMode

This method of the Direct3dRMFrame Class sets the z-buffer mode (that is, whether z-buffering is enabled or disabled).

Syntax

public void setZbufferMode(int val);

Parameters

val One value of the D3DRMZBUFFER_ type, specifying the z-buffer mode.

Remarks

By default, a frame's initial z-buffer mode is D3DRMZBUFFER_FROMPARENT.

See Also

getZbufferMode


transform (Direct3dRMFrame Class)

 Microsoft SDK for Java

transform

This method of the Direct3dRMFrame Class transforms the vector in the s parameter, which is in model coordinates, into world coordinates. The result is returned in the d parameter.

Syntax

public void transform(D3dVector d, D3dVector s);

Parameters

d | A D3dVector object that receives the result of the transformation operation.
s | The D3dVector object that is the source of the transformation operation.

See Also

inverseTransform


Direct3dRMFrameArray Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMFrameArray Class

Applications use the methods of the Direct3dRMFrameArray Class of the com.ms.directX package to organize frame objects.

public class Direct3dRMFrameArray implements
            IDirect3dRMFrameArray
{
  // Methods
  public Direct3dRMFrame getElement(int index);
  public int getSize();
}

The Direct3dRMFrameArray object is obtained by calling the getPickFrame or getChildren method.


Methods (Direct3dRMFrameArray Class)

 Microsoft SDK for Java

Direct3dRMFrameArray Class Methods

The Direct3dRMFrameArray Class contains the following methods:

getElement retrieves one of the Direct3dRMFrame objects associated with this object.
getSize retrieves the number of Direct3dRMFrame objects associated with this object.


getElement (Direct3dRMFrameArray Class)

 Microsoft SDK for Java

getElement

This method of the Direct3dRMFrameArray Class retrieves one of the Direct3dRMFrame objects associated with this object.

Syntax

public Direct3dRMFrame getElement(int index);

Return Value

Returns the Direct3dRMFrame object if successful; otherwise, null.

Parameters

index Identifies the object to return. Must be a value in the range of 0 to one less than the number returned by the getSize method.


getSize (Direct3dRMFrameArray Class)

 Microsoft SDK for Java

getSize

This method of the Direct3dRMFrameArray Class retrieves the number of Direct3dRMFrame objects associated with this object.

Syntax

public int getSize();

Return Value

Returns the number of objects.


Direct3dRMLight Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMLight Class

Applications use the methods of the Direct3dRMLight Class of the com.ms.directX package to interact with light objects.

public class Direct3dRMLight implements IDirect3dRMLight
{
  // Methods
  public int getColor();
  public float getConstantAttenuation();
  public Direct3dRMFrame getEnableFrame();
  public float getLinearAttenuation();
  public float getPenumbra();
  public float getQuadraticAttenuation();
  public float getRange();
  public int getType();
  public float getUmbra();
  public void setColor(int c);
  public void setColorRGB(float r, float g, float b);
  public void setConstantAttenuation(float atn);
  public void setEnableFrame(Direct3dRMFrame f);
  public void setLinearAttenuation(float atn);
  public void setPenumbra(float p);
  public void setQuadraticAttenuation(float atn);
  public void setRange(float rng);
  public void setType(int t);
  public void setUmbra(float u);
}

The Direct3dRMLight class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

The Direct3dRMLight object is obtained by calling the createLight or createLightRGB method.


Methods (Direct3dRMLight Class)

 Microsoft SDK for Java

Direct3dRMLight Class Methods

The Direct3dRMLight Class contains the following methods:

getColor retrieves the color of the current Direct3dRMLight object.
getConstantAttenuation retrieves the constant attenuation factor for the Direct3dRMLight object.
getEnableFrame retrieves the enable frame for a light.
getLinearAttenuation retrieves the linear attenuation factor for a light.
getPenumbra retrieves the penumbra angle of a spotlight.
getQuadraticAttenuation returns the quadratic attenuation value.
getRange retrieves the range of the current Direct3dRMLight object.
getType retrieves the type of a given light.
getUmbra retrieves the umbra angle of the Direct3dRMLight object.
setColor sets the color of the given light.
setColorRGB sets the color of the given light.
setConstantAttenuation sets the constant attenuation factor for a light.
setEnableFrame sets the enable frame for a light.
setLinearAttenuation sets the linear attenuation factor for a light.
setPenumbra sets the angle of the penumbra cone.
setQuadraticAttenuation sets the quadratic attenuation factor for a light.
setRange sets the range of a light.
setType changes the light type.
setUmbra sets the angle of the umbra cone.


getColor (Direct3dRMLight Class)

 Microsoft SDK for Java

getColor

This method of the Direct3dRMLight Class retrieves the color of the current Direct3dRMLight object.

Syntax

public int getColor();

Return Value

Returns the color.

See Also

setColor


getConstantAttenuation (Direct3dRMLight Class)

 Microsoft SDK for Java

getConstantAttenuation

This method of the Direct3dRMLight Class retrieves the constant attenuation factor for the Direct3dRMLight object.

Syntax

public float getConstantAttenuation();

Return Value

Returns the constant attenuation value.

Remarks

The constant attenuation value affects the light intensity inversely. For example, a constant attenuation value of 2 reduces the intensity of the light by half.

See Also

setConstantAttenuation


getEnableFrame (Direct3dRMLight Class)

 Microsoft SDK for Java

getEnableFrame

This method of the Direct3dRMLight Class retrieves the enable frame for a light.

Syntax

public Direct3dRMFrame getEnableFrame();

Return Value

Returns the Direct3dRMFrame object if successful; otherwise, null.

See Also

setEnableFrame


getLinearAttenuation (Direct3dRMLight Class)

 Microsoft SDK for Java

getLinearAttenuation

This method of the Direct3dRMLight Class retrieves the linear attenuation factor for a light.

Syntax

public float getLinearAttenuation();

Return Value

Returns the linear attenuation value.

See Also

setLinearAttenuation


getPenumbra (Direct3dRMLight Class)

 Microsoft SDK for Java

getPenumbra

This method of the Direct3dRMLight Class retrieves the penumbra angle of a spotlight.

Syntax

public float getPenumbra();

Return Value

Returns the penumbra angle.

See Also

setPenumbra


getQuadraticAttenuation (Direct3dRMLight Class)

 Microsoft SDK for Java

getQuadraticAttenuation

This method of the Direct3dRMLight Class retrieves the quadratic attenuation factor for a light.

Syntax

public float getQuadraticAttenuation();

Return Value

Returns the quadratic attenuation value.

See Also

setQuadraticAttenuation


getRange (Direct3dRMLight Class)

 Microsoft SDK for Java

getRange

This method of the Direct3dRMLight Class retrieves the range of the current Direct3dRMLight object.

Syntax

public float getRange();

Return Value

Returns a value describing the range.

See Also

setRange


getType (Direct3dRMLight Class)

 Microsoft SDK for Java

getType

This method of the Direct3dRMLight Class retrieves the type of a given light.

Syntax

public int getType();

Return Value

Returns one value of light type.

See Also

setType


getUmbra (Direct3dRMLight Class)

 Microsoft SDK for Java

getUmbra

This method of the Direct3dRMLight Class retrieves the umbra angle of the Direct3dRMLight object.

Syntax

public float getUmbra();

Return Value

Returns The umbra angle.

See Also

setUmbra


setColor (Direct3dRMLight Class)

 Microsoft SDK for Java

setColor

This method of the Direct3dRMLight Class sets the color of the given light.

Syntax

public void setColor(int c);

Parameters

c The new color of the light.

See Also

getColor


setColorRGB (Direct3dRMLight Class)

 Microsoft SDK for Java

setColorRGB

This method of the Direct3dRMLight Class sets the color of the given light.

Syntax

public void setColorRGB(float r, float g, float b);

Parameters

r | The red element of the new color of the light.
g | The green element of the new color of the light.
b | The blue element of the new color of the light.


setConstantAttenuation (Direct3dRMLight Class)

 Microsoft SDK for Java

setConstantAttenuation

This method of the Direct3dRMLight Class sets the constant attenuation factor for a light.

Syntax

public void setConstantAttenuation(float atn);

Parameters

atn The new attenuation factor.

Remarks

The constant attenuation value affects the light intensity inversely. For example, a constant attenuation value of 2 reduces the intensity of the light by half.

See Also

getConstantAttenuation


setEnableFrame (Direct3dRMLight Class)

 Microsoft SDK for Java

setEnableFrame

This method of the Direct3dRMLight Class sets the enable frame for a light.

Syntax

public void setEnableFrame(Direct3dRMFrame f);

Parameters

f The Direct3dRMFrame object to be the light's enable frame. Child frames of this frame are also enabled for this light source.

See Also

getEnableFrame


setLinearAttenuation (Direct3dRMLight Class)

 Microsoft SDK for Java

setLinearAttenuation

This method of the Direct3dRMLight Class sets the linear attenuation factor for a light.

Syntax

public void setLinearAttenuation(float atn);

Parameters

atn The new attenuation factor.

See Also

getLinearAttenuation


setPenumbra (Direct3dRMLight Class)

 Microsoft SDK for Java

setPenumbra

This method of the Direct3dRMLight Class sets the angle of the penumbra cone.

Syntax

public void setPenumbra(float p);

Parameters

p The new penumbra angle. This angle must be greater than or equal to the angle of the umbra. If you set the penumbra angle to less than the umbra angle, the umbra angle will be set equal to the penumbra angle.

Remarks

By default, the initial penumbra angle is 0.5 radians.

See Also

getPenumbra


setQuadraticAttenuation (Direct3dRMLight Class)

 Microsoft SDK for Java

setQuadraticAttenuation

This method of the Direct3dRMLight Class sets the quadratic attenuation factor for a light.

Syntax

public void setQuadraticAttenuation(float atn);

Parameters

atn The new attenuation factor.

See Also

getQuadraticAttenuation


setRange (Direct3dRMLight Class)

 Microsoft SDK for Java

setRange

This method of the Direct3dRMLight Class sets the range of a light. The light affects only those objects within the range.

Syntax

public void setRange(float rng);

Parameters

rng The new range.

Remarks

By default, the initial range of light is 256.

See Also

getRange


setType (Direct3dRMLight Class)

 Microsoft SDK for Java

setType

This method of the Direct3dRMLight Class changes the light type.

Syntax

public void setType(int t);

Parameters

t The new light type.

See Also

getType


setUmbra (Direct3dRMLight Class)

 Microsoft SDK for Java

setUmbra

This method of the Direct3dRMLight Class sets the angle of the umbra cone.

Syntax

public void setUmbra(float u);

Parameters

u The new umbra angle. This angle must be less than or equal to the angle of the penumbra. If you set the umbra angle to greater than the penumbra angle, the penumbra angle will be set equal to the umbra angle.

Remarks

By default, the initial umbra angle is 0.4 radians.

See Also

getUmbra


Direct3dRMLightArray Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMLightArray Class

Applications use the methods of the Direct3dRMLightArray Class of the com.ms.directX package to organize light objects.

public class Direct3dRMLightArray implements
            IDirect3dRMLightArray
{
  // Methods
  public Direct3dRMLight getElement(int index);
  public int getSize();
}

The Direct3dRMLightArray object is obtained by calling the getLights method.


Methods (Direct3dRMLightArray Class)

 Microsoft SDK for Java

Direct3dRMLightArray Class Methods

The Direct3dRMLightArray Class contains the following methods:

getElement retrieves one of the Direct3dRMLight objects associated with this object.
getSize retrieves the number of Direct3dRMLight objects associated with this object.


getElement (Direct3dRMLightArray Class)

 Microsoft SDK for Java

getElement

This method of the Direct3dRMLightArray Class retrieves one of the Direct3dRMLight objects associated with this object.

Syntax

public Direct3dRMLight getElement(int index);

Return Value

Returns the Direct3dRMLight object if successful; otherwise, returns null.

Parameters

index Identifies the object to return. The index must be a value in the range of 0 to one less than the number returned by the getSize method.


getSize (Direct3dRMLightArray Class)

 Microsoft SDK for Java

getSize

This method of the Direct3dRMLightArray Class retrieves the number of Direct3dRMLight objects associated with this object.

Syntax

public int getSize();

Return Value

Returns the number of objects.


Direct3dRMMaterial Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMMaterial Class

Applications use the methods of the Direct3dRMMaterial Class of the com.ms.directX package to interact with material objects.

public class Direct3dRMMaterial implements IDirect3dRMMaterial
{
  // Methods
  public void getEmissive(float[] r, float[] g, float[] b);
  public float getPower();
  public void getSpecular(float[] r, float[] g, float[] b);
  public void setEmissive(float r, float g, float b);
  public void setPower(float power);
  public void setSpecular(float r, float g, float b);
}

The Direct3dRMMaterial class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

The Direct3dRMMaterial object is obtained by calling the createMaterial method.


Methods (Direct3dRMMaterial Class)

 Microsoft SDK for Java

Direct3dRMMaterial Class Methods

The Direct3dRMMaterial Class contains the following methods:

getEmissive retrieves the setting for the emissive property of a material.
getPower retrieves the power used for the specular exponent in the given material.
getSpecular retrieves the color of the specular highlights of a material.
setEmissive sets the emissive property of a material.
setPower sets the power used for the specular exponent in a material.
setSpecular sets the color of the specular highlights of a material.


getEmissive (Direct3dRMMaterial Class)

 Microsoft SDK for Java

getEmissive

This method of the Direct3dRMMaterial Class retrieves the setting for the emissive property of a material. The setting of this property is the color and intensity of the light that the object emits.

Syntax

public void getEmissive(float[] r, float[] g, float[] b);

Parameters

r | The array variables that receive the red component of the emissive color.
g | The array variables that receive the green component of the emissive color.
b | The array variables that receive the blue component of the emissive color.

See Also

setEmissive


getPower (Direct3dRMMaterial Class)

 Microsoft SDK for Java

getPower

This method of the Direct3dRMMaterial Class retrieves the power used for the specular exponent in the given material.

Syntax

public float getPower();

Return Value

Returns the value specifying the power of the specular exponent.

See Also

setPower


getSpecular (Direct3dRMMaterial Class)

 Microsoft SDK for Java

getSpecular

This method of the Direct3dRMMaterial Class retrieves the color of the specular highlights of a material.

Syntax

public void getSpecular(float[] r, float[] g, float[] b);

Parameters

r | The array variables that receive the red component of the color of the specular highlights when the method returns.
g | The array variables that receive the green component of the color of the specular highlights when the method returns.
b | The array variables that receive the blue component of the color of the specular highlights when the method returns.

See Also

setSpecular


setEmissive (Direct3dRMMaterial Class)

 Microsoft SDK for Java

setEmissive

This method of the Direct3dRMMaterial Class sets the emissive property of a material.

Syntax

public void setEmissive(float r, float g, float b);

Parameters

r | The red component of the emissive color.
g | The green component of the emissive color.
b | The blue component of the emissive color.

See Also

getEmissive


setPower (Direct3dRMMaterial Class)

 Microsoft SDK for Java

setPower

This method of the Direct3dRMMaterial Class sets the power used for the specular exponent in a material.

Syntax

public void setPower(float power);

Parameters

power The new specular exponent.

See Also

getPower


setSpecular (Direct3dRMMaterial Class)

 Microsoft SDK for Java

setSpecular

This method of the Direct3dRMMaterial Class sets the color of the specular highlights of a material.

Syntax

public void setSpecular(float r, float g, float b);

Parameters

r | The red component of the specular highlight color.
g | The green component of the specular highlight color.
b | The blue component of the specular highlight color.

See Also

getSpecular


Direct3dRMMesh Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMMesh Class

Applications use the methods of the Direct3dRMMesh Class of the com.ms.directX package to interact with groups of meshes.

public class Direct3dRMMesh implements IDirect3dRMMesh
{
  // Methods
  public void addGroup(int vcnt, int fcnt, int vPerFace,
        int[] fdata, int[] retId);
  public void getBox(D3dRMBox vector);
  public void getGroup(int id, int[] vcnt, int[] fcnt,
        int[] vPerFace, int[] fDataSize, int[] fdata);
  public int getGroupColor(int id);
  public int getGroupCount();
  public int getGroupMapping(int id);
  public Direct3dRMMaterial getGroupMaterial(int id);
  public int getGroupQuality(int id);
  public void getGroupSize(int id, int[] val);
  public Direct3dRMTexture getGroupTexture(int id);
  public void getVertices(int id, int idx, int vCount,
        Direct3dRMVertex[] v);
  public void getVerticesSize(int id, int idx, int[] cnt);
  public void scale(float sx, float sy, float sz);
  public void setGroupColor(int id, int val);
  public void setGroupColorRGB(int id, float r, float g, float b);
  public void setGroupMapping(int id, int value);
  public void setGroupMaterial(int id, Direct3dRMMaterial val);
  public void setGroupQuality(int id, int value);
  public void setGroupTexture(int id, Direct3dRMTexture val);
  public void setVertices(int id, int idx, int vCount,
        Direct3dRMVertex[] v);
  public void setVerticesAsFloats(int id, int idx, int vCount,
        float[] v);
  public void translate(float tx, float ty, float tz);
}

The Direct3dRMMesh class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

The Direct3dRMMesh object is obtained by calling the createMesh method.


Methods (Direct3dRMMesh Class)

 Microsoft SDK for Java

Direct3dRMMesh Class Methods

The Direct3dRMMesh Class contains the following methods:

addGroup allocates space for a collection of vertices and faces and retrieves an identifier for the group.
getBox retrieves the bounding box containing a Direct3dRMMesh object.
getGroup retrieves the data associated with a specified group.
getGroupColor retrieves the color for a group.
getGroupCount retrieves the number of groups for a given Direct3dRMMesh object.
getGroupMapping returns a description of how textures are mapped to a group in a Direct3dRMMesh object.
getGroupMaterial retrieves the material object associated with a group in a Direct3dRMMesh object.
getGroupQuality retrieves the rendering quality for a specified group in a Direct3dRMMesh object.
getGroupSize retrieves the size of data associated with the group.
getGroupTexture retrieves an address of the texture associated with a group in a Direct3dRMMesh object.
getVertices retrieves the vertex positions for a specified group in a Direct3dRMMesh object.
getVerticesSize retrieves the number of vertex positions from the given index to the end of the array associated with the group.
scale scales a Direct3dRMMesh object by the given scaling factors parallel to the x-, y-, and z-axes in model coordinates.
setGroupColor sets the color of a group in a Direct3dRMMesh object.
setGroupColorRGB sets the color of a group in a Direct3dRMMesh object by using individual RGB values.
setGroupMapping sets the mapping for a group in a Direct3dRMMesh object. setGroupMaterial sets the material associated with a group in a Direct3dRMMesh object.
setGroupQuality sets the rendering quality for a specified group in a Direct3dRMMesh object.
setGroupTexture sets the texture associated with a group in a Direct3dRMMesh object.
setVertices sets the vertex positions for a specified group in a Direct3dRMMesh object.
setVerticesAsFloats sets the vertex positions for a specified group in a Direct3dRMMesh object, using an array of floats.
translate adds the specified offsets to the vertex positions of a Direct3dRMMesh object.


addGroup (Direct3dRMMesh Class)

 Microsoft SDK for Java

addGroup

This method of the Direct3dRMMesh Class allocates space for a collection of vertices and faces and retrieves an identifier for the group.

Syntax

public void addGroup(int vcnt, int fcnt, int vPerFace, int[] fdata, int[] retId);

Parameters

vcnt | The number of vertices in the group.
fcnt | The number of faces in the group.
vPerFace | Number of vertices per face in the group, if all faces have the same vertex count. If the group contains faces with varying vertex counts, this parameter should be zero.
fdata The array variable containing face data.

If the vPerFace parameter specifies a value, this data is simply a list of indices into the group's vertex array. If vPerFace is zero, the vertex indices should be preceded by an integer giving the number of vertices in that face.

For example, if vPerFace is zero and the group is made up of triangular and quadrilateral faces, the data might be in the following form:

3 index index index 4 index index index index 3 index index index ...
retId | The array variable that receives a value identifying the group.

Remarks

A newly added group has the following default properties:

  • White

  • No texture

  • No specular reflection

  • Position, normal, and color of each vertex in the vertex array equal to zero

To set the positions of the vertices, use the setVertices method.


getBox (Direct3dRMMesh Class)

 Microsoft SDK for Java

getBox

This method of the Direct3dRMMesh Class retrieves the bounding box containing a Direct3dRMMesh object. The bounding box gives the minimum and maximum model coordinates in each dimension.

Syntax

public void getBox(D3dRMBox vector);

Parameters

vector A D3dRMBox object that receives the bounding box-coordinates.


getGroup (Direct3dRMMesh Class)

 Microsoft SDK for Java

getGroup

This method of the Direct3dRMMesh Class retrieves the data associated with a specified group.

Syntax

public void getGroup(int id, int[] vcnt, int[] fcnt, int[] vPerFace, int[] fDataSize, int[] fdata);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
vcnt | The array variables that receive the number of vertices for the group.
fcnt | The array variables that receive the number of faces for the group.
vPerFace | The array variable that receives the number of vertices per face for the group.
fDataSize | The array variable that receives the number of values in the array associated with the fdata parameter.
fData | The array variable that receives the face data for the group. The format of this data is the same as was specified in the call to the addGroup method.


getGroupColor (Direct3dRMMesh Class)

 Microsoft SDK for Java

getGroupColor

This method of the Direct3dRMMesh Class retrieves the color for a group.

Syntax

public int getGroupColor(int id);

Return Value

Returns a value specifying the color if successful; otherwise, returns zero.

Parameters

id The group identifier. This identifier must have been produced by using the addGroup method.

See Also

setGroupColor, setGroupColorRGB


getGroupCount (Direct3dRMMesh Class)

 Microsoft SDK for Java

getGroupCount

This method of the Direct3dRMMesh Class retrieves the number of groups for a given Direct3dRMMesh object.

Syntax

public int getGroupCount();

Return Value

Returns the number of groups if successful; otherwise, returns zero.


getGroupMapping (Direct3dRMMesh Class)

 Microsoft SDK for Java

getGroupMapping

This method of the Direct3dRMMesh Class returns a description of how textures are mapped to a group in a Direct3dRMMesh object.

Syntax

public int getGroupMapping(int id);

Return Value

Returns one value of mapping type describing how textures are mapped to a group, if successful; otherwise, returns zero.

Parameters

id The group identifier. This identifier must have been produced by using the addGroup method.

See Also

setGroupMapping


getGroupMaterial (Direct3dRMMesh Class)

 Microsoft SDK for Java

getGroupMaterial

This method of the Direct3dRMMesh Class retrieves the material object associated with a group in a Direct3dRMMesh object.

Syntax

public Direct3dRMMaterial getGroupMaterial(int id);

Return Value

Returns the Direct3dRMMaterial object if successful; otherwise, returns null.

Parameters

id The group identifier. This identifier must have been produced by using the addGroup method.

See Also

setGroupMaterial


getGroupQuality (Direct3dRMMesh Class)

 Microsoft SDK for Java

getGroupQuality

This method of the Direct3dRMMesh Class retrieves the rendering quality for a specified group in a Direct3dRMMesh object.

Syntax

public int getGroupQuality(int id);

Return Value

Returns one or more values of the render quality type if successful; otherwise, returns zero. These values include the shading, lighting, and fill modes for the object.

Parameters

id The group identifier. This identifier must have been produced by using the addGroup method.

See Also

setGroupQuality


getGroupSize (Direct3dRMMesh Class)

 Microsoft SDK for Java

getGroupSize

This method of the Direct3dRMMesh Class retrieves the size of data associated with the group.

Syntax

public void getGroupSize(int id, int[] val);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
val | The array variable that receives the size of the data.

See Also

getGroup


getGroupTexture (Direct3dRMMesh Class)

 Microsoft SDK for Java

getGroupTexture

This method of the Direct3dRMMesh Class retrieves an address of the texture associated with a group in a Direct3dRMMesh object.

Syntax

public Direct3dRMTexture getGroupTexture(int id);

Return Value

Returns the Direct3dRMTexture object if successful; otherwise, returns null.

Parameters

id The group identifier. This identifier must have been produced by using the addGroup method.

See Also

setGroupTexture


getVertices (Direct3dRMMesh Class)

 Microsoft SDK for Java

getVertices

This method of the Direct3dRMMesh Class retrieves the vertex positions for a specified group in a Direct3dRMMesh object.

Syntax

public void getVertices(int id, int idx, int vCount, Direct3dRMVertex[] v);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
idx The index of the D3dRMVertex object to return. The idx parameter is used in an internal data structure, not the v array. The structure follows the following formula:
D3DVECTOR position;    v[0]x  v[1]y  v[2]z
D3DVECTOR normal;      v[3]xn v[4]yn v[5]zn
D3DVALUE tu, tv;       v[6]   v[7]
D3DCOLOR color;        v[8]
                       v[9]x for the next D3dRMVector
vCount | The number of D3dRMVertex objects (vertices) to retrieve.
v | The array of D3dRMVertex objects that receives the vertex positions.

See Also

setVertices


getVerticesSize (Direct3dRMMesh Class)

 Microsoft SDK for Java

getVerticesSize

This method of the Direct3dRMMesh Class retrieves the number of vertex positions from the given index to the end of the array associated with the group.

Syntax

public void getVerticesSize(int id, int idx, int[] cnt);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
idx | The index of the first vertex position to count.
cnt | The array variable that receives the count of vertex positions.

See Also

getVertices


scale (Direct3dRMMesh Class)

 Microsoft SDK for Java

scale

This method of the Direct3dRMMesh Class scales a Direct3dRMMesh object by the given scaling factors parallel to the x-, y-, and z-axes in model coordinates.

Syntax

public void scale(float sx, float sy, float sz);

Parameters

sx | The scaling factor that is applied along the x-axis.
sy | The scaling factor that is applied along the y-axis.
sz | The scaling factor that is applied along the z-axis.


setGroupColor (Direct3dRMMesh Class)

 Microsoft SDK for Java

setGroupColor

This method of the Direct3dRMMesh Class sets the color of a group in a Direct3dRMMesh object.

Syntax

public void setGroupColor(int id, int val);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
val | The color of the group.

See Also

getGroupColor, setGroupColorRGB


setGroupColorRGB (Direct3dRMMesh Class)

 Microsoft SDK for Java

setGroupColorRGB

This method of the Direct3dRMMesh Class sets the color of a group in a Direct3dRMMesh object by using individual RGB values.

Syntax

public void setGroupColorRGB(int id, float r, float g, float b);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
r | The red component of the group color.
g | The green component of the group color.
b | The blue component of the group color.

See Also

getGroupColor, setGroupColor


setGroupMapping (Direct3dRMMesh Class)

 Microsoft SDK for Java

setGroupMapping

This method of the Direct3dRMMesh Class sets the mapping for a group in a Direct3dRMMesh object. The mapping controls how textures are mapped to a surface.

Syntax

public void setGroupMapping(int id, int value);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
value | The mapping type value describing the mapping for the group.

See Also

getGroupMapping


setGroupMaterial (Direct3dRMMesh Class)

 Microsoft SDK for Java

setGroupMaterial

This method of the Direct3dRMMesh Class sets the material associated with a group in a Direct3dRMMesh object.

Syntax

public void setGroupMaterial(int id, Direct3dRMMaterial val);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
val | The Direct3dRMMaterial object to set.

See Also

getGroupMaterial


setGroupQuality (Direct3dRMMesh Class)

 Microsoft SDK for Java

setGroupQuality

This method of the Direct3dRMMesh Class sets the rendering quality for a specified group in a Direct3dRMMesh object.

Syntax

public void setGroupQuality(int id, int value);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
value | The render quality type value. These values include the shading, lighting, and fill modes for the object.

See Also

getGroupQuality


setGroupTexture (Direct3dRMMesh Class)

 Microsoft SDK for Java

setGroupTexture

This method of the Direct3dRMMesh Class sets the texture associated with a group in a Direct3dRMMesh object.

Syntax

public void setGroupTexture(int id, Direct3dRMTexture val);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
val | The Direct3dRMTexture object to set.

See Also

getGroupTexture


setVertices (Direct3dRMMesh Class)

 Microsoft SDK for Java

setVertices

This method of the Direct3dRMMesh Class sets the vertex positions for a specified group in a Direct3dRMMesh object.

Syntax

public void setVertices(int id, int idx, int vCount, Direct3dRMVertex[] v);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
idx The index of the first D3dRMVertex object to set. The idx parameter is used in an internal data structure, not the v array. The structure uses the following format:
D3DVECTOR position;    v[0]x  v[1]y  v[2]z
D3DVECTOR normal;      v[3]xn v[4]yn v[5]zn
D3DVALUE tu, tv;       v[6]   v[7]
D3DCOLOR color;        v[8]
                       v[9]x for the next D3dRMVector
vCount | The number of vertices in the array.
v | An array of D3dRMVertex objects specifying the vertex positions to be set.

Remarks

Vertices are local to the group. If an application needs to share vertices between two different groups (for example, if neighboring faces in a mesh are different colors), the vertices must be duplicated in both groups.

See Also

getVertices


setVerticesAsFloats (Direct3dRMMesh Class)

 Microsoft SDK for Java

setVerticesAsFloats

This method of the Direct3dRMMesh Class sets the vertex positions for a specified group in a Direct3dRMMesh object, using an array of floats.

Syntax

public void setVerticesAsFloats(int id, int idx, int vCount, float[] v);

Parameters

id | The group identifier. This identifier must have been produced by using the addGroup method.
idx | The index of the first D3dRMVertex object to set. The idx parameter is used in an internal data structure, not the v array.
vCount | The number of floats to set.
v | An array of floats specifying the vertex positions to be set.

Remarks

Vertices are local to the group. If an application needs to share vertices between two different groups (for example, if neighboring faces in a mesh are different colors), the vertices must be duplicated in both groups.


translate (Direct3dRMMesh Class)

 Microsoft SDK for Java

translate

This method of the Direct3dRMMesh Class adds the specified offsets to the vertex positions of a Direct3dRMMesh object.

Syntax

public void translate(float tx, float ty, float tz);

Parameters

tx | The offset that is added to the x-coordinate of each vertex position.
ty | The offset that is added to the y-coordinate of each vertex position.
tz | The offset that is added to the z coordinate of each vertex position.


Direct3dRMMeshBuilder Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMMeshBuilder Class

Applications use the methods of the Direct3dRMMeshBuilder Class of the com.ms.directX package to interact with mesh objects.

public class Direct3dRMMeshBuilder implements
            IDirect3dRMMeshBuilder
{
  // Methods
  public void addFace(Direct3dRMFace f);
  public void addFaces(int vCount, D3dVector[] v, int nCount,
        D3dVector[] n, int[] cones);
  public void addFacesAsFloats(int vc, float[] ver, int nc, float[]
        norm, int[] cones);
  public void addFrame(Direct3dRMFrame f);
  public void addMesh(Direct3dRMMesh m);
  public void addMeshBuilder(Direct3dRMMeshBuilder mb);
  public int addNormal(float x, float y, float z);
  public int addVertex(float x, float y, float z);
  public Direct3dRMFace createFace();
  public Direct3dRMFaceArray createFaceArray(int vCount,
        float[] vertices, int nCount, float[] normals,
        int[] cones);
  public Direct3dRMMesh createMesh();
  public void generateNormals();
  public void getBox(D3dRMBox retv);
  public int getColorSource();
  public Direct3dRMMeshBuilder getd3drmMeshBuilder();
  public int getFaceCount();
  public void getFacedataSize(int[] f_cnt);
  public Direct3dRMFaceArray getFaces();
  public void getNormalsSize(int[] n_cnt);
  public int getPerspective();
  public int getQuality();
  public void getTextureCoordinates(int idx, float[] u, float[] v);
  public int getVertexColor(int index);
  public int getVertexCount();
  public void getVertices(int[] vc, D3dvector v, int[] nc,
        D3dvector n, int[] fs, int[] fc);
  public int getVerticesSize();
  public void loadFromFileByPos(String filename, int position,
        int flags, ILoadTextureCallback c, IUnknown pUser);
  public void reserveSpace(int v_cnt, int n_cnt, int f_cnt);
  public void save(String fname, int xFormat, int save);
  public void scale(float sx, float sy, float sz);
  public void setColor(int col);
  public void setColorRGB(float red, float green, float blue);
  public void setColorSource(int val);
  public void setMaterial(Direct3dRMMaterial val);
  public void setNormal(int idx, float x, float y, float z);
  public void setPerspective(int persp);
  public void setQuality(int q);
  public void setTexture(Direct3dRMTexture val);
  public void setTextureCoordinates(int idx, float u, float v);
  public void setTextureTopology(int wrap_u, int wrap_v);
  public void setVertex(int idx, float x, float y, float z);
  public void setVertexColor(int idx, int c);
  public void setVertexColorRGB(int idx, float r, float g, float b);
  public void translate(float tx, float ty, float tz);
}

The Direct3dRMMeshBuilder class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

The Direct3dRMMeshBuilder object is obtained by calling the createMeshBuilder method.

There are two ways to add faces to a mesh object.
The recommended way is to use the addFaces method.

Example

// Create a mesh builder.
mb = myd3drm.createMeshBuilder();

// Add faces to the mesh.
mb.addFaces(vCount, v, nCount, n, cones);

// Create a material to set for the whole mesh.
material = myd3drm.createMaterial();
mb.setMaterial(material); // This works.

Another possible way is to use the addVertex and addNormal methods, then use createFace to create a face, and add the vertices and normals to it. Currently, this procedure fails.

Example

// Create a mesh builder.
mb = myd3drm.createMeshBuilder();
// Add four vertices.
mb.addVertex(x, y, x); // ...
// Add four normals.
mb.addNormal(x, y, z); // ...

// Create a face from the mesh builder.
d3drmface = mb.createFace();

// Use the Direct3dRMFace.addVertexAndNormalIndexed method
// to add the vertex and normals to the face.
d3drmface.addVertexAndNormalIndexed(index, index); // ...

// Create a material to set for the whole mesh.
material = myd3drm.createMaterial();
mb.setMaterial(material); // This faults.


Methods (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

Direct3dRMMeshBuilder Class Methods

The Direct3dRMMeshBuilder Class contains the following methods:

addFace adds a face to a Direct3dRMMeshBuilder object.
addFaces adds a face to the Direct3dRMMeshBuilder object.
addFacesAsFloats adds a face to the Direct3dRMMeshBuilder object.
addFrame adds the contents of a frame to a Direct3dRMMeshBuilder object.
addMesh adds a mesh to a Direct3dRMMeshBuilder object.
addMeshBuilder adds the contents of a Direct3dRMMeshBuilder object to another Direct3dRMMeshBuilder object.
addNormal adds a normal to a Direct3dRMMeshBuilder object.
addVertex adds a vertex to a Direct3dRMMeshBuilder object.
createFace creates a new face with no vertices and adds it to a Direct3dRMMeshBuilder object.
createFaceArray creates a face array for the Direct3dRMMeshBuilder object.
createMesh creates a new mesh from a Direct3dRMMeshBuilder object.
generateNormals processes the Direct3dRMMeshBuilder object and generates vertex normals that are the average of each vertex's adjoining face normals.
getBox retrieves the bounding box containing a Direct3dRMMeshBuilder object.
getColorSource retrieves the color source of a Direct3dRMMeshBuilder object.
getd3drmMeshBuilder retrieves a mesh builder object associated with this object.
getFaceCount retrieves the number of faces in a Direct3dRMMeshBuilder object.
getFacedataSize retrieves the size of the faces in a Direct3dRMFaceArray and stores them in the int array f_cnt.
getFaces retrieves the faces of a Direct3dRMMeshBuilder object.
getNormalsSize retrieves the size of the normals in a Direct3dRMFaceArray and stores them in the int array n_cnt.
getPerspective determines whether perspective correction for a Direct3dRMMeshBuilder object is turned on.
getQuality retrieves the rendering quality of a Direct3dRMMeshBuilder object.
getTextureCoordinates retrieves the texture coordinates of a specified vertex in a Direct3dRMMeshBuilder object.
getVertexColor retrieves the color of a specified vertex in a Direct3dRMMeshBuilder object.
getVertexCount retrieves the number of vertices in a Direct3dRMMeshBuilder object.
getVertices retrieves the vertex, normal, and face data for a Direct3dRMMeshBuilder object.
getVerticesSize retrieves the number of vertices.
loadFromFileByPos loads a Direct3dRMMeshBuilder object.
reserveSpace reserves space within a Direct3dRMMeshBuilder object for the specified number of vertices, normals, and faces.
save saves a Direct3dRMMeshBuilder object.
scale scales a Direct3dRMMeshBuilder object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.
setColor sets all the faces of a Direct3dRMMeshBuilder object to a given color.
setColorRGB sets all the faces of a Direct3dRMMeshBuilder object to a given color.
setColorSource sets the color source of a Direct3dRMMeshBuilder object.
setMaterial sets the material of all the faces of a Direct3dRMMeshBuilder object.
setNormal sets the normal vector of a specified vertex in a Direct3dRMMeshBuilder object.
setPerspective enables or disables perspective-correct texture-mapping for a Direct3dRMMeshBuilder object.
setQuality sets the rendering quality of a Direct3dRMMeshBuilder object.
setTexture sets the texture of all the faces of a Direct3dRMMeshBuilder object.
setTextureCoordinates sets the texture coordinates of a specified vertex in a Direct3dRMMeshBuilder object.
setTextureTopology sets the texture topology of a Direct3dRMMeshBuilder object.
setVertex sets the position of a specified vertex in a Direct3dRMMeshBuilder object.
setVertexColor sets the color of a specified vertex in a Direct3dRMMeshBuilder object.
setVertexColorRGB sets the color of a specified vertex in a Direct3dRMMeshBuilder object.
translate adds the specified offsets to the vertex positions of a Direct3dRMMeshBuilder object.


addFace (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

addFace

This method of the Direct3dRMMeshBuilder Class adds a face to a Direct3dRMMeshBuilder object.

Syntax

public void addFace(Direct3dRMFace f);

Parameters

f The Direct3dRMFace object to add.

Remarks

Any one face can exist in only one mesh at a time.


addFaces (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

addFaces

This method of the Direct3dRMMeshBuilder Class adds a face to the Direct3dRMMeshBuilder object. This method is very similar to addFaces(int, float[], int, float[], int[]) except that it uses D3dVector array objects instead of simple float arrays.

Syntax

public void addFaces(int vCount, D3dVector[] v, int nCount, D3dVector[] n,

        int[] cones);

Parameters

vCount | The number of vertices to use to create the face.
v | An array of vectors that contains the vertices to use to create the face.
nCount The number of normals to use to create the face. If nCount is 0, the data is formatted as follows:
3, 1, 2, 3 //(v[1], v[2], and v[3] make this triangle)
3, 1, 2, 5 //(v[1], v[2], and v[5] make this triangle)
4, 7, 4, 0, 1 //(v[7], v[4], 4[0], and v[1] make this quadrilateral)

However, if nCount is not 0, then the data is as follows:

3, 1, 1, 2, 2, 3, 3 // normals are interlaced.
3, 1, 1, 2, 2, 5, 5
4, 7, 7, 4, 4, 0, 0, 1, 1
n | An array of vectors that contains the normals used to create the face.
cones | Array variable that contains the data associated with the face.


addFacesAsFloats (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

addFacesAsFloats

This method of the Direct3dRMMeshBuilder Class adds a face to the Direct3dRMMeshBuilder object.

Syntax

public void addFacesAsFloats(int vc, float[] ver, int nc, float[] norm, int[] cones);

Parameters

vc | Number of vertices. This is one-third the size of the float array.
ver | A float array variable that contains the vertices to use to create the face.
nc | Number of normals. This is one-third the size of the float array.
norm | A float array variable that contains the normals to use to create the face.
cones | Array variable that contains the data associated with the face.


addFrame (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

addFrame

This method of the Direct3dRMMeshBuilder Class adds the contents of a frame to a Direct3dRMMeshBuilder object.

Syntax

public void addFrame(Direct3dRMFrame f);

Parameters

f The Direct3dRMFrame object to add.

Remarks

The source frame is not modified or referenced by this operation.


addMesh (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

addMesh

This method of the Direct3dRMMeshBuilder Class adds a mesh to a Direct3dRMMeshBuilder object.

Syntax

public void addMesh(Direct3dRMMesh m);

Parameters

m The Direct3dRMMesh object to add.


addMeshBuilder (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

addMeshBuilder

This method of the Direct3dRMMeshBuilder Class adds the contents of a Direct3dRMMeshBuilder object to another Direct3dRMMeshBuilder object.

Syntax

public void addMeshBuilder(Direct3dRMMeshBuilder mb);

Parameters

mb The Direct3dRMMeshBuilder object to add.

Remarks

The source Direct3dRMMeshBuilder object is not modified or referenced by this operation.


addNormal (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

addNormal

This method of the Direct3dRMMeshBuilder Class adds a normal to a Direct3dRMMeshBuilder object.

Syntax

public int addNormal(float x, float y, float z);

Return Value

Returns the index of the normal.

Parameters

x | The x component of the direction of the new normal
y | The y component of the direction of the new normal
z | The z component of the direction of the new normal.


addVertex (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

addVertex

This method of the Direct3dRMMeshBuilder Class adds a vertex to a Direct3dRMMeshBuilder object.

Syntax

public int addVertex(float x, float y, float z);

Return Value

Returns the index of the vertex.

Parameters

x | The x component of the position of the new vertex.
y | The y component of the position of the new vertex.
z | The z component of the position of the new vertex.


createFace (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

createFace

This method of the Direct3dRMMeshBuilder Class creates a new face with no vertices and adds it to a Direct3dRMMeshBuilder object.

Syntax

public Direct3dRMFace createFace();

Return Value

Returns the Direct3dRMFace object if successful; otherwise, returns null


createFaceArray (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

createFaceArray

This method of the Direct3dRMMeshBuilder Class creates a face array for the Direct3dRMMeshBuilder object.

Syntax

public Direct3dRMFaceArray createFaceArray(int vCount, float[] vertices, int nCount, float[] normals, int[] cones);

Return Value

Returns the Direct3dRMFaceArray object if successful; otherwise, null

Parameters

vCount | The number of vertices. This is one-third the size of the float array.
vertices | the array variable that contains the vertices used to create the face array.
nCount | the number of normals. This is one-third the size of the float array.
normals | The array variable that contains the normals used to create the face array.
cones | The array variable that contains the data associated with the face array.


createMesh (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

createMesh

This method of the Direct3dRMMeshBuilder Class creates a new mesh from a Direct3dRMMeshBuilder object.

Syntax

public Direct3dRMMesh createMesh();

Return Value

Returns the Direct3dRMMesh object if successful; otherwise, returns null


generateNormals (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

generateNormals

This method of the Direct3dRMMeshBuilder Class processes the Direct3dRMMeshBuilder object and generates vertex normals that are the average of each vertex's adjoining face normals.

Syntax

public void generateNormals();

Remarks

Averaging the normals of back-to-back faces produces a zero normal.


getBox (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getBox

This method of the Direct3dRMMeshBuilder Class retrieves the bounding box containing a Direct3dRMMeshBuilder object. The bounding box gives the minimum and maximum model coordinates in each dimension.

Syntax

public void getBox(D3dRMBox retv);

Parameters

retv A D3dRMBox object that receives the bounding box-coordinates.


getColorSource (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getColorSource

This method of the Direct3dRMMeshBuilder Class retrieves the color source of a Direct3dRMMeshBuilder object. The color source can be either a face or a vertex.

Syntax

public int getColorSource();

Return Value

Returns a value of color source type.

See Also

setColorSource


getd3drmMeshBuilder (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getd3drmMeshBuilder

This method of the Direct3dRMMeshBuilder Class retrieves a mesh builder object associated with this object.

Syntax

public Direct3dRMMeshBuilder getd3drmMeshBuilder();

Return Value

Returns the Direct3dRMMeshBuilder object if successful; otherwise, returns null


getFaceCount (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getFaceCount

This method of the Direct3dRMMeshBuilder Class retrieves the number of faces in a Direct3dRMMeshBuilder object.

Syntax

public int getFaceCount();

Return Value

Returns the number of faces.


getFacedataSize (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getFacedataSize

This method of the Direct3dRMMeshBuilder Class retrieves the size of the faces in a Direct3dRMFaceArray and stores them in the int array f_cnt.

Syntax

public void getFacedataSize(int[] f_cnt);

Parameters

f_cnt The array that stores the sizes of the faces that are measured.


getFaces (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getFaces

This method of the Direct3dRMMeshBuilder Class retrieves the faces of a Direct3dRMMeshBuilder object.

Syntax

public Direct3dRMFaceArray getFaces();

Return Value

Returns the Direct3dRMFaceArray object if successful; otherwise, returns null


getNormalsSize (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getNormalsSize

This method of the Direct3dRMMeshBuilder Class retrieves the size of the normals in a Direct3dRMFaceArray and stores them in the int array n_cnt.

Syntax

public void getNormalsSize(int[] n_cnt);

Parameters

n_cnt The array that stores the sizes of the faces that are measured.


getPerspective (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getPerspective

This method of the Direct3dRMMeshBuilder Class determines whether perspective correction for a Direct3dRMMeshBuilder object is turned on.

Syntax

public int getPerspective();

Return Value

Returns true if perspective correction is on, otherwise, returns false.


getQuality (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getQuality

This method of the Direct3dRMMeshBuilder Class retrieves the rendering quality of a Direct3dRMMeshBuilder object.

Syntax

public int getQuality();

Return Value

Returns a value that specifies the rendering quality of the mesh.

See Also

setQuality


getTextureCoordinates (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getTextureCoordinates

This method of the Direct3dRMMeshBuilder Class retrieves the texture coordinates of a specified vertex in a Direct3dRMMeshBuilder object.

Syntax

public void getTextureCoordinates(int idx, float[] u, float[] v);

Parameters

idx | The index of the vertex.
u | The array variables that receive the texture coordinates of the vertex.
v | The array variables that receive the texture coordinates of the vertex.

See Also

setTextureCoordinates


getVertexColor (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getVertexColor

This method of the Direct3dRMMeshBuilder Class retrieves the color of a specified vertex in a Direct3dRMMeshBuilder object.

Syntax

public int getVertexColor(int index);

Return Value

Returns the color.

Parameters

index The index of the vertex.

See Also

setVertexColor


getVertexCount (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getVertexCount

This method of the Direct3dRMMeshBuilder Class retrieves the number of vertices in a Direct3dRMMeshBuilder object.

Syntax

public int getVertexCount();

Return Value

Returns the number of vertices.


getVertices (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getVertices

This method of the Direct3dRMMeshBuilder Class retrieves the vertex, normal, and face data for a Direct3dRMMeshBuilder object.

Syntax

public void getVertices(int[] vc, D3dvector v, int[] nc, D3dvector n, int[] fs, int[] fc);

Parameters

vc | The array variable that receives the number of vertices.
v | A D3dVector object that receives the vertices for the Direct3dRMMeshBuilder object.
nc | The array variable that receives the number of normals.
n | A D3dVector object that receives the normals for the Direct3dRMMeshBuilder object.
fs | The array variable that receives the length of the array associated with the fc parameter.
fc | The array variable that receives the face data for the Direct3dRMMeshBuilder object. This data is in the same format as specified in the addFacesToMesh method except that it is null-terminated.


getVerticesSize (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

getVerticesSize

This method of the Direct3dRMMeshBuilder Class retrieves the number of vertices.

Syntax

public int getVerticesSize();

Return Value

Returns the number of vertices.

See Also

getVertices


loadFromFileByPos (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

loadFromFileByPos

This method of the Direct3dRMMeshBuilder Class loads a Direct3dRMMeshBuilder object.

Syntax

public void loadFromFileByPos(String filename, int position, int flags, ILoadTextureCallback c, IUnknown pUser);

Parameters

filename | The name of the file containing the object to be loaded.
position | The position of the object to be loaded. The value gives the object's order in the file.
flags | The load options type value.
c | The callback interface that contains a load texture callback function called to load textures used by an object that require special formatting. This parameter can be null.
pUser | Application-defined data passed to the load texture callback function.

Remarks

By default, this method loads the first mesh from the file specified by the filename parameter.


reserveSpace (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

reserveSpace

This method of the Direct3dRMMeshBuilder Class reserves space within a Direct3dRMMeshBuilder object for the specified number of vertices, normals, and faces. This allows the system to use memory more efficiently.

Syntax

public void reserveSpace(int v_cnt, int n_cnt, int f_cnt);

Parameters

v_cnt | The number of vertices to allocate space for.
n_cnt | The number of normals to allocate space for.
f_cnt | The number of faces to allocate space for.


save (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

save

This method of the Direct3dRMMeshBuilder Class saves a Direct3dRMMeshBuilder object.

Syntax

public void save(String fname, int xFormat, int save);

Parameters

fname | The name of the created file. This file must have a .X file name extension.
xFormat | D3DRMXOF_TEXT.
save | A value of the save options type.


scale (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

scale

This method of the Direct3dRMMeshBuilder Class scales a Direct3dRMMeshBuilder object by the given scaling factors, parallel to the x-, y-, and z-axes in model coordinates.

Syntax

public void scale(float sx, float sy, float sz);

Parameters

sx | The scaling factors that are applied along the x-axis.
sy | the scaling factors that are applied along the y-axis.
sz | The scaling factors that are applied along the z-axis.


setColor (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setColor

This method of the Direct3dRMMeshBuilder Class sets all the faces of a Direct3dRMMeshBuilder object to a given color.

Syntax

public void setColor(int col);

Parameters

col The color of the faces.


setColorRGB (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setColorRGB

This method of the Direct3dRMMeshBuilder Class sets all the faces of a Direct3dRMMeshBuilder object to a given color.

Syntax

public void setColorRGB(float red, float green, float blue);

Parameters

red | The red component of the color.
green | The green component of the color.
blue | The blue component of the color.


setColorSource (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setColorSource

This method of the Direct3dRMMeshBuilder Class sets the color source of a Direct3dRMMeshBuilder object.

Syntax

public void setColorSource(int val);

Parameters

val The value of color source type that specifies the new color source to use.

Remarks

This method does not exhibit expected behavior under certain circumstances. If you use this method to set colors to faces, then it works as expected. But if you try to set colors for individual vertices, it wont, because face data is still used. To set vertice's colors, call the createMesh method and set individual vertex colors with the setVertex method.

See Also

getColorSource


setMaterial (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setMaterial

This method of the Direct3dRMMeshBuilder Class sets the material of all the faces of a Direct3dRMMeshBuilder object.

Syntax

public void setMaterial(Direct3dRMMaterial val);

Parameters

val The Direct3dRMMaterial object to set.


setNormal (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setNormal

This method of the Direct3dRMMeshBuilder Class sets the normal vector of a specified vertex in a Direct3dRMMeshBuilder object.

Syntax

public void setNormal(int idx, float x, float y, float z);

Parameters

idx | The index of the normal to be set.
x | The x component of the vector to assign to the specified normal.
y | The y component of the vector to assign to the specified normal.
z | The z component of the vector to assign to the specified normal.


setPerspective (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setPerspective

This method of the Direct3dRMMeshBuilder Class enables or disables perspective-correct texture-mapping for a Direct3dRMMeshBuilder object.

Syntax

public void setPerspective(int persp);

Parameters

persp Specify true if the mesh should be texture-mapped with perspective correction, otherwise, specify false.


setQuality (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setQuality

This method of the Direct3dRMMeshBuilder Class sets the rendering quality of a Direct3dRMMeshBuilder object.

Syntax

public void setQuality(int q);

Parameters

q The value that specifies the new rendering quality to use.

See Also

getQuality


setTexture (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setTexture

This method of the Direct3dRMMeshBuilder Class sets the texture of all the faces of a Direct3dRMMeshBuilder object.

Syntax

public void setTexture(Direct3dRMTexture val);

Parameters

val The Direct3dRMTexture object to set.


setTextureCoordinates (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setTextureCoordinates

This method of the Direct3dRMMeshBuilder Class sets the texture coordinates of a specified vertex in a Direct3dRMMeshBuilder object.

Syntax

public void setTextureCoordinates(int idx, float u, float v);

Parameters

idx | The index of the vertex to be set.
u | The texture u coordinate to assign to the specified mesh vertex.
v | The texture v coordinate to assign to the specified mesh vertex.

See Also

getTextureCoordinates


setTextureTopology (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setTextureTopology

This method of the Direct3dRMMeshBuilder Class sets the texture topology of a Direct3dRMMeshBuilder object.

Syntax

public void setTextureTopology(int wrap_u, int wrap_v);

Parameters

wrap_u | Specify true if you want the texture to have a cylindrical topology in the u dimension; otherwise, specify false.
wrap_v | Specify true if you want the texture to have a cylindrical topology in the v dimension; otherwise, specify false. You can use any combination of true and false for these parameters. (Both can be true, both can be false, and so on.)


setVertex (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setVertex

This method of the Direct3dRMMeshBuilder Class sets the position of a specified vertex in a Direct3dRMMeshBuilder object.

Syntax

public void setVertex(int idx, float x, float y, float z);

Parameters

idx | The index of the vertex to be set.
x | The x component of the position to assign to the specified vertex.
y | The y component of the position to assign to the specified vertex.
z | The z component of the position to assign to the specified vertex.


setVertexColor (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setVertexColor

This method of the Direct3dRMMeshBuilder Class sets the color of a specified vertex in a Direct3dRMMeshBuilder object.

Syntax

public void setVertexColor(int idx, int c);

Parameters

idx | The index of the vertex to be set.
c | The color to assign to the specified vertex.

See Also

getVertexColor


setVertexColorRGB (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

setVertexColorRGB

This method of the Direct3dRMMeshBuilder Class sets the color of a specified vertex in a Direct3dRMMeshBuilder object.

Syntax

public void setVertexColorRGB(int idx, float r, float g, float b);

Parameters

idx | The index of the vertex to be set.
r | The red component of the color assigned to the specified vertex.
g | The green component of the color assigned to the specified vertex.
b | The blue component of the color assigned to the specified vertex.


translate (Direct3dRMMeshBuilder Class)

 Microsoft SDK for Java

translate

This method of the Direct3dRMMeshBuilder Class adds the specified offsets to the vertex positions of a Direct3dRMMeshBuilder object.

Syntax

public void translate(float tx, float ty, float tz);

Parameters

tx | The offset that is added to the x-coordinate of each vertex position.
ty | The offset that is added to the y-coordinate of each vertex position.
tz | The offset that is added to the z coordinate of each vertex position.


Direct3dRMObject Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMObject Class

Applications use the methods of the Direct3dRMObject Class of the com.ms.directX package to work with the object superclass of Direct3dRM objects.

public class Direct3dRMObject implements IDirect3dRMObject
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMObject duplicate();
  public int getAppData();
  public String getClassName();
  public String getName();
  public void setAppData(int data);
  public void setName(String name);
}


Methods (Direct3dRMObject Class)

 Microsoft SDK for Java

Direct3dRMObject Class Methods

The Direct3dRMObject Class contains the following methods:

addDestroyCallback registers a function to be called when an object is destroyed.
deleteDestroyCallback removes a function previously registered with the addDestroyCallback method.
duplicate creates a copy of an object.
getAppData retrieves the 32 bits of application-specific data in the object. The default value is 0.
getClassName retrieves the name of the object's class.
getName retrieves the object name.
setAppData sets the 32 bits of application-specific data in the object.
setName sets the object's name.


addDestroyCallback (Direct3dRMObject Class)

 Microsoft SDK for Java

addDestroyCallback

This method of the Direct3dRMObject Class registers a function to be called when an object is destroyed.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);

Parameters

fn | The callback interface that contains a user-defined callback function that will be called when the object is destroyed.
Arg | Application-defined data passed to the callback function. Because this function is called after the object has been destroyed, you should not call this function with the object as an argument.


deleteDestroyCallback (Direct3dRMObject Class)

 Microsoft SDK for Java

deleteDestroyCallback

This method of the Direct3dRMObject Class removes a function previously registered with the addDestroyCallback method.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);

Parameters

fn | The callback interface that contains a user-defined callback function that will be called when the object is destroyed.
args | Application-defined data passed to the callback function.


duplicate (Direct3dRMObject Class)

 Microsoft SDK for Java

duplicate

This method of the Direct3dRMObject Class creates a copy of an object.

Syntax

public Direct3dRMObject duplicate();

Return Value

Returns the Direct3dRMObject object if successful; otherwise, returns null.


getAppData (Direct3dRMObject Class)

 Microsoft SDK for Java

getAppData

This method of the Direct3dRMObject Class retrieves the 32 bits of application-specific data in the object. The default value is 0.

Syntax

public int getAppData();

Return Value

Returns the data value defined by the application.

See Also

setAppData


getClassName (Direct3dRMObject Class)

 Microsoft SDK for Java

getClassName

This method of the Direct3dRMObject Class retrieves the name of the object's class.

Syntax

public String getClassName();

Return Value

Returns the name of the class.


getName (Direct3dRMObject Class)

 Microsoft SDK for Java

getName

This method of the Direct3dRMObject Class retrieves the object name.

Syntax

public String getName();

Return Value

Returns the name of the object.

See Also

setName


setAppData (Direct3dRMObject Class)

 Microsoft SDK for Java

setAppData

This method of the Direct3dRMObject Class sets the 32 bits of application-specific data in the object.

Syntax

public void setAppData(int data);

Parameters

data A user-defined integer. You cannot use this method to set a generic Java Object.

See Also

getAppData


setName (Direct3dRMObject Class)

 Microsoft SDK for Java

setName

This method of the Direct3dRMObject Class sets the object's name.

Syntax

public void setName(String name);

Parameters

name A String that contains the name of the object.

See Also

getName


Direct3dRMPickArray Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMPickArray Class

Applications use the methods of the Direct3dRMPickArray Class of the com.ms.directX package to organize pick objects.

public class Direct3dRMPickArray implements
            IDirect3dRMPickArray
{
  // Methods
  public Direct3dRMFrameArray getPickFrame(int index, D3dRMPickDesc
        desc);
  public Direct3dRMVisual getPickVisual(int index,
        D3dRMPickDesc desc);
  public int getSize();
}

The Direct3dRMPickArray object is obtained by calling the pick method.


Methods (Direct3dRMPickArray Class)

 Microsoft SDK for Java

Direct3dRMPickArray Class Methods

The Direct3dRMPickArray Class contains the following methods:

getPickFrame retrieves a Direct3dRMFrameArray object associated with this object.
getPickVisual returns one of the Direct3dRMVisual objects associated with this object.
getSize retrieves the number of Direct3dRMVisual and Direct3dRMFrameArray objects associated with this object.


getPickFrame (Direct3dRMPickArray Class)

 Microsoft SDK for Java

getPickFrame

This method of the Direct3dRMPickArray Class retrieves a Direct3dRMFrameArray object associated with this object.

Syntax

public Direct3dRMFrameArray getPickFrame(int index, D3dRMPickDesc desc);

Return Value

Returns the Direct3dRMFrameArray object if successful; otherwise, returns null.

Parameters

index | The object to return. The index must be a value in the range of 0 to one less than the number returned by the getSize method.
desc | The D3dRMPickDesc object that receives the pick description.


getPickVisual (Direct3dRMPickArray Class)

 Microsoft SDK for Java

getPickVisual

This method of the Direct3dRMPickArray Class returns one of the Direct3dRMVisual objects associated with this object.

Syntax

public Direct3dRMVisual getPickVisual(int index, D3dRMPickDesc desc);

Return Value

Returns the Direct3dRMVisual object if successful; otherwise, returns null.

Parameters

index | The object to return. The index must be a value in the range of 0 to one less than the number returned by the getSize method.
desc | The D3dRMPickDesc object that receives the pick description.


getSize (Direct3dRMPickArray Class)

 Microsoft SDK for Java

getSize

This method of the Direct3dRMPickArray Class retrieves the number of Direct3dRMVisual and Direct3dRMFrameArray objects associated with this object.

Syntax

public int getSize();

Return Value

Returns the number of objects.


Direct3dRMTexture Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMTexture Class

Applications use the methods of the Direct3dRMTexture Class of the com.ms.directX package to work with textures, which are rectangular arrays of pixels.

public class Direct3dRMTexture implements IDirect3dRMTexture
{
  // Methods
  public void changed(int pixels, int palette);
  public int getColors();
  public void getDecalOrigin(int[] x, int[] y);
  public int getDecalScale();
  public void getDecalSize(float[] w, float[] h);
  public int getDecalTransparency();
  public int getDecalTransparentColor();
  public Direct3dRMImage getImage();
  public void getImageBuffer(byte[] buffer1);
  public void getImagePalette(byte[] pal);
  public int getShades();
  public void setColors(int c);
  public void setDecalOrigin(int x, int y);
  public void setDecalScale(int s);
  public void setDecalSize(float width, float height);
  public void setDecalTransparency(int trans);
  public void setDecalTransparentColor(int tcolor);
  public void setShades(int s);
}

The Direct3dRMTexture class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

The Direct3dRMTexture object is obtained by calling the createTexture method.


Methods (Direct3dRMTexture Class)

 Microsoft SDK for Java

Direct3dRMTexture Class Methods

The Direct3dRMTexture Class contains the following methods:

changed informs the renderer that the application has changed the pixels or the palette of a texture.
getColors retrieves the maximum number of colors used for rendering a texture.
getDecalOrigin retrieves the current origin of the decal.
getDecalScale retrieves the scaling property of the given decal.
getDecalSize retrieves the size of the decal.
getDecalTransparency retrieves the transparency property of the decal.
getDecalTransparentColor retrieves the transparent color of the decal.
getImage retrieves the image that the texture is created with.
getImageBuffer retrieves the image buffer that the texture is created with.
getImagePalette retrieves the image palette that the texture is created with.
getShades retrieves the number of shades used for each color in the texture when rendering.
setColors sets the maximum number of colors used for rendering a texture.
setDecalOrigin sets the decal origin as an offset from the top left of the decal.
setDecalScale sets the scaling property for a decal.
setDecalSize sets the size of the decal to be used if the decal is being scaled according to its depth in the scene.
setDecalTransparency sets the transparency property of the decal.
setDecalTransparentColor sets the transparent color for a decal.
setShades sets the maximum number of shades to use for each color for the texture when rendering.


changed (Direct3dRMTexture Class)

 Microsoft SDK for Java

changed

This method of the Direct3dRMTexture Class informs the renderer that the application has changed the pixels or the palette of a texture.

Syntax

public void changed(int pixels, int palette);

Parameters

pixels | If this parameter is true, the pixels have changed.
palette | If this parameter is true, the palette has changed.


getColors (Direct3dRMTexture Class)

 Microsoft SDK for Java

getColors

This method of the Direct3dRMTexture Class retrieves the maximum number of colors used for rendering a texture.

Syntax

public int getColors();

Return Value

Returns the number of colors.

Remarks

This method returns the number of colors that the texture has been quantized to, not the number of colors in the image that the texture was created from. Consequently, the number of colors that are returned usually matches the number ofcolors that were set by calling the setDefaultTextureColors method, unless you explicitly used the setColors method to change the colors for the texture.

See Also

setColors


getDecalOrigin (Direct3dRMTexture Class)

 Microsoft SDK for Java

getDecalOrigin

This method of the Direct3dRMTexture Class retrieves the current origin of the decal.

Syntax

public void getDecalOrigin(int[] x, int[] y);

Parameters

x | The array variables that receive the x-coordinate of the origin of the decal.
y | The array variables that receive the y-coordinate of the origin of the decal.

See Also

setDecalOrigin


getDecalScale (Direct3dRMTexture Class)

 Microsoft SDK for Java

getDecalScale

This method of the Direct3dRMTexture Class retrieves the scaling property of the given decal.

Syntax

public int getDecalScale();

Return Value

Returns the scaling property if successful; otherwise, returns -1.

See Also

setDecalScale


getDecalSize (Direct3dRMTexture Class)

 Microsoft SDK for Java

getDecalSize

This method of the Direct3dRMTexture Class retrieves the size of the decal.

Syntax

public void getDecalSize(float[] w, float[] h);

Parameters

w | The addresses of variables that will be filled with the width of the decal when the method returns.
h | The addresses of variables that will be filled with the height of the decal when the method returns.

See Also

setDecalSize


getDecalTransparency (Direct3dRMTexture Class)

 Microsoft SDK for Java

getDecalTransparency

This method of the Direct3dRMTexture Class retrieves the transparency property of the decal.

Syntax

public int getDecalTransparency();

Return Value

Returns true if the decal has a transparent color; otherwise, returns false.

See Also

setDecalTransparency


getDecalTransparentColor (Direct3dRMTexture Class)

 Microsoft SDK for Java

getDecalTransparentColor

This method of the Direct3dRMTexture Class retrieves the transparent color of the decal.

Syntax

public int getDecalTransparentColor();

Return Value

Returns the value of the transparent color.

See Also

setDecalTransparentColor


getImage (Direct3dRMTexture Class)

 Microsoft SDK for Java

getImage

This method of the Direct3dRMTexture Class retrieves the image that the texture is created with.

Syntax

public Direct3dRMImage getImage();

Return Value

Returns the D3dRMImage object that the current texture was created with.


getImageBuffer (Direct3dRMTexture Class)

 Microsoft SDK for Java

getImageBuffer

This method of the Direct3dRMTexture Class retrieves the image buffer that the texture is created with.

Syntax

public void getImageBuffer(byte[] buffer1);

Parameters

buffer1 The image buffer.


getImagePalette (Direct3dRMTexture Class)

 Microsoft SDK for Java

getImagePalette

This method of the Direct3dRMTexture Class retrieves the image palette that the texture is created with.

Syntax

public void getImagePalette(byte[] pal);

Parameters

pal The image palette.


getShades (Direct3dRMTexture Class)

 Microsoft SDK for Java

getShades

This method of the Direct3dRMTexture Class retrieves the number of shades used for each color in the texture when rendering.

Syntax

public int getShades();

Return Value

Returns the number of shades.

See Also

setShades


setColors (Direct3dRMTexture Class)

 Microsoft SDK for Java

setColors

This method of the Direct3dRMTexture Class sets the maximum number of colors used for rendering a texture. This method is required only in the ramp color model.

Syntax

public void setColors(int c);

Parameters

c The number of colors.

Remarks

By default, the initial number of colors is 8.

See Also

getColors


setDecalOrigin (Direct3dRMTexture Class)

 Microsoft SDK for Java

setDecalOrigin

This method of the Direct3dRMTexture Class sets the decal origin as an offset from the top left of the decal.

Syntax

public void setDecalOrigin(int x, int y);

Parameters

x | The x-coordinate of the new origin for the decal.
y | The y-coordinate of the new origin for the decal.

Remarks

The decal origin is mapped to its frame's position when rendering. For example, the origin of a decal of a cross would be set to the middle of the decal, and the origin of an arrow pointing down would be set to midway along the bottom edge.

By default, the initial decal origin is [0, 0].

See Also

getDecalOrigin


setDecalScale (Direct3dRMTexture Class)

 Microsoft SDK for Java

setDecalScale

This method of the Direct3dRMTexture Class sets the scaling property for a decal.

Syntax

public void setDecalScale(int s);

Parameters

s If this parameter is true, depth is taken into account when the decal is scaled. If it is false, depth information is ignored.

Remarks

By default, the initial decal scaling property is true.

See Also

getDecalScale


setDecalSize (Direct3dRMTexture Class)

 Microsoft SDK for Java

setDecalSize

This method of the Direct3dRMTexture Class sets the size of the decal to be used if the decal is being scaled according to its depth in the scene.

Syntax

public void setDecalSize(float width, float height);

Parameters

width | The new width of the decal, in model coordinates.
height | The new height of the decal, in model coordinates.

Remarks

By default, the initial decal size is [1, 1].

See Also

getDecalSize


setDecalTransparency (Direct3dRMTexture Class)

 Microsoft SDK for Java

setDecalTransparency

This method of the Direct3dRMTexture Class sets the transparency property of the decal.

Syntax

public void setDecalTransparency(int trans);

Parameters

trans If this parameter is true, the decal has a transparent color. If it is false, it has an opaque color.

Remarks

By default, the initial transparency property is false.

See Also

getDecalTransparency


setDecalTransparentColor (Direct3dRMTexture Class)

 Microsoft SDK for Java

setDecalTransparentColor

This method of the Direct3dRMTexture Class sets the transparent color for a decal.

Syntax

public void setDecalTransparentColor(int tcolor);

Parameters

tcolor The new transparent color.

Remarks

By default, the initial transparent color is black.

See Also

getDecalTransparentColor


setShades (Direct3dRMTexture Class)

 Microsoft SDK for Java

setShades

This method of the Direct3dRMTexture Class sets the maximum number of shades to use for each color for the texture when rendering. This method is required only in the ramp color model.

Syntax

public void setShades(int s);

Parameters

s The new number of shades. This value must be a power of 2.

Remarks

By default, the initial number of shades is 16.

See Also

getShades


Direct3dRMUserVisual Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMUserVisual Class

Applications use the Direct3dRMUserVisual Class of the com.ms.directX package to manage user visual objects.

public class Direct3dRMUserVisual implements
            IDirect3dRMUserVisual
{

Note This class does not provide an init method. Use the Direct3dRM.createUserVisual method to create and initialize Direct3dRMUserVisual objects.

The Direct3dRMUserVisual class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName


Direct3dRMViewport Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMViewport Class

Applications use the methods of the Direct3dRMViewport Class of the com.ms.directX package to work with viewport objects.

public class Direct3dRMViewport implements IDirect3dRMViewport
{
  // Methods
  public void clear();
  public void configure(int x, int y, int width, int height);
  public void forceUpdate(int x1, int y1, int x2, int y2);
  public float getBack();
  public Direct3dRMFrame getCamera();
  public Direct3dRMDevice getDevice();
  public Direct3dViewport getDirect3DViewport();
  public float getField();
  public float getFront();
  public int getHeight();
  public void getPlane(float[] l, float[] r, float[] b, float[] t);
  public int getProjection();
  public int getUniformScaling();
  public int getWidth();
  public int getX();
  public int getY();
  public void inverseTransform(D3dVector d, D3dRMVector4d s);
  public Direct3dRMPickedArray pick(int x, int y);
  public void render(Direct3dRMFrame f);
  public void setBack(float v);
  public void setCamera(Direct3dRMFrame f);
  public void setField(float v);
  public void setFront(float v);
  public void setPlane(float left, float right, float bottom, float
        top);
  public void setProjection(int val);
  public void setUniformScaling(int flag);
  public void transform(D3dRMVector4d d, D3dVector s);
}

The Direct3dRMViewport class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

Note This class does not provide an init method. Use the Direct3dRM.createViewport method to create and initialize Direct3dRMViewport objects.


Methods (Direct3dRMViewport Class)

 Microsoft SDK for Java

Direct3dRMViewport Class Methods

The Direct3dRMViewport Class contains the following methods:

clear clears the given viewport to the current background color.
configure reconfigures the viewport origin and dimensions.
forceUpdate forces an area of the viewport to be updated.
getBack retrieves the position of the viewport back clipping plane.
getCamera retrieves the camera for a viewport.
getDevice retrieves the device associated with a viewport.
getDirect3DViewport retrieves the Microsoft® Direct3D® viewport corresponding to the current Direct3dRMViewport object.
getField retrieves the viewport's field of view.
getFront retrieves the position of the viewport's front clipping plane.
getHeight retrieves the height (measured in pixels) of the viewport.
getPlane retrieves the dimensions of the viewport on the front clipping plane.
getProjection retrieves the viewport's projection type. A viewport can use either orthographic or perspective projection.
getUniformScaling retrieves the scaling property used to scale the viewing volume into the larger dimension of the window.
getWidth retrieves the width (measured in pixels) of the viewport.
getX retrieves the x-offset of the start of the viewport on a device.
getY retrieves the y-offset of the start of the viewport on a device.
inverseTransform transforms the vector in the s parameter (measured in screen coordinates) to world coordinates and returns the result in the d parameter.
pick finds a depth-sorted list of objects (and faces, if relevant) that includes the path taken in the hierarchy, from the root down to the frame that contained the object.
render renders a frame hierarchy to the given viewport.
setBack sets the position of the back clipping plane for a viewport.
setCamera sets a camera for a viewport.
setField sets the viewport field of view.
setFront sets the position of the front clipping plane for a viewport.
setPlane sets the dimensions of the viewport on the front clipping plane, relative to the camera's z-axis.
setProjection sets the viewport projection.
setUniformScaling sets the scaling property used to scale the viewing volume into the larger dimension of the window.
transform transforms the vector in the s parameter (measured in world coordinates) to screen coordinates and returns the result in the d parameter.


clear (Direct3dRMViewport Class)

 Microsoft SDK for Java

clear

This method of the Direct3dRMViewport Class clears the given viewport to the current background color.

Syntax

public void clear();


configure (Direct3dRMViewport Class)

 Microsoft SDK for Java

configure

This method of the Direct3dRMViewport Class reconfigures the viewport origin and dimensions.

Syntax

public void configure(int x, int y, int width, int height);

Parameters

x | The x-coordinate of the new viewport position.
y | The y-coordinate of the new viewport position.
width | The new width of the viewport (in pixels).
height | The new height of the viewport (in pixels).

Remarks

This method carries out no action if x + width or y + height are greater than the width or height of the device, or if any of x, y, width, or height is less than zero.


forceUpdate (Direct3dRMViewport Class)

 Microsoft SDK for Java

forceUpdate

This method of the Direct3dRMViewport Class forces an area of the viewport to be updated. The specified area will be copied to the screen at the next call to the update method.

Syntax

public void forceUpdate(int x1, int y1, int x2, int y2);

Parameters

x1 | The updated area's upper-left x-coordinate.
y1 | The updated area's upper-left y-coordinate.
x2 | The updated area's lower-right y-coordinate.
y2 | The updated area's lower-right y-coordinate.

Remarks

The system might update any region that is larger than the specified rectangle, including (possibly) the entire window.


getBack (Direct3dRMViewport Class)

 Microsoft SDK for Java

getBack

This method of the Direct3dRMViewport Class retrieves the position of the viewport back clipping plane.

Syntax

public float getBack();

Return Value

Returns a value describing the position of the plane.

See Also

setBack


getCamera (Direct3dRMViewport Class)

 Microsoft SDK for Java

getCamera

This method of the Direct3dRMViewport Class retrieves the camera for a viewport.

Syntax

public Direct3dRMFrame getCamera();

Return Value

Returns the Direct3dRMFrame object if successful; otherwise, returns null.

See Also

setCamera


getDevice (Direct3dRMViewport Class)

 Microsoft SDK for Java

getDevice

This method of the Direct3dRMViewport Class retrieves the device associated with a viewport.

Syntax

public Direct3dRMDevice getDevice();

Return Value

Returns the Direct3dRMDevice object if successful; otherwise, returns null.


getDirect3DViewport (Direct3dRMViewport Class)

 Microsoft SDK for Java

getDirect3DViewport

This method of the Direct3dRMViewport Class retrieves the Direct3D viewport corresponding to the current Direct3dRMViewport object.

Syntax

public Direct3dViewport getDirect3DViewport();

Return Value

Returns the Direct3dViewport object if successful; otherwise, returns null.


getField (Direct3dRMViewport Class)

 Microsoft SDK for Java

getField

This method of the Direct3dRMViewport Class retrieves the viewport's field of view.

Syntax

public float getField();

Return Value

Returns a value describing the viewport's field of view.

See Also

setField


getFront (Direct3dRMViewport Class)

 Microsoft SDK for Java

getFront

This method of the Direct3dRMViewport Class retrieves the position of the viewport's front clipping plane.

Syntax

public float getFront();

Return Value

Returns a value describing the position of the plane.

See Also

setFront


getHeight (Direct3dRMViewport Class)

 Microsoft SDK for Java

getHeight

This method of the Direct3dRMViewport Class retrieves the height (measured in pixels) of the viewport.

Syntax

public int getHeight();

Return Value

Returns the height of the viewport (in pixels).


getPlane (Direct3dRMViewport Class)

 Microsoft SDK for Java

getPlane

This method of the Direct3dRMViewport Class retrieves the dimensions of the viewport on the front clipping plane.

Syntax

public void getPlane(float[] l, float[] r, float[] b, float[] t);

Parameters

l | The array variables that receive the left dimensions of the viewport on the front clipping plane.
r | The array variables that receive the right dimensions of the viewport on the front clipping plane.
b | The array variables that receive the bottom dimensions of the viewport on the front clipping plane.
t | The array variables that receive the top dimensions of the viewport on the front clipping plane.

See Also

setPlane


getProjection (Direct3dRMViewport Class)

 Microsoft SDK for Java

getProjection

This method of the Direct3dRMViewport Class retrieves the viewport's projection type. A viewport can use either orthographic or perspective projection.

Syntax

public int getProjection();

Return Value

Returns a projection type value.

See Also

setProjection


getUniformScaling (Direct3dRMViewport Class)

 Microsoft SDK for Java

getUniformScaling

This method of the Direct3dRMViewport Class retrieves the scaling property used to scale the viewing volume into the larger dimension of the window.

Syntax

public int getUniformScaling();

Return Value

Returns true if the viewport scales uniformly; otherwise, returns false.

See Also

setUniformScaling


getWidth (Direct3dRMViewport Class)

 Microsoft SDK for Java

getWidth

This method of the Direct3dRMViewport Class retrieves the width (measured in pixels) of the viewport.

Syntax

public int getWidth();

Return Value

Returns the width of the viewport (in pixels).


getX (Direct3dRMViewport Class)

 Microsoft SDK for Java

getX

This method of the Direct3dRMViewport Class retrieves the x-offset of the start of the viewport on a device.

Syntax

public int getX();

Return Value

Returns the x-offset.


getY (Direct3dRMViewport Class)

 Microsoft SDK for Java

getY

This method of the Direct3dRMViewport Class retrieves the y-offset of the start of the viewport on a device.

Syntax

public int getY();

Return Value

Returns the y-offset.


inverseTransform (Direct3dRMViewport Class)

 Microsoft SDK for Java

inverseTransform

This method of the Direct3dRMViewport Class transforms the vector in the s parameter (measured in screen coordinates) to world coordinates and returns the result in the d parameter.

Syntax

public void inverseTransform(D3dVector d, D3dRMVector4d s);

Parameters

d | A D3dVector object that receives the result of the operation.
s | A D3dRMVector4d object that contains the source of the operation.


pick (Direct3dRMViewport Class)

 Microsoft SDK for Java

pick

This method of the Direct3dRMViewport Class finds a depth-sorted list of objects (and faces, if relevant) that includes the path taken in the hierarchy, from the root down to the frame that contained the object.

Syntax

public Direct3dRMPickedArray pick(int x, int y);

Return Value

Returns the Direct3dRMPickedArray object if successful; otherwise, returns null.

Parameters

x | The x-coordinate used for picking.
y | The y-coordinate used for picking.


render (Direct3dRMViewport Class)

 Microsoft SDK for Java

render

This method of the Direct3dRMViewport Class renders a frame hierarchy to the given viewport. Only those visuals on the given frame and any frames below it in the hierarchy are rendered.

Syntax

public void render(Direct3dRMFrame f);

Parameters

f The Direct3dRMFrame object that represents the frame hierarchy to be rendered.


setBack (Direct3dRMViewport Class)

 Microsoft SDK for Java

setBack

This method of the Direct3dRMViewport Class sets the position of the back clipping plane for a viewport.

Syntax

public void setBack(float v);

Parameters

v The new position of the back clipping plane.

See Also

getBack, setFront


setCamera (Direct3dRMViewport Class)

 Microsoft SDK for Java

setCamera

This method of the Direct3dRMViewport Class sets a camera for a viewport.

Syntax

public void setCamera(Direct3dRMFrame f);

Parameters

f The Direct3dRMFrame object that represents the camera.

Remarks

This method sets viewport position, direction, and orientation to that of the given camera frame. The view is oriented along the positive z-axis of the camera frame, with the up direction being that of the positive y-axis.

See Also

getCamera


setField (Direct3dRMViewport Class)

 Microsoft SDK for Java

setField

This method of the Direct3dRMViewport Class sets the viewport field of view.

Syntax

public void setField(float v);

Parameters

v The new field of view. If this value is less than or equal to zero, this method does not carry out an action.

Remarks

By default, the initial field of view value is 0.5.

See Also

getField


setFront (Direct3dRMViewport Class)

 Microsoft SDK for Java

setFront

This method of the Direct3dRMViewport Class sets the position of the front clipping plane for a viewport.

Syntax

public void setFront(float v);

Parameters

v The new position of the front clipping plane. If the value passed is less than or equal to zero, this method does not carry out an action.

Remarks

By default, the initial position is 1.0.

See Also

getFront


setPlane (Direct3dRMViewport Class)

 Microsoft SDK for Java

setPlane

This method of the Direct3dRMViewport Class sets the dimensions of the viewport on the front clipping plane, relative to the camera's z-axis.

Syntax

public void setPlane(float left, float right, float bottom, float top);

Parameters

left | The minimum x-coordinate of the four sides of the viewport.
right | The maximum x-coordinate of the four sides of the viewport.
bottom | The minimum y-coordinate of the four sides of the viewport.
top | The maximum y-coordinate of the four sides of the viewport.

Remarks

Unlike the setField method, which specifies a centered proportional viewport, this method enables you to specify a viewport of arbitrary proportion and position. For example, this method could be used to construct a sheared viewing frustum to implement a right- or left-eye stereo view.

See Also

getPlane, setField


setProjection (Direct3dRMViewport Class)

 Microsoft SDK for Java

setProjection

This method of the Direct3dRMViewport Class sets the viewport projection.

Syntax

public void setProjection(int val);

Parameters

val A projection type value.

See Also

getProjection


setUniformScaling (Direct3dRMViewport Class)

 Microsoft SDK for Java

setUniformScaling

This method of the Direct3dRMViewport Class sets the scaling property used to scale the viewing volume into the larger dimension of the window.

Syntax

public void setUniformScaling(int flag);

Parameters

flag The new scaling property. If this parameter is true, the same horizontal and vertical scaling factor is used to scale the viewing volume. Otherwise, different scaling factors are used to scale the viewing volume exactly into the window.

Remarks

This method is typically used with the setPlane method to support banding.

By default, the initial scaling property is true.

See Also

getUniformScaling


transform (Direct3dRMViewport Class)

 Microsoft SDK for Java

transform

This method of the Direct3dRMViewport Class transforms the vector in the s parameter (measured in world coordinates) to screen coordinates and returns the result in the d parameter.

Syntax

public void transform(D3dRMVector4d d, D3dVector s);

Parameters

d | A D3dRMVector4d object that receives the result of the transformation operation.
s | A D3dVector object that contains the source for the transformation operation.

Remarks

The result of the transformation is a four-element homogeneous vector.


Direct3dRMViewportArray Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMViewportArray Class

Applications use the methods of the Direct3dRMViewportArray Class of the com.ms.directX package to organize viewport objects.

public class Direct3dRMViewportArray implements
            IDirect3dRMViewportArray
{
  // Methods
  public Direct3dRMViewport getElement(int index);
  public int getSize();
}

The Direct3dRMViewportArray object is obtained by calling the Direct3dRM.createFrame method.


Methods (Direct3dRMViewportArray Class)

 Microsoft SDK for Java

Direct3dRMViewportArray Class Methods

The Direct3dRMViewportArray Class contains the following methods:

getElement retrieves one of the Direct3dRMViewport objects associated with the current Direct3dRMViewportArray object.
getSize retrieves the number of Direct3dRMViewport objects associated with the current Direct3dRMViewportArray object.


getElement (Direct3dRMViewportArray Class)

 Microsoft SDK for Java

getElement

This method of the Direct3dRMViewportArray Class retrieves one of the Direct3dRMViewport objects associated with the current Direct3dRMViewportArray object.

Syntax

public Direct3dRMViewport getElement(int index);

Return Value

Returns the Direct3dRMViewport object if successful; otherwise, returns null.

Parameters

index The identifier of the object to return. The index must be a value in the range of 0 to one less than the number returned by the getSize method.


getSize (Direct3dRMViewportArray Class)

 Microsoft SDK for Java

getSize

This method of the Direct3dRMViewportArray Class retrieves the number of Direct3dRMViewport objects associated with the current Direct3dRMViewportArray object.

Syntax

public int getSize();

Return Value

Returns the number of objects.


Direct3dRMVisual Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMVisual Class

Applications use the Direct3dRMVisual Class of the com.ms.directX package when creating shadows or adding visuals to a frame.

public class Direct3dRMVisual implements IDirect3dRMVisual
{
  // Methods
  public Direct3dRMMeshBuilder getd3drmMeshBuilder();
}

This class supports the getd3drmMeshBuilder method.

In addition, the Direct3dRMFrame class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName


Methods (Direct3dRMVisual Class)

 Microsoft SDK for Java

Direct3dRMVisual Class Methods

The Direct3dRMVisual Class contains the following method:

getd3drmMeshBuilder retrieves the mesh builder object associated with the current Direct3dRMVisual object.


getd3drmMeshBuilder (Direct3dRMVisual Class)

 Microsoft SDK for Java

getd3drmMeshBuilder

This method of the Direct3dRMVisual retrieves the mesh builder object associated with the current Direct3dRMVisual object.

Syntax

public Direct3dRMMeshBuilder getd3drmMeshBuilder();

Return Value

Returns the Direct3dRMMeshBuilder object if successful; otherwise, returns null.


Direct3dRMVisualArray Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMVisualArray Class

Applications use the methods of the Direct3dRMVisualArray Class of the com.ms.directX package to organize groups of visual objects.

public class Direct3dRMVisualArray implements
            IDirect3dRMVisualArray
{
  // Methods
  public Direct3dRMVisual getElement(int index);
  public int getSize();
}

The Direct3dRMVisualArray object is obtained by calling the Direct3dRMFrame.getVisuals method.


Methods (Direct3dRMVisualArray Class)

 Microsoft SDK for Java

Direct3dRMVisualArray Class Methods

The Direct3dRMVisualArray Class contains the following methods:

getElement returns one of the Direct3dRMVisual objects associated with the current Direct3dRMVisualArray object.
getSize retrieves the number of Direct3dRMVisual objects associated with the current Direct3dRMVisualArray object.


getElement (Direct3dRMVisualArray Class)

 Microsoft SDK for Java

getElement

This method of the Direct3dRMVisualArray Class returns one of the Direct3dRMVisual objects associated with the current Direct3dRMVisualArray object.

Syntax

public Direct3dRMVisual getElement(int index);

Return Value

Returns the Direct3dRMVisual object if successful; otherwise, returns null.

Parameters

index Identifies the object to return. The index must be a value in the range of 0 to one less than the number returned by the getSize method.


getSize (Direct3dRMVisualArray Class)

 Microsoft SDK for Java

getSize

This method of the Direct3dRMVisualArray Class retrieves the number of Direct3dRMVisual objects associated with the current Direct3dRMVisualArray object.

Syntax

public int getSize();

Return Value

Returns the number of objects.


Direct3dRMWinDevice Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMWinDevice Class

Applications use the methods of the Direct3dRMWinDevice Class of the com.ms.directX package to respond to window messages in a window procedure.

public class Direct3dRMWinDevice implements
            IDirect3dRMWinDevice
{
  // Methods
  public void handleActivate(int wparam);
  public void handlePaint(int hdc);
}

In addition, the Direct3dRMWinDevice class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

The Direct3dRMWinDevice object is obtained by calling the getDevices method or by calling a method such as createDeviceFromD3D.


Methods (Direct3dRMWinDevice Class)

 Microsoft SDK for Java

Direct3dRMWinDevice Class Methods

The Direct3dRMWinDevice Class contains the following methods:

handleActivate responds to a Microsoft® Windows® WM_ACTIVATE message.
handlePaint handles painting updates.


handleActivate (Direct3dRMWinDevice Class)

 Microsoft SDK for Java

handleActivate

This method of the Direct3dRMWinDevice Class responds to a Microsoft® Windows® WM_ACTIVATE message. This method ensures that the colors in the active rendering window are correct.

Syntax

public void handleActivate(int wparam);

Parameters

wparam The WPARAM parameter is passed to the message-processing procedure with the WM_ACTIVATE message.


handlePaint (Direct3dRMWinDevice Class)

 Microsoft SDK for Java

handlePaint

This method of the Direct3dRMWinDevice Class handles painting updates.

Syntax

public void handlePaint(int hdc);

Parameters

hdc The device context (DC) handle.

Remarks

This method should be called before repainting any application areas in the window because areas outside the viewports that have been created on the device can be repainted.


Direct3dRMWrap Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dRMWrap Class

Applications use the methods of the Direct3dRMWrap Class of the com.ms.directX package to work with wrap objects.

public class Direct3dRMWrap implements IDirect3dRMWrap
{
  // Methods
  public void applyFace(Direct3dRMFace face);
  public void applyMesh(Direct3dRMMesh mesh);
  public void applyMeshBuilder(Direct3dRMMeshBuilder meshbuilder);
  public void applyRelative(Direct3dRMFrame f, Direct3dRMObject o);
}

In addition, the Direct3dRMWrap class inherits the following methods from the Direct3dRMObject class:

addDestroyCallback
duplicate
deleteDestroyCallback
getAppData
getClassName
getName
setAppData
setName

Note This class does not provide an init method. Use the Direct3dRM.createWrap method to create and initialize Direct3dRMWrap objects.

Note Wrap objects wrap a two dimensional surface to a three dimensional object. If you are using DirectX3 on the native side, wrap objects might not behave as expected. If you are using DirectX5, you should not encounter problems.


Methods (Direct3dRMWrap Class)

 Microsoft SDK for Java

Direct3dRMWrap Class Methods

The Direct3dRMWrap Class contains the following methods:

applyFace applies a Direct3dRMWrap object to a destination Direct3dRMFace object.
applyMesh applies a Direct3dRMWrap object to a destination Direct3dRMMesh object.
applyMeshBuilder applies a Direct3dRMWrap object to a destination Direct3dRMMeshBuilder object.
applyRelative applies the wrap to the vertices of the object.


applyFace (Direct3dRMWrap Class)

 Microsoft SDK for Java

applyFace

This method of the Direct3dRMWrap Class applies a Direct3dRMWrap object to a destination Direct3dRMFace object.

Syntax

public void applyFace(Direct3dRMFace face);

Parameters

face The destination object.

See Also

com.ms.directX.Direct3dRM


applyMesh (Direct3dRMWrap Class)

 Microsoft SDK for Java

applyMesh

This method of the Direct3dRMWrap Class applies a Direct3dRMWrap object to a destination Direct3dRMMesh object.

Syntax

public void applyMesh(Direct3dRMMesh mesh);

Parameters

mesh The destination object.

See Also

com.ms.directX.Direct3dRM


applyMeshBuilder (Direct3dRMWrap Class)

 Microsoft SDK for Java

applyMeshBuilder

This method of the Direct3dRMWrap Class applies a Direct3dRMWrap object to a destination Direct3dRMMeshBuilder object.

Syntax

public void applyMeshBuilder(Direct3dRMMeshBuilder meshbuilder);

Parameters

meshbuilder The destination object.

See Also

com.ms.directX.Direct3dRM


applyRelative (Direct3dRMWrap Class)

 Microsoft SDK for Java

applyRelative

This method of the Direct3dRMWrap Class applies the wrap to the vertices of the object. First it transforms each vertex by the frame's world transformation. Then it transforms each vertex by the inverse world transformation of the wrap's reference frame.

Syntax

public void applyRelative(Direct3dRMFrame f, Direct3dRMObject o);

Parameters

f | The Direct3dRMFrame object containing the object to wrap.
o | The Direct3dRMWrap object to apply.

See Also

com.ms.directX.Direct3dRM


Direct3dTexture Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dTexture Class

Applications use the methods of the Direct3dTexture Class of the com.ms.directX package to retrieve and set texture properties.

public class Direct3dTexture implements IDirect3dTexture
{
  // Methods
  public void getHandle(Direct3dDevice dev);
  public void initialize(Direct3dDevice dev,
        DirectDrawSurface surf);
  public void load(Direct3dTexture tex);
  public void paletteChanged(int start, int count);
  public void unload();
}


Methods (Direct3dTexture Class)

 Microsoft SDK for Java

Direct3dTexture Class Methods

The Direct3dTexture Class contains the following methods:

getHandle obtains the texture handle for the Direct3dTexture object.
initialize initializes the Direct3dTexture object.
load loads a texture that was created with the DDSCAPS_ALLOCONLOAD flag, which indicates that memory for the DirectDraw surface is not allocated until the surface is loaded by using this method.
paletteChanged informs the driver that the palette has changed on a surface.
unload unloads the current texture.


getHandle (Direct3dTexture Class)

 Microsoft SDK for Java

getHandle

This method of the Direct3dTexture Class obtains the texture handle for the Direct3dTexture object. This handle is used in all Direct3D API calls where a texture is to be referenced.

Syntax

public void getHandle(Direct3dDevice dev);

Parameters

dev The Direct3dDevice object that the texture is to be loaded into.


initialize (Direct3dTexture Class)

 Microsoft SDK for Java

initialize

This method of the Direct3dTexture Class initializes the Direct3dTexture object.

Syntax

public void initialize(Direct3dDevice dev, DirectDrawSurface surf);

Parameters

dev | The device representing the Direct3D object.
surf | The DirectDrawSurface for this object.


load (Direct3dTexture Class)

 Microsoft SDK for Java

load

This method of the Direct3dTexture Class loads a texture that was created with the DDSCAPS_ALLOCONLOAD flag, which indicates that memory for the DirectDraw surface is not allocated until the surface is loaded by using this method.

Syntax

public void load(Direct3dTexture tex);

Parameters

tex The texture to load.

See Also

unload


paletteChanged (Direct3dTexture Class)

 Microsoft SDK for Java

paletteChanged

This method of the Direct3dTexture Class informs the driver that the palette has changed on a surface.

Syntax

public void paletteChanged(int start, int count);

Parameters

start | The index of the first palette entry that has changed.
count | The number of palette entries that have changed.

Remarks

This method is particularly useful for applications that play video clips and therefore require palette-changing capabilities.


unload (Direct3dTexture Class)

 Microsoft SDK for Java

unload

This method of the Direct3dTexture Class unloads the current texture.

Syntax

public void unload();

See Also

load


Direct3dViewport Class (com.ms.directX Package)

 Microsoft SDK for Java

Direct3dViewport Class

Applications use the methods of the Direct3dViewport Class of the com.ms.directX package to retrieve and set the properties of viewports.

public class Direct3dViewport implements IDirect3dViewport
{
  // Methods
  public void addLight(Direct3dLight light);
  public void clear(int count, D3dRect rec, int flags);
  public void deleteLight(Direct3dLight light);
  public void getBackground(int[] hdl, int[] stat);
  public DirectDrawSurface getBackgroundDepth(int[] status);
  public void getViewport(D3dViewportDesc vp);
  public Direct3dLight nextLight(Direct3dLight l1, int flags);
  public void setBackground(int hdl);
  public void setBackgroundDepth(IDirectDrawSurface surface);
  public void setViewport(D3dViewportDesc vp);

}

Note This class does not provide an initialize method. Use the Direct3d.createViewport()method to create and initialize Direct3dViewport objects.


Methods (Direct3dViewport Class)

 Microsoft SDK for Java

Direct3dViewport Class Methods

The Direct3dViewport Class contains the following methods:

addLight adds a Direct3dLight light object to the viewport.
clear clears the viewport or a set of rectangles in the viewport to the current background material.
deleteLight deletes a Direct3dLight light object from the viewport.
getBackground retrieves the handle of a material that represents the current viewport background.
getBackgroundDepth retrieves a DirectDraw surface that represents the current background-depth field associated with the viewport.
getViewport retrieves the viewport registers.
nextLight retrieves a light from a Direct3dViewport, according to the specified flags.
setBackground sets the background associated with the viewport.
setBackgroundDepth sets the viewport background depth field.
setViewport sets the viewport registers.


addLight (Direct3dViewport Class)

 Microsoft SDK for Java

addLight

This method of the Direct3dViewport Class adds a Direct3dLight light object to the viewport.

Syntax

public void addLight(Direct3dLight light);

Parameters

light The Direct3dLight object to add.


clear (Direct3dViewport Class)

 Microsoft SDK for Java

clear

This method of the Direct3dViewport Class clears the viewport or a set of rectangles in the viewport to the current background material.

Syntax

public void clear(int count, D3dRect rec, int flags);

Parameters

count | The number of rectangles pointed to by rec.
rec | A D3dRect object.
flags | One or more values of D3DCLEAR_ type, indicating what to clear: the rendering target, the z-buffer, or both.


deleteLight (Direct3dViewport Class)

 Microsoft SDK for Java

deleteLight

This method of the Direct3dViewport Class deletes a Direct3dLight light object from the viewport.

Syntax

public void deleteLight(Direct3dLight light);

Parameters

light The Direct3dLight object to delete.


getBackground (Direct3dViewport Class)

 Microsoft SDK for Java

getBackground

This method of the Direct3dViewport Class retrieves the handle of a material that represents the current viewport background.

Syntax

public void getBackground(int[] hdl, int[] stat);

Parameters

hdl | The array variable that receives the handle of the material being used as the background.
stat | The array variable that receives a value, indicating whether a background is associated with the viewport. If this value is FALSE, a background is not associated with the viewport.

See Also

setBackground


getBackgroundDepth (Direct3dViewport Class)

 Microsoft SDK for Java

getBackgroundDepth

This method of the Direct3dViewport Class retrieves a DirectDraw surface that represents the current background-depth field associated with the viewport.

Syntax

public DirectDrawSurface getBackgroundDepth(int[] status);

Return Value

Returns the DirectDrawSurface object if successful; otherwise, returns null.

Parameters

status The array variable that receives the value FALSE if a background depth is not associated with the viewport.

See Also

setBackgroundDepth


getViewport (Direct3dViewport Class)

 Microsoft SDK for Java

getViewport

This method of the Direct3dViewport Class retrieves the viewport registers.

Syntax

public void getViewport(D3dViewportDesc vp);

Parameters

vp A D3dViewportDesc object that receives values for the viewport.

See Also

setViewport


nextLight (Direct3dViewport Class)

 Microsoft SDK for Java

nextLight

This method of the Direct3dViewport Class retrieves a light from a Direct3dViewport, according to the specified flags.

Syntax

public Direct3dLight nextLight(Direct3dLight l1, int flags);

Return Value

Returns the requested Direct3dLight object.

Parameters

l1 | This can be null if the flags constant is either D3DNEXT_HEAD or D3DNEXT_TAIL.
flags | This can be one of the following values: D3DNEXT_HEAD D3DNEXT_TAIL D3DNEXT_NEXT


setBackground (Direct3dViewport Class)

 Microsoft SDK for Java

setBackground

This method of the Direct3dViewport Class sets the background associated with the viewport.

Syntax

public void setBackground(int hdl);

Parameters

hdl The material handle that will be used as the background.

See Also

getBackground


setBackgroundDepth (Direct3dViewport Class)

 Microsoft SDK for Java

setBackgroundDepth

This method of the Direct3dViewport Class sets the viewport background depth field.

Syntax

public void setBackgroundDepth(IDirectDrawSurface surface);

Parameters

surface The DirectDrawSurface object representing the background depth.

Remarks

The z-buffer is filled with the specified depth field when the clear method is called and the D3DCLEAR_ZBUFFER flag is specified. The bit depth must be 16 bits.

See Also

getBackgroundDepth


setViewport (Direct3dViewport Class)

 Microsoft SDK for Java

setViewport

This method of the Direct3dViewport Class sets the viewport registers.

Syntax

public void setViewport(D3dViewportDesc vp);

Parameters

vp A D3dViewportDesc object that contains the new viewport.

See Also

getViewport


DirectDraw Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectDraw Class

Applications use the methods of the DirectDraw Class of the com.ms.directX package to create Microsoft® DirectDraw® objects and work with system-level variables.

public class DirectDraw implements IDirectDraw
{
  // Methods
  public DirectDrawClipper createClipper(int flags);
  public Direct3d createD3D();
  public DirectDrawPalette createPalette(int flags, byte[] pe);
  public DirectDrawPalette createPalette(int flags);
  public DirectDrawPalette createPalette(int flags, Color[] pe);
  public DirectDrawPalette createPalette(int flags,
        PaletteEntry[] pe);
  public DirectDrawSurface createSurface(DDSurfaceDesc dd);
  public DirectDrawSurface duplicateSurface(DirectDrawSurface ddIn);
  public void enumDisplayModes(int d, DDSurfaceDesc s,
        IUnknown args, IEnumModesCallback fn);
  public void flipToGDISurface();
  public int getAvailableTotalMem(int[] ddsCaps);
  public void getCaps(DDCaps driverCaps, DDCapsFx driverCapsFx,
        DDCaps helCaps, DDCapsFx helCapsFx);
  public void getDisplayMode(DDSurfaceDesc surface);
  public int getFourCCCodes(int[] size);
  public int getFreeMem(int [] ddsCaps);
  public DirectDrawSurface getGDISurface();
  public int getMonitorFrequency();
  public int getNumFourCCCodes();
  public int getScanLine();
  public int getVerticalBlankStatus();
  public DirectDrawPalette loadPaletteFromBitmap(String bName);
  public void restoreDisplayMode();
  public void setCooperativeLevel(Component c, int flags);
  public void setCooperativeLevel(int hdl, int flags);
  public void setDisplayMode(int w, int h, int bpp, int ref,
        int mode);
  public int systemBpp();
  public int tickCount();
  public void waitForVerticalBlank(int flags, int handle);
}


Methods (DirectDraw Class)

 Microsoft SDK for Java

DirectDraw Class Methods

The DirectDraw Class contains the following methods:

createClipper creates a DirectDrawClipper object.
createD3D creates a Microsoft® Direct3D® object.
createPalette creates a DirectDrawPalette object for this DirectDraw object.
createSurface creates a DirectDrawSurface object for this DirectDraw object.
duplicateSurface duplicates a DirectDrawSurface object.
enumDisplayModes enumerates all the display modes the hardware exposes through the DirectDraw object that are compatible with a provided surface description.
flipToGDISurface makes the surface that GDI writes to the primary surface.
getAvailableTotalMem retrieves the total available amount of display memory.
getCaps fills in the capabilities of the device driver for the hardware and the hardware emulation layer (HEL).
getDisplayMode retrieves the current display mode.
getFourCCCodes retrieves the FourCC codes supported by the DirectDraw object. This method can also retrieve the number of codes supported.
getFreeMem retrieves the amount of display memory currently free.
getGDISurface retrieves the DirectDrawSurface object that currently represents the surface memory that the Graphical Device Interface (GDI) is treating as the primary surface.
getMonitorFrequency retrieves the frequency of the monitor being driven by the DirectDraw object.
getNumFourCCCodes retrieves the number of FourCC codes in the array getFourCCCodes specifies.
getScanLine retrieves the scan line that is currently being drawn on the monitor.
getVerticalBlankStatus retrieves the status of the vertical blank.
loadPaletteFromBitmap loads a palette.
restoreDisplayMode resets the mode of the display device hardware for the primary surface to what it was before the setDisplayMode method was called.
setCooperativeLevel determines the top-level behavior of the application (the primary method that does so).
setDisplayMode sets the mode of the display-device hardware.
systemBpp retrieves the current system's bits-per-pixel value.
tickCount retrieves the current tick count.
waitForVerticalBlank assists the application to synchronize itself with the vertical-blank interval.


createClipper (DirectDraw Class)

 Microsoft SDK for Java

createClipper

This method of the DirectDraw Class creates a DirectDrawClipper object.

Syntax

public DirectDrawClipper createClipper(int flags);

Return Value

Returns the DirectDrawClipper object if successful; otherwise, returns null.

Parameters

flags This parameter is currently not used and must be set to 0.

Remarks

The DirectDrawClipper object can be attached to a DirectDrawSurface and used during blt and updateOverlay operations.

See Also

com.ms.directX.DirectDrawSurface


createD3D (DirectDraw Class)

 Microsoft SDK for Java

createD3D

This method of the DirectDraw Class creates a Direct3D object.

Syntax

public Direct3d createD3D();

Return Value

Returns the Direct3d object if successful; otherwise, returns null.


createPalette (DirectDraw Class)

 Microsoft SDK for Java

createPalette

The createPalette method of the DirectDraw Class contains the following signatures:

createPalette(int flags, byte[] pe)
createPalette(int flags)
createPalette(int flags, Color[] pe)
createPalette(int flags, PaletteEntry[] pe)

createPalette(int flags, byte[] pe)

Creates a DirectDrawPalette object for this DirectDraw object.

Syntax

public DirectDrawPalette createPalette(int flags, byte[] pe);

Return Value

Returns the DirectDrawPalette object if successful; otherwise, returns null.

Parameters

flags | One or more values of the DDPCAPS_ type.
pe | The array variable that contains the data describing the initial value for each palette entry.

createPalette(int flags)

Creates a palette and fills it with standard halftone entries.

Syntax

public DirectDrawPalette createPalette(int flags);

Return Value

Returns the DirectDrawPalette object if successful; otherwise, returns null. Currently, only DDPCAPS_8BIT and DDPCAPS_INITIALIZE are valid arguments for the flags parameter.

Parameters

flags One or more values of DDPCAPS_ type.

createPalette(int flags, Color[] pe)

Creates a DirectDrawPalette object for this DirectDraw object.

Syntax

public DirectDrawPalette createPalette(int flags, Color[] pe);

Return Value

Returns the DirectDrawPalette object if successful; otherwise, returns null.

Parameters

flags | One or more values of the DDPCAPS_ type.
pe | The array variable that contains the data describing the initial color value for each palette entry.

createPalette(int flags, PaletteEntry[] pe)

Creates a DirectDrawPalette object for this DirectDraw object.

Syntax

public DirectDrawPalette createPalette(int flags, PaletteEntry[] pe);

Return Value

Returns the DirectDrawPalette object if successful; otherwise, returns null.

Parameters

flags | One or more values of DDPCAPS_ type.
pe | The array variable that contains a PaletteEntry object describing each palette entry.


createSurface (DirectDraw Class)

 Microsoft SDK for Java

createSurface

This method of the DirectDraw Class creates a DirectDrawSurface object for this DirectDraw object.

Syntax

public DirectDrawSurface createSurface(DDSurfaceDesc dd);

Return Value

Returns the DirectDrawSurface object if successful; otherwise, returns null.

Parameters

dd The DDSurfaceDesc object that describes the requested surface.


duplicateSurface (DirectDraw Class)

 Microsoft SDK for Java

duplicateSurface

This method of the DirectDraw Class duplicates a DirectDrawSurface object.

Syntax

public DirectDrawSurface duplicateSurface(DirectDrawSurface ddIn);

Return Value

Returns the DirectDrawSurface object if successful; otherwise, returns null.

Parameters

ddIn The DirectDrawSurface object to be duplicated.

Remarks

This method creates a new DirectDrawSurface object that represents the same surface memory as an existing DirectDrawSurface object. This duplicate can be used just like the original object. The surface memory is released after the last object referencing it is released. A primary surface, 3D surface, or implicitly created surface cannot be duplicated.


enumDisplayModes (DirectDraw Class)

 Microsoft SDK for Java

enumDisplayModes

This method of the DirectDraw Class enumerates all the display modes the hardware exposes through the DirectDraw object that are compatible with a provided surface description. If null is passed for the surface description, all exposed modes are enumerated.

Syntax

public void enumDisplayModes(int d, DDSurfaceDesc s, IUnknown args, IEnumModesCallback fn);

Parameters

d | This flag Can be DDEDM_REFRESHRATES.
s | A DDSurfaceDesc object that will be checked against available modes. If the value of this parameter is null, all modes are enumerated.
args | Application-defined data that will be passed to each enumeration member.
fn | The callback interface containing the callback function that the enumeration procedure will call every time a match is found.

Remarks

This method enumerates the backBufferCount field of the DDSurfaceDesc class. If you use the setDisplayMode method to set the refresh rate of a new mode, you must use enumDisplayModes to enumerate the backBufferCount field.

See Also

getDisplayMode, setDisplayMode, restoreDisplayMode


flipToGDISurface (DirectDraw Class)

 Microsoft SDK for Java

flipToGDISurface

This method of the DirectDraw Class makes the surface that GDI writes to the primary surface.

Syntax

public void flipToGDISurface();

Remarks

This method can be called at the end of a page-flipping application to ensure that the display memory that the GDI is writing to is visible to the user.

See Also

getGDISurface


getAvailableTotalMem (DirectDraw Class)

 Microsoft SDK for Java

getAvailableTotalMem

This method of the DirectDraw Class retrieves the total available amount of display memory.

Syntax

public int getAvailableTotalMem(int[] ddsCaps);

Return Value

Returns the amount of memory.

Parameters

ddsCaps An array of the values found in the DDSCaps class.

Remarks

A display adapter card can make no distinction between two different memory types.

For example, the adapter might use the same portion of display memory to store z-buffers and textures. So, allocating one type of surface (for example, a z-buffer) can affect the amount of display memory available for another type of surface (for example, textures). Therefore, it is best to first allocate an application's fixed resources (such as front, back, and z-buffers) before determining how much memory is available for dynamic use, such as texture mapping.


getCaps (DirectDraw Class)

 Microsoft SDK for Java

getCaps

This method of the DirectDraw Class fills in the capabilities of the device driver for the hardware and the hardware emulation layer (HEL).

Syntax

public void getCaps(DDCaps driverCaps, DDCapsFx driverCapsFx, DDCaps helCaps, DDCapsFx helCapsFx);

Parameters

driverCaps | A DDCaps object that receives the capabilities of the hardware, as reported by the device driver.
driverCapsFx | A DDCapsFx object that receives the capabilities of the hardware, as reported by the device driver. The DDCapsFx class is used with classes that contain more than 256 bytes of member data.
helCaps | A DDCaps object that receives the capabilities of the HEL.
helCapsFx | A DDCapsFx object that receives the capabilities of the HEL. The DDCapsFx class is used with classes that contain more than 256 bytes of member data.


getDisplayMode (DirectDraw Class)

 Microsoft SDK for Java

getDisplayMode

This method of the DirectDraw Class retrieves the current display mode.

Syntax

public void getDisplayMode(DDSurfaceDesc surface);

Parameters

surface A DDSurfaceDesc object that receives a description of the surface.

Remarks

An application should not save the information returned by this method to restore the display mode on clean-up. The application should use the restoreDisplayMode method to restore the mode on clean-up, which avoids mode-setting conflicts that could arise in a multiprocess environment.

See Also

setDisplayMode, restoreDisplayMode, enumDisplayModes


getFourCCCodes (DirectDraw Class)

 Microsoft SDK for Java

getFourCCCodes

This method of the DirectDraw Class retrieves the FourCC codes supported by the DirectDraw object. This method can also retrieve the number of codes supported.

Syntax

public int getFourCCCodes(int[] size);

Return Value

Returns an address of an array that contains the codes.

Parameters

size The array variable that receives the FourCC codes supported by this DirectDraw object.


getFreeMem (DirectDraw Class)

 Microsoft SDK for Java

getFreeMem

This method of the DirectDraw Class retrieves the amount of display memory currently free.

Syntax

public int getFreeMem(int [] ddsCaps);

Return Value

Returns the amount of free display memory.

Parameters

ddsCaps An array of the values found in the DDSCaps class.

Remarks

This method provides only a snapshot of the current display-memory state. The amount of free display memory is subject to change as surfaces are created and released. Therefore, you should use the free memory value only as an approximation.


getGDISurface (DirectDraw Class)

 Microsoft SDK for Java

getGDISurface

This method of the DirectDraw Class retrieves the DirectDrawSurface object that currently represents the surface memory that the Graphical Device Interface (GDI) is treating as the primary surface.

Syntax

public DirectDrawSurface getGDISurface();

Return Value

Returns the DirectDrawSurface object if successful; otherwise, returns null.

See Also

flipToGDISurface


getMonitorFrequency (DirectDraw Class)

 Microsoft SDK for Java

getMonitorFrequency

This method of the DirectDraw Class retrieves the frequency of the monitor being driven by the DirectDraw object. The frequency value is returned in Hz multiplied by 100. For example, 60Hz is returned as 6000.

Syntax

public int getMonitorFrequency();

Return Value

Returns the monitor frequency.


getNumFourCCCodes (DirectDraw Class)

 Microsoft SDK for Java

getNumFourCCCodes

This method of the DirectDraw Class retrieves the number of FourCC codes in the array getFourCCCodes specifies.

Syntax

public int getNumFourCCCodes();

Return Value

Returns the number of FourCCCodes.


getScanLine (DirectDraw Class)

 Microsoft SDK for Java

getScanLine

This method of the DirectDraw Class retrieves the scan line that is currently being drawn on the monitor.

Syntax

public int getScanLine();

Return Value

Returns the scan line.

See Also

getVerticalBlankStatus, waitForVerticalBlank


getVerticalBlankStatus (DirectDraw Class)

 Microsoft SDK for Java

getVerticalBlankStatus

This method of the DirectDraw Class retrieves the status of the vertical blank.

Syntax

public int getVerticalBlankStatus();

Return Value

Returns 1 if a vertical blank is occurring; otherwise, returns 0.

Remarks

To synchronize with the vertical blank, use the waitForVerticalBlank method.

See Also

getScanLine, waitForVerticalBlank


loadPaletteFromBitmap (DirectDraw Class)

 Microsoft SDK for Java

loadPaletteFromBitmap

This method of the DirectDraw Class loads a palette.

Syntax

public DirectDrawPalette loadPaletteFromBitmap(String bName);

Return Value

Returns the DirectDrawPalette object if successful; otherwise, returns null.

Parameters

bName Name of the bitmap that contains the palette to load.


restoreDisplayMode (DirectDraw Class)

 Microsoft SDK for Java

restoreDisplayMode

This method of the DirectDraw Class resets the mode of the display device hardware for the primary surface to what it was before the setDisplayMode method was called. Exclusive-level access is required to use this method.

Syntax

public void restoreDisplayMode();

See Also

setDisplayMode, enumDisplayModes, setCooperativeLevel


setCooperativeLevel (DirectDraw Class)

 Microsoft SDK for Java

setCooperativeLevel

The setCooperativeLevel method of the DirectDraw Class contains the following signatures:

setCooperativeLevel(Component c, int flags)
setCooperativeLevel(int hdl, int flags)

setCooperativeLevel(Component c, int flags)

Determines the top-level behavior of the application (the primary method that does so).

Syntax

public void setCooperativeLevel(Component c, int flags);

Parameters

c | The Component used for the application.
flags | One or more values of DDSCL_ type.

Remarks

You must call the show() or addNotify() method before calling setCooperativeLevel.

See Also

setDisplayMode, compact, enumDisplayModes

setCooperativeLevel(int hdl, int flags)

Serves as a helper for the setCooperativeLevel(Component, int) method and remains for use by more advanced programmers. The setCooperativeLevel method also determines the top-level behavior of the application.

Syntax

public void setCooperativeLevel(int hdl, int flags);

Parameters

hdl | The Microsoft® Windows® handle used for the application. Applications can use DirectDraw with multiple windows. Therefore, setCooperativeLevel does not require a window handle to be specified if the application is requesting the DDSCL_NORMAL mode. By passing a null to the window handle, all the windows can be used simultaneously in normal Windows mode.
flags | One or more values of the DDSCL_ type.

See Also

setDisplayMode, compact, enumDisplayModes


setDisplayMode (DirectDraw Class)

 Microsoft SDK for Java

setDisplayMode

This method of the DirectDraw Class sets the mode of the display-device hardware.

Syntax

public void setDisplayMode(int w, int h, int bpp, int ref, int mode);

Parameters

w | The width of the new mode.
h | The height of the new mode.
bpp | The bits per pixel of the new mode.
ref | The refresh rate of the new mode.
mode | Reserved; value must be 0.

Remarks

The setCooperativeLevel method must be used to set exclusive-level access before the mode can be changed. If other applications have created a DirectDrawSurface object on the primary surface and the mode is changed, those applications' primary surface objects return DDERR_SURFACELOST until they are restored.

See Also

restoreDisplayMode, getDisplayMode, enumDisplayModes, setCooperativeLevel


systemBpp (DirectDraw Class)

 Microsoft SDK for Java

systemBpp

This method of the DirectDraw Class retrieves the current system's bits-per-pixel value.

Syntax

public int systemBpp();

Return Value

Returns the bits-per-pixel value.


tickCount (DirectDraw Class)

 Microsoft SDK for Java

tickCount

This method of the DirectDraw Class retrieves the current tick count.

Syntax

public int tickCount();

Return Value

Returns the tick count.


waitForVerticalBlank (DirectDraw Class)

 Microsoft SDK for Java

waitForVerticalBlank

This method of the DirectDraw Class assists the application to synchronize itself with the vertical-blank interval.

Syntax

public void waitForVerticalBlank(int flags, int handle);

arameters

flags | One value of DDWAITVB_ type; flag specifies how long to wait for the vertical blank.
handle | The handle of the event to be triggered when the vertical blank begins.

See Also

getVerticalBlankStatus, getScanLine


DirectDrawBitmap Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectDrawBitmap Class

Applications use the DirectDrawBitmap Class of the com.ms.directX package to create and manage bitmaps.

public class DirectDrawBitmap implements IDirectDrawBitmap
{
  // Methods
  public void filename(String val);
  public int height();
  public void initHeight(int val);
  public void initWidth(int val);
  public int loaded();
  public int width();
}


Methods (DirectDrawBitmap Class)

 Microsoft SDK for Java

DirectDrawBitmap Class Methods

The DirectDrawBitmap Class contains the following methods:

filename sets the name of the file containing the bitmap data.
height retrieves the actual height of the bitmap.
initHeight sets the initial height of the bitmap.
initWidth initializes the width of the bitmap.
loaded indicates whether the bitmap data has been loaded.
width retrieves the actual width of the bitmap.


filename (DirectDrawBitmap Class)

 Microsoft SDK for Java

filename

This method of the DirectDrawBitmap Class sets the name of the file containing the bitmap data.

Syntax

public void filename(String val);

Parameters

val The name of the bitmap file.


height (DirectDrawBitmap Class)

 Microsoft SDK for Java

height

This method of the DirectDrawBitmap Class retrieves the actual height of the bitmap.

Syntax

public int height();

Return Value

Returns the height, in pixels.


initHeight (DirectDrawBitmap Class)

 Microsoft SDK for Java

initHeight

This method of the DirectDrawBitmap Class sets the initial height of the bitmap.

Syntax

public void initHeight(int val);

Parameters

val The initial height, in pixels.


initWidth (DirectDrawBitmap Class)

 Microsoft SDK for Java

initWidth

This method of the DirectDrawBitmap Class initializes the width of the bitmap.

Syntax

public void initWidth(int val);

Parameters

val The initial width, in pixels.


loaded (DirectDrawBitmap Class)

 Microsoft SDK for Java

loaded

This method of the DirectDrawBitmap Class indicates whether the bitmap data has been loaded.

Syntax

public int loaded();

Return Value

Returns 1 if loaded, 0 otherwise.


width (DirectDrawBitmap Class)

 Microsoft SDK for Java

width

This method of the DirectDrawBitmap Class retrieves the actual width of the bitmap.

Syntax

public int width();

Return Value

Returns the width in pixels.


DirectDrawClipper Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectDrawClipper Class

Applications use the methods of the DirectDrawClipper Class of the com.ms.directX package to manage clip lists.

public class DirectDrawClipper implements IDirectDrawClipper
{
  // Methods
  public void getClipList(Rect rec, int [] rects, int count,
        Rect boundingrect);
  public int getClipListSize(Rect rec);
  public int getHWnd();
  public void initialize(DirectDraw dd, int flags);
  public int isClipListChanged();
  public void setClipList(Rect rec, int [] rects, int count);
  public void setComponent(Component c);
  public void setHWnd(int flags, int hdl);
  public void setOffset(int x, int y);
  public void setSurfaceOffset(Point point);
  public void setSurfaceVisRgn(Region visRgn);
}


Methods (DirectDrawClipper Class)

 Microsoft SDK for Java

DirectDrawClipper Class Methods

The DirectDrawClipper Class contains the following methods:

getClipList retrieves a copy of the clip list associated with a DirectDrawClipper object.
getClipListSize retrieves the size of the portion of the clip list contained with the given rectangle.
getHWnd retrieves the window handle previously associated with this DirectDrawClipper object by the setHWnd method.
initialize initializes a DirectDrawClipper object.
isClipListChanged monitors the status of the clip list if a window handle is associated with a DirectDrawClipper object.
setClipList sets or deletes the clip list used by the blt and updateOverlay methods on surfaces that the parent DirectDrawClipper object is attached to.
setComponent associates the surface object with a top-level Java component.
setHWnd sets the window handle that will obtain the clipping information.
setOffset calls to native code to translate a surface to new coordinates.
setSurfaceOffset translates a surface to new coordinates.
setSurfaceVisRgn sets a visible region for the surface.


getClipList (DirectDrawClipper Class)

 Microsoft SDK for Java

getClipList

This method of the DirectDrawClipper Class retrieves a copy of the clip list associated with a DirectDrawClipper object. A subset of the clip list can be selected by passing a rectangle that clips the clip list.

Syntax

public void getClipList(Rect rec, int [] rects, int count, Rect boundingrect);

Parameters

rec | A Rect object that is used to clip the clip list.
rects | An int array containing a list of rectangle dimensions.
count | The number of rectangles in the array.
boundingrect | The bounding rectangle.

See Also

setClipList


getClipListSize (DirectDrawClipper Class)

 Microsoft SDK for Java

getClipListSize

This method of the DirectDrawClipper Class retrieves the size of the portion of the clip list contained with the given rectangle.

Syntax

public int getClipListSize(Rect rec);

Return Value

Returns the clip list size.

Parameters

rec A Rect object that is used to clip the clip list.


getHWnd (DirectDrawClipper Class)

 Microsoft SDK for Java

getHWnd

This method of the DirectDrawClipper Class retrieves the window handle previously associated with this DirectDrawClipper object by the setHWnd method.

Syntax

public int getHWnd();

Return Value

Returns The window handle.

See Also

setHWnd


initialize (DirectDrawClipper Class)

 Microsoft SDK for Java

initialize

This method of the DirectDrawClipper Class initializes a DirectDrawClipper object.

Syntax

public void initialize(DirectDraw dd, int flags);

Parameters

dd | The DirectDraw object. If this parameter is set to null, an independent DirectDrawClipper object is created.
flags | Reserved; the value must be 0.

See Also

com.ms.directX.DirectDraw


isClipListChanged (DirectDrawClipper Class)

 Microsoft SDK for Java

isClipListChanged

This method of the DirectDrawClipper Class monitors the status of the clip list if a window handle is associated with a DirectDrawClipper object.

Syntax

public int isClipListChanged();

Return Value

Returns true if the clip list has changed.


setClipList (DirectDrawClipper Class)

 Microsoft SDK for Java

setClipList

This method of the DirectDrawClipper Class sets or deletes the clip list used by the blt and updateOverlay methods on surfaces that the parent DirectDrawClipper object is attached to.

Syntax

public void setClipList(Rect rec, int [] rects, int count);

Parameters

rec | A Rect object that is used to clip the clip list.
rects | An int array containing a list of rectangle dimensions.
count | The number of rectangles in the list.

Remarks

The clip list cannot be set if a window handle is already associated with the DirectDrawClipper object. Note that the bltFast method cannot clip.

See Also

getClipList


setComponent (DirectDrawClipper Class)

 Microsoft SDK for Java

setComponent

This method of the DirectDrawClipper Class associates the surface object with a top-level Java component.

Syntax

public void setComponent(Component c);

Parameters

c The component to link the DirectDrawClipper object to.


setHWnd (DirectDrawClipper Class)

 Microsoft SDK for Java

setHWnd

This method of the DirectDrawClipper Class sets the window handle that will obtain the clipping information.

Syntax

public void setHWnd(int flags, int hdl);

Parameters

flags | Reserved; the value must be 0.
hdl | The window handle that obtains the clipping information.

See Also

getHWnd


setOffset (DirectDrawClipper Class)

 Microsoft SDK for Java

setOffset

This method of the DirectDrawClipper Class calls to native code to translate a surface to new coordinates.

Syntax

public void setOffset(int x, int y);

Parameters

x | The new x-coordinate to offset the surface to.
y | The new y-coordinate to offset the surface to.


setSurfaceOffset (DirectDrawClipper Class)

 Microsoft SDK for Java

setSurfaceOffset

This method of the DirectDrawClipper Class translates a surface to new coordinates.

Syntax

public void setSurfaceOffset(Point point);

Parameters

point The new point to offset the surface to.


setSurfaceVisRgn (DirectDrawClipper Class)

 Microsoft SDK for Java

setSurfaceVisRgn

This method of the DirectDrawClipper Class sets a visible region for the surface.

Syntax

public void setSurfaceVisRgn(Region visRgn);

Parameters

visRgn The region to set for the surface.


DirectDrawPalette Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectDrawPalette Class

Applications use the methods of the DirectDrawPalette Class of the com.ms.directX package to create Microsoft® DirectDraw® palette objects and work with system-level variables.

public class DirectDrawPalette implements IDirectDrawPalette
{
  // Methods
  public int getCaps();
  public Color[] getColorEntries(int flags, int start, int count);
  public void getEntries(int flags, int start, int count,
        byte[] val);
  public PaletteEntry[] getPaletteEntries(int flags, int start, int
        count);
  public void setEntries(int flags, int start, int count,
        byte[] val);
  public void setEntries(int flags, int start, int count,
        Color c[]);
  public void setEntries(int flags, int start, int count,
        PaletteEntry pe[]);
  public void setEntriesHalftone(int start, int count);
  public void setEntriesSystemPalette(int start, int count);
}

Note This class does not provide an initialize method. Use the DirectDraw.createPalette method to create and initialize DirectDrawPalette objects.


Methods (DirectDrawPalette Class)

 Microsoft SDK for Java

DirectDrawPalette Class Methods

The DirectDrawPalette Class contains the following methods:

getCaps retrieves the capabilities of this palette object.
getColorEntries queries palette values from a DirectDrawPalette object and returns the color values associated with each entry.
getEntries queries palette values from a DirectDrawPalette object.
getPaletteEntries queries palette values from a DirectDrawPalette object and returns a PaletteEntry object that represents each entry.
setEntries immediately changes entries in a DirectDrawPalette object.
setEntriesHalftone fills the palette in with standard halftone entries.
setEntriesSystemPalette fills the entries in the palette with the values in the current system palette.


getCaps (DirectDrawPalette Class)

 Microsoft SDK for Java

getCaps

This method of the DirectDrawPalette Class retrieves the capabilities of this palette object.

Syntax

public int getCaps();

Return Value

Returns one value of the DDPCAPS_ type.


getColorEntries (DirectDrawPalette Class)

 Microsoft SDK for Java

getColorEntries

This method of the DirectDrawPalette Class queries palette values from a DirectDrawPalette object and returns the color values associated with each entry.

Syntax

public Color[] getColorEntries(int flags, int start, int count);

Return Value

Returns an array that contains the color values for the requested entries.

Parameters

flags | Reserved; the value must be 0.
start | The beginning of the entries that should be sequentially retrieved.
count | The number of palette entries to retrieve. The colors of each palette entry are returned in sequence, from the value of the start parameter through the value of the count parameter minus 1.

See Also

getEntries, getPaletteEntries


getEntries (DirectDrawPalette Class)

 Microsoft SDK for Java

getEntries

This method of the DirectDrawPalette Class queries palette values from a DirectDrawPalette object.

Syntax

public void getEntries(int flags, int start, int count, byte[] val);

Parameters

flags | Reserved; the value must be 0.
start | The beginning of the entries that should be sequentially retrieved.
count | Number of palette entries that can fit in the object-specified val. The colors of each palette entry are returned in sequence, from the value of the start parameter through the value of the count parameter minus 1.
val | The array variable that receives the palette entries. The palette entries are 1 byte each if the DDPCAPS_8BITENTRIES flag is set; otherwise, entries are 4 bytes each. Each entry is a color description.

See Also

setEntries


getPaletteEntries (DirectDrawPalette Class)

 Microsoft SDK for Java

getPaletteEntries

This method of the DirectDrawPalette Class queries palette values from a DirectDrawPalette object and returns a PaletteEntry object that represents each entry.

Syntax

public PaletteEntry[] getPaletteEntries(int flags, int start, int count);

Return Value

Returns an array of objects that contain the requested entries.

Parameters

flags | Reserved; the value must be 0.
start | The beginning of the entries that should be sequentially retrieved.
count | The number of palette entries to retrieve. Each palette entry is returned in sequence, from the value of the start parameter through the value of the count parameter minus 1.

See Also

getColorEntries, getEntries


setEntries (DirectDrawPalette Class)

 Microsoft SDK for Java

setEntries

The setEntries method of the DirectDrawPalette Class contains the following signatures:

setEntries(int flags, int start, int count, byte[] val)
setEntries(int flags, int start, int count, Color c[])
setEntries(int flags, int start, int count, PaletteEntry pe[])

setEntries(int flags, int start, int count, byte[] val)

Immediately changes entries in a DirectDrawPalette object. The palette must have been attached to a surface by using the setPalette method before setEntries can be used.

Syntax

public void setEntries(int flags, int start, int count, byte[] val);

Parameters

flags | Reserved; the value must be 0.
start | The first entry to be set.
count | The number of palette entries to be changed.
val | The array variable that contains the palette entries. The palette entries are 1 byte each if the DDPCAPS_8BITENTRIES flag is set; otherwise, entries are 4 bytes each. Each entry is a color description.

See Also

getEntries, com.ms.directX.DirectDrawSurface

setEntries(int flags, int start, int count, Color c[])

Immediately changes entries in a DirectDrawPalette object. The palette must have been attached to a surface by using the setPalette method before setEntries can be used.

Syntax

public void setEntries(int flags, int start, int count, Color c[]);

Parameters

flags | Reserved; the value must be 0.
start | The first entry to be set.
count | The number of palette entries to be changed.
c | The array variable that contains the new color values for each entry.

See Also

getEntries, com.ms.directX.DirectDrawSurface

setEntries(int flags, int start, int count, PaletteEntry pe[])

Immediately changes entries in a DirectDrawPalette object. The palette must have been attached to a surface by using the setPalette method before setEntries can be used.

Syntax

public void setEntries(int flags, int start, int count, PaletteEntry pe[]);

Parameters

flags | Reserved; the value must be 0.
start | The first entry to be set.
count | The number of palette entries to be changed.
pe | The array variable that contains the PaletteEntry objects that define the new values for each entry.

See Also

getEntries, com.ms.directX.DirectDrawSurface


setEntriesHalftone (DirectDrawPalette Class)

 Microsoft SDK for Java

setEntriesHalftone

This method of the DirectDrawPalette Class fills the palette in with standard halftone entries.

Syntax

public void setEntriesHalftone(int start, int count);

Parameters

start | The starting position in the palette to place the values.
count | The number of entries to add to the palette.


setEntriesSystemPalette (DirectDrawPalette Class)

 Microsoft SDK for Java

setEntriesSystemPalette

This method of the DirectDrawPalette Class fills the entries in the palette with the values in the current system palette.

Syntax

public void setEntriesSystemPalette(int start, int count);

Parameters

start | The starting position in the palette to place the values.
count | The number of entries to add to the palette.


DirectDrawSurface Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectDrawSurface Class

Applications use the methods of the DirectDrawSurface Class of the com.ms.directX package to create Microsoft® DirectDraw® surface objects and work with system-level variables.

public class DirectDrawSurface implements IDirectDrawSurface
{
  // Methods
  public void addAttachedSurface(DirectDrawSurface ddS);
  public void addOverlayDirtyRect(Rect r);
  public int blt(Rect dest, DirectDrawSurface ddS, Rect src,
        int flags);
  public int bltColorFill(Rect dest, int fillValue);
  public int bltFast(int dx, int dy, DirectDrawSurface ddS,
        Rect src, int trans);
  public int bltFx(Rect dest, DirectDrawSurface ddS, Rect src,
        int flags, DDBltFx bltFx);
  public void copyBitmap(DirectDrawBitmap val, int cx, int cy,
        int dx, int dy);
  public Direct3dDevice create3DDevice(_Guid g);
  public void deleteAttachedSurface(int flags,
        DirectDrawSurface ddS);
  public void enumAttachedSurfaces(IUnknown args,
        IEnumSurfacesCallback fn);
  public void enumOverlayZOrders(int flags, IUnknown args,
        IEnumZOrdersCallback fn);
  public void flip(DirectDrawSurface ddS, int flags);
  public DirectDrawSurface getAttachedSurface(int caps);
  public int getBltStatus(int flags);
  public int getCaps();
  public DirectDrawClipper getClipper();
  public void getColorKey(int flags, DDColorKey val);
  public int getDC();
  public IUnknown getDDInterface();
  public int getFlipStatus(int flags);
  public int getOverlayPositionX();
  public int getOverlayPositionY();
  public DirectDrawPalette getPalette();
  public void getPixelFormat(DDPixelFormat pf);
  public void getSurfaceDesc(DDSurfaceDesc surface);
  public int isLost();
  public void lock(Rect r, DDSurfaceDesc d, int flags, int hnd,
        byte[] memory);
  public void releaseDC(int hdc);
  public int restore();
  public void setClipper(DirectDrawClipper val);
  public void setColorKey(int flags, DDColorKey val);
  public void setOverlayPosition(int x, int y);
  public void setPalette(DirectDrawPalette ddp);
  public void unlock(Rect r, DDSurfaceDesc d, byte[] memory);
  public void updateOverlay(Rect r, DirectDrawSurface ddS, Rect d,
        int flags);
  public void updateOverlayDisplay(int flags);
  public void updateOverlayZOrder(int flags, DirectDrawSurface ddS);
}

Note This class does not provide an initialize method. Use the DirectDraw.createSurface method to create and initialize DirectDrawSurface objects.


Methods (DirectDrawSurface Class)

 Microsoft SDK for Java

DirectDrawSurface Class Methods

The DirectDrawSurface Class contains the following methods:

addAttachedSurface attaches a surface to another surface.
addOverlayDirtyRect builds the list of the rectangles that need to be updated the next time the updateOverlayDisplay method is called.
blt performs a bit block transfer.
bltColorFill fills the given rectangle on the surface with the given fill value.
bltFast performs a source copy blit or transparent blit by using a source color key or destination color key.
bltFx is capable of synchronous or asynchronous blits.
copyBitmap copies a bitmap.
create3DDevice creates a device from the surface if you want a rendering surface.
deleteAttachedSurface detaches two attached surfaces.
enumAttachedSurfaces enumerates all the surfaces attached to a given surface.
enumOverlayZOrders enumerates the overlay surfaces on the specified destination.
flip makes the surface memory associated with the DDSCAPS_BACKBUFFER surface become associated with the front-buffer surface.
getAttachedSurface obtains the attached surface that has the specified capabilities.
getBltStatus obtains the blitter status.
getCaps retrieves the capabilities of the surface.
getClipper retrieves the DirectDrawClipper object associated with this surface.
getColorKey retrieves the color key value for the DirectDrawSurface object.
getDC creates a Graphical Device Interface-compatible handle of a device context for the surface.
getDDInterface retrieves an interface to the DirectDraw object that was used to create the surface.
getFlipStatus indicates whether the surface has finished its flipping process.
getOverlayPositionX given a visible, active overlay surface (DDSCAPS_OVERLAY flag set), this method returns the x-display-coordinate of the surface.
getOverlayPositionY given a visible, active overlay surface (DDSCAPS_OVERLAY flag set), this method returns the y-display-coordinate of the surface.
getPalette retrieves the DirectDrawPalette structure associated with this surface.
getPixelFormat retrieves the color and pixel format of the surface.
getSurfaceDesc retrieves a description of the surface in its current condition.
isLost determines if the surface memory associated with a DirectDrawSurface object has been freed.
lock obtains the contents of the surface memory.
releaseDC releases the handle of a device context previously obtained by using the getDC method.
restore restores a surface that has been lost.
setClipper attaches a DirectDrawClipper object to a DirectDrawSurface object.
setColorKey Sets the color key value for the DirectDrawSurface object if the hardware supports color keys on a per surface basis.
setOverlayPosition changes the display coordinates of an overlay surface.
setPalette attaches the specified DirectDrawPalette object to a surface.
unlock notifies DirectDraw that the direct surface manipulations are complete and copies the contents of the memory buffer into the surface.
updateOverlay repositions or modifies the visual attributes of an overlay surface.
updateOverlayDisplay repaints the rectangles in the dirty rectangle list of all active overlays.
updateOverlayZOrder sets the z-order of an overlay.


addAttachedSurface (DirectDrawSurface Class)

 Microsoft SDK for Java

addAttachedSurface

This method of the DirectDrawSurface Class attaches a surface to another surface.

Syntax

public void addAttachedSurface(DirectDrawSurface ddS);

Parameters

ddS The DirectDrawSurface object to attach.

See Also

deleteAttachedSurface, enumAttachedSurfaces, flip


addOverlayDirtyRect (DirectDrawSurface Class)

 Microsoft SDK for Java

addOverlayDirtyRect

This method of the DirectDrawSurface Class builds the list of the rectangles that need to be updated the next time the updateOverlayDisplay method is called.

Syntax

public void addOverlayDirtyRect(Rect r);

Parameters

r The Rect object that needs to be updated.

Remarks

This method is used for the software implementation. It is not needed if the overlay support is provided by the hardware.

See Also

updateOverlayDisplay


blt (DirectDrawSurface Class)

 Microsoft SDK for Java

blt

This method of the DirectDrawSurface Class performs a bit block transfer.

Syntax

public int blt(Rect dest, DirectDrawSurface ddS, Rect src, int flags);

Return Value

Returns S_OK or 0 if the blit was set successfully; otherwise, returns an HRESULT error code. Use the DDBLT_WAIT flag to modify the return behavior as previously discussed.

Parameters

dest | A Rect object that defines the upper-left and lower-right points of the rectangle on the destination surface to be blitted to.
ddS | The DirectDrawSurface object that is the source for the blit operation.
src | A Rect object that defines the upper-left and lower-right points of the rectangle on the source surface to be blitted from.
flags | One or more of these values: DDCOOPERATIVE_CLIPTOCOMPONENT or DDCOOPERATIVE_OFFSETTOCOMPONENT DDBLT_ALPHADEST DDBLT_ASYNC DDBLT_ALPHADESTNEG DDBLT_KEYDEST DDBLT_ALPHASRC DDBLT_KEYSRC DDBLT_ALPHASRCNEG DDBLT_WAIT

Remarks

This method is capable of synchronous or asynchronous blits, either display memory to display memory, display memory to system memory, system memory to display memory, or system memory to system memory. The blits can be performed by using z-information, alpha information, source color keys, and destination color keys. Arbitrary stretching or shrinking will be performed if the source and destination rectangles are not the same size.

Typically, blt returns immediately with an error if the blitter is busy and the blit could not be set up. The DDBLT_WAIT flag can alter this behavior so that the method will either wait until the blit can be set up or another error occurs before it returns.


bltColorFill (DirectDrawSurface Class)

 Microsoft SDK for Java

bltColorFill

This method of the DirectDrawSurface Class fills the given rectangle on the surface with the given fill value.

Syntax

public int bltColorFill(Rect dest, int fillValue);

Return Value

Returns S_OK or 0 if the operation is successful; otherwise, returns an error code.

Parameters

dest | A Rect object that defines the upper-left and lower-right points of the rectangle on the destination surface to be filled.
fillvalue | The fill value to fill the rectangle with.


bltFast (DirectDrawSurface Class)

 Microsoft SDK for Java

bltFast

This method of the DirectDrawSurface Class performs a source copy blit or transparent blit by using a source color key or destination color key. This method always attempts an asynchronous blit if it is supported by the hardware.

Syntax

public int bltFast(int dx, int dy, DirectDrawSurface ddS, Rect src, int trans);

Return Value

Returns S_OK or 0 if the operation is successful; otherwise, returns an error code.

Parameters

dx |
dy | The x and y-coordinates to blit to on the destination surface.
ddS | The DirectDrawSurface object that is the source for the blit operation.
src | The Rect object that defines the upper-left and lower-right points of the rectangle on the source surface to be blitted from.
trans | One value of DDBLTFAST_ type, specifying the type of transfer.

Remarks

This method works only on display memory surfaces and cannot clip when blitting. The software implementation of bltFast is 10 percent faster than the blt method. However, there is no speed difference between the two if display hardware is being used.

Typically, bltFast returns immediately with an error if the blitter is busy and the blit cannot be set up. You can use the DDBLTFAST_WAIT flag, however, if you want this method to not return until either the blit can be set up or another error occurs.


bltFx (DirectDrawSurface Class)

 Microsoft SDK for Java

bltFx

This method of the DirectDrawSurface Class is capable of synchronous or asynchronous blits, in one of the following formats:

  • Display memory to display memory

  • Display memory to system memory

  • System memory to display memory

  • System memory to system memory

The blits can be performed by using z-information, alpha information, source color keys, and destination color keys. Arbitrary stretching or shrinking will be performed if the source and destination rectangles are not the same size.

Syntax

public int bltFx(Rect dest, DirectDrawSurface ddS, Rect src, int flags, DDBltFx bltFx);

Return Value

Returns S_OK or 0 if the operation is successful; otherwise, returns an error code.

Parameters

dest | A Rect object that defines the upper-left and lower-right points of the rectangle on the destination surface to be blitted to.
ddS | The DirectDrawSurface object that is the source for the blit operation.
src | A Rect object that defines the upper-left and lower-right points of the rectangle on the source surface to be blitted from.
flags | This parameter is currently not used and must be set to 0.
bltfx | The DDBltFx object that defines the parameters for the blit operations.


copyBitmap (DirectDrawSurface Class)

 Microsoft SDK for Java

copyBitmap

This method of the DirectDrawSurface Class copies a bitmap.

Syntax

public void copyBitmap(DirectDrawBitmap val, int cx, int cy, int dx, int dy);

Parameters

val | The DirectDrawBitmap object
cx | The bitmap's upper-left x-coordinate.
cy | The bitmap's upper-left y-coordinate.
dx | The bitmap's lower-right x-coordinate.
dy | The bitmap's lower-right y-coordinate.


create3DDevice (DirectDrawSurface Class)

 Microsoft SDK for Java

create3DDevice

This method of the DirectDrawSurface Class creates a device from the surface if you want a rendering surface. This method emulates the IUnknown interface's HRESULT QueryInterface(REFIID riid, LPVOID* obp); COM method inherited by DirectX3 COM interfaces.

Syntax

public Direct3dDevice create3DDevice(_Guid g);

Return Value

Returns a Direct3dDevice object that acts as a rendering surface.

Parameters

g A globally unique identifier retrieved with the enumDevices method.


deleteAttachedSurface (DirectDrawSurface Class)

 Microsoft SDK for Java

deleteAttachedSurface

This method of the DirectDrawSurface Class detaches two attached surfaces. The detached surface is not released.

Syntax

public void deleteAttachedSurface(int flags, DirectDrawSurface ddS);

Parameters

flags | Reserved; must be 0.
ddS | The DirectDrawSurface object to detach. If this parameter is null, all attached surfaces are detached.

See Also

flip


enumAttachedSurfaces (DirectDrawSurface Class)

 Microsoft SDK for Java

enumAttachedSurfaces

This method of the DirectDrawSurface Class enumerates all the surfaces attached to a given surface.

Syntax

public void enumAttachedSurfaces(IUnknown args, IEnumSurfacesCallback fn);

Parameters

args | Application-defined structure that is passed to the enumeration member every time it is called.
fn | Callback interface that contains callback function that will be called for each surface that is attached to this surface.


enumOverlayZOrders (DirectDrawSurface Class)

 Microsoft SDK for Java

enumOverlayZOrders

This method of the DirectDrawSurface Class enumerates the overlay surfaces on the specified destination. The overlays can be enumerated in front-to-back or back-to-front order.

Syntax

public void enumOverlayZOrders(int flags, IUnknown args, IEnumZOrdersCallback fn);

Parameters

flags | One value of DDENUMOVERLAYZ_ type.
args | User-defined context that will be passed to the callback function for each overlay surface.
fn | Callback interface that contains the callback function that will be called for each surface being overlaid on this surface.


flip (DirectDrawSurface Class)

 Microsoft SDK for Java

flip

This method of the DirectDrawSurface Class makes the surface memory associated with the DDSCAPS_BACKBUFFER surface become associated with the front-buffer surface.

Syntax

public void flip(DirectDrawSurface ddS, int flags);

Parameters

ddS | The DirectDrawSurface object that will be flipped to. The default for this parameter is null; in which case, flip cycles through the buffers in the order they are attached to each other. This parameter is used only as an override.
flags | Can be DDFLIP_WAIT.

Remarks

This method can be called only by a surface that has the DDSCAPS_FLIP and DDSCAPS_FRONTBUFFER values set. The display memory previously associated with the front buffer is associated with the back buffer. If there is more than one back buffer, a ring is formed and the surface memory buffers cycle one step through it every time flip is called.

The ddS parameter is used in rare cases when the back buffer is not the buffer that should become the front buffer. Typically this parameter is null.

The flip method will always be synchronized with the vertical blank.

See Also

getFlipStatus


getAttachedSurface (DirectDrawSurface Class)

 Microsoft SDK for Java

getAttachedSurface

This method of the DirectDrawSurface Class obtains the attached surface that has the specified capabilities.

Syntax

public DirectDrawSurface getAttachedSurface(int caps);

Return Value

Returns the DirectDrawSurface object if successful; otherwise, returns null.

Parameters

caps A value that specifies the hardware capabilities of the surface.

Remarks

Attachments are used to connect multiple DirectDrawSurface objects into complex structures, like the ones needed to support 3D page flipping with z-buffers. This method fails if more than one surface is attached that matches the capabilities requested. In this case, the application must use the enumAttachedSurfaces method to obtain the attached surfaces.


getBltStatus (DirectDrawSurface Class)

 Microsoft SDK for Java

getBltStatus

This method of the DirectDrawSurface Class obtains the blitter status.

Syntax

public int getBltStatus(int flags);

Return Value

Returns DD_OK if a blitter is present, DDERR_WASSTILLDRAWING if the blitter is busy.

Parameters

flags One value of DDGBS_ type.


getCaps (DirectDrawSurface Class)

 Microsoft SDK for Java

getCaps

This method of the DirectDrawSurface Class retrieves the capabilities of the surface. These capabilities are not necessarily related to the capabilities of the display device.

Syntax

public int getCaps();

Return Value

Returns the hardware capabilities of the surface.


getClipper (DirectDrawSurface Class)

 Microsoft SDK for Java

getClipper

This method of the DirectDrawSurface Class retrieves the DirectDrawClipper object associated with this surface.

Syntax

public DirectDrawClipper getClipper();

Return Value

Returns the DirectDrawClipper object if successful; null otherwise.

See Also

setClipper


getColorKey (DirectDrawSurface Class)

 Microsoft SDK for Java

getColorKey

This method of the DirectDrawSurface Class retrieves the color key value for the DirectDrawSurface object.

Syntax

public void getColorKey(int flags, DDColorKey val);

Parameters

flags | One value of DDCKEY_ type, specifying which color key to retrieve information for.
val | The DDColorKey object that receives the current values for the specified color key of the DirectDrawSurface object.

See Also

setColorKey


getDC (DirectDrawSurface Class)

 Microsoft SDK for Java

getDC

This method of the DirectDrawSurface Class creates a Graphical Device Interface-compatible handle of a device context for the surface.

Syntax

public int getDC();

Return Value

Returns the handle of a device context.


getDDInterface (DirectDrawSurface Class)

 Microsoft SDK for Java

getDDInterface

This method of the DirectDrawSurface Class retrieves an interface to the DirectDraw object that was used to create the surface.

Syntax

public IUnknown getDDInterface();

Return Value

Returns the IUnknown object if successful; null otherwise.


getFlipStatus (DirectDrawSurface Class)

 Microsoft SDK for Java

getFlipStatus

This method of the DirectDrawSurface Class indicates whether the surface has finished its flipping process.

Syntax

public int getFlipStatus(int flags);

Return Value

Returns DD_OK if successful, or DDERR_WASSTILLDRAWING if the surfaces has not finished its flipping process.

Parameters

flags One value of DDGFS_ type.

See Also

flip


getOverlayPositionX (DirectDrawSurface Class)

 Microsoft SDK for Java

getOverlayPositionX

This method of the DirectDrawSurface Class, given a visible, active overlay surface (DDSCAPS_OVERLAY flag set), returns the x-display-coordinate of the surface.

Syntax

public int getOverlayPositionX();

Return Value

Returns the x-coordinate.

See Also

getOverlayPositionY, setOverlayPosition, updateOverlay


getOverlayPositionY (DirectDrawSurface Class)

 Microsoft SDK for Java

getOverlayPositionY

This method of the DirectDrawSurface Class, given a visible, active overlay surface (DDSCAPS_OVERLAY flag set), returns the y-display-coordinate of the surface.

Syntax

public int getOverlayPositionY();

Return Value

Returns the y-coordinate.

See Also

getOverlayPositionX, setOverlayPosition, updateOverlay


getPalette (DirectDrawSurface Class)

 Microsoft SDK for Java

getPalette

This method of the DirectDrawSurface Class retrieves the DirectDrawPalette structure associated with this surface.

Syntax

public DirectDrawPalette getPalette();

Return Value

Returns the DirectDrawPalette object if successful; null otherwise. This is null if no DirectDrawPalette object is associated with this surface. If the surface is the primary surface, or a back buffer to the primary surface, and the primary surface is in 8-bpp mode, this method returns the system palette.

See Also

setPalette


getPixelFormat (DirectDrawSurface Class)

 Microsoft SDK for Java

getPixelFormat

This method of the DirectDrawSurface Class retrieves the color and pixel format of the surface.

Syntax

public void getPixelFormat(DDPixelFormat pf);

Parameters

pf A DDPixelFormat object that receives a detailed description of the current pixel and color space format of the surface.


getSurfaceDesc (DirectDrawSurface Class)

 Microsoft SDK for Java

getSurfaceDesc

This method of the DirectDrawSurface Class retrieves a description of the surface in its current condition.

Syntax

public void getSurfaceDesc(DDSurfaceDesc surface);

Parameters

surface A DDSurfaceDesc object that receives the current description of this surface.


isLost (DirectDrawSurface Class)

 Microsoft SDK for Java

isLost

This method of the DirectDrawSurface Class determines if the surface memory associated with a DirectDrawSurface object has been freed.

Syntax

public int isLost();

Return Value

Returns DD_OK if the memory has not been freed.

Remarks

You can use this method to reallocate surface memory. When a DirectDrawSurface object loses its surface memory, most methods perform no function.

Surfaces can lose their memory when the mode of the display card is changed, or when an application receives exclusive access to the display card and frees all the surface memory currently allocated on the display card.

See Also

restore


lock (DirectDrawSurface Class)

 Microsoft SDK for Java

lock

This method of the DirectDrawSurface Class obtains the contents of the surface memory.

Syntax

public void lock(Rect r, DDSurfaceDesc d, int flags, int hnd, byte[] memory);

Parameters

r | A Rect object that identifies the region of surface that is being locked.
d | A DDSurfaceDesc object that receives the relevant details about the surface.
flags | One or more values of DDLOCK_ type.
hnd | Handle of a system event that is triggered when the surface is ready to be locked.
memory | Array variable that receives the contents of the surface memory.

Remarks

The contents of the surface memory remain valid until the corresponding the unlock method is called. Applications that change the contents must flush the changes back into system memory (use the unlock for this as well).

Your application cannot blit from a region of a surface that is locked.

Typically, lock returns immediately when a lock cannot be obtained because a blit is in progress. You can use the DDLOCK_WAIT flag if you want the method to continue trying to obtain a lock.

See Also

unlock


releaseDC (DirectDrawSurface Class)

 Microsoft SDK for Java

releaseDC

This method of the DirectDrawSurface Class releases the handle of a device context previously obtained by using the getDC method.

Syntax

public void releaseDC(int hdc);

Parameters

hdc The handle of a device context.


restore (DirectDrawSurface Class)

 Microsoft SDK for Java

restore

This method of the DirectDrawSurface Class restores a surface that has been lost. This occurs when the surface memory associated with the DirectDrawSurface object has been freed.

Syntax

public int restore();

Return Value

Returns DD_OK is successful.

Remarks

Surfaces can be lost because the mode of the display card was changed or because an application received exclusive access to the display card and freed all the surface memory currently allocated on the card. When a DirectDrawSurface object loses its surface memory, many methods will return DDERR_SURFACELOST and perform no other function. The restore method will reallocate surface memory and reattach it to the DirectDrawSurface object.

A single call to this method will restore a DirectDrawSurface object's associated implicit surfaces (back buffers, and so on). An attempt to restore an implicitly created surface will result in an error. restore will not work across explicit attachments created by using the addAttachedSurface method—each of these surfaces must be restored individually.

See Also

isLost, addAttachedSurface


setClipper (DirectDrawSurface Class)

 Microsoft SDK for Java

setClipper

This method of the DirectDrawSurface Class attaches a DirectDrawClipper object to a DirectDrawSurface object.

Syntax

public void setClipper(DirectDrawClipper val);

Parameters

val The DirectDrawClipper object that will be attached to the DirectDrawSurface object. If this parameter is null, the current DirectDrawClipper object will be detached.

Remarks

This method is primarily used by surfaces that are being overlaid on or blitted to the primary surface. However, it can be used on any surface. After a DirectDrawClipper object has been attached and a clip list is associated with it, the DirectDrawClipper object will be used for the blt and updateOverlay operations involving the parent DirectDrawSurface object. This method can also detach a DirectDrawSurface object's current DirectDrawClipper object.

If this method is called several times consecutively on the same surface for the same DirectDrawClipper object, the reference count for the object is incremented only once. Subsequent calls do not affect the object's reference count.

See Also

getClipper


setColorKey (DirectDrawSurface Class)

 Microsoft SDK for Java

setColorKey

This method of the DirectDrawSurface Class sets the color key value for the DirectDrawSurface object if the hardware supports color keys on a per surface basis.

Syntax

public void setColorKey(int flags, DDColorKey val);

Parameters

flags | One value of DDCKEY_ type, specifying which color key to set.
val | A DDColorKey object that contains the new color key values for the DirectDrawSurface object.

See Also

getColorKey


setOverlayPosition (DirectDrawSurface Class)

 Microsoft SDK for Java

setOverlayPosition

This method of the DirectDrawSurface Class changes the display coordinates of an overlay surface.

Syntax

public void setOverlayPosition(int x, int y);

Parameters

x | New x-display-coordinate.
y | New y-display-coordinate.

See Also

getOverlayPositionX, getOverlayPositionY, updateOverlay


setPalette (DirectDrawSurface Class)

 Microsoft SDK for Java

setPalette

This method of the DirectDrawSurface Class attaches the specified DirectDrawPalette object to a surface. The surface uses this palette for all subsequent operations. The palette change takes place immediately, without regard to refresh timing.

Syntax

public void setPalette(DirectDrawPalette ddp);

Parameters

ddp The DirectDrawPalette object that this surface should use for future operations.

Remarks

If this method is called several times consecutively on the same surface for the same palette, the reference count for the palette is incremented only once. Subsequent calls do not effect the palette's reference count.

See Also

getPalette, com.ms.directX.DirectDraw.createPalette


unlock (DirectDrawSurface Class)

 Microsoft SDK for Java

unlock

This method of the DirectDrawSurface Class notifies DirectDraw that the direct surface manipulations are complete and copies the contents of the memory buffer into the surface.

Syntax

public void unlock(Rect r, DDSurfaceDesc d, byte[] memory);

Parameters

r | A Rect object that identifies the region of surface that receives the changes.
d | The DDSurfaceDesc object returned by the lock method.
memory | Array variable that contains the new contents of the surface memory.

See Also

lock


updateOverlay (DirectDrawSurface Class)

 Microsoft SDK for Java

updateOverlay

This method of the DirectDrawSurface Class repositions or modifies the visual attributes of an overlay surface. These surfaces must have the DDSCAPS_OVERLAY value set.

Syntax

public void updateOverlay(Rect r, DirectDrawSurface ddS, Rect d, int flags);

Parameters

r | A Rect object that defines the x, y, width, and height of the region on the source surface being used as the overlay.
ddS | The DirectDrawSurface that is being overlaid.
d | A Rect object that defines the x, y, width, and height of the region on the destination surface that the overlay should be moved to.
flags | One or more values of DDOVER_ type.


updateOverlayDisplay (DirectDrawSurface Class)

 Microsoft SDK for Java

updateOverlayDisplay

This method of the DirectDrawSurface Class repaints the rectangles in the dirty rectangle list of all active overlays. This clears the dirty rectangle list. This method is for software emulation only—it does nothing if the hardware supports overlays.

Syntax

public void updateOverlayDisplay(int flags);

Parameters

flags Type of update to perform. Can be DDOVER_REFRESHDIRTYRECTS or DDOVER_REFRESHALL.

See Also

addOverlayDirtyRect


updateOverlayZOrder (DirectDrawSurface Class)

 Microsoft SDK for Java

updateOverlayZOrder

This method of the DirectDrawSurface Class sets the z-order of an overlay.

Syntax

public void updateOverlayZOrder(int flags, DirectDrawSurface ddS);

Parameters

flags | One value of DDOVERZ_ type.
ddS | The DirectDrawSurface object to be used as a relative position in the overlay chain. This parameter is needed only for DDOVERZ_INSERTINBACKOF and DDOVERZ_INSERTINFRONTOF.

See Also

enumOverlayZOrders


DirectInput Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectInput Class

The DirectInput Class is in the com.ms.directX package.

public class DirectInput implements IDirectInput
{
  // Methods
  public void getDevCaps(int joyid, JoyCaps pjc);
  public String getDevCapsOEMVxd(int joyid);
  public String getDevCapsProductName(int joyid);
  public String getDevCapsRegKey(int joyid);
  public int getNumDevs();
  public void getPos(int joyid, JoyInfo info);
}


Methods (DirectInput Class)

 Microsoft SDK for Java

DirectInput Class Methods

The DirectInput Class contains the following methods:

getDevCaps queries a joystick to determine its capabilities.
getDevCapsOEMVxd queries a joystick for the name of its original virtual device driver.
getDevCapsProductName queries a joystick for its manufacturer's product name.
getDevCapsRegKey queries a joystick for the Microsoft® Windows® Registry key, where its capability information is stored.
getNumDevs queries the joystick driver for the number of joysticks it supports.
getPos queries a joystick for its position and button status.


getDevCaps (DirectInput Class)

 Microsoft SDK for Java

getDevCaps

This method of the DirectInput Class queries a joystick to determine its capabilities.

Syntax

public void getDevCaps(int joyid, JoyCaps pjc);

Parameters

joyid | The joystick identifier.
pic | The JoyCaps object that contains the joystick capabilities.


getDevCapsOEMVxd (DirectInput Class)

 Microsoft SDK for Java

getDevCapsOEMVxd

This method of the DirectInput Class queries a joystick for the name of its original virtual device driver.

Syntax

public String getDevCapsOEMVxd(int joyid);

Return Value

Returns the name of the virtual device driver.

Parameters

joyid The joystick identifier.


getDevCapsProductName (DirectInput Class)

 Microsoft SDK for Java

getDevCapsProductName

This method of the DirectInput Class queries a joystick for its manufacturer's product name.

Syntax

public String getDevCapsProductName(int joyid);

Return Value

Returns The joystick model name.

Parameters

joyid The joystick identifier.


getDevCapsRegKey (DirectInput Class)

 Microsoft SDK for Java

getDevCapsRegKey

This method of the DirectInput Class queries a joystick for the Microsoft® Windows® Registry key, where its capability information is stored.

Syntax

public String getDevCapsRegKey(int joyid);

Return Value

Returns the name of the registry key.

Parameters

joyid The joystick identifier.


getNumDevs (DirectInput Class)

 Microsoft SDK for Java

getNumDevs

This method of the DirectInput Class queries the joystick driver for the number of joysticks it supports.

Syntax

public int getNumDevs();

Return Value

Returns the number of joysticks the driver supports; otherwise, returns zero if no driver is present.


getPos (DirectInput Class)

 Microsoft SDK for Java

getPos

This method of the DirectInput Class queries a joystick for its position and button status.

Syntax

public void getPos(int joyid, JoyInfo info);

Parameters

joyid | The joystick identifier.
info | The JoyInfo object that contains extended position information and button status of the joystick.


DirectPlay2 Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectPlay2 Class

Applications use the methods of the DirectPlay2 Class of the com.ms.directX package to create Microsoft® DirectPlay®2 objects and work with system-level variables.

public class DirectPlay2 implements IDirectPlay2
{
  // Methods
  public void addPlayerToGroup(int groupId, int playerId);
  public void close();
  public IDirectPlay2 create(_Guid g);
  public int createGroup(String friendlyName, String formalName,
        byte[] data, int dataSize);
  public int createPlayer(String friendlyName, String formalName,
        int receiveEvent, byte[] data, int dataSize);
  public void deletePlayerFromGroup(int groupId, int playerId);
  public void destroyGroup(int groupId);
  public void destroyPlayer(int playerId);
  public void enumGroupPlayers(int groupId, _Guid sessionGuid,
        IEnumPlayersCallback2 callback, IUnknown context,
        int flags);
  public void enumGroups(_Guid sessionGuid,
        IEnumPlayersCallback2 callback, IUnknown context,
        int flags);
  public void enumPlayers(_Guid sessionGuid,
        IEnumPlayersCallback2 callback, IUnknown context,
        int flags);
  public void enumServiceProviders(
        IEnumServiceProvidersCallback callback, IUnknown context);
  public void enumSessions(DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password, int timeOut,
        IEnumSessionsCallback2 callback, IUnknown context,
        int flags);
  public void getCaps(DPCaps caps, int flags);
  public void getGroupData(int groupId, byte[] data,
        int[] dataSize, int flags);
  public String getGroupFormalName(int groupId);
  public String getGroupFriendlyName(int groupId);
  public int getMessageCount(int playerId);
  public void getPlayerAddress(int playerId, byte[] addressData,
        int[] addressSize);
  public int getPlayerAddressSize(int playerId);
  public void getPlayerCaps(int playerId, DPCaps caps, int flags);
  public void getPlayerData(int playerId, byte[] data,
        int[] dataSize, int flags);
  public String getPlayerFormalName(int playerId);
  public String getPlayerFriendlyName(int playerId);
  public void getSessionDesc(DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String[] sessionName, String[] password);
  public void initialize(_Guid guid);
  public void open(DPSessionDesc sessionDesc, _Guid sessionGuid,
        _Guid applicationGuid, String sessionName,
        String password, int flags);
  public void receive(int[] fromPlayerId, int[] toPlayerId,
        int flags, byte[] data, int[] dataSize);
  public int receiveSize(int flags);
  public void send(int fromPlayerId, int toPlayerId, int flags,
        byte[] data, int dataSize);
  public void setGroupData(int groupId, byte[] data, int dataSize,
        int flags);
  public void setGroupName(int groupId, String friendlyName, String
        formalName, int flags);
  public void setPlayerData(int playerId, byte[] data,
        int dataSize, int flags);
  public void setPlayerName(int playerId, String friendlyName,
        String formalName, int flags);
  public void setSessionDesc(DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password, int flags);
  public void stopEnumGroupPlayers();
  public void stopEnumGroups();
  public void stopEnumPlayers();
  public void stopEnumServiceProviders();
  public void stopEnumSessions();
}

CAUTION The enumeration methods provided in this class are fundamentally different from their native code counterparts. While the native code implementation return type is a boolean, the Java return type is void. This makes stopping an enumeration more difficult (you can not return false to stop the enumeration). You can use the following DirectPlay methods to stop enumerations:

stopEnumSessions
stopEnumGroups
stopEnumGroupPlayers
stopEnumPlayers
stopEnumServiceProviders

The stopEnumSessions is the most important method of these, because a session enumeration can proceed infinitely.


Methods (DirectPlay2 Class)

 Microsoft SDK for Java

DirectPlay2 Class Methods

The DirectPlay2 Class contains the following methods:

addPlayerToGroup adds an existing player to an existing group.
close closes a previously opened session.
create creates a DirectPlay object.
createGroup creates a logical group of players in the current session.
createPlayer creates a local player for the current session.
deletePlayerFromGroup removes a player from a group.
destroyGroup deletes a group from the session.
destroyPlayer deletes a player from the session, removes any pending messages destined for that player from the message queue, and removes the player from any groups to which that player belonged.
enumGroupPlayers enumerates all the players of a particular group existing in the current session.
enumGroups enumerates the groups available to a session.
enumPlayers enumerates the players in a session. Use the stopEnumPlayers method to stop the enumeration.
enumServiceProviders enumerates the DirectPlay service providers installed on the system.
enumSessions enumerates the sessions available to this DirectPlay object.
getCaps retrieves the capabilities of this DirectPlay object.
getGroupData retrieves data for a group of players.
getGroupFormalName retrieves the formal name associated with the group.
getGroupFriendlyName retrieves the friendly name associated with the group.
getMessageCount queries for the number of messages in a specific local player's message receive queue.
getPlayerAddress retrieves the DirectPlay address for a player.
getPlayerAddressSize retrieves the DirectPlay address size for a player.
getPlayerCaps obtains the current capabilities of a specified player.
getPlayerData retrieves player data for the specified player ID.
getPlayerFormalName obtains the formal name associated with a player.
getPlayerFriendlyName obtains the friendly name associated with a player.
getSessionDesc retrieves a description of the specified session.
initialize initializes the DirectPlay2 object.
open establishes a gaming session instance.
receive retrieves a message from the message queue.
receiveSize retrieves the size of the message data associated with the next or specified message on the message queue.
send sends messages to other players, to a group of players, or to all players in the session.
setGroupData sets data for the group specified by the group ID.
setGroupName sets the name of a group after it has been created.
setPlayerData associates an application-specific data block with a player ID.
setPlayerName sets the name of the player after it has been changed.
setSessionDesc is currently not supported.
stopEnumGroupPlayers stops a group players enumeration.
stopEnumGroups stops a group enumeration.
stopEnumPlayers stops a players enumeration.
stopEnumServiceProviders stops a service provider enumeration.
stopEnumSessions stops a session enumeration.


addPlayerToGroup (DirectPlay2 Class)

 Microsoft SDK for Java

addPlayerToGroup

This method of the DirectPlay2 Class adds an existing player to an existing group.

Syntax

public void addPlayerToGroup(int groupId, int playerId);

Parameters

groupId | The ID of the group to be augmented.
playerId | The ID of the player to be added to the group.

Remarks

Groups cannot be added to other groups, but players can be members of multiple groups. A DPSYS_ADDDIRECTPLAYERTOGROUP system message will be generated and sent to all the other players.

See Also

createGroup, deletePlayerFromGroup, DPSYS_ADDDIRECTPLAYERTOGROUP


close (DirectPlay2 Class)

 Microsoft SDK for Java

close

This method of the DirectPlay2 Class closes a previously opened session.

Syntax

public void close();

Remarks

All locally created players will be destroyed, and corresponding DPSYS_DESTROYPLAYERORGROUP system messages are sent to other session participants. However, groups will not be destroyed; use destroyGroup to destroy the group.

See Also

destroyPlayer, DPMSG_DESTROYPLAYERORGROUP, open


create (DirectPlay2 Class)

 Microsoft SDK for Java

create

This method of the DirectPlay2 Class creates a DirectPlay object.

Syntax

public IDirectPlay2 create(_Guid g);

Return Value

Returns the DirectPlay object if successful; null otherwise.

Parameters

g A _Guid object that specifies the globally unique identifier (GUID) that represents the service provider that should be created.

Remarks

This function attempts to initialize a DirectPlay object. You should call the enumServiceProviders method immediately before initialization to determine what types of service providers are available (enumServiceProviders fills in the g parameter for create).

See Also

enumServiceProviders


createGroup (DirectPlay2 Class)

 Microsoft SDK for Java

createGroup

This method of the DirectPlay2 Class creates a logical group of players in the current session.

Syntax

public int createGroup(String friendlyName, String formalName, byte[] data, int dataSize);

Return Value

Returns a unique DirectPlay ID that identifies the new group.

Parameters

formalName | The formal name of the group. Use null to indicate that the group has no formal name.
friendlyName | The friendly name of the group. Use null to indicate that the group has no friendly name.
data | A block of application-defined remote data to associate with the group ID. Null indicates that the group has no initial data. The data specified here is assumed to be remote data that will be propagated to all the other applications in the session as if setGroupData were called.
dataSize | The size, in bytes, of data.

Remarks

Messages can be sent to a group, and DirectPlay will forward the message to every player in the group. The Group ID returned to the caller should be used to identify the group for message passing and data association. Player and Group identifiers assigned by DirectPlay will always be unique within the session. This method will generate a DPSYS_CREATEPLAYERORGROUP message that will be sent to all the other players.

See Also

DPMSG_CREATEPLAYERORGROUP, destroyGroup, enumGroups, enumGroupPlayers, send


createPlayer (DirectPlay2 Class)

 Microsoft SDK for Java

createPlayer

This method of the DirectPlay2 Class creates a local player for the current session.

Syntax

public int createPlayer(String friendlyName, String formalName, int receiveEvent, byte[] data, int dataSize);

Return Value

Returns a unique DirectPlay ID that identifies the new player.

Parameters

formalName | The formal name of the player. Use null to indicate that the player has no formal name information.
friendlyName | The friendly name of the player. Use null to indicate that the player has no friendly name.
receiveEvent | An event object created by the application that will be triggered by DirectPlay2 when a message addressed to this player is received.
data | A block of application-defined remote data to associate with the group ID. Null indicates that the group has no initial data. The data specified here is assumed to be remote data that will be propagated to all the other applications in the session as if setPlayerData were called.
dataSize | The size, in bytes, of data.

Remarks

A single process can have multiple local players that communicate through a DirectPlay object with any number of other local or remote players running on multiple computers. The player ID returned to the caller should be used to identify the player for message passing and data association. Player and Group IDs assigned by DirectPlay will always be unique within the session.

The application can associate an initial name with the player at its creation (see setPlayerName). The names in friendlyName and formalName are provided for human use only; they are not used internally and need not be unique.

Upon successful completion, this method sends a DPSYS_CREATEPLAYERORGROUP system message to all the other players in the session announcing that a new player has joined the session.

See Also

DPMSG_CREATEPLAYERORGROUP, destroyPlayer, enumPlayers, receive, send, setPlayerName


deletePlayerFromGroup (DirectPlay2 Class)

 Microsoft SDK for Java

deletePlayerFromGroup

This method of the DirectPlay2 Class removes a player from a group.

Syntax

public void deletePlayerFromGroup(int groupId, int playerId);

Parameters

groupId | The group ID of the group to be adjusted.
playerId | The ID of the player to be removed from the group.

Remarks

A DPSYS_DELETEPLAYERFROMGROUP system message is generated to inform the other players of this change.

See Also

addPlayerToGroup, DPMSG_DELETEPLAYERFROMGROUP


destroyGroup (DirectPlay2 Class)

 Microsoft SDK for Java

destroyGroup

This method of the DirectPlay2 Class deletes a group from the session. The ID belonging to this group will not be reused during the current session.

Syntax

public void destroyGroup(int groupId);

Parameters

groupId The ID of the group being removed from the game.

Remarks

It is not necessary to empty a group before deleting it. The individual players belonging to the group are not destroyed. This method will generate a DPSYS_DELETEPLAYERFROMGROUP for each player in the group, and then generate a DPSYS_DESTROYPLAYERORGROUP system message.

See Also

createGroup, DPMSG_DESTROYPALYERORGROUP


destroyPlayer (DirectPlay2 Class)

 Microsoft SDK for Java

destroyPlayer

This method of the DirectPlay2 Class deletes a player from the session, removes any pending messages destined for that player from the message queue, and removes the player from any groups to which that player belonged. The player ID will not be reused during the current session.

Syntax

public void destroyPlayer(int playerId);

Parameters

playerId The ID of the player that is being removed from the session.

Remarks

This method will generate a DPSYS_DELETEPLAYERFROMGROUP message for each group that the player belongs to, and then generate a DPSYS_DESTROYPLAYERORGROUP system message.

See Also

createPlayer, DPSYS_DESTROYPLAYERORGROUP


enumGroupPlayers (DirectPlay2 Class)

 Microsoft SDK for Java

enumGroupPlayers

This method of the DirectPlay2 Class enumerates all the players of a particular group existing in the current session. Use the stopEnumGroupPlayers method to stop the enumeration.

Syntax

public void enumGroupPlayers(int groupId, _Guid sessionGuid, IEnumPlayersCallback2 callback, IUnknown context, int flags);

Parameters

groupId | The Group ID, whose players are to be enumerated.
sessionGuid | The GUID of the DirectPlay session of interest. This parameter must be set to null unless the DPENUMPLAYERS_SESSION flag is specified.
callback | The callback interface that contains the callback function to be called for every player in the group.
context | A caller-defined context that is passed to each enumeration callback.
flags | The flags to pass to the callback function.

Remarks

By default, this method will enumerate group players by using the local player list for the current session. This method cannot be called from within an enumSessions enumeration.

See Also

createPlayer, destroyPlayer, addPlayerToGroup, deletePlayerFromGroup, stopEnumGroupPlayers


enumGroups (DirectPlay2 Class)

 Microsoft SDK for Java

enumGroups

This method of the DirectPlay2 Class enumerates the groups available to a session. Use the stopEnumGroups method to stop the enumeration.

Syntax

public void enumGroups(_Guid sessionGuid, IEnumPlayersCallback2 callback, IUnknown context, int flags);

Parameters

sessionGuid | The GUID of the DirectPlay session of interest. This parameter must be set to NULL unless the DPENUMPLAYERS_SESSION flag is specified.
callback | The callback interface that contains the callback function to be called for every group in the session.
context | A caller-defined context that is passed to each enumeration callback.
flags | The value can be 0 or DPENUMPLAYERS_SESSION. This flag is passed to the callback function.

Remarks

By default, this method will enumerate using the local player list for the current session. The DPENUMPLAYERS_SESSION flag can be used, along with a session instance GUID, to request that a session's host provide its list for enumeration. This method cannot be called from within an enumSessions enumeration. Furthermore, use of the DPENUMPLAYERS_SESSION flag with this method must occur after the enumSessions method has been called and before any calls to close or open.

See Also

createGroup, destroyGroup, enumSessions, stopEnumGroups


enumPlayers (DirectPlay2 Class)

 Microsoft SDK for Java

enumPlayers

This method of the DirectPlay2 Class enumerates the players in a session. Use the stopEnumPlayers method to stop the enumeration.

Syntax

public void enumPlayers(_Guid sessionGuid, IEnumPlayersCallback2 callback, IUnknown context, int flags);

Parameters

sessionGuid | A GUID of the DirectPlay session of interest. This parameter must be set to NULL unless the DPENUMPLAYERS_SESSION flag is specified.
callback | The callback instance that contains the callback function that will be called for every group in the session.
context | A caller-defined context that is passed to each enumeration callback.
flags | One or more values of the DPENUMPLAYERS_GROUP type. The values are also passed to the callback function.

Remarks

By default, this method will enumerate players in the current open session. Groups can also be included in the enumeration by using the DPENUMPLAYERS_GROUP flag. The DPENUMPLAYERS_SESSION flag can be used with a session instance GUID to request that a session host provide its list for enumeration. This method cannot be called from within an enumSessions enumeration. Also, use of the DPENUMPLAYERS_SESSION flag with this method must occur after the enumSessions method has been called, and before any calls to close or open.

See Also

createPlayer, destroyPlayer, enumSessions, stopEnumPlayers


enumServiceProviders (DirectPlay2 Class)

 Microsoft SDK for Java

enumServiceProviders

This method of the DirectPlay2 Class enumerates the DirectPlay service providers installed on the system. Use the stopEnumServiceProviders method to stop the enumeration.

Syntax

public void enumServiceProviders(IEnumServiceProvidersCallback callback, IUnknown context);

Parameters

callback | The IenumServiceProvidersCallback interface that contains the callback function to be called with a description of each DirectPlay service provider interface installed in the system.
context | The caller-defined data that is passed to the callback function each time the function is invoked.

Remarks

This method enumerates service providers installed in the system, even though the system might not be capable of using those service providers. For example, a TAPI service provider can be enumerated, even though the system might not have a modem installed.

See Also

stopEnumServiceProviders


enumSessions (DirectPlay2 Class)

 Microsoft SDK for Java

enumSessions

This method of the DirectPlay2 Class enumerates the sessions available to this DirectPlay object. Use the stopEnumSessions method to stop the enumeration.

Syntax

public void enumSessions(DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String sessionName, String password, int timeOut, IEnumSessionsCallback2 callback, IUnknown context, int flags);

Parameters

sessionDesc | A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this structure will be enumerated. If a password is required, the password field should be set accordingly.
sessionGuid | The GUID of the DirectPlay session of interest. This parameter must be set to NULL unless the DPENUMPLAYERS_SESSION flag is specified.
applicationGuid | The GUID of the application.
sessionName | The Unicode string containing the name of the session. Use this member only if the IDirectPlay2 interface is in use.
password | The Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.
timeOut | The total amount of time (in milliseconds) that DirectPlay will wait for replies to the enumeration message (not the time between each enumeration). It is recommended that this parameter be set to zero, so DirectPlay can compute the default timeout appropriate for the service provider.
callback | The callback interface that contains the callback function to be called for each DirectPlay session responding.
context | A user-defined context that is passed to each enumeration callback.
flags | A value of the DPENUMSESSIONS_ALL type. Set to 0 or DPENUMSESSIONS_AVAILABLE, to enumerate only available sessions.

Remarks

This method is usually called immediately after the DirectPlay object is created using directPlayCreate. It cannot be called while connected to a session or after an application has created a session. enumSessions works by asking that the service provider locate one or more hosts on the network and send the hosts an enumeration request. The replies received make up the sessions that are enumerated. The amount of time DirectPlay spends listening for these replies is controlled by the f1 parameter. When this time interval has expired, your callback will be notified with the DPESC_TIMEDOUT flag. At this point, you can choose to continue the enumeration by setting f1 to a new value and returning 1 or by returning 0 to cancel the enumeration. It is recommended that f1 be set to 0. In that case, DirectPlay will compute a time out that is appropriate for the service provider.

Usually, only sessions that can be joined are enumerated. If the DPENUMSESSIONS_ALL flag is specified, sessions will be enumerated even if the creation of new players has been disabled. Be aware that the application will still not be able to join these sessions.

If the application was not launched by a lobby, the service provider can display a dialog to obtain information from the user to perform the enumeration. For example, the Microsoft serial service provider will ask for COM port settings, the modem service provider will ask for a phone number, and the Internet service provider will ask for an IP address of the host.

Password protected sessions will not be enumerated unless you supply a correct password.

See Also

open, stopEnumSessions


getCaps (DirectPlay2 Class)

 Microsoft SDK for Java

getCaps

This method of the DirectPlay2 Class retrieves the capabilities of this DirectPlay object.

Syntax

public void getCaps(DPCaps caps, int flags);

Parameters

caps | A DPCaps object that receives the capabilities of the DirectPlay object. The size field of the DPCaps object must be filled in before using getCaps.
flags | If this parameter is set to 0, the capabilities will be computed for nonguaranteed messaging. DPGETCAPS_GUARANTEED Retrieves the capabilities for a guaranteed message delivery.

Remarks

The difference between this method and getPlayerCaps is that this method returns the capabilities of the current session and getPlayerCaps returns the capabilities of the requested player.

See Also

com.ms.directX.DPCaps, getPlayerCaps, send


getGroupData (DirectPlay2 Class)

 Microsoft SDK for Java

getGroupData

This method of the DirectPlay2 Class retrieves data for a group of players.

Syntax

public void getGroupData(int groupId, byte[] data, int[] dataSize, int flags);

Parameters

groupId | The group ID that data is being requested for.
data | The buffer where the application-specific group data is to be written. Set this parameter to NULL to request only the size of data. The dataSize parameter will be set to the size required to hold the data.
dataSize | The size of the buffer before the method is called. After the method returns, this parameter will be set to the size (in bytes) of the group data. If the buffer was too small (DPERR_BUFFERTOOSMALL), this parameter will be set to the buffer size required (see the note about passing null as an argument for other behavior regarding DPERR_BUFFERTOOSMALL).
flags | If this parameter is set to 0, the remote data will be retrieved.

Remarks

DirectPlay can maintain two types of group data: local and remote. The application must specify which type of data to retrieve. Local data was set by this DirectPlay2 object by using the DPSET_LOCAL flag. Remote data might have been set by any application in the session by using the DPSET_REMOTE flag.

You can pass a null for the data buffer parameter to retrieve the size for the buffer. However, when you do this you must put the code into a try...catch block, because a DPERR_BUFFERTOOSMALL error is generated. The following example shows how you might implement a try...catch block to catch the error:

int  hr=0;
try {
      Glb.glpDPlay2.getGroupData(dpID,null, dataSize,DPGET_REMOTE);
    }
catch (ComException e){ hr= e.getHResult();}

// Check for the DPERR_BUFFERTOOSMALL error
if (hr!=DPERR_BUFFERTOOSMALL){
       //problem...
    }

See Also

com.ms.directX.DirectXConstants.DPGET_REMOTE, com.ms.directX.DirectXConstants.DPGET_LOCAL


getGroupFormalName (DirectPlay2 Class)

 Microsoft SDK for Java

getGroupFormalName

This method of the DirectPlay2 Class retrieves the formal name associated with the group.

Syntax

public String getGroupFormalName(int groupId);

Return Value

Returns the formal name associated with the group.

Parameters

groupId The ID of the group, whose name is being requested.


getGroupFriendlyName (DirectPlay2 Class)

 Microsoft SDK for Java

getGroupFriendlyName

This method of the DirectPlay2 Class retrieves the friendly name associated with the group.

Syntax

public String getGroupFriendlyName(int groupId);

Return Value

Returns the friendly name associated with the group.

Parameters

groupId The ID of the group, whose name is being requested.


getMessageCount (DirectPlay2 Class)

 Microsoft SDK for Java

getMessageCount

This method of the DirectPlay2 Class queries for the number of messages in a specific local player's message receive queue.

Syntax

public int getMessageCount(int playerId);

Return Value

Returns the message count.

Parameters

playerId The layer ID that the message count is requested for. The player must be local.

See Also

receive


getPlayerAddress (DirectPlay2 Class)

 Microsoft SDK for Java

getPlayerAddress

This method of the DirectPlay2 Class retrieves the DirectPlay address for a player. The DirectPlay address is a network address for a player using a specific service provider.

Syntax

public void getPlayerAddress(int playerId, byte[] addressData, int[] addressSize);

Parameters

playerId | Player ID that the address is being requested for.
addressData | Address of a buffer where the DirectPlay2 address is to be written. Set this parameter to NULL to request only the size of data. The addressSize parameter will be set to the size required to hold the data.
addressSize | The size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the group data. If the buffer was too small (DPERR_BUFFERTOOSMALL), then this parameter will be set to the buffer size that is required.


getPlayerAddressSize (DirectPlay2 Class)

 Microsoft SDK for Java

getPlayerAddressSize

This method of the DirectPlay2 Class retrieves the DirectPlay address size for a player.

Syntax

public int getPlayerAddressSize(int playerId);

Return Value

Returns the address size.

Parameters

playerId The player ID that the address size is being requested for.


getPlayerCaps (DirectPlay2 Class)

 Microsoft SDK for Java

getPlayerCaps

This method of the DirectPlay2 Class obtains the current capabilities of a specified player.

Syntax

public void getPlayerCaps(int playerId, DPCaps caps, int flags);

Parameters

playerId | The player ID that the capabilities should be computed for.
caps | A DPCaps object that receives the capabilities of the player. The size field of the DPCaps object must contain a value before using getPlayerCaps.
flags | If this parameter is set to 0, the capabilities will be computed for nonguaranteed messaging.

Remarks

The difference between this method and getCaps is that this method returns the capabilities of the requested player; getCaps returns the capabilities of the current session.

See Also

com.ms.directX.DPCaps, getCaps, send, com.ms.directX.DirectXConstants.DPGETCAPS_GUARANTEED


getPlayerData (DirectPlay2 Class)

 Microsoft SDK for Java

getPlayerData

This method of the DirectPlay2 Class retrieves player data for the specified player ID.

Syntax

public void getPlayerData(int playerId, byte[] data, int[] dataSize, int flags);

Parameters

playerId | ID of the player for which data is being requested.
data | Application-specific player data. Set this parameter to null to request only the size of data. The dataSize parameter will be set to the size required to hold the data.
dataSize | The size of the buffer before calling this method. After the method returns, this parameter will be set to the size, in bytes, of the group data. If the buffer was too small (DPERR_BUFFERTOOSMALL), this parameter will be set to the buffer size required.
flags | If this parameter is set to 0, the remote data will be retrieved. DPGET_REMOTE Retrieves the current data from the remote shared data space. DPGET_LOCAL Retrieves the local data set by this application.


getPlayerFormalName (DirectPlay2 Class)

 Microsoft SDK for Java

getPlayerFormalName

This method of the DirectPlay2 Class obtains the formal name associated with a player.

Syntax

public String getPlayerFormalName(int playerId);

Return Value

Returns the name.

Parameters

playerId Player ID number for which the name information is being requested.

See Also

setPlayerName


getPlayerFriendlyName (DirectPlay2 Class)

 Microsoft SDK for Java

getPlayerFriendlyName

This method of the DirectPlay2 Class obtains the friendly name associated with a player.

Syntax

public String getPlayerFriendlyName(int playerId);

Return Value

Returns the name.

Parameters

playerId Player ID number for which the name information is being requested.

See Also

setPlayerName


getSessionDesc (DirectPlay2 Class)

 Microsoft SDK for Java

getSessionDesc

This method of the DirectPlay2 Class retrieves a description of the specified session.

Syntax

public void getSessionDesc(DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String[] sessionName, String[] password);

Parameters

sessionDesc | A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this structure will be enumerated. If a password is required, the password field should be set accordingly.
sessionGuid | The GUID of the session instance.
applicationGuid | The GUID of the application running in the session instance. It uniquely identifies the application so that DirectPlay connects only to other computers running the same application. This member can be set to GUID_NULL to enumerate sessions for any application.
sessionName | The Unicode string containing the name of the session. Use this member only if the IDirectPlay2 interface is in use.
password | The Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.


initialize (DirectPlay2 Class)

 Microsoft SDK for Java

initialize

This method of the DirectPlay2 Class initializes the DirectPlay2 object.

Syntax

public void initialize(_Guid guid);

Parameters

guid The GUID used as the interface identifier.

Remarks

Since the DirectPlay2 object is initialized when it is created, calling this method will always result in no action.


open (DirectPlay2 Class)

 Microsoft SDK for Java

open

This method of the DirectPlay2 Class establishes a gaming session instance.

Syntax

public void open(DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String sessionName, String password, int flags);

Parameters

sessionDesc | The DPSessionDesc object describing the session to be created or joined.
sessionGuid | The GUID of the DirectPlay session of interest.
applicationGuid | The GUID of the application running in the session instance. It uniquely identifies the application so that DirectPlay connects only to other computers running the same application. This member can be set to GUID_NULL to enumerate sessions for any application.
sessionName | Unicode string containing the name of the session. Use this member only if the IdirectPlay2 interface is in use.
password | Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.
flags | Can be one of the following flags: DPOPEN_CREATE DPOPEN_JOIN

Remarks

An application can either create a new session (which other remote applications join) or join an existing session. open must be called before any local players are created. Before an application can join an existing session, it will use enumSessions to obtain a list of what sessions can be joined and their session descriptions. Attempting to join a session where adding new players is disabled, joining is disabled, or the player limit has been reached will result in no action.

See Also

close, enumSessions


receive (DirectPlay2 Class)

 Microsoft SDK for Java

receive

This method of the DirectPlay2 Class retrieves a message from the message queue.

Syntax

public void receive(int[] fromPlayerId, int[] toPlayerId, int flags, yte[] data, int[] dataSize);

Parameters

fromPlayerId | A array that receives the player ID of the sender of the message.
toPlayerId | An array that receives the player ID of the receiver of the message.
flags | One or more values of DPRECEIVE_ type. Both DPRECEIVE_TOPLAYER and DPRECEIVE_FROMPLAYER can be specified, in which case receive will return whichever message is encountered first.
data | Array variable that receives the message data.
dataSize | The length of the array assigned to the data parameter.

Remarks

Any message received from player ID DPID_SYSMSG is a system message that is generated by the host. For such messages, the application should interpret data as a generic system message and check for the type of message before processing it.

Messages that were sent to player ID DPID_SYSMSG as a way to broadcast them to all players, or to a group ID to send them to all the players in the group, still appear to come from the sending player ID. An application will only receive messages directed to a local player. A player cannot receive a message where the sender and receiver IDs are the same.

If DPSESSION_NOMESSAGEID is specified in the session description, the LPID_FROM and LPID_TO variables are meaningless.

All the service providers shipped with DirectPlay perform integrity checks on the data to protect against corruption. Any message received will be verified. If data corruption is detected, the message will either be thrown away (if it was sent nonguaranteed) or it will be retransmitted (if it was sent guaranteed).

See Also

send


receiveSize (DirectPlay2 Class)

 Microsoft SDK for Java

receiveSize

This method of the DirectPlay2 Class retrieves the size of the message data associated with the next or specified message on the message queue.

Syntax

public int receiveSize(int flags);

Return Value

Returns the size of the message data.

Parameters

flags Can be DPRECEIVE_ALL.


send (DirectPlay2 Class)

 Microsoft SDK for Java

send

This method of the DirectPlay2 Class sends messages to other players, to a group of players, or to all players in the session.

Syntax

public void send(int fromPlayerId, int toPlayerId, int flags, byte[] data, int dataSize);

Parameters

fromPlayerId | The player ID of the sending player. The player ID must correspond to one of the local players on this computer.
toPlayerId | The player ID of the player to send the message to, the group ID of the group of players to send the message to, or DPID_ALLPLAYERS to send to all players in the session. If DPSEND_OPENSTREAM or DPSEND_CLOSESTREAM flags are used, this parameter must be a player ID.
flags | One value of DPSEND_ type, indicating how the message should be sent. If this parameter is set to 0, the message is sent nonguaranteed and at normal priority.
data | Array variable that contains the data being sent. Set to null if there is no actual message to send.
dataSize | Length of the data being sent.

Remarks

To send a message to another player, specify the target player's player ID. To send a message to a group of players, send the message to the group ID assigned to the group. To send messages to the entire session, specify the player ID DPID_ALLPLAYERS. The send method cannot be used inside a lock / unlock or a getDC / releaseDC method pair.

A player cannot send a message to itself. If a player sends a message to a group that it is part of or to DPID_ALLPLAYERS, it will not receive a copy of that message.

If DPSESSION_NOMESSAGEID was specified in the session description, it is possible for a player to receive a message that it sent to a group. Since there is no DirectPlay message ID header on the message (indicating who sent the message), it cannot filter out messages from itself when the service provider implements group sends, and the application will need to be able to evaluate this based on the content of the message.

When DPSESSION_NOMESSAGEID is used, the message is sent to one of the local players on the target computer.

Messages can be sent guaranteed or nonguaranteed. By default, messages are sent nonguaranteed, which means that DirectPlay does no verification that the message reached the intended recipient. Sending a guaranteed message takes much longer, a minimum of two to three times longer than a nonguaranteed message. Applications should try to minimize sending guaranteed messages as much as possible and design the application to tolerate lost messages.

All the service providers shipped with DirectPlay perform integrity checks on the data to protect against corruption. Any message received will be verified, and if data corruption is detected, it will either be thrown away (if it was sent nonguaranteed), or it will be retransmitted (if it was sent guaranteed).

Note In this version of DirectPlay2, DPSEND_GUARANTEED will only guarantee delivery if the service provider supports it. An application can find out if delivery will be guaranteed by calling getCaps and checking for the DPCAPS_GUARANTEEDSUPPORTED flag. If this flag is not set, the DPSEND_GUARANTEED flag will be ignored and the message will be sent nonguaranteed. The next version of DirectPlay will implement guaranteed delivery on nonguaranteed service providers so the guaranteed supported CAPS flag will always be present. If the application implements its own method of guaranteeing message delivery, it must be sure not to use the DPSEND_GUARANTEED flag. When testing the performance of your application, it is important to know if the service provider supports guaranteed messaging. If it does not, every place you specified DPSEND_GUARANTEED will run slower with the next version of DirectPlay.

See Also

receive


setGroupData (DirectPlay2 Class)

 Microsoft SDK for Java

setGroupData

This method of the DirectPlay2 Class sets data for the group specified by the group ID.

Syntax

public void setGroupData(int groupId, byte[] data, int dataSize, int flags);

Parameters

groupId | The group ID for which data is being set.
data | The data to be set. Set to NULL to clear any existing group data.
dataSize | Size of the data buffer.
flags | If this parameter is set to 0, the remote group data will be set and propagated using nonguaranteed messaging. See also: DPSET_REMOTE DPSET_LOCAL DPSET_GUARANTEED


setGroupName (DirectPlay2 Class)

 Microsoft SDK for Java

setGroupName

This method of the DirectPlay2 Class sets the name of a group after it has been created. A DPSYS_SETPLAYERORGROUPNAME system message will be sent to all the other players notifying them of the change, unless DPSESSION_NODATAMESSAGES is set in the session description.

Syntax

public void setGroupName(int groupId, String friendlyName, String formalName, int flags);

Parameters

groupId | The ID of the group for which the name is being set.
friendlyName | The friendly name of the group.
formalName | The formal name of the group.
flags | If this parameter is set to 0, the name will be propagated to all the remote systems by using nonguaranteed message passing. See also: DPSET_GUARANTEED


setPlayerData (DirectPlay2 Class)

 Microsoft SDK for Java

setPlayerData

This method of the DirectPlay2 Class associates an application-specific data block with a player ID.

Syntax

public void setPlayerData(int playerId, byte[] data, int dataSize, int flags);

Parameters

playerId | The ID of the player for which data is being set.
data | The data to be set. Set this parameter to null to clear any existing player data.
dataSize | The size of the data.
flags | If this parameter is set to 0, the remote player data will be set and propagated by using nonguaranteed messaging. This parameter can be one or a combination of the following flags: DPSET_REMOTE DPSET_LOCAL DPSET_GUARANTEED


setPlayerName (DirectPlay2 Class)

 Microsoft SDK for Java

setPlayerName

This method of the DirectPlay2 Class sets the name of the player after it has been changed. A DPSYS_SETPLAYERORGROUPNAME system message will be sent to all other players notifying them of the change, unless DPSESSION_NODATAMESSAGES is set in the session description.

Syntax

public void setPlayerName(int playerId, String friendlyName, String formalName, int flags);

Parameters

playerId | The player ID for which data is being sent.
formalName | The formal name for the player. Use null if the player has no formal name.
friendlyName | The friendly name for the player. Use null if the player has no friendly name.
flags | If this parameter is set to 0, the name will be propagated to all the remote systems using nonguaranteed message passing.

See Also

DPMSG_SETPLAYERORGROUPNAME, getPlayerFormalName, getPlayerFriendlyName, send, com.ms.directX.DirectXConstants.DPSET_GUARANTEED


setSessionDesc (DirectPlay2 Class)

 Microsoft SDK for Java

setSessionDesc

This method of the DirectPlay2 Class is currently not supported. Changes the properties of the current session. This method works only when called on the computer that is the host of the session.

Syntax

public void setSessionDesc(DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String sessionName, String password, int flags);

Return Value

Returns DPERR_UNSUPPORTED.

Parameters

sessionDesc | The DPSessionDesc object describing the session to be created or joined.
sessionGuid | The GUID of the DirectPlay session of interest.
applicationGuid | The GUID of the application running in the session instance. It uniquely identifies the application so that DirectPlay connects only to other computers running the same application. This member can be set to GUID_NULL to enumerate sessions for any application.
sessionName | Unicode string containing the name of the session. Use this member only if the IdirectPlay2 interface is in use.
password | Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.
flags | No flags are currently used by this method.


stopEnumGroupPlayers (DirectPlay2 Class)

 Microsoft SDK for Java

stopEnumGroupPlayers

This method of the DirectPlay2 Class stops a group players enumeration. You must use this method to stop an enumeration, because, unlike native code that has a boolean return value for enumeration methods, Java enumeration methods return void.

Syntax

public void stopEnumGroupPlayers();

See Also

enumGroupPlayers


stopEnumGroups (DirectPlay2 Class)

 Microsoft SDK for Java

stopEnumGroups

This method of the DirectPlay2 Class stops a group enumeration. You must use this method to stop an enumeration, because, unlike native code that has a boolean return value for enumeration methods, Java enumeration methods return void.

Syntax

public void stopEnumGroups();

See Also

enumGroups


stopEnumPlayers (DirectPlay2 Class)

 Microsoft SDK for Java

stopEnumPlayers

This method of the DirectPlay2 Class stops a players enumeration. You must use this method to stop an enumeration, because, unlike native code that has a boolean return value for enumeration methods, Java enumeration methods return void.

Syntax

public void stopEnumPlayers();

See Also

enumPlayers


stopEnumServiceProviders (DirectPlay2 Class)

 Microsoft SDK for Java

stopEnumServiceProviders

This method of the DirectPlay2 Class stops a service provider enumeration. You must use this method to stop an enumeration, because, unlike native code that has a boolean return value for enumeration methods, Java enumeration methods return void.

Syntax

public void stopEnumServiceProviders();

See Also

enumServiceProviders


stopEnumSessions (DirectPlay2 Class)

 Microsoft SDK for Java

stopEnumSessions

This method of the DirectPlay2 Class stops a session enumeration. You must use this method to stop an enumeration, because, unlike native code that has a boolean return value for enumeration methods, Java enumeration methods return void.

Syntax

public void stopEnumSessions();

See Also

enumSessions


DirectPlayLobby Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectPlayLobby Class

The DirectPlayLobby Class is in the com.ms.directX package.

public class DirectPlayLobby implements IDirectPlayLobby
{
  // Methods
  public DirectPlay2 connect();
  public DirectPlayLobby create(_Guid guid);
  public void createAddress(_Guid spGuid, _Guid addressTypeGuid,
        String addressString, byte[] addressData,
        int[] addressSize);
  public int createAddressSize(_Guid spGuid, _Guid addressTypeGuid,
        String addressString);
  public void enumAddress(IEnumAddressCallback callback,
        byte[] addressData, int addressSize, IUnknown context);
  public void enumAddressTypes(IEnumAddressTypesCallback callback,
        _Guid spGuid, IUnknown context, int flags);
  public void enumLocalApplications(
        IEnumLocalApplicationsCallback callback,
        IUnknown context, int flags);
  public void enumServiceProviders(
        IEnumServiceProvidersCallback callback, IUnknown context);
  public void getConnectionSettings(int applicationId,
        int[] connectionFlags, DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String[] sessionName, String[] password,
        String[] playerShortName, String[] playerLongName,
        _Guid guidSP, byte[] addressData, int[] addressSize);
  public int getConnectionSettingsAddressSize(int applicationId);
  public void receiveLobbyMessage(int applicationId, int[] flags,
        byte[] data, int[] dataSize);
  public void receiveLobbyMessageSize(int applicationId,
        int[] flags, int[] dataSize);
  public void runApplication(int[] applicationId,
        int connectionFlags, DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password,
        String playerShortName, String playerLongName,
        _Guid spGuid, byte[] addressData, int addressSize,
        int receiveEvent);
  public void sendLobbyMessage(int applicationId, byte[] data,
        int dataSize);
  public void setConnectionSettings(int applicationId,
        int connectionFlags, DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password,
        String playerShortName, String playerLongName,
        _Guid spGuid, byte[] addressData, int addressSize);
  public void setLobbyMessageEvent(int applicationId,
        int receiveEvent);
}


Methods (DirectPlayLobby Class)

 Microsoft SDK for Java

DirectPlayLobby Class Methods

The DirectPlayLobby Class contains the following methods:

connect connects an application to a session by using the connection data supplied by the lobby client in the runApplication method or by calling the setConnectionSettings method.
create creates an instance of a IDirectPlayLobby object and attempts to initialize it.
createAddress creates a DirectPlay address when given a service provider-specific network address.
createAddressSize
enumAddress parses out sections from the DirectPlay address buffer.
enumAddressTypes enumerates all the address types that a given service provider needs to build the DirectPlay address.
enumLocalApplications enumerates the applications that are registered with DirectPlay.
enumServiceProviders enumerates the DirectPlayLobby service providers installed on the system.
getConnectionSettings retrieves all the information needed to start and connect an application.
getConnectionSettingsAddressSize retrieves the size of the buffer that contains the connection settings.
receiveLobbyMessage retrieves the message sent between a lobby client application and a DirectPlay application.
receiveLobbyMessageSize retrieves the size of the message sent between a lobby client application and a DirectPlay application.
runApplication runs a DirectPlay application.
sendLobbyMessage sends a message between the application and the lobby client.
setConnectionSettings modifies the connection settings needed to start and connect an application.
setLobbyMessageEvent registers an event that will be set when a lobby message is received.


connect (DirectPlayLobby Class)

 Microsoft SDK for Java

connect

This method of the DirectPlayLobby Class connects an application to a session by using the connection data supplied by the lobby client in the runApplication method or by calling the setConnectionSettings method.

Syntax

public DirectPlay2 connect();

Return Value

Returns a Microsoft® DirectPlay® object with the correct service provider and opens the correct session without prompting the user to complete any dialog boxes.

Remarks

If this method fails with the DPERR_NOTLOBBIED error value, the application should perform the normal steps of calling enumServiceProviders, create, enumSessions and open. If it fails on any other error value, there is a problem connecting to the session.

Before calling this method, the application can examine the connection settings that will be used to start the application by using the getConnectionSettings method. The application can then modify these settings and set them by using the setConnectionSettings method.


create (DirectPlayLobby Class)

 Microsoft SDK for Java

create

This method of the DirectPlayLobby Class creates an instance of a IDirectPlayLobby object and attempts to initialize it.

Syntax

public DirectPlayLobby create(_Guid guid);

Return Value

Returns an DirectPlayLobby object.

Parameters

guid A globally unique identifier (GUID).


createAddress (DirectPlayLobby Class)

 Microsoft SDK for Java

createAddress

This method of the DirectPlayLobby Class creates a DirectPlay address when given a service provider-specific network address. The resulting address contains the GUID of the service provider and data that the service provider can interpret as a network address.

Syntax

public void createAddress(_Guid spGuid, _Guid addressTypeGuid, String addressString, byte[] addressData, int[] addressSize);

Parameters

spGuid | The address of the service provider GUID. (In C++, it is a reference to the GUID.)
addressTypeGuid | The address of a GUID identifying the specific network address type being used.
addressString | A buffer that the constructed DirectPlay address is to be written to.
addressData | A buffer containing the specific network address.
addressSize | The size of the DirectPlay address buffer. Before calling this method, the service provider must initialize addressSize to the size of the buffer. After the method has returned, this parameter will contain the number of bytes written to the address. If the buffer was too small (DPERR_BUFFERTOOSMALL), this parameter will be set to the size required to store the DirectPlay address.


createAddressSize (DirectPlayLobby Class)

 Microsoft SDK for Java

createAddressSize

This is a method of the DirectPlayLobby Class.

Syntax

public int createAddressSize(_Guid spGuid, _Guid addressTypeGuid, String addressString);

Return Value

Returns

Parameters

spGuid | The address of the service provider GUID.
addressTypeGuid | The address of a GUID identifying the specific network address type being used.
addressString | A buffer in which the constructed DirectPlay address is to be written.


enumAddress (DirectPlayLobby Class)

 Microsoft SDK for Java

enumAddress

This method of the DirectPlayLobby Class parses out sections from the DirectPlay address buffer.

Syntax

public void enumAddress(IEnumAddressCallback callback, byte[] addressData, int addressSize, IUnknown context);

Parameters

callback | The EnumAddressCallback function that will be called for each information section in the DirectPlay address.
addressData | The start of the DirectPlay address buffer.
addressSize | The size of the DirectPlay address.
context | The context that will be passed to the callback function.


enumAddressTypes (DirectPlayLobby Class)

 Microsoft SDK for Java

enumAddressTypes

This method of the DirectPlayLobby Class enumerates all the address types that a given service provider needs to build the DirectPlay address.

Syntax

public void enumAddressTypes(IEnumAddressTypesCallback callback, _Guid spGuid, IUnknown context, int flags);

Parameters

callback | The EnumAddressTypeCallback function that will be called for each address type for a service provider. If the service provider takes no address type, the callback will not be called.
spGuid | The GUID of the service provider, whose address types are to be enumerated.
context | The context that will be passed to the callback function.
flags | Reserved; the value must be zero.


enumLocalApplications (DirectPlayLobby Class)

 Microsoft SDK for Java

enumLocalApplications

This method of the DirectPlayLobby Class enumerates the applications that are registered with DirectPlay.

Syntax

public void enumLocalApplications(IEnumLocalApplicationsCallback callback, IUnknown context, int flags);

Parameters

callback | The EnumLocalApplicationsCallback function that will be called for each enumerated application.
context | The context passed to the callback function.
flags | Reserved; must be zero.


enumServiceProviders (DirectPlayLobby Class)

 Microsoft SDK for Java

enumServiceProviders

This method of the DirectPlayLobby Class enumerates the DirectPlayLobby service providers installed on the system.

Syntax

public void enumServiceProviders(IEnumServiceProvidersCallback callback, IUnknown context);

Parameters

callback | The IEnumServiceProvidersCallback interface that contains the callback function to be called with a description of each DirectPlay service provider interface installed on the system.
context | Caller-defined data that is passed to the callback function each time the function is invoked.

Remarks

This method enumerates service providers installed in the system, even though the system might not be enabled to use those service providers. For example, a TAPI service provider can be enumerated, even though the system might not have a modem installed.


getConnectionSettings (DirectPlayLobby Class)

 Microsoft SDK for Java

getConnectionSettings

This method of the DirectPlayLobby Class retrieves all the information needed to start and connect an application. The data returned is the same data that was passed to the runApplication method by the lobby client or set by calling the setConnectionSettings method.

Syntax

public void getConnectionSettings(int applicationId, int[] connectionFlags, DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String[] sessionName, String[] password, String[] playerShortName, String[] playerLongName, _Guid guidSP, byte[] addressData, int[] addressSize);

Parameters

applicationId | The application identifier.
connectionFlags | Indicates how the connection should be made. This can be one of the following: DPLCONNECTION_CREATESESSION Creates a new session as described in the session description. DPLCONNECTION_JOINSESSION Joins the existing session as described in the session description.
sessionDesc | A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this class will be enumerated.
sessionGuid | The GUID of the DirectPlay session of interest. This parameter must be set to NULL unless the DPENUMPLAYERS_SESSION flag is specified.
applicationGuid | The application GUID.
sessionName | The Unicode string containing the name of the session. Use this member only if the IDirectPlay2 interface is in use.
password | Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.
playerShortName | The short name that the player should be created with. This will be the name of the person registered in the lobby. The application can ignore this name.
playerLongName | The long name that the player should be created with.
guidSP | The GUID of the service provider used to connect to the session.
addressData | The information that the service provider needs to connect to a session.
addressSize | The address data size (in bytes).


getConnectionSettingsAddressSize (DirectPlayLobby Class)

 Microsoft SDK for Java

getConnectionSettingsAddressSize

This method of the DirectPlayLobby Class retrieves the size of the buffer that contains the connection settings.

Syntax

public int getConnectionSettingsAddressSize(int applicationId);

Return Value

Returns the buffer size (in bytes).

Parameters

applicationId When called from a lobby client that communicates with several applications, this parameter identifies which application connection settings to retrieve.


receiveLobbyMessage (DirectPlayLobby Class)

 Microsoft SDK for Java

receiveLobbyMessage

This method of the DirectPlayLobby Class retrieves the message sent between a lobby client application and a DirectPlay application. Messages are queued, so there is no danger of losing data if it is not read in time.

Syntax

public void receiveLobbyMessage(int applicationId, int[] flags, byte[] data, int[] dataSize);

Parameters

applicationId | Identifies which application message to retrieve when called from a lobby client (that communicates with several applications). When called from an application (that communicates only with one lobby client), this parameter must be set to zero. This ID number is obtained by using the runApplication method.
flags | Flags indicating what type of message is being returned. This can be DPLAD_SYSTEM.
data | The message to be written. Set this parameter to NULL to request only the size of message. The lpdwDataSize parameter will be set to the minimum size required to hold the message.
dataSize | The size of the buffer before this method is called. After the method returns, this parameter will be set to the size, in bytes, of the message. If the buffer was too small (DPERR_BUFFERTOOSMALL), this parameter will be set to the minimum buffer size required.


receiveLobbyMessageSize (DirectPlayLobby Class)

 Microsoft SDK for Java

receiveLobbyMessageSize

This method of the DirectPlayLobby Class retrieves the size of the message sent between a lobby client application and a DirectPlay application.

Syntax

public void receiveLobbyMessageSize(int applicationId, int[] flags, int[] dataSize);

Parameters

applicationId | Identifies which application's message to retrieve when this method is called from a lobby client (that communicates with several applications).
flags | The flags indicating the type of message being returned.
dataSize | The size of the buffer before this method is called. After the method returns, dataSize will be set to the size (in bytes) of the message. If the buffer was too small (DPERR_BUFFERTOOSMALL), dataSize will be set to the minimum buffer size required.


runApplication (DirectPlayLobby Class)

 Microsoft SDK for Java

runApplication

This method of the DirectPlayLobby Class runs a DirectPlay application.

Syntax

public void runApplication(int[] applicationId, int connectionFlags, DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGud, String sessionName, String password, String playerShortName, String playerLongName, _Guid spGuid, byte[] addressData, int addressSize, int receiveEvent);

Parameters

applicationId | The application identifier.
connectionFlags | Indicates how the connection should be made. This parameter can be one of the following flags: DPLCONNECTION_CREATESESSION Creates a new session as described in the session description. DPLCONNECTION_JOINSESSION Joins the existing session as described in the session description.
sessionDesc | A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this class will be enumerated.
sessionGuid | The GUID of the DirectPlay session of interest. This parameter must be set to NULL unless the DPENUMPLAYERS_SESSION flag is specified.
applicationGuid | The application GUID.
sessionName | The Unicode string containing the name of the session. Use this member only if the IDirectPlay2 interface is in use.
password | The Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.
playerShortName | The short name that the player should be created with. This will be the name of the person registered in the lobby. The application can ignore this name.
playerLongName | The long name that the player should be created with.
spGuid | The GUID of the service provider used to connect to the session.
addressData | The information that the service provider needs to connect to a session.
addressSize | Address data size (in bytes).
receiveEvent | The event handle set when a message is received.


sendLobbyMessage (DirectPlayLobby Class)

 Microsoft SDK for Java

sendLobbyMessage

This method of the DirectPlayLobby Class sends a message between the application and the lobby client.

Syntax

public void sendLobbyMessage(int applicationId, byte[] data, int dataSize);

Parameters

applicationId | Identifies which application to send a message to when called from a lobby client (that communicates with several applications). When called from an application (that communicates with only one lobby client), this parameter must be zero. This ID is obtained by using the runApplication method.
data | The message to send.
dataSize | The buffer size (in bytes).


setConnectionSettings (DirectPlayLobby Class)

 Microsoft SDK for Java

setConnectionSettings

This method of the DirectPlayLobby Class modifies the connection settings needed to start and connect an application.

Syntax

public void setConnectionSettings(int applicationId, int connectionFlags, DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String sesionName, String password, String playerShortName, String playerLongName, _Guid spGuid, byte[] addressData, int addressSize);

Parameters

applicationId | When this method is called from a lobby client that communicates with several applications, applicationId identifies which application connection settings to retrieve.
connectionFlags | Indicates how the connection should be made. This parameter can be one of the following flags: DPLCONNECTION_CREATESESSION Creates a new session as described in the session description. DPLCONNECTION_JOINSESSION Joins the existing session as described in the session description.
sessionDesc | A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this class will be enumerated.
sessionGuid | The GUID of the DirectPlay session of interest. This parameter must be set to NULL unless the DPENUMPLAYERS_SESSION flag is specified.
applicationGuid | The application GUID.
sessionName | The Unicode string containing the name of the session. Use this member only if the IDirectPlay2 interface is in use.
password | The Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.
playerShortName | The short name that the player should be created with. This will be the name of the person registered in the lobby. The application can ignore this name.
playerLongName | The long name that the player should be created with.
spGuid | The GUID of the service provider used to connect to the session.
addressData | The information that the service provider needs to connect to a session.
addressSize | The address data size (in bytes).


setLobbyMessageEvent (DirectPlayLobby Class)

 Microsoft SDK for Java

setLobbyMessageEvent

This method of the DirectPlayLobby Class registers an event that will be set when a lobby message is received. The application must call this method if it needs to synchronize with messages. The lobby client can call this method to change the events specified in the call to the runApplication method.

Syntax

public void setLobbyMessageEvent(int applicationId, int receiveEvent);

Parameters

applicationId | Identifies which application the event is associated with when called from a lobby client that communicates with several applications. When called from an application that communicates with only one lobby client, this parameter must be zero. This ID number is obtained from runApplication.
receiveEvent | The event handle set when a message is received.


DirectSound Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectSound Class

Applications use the methods of the DirectSound Class of the com.ms.directX package to create DirectSound objects and set up the environment.

public class DirectSound implements IDirectSound
{
  // Methods
  public void compact();
  public DirectSoundBuffer createSoundBuffer(
        DSBufferDesc bufferDesc, byte[] format);
  public DirectSoundBuffer createSoundBuffer(
        DSBufferDesc bufferDesc, WaveFormatEx format);
  public DirectSoundBuffer duplicateSoundBuffer(
        DirectSoundBuffer original);
  public void enumSoundDrivers(IEnumSoundDriversCallback callback,
        IUnknown context);
  public void getCaps(DSCaps caps);
  public void getSpeakerConfig(int[] speakerConfig);
  public void initialize(_Guid guid);
  public void setCooperativeLevel(int hwnd, int level);
  public void setSpeakerConfig(int speakerConfig);
}


Methods (DirectSound Class)

 Microsoft SDK for Java

DirectSound Class Methods

The DirectSound Class contains the following methods:

compact moves the unused portions of onboard sound memory, if any, to a contiguous block so that the largest portion of free memory will be available.
createSoundBuffer creates a DirectSoundBuffer object to hold a sequence of audio samples.
duplicateSoundBuffer creates a new DirectSoundBuffer object that uses the same buffer memory as the original object.
enumSoundDrivers enumerates the DirectSound drivers installed in the system.
getCaps retrieves the capabilities of the hardware device that is represented by the DirectSound object.
getSpeakerConfig retrieves the speaker configuration specified for this DirectSound object.
initialize initializes the DirectSound object if it has not yet been initialized.
setCooperativeLevel sets the cooperative level of the application for this sound device.
setSpeakerConfig specifies the speaker configuration for the DirectSound object.


compact (DirectSound Class)

 Microsoft SDK for Java

compact

This method of the DirectSound Class moves the unused portions of onboard sound memory, if any, to a contiguous block so that the largest portion of free memory will be available.

Syntax

public void compact();

Remarks

If the application calls this method, it must have exclusive cooperation with the DirectSound object. (To get exclusive access, specify DSSCL_EXCLUSIVE in a call to the setCooperativeLevel method.) This method will fail if any operations are in progress.

See Also

setCooperativeLevel


createSoundBuffer (DirectSound Class)

 Microsoft SDK for Java

createSoundBuffer

The createSoundBuffer method of the DirectSound Class contains the following signatures:

createSoundBuffer(DSBufferDesc bufferDesc, byte[] format)
createSoundBuffer(DSBufferDesc bufferDesc, WaveFormatEx format)

createSoundBuffer(DSBufferDesc bufferDesc, byte[] format)

Creates a DirectSoundBuffer object to hold a sequence of audio samples.

Syntax

public DirectSoundBuffer createSoundBuffer(DSBufferDesc bufferDesc, byte[] format);

Return Value

Returns the DirectSoundBuffer object if successful; null otherwise.

Parameters

bufferDesc | A DSBufferDesc object that contains the description of the sound buffer to be created.
format | Array variable that specifies the wave format for the sound buffer.

Remarks

Before it can play any sound buffers, the application must specify a cooperative level for a DirectSound object by using the setCooperativeLevel method.

The bufferDesc parameter is an object that describes the type of buffer desired, including format, size, and capabilities. The application must specify the needed capabilities, or they will not be available. For example, if the application creates a DirectSoundBuffer object without specifying the DSBCAPS_CTRLFREQUENCY flag, any call to setFrequency will fail.

The DSBCAPS_STATIC flag can also be specified, in which case DirectSound stores the buffer in onboard memory, if available, in order to take advantage of hardware mixing. To force the buffer to use either hardware or software mixing, use the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flags.

See Also

com.ms.directX.DSBufferDesc, duplicateSoundBuffer, setCooperativeLevel

createSoundBuffer(DSBufferDesc bufferDesc, WaveFormatEx format)

Creates a DirectSoundBuffer object to hold a sequence of audio samples.

Syntax

public DirectSoundBuffer createSoundBuffer(DSBufferDesc bufferDesc, WaveFormatEx format);

Return Value

Returns the DirectSoundBuffer object if successful; null otherwise.

Parameters

bufferDesc | A DSBufferDesc object that contains the description of the sound buffer to be created.
format | A WaveFormatEx object that specifies the wave format for the sound buffer.

Remarks

Before it can play any sound buffers, the application must specify a cooperative level for a DirectSound object by using the setCooperativeLevel method.

The bufferDesc parameter is an object that describes the type of buffer desired, including format, size, and capabilities. The application must specify the needed capabilities, or they will not be available. For example, if the application creates a DirectSoundBuffer object without specifying the DSBCAPS_CTRLFREQUENCY flag, any call to setFrequency will fail.

The DSBCAPS_STATIC flag can also be specified, in which case DirectSound stores the buffer in onboard memory, if available, in order to take advantage of hardware mixing. To force the buffer to use either hardware or software mixing, use the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flags.

See Also

com.ms.directX.DSBufferDesc, duplicateSoundBuffer, setCooperativeLevel


duplicateSoundBuffer (DirectSound Class)

 Microsoft SDK for Java

duplicateSoundBuffer

This method of the DirectSound Class creates a new DirectSoundBuffer object that uses the same buffer memory as the original object.

Syntax

public DirectSoundBuffer duplicateSoundBuffer(DirectSoundBuffer original);

Return Value

Returns the DirectSoundBuffer object if successful; null otherwise.

Parameters

original The DirectSoundBuffer object to be duplicated.

Remarks

The new object can be used just like the original.

Initially, the duplicate buffer will have the same parameters as the original buffer. However, the application can change the parameters of each buffer independently, and each can be played or stopped without affecting the other.

If data in the buffer is changed through one object, the change will be reflected in the other object since the buffer memory is shared.

The buffer memory will be released when the last object referencing it is released.

See Also

createSoundBuffer


enumSoundDrivers (DirectSound Class)

 Microsoft SDK for Java

enumSoundDrivers

This method of the DirectSound Class enumerates the DirectSound drivers installed in the system.

Syntax

public void enumSoundDrivers(IEnumSoundDriversCallback callback, IUnknown context);

Parameters

callback | The IEnumSoundDriversCallback interface that contains the callback function to be called for each DirectSound object installed in the system.
context | User-defined context passed to the enumeration callback function every time that function is called.


getCaps (DirectSound Class)

 Microsoft SDK for Java

getCaps

This method of the DirectSound Class retrieves the capabilities of the hardware device that is represented by the DirectSound object.

Syntax

public void getCaps(DSCaps caps);

Parameters

caps The DSCaps object that receives the capabilities of this sound device.

Remarks

Information retrieved in the DSCaps object describes the maximum capabilities of the sound device and those currently available, such as the number of hardware mixing channels and the amount of onboard sound memory. This information can be used to fine-tune performance and optimize resource allocation.

Because of resource sharing requirements, the maximum capabilities in one area might only be available at the cost of another area. For example, the maximum number of hardware-mixed streaming sound buffers might only be available if there are no hardware static sound buffers.

See Also

directSoundCreate, com.ms.directX.DSCaps


getSpeakerConfig (DirectSound Class)

 Microsoft SDK for Java

getSpeakerConfig

This method of the DirectSound Class retrieves the speaker configuration specified for this DirectSound object.

Syntax

public void getSpeakerConfig(int[] speakerConfig);

Parameters

speakerConfig Array variable that receives the speaker configuration for this DirectSound object. The speaker configuration is specified with one value of DSSPEAKER_ type.

See Also

setSpeakerConfig


initialize (DirectSound Class)

 Microsoft SDK for Java

initialize

This method of the DirectSound Class initializes the DirectSound object if it has not yet been initialized.

Syntax

public void initialize(_Guid guid);

Parameters

guid The GUID specifying the sound driver for this DirectSound object to bind to, or null to select the primary sound driver.


setCooperativeLevel (DirectSound Class)

 Microsoft SDK for Java

setCooperativeLevel

This method of the DirectSound Class sets the cooperative level of the application for this sound device.

Syntax

public void setCooperativeLevel(int hwnd, int level);

Parameters

hwnd | Window handle for the application.
level | One value of DSSCL_ type, specifying the requested priority level.

Remarks

The application must set the cooperative level by calling this method before its buffers can be played. The recommended cooperative level is DSSCL_NORMAL; use other priority levels when necessary.

You must call the show() or addNotify() method before calling setCooperativeLevel.

Example

class Test implements DirectXConstants{

    void run(){
                  DirectSound ds = new DirectSound();
                  this.show();
                  ds.setCooperativeLevel(this,DSSCL_EXCLUSIVE);
              }
}

See Also

compact


setSpeakerConfig (DirectSound Class)

 Microsoft SDK for Java

setSpeakerConfig

This method of the DirectSound Class specifies the speaker configuration for the DirectSound object.

Syntax

public void setSpeakerConfig(int speakerConfig);

Parameters

speakerConfig One value of DSSPEAKER_ type, specifying the speaker configuration of the specified DirectSound object.

See Also

getSpeakerConfig


DirectSound3dBuffer Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectSound3dBuffer Class

The DirectSound3dBuffer Class is in the com.ms.directX package.

public class DirectSound3dBuffer implements
            IDirectSound3dBuffer
{
  // Methods
  public void getAllParameters(DS3dBuffer buffer);
  public void getConeAngles(int[] inCone, int[] outCone);
  public void getConeOrientation(D3dVector orientation);
  public void getConeOutsideVolume(int[] coneOutsideVolume);
  public void getMaxDistance(float[] maxDistance);
  public void getMinDistance(float[] minDistance);
  public void getMode(int[] mode);
  public void getPosition(D3dVector position);
  public void getVelocity(D3dVector velocity);
  public void setAllParameters(DS3dBuffer buffer, int applyFlag);
  public void setConeAngles(int inCone, int outCone, int applyFlag);
  public void setConeOrientation(float x, float y, float z,
        int applyFlag);
  public void setConeOutsideVolume(int coneOutsideVolume,
        int applyFlag);
  public void setMaxDistance(float maxDistance, int applyFlag);
  public void setMinDistance(float minDistance, int applyFlag);
  public void setMode(int mode, int applyFlag);
  public void setPosition(float x, float y, float z, int applyFlag);
  public void setVelocity(float x, float y, float z, int applyFlag);
}


Methods (DirectSound3dBuffer Class)

 Microsoft SDK for Java

DirectSound3dBuffer Class Methods

The DirectSound3dBuffer Class contains the following methods:

getAllParameters retrieves information that describes the 3D characteristics of a sound buffer at a given point in time.
getConeAngles retrieves the inside and outside angles of the sound projection cone for this sound buffer.
getConeOrientation retrieves the orientation of the sound projection cone for this sound buffer.
getConeOutsideVolume retrieves the current cone outside volume for this sound buffer.
getMaxDistance retrieves the current maximum distance for this sound buffer.
getMinDistance retrieves the current minimum distance for this sound buffer.
getMode retrieves the current operation mode for 3D sound processing.
getPosition retrieves the sound buffer's current position, in distance units.
getVelocity retrieves the current velocity for this sound buffer.
setAllParameters sets all 3D sound buffer parameters from a given DS3dBuffer that describes all aspects of the sound buffer at a moment in time.
setConeAngles sets the inside and outside angles of the sound projection cone for this sound buffer.
setConeOrientation sets the orientation of the sound projection cone for this sound buffer.
setConeOutsideVolume sets the current cone outside volume for this sound buffer.
setMaxDistance sets the current maximum distance value.
setMinDistance sets the current minimum distance value.
setMode sets the operation mode for 3D sound processing.
setPosition sets the sound buffer's current position, in distance units.
setVelocity sets the sound buffer's current velocity.


getAllParameters (DirectSound3dBuffer Class)

 Microsoft SDK for Java

getAllParameters

This method of the DirectSound3dBuffer Class retrieves information that describes the 3D characteristics of a sound buffer at a given point in time.

Syntax

public void getAllParameters(DS3dBuffer buffer);

Parameters

buffer The DS3dBuffer that will contain the information describing the 3D characteristics of the sound buffer.


getConeAngles (DirectSound3dBuffer Class)

 Microsoft SDK for Java

getConeAngles

This method of the DirectSound3dBuffer Class retrieves the inside and outside angles of the sound projection cone for this sound buffer.

Syntax

public void getConeAngles(int[] inCone, int[] outCone);

Parameters

inCone | The inside angles of the sound projection cone.
outCone | The outside angles of the sound projection cone.


getConeOrientation (DirectSound3dBuffer Class)

 Microsoft SDK for Java

getConeOrientation

This method of the DirectSound3dBuffer Class retrieves the orientation of the sound projection cone for this sound buffer.

Syntax

public void getConeOrientation(D3dVector orientation);

Parameters

orientation The D3dVector that will contain the current orientation of the sound projection cone. The vector information represents the center of the sound cone.

Remarks

This method has no effect unless the cone angle and cone volume factor have also been set. The default value is (0,0,1).


getConeOutsideVolume (DirectSound3dBuffer Class)

 Microsoft SDK for Java

getConeOutsideVolume

This method of the DirectSound3dBuffer Class retrieves the current cone outside volume for this sound buffer.

Syntax

public void getConeOutsideVolume(int[] coneOutsideVolume);

Parameters

coneOutsideVolume The current cone outside volume for this buffer.

Remarks

Volume levels are represented by attenuation. Allowable values are between 0 (no attenuation) and -10,000 (silence). Amplification is not currently supported by DirectSound.


getMaxDistance (DirectSound3dBuffer Class)

 Microsoft SDK for Java

getMaxDistance

This method of the DirectSound3dBuffer Class retrieves the current maximum distance for this sound buffer.

Syntax

public void getMaxDistance(float[] maxDistance);

Parameters

maxDistance The current maximum distance setting.

Remarks

The maximum distance value is infinite by default.


getMinDistance (DirectSound3dBuffer Class)

 Microsoft SDK for Java

getMinDistance

This method of the DirectSound3dBuffer Class retrieves the current minimum distance for this sound buffer.

Syntax

public void getMinDistance(float[] minDistance);

Parameters

minDistance The current minimum distance setting.

Remarks

The minimum distance value is 1.0 (corresponding to 1.0 meter at the default distance factor of 1.0 m per unit) by default.


getMode (DirectSound3dBuffer Class)

 Microsoft SDK for Java

getMode

This method of the DirectSound3dBuffer Class retrieves the current operation mode for 3D sound processing.

Syntax

public void getMode(int[] mode);

Parameters

mode The current mode setting. This value will be one of the following:

DS3DMODE_DISABLE
DS3DMODE_HEADRELATIVE
DS3DMODE_NORMAL


getPosition (DirectSound3dBuffer Class)

 Microsoft SDK for Java

getPosition

This method of the DirectSound3dBuffer Class retrieves the sound buffer's current position, in distance units. Distance units are meters by default, but the units can be changed by using the setDistanceFactor method.

Syntax

public void getPosition(D3dVector position);

Parameters

position The D3dVector that will contain the current position of the sound buffer.


getVelocity (DirectSound3dBuffer Class)

 Microsoft SDK for Java

getVelocity

This method of the DirectSound3dBuffer Class retrieves the current velocity for this sound buffer.

Syntax

public void getVelocity(D3dVector velocity);

Parameters

velocity The D3dVector that will contain the sound buffer's current velocity.

Remarks

Velocity is used for Doppler effects only. It does not actually move the buffer.


setAllParameters (DirectSound3dBuffer Class)

 Microsoft SDK for Java

setAllParameters

This method of the DirectSound3dBuffer Class sets all 3D sound buffer parameters from a given DS3dBuffer that describes all aspects of the sound buffer at a moment in time.

Syntax

public void setAllParameters(DS3dBuffer buffer, int applyFlag);

Parameters

buffer | The DS3dBuffer containing the information that describes the 3D characteristics of the sound buffer.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE


setConeAngles (DirectSound3dBuffer Class)

 Microsoft SDK for Java

setConeAngles

This method of the DirectSound3dBuffer Class sets the inside and outside angles of the sound projection cone for this sound buffer.

Syntax

public void setConeAngles(int inCone, int outCone, int applyFlag);

Parameters

inCone | Inside angle of the sound projection cone.
outCone | Outside angle of the sound projection cone.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE

Remarks

Each angle must be in the range of 0 degrees (no cone) to 360 degrees (the full sphere). The default value is 360. For additional information see, Sound Projection Cones.


setConeOrientation (DirectSound3dBuffer Class)

 Microsoft SDK for Java

setConeOrientation

This method of the DirectSound3dBuffer Class sets the orientation of the sound projection cone for this sound buffer. This method has no effect unless the cone angle and cone volume factor have also been set.

Syntax

public void setConeOrientation(float x, float y, float z, int applyFlag);

Parameters

x | The x-coordinate of the new sound cone orientation vector.
y | The y-coordinate of the new sound cone orientation vector.
z | The z-coordinate of the new sound cone orientation vector.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE

Remarks

The vector information in the orientation parameter of the getConeOrientation method represents the center of the sound cone. The default value is (0,0,1).


setConeOutsideVolume (DirectSound3dBuffer Class)

 Microsoft SDK for Java

setConeOutsideVolume

This method of the DirectSound3dBuffer Class sets the current cone outside volume for this sound buffer.

Syntax

public void setConeOutsideVolume(int coneOutsideVolume, int applyFlag);

Parameters

coneOutsideVolume | Cone outside volume for this sound buffer, in hundredths of decibels. Allowable values are between 0 (no attenuation) and -10,000 (silence).
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE

Remarks

Volume levels are represented by attenuation. Amplification is not currently supported by DirectSound.


setMaxDistance (DirectSound3dBuffer Class)

 Microsoft SDK for Java

setMaxDistance

This method of the DirectSound3dBuffer Class sets the current maximum distance value.

Syntax

public void setMaxDistance(float maxDistance, int applyFlag);

Parameters

maxDistance | New maximum distance value.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE

Remarks

The maximum distance value is infinite by default.


setMinDistance (DirectSound3dBuffer Class)

 Microsoft SDK for Java

setMinDistance

This method of the DirectSound3dBuffer Class sets the current minimum distance value.

Syntax

public void setMinDistance(float minDistance, int applyFlag);

Parameters

minDistance | New minimum distance value.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE

Remarks

The minimum distance value is 1.0 (corresponding to 1.0 meter at the default distance factor of 1.0 m per unit) by default.


setMode (DirectSound3dBuffer Class)

 Microsoft SDK for Java

setMode

This method of the DirectSound3dBuffer Class sets the operation mode for 3D sound processing.

Syntax

public void setMode(int mode, int applyFlag);

Parameters

mode Flag specifying the 3D sound processing mode to be set.

DS3DMODE_DISABLE

Processing of 3D sound is disabled. The sound seems to originate from the center of the listener's head.

DS3DMODE_HEADRELATIVE

Sound parameters (position, velocity, and orientation) are relative to the listener's parameters. In this mode, the absolute parameters of the sound are updated automatically as the listener's parameters change, so that the relative parameters remain constant.

DS3DMODE_NORMAL

Normal processing. This is the default mode.
applyFlag Value indicating when the setting should be applied. This value must be one of the following:

DS3D_DEFERRED
DS3D_IMMEDIATE


setPosition (DirectSound3dBuffer Class)

 Microsoft SDK for Java

setPosition

This method of the DirectSound3dBuffer Class sets the sound buffer's current position, in distance units. Distance units are meters by default, but the units can be changed by using the setDistanceFactor method.

Syntax

public void setPosition(float x, float y, float z, int applyFlag);

Parameters

x | The x-coordinate of the new position vector.
y | The y-coordinate of the new position vector.
z | The z-coordinate of the new position vector.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE


setVelocity (DirectSound3dBuffer Class)

 Microsoft SDK for Java

setVelocity

This method of the DirectSound3dBuffer Class sets the sound buffer's current velocity.

Syntax

public void setVelocity(float x, float y, float z, int applyFlag);

Parameters

x | The x-coordinate of the new velocity vector.
y | The y-coordinate of the new velocity vector.
z | The z-coordinate of the new velocity vector.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE

Remarks

Velocity is used for Doppler effects only. It does not actually move the buffer.


DirectSound3dListener Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectSound3dListener Class

The DirectSound3dListener Class is in the com.ms.directX package.

public class DirectSound3dListener implements
            IDirectSound3dListener
{
  // Methods
  public void commitDeferredSettings();
  public void getAllParameters(DS3dListener listener);
  public void getDistanceFactor(float[] distanceFactor);
  public void getDopplerFactor(float[] dopplerFactor);
  public void getOrientation(D3dVector orientFront,
        D3dVector orientTop);
  public void getPosition(D3dVector position);
  public void getRolloffFactor(float[] rolloffFactor);
  public void getVelocity(D3dVector velocity);
  public void setAllParameters(DS3dListener listener,
        int applyFlag);
  public void setDistanceFactor(float distanceFactor,
        int applyFlag);
  public void setDopplerFactor(float dopplerFactor, int applyFlag);
  public void setOrientation(float xFront, float yFront,
        float zFront, float xTop, float yTop, float zTop,
        int applyFlag);
  public void setPosition(float x, float y, float z, int applyFlag);
  public void setRolloffFactor(float rolloffFactor, int applyFlag);
  public void setVelocity(float x, float y, float z, int applyFlag);
}


Methods (DirectSound3dListener Class)

 Microsoft SDK for Java

DirectSound3dListener Class Methods

The DirectSound3dListener Class contains the following methods:

commitDeferredSettings commits any deferred settings made since the last call to this method.
getAllParameters retrieves information that describes the current state of the 3D world and listener.
getDistanceFactor retrieves the current distance factor.
getDopplerFactor retrieves the current Doppler effect factor.
getOrientation retrieves the listener's current orientation in vectors: a front vector and a top vector.
getPosition retrieves the listener's current position in distance units.
getRolloffFactor retrieves the current rolloff factor.
getVelocity retrieves the listener's current velocity.
setAllParameters sets all 3D listener parameters from a given DS3dListener class that describes all aspects of the 3D listener at a moment in time.
setDistanceFactor sets the current distance factor.
setDopplerFactor sets the current Doppler effect factor.
setOrientation sets the listeners orientation, given a front vector and a top vector.
setPosition retrieves the listener's current position in distance units.
setRolloffFactor sets the rolloff factor.
setVelocity sets the listener's velocity.


commitDeferredSettings (DirectSound3dListener Class)

 Microsoft SDK for Java

commitDeferredSettings

This method of the DirectSound3dListener Class commits any deferred settings made since the last call to this method.

Syntax

public void commitDeferredSettings();


getAllParameters (DirectSound3dListener Class)

 Microsoft SDK for Java

getAllParameters

This method of the DirectSound3dListener Class retrieves information that describes the current state of the 3D world and listener.

Syntax

public void getAllParameters(DS3dListener listener);

Parameters

listener The DS3dListener object that contains the current state of the 3D world and listener.


getDistanceFactor (DirectSound3dListener Class)

 Microsoft SDK for Java

getDistanceFactor

This method of the DirectSound3dListener Class retrieves the current distance factor.

Syntax

public void getDistanceFactor(float[] distanceFactor);

Parameters

distanceFactor The array that will contain the current distance factor values.


getDopplerFactor (DirectSound3dListener Class)

 Microsoft SDK for Java

getDopplerFactor

This method of the DirectSound3dListener Class retrieves the current Doppler effect factor.

Syntax

public void getDopplerFactor(float[] dopplerFactor);

Parameters

dopplerFactor The array that will contain the current Doppler factor values.

Remarks

This Doppler factor has a range of 0 (no Doppler effects) to 10.0 (10 times the Doppler effects found in the physical world). The default value is DS3D_DEFAULTDOPPLERFACTOR (1.0).


getOrientation (DirectSound3dListener Class)

 Microsoft SDK for Java

getOrientation

This method of the DirectSound3dListener Class retrieves the listener's current orientation in vectors: a front vector and a top vector.

Syntax

public void getOrientation(D3dVector orientFront, D3dVector orientTop);

Parameters

orientFront | The D3dVector object that will contain the listener's front orientation vector.
orientTop | The D3dVector object that will contain the listener's top orientation vector.

Remarks

The front vector points in the direction of the listener's nose, and the top vector points out the top of the listener's head. By default, the front vector is (0,0,1.0) and the top vector is (0,1.0,0).


getPosition (DirectSound3dListener Class)

 Microsoft SDK for Java

getPosition

This method of the DirectSound3dListener Class retrieves the listener's current position in distance units. By default, these units are meters, but this can be changed by calling the setDistanceFactor method.

Syntax

public void getPosition(D3dVector position);

Parameters

position The D3dVector that will contain the listener's position vector.


getRolloffFactor (DirectSound3dListener Class)

 Microsoft SDK for Java

getRolloffFactor

This method of the DirectSound3dListener Class retrieves the current rolloff factor.

Syntax

public void getRolloffFactor(float[] rolloffFactor);

Parameters

rolloffFactor Tha array that will contain the current rolloff factor values.

Remarks

The default value is DS3D_DEFAULTROLLOFFFACTOR (1.0). For additional information about the rolloff factor, see Rolloff Factor.


getVelocity (DirectSound3dListener Class)

 Microsoft SDK for Java

getVelocity

This method of the DirectSound3dListener Class retrieves the listener's current velocity.

Syntax

public void getVelocity(D3dVector velocity);

Parameters

velocity The D3dVector that will contain the listener's current velocity.

Remarks

Velocity is used only for Doppler effects. It does not actually move the listener. To change the listener's position, use the setPosition method. The default velocity is (0,0,0).


setAllParameters (DirectSound3dListener Class)

 Microsoft SDK for Java

setAllParameters

This method of the DirectSound3dListener Class sets all 3D listener parameters from a given DS3dListener class that describes all aspects of the 3D listener at a moment in time.

Syntax

public void setAllParameters(DS3dListener listener, int applyFlag);

Parameters

listener | Address of a DS3dListener class that contains information describing all current 3D listener parameters.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE


setDistanceFactor (DirectSound3dListener Class)

 Microsoft SDK for Java

setDistanceFactor

This method of the DirectSound3dListener Class sets the current distance factor.

Syntax

public void setDistanceFactor(float distanceFactor, int applyFlag);

Parameters

distanceFactor | New distance factor.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE


setDopplerFactor (DirectSound3dListener Class)

 Microsoft SDK for Java

setDopplerFactor

This method of the DirectSound3dListener Class sets the current Doppler effect factor.

Syntax

public void setDopplerFactor(float dopplerFactor, int applyFlag);

Parameters

dopplerFactor | New Doppler factor value.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE

Remarks

This Doppler factor has a range of 0 (no Doppler effects) to 10.0 (10 times the Doppler effects found in the physical world). The default value is DS3D_DEFAULTDOPPLERFACTOR (1.0).


setOrientation (DirectSound3dListener Class)

 Microsoft SDK for Java

setOrientation

This method of the DirectSound3dListener Class sets the listeners orientation, given a front vector and a top vector.

Syntax

public void setOrientation(float xFront, float yFront, float zFront, float xTop, float yTop, float zTop, int applyFlag);

Parameters

xFront | The x component of the front vector.
yFront | The y component of the front vector.
zFront | The z component of the front vector.
xTop | The x component of the top vector.
yTop | The y component of the top vector.
ztop | The x component of the top vector.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE

Remarks

The front vector points in the direction of the listener's nose, and the top vector points out the top of the listener's head.


setPosition (DirectSound3dListener Class)

 Microsoft SDK for Java

setPosition

This method of the DirectSound3dListener Class retrieves the listener's current position in distance units. By default, these units are meters, but this can be changed by calling the DirectSound3dListener.setDistanceFactor method.

Syntax

public void setPosition(float x, float y, float z, int applyFlag);

Parameters

y | The x component of the vector that will contain the listener's position.
y | The y component of the vector that will contain the listener's position.
z | The z component of the vector that will contain the listener's position.
applyFlag | Flag values.


setRolloffFactor (DirectSound3dListener Class)

 Microsoft SDK for Java

setRolloffFactor

This method of the DirectSound3dListener Class sets the rolloff factor.

Syntax

public void setRolloffFactor(float rolloffFactor, int applyFlag);

Parameters

rolloffFactor | New rolloff factor.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE

Remarks

The default value is DS3D_DEFAULTROLLOFFFACTOR (1.0). For additional information about the rolloff factor, see Rolloff Factor.


setVelocity (DirectSound3dListener Class)

 Microsoft SDK for Java

setVelocity

This method of the DirectSound3dListener Class sets the listener's velocity.

Syntax

public void setVelocity(float x, float y, float z, int applyFlag);

Parameters

x | The x-coordinate of the listener's new velocity vector.
y | The y-coordinate of the listener's new velocity vector.
z | The z-coordinate of the listener's new velocity vector.
applyFlag | Value indicating when the setting should be applied. This value must be one of the following: DS3D_DEFERRED DS3D_IMMEDIATE

Remarks

Velocity is used only for Doppler effects. It does not actually move the listener. To change the listener's position, use the setPosition method. The default velocity is (0,0,0).


DirectSoundBuffer Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectSoundBuffer Class

Applications use the methods of the DirectSoundBuffer Class of the com.ms.directX package to create DirectSoundBuffer objects and set up the environment.

public class DirectSoundBuffer implements IDirectSoundBuffer
{
  // Methods
  public DirectSound3dBuffer get3dBuffer();
  public DirectSound3dListener get3dListener();
  public void getCaps(DSBCaps caps);
  public void getCurrentPosition(DSCursors cursors);
  public void getFormat(byte[] format, int size);
  public WaveFormatEx getFormat();
  public int getFormatSize();
  public int getFrequency();
  public int getPan();
  public int getStatus();
  public int getVolume();
  public void play(int flags);
  public void restore();
  public void setCurrentPosition(int newPosition);
  public void setFormat(byte[] format);
  public void setFormat(WaveFormatEx format);
  public void setFrequency(int frequency);
  public void setPan(int pan);
  public void setVolume(int volume);
  public void stop();
  public void transferToSoundBuffer(DSResourceDesc resourceDesc,
        int flags);
  public void writeBuffer(int start, int size, byte[] buffer,
        int flags);
}

Note This class does not provide an initialize method. Use the DirectSound.createSoundBuffer method to create and initialize DirectSoundBuffer objects.


Methods (DirectSoundBuffer Class)

 Microsoft SDK for Java

DirectSoundBuffer Class Methods

The DirectSoundBuffer Class contains the following methods:

get3dBuffer retrieves a DirectSound3dBuffer object for the DirectSound buffer.
get3dListener retrieves a DirectSound3dListener object for the DirectSound buffer.
getCaps retrieves the capabilities of the DirectSoundBuffer object.
getCurrentPosition retrieves the current position of the play and write cursors in the sound buffer.
getFormat retrieves a description of the format of the sound data in the buffer.
getFormatSize retrieves the size of the format information.
getFrequency retrieves the frequency, in samples per second, at which the buffer is being played.
getPan retrieves a variable that represents the relative volume between the left and right audio channels.
getStatus retrieves the current status of the sound buffer.
getVolume retrieves the current volume for this sound buffer.
play causes the sound buffer to play from the current position.
restore restores the memory allocation for a lost sound buffer for the specified DirectSoundBuffer object.
setCurrentPosition moves the current play cursor for secondary sound buffers.
setFormat sets the format of the primary sound buffer for the application.
setFrequency sets the frequency at which the audio samples are played.
setPan specifies the relative volume between the left and right channels.
setVolume changes the volume of a sound buffer.
stop causes the sound buffer to stop playing.
transferToSoundBuffer transfers the wave data from the given resource to the start of the sound buffer.
writeBuffer writes the contents of a buffer to the given position in the sound buffer.


get3dBuffer (DirectSoundBuffer Class)

 Microsoft SDK for Java

get3dBuffer

This method of the DirectSoundBuffer Class retrieves a DirectSound3dBuffer object for the DirectSound buffer.

Syntax

public DirectSound3dBuffer get3dBuffer();


get3dListener (DirectSoundBuffer Class)

 Microsoft SDK for Java

get3dListener

This method of the DirectSoundBuffer Class retrieves a DirectSound3dListener object for the DirectSound buffer.

Syntax

public DirectSound3dListener get3dListener();


getCaps (DirectSoundBuffer Class)

 Microsoft SDK for Java

getCaps

This method of the DirectSoundBuffer Class retrieves the capabilities of the DirectSoundBuffer object.

Syntax

public void getCaps(DSBCaps caps);

Parameters

caps A DSBCaps object that receives the capabilities of this sound buffer.

Remarks

The DSBCaps object contains similar information to the DSBufferDesc object passed to the createSoundBuffer method, with some additional information. This additional information can include the location of the buffer, either in hardware or software, and some cost measures. Examples of cost measures include the time it takes to download to a hardware buffer and the processing overhead required to mix and play the buffer when it is in the system memory.

The flags specified in the flags field of the DSBCaps object are the same flags used by the DSBufferDesc object. The only difference is that in the DSBCaps object, either DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE will be specified according to the location of the buffer memory. In the DSBufferDesc object, these flags are optional and, depending on which flag is specified, force the buffer to be located in either hardware or software.

See Also

com.ms.directX.DirectSound, com.ms.directX.DSBCaps, com.ms.directX.DSBufferDesc


getCurrentPosition (DirectSoundBuffer Class)

 Microsoft SDK for Java

getCurrentPosition

This method of the DirectSoundBuffer Class retrieves the current position of the play and write cursors in the sound buffer.

Syntax

public void getCurrentPosition(DSCursors cursors);

Parameters

cursors A DSCursors object that receives the current play and write positions in the DirectSoundBuffer object. These positions are offsets within the sound buffer and are specified in bytes.

Remarks

The write cursor indicates the position at which it is safe to write new data into the buffer. The write cursor always leads the play cursor, typically by about 15 milliseconds worth of audio data.

It is always safe to change data that is behind the play position.

See Also

setCurrentPosition


getFormat (DirectSoundBuffer Class)

 Microsoft SDK for Java

getFormat

The getFormat method of the DirectSoundBuffer Class contains the following signatures:

getFormat(byte[] format, int size)
getFormat()

getFormat(byte[] format, int size)

Retrieves a description of the format of the sound data in the buffer.

Syntax

public void getFormat(byte[] format, int size);

Parameters

format | Array variable that receives a description of the sound data in the buffer.
size | Length of the array assigned to v1. DirectSound writes, at most, insz bytes to that array.

Remarks

Before retrieving the format description, always use the getFormatSize method to query the DirectSoundBuffer object for the size of the format. Use this size to create an array of sufficient length to receive the format description.

See Also

getFormatSize, setFormat

getFormat()

Retrieves a description of the format of the sound data in the buffer.

Syntax

public WaveFormatEx getFormat();

Return Value

Returns the WaveFormatEx object if successful; null otherwise.

See Also

setFormat


getFormatSize (DirectSoundBuffer Class)

 Microsoft SDK for Java

getFormatSize

This method of the DirectSoundBuffer Class retrieves the size of the format information.

Syntax

public int getFormatSize();

Return Value

Returns the size.


getFrequency (DirectSoundBuffer Class)

 Microsoft SDK for Java

getFrequency

This method of the DirectSoundBuffer Class retrieves the frequency, in samples per second, at which the buffer is being played. This value will be in the range of 100-100,000.

Syntax

public int getFrequency();

Return Value

Returns the frequency at which the audio buffer is being played.

See Also

setFrequency


getPan (DirectSoundBuffer Class)

 Microsoft SDK for Java

getPan

This method of the DirectSoundBuffer Class retrieves a variable that represents the relative volume between the left and right audio channels.

Syntax

public int getPan();

Return Value

Returns the relative mix between the left and right speakers.

Remarks

The returned value is measured in hundredths of a decibel (dB), in the range of -10,000 to 10,000. The value -10,000 means the right channel is attenuated by 100 dB. The value 10,000 means the left channel is attenuated by 100 dB. 0 is the neutral value; a return value of 0 means that both channels are at full volume (they are attenuated by 0 decibels). At any setting other than 0, one of the channels is at full volume and the other is attenuated.

A pan of -2173 means that the left channel is at full volume and the right channel is attenuated by 21.73 dB. Similarly, a pan of 870 means that the left channel is attenuated by 8.7 dB and the right channel is at full volume. A pan of -10,000 means that the right channel is silent and the sound is "all the way to the left," while a pan of 10,000 means that the left channel is silent and the sound is "all the way to the right."

The pan control acts cumulatively with the volume control.

See Also

getVolume, setPan, setVolume


getStatus (DirectSoundBuffer Class)

 Microsoft SDK for Java

getStatus

This method of the DirectSoundBuffer Class retrieves the current status of the sound buffer.

Syntax

public int getStatus();

Return Value

Returns one value of DSBSTATUS_ type, specifying the status of the sound buffer.


getVolume (DirectSoundBuffer Class)

 Microsoft SDK for Java

getVolume

This method of the DirectSoundBuffer Class retrieves the current volume for this sound buffer.

Syntax

public int getVolume();

Return Value

Returns the volume associated with the specified DirectSound buffer.

Remarks

The volume is specified in hundredths of decibels (dB), and ranges from 0 to -10,000. The value 0 represents the original, unadjusted volume of the stream. The value -10,000 indicates an audio volume attenuated by 100 dB, which, for all practical purposes, is silence. Amplification is not currently supported by DirectSound.

The decibel (dB) scale corresponds to the logarithmic hearing characteristics of the ear. For example, an attenuation of 10 dB makes a buffer sound half as loud, and an attenuation of 20 dB makes a buffer sound one quarter as loud.

See Also

setVolume


play (DirectSoundBuffer Class)

 Microsoft SDK for Java

play

This method of the DirectSoundBuffer Class causes the sound buffer to play from the current position.

Syntax

public void play(int flags);

Parameters

flags One value of DSBPLAY_ type, specifying how to play the buffer.

Remarks

For secondary sound buffers, this method will cause the buffer to be mixed into the primary buffer and output to the sound device. If this is the first buffer to play, it will implicitly create a primary buffer and start playing that buffer; the application does not need to explicitly direct the primary buffer to play.

If the buffer specified in the method is already playing, the call to the method will succeed and the buffer will continue to play. However, the flags that define playback characteristics are superseded by the flags defined in the most recent call.

Primary buffers must be played with the DSBPLAY_LOOPING flag set.

For primary sound buffers, this method will cause them to start playing to the sound device. If the application is set to the DSSCL_WRITEPRIMARY cooperative level, this will cause the audio data in the primary buffer to be output to the sound device. However, if the application is set to any other cooperative level, this method will ensure that the primary buffer is playing even when no secondary buffers are playing; in that case, silence will be played. This can reduce processing overhead when sounds are started and stopped in sequence, since the primary buffer will be playing continuously rather than stopping and starting between secondary buffers.

Note Before this method can be called on any sound buffer, the application must call the setCooperativeLevel method and specify a cooperative level, typically DSSCL_NORMAL. If setCooperativeLevel has not been called, the play method carries out no action.

See Also

com.ms.directX.DirectSound


restore (DirectSoundBuffer Class)

 Microsoft SDK for Java

restore

This method of the DirectSoundBuffer Class restores the memory allocation for a lost sound buffer for the specified DirectSoundBuffer object.

Syntax

public void restore();

Remarks

If the application does not have the input focus, restore might not succeed. For example, if the application with the input focus has the DSSCL_WRITEPRIMARY cooperative level, no other application will be able to restore its buffers. Similarly, an application with the DSSCL_WRITEPRIMARY cooperative level must have the input focus to restore its primary sound buffer.

Once DirectSound restores the buffer memory, the application must rewrite the buffer with valid sound data. DirectSound cannot restore the contents of the memory, only the memory itself.

The application can receive notification that a buffer is lost when it specifies that buffer in a call to the play method. The getStatus method can also be used to retrieve the status of the sound buffer and test for the DSBSTATUS_BUFFERLOST flag.

See Also

play, getStatus


setCurrentPosition (DirectSoundBuffer Class)

 Microsoft SDK for Java

setCurrentPosition

This method of the DirectSoundBuffer Class moves the current play cursor for secondary sound buffers.

Syntax

public void setCurrentPosition(int newPosition);

Parameters

newPosition New position, in bytes, from the beginning of the buffer that will be used when the sound buffer is played.

Remarks

This method cannot be called on primary sound buffers.

If the buffer is playing, it will immediately move to the new position and continue. If it is not playing, it will begin from the new position the next time the play method is called.

See Also

getCurrentPosition, play


setFormat (DirectSoundBuffer Class)

 Microsoft SDK for Java

setFormat

The setFormat method of the DirectSoundBuffer Class contains the following signatures:

setFormat(byte[] format)
setFormat(WaveFormatEx format)

setFormat(byte[] format)

Sets the format of the primary sound buffer for the application. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.

Syntax

public void setFormat(byte[] format);

Parameters

format Array variable that specifies the new format for the primary sound buffer.

Remarks

If this method is called on a primary buffer which is being accessed in write-primary cooperative level, the buffer must be stopped before setFormat is called. If this method is being called on a primary buffer for a non-write-primary level, DirectSound will implicitly stop the primary buffer, change the format, and restart the primary; the application does not need to do this explicitly.

A call to this method fails if the hardware does not directly support the requested pulse coded modulation (PCM) format. It will also fail if the calling application has the DSSCL_NORMAL cooperative level.

If a secondary sound buffer requires a format change, the application should create a new DirectSoundBuffer object using the new format.

DirectSound supports PCM formats; it does not currently support compressed formats.

See Also

getFormat

setFormat(WaveFormatEx format)

Sets the format of the primary sound buffer for the application. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.

Syntax

public void setFormat(WaveFormatEx format);

Parameters

format A WaveFormatEx object that specifies the wave format to set.

Remarks

If this method is called on a primary buffer which is being accessed in write-primary cooperative level, the buffer must be stopped before setFormat is called. If this method is being called on a primary buffer for a non-write-primary level, DirectSound will implicitly stop the primary buffer, change the format, and restart the primary; the application does not need to do this explicitly.

A call to this method fails if the hardware does not directly support the requested pulse coded modulation (PCM) format. It will also fail if the calling application has the DSSCL_NORMAL cooperative level.

If a secondary sound buffer requires a format change, the application should create a new DirectSoundBuffer object using the new format.

DirectSound supports PCM formats; it does not currently support compressed formats.

See Also

getFormat


setFrequency (DirectSoundBuffer Class)

 Microsoft SDK for Java

setFrequency

This method of the DirectSoundBuffer Class sets the frequency at which the audio samples are played.

Syntax

public void setFrequency(int frequency);

Parameters

frequency New frequency, in Hz, at which to play the audio samples. The value must be between 100 and 100,000. If the value is 0, the frequency is reset to the current buffer format. This format is specified in the createSoundBuffer method.

Remarks

Increasing or decreasing the frequency changes the perceived pitch of the audio data. This method does not affect the format of the buffer.

See Also

getFrequency, play, setFormat, com.ms.directX.DirectSound


setPan (DirectSoundBuffer Class)

 Microsoft SDK for Java

setPan

This method of the DirectSoundBuffer Class specifies the relative volume between the left and right channels.

Syntax

public void setPan(int pan);

Parameters

pan Relative volume between the left and right channels. This value has a range of -10,000 to 10,000 and is measured in hundredths of a decibel.

Remarks

0 is the neutral value for pan and indicates that both channels are at full volume (attenuated by 0 decibels). At any other setting, one of the channels is at full volume and the other is attenuated. For example, a pan of -2173 means that the left channel is at full volume and the right channel is attenuated by 21.73 dB. Similarly, a pan of 870 means that the left channel is attenuated by 8.7 dB and the right channel is at full volume.

A pan of -10,000 means that the right channel is silent and the sound is "all the way to the left," while a pan of 10,000 means that the left channel is silent and the sound is "all the way to the right."

The pan control is cumulative with the volume control.

See Also

getPan, getVolume, setVolume


setVolume (DirectSoundBuffer Class)

 Microsoft SDK for Java

setVolume

This method of the DirectSoundBuffer Class changes the volume of a sound buffer.

Syntax

public void setVolume(int volume);

Parameters

volume New volume requested for this sound buffer. Values range from 0 (0 dB, no volume adjustment) to –10,000 (-100 dB, essentially silent). DirectSound does not currently support amplification.

Remarks

Volume units of are in hundredths of decibels, where 0 is the original volume of the stream.

Positive decibels correspond to amplification and negative decibels correspond to attenuation. The decibel scale corresponds to the logarithmic hearing characteristics of the ear. An attenuation of 10 dB makes a buffer sound half as loud; an attenuation of 20 dB makes a buffer sound one quarter as loud. DirectSound does not currently support amplification.

The pan control is cumulative with the volume control.

See Also

getPan, getVolume, setPan


stop (DirectSoundBuffer Class)

 Microsoft SDK for Java

stop

This method of the DirectSoundBuffer Class causes the sound buffer to stop playing.

Syntax

public void stop();

Remarks

For secondary sound buffers, stop will set the current position of the buffer to the sample that follows the last sample played. This means that if the play method is called on the buffer, it will continue playing where it left off.

For primary sound buffers, if an application has the DSSCL_WRITEPRIMARY level, this method will stop the buffer and reset the current position to 0 (the beginning of the buffer). This is necessary because the primary buffers on most sound cards can only play from the beginning of the buffer.

However, if stop is called on a primary buffer and the application has a cooperative level other than DSSCL_WRITEPRIMARY, this method simply reverses the effects of play. It configures the primary buffer to stop if no secondary buffers are playing. If other buffers are playing in this or other applications, the primary buffer will not actually stop until they are stopped. This method is useful because playing the primary buffer consumes processing overhead even if the buffer is playing sound data with the amplitude of 0 dB.

See Also

play


transferToSoundBuffer (DirectSoundBuffer Class)

 Microsoft SDK for Java

transferToSoundBuffer

This method of the DirectSoundBuffer Class transfers the wave data from the given resource to the start of the sound buffer.

Syntax

public void transferToSoundBuffer(DSResourceDesc resourceDesc, int flags);

Parameters

resourceDesc | A DSResourceDesc object that specifies the wave resource to transfer.
flags | A value of DSBLOCK_ type specifying how the buffer should be locked before it receives the wave data.

Remarks

This method automatically locks and unlocks the buffer before and after writing the data.


writeBuffer (DirectSoundBuffer Class)

 Microsoft SDK for Java

writeBuffer

This method of the DirectSoundBuffer Class writes the contents of a buffer to the given position in the sound buffer.

Syntax

public void writeBuffer(int start, int size, byte[] buffer, int flags);

Parameters

start | Offset, in bytes, from the start of the buffer to the position to begin writing the data. This parameter is ignored if DSBLOCK_FROMWRITECURSOR is specified in the flags parameter.
size | Size, in bytes, of the portion of the buffer to write to.
buffer | Array variable that contain the data to write.
flags | A value of DSBLOCK_ type specifying how the buffer should be locked before it is written to.

Remarks

This method automatically locks and unlocks the buffer before and after writing the data.


DirectSoundResource Class (com.ms.directX Package)

 Microsoft SDK for Java

DirectSoundResource Class

Applications use the DirectSoundResource Class of the com.ms.directX package to load wave format objects.

public class DirectSoundResource implements
            IDirectSoundResource
{
  // Methods
  public void loadWaveFile(String name,
        DSResourceDesc resourceDesc, byte[] wave);
  public WaveFormatEx loadWaveFile(String name,
        DSResourceDesc resourceDesc);
  public void loadWaveResource(int handle,
        DSResourceDesc resourceDesc, byte[] wave);
  public WaveFormatEx loadWaveResource(int handle,
        DSResourceDesc resourceDesc);
  public void readBuffer(int sourceIndex, int destIndex, int size,
        DSResourceDesc resourceDesc, byte[] buffer, int maxbuf);
}


Methods (DirectSoundResource Class)

 Microsoft SDK for Java

DirectSoundResource Class Methods

The DirectSoundResource Class contains the following methods:

loadWaveFile loads a wave resource from the given file.
loadWaveResource loads a wave resource from the given module.
readBuffer reads an amount of data from a resource into the given buffer.


loadWaveFile (DirectSoundResource Class)

 Microsoft SDK for Java

loadWaveFile

The loadWaveFile method of the DirectSoundResource Class contains the following signatures:

loadWaveFile(String name, DSResourceDesc resourceDesc, byte[] wave)
loadWaveFile(String name, DSResourceDesc resourceDesc)

loadWaveFile(String name, DSResourceDesc resourceDesc, byte[] wave)

Loads a wave resource from the given file.

Syntax

public void loadWaveFile(String name, DSResourceDesc resourceDesc, byte[] wave);

Parameters

name | Name of the file that contains the resource.
resourceDesc | The DSResourceDesc object that receives a description of the resource.
wave | Array variable that receives the wave resource data.

loadWaveFile(String name, DSResourceDesc resourceDesc)

Loads a wave resource from a file and returns it as a wave format object.

Syntax

public WaveFormatEx loadWaveFile(String name, DSResourceDesc resourceDesc);

Return Value

Returns the WaveFormatEx object if successful; null otherwise.

Parameters

name | Name of the file that contains the resource.
resourceDesc | The DSResourceDesc object that receives a description of the resource.


loadWaveResource (DirectSoundResource Class)

 Microsoft SDK for Java

loadWaveResource

The loadWaveResource method of the DirectSoundResource Class contains the following signatures:

loadWaveResource(int handle, DSResourceDesc resourceDesc, byte[] wave)
loadWaveResource(int handle, DSResourceDesc resourceDesc)

loadWaveResource(int handle, DSResourceDesc resourceDesc, byte[] wave)

Loads a wave resource from the given module.

Syntax

public void loadWaveResource(int handle, DSResourceDesc resourceDesc, byte[] wave);

Parameters

handle | Handle of the module containing the resource.
resourceDesc | The DSResourceDesc object that receives a description of the resource.
wave | Array variable that receives the wave resource data.

loadWaveResource(int handle, DSResourceDesc resourceDesc)

Loads a wave resource and returns it as a wave format object.

Syntax

public WaveFormatEx loadWaveResource(int handle, DSResourceDesc resourceDesc);

Return Value

Returns the WaveFormatEx object if successful; null otherwise.

Parameters

handle | Handle of the module containing the resource.
resourceDesc | The DSResourceDesc object that receives a description of the resource.


readBuffer (DirectSoundResource Class)

 Microsoft SDK for Java

readBuffer

This method of the DirectSoundResource Class reads an amount of data from a resource into the given buffer.

Syntax

public void readBuffer(int sourceIndex, int destIndex, int size, DSResourceDesc resourceDesc, byte[] buffer, int maxbuf);

Parameters

sourceIndex | Index into the resource, indicating the first byte of data to read.
destIndex | Index into the buffer, indicating to first byte to receive the data to be read.
size | Number of bytes of data to read.
resourceDesc | The DSResourceDesc object that contains a description of the resource. The fields of this object must have been previously initialized by using loadWaveResource or loadWaveFile.
buffer | Array variable that receives the data.
maxbuf | Length of the buffer array. The method retrieves no more than this amount of data.

Remarks

If destIndex is non-zero and destIndex + size is greater than maxbuf, the method fills to the end of the buffer, then wraps back to the beginning of the buffer and continues to fill the buffer until the method reads the requested data or encounters the position specified by destIndex.


DPCaps Class (com.ms.directX Package)

 Microsoft SDK for Java

DPCaps Class

The DPCaps Class of the com.ms.directX package contains the capabilities of a DirectPlay object after a call to the getCaps or getPlayerCaps methods. Any of these capabilities can differ depending on whether guaranteed or non-guaranteed capabilities are requested. This class is read-only.

public final class DPCaps
{
  // Fields
  public int flags;
  public int headerLength;
  public int hundredBaud;
  public int latency;
  public int maxBufferSize;
  public int maxLocalPlayers;
  public int maxPlayers;
  public int maxQueueSize;
  public int timeOut;
}

See Also

DirectPlay2, send


Fields (DPCaps Class)

 Microsoft SDK for Java

DPCaps Class Fields

The DPCaps Class contains the following fields.

flags | One or more values of DPCAPS_ type, indicating the properties of the DirectPlay object.
headerLength | Size, in bytes, of the header that will be added to player messages by this DirectPlay object. Note that the header size depends on which service provider is in use.
hundredBaud | Bandwidth specified in multiples of one hundred bits per second. For example, a value of 24 specifies 2400 baud.
latency | Latency estimate by the service provider, in milliseconds. If this value is 0, DirectPlay cannot provide an estimate. Accuracy for some service providers rests on application-to-application testing, taking into consideration the average message size. Latency can differ depending on whether the application is interested in guaranteed or non-guaranteed message delivery.
maxBufferSize | Maximum number of bytes that can be sent in a single packet by this service provider. Larger messages will be sent using more than one packet.
maxLocalPlayers | Maximum number of local players supported in a session.
maxPlayers | Maximum number of local and remote players supported in a session by this DirectPlay object.
maxQueueSize | This field is no longer used.
timeOut | Service provider's suggested timeout value. By default, DirectPlay will use this timeout value when waiting for replies to messages.


DPSessionDesc Class (com.ms.directX Package)

 Microsoft SDK for Java

DPSessionDesc Class

The DPSessionDesc Class of the com.ms.directX package contains a description of the capabilities of an DirectPlay session.

public final class DPSessionDesc
{
  // Fields
  public int currentPlayers;
  public int flags;
  public int maxPlayers;
  public int reserved1;
  public int reserved2;
  public int user1;
  public int user2;
  public int user3;
  public int user4;
}

See Also

enumSessions


Fields (DPSessionDesc Class)

 Microsoft SDK for Java

DPSessionDesc Class Fields

The DPSessionDesc Class contains the following fields.

currentPlayers | Current players and groups in the session.
flags | One of DPOPEN_CREATESESSION, DPOPEN_OPENSESSION, or DPENUMSESSIONS_ALL.
maxPlayers | Maximum number of players and groups allowed in this session. This field is ignored if the application is not creating a new session.
reserved1 | Reserved.
reserved2 | Reserved.
user1 | User-specific data for the game or session.
user2 | User-specific data for the game or session.
user3 | User-specific data for the game or session.
user4 | User-specific data for the game or session.


DS3dBuffer Class (com.ms.directX Package)

 Microsoft SDK for Java

DS3dBuffer Class

The DS3bBuffer Class is in the com.ms.directX package.

public final class DS3dBuffer
{
  // Fields
  public float coneOrientationX;
  public float coneOrientationY;
  public float coneOrientationZ;
  public int coneOutsideVolume;
  public int insideConeAngle;
  public float maxDistance;
  public float minDistance;
  public int mode;
  public int outsideConeAngle;
  public float positionVectorX;
  public float positionVectorY;
  public float positionVectorZ;
  public float velocityVectorX;
  public float velocityVectorY;
  public float velocityVectorZ;
}


Fields (DS3dBuffer Class)

 Microsoft SDK for Java

DS3dBuffer Class Fields

The DS3dBuffer Class contains the following fields.

coneOrientationX | The x component of the D3dVector that describes the current orientation of this 3D buffer's sound projection cone.
coneOrientationY | The y component of the D3dVector that describes the current orientation of this 3D buffer's sound projection cone.
coneOrientationZ | The z component of the D3dVector that describes the current orientation of this 3D buffer's sound projection cone.
coneOutsideVolume | The cone outside volume.
insideConeAngle | The angle of the inside sound projection cone.
maxDistance | The maximum distance.
minDistance | The minimum distance.
mode | The 3D sound processing mode to be set. Can be one of the following: DS3DMODE_DISABLE DS3DMODE_HEADRELATIVE DS3DMODE_NORMAL
outsideConeAngle | The angle of the outside sound projection cone.
positionVectorX | The x component of the D3dVector that describes the current position of this 3D sound buffer.
positionVectorY | The y component of the D3dVector that describes the current position of this 3D sound buffer.
positionVectorZ | The z component of the D3dVector that describes the current position of this 3D sound buffer.
velocityVectorX | The x component of the D3dVector that describes the current velocity of this 3D sound buffer.
velocityVectorY | The y component of the D3dVector that describes the current velocity of this 3D sound buffer.
velocityVectorZ | The z component of the D3dVector that describes the current velocity of this 3D sound buffer.


DS3dListener Class (com.ms.directX Package)

 Microsoft SDK for Java

DS3dListener Class

The DS3dListener Class is in the com.ms.directX package.

public final class DS3dListener
{
  // Fields
  public float flDistanceFactor;
  public float flDopplerFactor;
  public float flRolloffFactor;
  public float orientFrontX;
  public float orientFrontY;
  public float orientFrontZ;
  public float orientTopX;
  public float orientTopY;
  public float orientTopZ;
  public float positionVectorX;
  public float positionVectorY;
  public float positionVectorZ;
  public float velocityVectorX;
  public float velocityVectorY;
  public float velocityVectorZ;
}


Fields (DS3dListener Class)

 Microsoft SDK for Java

DS3dListener Class Fields

The DS3dListener Class contains the following fields.

flDistanceFactor | The current distance factor.
flDopplerFactor | The current Doppler factor.
flRolloffFactor | The current rolloff factor.
orientFrontX | The x element of the D3dVector that describes the listener's front orientation.
orientFrontY | The y element of the D3dVector that describes the listener's front orientation.
orientFrontZ | The z element of the D3dVector that describes the listener's front orientation.
orientTopX | The x element of the D3dVector that describes the listener's top orientation.
orientTopY | The y element of the D3dVector that describes the listener's top orientation.
orientTopZ | The z element of the D3dVector that describes the listener's top orientation.
positionVectorX | The x element of the D3dVector that describes the listener's position.
positionVectorY | The y element of the D3dVector that describes the listener's position.
positionVectorZ | The z element of the D3dVector that describes the listener's position.
velocityVectorX | The x element of the D3dVector that describes the listener's velocity.
velocityVectorY | The y element of the D3dVector that describes the listener's velocity.
velocityVectorZ | The z element of the D3dVector that describes the listener's velocity.


DSBCaps Class (com.ms.directX Package)

 Microsoft SDK for Java

DSBCaps Class

The DSBCaps Class of the com.ms.directX package specifies the capabilities of a DirectSound buffer object, for use by the getCaps method.

public final class DSBCaps
{
  // Fields
  public int bufferBytes;
  public int flags;
  public int playCpuOverhead;
  public int unlockTransferRate;
}

See Also

DirectSoundBuffer


Fields (DSBCaps Class)

 Microsoft SDK for Java

DSBCaps Class Fields

The DSBCaps Class contains the following fields.

bufferBytes | Size of this buffer, in bytes.
flags | One or more values of DSBCAPS type that specify buffer-object capabilities.
playCpuOverhead | Specifies the processing overhead as a percentage of main processing cycles needed to mix this sound buffer. For hardware buffers, this field will be 0 because the mixing is performed by the sound device. For software buffers, this field depends on the buffer format and the speed of the system processor.
unlockTransferRate | Specifies the rate, in kilobytes per second, that data is transferred to the buffer memory when unlock is called. High-performance applications can use this value to determine the time required for unlock to execute. For software buffers located in system memory, the rate will be very high since no processing is required. For hardware buffers, the rate might be slower because the buffer might have to be downloaded to the sound card, which can have a limited transfer rate.


DSBufferDesc Class (com.ms.directX Package)

 Microsoft SDK for Java

DSBufferDesc Class

The DSBufferDesc Class of the com.ms.directX package describes the necessary characteristics of a new DirectSoundBuffer object. This class is used by the createSoundBuffer method.

public final class DSBufferDesc
{
  // Fields
  public int bufferBytes;
  public int flags;
}


Fields (DSBufferDesc Class)

 Microsoft SDK for Java

DSBufferDesc Class Fields

The DSBufferDesc Class contains the following fields.

bufferBytes | Size of the new buffer, in bytes. This value must be 0 when creating primary buffers.
flags | One or more values of DBSCAPS_ type, identifying the capabilities to include when creating a new DirectSoundBuffer object.


DSCaps Class (com.ms.directX Package)

 Microsoft SDK for Java

DSCaps Class

The DSCaps Class of the com.ms.directX package specifies the capabilities of a DirectSound device for use by the getCaps method.

public final class DSCaps
{
  // Fields
  public int flags;
  public int freeHw3DAllBuffers;
  public int freeHw3DStaticBuffers;
  public int freeHw3DStreamingBuffers;
  public int freeHwMemBytes;
  public int freeHwMixingAllBuffers;
  public int freeHwMixingStaticBuffers;
  public int freeHwMixingStreamingBuffers;
  public int maxContigFreeHwMemBytes;
  public int maxHw3DAllBuffers;
  public int maxHw3DStaticBuffers;
  public int maxHw3DStreamingBuffers;
  public int maxHwMixingAllBuffers;
  public int maxHwMixingStaticBuffers;
  public int maxHwMixingStreamingBuffers;
  public int maxSecondarySampleRate;
  public int minSecondarySampleRate;
  public int playCpuOverheadSwBuffers;
  public int primaryBuffers;
  public int totalHwMemBytes;
  public int unlockTransferRateHwBuffers;
}


Fields (DSCaps Class)

 Microsoft SDK for Java

DSCaps Class Fields

The DSCaps Class contains the following fields.

flags | One or more values of DSCAPS type, specifying device capabilities.
freeHw3DAllBuffers | Description of the free, or unallocated, hardware 3D positional capabilities of the device.
freeHw3DStaticBuffers | Description of the free, or unallocated, hardware 3D positional capabilities of the device.
freeHw3DStreamingBuffers | Description of the free, or unallocated, hardware 3D positional capabilities of the device. These will all be 0 for the first release.
freeHwMemBytes | Size, in bytes, of the free memory on the sound card.
freeHwMixingAllBuffers | Description of the free hardware mixing capabilities of the device.
freeHwMixingStaticBuffers | Description of the free hardware mixing capabilities of the device.
freeHwMixingStreamingBuffers | Description of the free, or unallocated, hardware mixing capabilities of the device. These freeHwMixing values can be used by an application to determine whether hardware resources are available for allocation to a secondary sound buffer. Also, by comparing these values to the fields that specify maximum mixing capabilities, the resources that are already allocated can be determined.
maxContigFreeHwMemBytes | Size, in bytes, of the largest contiguous block of free memory on the sound card.
maxHw3DAllBuffers | Description of the hardware 3D positional capabilities of the device. These will all be 0 for the first release.
maxHw3DStaticBuffers | Description of the hardware 3D positional capabilities of the device. These will all be 0 for the first release.
maxHw3DStreamingBuffers | Description of the hardware 3D positional capabilities of the device.
maxHwMixingAllBuffers | Specifies the total number of buffers that can be mixed in hardware.
maxHwMixingStaticBuffers | Specifies the maximum number of static sound buffers.
maxHwMixingStreamingBuffers | Specifies the maximum number of streaming sound buffers. Note The value for maxHwMixingAllBuffers might be less than the sum of maxHwMixingStaticBuffers and maxHwMixingStreamingBuffers. Resource trade-offs frequently occur.
maxSecondarySampleRate | Maximum sample rate specification that is supported by this device's hardware secondary sound buffers.
minSecondarySampleRate | Minimum sample rate specification that is supported by this device's hardware secondary sound buffers.
playCpuOverheadSwBuffers | Description of the processing overhead, as a percentage of the central processing unit, needed to mix software buffers (those located in main system memory). This varies according to the bus type, the processor type, and the clock speed. The unlock transfer rate for software buffers is 0 because the data does not need to be transferred anywhere. Similarly, the play processing overhead for hardware buffers is 0 because the mixing is done by the sound device.
primaryBuffers | Number of primary buffers supported. This value will always be 1 for this release.
totalHwMemBytes | Size, in bytes, of the amount of memory on the sound card that stores static sound buffers.
unlockTransferRateHwBuffers | Description of the rate, in kilobytes per second, at which data can be transferred to hardware static sound buffers (those located in onboard sound memory). This and the number of bytes transferred determines the duration of a call to the unlock method.


DSCursors Class (com.ms.directX Package)

 Microsoft SDK for Java

DSCursors Class

The DSCursors Class of the com.ms.directX package contains the play and write positions in a DirectSoundBuffer object. Used with the getCurrentPosition method.

public final class DSCursors
{
  // Fields
  public int play;
  public int write;
}


Fields (DSCursors Class)

 Microsoft SDK for Java

DSCursors Class Fields

The DSCursors Class contains the following fields.

play | Current play position in the DirectSoundBuffer object. This position is an offset within the sound buffer and is specified in bytes.
write | Current write position in the DirectSoundBuffer object. This position is an offset within the sound buffer and is specified in bytes.


DSResourceDesc Class (com.ms.directX Package)

 Microsoft SDK for Java

DSResourceDesc Class

The DSResourceDesc Class of the com.ms.directX package contains information about a loaded resource. Used by the DirectSoundResource.loadWaveResource and DirectSoundResource.loadWaveFile methods.

public final class DSResourceDesc
{
  // Fields
  public int bufferBytes;
  public int flags;
}

See Also

DirectSoundResource


Fields (DSResourceDesc Class)

 Microsoft SDK for Java

DSResourceDesc Class Fields

The DSResourceDesc Class contains the following fields.

bufferBytes | Number of bytes in the buffer identified by the private lpBufferData member.
flags | Reserved.


JoyCaps Class (com.ms.directX Package)

 Microsoft SDK for Java

JoyCaps Class

The JoyCaps Class is in the com.ms.directX package.

public final class JoyCaps
{
  // Fields
  public int caps;
  public int maxAxes;
  public int maxButtons;
  public char mid;
  public int numAxes;
  public int numButtons;
  public int periodMax;
  public int periodMin;
  public char pid;
  public int rMax;
  public int rMin;
  public int uMax;
  public int uMin;
  public int vMax;
  public int vMin;
  public int xMax;
  public int xMin;
  public int yMax;
  public int yMin;
  public int zMax;
  public int zMin;
}


Fields (JoyCaps Class)

 Microsoft SDK for Java

JoyCaps Class Fields

The JoyCaps Class contains the following fields.

caps | Joystick capabilities. These may be one of the following: JOYCAPS_HASPOV The joystick has Point-Of-View information. JOYCAPS_HASR The joystick has rudder (fourth axis) information. JOYCAPS_HASU The joystick has u-coordinate information. JOYCAPS_HASV The joystick has v-coordinate information. JOYCAPS_HASZ The joystick has z-coordinate information JOYCAPS_POV4DIR The joystick Point-Of-View supports discrete values. JOYCAPS_POVCTS The joystick Point-Of-View supports continuous degree bearings.
maxAxes | The maximum number of axes supported by the joystick.
maxButtons | The maximum number of buttons a joystick supports.
mid | Manufacturer identifier.
numAxes | The number of axes currently supported by the joystick.
numButtons | The current number of joystick buttons in use.
periodMax | The maximum polling frequency supported once an application has captured a joystick.
periodMin | The minumim polling frequency supported once an application has captured a joystick.
pid | Product identifier.
rMax | Maximum r-axis (the fourth, or rudder-axis) coordinate.
rMin | Minimum r-axis (the fourth, or rudder-axis) coordinate.
uMax | Maximum u-axis (fifth axis) coordinate.
uMin | Minimum u-axis (fifth axis) coordinate.
vMax | Maximum v-axis (sixth axis) coordinate.
vMin | Minimum v-axis (sixth axis) coordinate.
xMax | Maximum x-axis coordinate.
xMin | Minimum x-axis coordinate.
yMax | Maximum y-axis coordinate.
yMin | Minimum y-axis coordinate.
zMax | Maximum z-axis coordinate.
zMin | Minimum z-axis coordinate.


JoyInfo Class (com.ms.directX Package)

 Microsoft SDK for Java

JoyInfo Class

The JoyInfo Class is in the com.ms.directX package.

public final class JoyInfo
{
  // Fields
  public int buttonNumber;
  public int buttons;
  public int flags;
  public int pov;
  public int rPos;
  public int uPos;
  public int vPos;
  public int xPos;
  public int yPos;
  public int zPos;
}


Fields (JoyInfo Class)

 Microsoft SDK for Java

JoyInfo Class Fields

The JoyInfo Class contains the following fields.

buttonNumber | Current button number that is pressed.
buttons | Current state of the 32 joystick buttons. The value of this member can be set to any combination of JOY_BUTTONn flags, where n is a value ranging from 1 to 32. Each value corresponds to the button that is pressed.
flags | Flags that indicate if information returned in this class is valid. Members that do not contain valid information are set to 0. These flags can be one or more of the JOY_RETURN* and JOY_CAL_ types.
pov | Current position of the Point-Of-View control. Values for this member range from 0 to 35,900. These values represent each views angle, in degress, multiplied by 100.
rPos | Current position of the rudder, or fourth joystick axis.
uPos | Current positions of the fifth joysick axis.
vPos | Current positions of the sixth joysick axis.
xPos | Current x-coordinate.
yPos | Current y-coordinate.
zPos | Current z coordinate.


PaletteEntry Class (com.ms.directX Package)

 Microsoft SDK for Java

PaletteEntry Class

The PaletteEntry Class of the com.ms.directX package specifies a color palette entry when creating palettes using the createPalette method.

public final class PaletteEntry
{
  // Fields
  public int peBlue;
  public int peFlags;
  public int peGreen;
  public int peRed;

  // Constructors
  public PaletteEntry();
  public PaletteEntry(byte[] b, int count, int flags);
}

Note that the fields of this class take values indicating the intensity of red, green, or blue. Intensity values are unsigned values in the range 0 to 255, unlike byte values which range from -128 to 127. When assigning intensity values to these fields, you might need to cast such values to byte type.


Constructors (PaletteEntry Class)

 Microsoft SDK for Java

PaletteEntry Class Constructors

The PaletteEntry Class contains the following constructors:

PaletteEntry()
PaletteEntry(byte[] b, int count, int flags)

PaletteEntry()

Creates an uninitialized palette entry object.

Syntax

public PaletteEntry();

PaletteEntry(byte[] b, int count, int flags)

Creates an initialized palette entry object.

Syntax

public PaletteEntry(byte[] b, int count, int flags);

Parameters

b | Array variable that contains the initial palette entry data. The data must be in the order: red intensity, green intensity, blue intensity, and flags.
count | Index into b of palette entry data for this object.
flags | Can be 0 or DDPCAPS_8BITENTRIES.

Remarks

Although b can contain data for more than one palette entry, count specifies which data to use to initialize the object being created.


Fields (PaletteEntry Class)

 Microsoft SDK for Java

PaletteEntry Class Fields

The PaletteEntry Class contains the following fields.

peBlue | Intensity of blue.
peFlags | One value of D3DPAL_ type.
peGreen | Intensity of green.
peRed | Intensity of red.


Rect Class (com.ms.directX Package)

 Microsoft SDK for Java

Rect Class

The Rect Class of the com.ms.directX package specifies the corners of a rectangle.

public final class Rect
{
  // Fields
  public int bottom;
  public int left;
  public int right;
  public int top;
}


Fields (Rect Class)

 Microsoft SDK for Java

Rect Class Fields

The Rect Class contains the following fields.

bottom | The y-coordinate of the lower-right corner.
left | The x-coordinate of the upper-left corner.
right | The x-coordinate of the lower-right corner.
top | The y-coordinate of the upper-left corner.


WaveFormatEx Class (com.ms.directX Package)

 Microsoft SDK for Java

WaveFormatEx Class

The WaveFormatEx Class of the com.ms.directX package specifies the format of data in a sound buffer.

public final class WaveFormatEx
{
  // Fields
  public int avgBytesPerSec;
  public int bitsPerSample;
  public int blockAlign;
  public int channels;
  public byte[] extra;
  public int formatTag;
  public int samplesPerSec;
  public int size;
}


Fields (WaveFormatEx Class)

 Microsoft SDK for Java

WaveFormatEx Class Fields

The WaveFormatEx Class contains the following fields.

avgBytesPerSec | Required average data-transfer rate, in bytes per second, for the format tag.
bitsPerSample | Bits per sample for the formatTag format type. If a compression scheme cannot define a bits-per-sample value, this field is zero.
blockAlign | Block alignment, in bytes. The block alignment is the minimum atomic unit of data for the formatTag format type. Playback and record software must process a multiple of blockAlign bytes of data at a time. Data written and read from a device must always start at the beginning of a block. For example, it is illegal to start playback of PCM data in the middle of a sample (that is, on a non-block-aligned boundary).
channels | Number of channels in the waveform-audio data. Monaural data uses one channel and stereo data uses two channels.
extra | Array variable that contains extra format information.
formatTag | Waveform-audio format type. Format tags are registered with Microsoft Corporation for many compression algorithms.
samplesPerSec | Sample rate, in samples per second (hertz), that each channel should be played or recorded.
size | Size, in bytes, of extra format information.


DirectXConstants Interface (com.ms.directX Package)

 Microsoft SDK for Java

DirectXConstants Interface

The DirectXConstants Interface of the com.ms.directx package defines all the constants used in DirectX for Java.

public interface DirectXConstants
{
  // Fields
  public final static int D3DBLEND_BOTHINVSRCALPHA;
  public final static int D3DBLEND_BOTHSRCALPHA;
  public final static int D3DBLEND_DESTALPHA;
  public final static int D3DBLEND_DESTCOLOR;
  public final static int D3DBLEND_INVDESTALPHA;
  public final static int D3DBLEND_INVDESTCOLOR;
  public final static int D3DBLEND_INVSRCALPHA;
  public final static int D3DBLEND_INVSRCCOLOR;
  public final static int D3DBLEND_ONE;
  public final static int D3DBLEND_SRCALPHA;
  public final static int D3DBLEND_SRCALPHASAT;
  public final static int D3DBLEND_SRCCOLOR;
  public final static int D3DBLEND_ZERO;
  public final static int D3DCLEAR_TARGET;
  public final static int D3DCLEAR_ZBUFFER;
  public final static int D3DCLIP_BACK;
  public final static int D3DCLIP_BOTTOM;
  public final static int D3DCLIP_FRONT;
  public final static int D3DCLIP_GEN0;
  public final static int D3DCLIP_GEN1;
  public final static int D3DCLIP_GEN2;
  public final static int D3DCLIP_GEN3;
  public final static int D3DCLIP_GEN4;
  public final static int D3DCLIP_GEN5;
  public final static int D3DCLIP_LEFT;
  public final static int D3DCLIP_RIGHT;
  public final static int D3DCLIP_TOP;
  public final static int D3DCMP_ALWAYS;
  public final static int D3DCMP_EQUAL;
  public final static int D3DCMP_GREATER;
  public final static int D3DCMP_GREATEREQUAL;
  public final static int D3DCMP_LESS;
  public final static int D3DCMP_LESSEQUAL;
  public final static int D3DCMP_NEVER;
  public final static int D3DCMP_NOTEQUAL;
  public final static int D3DCOLOR_MONO;
  public final static int D3DCOLOR_RGB;
  public final static int D3DCULL_CCW;
  public final static int D3DCULL_CW;
  public final static int D3DCULL_NONE;
  public final static int D3DDD_BCLIPPING;
  public final static int D3DDD_COLORMODEL;
  public final static int D3DDD_DEVCAPS;
  public final static int D3DDD_DEVICERENDERBITDEPTH;
  public final static int D3DDD_DEVICEZBUFFERBITDEPTH;
  public final static int D3DDD_LIGHTINGCAPS;
  public final static int D3DDD_LINECAPS;
  public final static int D3DDD_MAXBUFFERSIZE;
  public final static int D3DDD_MAXVERTEXCOUNT;
  public final static int D3DDD_TRANSFORMCAPS;
  public final static int D3DDD_TRICAPS;
  public final static int D3DDEB_BUFSIZE;
  public final static int D3DDEB_CAPS;
  public final static int D3DDEB_LPDATA;
  public final static int D3DDEBCAPS_MEM;
  public final static int D3DDEBCAPS_SYSTEMMEMORY;
  public final static int D3DDEBCAPS_VIDEOMEMORY;
  public final static int D3DDEVCAPS_EXECUTESYSTEMMEMORY;
  public final static int D3DDEVCAPS_EXECUTEVIDEOMEMORY;
  public final static int D3DDEVCAPS_FLOATTLVERTEX;
  public final static int D3DDEVCAPS_SORTDECREASINGZ;
  public final static int D3DDEVCAPS_SORTEXACT;
  public final static int D3DDEVCAPS_SORTINCREASINGZ;
  public final static int D3DDEVCAPS_TEXTURESYSTEMMEMORY;
  public final static int D3DDEVCAPS_TEXTUREVIDEOMEMORY;
  public final static int D3DDEVCAPS_TLVERTEXSYSTEMMEMORY;
  public final static int D3DDEVCAPS_TLVERTEXVIDEOMEMORY;
  public final static int D3DEXECUTE_CLIPPED;
  public final static int D3DEXECUTE_UNCLIPPED;
  public final static int D3DFDS_ALPHACMPCAPS;
  public final static int D3DFDS_COLORMODEL;
  public final static int D3DFDS_DSTBLENDCAPS;
  public final static int D3DFDS_GUID;
  public final static int D3DFDS_HARDWARE;
  public final static int D3DFDS_LINES;
  public final static int D3DFDS_MISCCAPS;
  public final static int D3DFDS_RASTERCAPS;
  public final static int D3DFDS_SHADECAPS;
  public final static int D3DFDS_SRCBLENDCAPS;
  public final static int D3DFDS_TEXTUREADDRESSCAPS;
  public final static int D3DFDS_TEXTUREBLENDCAPS;
  public final static int D3DFDS_TEXTURECAPS;
  public final static int D3DFDS_TEXTUREFILTERCAPS;
  public final static int D3DFDS_TRIANGLES;
  public final static int D3DFDS_ZCMPCAPS;
  public final static int D3DFILL_POINT;
  public final static int D3DFILL_SOLID;
  public final static int D3DFILL_WIREFRAME;
  public final static int D3DFILTER_LINEAR;
  public final static int D3DFILTER_LINEARMIPLINEAR;
  public final static int D3DFILTER_LINEARMIPNEAREST;
  public final static int D3DFILTER_MIPLINEAR;
  public final static int D3DFILTER_MIPNEAREST;
  public final static int D3DFILTER_NEAREST;
  public final static int D3DFOG_EXP;
  public final static int D3DFOG_EXP2;
  public final static int D3DFOG_LINEAR;
  public final static int D3DFOG_NONE;
  public final static int D3DLIGHT_DIRECTIONAL;
  public final static int D3DLIGHT_GLSPOT;
  public final static int D3DLIGHT_PARALLELPOINT;
  public final static int D3DLIGHT_POINT;
  public final static int D3DLIGHT_SPOT;
  public final static int D3DLIGHTSTATE_AMBIENT;
  public final static int D3DLIGHTSTATE_COLORMODEL;
  public final static int D3DLIGHTSTATE_FOGDENSITY;
  public final static int D3DLIGHTSTATE_FOGEND;
  public final static int D3DLIGHTSTATE_FOGMODE;
  public final static int D3DLIGHTSTATE_FOGSTART;
  public final static int D3DLIGHTSTATE_MATERIAL;
  public final static int D3DOP_BRANCHFORWARD;
  public final static int D3DOP_EXIT;
  public final static int D3DOP_LINE;
  public final static int D3DOP_MATRIXLOAD;
  public final static int D3DOP_MATRIXMULTIPLY;
  public final static int D3DOP_POINT;
  public final static int D3DOP_PROCESSVERTICES;
  public final static int D3DOP_SETSTATUS;
  public final static int D3DOP_SPAN;
  public final static int D3DOP_STATELIGHT;
  public final static int D3DOP_STATERENDER;
  public final static int D3DOP_STATETRANSFORM;
  public final static int D3DOP_TEXTURELOAD;
  public final static int D3DOP_TRIANGLE;
  public final static int D3DPAL_FREE;
  public final static int D3DPAL_READONLY;
  public final static int D3DPAL_RESERVED;
  public final static int D3DPBLENDCAPS_BOTHINVSRCALPHA;
  public final static int D3DPBLENDCAPS_BOTHSRCALPHA;
  public final static int D3DPBLENDCAPS_DESTALPHA;
  public final static int D3DPBLENDCAPS_DESTCOLOR;
  public final static int D3DPBLENDCAPS_INVDESTALPHA;
  public final static int D3DPBLENDCAPS_INVDESTCOLOR;
  public final static int D3DPBLENDCAPS_INVSRCALPHA;
  public final static int D3DPBLENDCAPS_INVSRCCOLOR;
  public final static int D3DPBLENDCAPS_ONE;
  public final static int D3DPBLENDCAPS_SRCALPHA;
  public final static int D3DPBLENDCAPS_SRCALPHASAT;
  public final static int D3DPBLENDCAPS_SRCCOLOR;
  public final static int D3DPBLENDCAPS_ZERO;
  public final static int D3DPCMPCAPS_ALWAYS;
  public final static int D3DPCMPCAPS_EQUAL;
  public final static int D3DPCMPCAPS_GREATER;
  public final static int D3DPCMPCAPS_GREATEREQUAL;
  public final static int D3DPCMPCAPS_LESS;
  public final static int D3DPCMPCAPS_LESSEQUAL;
  public final static int D3DPCMPCAPS_NEVER;
  public final static int D3DPCMPCAPS_NOTEQUAL;
  public final static int D3DPMISCCAPS_CONFORMANT;
  public final static int D3DPMISCCAPS_CULLCCW;
  public final static int D3DPMISCCAPS_CULLCW;
  public final static int D3DPMISCCAPS_CULLNONE;
  public final static int D3DPMISCCAPS_LINEPATTERNREP;
  public final static int D3DPMISCCAPS_MASKPLANES;
  public final static int D3DPMISCCAPS_MASKZ;
  public final static int D3DPRASTERCAPS_DITHER;
  public final static int D3DPRASTERCAPS_FOGTABLE;
  public final static int D3DPRASTERCAPS_FOGVERTEX;
  public final static int D3DPRASTERCAPS_PAT;
  public final static int D3DPRASTERCAPS_ROP2;
  public final static int D3DPRASTERCAPS_STIPPLE;
  public final static int D3DPRASTERCAPS_SUBPIXEL;
  public final static int D3DPRASTERCAPS_SUBPIXELX;
  public final static int D3DPRASTERCAPS_XOR;
  public final static int D3DPRASTERCAPS_ZTEST;
  public final static int D3DPROCESSVERTICES_COPY;
  public final static int D3DPROCESSVERTICES_NOCOLOR;
  public final static int D3DPROCESSVERTICES_OPMASK;
  public final static int D3DPROCESSVERTICES_TRANSFORM;
  public final static int D3DPROCESSVERTICES_TRANSFORMLIGHT;
  public final static int D3DPROCESSVERTICES_UPDATEEXTENTS;
  public final static int D3DPSHADECAPS_ALPHAFLATBLEND;
  public final static int D3DPSHADECAPS_ALPHAFLATSTIPPLED;
  public final static int D3DPSHADECAPS_ALPHAGOURAUDBLEND;
  public final static int D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED;
  public final static int D3DPSHADECAPS_ALPHAPHONGBLEND;
  public final static int D3DPSHADECAPS_ALPHAPHONGSTIPPLED;
  public final static int D3DPSHADECAPS_COLORFLATMONO;
  public final static int D3DPSHADECAPS_COLORFLATRGB;
  public final static int D3DPSHADECAPS_COLORGOURAUDMONO;
  public final static int D3DPSHADECAPS_COLORGOURAUDRGB;
  public final static int D3DPSHADECAPS_COLORPHONGMONO;
  public final static int D3DPSHADECAPS_COLORPHONGRGB;
  public final static int D3DPSHADECAPS_FOGFLAT;
  public final static int D3DPSHADECAPS_FOGGOURAUD;
  public final static int D3DPSHADECAPS_FOGPHONG;
  public final static int D3DPSHADECAPS_SPECULARFLATMONO;
  public final static int D3DPSHADECAPS_SPECULARFLATRGB;
  public final static int D3DPSHADECAPS_SPECULARGOURAUDMONO;
  public final static int D3DPSHADECAPS_SPECULARGOURAUDRGB;
  public final static int D3DPSHADECAPS_SPECULARPHONGMONO;
  public final static int D3DPSHADECAPS_SPECULARPHONGRGB;
  public final static int D3DPTADDRESSCAPS_CLAMP;
  public final static int D3DPTADDRESSCAPS_MIRROR;
  public final static int D3DPTADDRESSCAPS_WRAP;
  public final static int D3DPTBLENDCAPS_COPY;
  public final static int D3DPTBLENDCAPS_DECAL;
  public final static int D3DPTBLENDCAPS_DECALALPHA;
  public final static int D3DPTBLENDCAPS_DECALMASK;
  public final static int D3DPTBLENDCAPS_MODULATE;
  public final static int D3DPTBLENDCAPS_MODULATEALPHA;
  public final static int D3DPTBLENDCAPS_MODULATEMASK;
  public final static int D3DPTEXTURECAPS_ALPHA;
  public final static int D3DPTEXTURECAPS_BORDER;
  public final static int D3DPTEXTURECAPS_PERSPECTIVE;
  public final static int D3DPTEXTURECAPS_POW2;
  public final static int D3DPTEXTURECAPS_SQUAREONLY;
  public final static int D3DPTEXTURECAPS_TRANSPARENCY;
  public final static int D3DPTFILTERCAPS_LINEAR;
  public final static int D3DPTFILTERCAPS_LINEARMIPLINEAR;
  public final static int D3DPTFILTERCAPS_LINEARMIPNEAREST;
  public final static int D3DPTFILTERCAPS_MIPLINEAR;
  public final static int D3DPTFILTERCAPS_MIPNEAREST;
  public final static int D3DPTFILTERCAPS_NEAREST;
  public final static int D3DRENDERSTATE_ALPHAFUNC;
  public final static int D3DRENDERSTATE_ALPHAREF;
  public final static int D3DRENDERSTATE_ALPHATESTENABLE;
  public final static int D3DRENDERSTATE_ANTIALIAS;
  public final static int D3DRENDERSTATE_BLENDENABLE;
  public final static int D3DRENDERSTATE_CULLMODE;
  public final static int D3DRENDERSTATE_DESTBLEND;
  public final static int D3DRENDERSTATE_DITHERENABLE;
  public final static int D3DRENDERSTATE_FILLMODE;
  public final static int D3DRENDERSTATE_FOGCOLOR;
  public final static int D3DRENDERSTATE_FOGENABLE;
  public final static int D3DRENDERSTATE_FOGTABLEDENSITY;
  public final static int D3DRENDERSTATE_FOGTABLEEND;
  public final static int D3DRENDERSTATE_FOGTABLEMODE;
  public final static int D3DRENDERSTATE_FOGTABLESTART;
  public final static int D3DRENDERSTATE_LASTPIXEL;
  public final static int D3DRENDERSTATE_LINEPATTERN;
  public final static int D3DRENDERSTATE_MONOENABLE;
  public final static int D3DRENDERSTATE_PLANEMASK;
  public final static int D3DRENDERSTATE_ROP2;
  public final static int D3DRENDERSTATE_SHADEMODE;
  public final static int D3DRENDERSTATE_SPECULARENABLE;
  public final static int D3DRENDERSTATE_SRCBLEND;
  public final static int D3DRENDERSTATE_STIPPLEDALPHA;
  public final static int D3DRENDERSTATE_STIPPLEENABLE;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN00;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN01;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN02;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN03;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN04;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN05;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN06;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN07;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN08;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN09;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN10;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN11;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN12;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN13;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN14;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN15;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN16;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN17;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN18;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN19;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN20;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN21;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN22;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN23;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN24;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN25;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN26;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN27;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN28;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN29;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN30;
  public final static int D3DRENDERSTATE_STIPPLEPATTERN31;
  public final static int D3DRENDERSTATE_SUBPIXEL;
  public final static int D3DRENDERSTATE_SUBPIXELX;
  public final static int D3DRENDERSTATE_TEXTUREADDRESS;
  public final static int D3DRENDERSTATE_TEXTUREHANDLE;
  public final static int D3DRENDERSTATE_TEXTUREMAG;
  public final static int D3DRENDERSTATE_TEXTUREMAPBLEND;
  public final static int D3DRENDERSTATE_TEXTUREMIN;
  public final static int D3DRENDERSTATE_TEXTUREPERSPECTIVE;
  public final static int D3DRENDERSTATE_WRAPU;
  public final static int D3DRENDERSTATE_WRAPV;
  public final static int D3DRENDERSTATE_ZENABLE;
  public final static int D3DRENDERSTATE_ZFUNC;
  public final static int D3DRENDERSTATE_ZVISIBLE;
  public final static int D3DRENDERSTATE_ZWRITEENABLE;
  public final static int D3DRMANIMATION_CLOSED;
  public final static int D3DRMANIMATION_LINEARPOSITION;
  public final static int D3DRMANIMATION_OPEN;
  public final static int D3DRMANIMATION_POSITION;
  public final static int D3DRMANIMATION_SCALEANDROTATION;
  public final static int D3DRMANIMATION_SPLINEPOSITION;
  public final static int D3DRMCOLOR_FROMFACE;
  public final static int D3DRMCOLOR_FROMVERTEX;
  public final static int D3DRMCOMBINE_AFTER;
  public final static int D3DRMCOMBINE_BEFORE;
  public final static int D3DRMCOMBINE_REPLACE;
  public final static int D3DRMCONSTRAIN_X;
  public final static int D3DRMCONSTRAIN_Y;
  public final static int D3DRMCONSTRAIN_Z;
  public final static int D3DRMFILL_MASK;
  public final static int D3DRMFILL_MAX;
  public final static int D3DRMFILL_POINTS;
  public final static int D3DRMFILL_SOLID;
  public final static int D3DRMFILL_WIREFRAME;
  public final static int D3DRMFOG_EXPONENTIAL;
  public final static int D3DRMFOG_EXPONENTIALSQUARED;
  public final static int D3DRMFOG_LINEAR;
  public final static int D3DRMLIGHT_AMBIENT;
  public final static int D3DRMLIGHT_DIRECTIONAL;
  public final static int D3DRMLIGHT_MASK;
  public final static int D3DRMLIGHT_MAX;
  public final static int D3DRMLIGHT_OFF;
  public final static int D3DRMLIGHT_ON;
  public final static int D3DRMLIGHT_PARALLELPOINT;
  public final static int D3DRMLIGHT_POINT;
  public final static int D3DRMLIGHT_SPOT;
  public final static int D3DRMLOAD_BYGUID;
  public final static int D3DRMLOAD_BYNAME;
  public final static int D3DRMLOAD_BYPOSITION;
  public final static int D3DRMLOAD_FIRST;
  public final static int D3DRMLOAD_FROMFILE;
  public final static int D3DRMLOAD_FROMMEMORY;
  public final static int D3DRMLOAD_FROMRESOURCE;
  public final static int D3DRMLOAD_FROMSTREAM;
  public final static int D3DRMLOAD_INSTANCEBYCOPYING;
  public final static int D3DRMLOAD_INSTANCEBYREFERENCE;
  public final static int D3DRMMATERIAL_FROMFRAME;
  public final static int D3DRMMATERIAL_FROMMESH;
  public final static int D3DRMMATERIAL_FROMPARENT;
  public final static int D3DRMPALETTE_FREE;
  public final static int D3DRMPALETTE_READONLY;
  public final static int D3DRMPALETTE_RESERVED;
  public final static int D3DRMPROJECT_ORTHOGRAPHIC;
  public final static int D3DRMPROJECT_PERSPECTIVE;
  public final static int D3DRMRENDER_FLAT;
  public final static int D3DRMRENDER_GOURAUD;
  public final static int D3DRMRENDER_PHONG;
  public final static int D3DRMRENDER_UNLITFLAT;
  public final static int D3DRMRENDER_WIREFRAME;
  public final static int D3DRMSHADE_FLAT;
  public final static int D3DRMSHADE_GOURAUD;
  public final static int D3DRMSHADE_MASK;
  public final static int D3DRMSHADE_MAX;
  public final static int D3DRMSHADE_PHONG;
  public final static int D3DRMSORT_BACKTOFRONT;
  public final static int D3DRMSORT_FROMPARENT;
  public final static int D3DRMSORT_FRONTTOBACK;
  public final static int D3DRMSORT_NONE;
  public final static int D3DRMTEXTURE_LINEAR;
  public final static int D3DRMTEXTURE_LINEARMIPLINEAR;
  public final static int D3DRMTEXTURE_LINEARMIPNEAREST;
  public final static int D3DRMTEXTURE_MIPLINEAR;
  public final static int D3DRMTEXTURE_MIPNEAREST;
  public final static int D3DRMTEXTURE_NEAREST;
  public final static int D3DRMWIREFRAME_CULL;
  public final static int D3DRMWIREFRAME_HIDDENLINE;
  public final static int D3DRMWRAP_CHROME;
  public final static int D3DRMWRAP_CYLINDER;
  public final static int D3DRMWRAP_FLAT;
  public final static int D3DRMWRAP_SPHERE;
  public final static int D3DRMXOF_BINARY;
  public final static int D3DRMXOF_COMPRESSED;
  public final static int D3DRMXOF_TEXT;
  public final static int D3DRMXOFSAVE_ALL;
  public final static int D3DRMXOFSAVE_MATERIALS;
  public final static int D3DRMXOFSAVE_NORMALS;
  public final static int D3DRMXOFSAVE_TEMPLATES;
  public final static int D3DRMXOFSAVE_TEXTURECOORDINATES;
  public final static int D3DRMXOFSAVE_TEXTURENAMES;
  public final static int D3DRMZBUFFER_DISABLE;
  public final static int D3DRMZBUFFER_ENABLE;
  public final static int D3DRMZBUFFER_FROMPARENT;
  public final static int D3DSETSTATUS_ALL;
  public final static int D3DSETSTATUS_EXTENTS;
  public final static int D3DSETSTATUS_STATUS;
  public final static int D3DSHADE_FLAT;
  public final static int D3DSHADE_GOURAUD;
  public final static int D3DSHADE_PHONG;
  public final static int D3DSTATE_OVERRIDE_BIAS;
  public final static int D3DSTATUS_CLIPINTERSECTIONALL;
  public final static int D3DSTATUS_CLIPINTERSECTIONBACK;
  public final static int D3DSTATUS_CLIPINTERSECTIONBOTTOM;
  public final static int D3DSTATUS_CLIPINTERSECTIONFRONT;
  public final static int D3DSTATUS_CLIPINTERSECTIONGEN0;
  public final static int D3DSTATUS_CLIPINTERSECTIONGEN1;
  public final static int D3DSTATUS_CLIPINTERSECTIONGEN2;
  public final static int D3DSTATUS_CLIPINTERSECTIONGEN3;
  public final static int D3DSTATUS_CLIPINTERSECTIONGEN4;
  public final static int D3DSTATUS_CLIPINTERSECTIONGEN5;
  public final static int D3DSTATUS_CLIPINTERSECTIONLEFT;
  public final static int D3DSTATUS_CLIPINTERSECTIONRIGHT;
  public final static int D3DSTATUS_CLIPINTERSECTIONTOP;
  public final static int D3DSTATUS_CLIPUNIONALL;
  public final static int D3DSTATUS_CLIPUNIONBACK;
  public final static int D3DSTATUS_CLIPUNIONBOTTOM;
  public final static int D3DSTATUS_CLIPUNIONFRONT;
  public final static int D3DSTATUS_CLIPUNIONGEN0;
  public final static int D3DSTATUS_CLIPUNIONGEN1;
  public final static int D3DSTATUS_CLIPUNIONGEN2;
  public final static int D3DSTATUS_CLIPUNIONGEN3;
  public final static int D3DSTATUS_CLIPUNIONGEN4;
  public final static int D3DSTATUS_CLIPUNIONGEN5;
  public final static int D3DSTATUS_CLIPUNIONLEFT;
  public final static int D3DSTATUS_CLIPUNIONRIGHT;
  public final static int D3DSTATUS_CLIPUNIONTOP;
  public final static int D3DSTATUS_DEFAULT;
  public final static int D3DSTATUS_ZNOTVISIBLE;
  public final static int D3DTADDRESS_CLAMP;
  public final static int D3DTADDRESS_MIRROR;
  public final static int D3DTADDRESS_WRAP;
  public final static int D3DTBLEND_COPY;
  public final static int D3DTBLEND_DECAL;
  public final static int D3DTBLEND_DECALALPHA;
  public final static int D3DTBLEND_DECALMASK;
  public final static int D3DTBLEND_MODULATE;
  public final static int D3DTBLEND_MODULATEALPHA;
  public final static int D3DTBLEND_MODULATEMASK;
  public final static int D3DTRANSFORM_CLIPPED;
  public final static int D3DTRANSFORM_UNCLIPPED;
  public final static int D3DTRANSFORMSTATE_PROJECTION;
  public final static int D3DTRANSFORMSTATE_VIEW;
  public final static int D3DTRANSFORMSTATE_WORLD;
  public final static short D3DTRIFLAG_EDGEENABLE1;
  public final static short D3DTRIFLAG_EDGEENABLE2;
  public final static short D3DTRIFLAG_EDGEENABLE3;
  public final static short D3DTRIFLAG_EDGEENABLETRIANGLE;
  public final static short D3DTRIFLAG_EVEN;
  public final static short D3DTRIFLAG_ODD;
  public final static short D3DTRIFLAG_START;
  public final static int DD_OK;
  public final static int DDBD_1;
  public final static int DDBD_16;
  public final static int DDBD_2;
  public final static int DDBD_24;
  public final static int DDBD_32;
  public final static int DDBD_4;
  public final static int DDBD_8;
  public final static int DDBLT_ALPHADEST;
  public final static int DDBLT_ALPHADESTCONSTOVERRIDE;
  public final static int DDBLT_ALPHADESTNEG;
  public final static int DDBLT_ALPHADESTSURFACEOVERRIDE;
  public final static int DDBLT_ALPHAEDGEBLEND;
  public final static int DDBLT_ALPHASRC;
  public final static int DDBLT_ALPHASRCCONSTOVERRIDE;
  public final static int DDBLT_ALPHASRCNEG;
  public final static int DDBLT_ALPHASRCSURFACEOVERRIDE;
  public final static int DDBLT_ASYNC;
  public final static int DDBLT_COLORFILL;
  public final static int DDBLT_DDFX;
  public final static int DDBLT_DDROPS;
  public final static int DDBLT_DEPTHFILL;
  public final static int DDBLT_KEYDEST;
  public final static int DDBLT_KEYDESTOVERRIDE;
  public final static int DDBLT_KEYSRC;
  public final static int DDBLT_KEYSRCOVERRIDE;
  public final static int DDBLT_ROP;
  public final static int DDBLT_ROTATIONANGLE;
  public final static int DDBLT_WAIT;
  public final static int DDBLT_ZBUFFER;
  public final static int DDBLT_ZBUFFERDESTCONSTOVERRIDE;
  public final static int DDBLT_ZBUFFERDESTOVERRIDE;
  public final static int DDBLT_ZBUFFERSRCCONSTOVERRIDE;
  public final static int DDBLT_ZBUFFERSRCOVERRIDE;
  public final static int DDBLTFAST_DESTCOLORKEY;
  public final static int DDBLTFAST_NOCOLORKEY;
  public final static int DDBLTFAST_SRCCOLORKEY;
  public final static int DDBLTFAST_WAIT;
  public final static int DDBLTFX_ARITHSTRETCHY;
  public final static int DDBLTFX_MIRRORLEFTRIGHT;
  public final static int DDBLTFX_MIRRORUPDOWN;
  public final static int DDBLTFX_NOTEARING;
  public final static int DDBLTFX_ROTATE180;
  public final static int DDBLTFX_ROTATE270;
  public final static int DDBLTFX_ROTATE90;
  public final static int DDBLTFX_ZBUFFERBASEDEST;
  public final static int DDBLTFX_ZBUFFERRANGE;
  public final static int DDCAPS_3D;
  public final static int DDCAPS_ALIGNBOUNDARYDEST;
  public final static int DDCAPS_ALIGNBOUNDARYSRC;
  public final static int DDCAPS_ALIGNSIZEDEST;
  public final static int DDCAPS_ALIGNSIZESRC;
  public final static int DDCAPS_ALIGNSTRIDE;
  public final static int DDCAPS_ALPHA;
  public final static int DDCAPS_BANKSWITCHED;
  public final static int DDCAPS_BLT;
  public final static int DDCAPS_BLTCOLORFILL;
  public final static int DDCAPS_BLTDEPTHFILL;
  public final static int DDCAPS_BLTFOURCC;
  public final static int DDCAPS_BLTQUEUE;
  public final static int DDCAPS_BLTSTRETCH;
  public final static int DDCAPS_CANBLTSYSMEM;
  public final static int DDCAPS_CANCLIP;
  public final static int DDCAPS_CANCLIPSTRETCHED;
  public final static int DDCAPS_COLORKEY;
  public final static int DDCAPS_COLORKEYHWASSIST;
  public final static int DDCAPS_GDI;
  public final static int DDCAPS_NOHARDWARE;
  public final static int DDCAPS_OVERLAY;
  public final static int DDCAPS_OVERLAYCANTCLIP;
  public final static int DDCAPS_OVERLAYFOURCC;
  public final static int DDCAPS_OVERLAYSTRETCH;
  public final static int DDCAPS_PALETTE;
  public final static int DDCAPS_PALETTEVSYNC;
  public final static int DDCAPS_READSCANLINE;
  public final static int DDCAPS_STEREOVIEW;
  public final static int DDCAPS_VBI;
  public final static int DDCAPS_ZBLTS;
  public final static int DDCAPS_ZOVERLAYS;
  public final static int DDCAPS2_CERTIFIED;
  public final static int DDCAPS2_NO2DDURING3DSCENE;
  public final static int DDCKEY_COLORSPACE;
  public final static int DDCKEY_DESTBLT;
  public final static int DDCKEY_DESTOVERLAY;
  public final static int DDCKEY_SRCBLT;
  public final static int DDCKEY_SRCOVERLAY;
  public final static int DDCKEYCAPS_DESTBLT;
  public final static int DDCKEYCAPS_DESTBLTCLRSPACE;
  public final static int DDCKEYCAPS_DESTBLTCLRSPACEYUV;
  public final static int DDCKEYCAPS_DESTBLTYUV;
  public final static int DDCKEYCAPS_DESTOVERLAY;
  public final static int DDCKEYCAPS_DESTOVERLAYCLRSPACE;
  public final static int DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV;
  public final static int DDCKEYCAPS_DESTOVERLAYONEACTIVE;
  public final static int DDCKEYCAPS_DESTOVERLAYYUV;
  public final static int DDCKEYCAPS_NOCOSTOVERLAY;
  public final static int DDCKEYCAPS_SRCBLT;
  public final static int DDCKEYCAPS_SRCBLTCLRSPACE;
  public final static int DDCKEYCAPS_SRCBLTCLRSPACEYUV;
  public final static int DDCKEYCAPS_SRCBLTYUV;
  public final static int DDCKEYCAPS_SRCOVERLAY;
  public final static int DDCKEYCAPS_SRCOVERLAYCLRSPACE;
  public final static int DDCKEYCAPS_SRCOVERLAYCLRSPACEYUV;
  public final static int DDCKEYCAPS_SRCOVERLAYONEACTIVE;
  public final static int DDCKEYCAPS_SRCOVERLAYYUV;
  public final static int DDCOOPERATIVE_CLIPTOCOMPONENT;
  public final static int DDCOOPERATIVE_OFFSETTOCOMPONENT;
  public final static int DDCREATE_EMULATIONONLY;
  public final static int DDCREATE_HARDWAREONLY;
  public final static int DDEDM_REFRESHRATES;
  public final static int DDENUMOVERLAYZ_BACKTOFRONT;
  public final static int DDENUMOVERLAYZ_FRONTTOBACK;
  public final static int DDENUMSURFACES_ALL;
  public final static int DDENUMSURFACES_CANBECREATED;
  public final static int DDENUMSURFACES_DOESEXIST;
  public final static int DDENUMSURFACES_MATCH;
  public final static int DDENUMSURFACES_NOMATCH;
  public final static int DDERR_SURFACELOST;
  public final static int DDERR_WASSTILLDRAWING;
  public final static int DDFLIP_WAIT;
  public final static int DDFXALPHACAPS_BLTALPHAEDGEBLEND;
  public final static int DDFXALPHACAPS_BLTALPHAPIXELS;
  public final static int DDFXALPHACAPS_BLTALPHAPIXELSNEG;
  public final static int DDFXALPHACAPS_BLTALPHASURFACES;
  public final static int DDFXALPHACAPS_BLTALPHASURFACESNEG;
  public final static int DDFXALPHACAPS_OVERLAYALPHAEDGEBLEND;
  public final static int DDFXALPHACAPS_OVERLAYALPHAPIXELS;
  public final static int DDFXALPHACAPS_OVERLAYALPHAPIXELSNEG;
  public final static int DDFXALPHACAPS_OVERLAYALPHASURFACES;
  public final static int DDFXALPHACAPS_OVERLAYALPHASURFACESNEG;
  public final static int DDFXCAPS_BLTARITHSTRETCHY;
  public final static int DDFXCAPS_BLTARITHSTRETCHYN;
  public final static int DDFXCAPS_BLTMIRRORLEFTRIGHT;
  public final static int DDFXCAPS_BLTMIRRORUPDOWN;
  public final static int DDFXCAPS_BLTROTATION;
  public final static int DDFXCAPS_BLTROTATION90;
  public final static int DDFXCAPS_BLTSHRINKX;
  public final static int DDFXCAPS_BLTSHRINKXN;
  public final static int DDFXCAPS_BLTSHRINKY;
  public final static int DDFXCAPS_BLTSHRINKYN;
  public final static int DDFXCAPS_BLTSTRETCHX;
  public final static int DDFXCAPS_BLTSTRETCHXN;
  public final static int DDFXCAPS_BLTSTRETCHY;
  public final static int DDFXCAPS_BLTSTRETCHYN;
  public final static int DDFXCAPS_OVERLAYARITHSTRETCHY;
  public final static int DDFXCAPS_OVERLAYARITHSTRETCHYN;
  public final static int DDFXCAPS_OVERLAYMIRRORLEFTRIGHT;
  public final static int DDFXCAPS_OVERLAYMIRRORUPDOWN;
  public final static int DDFXCAPS_OVERLAYSHRINKX;
  public final static int DDFXCAPS_OVERLAYSHRINKXN;
  public final static int DDFXCAPS_OVERLAYSHRINKY;
  public final static int DDFXCAPS_OVERLAYSHRINKYN;
  public final static int DDFXCAPS_OVERLAYSTRETCHX;
  public final static int DDFXCAPS_OVERLAYSTRETCHXN;
  public final static int DDFXCAPS_OVERLAYSTRETCHY;
  public final static int DDFXCAPS_OVERLAYSTRETCHYN;
  public final static int DDGBS_CANBLT;
  public final static int DDGBS_ISBLTDONE;
  public final static int DDGFS_CANFLIP;
  public final static int DDGFS_ISFLIPDONE;
  public final static int DDLOCK_EVENT;
  public final static int DDLOCK_READONLY;
  public final static int DDLOCK_SURFACEMEMORYPTR;
  public final static int DDLOCK_WAIT;
  public final static int DDLOCK_WRITEONLY;
  public final static int DDOVER_ADDDIRTYRECT;
  public final static int DDOVER_ALPHADEST;
  public final static int DDOVER_ALPHADESTCONSTOVERRIDE;
  public final static int DDOVER_ALPHADESTNEG;
  public final static int DDOVER_ALPHADESTSURFACEOVERRIDE;
  public final static int DDOVER_ALPHAEDGEBLEND;
  public final static int DDOVER_ALPHASRC;
  public final static int DDOVER_ALPHASRCCONSTOVERRIDE;
  public final static int DDOVER_ALPHASRCNEG;
  public final static int DDOVER_ALPHASRCSURFACEOVERRIDE;
  public final static int DDOVER_DDFX;
  public final static int DDOVER_HIDE;
  public final static int DDOVER_KEYDEST;
  public final static int DDOVER_KEYDESTOVERRIDE;
  public final static int DDOVER_KEYSRC;
  public final static int DDOVER_KEYSRCOVERRIDE;
  public final static int DDOVER_REFRESHALL;
  public final static int DDOVER_REFRESHDIRTYRECTS;
  public final static int DDOVER_SHOW;
  public final static int DDOVERFX_ARITHSTRETCHY;
  public final static int DDOVERFX_MIRRORLEFTRIGHT;
  public final static int DDOVERFX_MIRRORUPDOWN;
  public final static int DDOVERZ_INSERTINBACKOF;
  public final static int DDOVERZ_INSERTINFRONTOF;
  public final static int DDOVERZ_MOVEBACKWARD;
  public final static int DDOVERZ_MOVEFORWARD;
  public final static int DDOVERZ_SENDTOBACK;
  public final static int DDOVERZ_SENDTOFRONT;
  public final static int DDPCAPS_1BIT;
  public final static int DDPCAPS_2BIT;
  public final static int DDPCAPS_4BIT;
  public final static int DDPCAPS_8BIT;
  public final static int DDPCAPS_8BITENTRIES;
  public final static int DDPCAPS_ALLOW256;
  public final static int DDPCAPS_INITIALIZE;
  public final static int DDPCAPS_PRIMARYSURFACE;
  public final static int DDPCAPS_PRIMARYSURFACELEFT;
  public final static int DDPCAPS_VSYNC;
  public final static int DDPF_ALPHA;
  public final static int DDPF_ALPHAPIXELS;
  public final static int DDPF_COMPRESSED;
  public final static int DDPF_FOURCC;
  public final static int DDPF_PALETTEINDEXED1;
  public final static int DDPF_PALETTEINDEXED2;
  public final static int DDPF_PALETTEINDEXED4;
  public final static int DDPF_PALETTEINDEXED8;
  public final static int DDPF_PALETTEINDEXEDTO8;
  public final static int DDPF_RGB;
  public final static int DDPF_RGBTOYUV;
  public final static int DDPF_YUV;
  public final static int DDPF_ZBUFFER;
  public final static int DDSCAPS_3D;
  public final static int DDSCAPS_3DDEVICE;
  public final static int DDSCAPS_ALLOCONLOAD;
  public final static int DDSCAPS_ALPHA;
  public final static int DDSCAPS_BACKBUFFER;
  public final static int DDSCAPS_COMPLEX;
  public final static int DDSCAPS_FLIP;
  public final static int DDSCAPS_FRONTBUFFER;
  public final static int DDSCAPS_HWCODEC;
  public final static int DDSCAPS_LIVEVIDEO;
  public final static int DDSCAPS_MIPMAP;
  public final static int DDSCAPS_MODEX;
  public final static int DDSCAPS_OFFSCREENPLAIN;
  public final static int DDSCAPS_OVERLAY;
  public final static int DDSCAPS_OWNDC;
  public final static int DDSCAPS_PALETTE;
  public final static int DDSCAPS_PRIMARYSURFACE;
  public final static int DDSCAPS_PRIMARYSURFACELEFT;
  public final static int DDSCAPS_SYSTEMMEMORY;
  public final static int DDSCAPS_TEXTURE;
  public final static int DDSCAPS_VIDEOMEMORY;
  public final static int DDSCAPS_VISIBLE;
  public final static int DDSCAPS_WRITEONLY;
  public final static int DDSCAPS_ZBUFFER;
  public final static int DDSCL_ALLOWMODEX;
  public final static int DDSCL_ALLOWREBOOT;
  public final static int DDSCL_EXCLUSIVE;
  public final static int DDSCL_FULLSCREEN;
  public final static int DDSCL_NORMAL;
  public final static int DDSCL_NOWINDOWCHANGES;
  public final static int DDSD_ALL;
  public final static int DDSD_ALPHABITDEPTH;
  public final static int DDSD_BACKBUFFERCOUNT;
  public final static int DDSD_CAPS;
  public final static int DDSD_CKDESTBLT;
  public final static int DDSD_CKDESTOVERLAY;
  public final static int DDSD_CKSRCBLT;
  public final static int DDSD_CKSRCOVERLAY;
  public final static int DDSD_HEIGHT;
  public final static int DDSD_MIPMAPCOUNT;
  public final static int DDSD_PITCH;
  public final static int DDSD_PIXELFORMAT;
  public final static int DDSD_REFRESHRATE;
  public final static int DDSD_WIDTH;
  public final static int DDSD_ZBUFFERBITDEPTH;
  public final static int DDSVCAPS_ENIGMA;
  public final static int DDSVCAPS_FLICKER;
  public final static int DDSVCAPS_REDBLUE;
  public final static int DDSVCAPS_SPLIT;
  public final static int DDWAITVB_BLOCKBEGIN;
  public final static int DDWAITVB_BLOCKBEGINEVENT;
  public final static int DDWAITVB_BLOCKEND;
  public final static int DPCAPS_GROUPOPTIMIZED;
  public final static int DPCAPS_GUARANTEEDOPTIMIZED;
  public final static int DPCAPS_GUARANTEEDSUPPORTED;
  public final static int DPCAPS_ISHOST;
  public final static int DPCAPS_KEEPALIVEOPTIMIZED;
  public final static int DPCPA_DTRFLOW;
  public final static int DPCPA_NOFLOW;
  public final static int DPCPA_RTSDTRFLOW;
  public final static int DPCPA_RTSFLOW;
  public final static int DPCPA_XONXOFFFLOW;
  public final static int DPENUMPLAYERS_ALL;
  public final static int DPENUMPLAYERS_GROUP;
  public final static int DPENUMPLAYERS_LOCAL;
  public final static int DPENUMPLAYERS_REMOTE;
  public final static int DPENUMPLAYERS_SESSION;
  public final static int DPENUMSESSIONS_ALL;
  public final static int DPENUMSESSIONS_AVAILABLE;
  public final static int DPESC_TIMEDOUT;
  public final static int DPGET_LOCAL;
  public final static int DPGET_REMOTE;
  public final static int DPGETCAPS_GUARANTEED;
  public final static int DPLAD_SYSTEM;
  public final static int DPLCONNECTION_CREATESESSION;
  public final static int DPLCONNECTION_JOINSESSION;
  public final static int DPLSYS_APPTERMINATED;
  public final static int DPLSYS_CONNECTIONSETTINGSREAD;
  public final static int DPLSYS_DPLAYCONNECTFAILED;
  public final static int DPLSYS_DPLAYCONNECTSUCCEEDED;
  public final static int DPOPEN_CREATE;
  public final static int DPOPEN_JOIN;
  public final static int DPPLAYERTYPE_GROUP;
  public final static int DPPLAYERTYPE_PLAYER;
  public final static int DPRECEIVE_ALL;
  public final static int DPRECEIVE_FROMPLAYER;
  public final static int DPRECEIVE_PEEK;
  public final static int DPRECEIVE_TOPLAYER;
  public final static int DPSEND_CLOSESTREAM;
  public final static int DPSEND_GUARANTEED;
  public final static int DPSEND_HIGHPRIORITY;
  public final static int DPSEND_OPENSTREAM;
  public final static int DPSESSION_JOINDISABLED;
  public final static int DPSESSION_KEEPALIVE;
  public final static int DPSESSION_MIGRATEHOST;
  public final static int DPSESSION_NEWPLAYERSDISABLED;
  public final static int DPSESSION_NODATAMESSAGES;
  public final static int DPSESSION_NOMESSAGEID;
  public final static int DPSET_GUARANTEED;
  public final static int DPSET_LOCAL;
  public final static int DPSET_REMOTE;
  public final static int DPSYS_ADDPLAYERTOGROUP;
  public final static int DPSYS_CREATEPLAYERORGROUP;
  public final static int DPSYS_DELETEPLAYERFROMGROUP;
  public final static int DPSYS_DESTROYPLAYERORGROUP;
  public final static int DPSYS_HOST;
  public final static int DPSYS_SESSIONLOST;
  public final static int DPSYS_SETPLAYERORGROUPDATA;
  public final static int DPSYS_SETPLAYERORGROUPNAME;
  public final static float DS3D_DEFAULTDISTANCEFACTOR;
  public final static float DS3D_DEFAULTDOPPLERFACTOR;
  public final static int DS3D_DEFERRED;
  public final static int DS3D_IMMEDIATE;
  public final static int DS3DMODE_DISABLE;
  public final static int DS3DMODE_HEADRELATIVE;
  public final static int DS3DMODE_NORMAL;
  public final static int DSBCAPS_CTRL3D;
  public final static int DSBCAPS_CTRLALL;
  public final static int DSBCAPS_CTRLDEFAULT;
  public final static int DSBCAPS_CTRLFREQUENCY;
  public final static int DSBCAPS_CTRLPAN;
  public final static int DSBCAPS_CTRLVOLUME;
  public final static int DSBCAPS_GETCURRENTPOSITION2;
  public final static int DSBCAPS_GLOBALFOCUS;
  public final static int DSBCAPS_LOCHARDWARE;
  public final static int DSBCAPS_LOCSOFTWARE;
  public final static int DSBCAPS_PRIMARYBUFFER;
  public final static int DSBCAPS_STATIC;
  public final static int DSBCAPS_STICKYFOCUS;
  public final static int DSBLOCK_FROMWRITECURSOR;
  public final static int DSBPLAY_LOOPING;
  public final static int DSBSTATUS_BUFFERLOST;
  public final static int DSBSTATUS_LOOPING;
  public final static int DSBSTATUS_PLAYING;
  public final static int DSCAPS_CERTIFIED;
  public final static int DSCAPS_CONTINUOUSRATE;
  public final static int DSCAPS_EMULDRIVER;
  public final static int DSCAPS_PRIMARY16BIT;
  public final static int DSCAPS_PRIMARY8BIT;
  public final static int DSCAPS_PRIMARYMONO;
  public final static int DSCAPS_PRIMARYSTEREO;
  public final static int DSCAPS_SECONDARY16BIT;
  public final static int DSCAPS_SECONDARY8BIT;
  public final static int DSCAPS_SECONDARYMONO;
  public final static int DSCAPS_SECONDARYSTEREO;
  public final static int DSSCL_EXCLUSIVE;
  public final static int DSSCL_NORMAL;
  public final static int DSSCL_PRIORITY;
  public final static int DSSCL_WRITEPRIMARY;
  public final static int DSSPEAKER_HEADPHONE;
  public final static int DSSPEAKER_MONO;
  public final static int DSSPEAKER_QUAD;
  public final static int DSSPEAKER_STEREO;
  public final static int DSSPEAKER_SURROUND;
  public final static int JOY_BUTTON1;
  public final static int JOY_BUTTON10;
  public final static int JOY_BUTTON11;
  public final static int JOY_BUTTON12;
  public final static int JOY_BUTTON13;
  public final static int JOY_BUTTON14;
  public final static int JOY_BUTTON15;
  public final static int JOY_BUTTON16;
  public final static int JOY_BUTTON17;
  public final static int JOY_BUTTON18;
  public final static int JOY_BUTTON19;
  public final static int JOY_BUTTON2;
  public final static int JOY_BUTTON20;
  public final static int JOY_BUTTON21;
  public final static int JOY_BUTTON22;
  public final static int JOY_BUTTON23;
  public final static int JOY_BUTTON24;
  public final static int JOY_BUTTON25;
  public final static int JOY_BUTTON26;
  public final static int JOY_BUTTON27;
  public final static int JOY_BUTTON28;
  public final static int JOY_BUTTON29;
  public final static int JOY_BUTTON3;
  public final static int JOY_BUTTON30;
  public final static int JOY_BUTTON31;
  public final static int JOY_BUTTON32;
  public final static int JOY_BUTTON4;
  public final static int JOY_BUTTON5;
  public final static int JOY_BUTTON6;
  public final static int JOY_BUTTON7;
  public final static int JOY_BUTTON8;
  public final static int JOY_BUTTON9;
  public final static int JOY_CAL_READ3;
  public final static int JOY_CAL_READ4;
  public final static int JOY_CAL_READ5;
  public final static int JOY_CAL_READ6;
  public final static int JOY_CAL_READALWAYS;
  public final static int JOY_CAL_READRONLY;
  public final static int JOY_CAL_READUONLY;
  public final static int JOY_CAL_READVONLY;
  public final static int JOY_CAL_READXONLY;
  public final static int JOY_CAL_READXYONLY;
  public final static int JOY_CAL_READYONLY;
  public final static int JOY_CAL_READZONLY;
  public final static int JOY_POVBACKWARD;
  public final static int JOY_POVCENTERED;
  public final static int JOY_POVFORWARD;
  public final static int JOY_POVLEFT;
  public final static int JOY_POVRIGHT;
  public final static int JOY_RETURNALL;
  public final static int JOY_RETURNBUTTONS;
  public final static int JOY_RETURNCENTERED;
  public final static int JOY_RETURNPOV;
  public final static int JOY_RETURNPOVCTS;
  public final static int JOY_RETURNR;
  public final static int JOY_RETURNRAWDATA;
  public final static int JOY_RETURNU;
  public final static int JOY_RETURNV;
  public final static int JOY_RETURNX;
  public final static int JOY_RETURNY;
  public final static int JOY_RETURNZ;
  public final static int JOY_USEDEADZONE;
  public final static short JOYCAPS_HASPOV;
  public final static short JOYCAPS_HASR;
  public final static short JOYCAPS_HASU;
  public final static short JOYCAPS_HASV;
  public final static short JOYCAPS_HASZ;
  public final static short JOYCAPS_POV4DIR;
  public final static short JOYCAPS_POVCTS;
  public final static int JOYERR_BASE;
  public final static int JOYERR_NOCANDO;
  public final static int JOYERR_NOERROR;
  public final static int JOYERR_PARMS;
  public final static int JOYERR_UNPLUGGED;
  public final static int JOYSTICKID1;
  public final static int JOYSTICKID2;
}


Fields (DirectXConstants Interface)

 Microsoft SDK for Java

DirectXConstants Interface Fields

The DirectXConstants Interface contains the following fields.

D3DBLEND_BOTHINVSRCALPHA | The destination blend selection is overridden when the source blend factor is (1-As, 1-As, 1-As, 1-As), and destination blend factor is (As, As, As, As).
D3DBLEND_BOTHSRCALPHA | The destination blend selection is overridden when the source blend factor is (As, As, As, As), and destination blend factor is (1-As, 1-As, 1-As, 1-As).
D3DBLEND_DESTALPHA | Blend factor is (Ad, Ad, Ad, Ad).
D3DBLEND_DESTCOLOR | Blend factor is (Rd, Gd, Bd, Ad).
D3DBLEND_INVDESTALPHA | Blend factor is (1-Ad, 1-Ad, 1-Ad, 1-Ad).
D3DBLEND_INVDESTCOLOR | Blend factor is (1-Rd, 1-Gd, 1-Bd, 1-Ad).
D3DBLEND_INVSRCALPHA | Blend factor is (1-As, 1-As, 1-As).
D3DBLEND_INVSRCCOLOR | Blend factor is (As, As, As, As, 1-As).
D3DBLEND_ONE | Blend factor is (1, 1, 1, 1).
D3DBLEND_SRCALPHA | Blend factor is (As, As, As, As).
D3DBLEND_SRCALPHASAT | Blend factor is (f, f, f, 1); f = min(As, 1-Ad).
D3DBLEND_SRCCOLOR | Blend factor is (Rs, Gs, Bs, As).
D3DBLEND_ZERO | Blend factor is (0, 0, 0, 0).
D3DCLEAR_TARGET | Clear the rendering target to the background material (if set).
D3DCLEAR_ZBUFFER | Clear the z-buffer or set it to the current background depth field (if set).
D3DCLIP_BACK | Clipped by the back plane of the viewing frustum.;
D3DCLIP_BOTTOM | Clipped by the bottom plane of the viewing frustum.
D3DCLIP_FRONT | Clipped by the front plane of the viewing frustum.
D3DCLIP_GEN0 | Application-defined clipping plane.
D3DCLIP_GEN1 | Application-defined clipping plane.
D3DCLIP_GEN2 | Application-defined clipping plane.
D3DCLIP_GEN3 | Application-defined clipping plane.
D3DCLIP_GEN4 | Application-defined clipping plane.
D3DCLIP_GEN5 | Application-defined clipping plane.
D3DCLIP_LEFT | Clipped by the left plane of the viewing frustum.
D3DCLIP_RIGHT | Clipped by the right plane of the viewing frustum.
D3DCLIP_TOP | Clipped by the top plane of the viewing frustum.
D3DCMP_ALWAYS | Always pass the test.
D3DCMP_EQUAL | Accept the new pixel if its value equals the value of the current pixel.
D3DCMP_GREATER | Accept the new pixel if its value is greater than the value of the current pixel.
D3DCMP_GREATEREQUAL | Accept the new pixel if its value is greater than or equal to the value of the current pixel.
D3DCMP_LESS | Accept the new pixel if its value is less than the value of the current pixel.
D3DCMP_LESSEQUAL | Accept the new pixel if its value is less than or equal to the value of the current pixel.
D3DCMP_NEVER | Always fail the test.
D3DCMP_NOTEQUAL | Accept the new pixel if its value does not equal the value of the current pixel.
D3DCOLOR_MONO | Use a monochromatic model (or ramp model). In this model, the blue component of a vertex color is used to define the brightness of a lit vertex.
D3DCOLOR_RGB | Use a full RGB model.
D3DCULL_CCW | Cull faces with counterclockwise vertices.
D3DCULL_CW | Cull faces with clockwise vertices.
D3DCULL_NONE | Do not cull faces.
D3DDD_BCLIPPING | The D3dDeviceDesc.clipping field is valid.
D3DDD_COLORMODEL | The D3dDeviceDesc.dcmColorModel field is valid.
D3DDD_DEVCAPS | The D3dDeviceDesc.devCaps field is valid.
D3DDD_DEVICERENDERBITDEPTH | The D3dDeviceDesc.deviceRenderBitDepth field is valid.
D3DDD_DEVICEZBUFFERBITDEPTH | The D3dDeviceDesc.deviceZBufferBitDepth field is valid.
D3DDD_LIGHTINGCAPS | The D3dDeviceDesc.dlcLightingCaps field is valid.
D3DDD_LINECAPS | Reserved.
D3DDD_MAXBUFFERSIZE | The D3dDeviceDesc.maxBufferSize field is valid.
D3DDD_MAXVERTEXCOUNT | The D3dDeviceDesc.maxVertexCount field is valid.
D3DDD_TRANSFORMCAPS | The D3dDeviceDesc.dtcTransformCaps field is valid.
D3DDD_TRICAPS | Reserved.
D3DDEB_BUFSIZE | The D3dExecuteBufferDesc.bufferSize field is valid.
D3DDEB_CAPS | The D3dExecuteBufferDesc.caps field is valid.
D3DDEB_LPDATA | The D3dExecuteBufferDesc.data field is valid.
D3DDEBCAPS_MEM | A logical OR of D3DDEBCAPS_SYSTEMMEMORY and D3DDEBCAPS_VIDEOMEMORY.
D3DDEBCAPS_SYSTEMMEMORY | The execute buffer data resides in system memory.
D3DDEBCAPS_VIDEOMEMORY | The execute buffer data resides in device memory.
D3DDEVCAPS_EXECUTESYSTEMMEMORY | Device can use execute buffers from system memory.
D3DDEVCAPS_EXECUTEVIDEOMEMORY | Device can use execute buffers from video memory.
D3DDEVCAPS_FLOATTLVERTEX | Device accepts floating point for post-transform vertex data.
D3DDEVCAPS_SORTDECREASINGZ | Device needs data sorted for decreasing depth.
D3DDEVCAPS_SORTEXACT | Device needs data sorted exactly.
D3DDEVCAPS_SORTINCREASINGZ | Device needs data sorted for increasing depth.
D3DDEVCAPS_TEXTURESYSTEMMEMORY | Device can retrieve textures from system memory.
D3DDEVCAPS_TEXTUREVIDEOMEMORY | Device can retrieves textures from device memory.
D3DDEVCAPS_TLVERTEXSYSTEMMEMORY | Device can use buffers from system memory for transformed and lit vertices.
D3DDEVCAPS_TLVERTEXVIDEOMEMORY | Device can use buffers from video memory for transformed and lit vertices.
D3DEXECUTE_CLIPPED | Clip any primitives in the buffer that are outside or partially outside the viewport.
D3DEXECUTE_UNCLIPPED | All primitives in the buffer are contained within the viewport.
D3DFDS_ALPHACMPCAPS | Match the D3dFindDeviceSearch.alphaCmpCaps field.
D3DFDS_COLORMODEL | Match the color model specified in the D3dFindDeviceSearch.dcmColorModel field.
D3DFDS_DSTBLENDCAPS | Match the D3dFindDeviceSearch.destBlendCaps field.
D3DFDS_GUID | Match the globally unique identifier (GUID).
D3DFDS_HARDWARE | Match the hardware or software search specification given in the D3dFindDeviceSearch.hardware field.
D3DFDS_LINES | Reserved.
D3DFDS_MISCCAPS | Match the D3dFindDeviceSearch.miscCaps field.
D3DFDS_RASTERCAPS | Match the D3dFindDeviceSearch.rasterCaps field.
D3DFDS_SHADECAPS | Match the D3dFindDeviceSearch.shadeCaps field.
D3DFDS_SRCBLENDCAPS | Match the D3dFindDeviceSearch.srcBlendCaps field.
D3DFDS_TEXTUREADDRESSCAPS | Match the D3dFindDeviceSearch.textureAddressCaps field.
D3DFDS_TEXTUREBLENDCAPS | Match the D3dFindDeviceSearch.textureBlendCaps field.
D3DFDS_TEXTURECAPS | Match the D3dFindDeviceSearch.textureCaps field.
D3DFDS_TEXTUREFILTERCAPS | Match the D3dFindDeviceSearch.textureFilterCaps field.
D3DFDS_TRIANGLES | Reserved.
D3DFDS_ZCMPCAPS | Match the D3dFindDeviceSearch.zCmpCaps field.
D3DFILL_POINT | Fill points.
D3DFILL_SOLID | Fill solid.
D3DFILL_WIREFRAME | Fill wire frames.
D3DFILTER_LINEAR | Weighted average of a 2-by-2 area of texels surrounding the desired pixel is used. This applies to both zooming in and zooming out. If either is supported, both zooming in and zooming out must be supported.
D3DFILTER_LINEARMIPLINEAR | Similar to D3DFILTER_MIPLINEAR, but interpolates between the two nearest mipmaps.
D3DFILTER_LINEARMIPNEAREST | Similar to D3DFILTER_MIPNEAREST, but interpolates between the two nearest mipmaps.
D3DFILTER_MIPLINEAR | Similar to D3DFILTER_LINEAR, but uses the appropriate mipmap for texel selection.
D3DFILTER_MIPNEAREST | Similar to D3DFILTER_NEAREST, but uses the appropriate mipmap for texel selection.
D3DFILTER_NEAREST | Texel with coordinates nearest to the desired pixel value is used. This applies to both zooming in and zooming out. If either zooming in or zooming out is supported, both must be supported.
D3DFOG_EXP | The fog effect intensifies exponentially.
D3DFOG_EXP2 | The fog effect intensifies exponentially with the square of the distance.
D3DFOG_LINEAR | The fog effect intensifies linearly between the start and end points.
D3DFOG_NONE | No fog effect.
D3DLIGHT_DIRECTIONAL | Light is a directional source.
D3DLIGHT_GLSPOT | Light is a GL-style spotlight.
D3DLIGHT_PARALLELPOINT | Light is a parallel point source.
D3DLIGHT_POINT | Light is a point source.
D3DLIGHT_SPOT | Light is a spotlight source.
D3DLIGHTSTATE_AMBIENT | Set the color and intensity of the current ambient light. If an application specifies this value, it should not specify a light as a parameter. The default value is 0.
D3DLIGHTSTATE_COLORMODEL | One value of D3DCOLOR_ type. The default value is D3DCOLOR_RGB.
D3DLIGHTSTATE_FOGDENSITY | Define the density setting for fog. The default value is 1.0.
D3DLIGHTSTATE_FOGEND | Define the ending value for fog. The default value is 100.0.
D3DLIGHTSTATE_FOGMODE | One value of D3DFOG_ type. The default value is D3DFOG_NONE.
D3DLIGHTSTATE_FOGSTART | Define the starting value for fog. The default value is 1.0.
D3DLIGHTSTATE_MATERIAL | Define the material that is lit and used to compute the final color and intensity values during rasterization. The default value is null.
D3DOP_BRANCHFORWARD | Enable a branching mechanism within the execute buffer.
D3DOP_EXIT | Signal that the end of the list has been reached.
D3DOP_LINE | Send a line to the renderer.
D3DOP_MATRIXLOAD | Trigger a data transfer in the rendering engine.
D3DOP_MATRIXMULTIPLY | Trigger a data transfer in the rendering engine.
D3DOP_POINT | Send a point to the renderer.
D3DOP_PROCESSVERTICES | Set both lighting and transformations for vertices.
D3DOP_SETSTATUS | Reset the status of the execute buffer.
D3DOP_SPAN | Span a list of points with the same y-value.
D3DOP_STATELIGHT | Set the value of internal state variables in the rendering engine for the lighting module. Operand data is a variable token and the new value. The token identifies the internal state variable, and the new value is the value to which that variable should be set.
D3DOP_STATERENDER | Set the value of internal state variables in the rendering engine for the rendering module. Operand data is a variable token and the new value. The token identifies the internal state variable, and the new value is the value to which that variable should be set.
D3DOP_STATETRANSFORM | Set the value of internal state variables in the rendering engine for the transformation module. Operand data is a variable token and the new value. The token identifies the internal state variable, and the new value is the value to which that variable should be set.
D3DOP_TEXTURELOAD | Trigger a data transfer in the rendering engine.
D3DOP_TRIANGLE | Send a triangle to the renderer.
D3DPAL_FREE | The renderer can use this entry freely.
D3DPAL_READONLY | The renderer cannot set this entry.
D3DPAL_RESERVED | The renderer cannot use this entry.
D3DPBLENDCAPS_BOTHINVSRCALPHA | The destination blend selection is overridden when the source blend factor is (1-As, 1-As, 1-As, 1-As) and destination blend factor is (As, As, As, As).
D3DPBLENDCAPS_BOTHSRCALPHA | The destination blend selection is overridden when the source blend factor is (As, As, As, As) and destination blend factor is (1-As, 1-As, 1-As, 1-As).
D3DPBLENDCAPS_DESTALPHA | Blend factor is (Ad, Ad, Ad, Ad).
D3DPBLENDCAPS_DESTCOLOR | Blend factor is (Rd, Gd, Bd, Ad).
D3DPBLENDCAPS_INVDESTALPHA | Blend factor is (1-Ad, 1-Ad, 1-Ad, 1-Ad).
D3DPBLENDCAPS_INVDESTCOLOR | Blend factor is (1-Rd, 1-Gd, 1-Bd, 1-Ad).
D3DPBLENDCAPS_INVSRCALPHA | Blend factor is (1-As, 1-As, 1-As, 1-As).
D3DPBLENDCAPS_INVSRCCOLOR | Blend factor is (1-Rd, 1-Gd, 1-Bd, 1-Ad).
D3DPBLENDCAPS_ONE | Blend factor is (1, 1, 1, 1).
D3DPBLENDCAPS_SRCALPHA | Blend factor is (As, As, As, As).
D3DPBLENDCAPS_SRCALPHASAT | Blend factor is (f, f, f, 1); f = min(As, 1-Ad).
D3DPBLENDCAPS_SRCCOLOR | Blend factor is (Rs, Gs, Bs, As).
D3DPBLENDCAPS_ZERO | Blend factor is (0, 0, 0, 0).
D3DPCMPCAPS_ALWAYS | Always pass the z-test.
D3DPCMPCAPS_EQUAL | Pass the z-test if the new z-value equals the current z-value.
D3DPCMPCAPS_GREATER | Pass the z-test if the new z-value is greater than the current z-value.
D3DPCMPCAPS_GREATEREQUAL | Pass the z-test if the new z-value is greater than or equal to the current z-value.
D3DPCMPCAPS_LESS | Pass the z-test if the new z-value is less than the current z-value.
D3DPCMPCAPS_LESSEQUAL | Pass the z-test if the new z-value is less than or equal to the current z-value.
D3DPCMPCAPS_NEVER | Always fail the z-test.
D3DPCMPCAPS_NOTEQUAL | Pass the z-test if the new z-value does not equal the current z-value.
D3DPMISCCAPS_CONFORMANT | The device conforms to the OpenGL standard.
D3DPMISCCAPS_CULLCCW | The driver supports counterclockwise culling through the D3DRENDERSTATE_CULLMODE state. (This applies only to triangle primitives.) This corresponds to the D3DCULL_CCW value.
D3DPMISCCAPS_CULLCW | The driver supports clockwise triangle culling through the D3DRENDERSTATE_CULLMODE state. (This applies only to triangle primitives.) This corresponds to the D3DCULL_CW value.
D3DPMISCCAPS_CULLNONE | The driver does not perform triangle culling. This corresponds to the D3DCULL_NONE value.
D3DPMISCCAPS_LINEPATTERNREP | Reserved.
D3DPMISCCAPS_MASKPLANES | The device can perform a bitmask of color planes.
D3DPMISCCAPS_MASKZ | The device can enable and disable modification of the z-buffer on pixel operations.
D3DPRASTERCAPS_DITHER | The device can dither to improve color resolution.
D3DPRASTERCAPS_FOGTABLE | The device calculates the fog value by referring to a lookup table containing fog values that are indexed to the depth of a given pixel.
D3DPRASTERCAPS_FOGVERTEX | The device calculates the fog value during the lighting operation and places the value into the alpha component of the D3DCOLOR_ value given for the specular color in the D3dLightData.out field. It then interpolates the fog value during rasterization.
D3DPRASTERCAPS_PAT | The driver can perform patterned drawing (lines or fills with D3DRENDERSTATE_LINEPATTERN or one of the D3DRENDERSTATE_STIPPLEPATTERN render states) for the primitive being queried.
D3DPRASTERCAPS_ROP2 | The device can support raster operations other than R2_COPYPEN.
D3DPRASTERCAPS_STIPPLE | The device can stipple polygons to simulate translucency.
D3DPRASTERCAPS_SUBPIXEL | The device performs subpixel placement of color, texture, and z data, rather than working with the nearest integer pixel coordinate. This helps avoid bleed-through due to z-imprecision, and jitter of color and texture values for pixels. Note that there is no corresponding state that can be enabled and disabled. The device either performs subpixel placement or it does not, and this bit is present only so that the Microsoft® Direct3D™ client will be better able to determine what the rendering quality will be.
D3DPRASTERCAPS_SUBPIXELX | The device is subpixel accurate along the x-axis only and is clamped to an integer y-axis scan line. For information about subpixel accuracy, see D3DPRASTERCAPS_SUBPIXEL .
D3DPRASTERCAPS_XOR | The device can support XOR operations.
D3DPRASTERCAPS_ZTEST | The device can perform z-test operations. This effectively renders a primitive and indicates whether any z-pixels would have been rendered.
D3DPROCESSVERTICES_COPY | Vertices should be copied to the driver, because they have always been transformed and lit. If all the vertices in the execute buffer can be copied, the driver does not need to do the work of processing the vertices; the result is an improvement in performance.
D3DPROCESSVERTICES_NOCOLOR | Vertices should not be colored.
D3DPROCESSVERTICES_OPMASK | Specifies a bitmask of the other flags in the flags member, exclusive of D3DPROCESSVERTICES_NOCOLOR and D3DPROCESSVERTICES_UPDATEEXTENTS.
D3DPROCESSVERTICES_TRANSFORM | Vertices should be transformed.
D3DPROCESSVERTICES_TRANSFORMLIGHT | Vertices should be transformed and lit.
D3DPROCESSVERTICES_UPDATEEXTENTS | Extents of all transformed vertices should be updated. This information is returned in the D3dStatus.x1, D3dStatus.y1, D3dStatus.x2, and D3dStatus.y2 fields.
D3DPSHADECAPS_ALPHAFLATBLEND | Device can support an alpha component for flat blended transparency (the D3DSHADE_FLAT state).
D3DPSHADECAPS_ALPHAFLATSTIPPLED | Device can support an alpha component for flat stippled transparency (the D3DSHADE_FLAT state). In these modes, the alpha color component for a primitive is provided as part of the color for the first vertex of the primitive.
D3DPSHADECAPS_ALPHAGOURAUDBLEND | Device can support an alpha component for Gouraud blended transparency (the D3DSHADE_GOURAUD state).
D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED | Device can support an alpha component for Gouraud stippled transparency (the D3DSHADE_GOURAUD state). In these modes, the alpha color component for a primitive is provided at vertices and interpolated across a face along with the other color components.
D3DPSHADECAPS_ALPHAPHONGBLEND | Device can support an alpha component for Phong blended transparency (the D3DSHADE_PHONG state).
D3DPSHADECAPS_ALPHAPHONGSTIPPLED | Device can support an alpha component for Phong stippled transparency (the D3DSHADE_PHONG state). In these modes, vertex parameters are reevaluated on a per-pixel basis, applying lighting effects for the red, green, and blue color components. Phong shading is not currently supported.
D3DPSHADECAPS_COLORFLATMONO | Device can support colored flat shading in the D3DCOLOR_MONO color model.
D3DPSHADECAPS_COLORFLATRGB | Device can support colored flat shading in the D3DCOLOR_RGB color model. In these modes, the color component for a primitive is provided as part of the color for the first vertex of the primitive. In monochromatic lighting modes, only the blue component of the color is interpolated. In RGB lighting modes, the red, green, and blue components are interpolated.
D3DPSHADECAPS_COLORGOURAUDMONO | Device can support colored Gouraud shading in the D3DCOLOR_MONOcolor model.
D3DPSHADECAPS_COLORGOURAUDRGB | Device can support colored Gouraud shading in the D3DCOLOR_RGB color model. In these modes, the color component for a primitive is provided at vertices and interpolated across a face along with the other color components. In monochromatic lighting modes, only the blue component of the color is interpolated. In RGB lighting modes, the red, green, and blue components are interpolated.
D3DPSHADECAPS_COLORPHONGMONO | Device can support colored Phong shading in the D3DCOLOR_MONO color model.
D3DPSHADECAPS_COLORPHONGRGB | Device can support colored Phong shading in the D3DCOLOR_RGB color model. In these modes, vertex parameters are reevaluated on a per-pixel basis. Lighting effects are applied for the red, green, and blue color components in RGB mode, and for the blue component only for monochromatic mode. Phong shading is not currently supported.
D3DPSHADECAPS_FOGFLAT | Device can support fog in the flat shading model.
D3DPSHADECAPS_FOGGOURAUD | Device can support fog in the Gouraud shading model.
D3DPSHADECAPS_FOGPHONG | Device can support fog in the Phong shading model. Phong shading is not currently supported.
D3DPSHADECAPS_SPECULARFLATMONO | Device can support specular highlights in flat shading in the D3DCOLOR_MONO color model.
D3DPSHADECAPS_SPECULARFLATRGB | Device can support specular highlights in flat shading in the D3DCOLOR_RGB color model.
D3DPSHADECAPS_SPECULARGOURAUDMONO | Device can support specular highlights in Gouraud shading in the D3DCOLOR_MONO color model.
D3DPSHADECAPS_SPECULARGOURAUDRGB | Device can support specular highlights in Gouraud shading in the D3DCOLOR_RGB color model.
D3DPSHADECAPS_SPECULARPHONGMONO | Device can support specular highlights in Phong shading in the D3DCOLOR_MONO color model. Phong shading is not currently supported.
D3DPSHADECAPS_SPECULARPHONGRGB | Device can support specular highlights in Phong shading in the D3DCOLOR_RGB color model. Phong shading is not currently supported.
D3DPTADDRESSCAPS_CLAMP | Device can clamp textures to addresses.
D3DPTADDRESSCAPS_MIRROR | Device can mirror textures to addresses.
D3DPTADDRESSCAPS_WRAP | Device can wrap textures to addresses.
D3DPTBLENDCAPS_COPY | Copy texture-blending mode (D3DTBLEND_COPY) is supported.
D3DPTBLENDCAPS_DECAL | Decal texture-blending mode (D3DTBLEND_DECAL) is supported.
D3DPTBLENDCAPS_DECALALPHA | Decal-alpha texture-blending mode (D3DTBLEND_DECALALPHA ) is supported.
D3DPTBLENDCAPS_DECALMASK | Decal-mask texture-blending mode (D3DTBLEND_DECALMASK ) is supported.
D3DPTBLENDCAPS_MODULATE | Modulate texture-blending mode (D3DTBLEND_MODULATE ) is supported.
D3DPTBLENDCAPS_MODULATEALPHA | Modulate-alpha texture-blending mode (D3DTBLEND_MODULATEALPHA ) is supported.
D3DPTBLENDCAPS_MODULATEMASK | Modulate-mask texture-blending mode (D3DTBLEND_MODULATEMASK ) is supported.
D3DPTEXTURECAPS_ALPHA | RGBA textures are supported. If this capability is not set, only RGB textures are supported in those modes.
D3DPTEXTURECAPS_BORDER | Texture mapping along borders is supported.
D3DPTEXTURECAPS_PERSPECTIVE | Perspective correction is supported.
D3DPTEXTURECAPS_POW2 | All non-mipmapped textures must have widths and heights specified as powers of two if this flag is set. (Note that all mipmapped textures must always have dimensions that are powers of two.)
D3DPTEXTURECAPS_SQUAREONLY | All textures must be square.
D3DPTEXTURECAPS_TRANSPARENCY | Texture transparency is supported. (Only those texels that are not the current transparent color are drawn.)
D3DPTFILTERCAPS_LINEAR | A weighted average of a 2-by-2 area of texels surrounding the desired pixel is used. This applies to both zooming in and zooming out. If either is supported, both zooming in and zooming out must be supported.
D3DPTFILTERCAPS_LINEARMIPLINEAR | Interpolate between the two nearest mipmaps.
D3DPTFILTERCAPS_LINEARMIPNEAREST | Interpolate between the two nearest mipmaps.
D3DPTFILTERCAPS_MIPLINEAR | Use the appropriate mipmap for texel selection.
D3DPTFILTERCAPS_MIPNEAREST | Use the appropriate mipmap for texel selection.
D3DPTFILTERCAPS_NEAREST | The texel with coordinates nearest to the desired pixel value is used. This applies to both zooming in and zooming out. If either is supported, both zooming in and zooming out must be supported.
D3DRENDERSTATE_ALPHAFUNC | One D3DCMP_ value. The default value is D3DCMP_ALWAYS. This field enables an application to accept or reject a pixel based on its alpha value.
D3DRENDERSTATE_ALPHAREF | Value specifying a reference alpha value against which pixels are tested when alpha-testing is enabled. The default value is 0.
D3DRENDERSTATE_ALPHATESTENABLE | This member enables applications to turn off the tests that otherwise would accept or reject a pixel based on its alpha value. Set to TRUE to enable alpha tests. The default value is FALSE.
D3DRENDERSTATE_ANTIALIAS | Antialiasing primitive edges. The default value is FALSE.
D3DRENDERSTATE_BLENDENABLE | TRUE to enable alpha blending. The default value is FALSE.
D3DRENDERSTATE_CULLMODE | One D3DCULL_ value. Software renderers have a fixed culling order and do not support changing the culling mode. The default value is D3DCULL_CCW.
D3DRENDERSTATE_DESTBLEND | One D3DBLEND_ value. The default value is D3DBLEND_ZERO.
D3DRENDERSTATE_DITHERENABLE | TRUE to enable dithering. The default value is FALSE.
D3DRENDERSTATE_FILLMODE | One or more D3DFILL_ values. The default value is D3DFILL_SOLID.
D3DRENDERSTATE_FOGCOLOR | A D3DCOLOR_ value. The default value is 0.
D3DRENDERSTATE_FOGENABLE | TRUE to enable fog. The default value is FALSE.
D3DRENDERSTATE_FOGTABLEDENSITY | Sets the maximum fog density for linear fog mode. This value can range from 0 to 1.
D3DRENDERSTATE_FOGTABLEEND | Fog table end. This is the position at which fog effects reach their maximum density for linear fog mode.
D3DRENDERSTATE_FOGTABLEMODE | A D3DFOG_ value. The default value is D3DFOG_NONE.
D3DRENDERSTATE_FOGTABLESTART | Fog table start. This is the position at which fog effects begin for linear fog mode.
D3DRENDERSTATE_LASTPIXEL | TRUE to prevent drawing the last pixel in a line. The default value is TRUE.
D3DRENDERSTATE_LINEPATTERN | Reserved.
D3DRENDERSTATE_MONOENABLE | TRUE to enable monochromatic rendering. The default value is FALSE. If the device does not support RGB rendering, the value will be TRUE. Applications can check whether the device supports RGB rendering by using the D3dDeviceDesc.dcmColorModel field.
D3DRENDERSTATE_PLANEMASK | Physical plane mask. The default value is 0.
D3DRENDERSTATE_ROP2 | One of the 16 ROP2 binary raster operations that specify how the supplied pixels are combined with the pixels of the display surface. Applications can use the D3DPRASTERCAPS_ROP2 flag in the D3dFindDeviceSearch.rasterCaps field to determine whether additional raster operations are supported. The default value is R2_COPYPEN.
D3DRENDERSTATE_SHADEMODE | One or more D3DSHADE_ values. The default value is D3DSHADE_GOURAUD.
D3DRENDERSTATE_SPECULARENABLE | TRUE to enable specular. The default value is TRUE.
D3DRENDERSTATE_SRCBLEND | One D3DBLEND_ value. The default value is D3DBLEND_ONE.
D3DRENDERSTATE_STIPPLEDALPHA | TRUE to enable stippled alpha. The default value is FALSE.
D3DRENDERSTATE_STIPPLEENABLE | Enables stippling in the device driver. When stippled alpha is enabled, it must override the current stipple pattern. When stippled alpha is disabled, the stipple pattern must be returned.
D3DRENDERSTATE_STIPPLEPATTERN00 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN01 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN02 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN03 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN04 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN05 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN06 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN07 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN08 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN09 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN10 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN11 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN12 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN13 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN14 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN15 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN16 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN17 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN18 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN19 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN20 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN21 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN22 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN23 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN24 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN25 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN26 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN27 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN28 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN29 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN30 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_STIPPLEPATTERN31 | Stipple pattern. Each render state applies to a separate line of the stipple pattern.
D3DRENDERSTATE_SUBPIXEL | TRUE to enable subpixel correction. The default value is FALSE.
D3DRENDERSTATE_SUBPIXELX | TRUE to enable correction in x-values only. The default value is FALSE.
D3DRENDERSTATE_TEXTUREADDRESS | One D3DTADDRESS_ value. The default value is D3DTADDRESS_WRAP.
D3DRENDERSTATE_TEXTUREHANDLE | Texture handle. The default value is null.
D3DRENDERSTATE_TEXTUREMAG | One D3DFILTER_ value. The default value is D3DFILTER_NEAREST.
D3DRENDERSTATE_TEXTUREMAPBLEND | One D3DTBLEND_ value. The default value is D3DTBLEND_MODULATE.
D3DRENDERSTATE_TEXTUREMIN | One D3DFILTER_ value. The default value is D3DFILTER_NEAREST.
D3DRENDERSTATE_TEXTUREPERSPECTIVE | TRUE for perspective correction. The default value is FALSE.
D3DRENDERSTATE_WRAPU | TRUE for wrapping in u-direction. The default value is FALSE.
D3DRENDERSTATE_WRAPV | TRUE for wrapping in v-direction. The default value is FALSE.
D3DRENDERSTATE_ZENABLE | TRUE to enable the z-buffer comparison test when writing to the frame buffer. The default value is FALSE.
D3DRENDERSTATE_ZFUNC | One D3DCMP_ value. This field enables an application to accept or reject a pixel based on its distance from the camera. The default value is D3DCMP_LESSEQUAL.
D3DRENDERSTATE_ZVISIBLE | TRUE to enable z-checking. Z-checking is a culling technique in which a polygon representing the screen space of an entire group of polygons is tested against the z-buffer to discover whether any of the polygons should be drawn. The default value is FALSE.
D3DRENDERSTATE_ZWRITEENABLE | TRUE to enable z-writes. This member enables an application to prevent the system from updating the z-buffer with new z-values. The default value is TRUE.
D3DRMANIMATION_CLOSED | Animation plays continually, looping back to the beginning whenever it reaches the end. In a closed animation, the last key in the animation should be a repeat of the first. This repeated key is used to indicate the time difference between the last and first keys in the looping animation.
D3DRMANIMATION_LINEARPOSITION | The animation's position is set linearly.
D3DRMANIMATION_OPEN | The animation plays once and stops.
D3DRMANIMATION_POSITION | The animation's position matrix overwrites any transformation matrices that could be set by other methods.
D3DRMANIMATION_SCALEANDROTATION | The animation's scale and rotation matrix overwrites any transformation matrices that could be set by other methods.
D3DRMANIMATION_SPLINEPOSITION | The animation's position is set using splines.
D3DRMCOLOR_FROMFACE | The object's color source is a face.
D3DRMCOLOR_FROMVERTEX | The object's color source is a vertex.
D3DRMCOMBINE_AFTER | The supplied matrix is multiplied with the frame's current matrix and follows the current matrix in the calculation.
D3DRMCOMBINE_BEFORE | The supplied matrix is multiplied with the frame's current matrix and precedes the current matrix in the calculation.
D3DRMCOMBINE_REPLACE | The supplied matrix replaces the frame's current matrix.
D3DRMCONSTRAIN_X | Use only y- and z-rotations.
D3DRMCONSTRAIN_Y | Use only x- and z-rotations.
D3DRMCONSTRAIN_Z | Use only x- and y-rotations.
D3DRMFILL_MASK | Fill using a mask.
D3DRMFILL_MAX | Maximum value for fill mode.
D3DRMFILL_POINTS | Fill points only; minimum fill mode.
D3DRMFILL_SOLID | Fill solid objects.
D3DRMFILL_WIREFRAME | Fill wireframes.
D3DRMFOG_EXPONENTIAL | The fog effect intensifies exponentially.
D3DRMFOG_EXPONENTIALSQUARED | The fog effect intensifies exponentially with the square of the distance.
D3DRMFOG_LINEAR | The fog effect intensifies linearly between the start and end points. This is the only fog mode currently supported.
D3DRMLIGHT_AMBIENT | Light is an ambient source.
D3DRMLIGHT_DIRECTIONAL | Light is a directional source.
D3DRMLIGHT_MASK | Lighting uses a mask.
D3DRMLIGHT_MAX | Maximum lighting mode.
D3DRMLIGHT_OFF | Lighting is off.
D3DRMLIGHT_ON | Lighting is on.
D3DRMLIGHT_PARALLELPOINT | Light is a parallel point source.
D3DRMLIGHT_POINT | Light is a point source.
D3DRMLIGHT_SPOT | Light is a spotlight source.
D3DRMLOAD_BYGUID | Load any object by using a specified globally unique identifier (GUID).
D3DRMLOAD_BYNAME | Load any object by using a specified name.
D3DRMLOAD_BYPOSITION | Load a stand-alone object based on a given zero-based position (that is, the nth object in the file). Stand-alone objects can contain other objects, but are not contained by any other objects.
D3DRMLOAD_FIRST | This is the default setting. Load the first stand-alone object of the given type (for example, a mesh if the application calls Direct3drmMeshBuilder.loadFromFileByPos). Stand-alone objects can contain other objects, but are not contained by any other objects.
D3DRMLOAD_FROMFILE | Load from a file. This is the default setting.
D3DRMLOAD_FROMMEMORY | Reserved.
D3DRMLOAD_FROMRESOURCE | Reserved.
D3DRMLOAD_FROMSTREAM | Reserved.
D3DRMLOAD_INSTANCEBYCOPYING | Check whether an object already exists with the same name as specified and, if so, copy that object.
D3DRMLOAD_INSTANCEBYREFERENCE | Check whether an object already exists with the same name as specified and, if so, use an instance of that object instead of creating a new one.
D3DRMMATERIAL_FROMFRAME | Material information is retrieved from the frame, overriding any previous material information that the visual object might have possessed.
D3DRMMATERIAL_FROMMESH | Material information is retrieved from the visual object (the mesh) itself. This is the default setting.
D3DRMMATERIAL_FROMPARENT | Material information, along with color or texture information, is inherited from the parent frame.
D3DRMPALETTE_FREE | Renderer can use this entry freely.
D3DRMPALETTE_READONLY | Fixed but can be used by renderer.
D3DRMPALETTE_RESERVED | Cannot be used by renderer.
D3DRMPROJECT_ORTHOGRAPHIC | The projection is orthographic.
D3DRMPROJECT_PERSPECTIVE | The projection is perspective.
D3DRMRENDER_FLAT | Flat shaded.
D3DRMRENDER_GOURAUD | Gouraud shaded.
D3DRMRENDER_PHONG | Phong shaded. Phong shading is not currently supported.
D3DRMRENDER_UNLITFLAT | Flat shaded without lighting.
D3DRMRENDER_WIREFRAME | Display only the edges.
D3DRMSHADE_FLAT | Flat shaded.
D3DRMSHADE_GOURAUD | Gouraud shaded.
D3DRMSHADE_MASK | Shading uses a mask.
D3DRMSHADE_MAX | Maximum shade.
D3DRMSHADE_PHONG | Phong shaded. Phong shading is not currently supported.
D3DRMSORT_BACKTOFRONT | Child frames are sorted back-to-front.
D3DRMSORT_FROMPARENT | Child frames inherit the sorting order of their parents. This is the default setting.
D3DRMSORT_FRONTTOBACK | Child frames are sorted front-to-back.
D3DRMSORT_NONE | Child frames are not sorted.
D3DRMTEXTURE_LINEAR | Linearly interpolate the four nearest pixels.
D3DRMTEXTURE_LINEARMIPLINEAR | Similar to D3DRMTEXTURE_MIPLINEAR, but interpolates between the two nearest mipmaps.
D3DRMTEXTURE_LINEARMIPNEAREST | Similar to D3DRMTEXTURE_MIPNEAREST, but interpolates between the two nearest mipmaps.
D3DRMTEXTURE_MIPLINEAR | Similar to D3DRMTEXTURE_LINEAR, but uses the appropriate mipmap instead of the texture.
D3DRMTEXTURE_MIPNEAREST | Similar to D3DRMTEXTURE_NEAREST, but uses the appropriate mipmap instead of the texture.
D3DRMTEXTURE_NEAREST | Choose the nearest pixel in the texture.
D3DRMWIREFRAME_CULL | The backfacing faces are not drawn.
D3DRMWIREFRAME_HIDDENLINE | Wireframe-rendered lines are obscured by nearer objects.
D3DRMWRAP_CHROME | The wrap allocates texture coordinates so that the texture appears to be reflected onto the objects.
D3DRMWRAP_CYLINDER | The wrap is cylindrical.
D3DRMWRAP_FLAT | The wrap is flat.
D3DRMWRAP_SPHERE | The wrap is spherical.
D3DRMXOF_BINARY | File is in binary format. This is the default setting.
D3DRMXOF_COMPRESSED | Not currently supported.
D3DRMXOF_TEXT | File is in text format.
D3DRMXOFSAVE_ALL | Save normal vectors, texture coordinates, materials, and texture names in addition to the basic geometry.
D3DRMXOFSAVE_MATERIALS | Save materials in addition to the basic geometry.
D3DRMXOFSAVE_NORMALS | Save normal vectors in addition to the basic geometry.
D3DRMXOFSAVE_TEMPLATES | Save templates with the file. By default, templates are not saved.
D3DRMXOFSAVE_TEXTURECOORDINATES | Save texture coordinates in addition to the basic geometry.
D3DRMXOFSAVE_TEXTURENAMES | Save texture names in addition to the basic geometry.
D3DRMZBUFFER_DISABLE | Z-buffering is disabled.
D3DRMZBUFFER_ENABLE | Z-buffering is enabled.
D3DRMZBUFFER_FROMPARENT | The frame inherits the z-buffer setting from its parent frame. This is the default setting.
D3DSETSTATUS_ALL |
D3DSETSTATUS_EXTENTS | Sets the extents of the bounding box specified in the D3dStatus.x1, D3dStatus.y1, D3dStatus.x2, and D3dStatus.y2 fields.
D3DSETSTATUS_STATUS | Sets the status.
D3DSHADE_FLAT | Flat shade mode. The color of the first vertex in the triangle is used to determine the color of the face.
D3DSHADE_GOURAUD | Gouraud shade mode. The color of the face is determined by a linear interpolation between all three of the triangle's vertices.
D3DSHADE_PHONG | Phong shade mode. This mode is not currently supported.
D3DSTATE_OVERRIDE_BIAS | Override bias.
D3DSTATUS_CLIPINTERSECTIONALL | Combination of all CLIPINTERSECTION flags.
D3DSTATUS_CLIPINTERSECTIONBACK | Logical AND of the clip flags for the vertices compared to the back clipping plane of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONBOTTOM | Logical AND of the clip flags for the vertices compared to the bottom of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONFRONT | Logical AND of the clip flags for the vertices compared to the front clipping plane of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONGEN0 | Logical AND of the clip flags for application-defined clipping planes.
D3DSTATUS_CLIPINTERSECTIONGEN1 | Logical AND of the clip flags for application-defined clipping planes.
D3DSTATUS_CLIPINTERSECTIONGEN2 | Logical AND of the clip flags for application-defined clipping planes.
D3DSTATUS_CLIPINTERSECTIONGEN3 | Logical AND of the clip flags for application-defined clipping planes.
D3DSTATUS_CLIPINTERSECTIONGEN4 | Logical AND of the clip flags for application-defined clipping planes.
D3DSTATUS_CLIPINTERSECTIONGEN5 | Logical AND of the clip flags for application-defined clipping planes.
D3DSTATUS_CLIPINTERSECTIONLEFT | Logical AND of the clip flags for the vertices compared to the left side of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONRIGHT | Logical AND of the clip flags for the vertices compared to the right side of the viewing frustum.
D3DSTATUS_CLIPINTERSECTIONTOP | Logical AND of the clip flags for the vertices compared to the top of the viewing frustum.
D3DSTATUS_CLIPUNIONALL | Combination of all CLIPUNION flags.
D3DSTATUS_CLIPUNIONBACK | Equal to D3DCLIP_BACK.
D3DSTATUS_CLIPUNIONBOTTOM | Equal to D3DCLIP_BOTTOM.
D3DSTATUS_CLIPUNIONFRONT | Equal to D3DCLIP_FRONT.
D3DSTATUS_CLIPUNIONGEN0 | Equal to D3DCLIP_GEN0
D3DSTATUS_CLIPUNIONGEN1 | Equal to D3DCLIP_GEN1.
D3DSTATUS_CLIPUNIONGEN2 | Equal to D3DCLIP_GEN2.
D3DSTATUS_CLIPUNIONGEN3 | Equal to D3DCLIP_GEN3.
D3DSTATUS_CLIPUNIONGEN4 | Equal to D3DCLIP_GEN4.
D3DSTATUS_CLIPUNIONGEN5 | Equal to D3DCLIP_GEN5.
D3DSTATUS_CLIPUNIONLEFT | Equal to D3DCLIP_LEFT.
D3DSTATUS_CLIPUNIONRIGHT | Equal to D3DCLIP_RIGHT.
D3DSTATUS_CLIPUNIONTOP | Equal to D3DCLIP_TOP.
D3DSTATUS_DEFAULT | Combination of D3DSTATUS_CLIPINTERSECTION and D3DSTATUS_ZNOTVISIBLE flags. This value is the default.
D3DSTATUS_ZNOTVISIBLE | Reserved.
D3DTADDRESS_CLAMP | Texture coordinates greater than 1.0 are set to 1.0, and values less than 0.0 are set to 0.0.
D3DTADDRESS_MIRROR | Equivalent to a tiling texture-addressing mode (that is, when neither D3DRENDERSTATE_WRAPU nor D3DRENDERSTATE_WRAPV is used), except that the texture is flipped at every integer junction. For u-values between 0 and 1, for example, the texture is addressed normally; between 1 and 2, the texture is flipped (mirrored); between 2 and 3, the texture is normal again, and so on.
D3DTADDRESS_WRAP | The D3DRENDERSTATE_WRAPU and D3DRENDERSTATE_WRAPV render states are used. This is the default setting.
D3DTBLEND_COPY | Copy texture-blending is supported.
BLEND_DECAL | Decal texture-blending is supported. In this mode, the RGB and alpha values of the texture replace the colors that would have been used with no texturing.
D3DTBLEND_DECALALPHA | Decal-alpha texture-blending is supported. In this mode, the RGB and alpha values of the texture are blended with the colors that would have been used with no texturing. In the D3DTBLEND_DECALALPHA mode, any alpha values in the texture replace the alpha values in the colors that would have been used with no texturing.
D3DTBLEND_DECALMASK | Decal-mask texture-blending is supported.
D3DTBLEND_MODULATE | Modulate texture-blending is supported. In this mode, the RGB values of the texture are multiplied with the RGB values that would have been used with no texturing. Any alpha values in the texture replace the alpha values that would have been used with no texturing.
D3DTBLEND_MODULATEALPHA | Modulate-alpha texture-blending is supported. In this mode, the RGB values of the texture are multiplied with the RGB values that would have been used with no texturing, and the alpha values of the texture are multiplied with the alpha values that would have been used with no texturing.
D3DTBLEND_MODULATEMASK | Modulate-mask texture-blending is supported.
D3DTRANSFORM_CLIPPED | The method uses the current transformation matrix to transform a set of vertices, checking the resulting vertices to see if they are within the viewing frustum. The homogeneous part of the D3dTransformData.in field will be set if the vertex is clipped. Otherwise, only the screen coordinates will be set. The D3dTransformData.x1, D3dTransformData.y1, D3dTransformData.x2, and D3dTransformData.y2 fields will also be set to the 2D bounding rectangle of the resulting vertices.
D3DTRANSFORM_UNCLIPPED | The method uses the current transformation matrix to transform a set of vertices. In this case, the system assumes that all the resulting coordinates will be within the viewing frustum. The D3dTransformData.x1, D3dTransformData.y1, D3dTransformData.x2, and D3dTransformData.y2 fields will be set to the bounding rectangle of the resulting vertices.
D3DTRANSFORMSTATE_PROJECTION | Define the matrix for the projection transformation. The default value is null (the identity matrix).
D3DTRANSFORMSTATE_VIEW | Define the matrix for the view transformation. The default value is null (the identity matrix).
D3DTRANSFORMSTATE_WORLD | Define the matrix for the world transformation. The default values is null (the identity matrix).
D3DTRIFLAG_EDGEENABLE1 | Edge defined by v1–v2.
D3DTRIFLAG_EDGEENABLE2 | Edge defined by v2–v3.
D3DTRIFLAG_EDGEENABLE3 | Edge defined by v3–v1.
D3DTRIFLAG_EDGEENABLETRIANGLE | All edges.
D3DTRIFLAG_EVEN | The v1–v2 edge of the current triangle is adjacent to the v3–v1 edge of the previous triangle; that is, v1 is the previous v1, and v2 is the previous v3.
D3DTRIFLAG_ODD | The v1–v2 edge of the current triangle is adjacent to the v2–v3 edge of the previous triangle; that is, v1 is the previous v3, and v2 is the previous v2.
D3DTRIFLAG_START | Begin the strip or fan, loading all three vertices.
DD_OK | The request completed successfully.
DDBD_1 | One bit per pixel.
DDBD_16 | Sixteen bits per pixel.
DDBD_2 | Two bits per pixel.
DDBD_24 | Twenty-four bits per pixel.
DDBD_32 | Thirty-two bits per pixel.
DDBD_4 | Four bits per pixel.
DDBD_8 | Eight bits per pixel.
DDBLT_ALPHADEST | Use either the alpha information in the pixel format or the alpha channel surface attached to the destination surface as the alpha channel for this blit.
DDBLT_ALPHADESTCONSTOVERRIDE | Uses the DDBltFx.alphaDestConst field as the alpha channel for the destination surface for this blit.
DDBLT_ALPHADESTNEG | Indicates that the destination surface becomes more transparent as the alpha value increases (0 is opaque).
DDBLT_ALPHADESTSURFACEOVERRIDE | Reserved.
DDBLT_ALPHAEDGEBLEND | Uses the DDBltFx.alphaEdgeBlend field as the alpha channel for the edges of the image that border the colors of the color key.
DDBLT_ALPHASRC | Uses either the alpha information in the pixel format or the alpha channel surface attached to the source surface as the alpha channel for this blit.
DDBLT_ALPHASRCCONSTOVERRIDE | Uses the DDBltFx.alphaSrcConst field as the alpha channel for the source for this blit.
DDBLT_ALPHASRCNEG | Indicates that the source surface becomes more transparent as the alpha value increases (0 is opaque).
DDBLT_ALPHASRCSURFACEOVERRIDE | Reserved.
DDBLT_ASYNC | Processes this blit asynchronously through the FIFO hardware in the order received. If there is no room in the FIFO hardware, the call fails.
DDBLT_COLORFILL | Uses the DDBltFx.fillValue field as the RGB color with which to fill the destination rectangle on the destination surface.
DDBLT_DDFX | Uses the DDBltFx.ddfx field to specify the effects to be used for this blit.
DDBLT_DDROPS | Uses the DDBltFx.ddrop field to specify the raster operations that are not part of the Microsoft® Win32® API.
DDBLT_DEPTHFILL | Reserved.
DDBLT_KEYDEST | Uses the color key associated with the destination surface.
DDBLT_KEYDESTOVERRIDE | Uses the DDBltFx.destColorSpaceLowValue and DDBltFx.destColorSpaceHighValue fields as the color key for the destination surface.
DDBLT_KEYSRC | Uses the color key associated with the source surface.
DDBLT_KEYSRCOVERRIDE | Uses the DDBltFx.srcColorSpaceLowValue and DDBltFx.srcColorSpaceHighValue fields as the color key for the source surface.
DDBLT_ROP | Uses the DDBltFx.rop field for the raster operation for this blit. The raster operations are the same as those defined in the Win32 API.
DDBLT_ROTATIONANGLE | Uses the DDBltFx.rotationAngle field as the rotation angle (specified in 1/100th of a degree) for the surface.
DDBLT_WAIT | Returns as soon as the blit can be set up.
DDBLT_ZBUFFER | Performs a z-buffered blit using the z-buffers attached to the source and destination surfaces and the DDBltFx.zbufferOpCode field as the z-buffer opcode.
DDBLT_ZBUFFERDESTCONSTOVERRIDE | Performs a z-buffered blit using the DDBltFx.zDestConst and DDBltFx.zbufferOpCode fields as the z-buffer and z-buffer opcode, respectively, for the destination.
DDBLT_ZBUFFERDESTOVERRIDE | Reserved.
DDBLT_ZBUFFERSRCCONSTOVERRIDE | Performs a z-buffered blit using the DDBltFx.zSrcConst and DDBltFx.zbufferOpCode fields as the z-buffer and z-buffer opcode, respectively, for the source.
DDBLT_ZBUFFERSRCOVERRIDE | Reserved.
DDBLTFAST_DESTCOLORKEY | A transparent blit that uses the destination’s color key.
DDBLTFAST_NOCOLORKEY | A normal copy blit with no transparency.
DDBLTFAST_SRCCOLORKEY | A transparent blit that uses the source’s color key.
DDBLTFAST_WAIT | Returns as soon as the blit can be set up.
DDBLTFX_ARITHSTRETCHY | Use arithmetic stretching along the y-axis for this blit.
DDBLTFX_MIRRORLEFTRIGHT | Turn the surface on its y-axis. This blit mirrors the surface from left to right.
DDBLTFX_MIRRORUPDOWN | Turn the surface on its x-axis. This blit mirrors the surface from top to bottom.
DDBLTFX_NOTEARING | Schedule this blit to avoid tearing.
DDBLTFX_ROTATE180 | Rotate the surface 180 degrees clockwise during this blit.
DDBLTFX_ROTATE270 | Rotate the surface 270 degrees clockwise during this blit.
DDBLTFX_ROTATE90 | Rotate the surface 90 degrees clockwise during this blit.
DDBLTFX_ZBUFFERBASEDEST | Adds the DDBltFx.zbufferBaseDest field to each of the source z-values before comparing them with the destination z-values during this z-blit.
DDBLTFX_ZBUFFERRANGE | Use the DDBltFx.zbufferLow and DDBltFx.zbufferHigh fields as range values to specify limits to the bits copied from a source surface during this z-blit.
DDCAPS_3D | Display hardware has 3D acceleration.
DDCAPS_ALIGNBOUNDARYDEST | DirectDraw will support only those source rectangles with the x-axis aligned to the DDCaps.alignBoundaryDest boundaries of the surface.
DDCAPS_ALIGNBOUNDARYSRC | DirectDraw will support only those source rectangles with the x-axis aligned to the DDCaps.alignBoundarySrc boundaries of the surface.
DDCAPS_ALIGNSIZEDEST | DirectDraw will support only those source rectangles whose x-axis sizes, in bytes, are DDCaps.alignSizeDest multiples.
DDCAPS_ALIGNSIZESRC | DirectDraw will support only those source rectangles whose x-axis sizes, in bytes, are DDCaps.alignSizeSrc multiples.
DDCAPS_ALIGNSTRIDE | DirectDraw will create display memory surfaces that have a stride alignment equal to the DDCaps.alignStrideAlign value.
DDCAPS_ALPHA | Indicates that the display hardware supports an alpha channel during blit operations.
DDCAPS_BANKSWITCHED | Display hardware is bank-switched and is potentially very slow at random access to display memory.
DDCAPS_BLT | Display hardware is capable of blit operations.
DDCAPS_BLTCOLORFILL | Display hardware is capable of color filling with a blitter.
DDCAPS_BLTDEPTHFILL | Display hardware is capable of depth filling z-buffers with a blitter.
DDCAPS_BLTFOURCC | Display hardware is capable of color-space conversions during blit operations.
DDCAPS_BLTQUEUE | Display hardware is capable of asynchronous blit operations.
DDCAPS_BLTSTRETCH | Display hardware is capable of stretching during blit operations.
DDCAPS_CANBLTSYSMEM | Display hardware is capable of blitting to or from system memory.
DDCAPS_CANCLIP | Display hardware is capable of clipping with blitting.
DDCAPS_CANCLIPSTRETCHED | Display hardware is capable of clipping while stretch blitting.
DDCAPS_COLORKEY | Support some form of color key in either overlay or blit operations. More specific color key capability information can be found in the DDCaps.colorkeyCaps field.
DDCAPS_COLORKEYHWASSIST | The color key is hardware assisted.
DDCAPS_GDI | Display hardware is shared with GDI.
DDCAPS_NOHARDWARE | There is no hardware support for DirectDraw.
DDCAPS_OVERLAY | Display hardware supports overlays.
DDCAPS_OVERLAYCANTCLIP | Display hardware supports overlays, but cannot clip them.
DDCAPS_OVERLAYFOURCC | Overlay hardware is capable of color-space conversions during overlay operations.
DDCAPS_OVERLAYSTRETCH | Overlay hardware is capable of stretching.
DDCAPS_PALETTE | DirectDraw is capable of creating and supporting DirectDrawPalette objects for more surfaces than only the primary surface.
DDCAPS_PALETTEVSYNC | DirectDraw® is capable of updating a palette synchronized with the vertical refresh.
DDCAPS_READSCANLINE | Display hardware is capable of returning the current scan line.
DDCAPS_STEREOVIEW | Display hardware has stereo vision capabilities.
DDCAPS_VBI | Display hardware is capable of generating a vertical-blank interrupt.
DDCAPS_ZBLTS | Supports the use of z-buffers with blit operations.
DDCAPS_ZOVERLAYS | Supports the use of the DirectDrawSurface.updateOverlayZOrder method as a z-value for overlays to control their layering.
DDCAPS2_CERTIFIED | Display hardware is certified.
DDCAPS2_NO2DDURING3DSCENE | Between calls to the Direct3dDevice.beginScene and Direct3dDevice.endScene methods, 2D operations such as DirectDrawSurface.blt and DirectDrawSurface.lock cannot be performed on any surfaces that Direct3D™ is using.
DDCKEY_COLORSPACE | A color space.
DDCKEY_DESTBLT | Color key or color space to use as a destination color key for blit operations.
DDCKEY_DESTOVERLAY | Color key or color space to use as a destination color key for overlay operations.
DDCKEY_SRCBLT | Color key or color space to use as a source color key for blit operations.
DDCKEY_SRCOVERLAY | Color key or color space to use as a source color key for overlay operations.
DDCKEYCAPS_DESTBLT | Supports transparent blitting with a color key that identifies the replaceable bits of the destination surface for RGB colors.
DDCKEYCAPS_DESTBLTCLRSPACE | Supports transparent blitting with a color space that identifies the replaceable bits of the destination surface for RGB colors.
DDCKEYCAPS_DESTBLTCLRSPACEYUV | Supports transparent blitting with a color space that identifies the replaceable bits of the destination surface for YUV colors.
DDCKEYCAPS_DESTBLTYUV | Supports transparent blitting with a color key that identifies the replaceable bits of the destination surface for YUV colors.
DDCKEYCAPS_DESTOVERLAY | Supports overlays with color keying of the replaceable bits of the destination surface being overlaid for RGB colors.
DDCKEYCAPS_DESTOVERLAYCLRSPACE | Support a color space as the color key for the destination of RGB colors.
DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV | Supports a color space as the color key for the destination of YUV colors.
DDCKEYCAPS_DESTOVERLAYONEACTIVE | Support only one active destination color key value for visible overlay surfaces.
DDCKEYCAPS_DESTOVERLAYYUV | Supports overlays using color keying of the replaceable bits of the destination surface being overlaid for YUV colors.
DDCKEYCAPS_NOCOSTOVERLAY | There are no bandwidth tradeoffs for using the color key with an overlay.
DDCKEYCAPS_SRCBLT | Supports transparent blitting using the color key for the source with this surface for RGB colors.
DDCKEYCAPS_SRCBLTCLRSPACE | Supports transparent blitting using a color space for the source with this surface for RGB colors.
DDCKEYCAPS_SRCBLTCLRSPACEYUV | Supports transparent blitting using a color space for the source with this surface for YUV colors.
DDCKEYCAPS_SRCBLTYUV | Supports transparent blitting using the color key for the source with this surface for YUV colors.
DDCKEYCAPS_SRCOVERLAY | Supports overlays using the color key for the source with this overlay surface for RGB colors.
DDCKEYCAPS_SRCOVERLAYCLRSPACE | Supports overlays using a color space as the source color key for the overlay surface for RGB colors.
DDCKEYCAPS_SRCOVERLAYCLRSPACEYUV | Supports overlays using a color space as the source color key for the overlay surface for YUV colors.
DDCKEYCAPS_SRCOVERLAYONEACTIVE | Supports only one active source color key value for visible overlay surfaces.
DDCKEYCAPS_SRCOVERLAYYUV | Supports overlays using the color key for the source with this overlay surface for YUV colors.
DDCOOPERATIVE_CLIPTOCOMPONENT | Used in the blt and the bltFast methods to specify that the DirectDraw object clips completely to a component's region.
DDCOOPERATIVE_OFFSETTOCOMPONENT | Used in the blt and the bltFast methods to specify that the DirectDraw object will only offset the blt to the component but will not clip to other components.
DDCREATE_EMULATIONONLY | Reserved.
DDCREATE_HARDWAREONLY | Reserved.
DDEDM_REFRESHRATES | Enumerates modes with different refresh rates. DirectDraw.enumDisplayModes guarantees that a particular mode will be enumerated only once. This flag specifies whether the refresh rate is taken into account when determining if a mode is unique.
DDENUMOVERLAYZ_BACKTOFRONT | Enumerates overlays back to front.
DDENUMOVERLAYZ_FRONTTOBACK | Enumerates overlays front to back.
DDENUMSURFACES_ALL | Enumerates all the surfaces that meet the search criterion.
DDENUMSURFACES_CANBECREATED | Enumerates the first surface that can be created and meets the search criterion.
DDENUMSURFACES_DOESEXIST | Enumerates the already existing surfaces that meet the search criterion.
DDENUMSURFACES_MATCH | Searches for any surface that matches the surface description.
DDENUMSURFACES_NOMATCH | Searches for any surface that does not match the surface description.
DDERR_SURFACELOST | Access to the surface is refused because the surface memory is gone. The DirectDrawSurface object representing this surface should have the DirectDrawSurface.restore method called on it.
DDERR_WASSTILLDRAWING | The previous blit operation that is transferring information to or from this surface is incomplete.
DDFLIP_WAIT | Typically, if the flip cannot be set up because the state of the display hardware is not appropriate, the DirectDrawSurface.flip method returns immediately and no flip occurs. Setting this flag causes the method to continue trying to flip. DirectDrawSurface.flip does not return until the flipping operation has been successfully set up or an error that prevents flipping occurs.
DDFXALPHACAPS_BLTALPHAEDGEBLEND | Supports alpha blending around the edge of a source color-keyed surface. Used for blit operations.
DDFXALPHACAPS_BLTALPHAPIXELS | Supports alpha information in pixel format. The bit depth of alpha information in the pixel format can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for blit operations.
DDFXALPHACAPS_BLTALPHAPIXELSNEG | Supports alpha information in pixel format. The bit depth of alpha information in the pixel format can be 1, 2, 4, or 8. The alpha value becomes more transparent as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can be used only if DDCAPS_ALPHA is set. Used for blit operations.
DDFXALPHACAPS_BLTALPHASURFACES | Supports alpha-only surfaces. The bit depth of an alpha-only surface can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for blit operations.
DDFXALPHACAPS_BLTALPHASURFACESNEG | Indicates that the alpha channel becomes more transparent as the alpha value increases. The depth of the alpha channel data can be 1, 2, 4, or 8. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can be set only if DDFXCAPS_ALPHASURFACES has been set. Used for blit operations.
DDFXALPHACAPS_OVERLAYALPHAEDGEBLEND | Supports alpha blending around the edge of a source color-keyed surface. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHAPIXELS | Supports alpha information in pixel format. The bit depth of alpha information in pixel format can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHAPIXELSNEG | Supports alpha information in pixel format. The bit depth of alpha information in pixel format can be 1, 2, 4, or 8. The alpha value becomes more transparent as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can be used only if DDFXCAPS_ALPHAPIXELS has been set. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHASURFACES | Supports alpha-only surfaces. The bit depth of an alpha-only surface can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHASURFACESNEG | Indicates that the alpha channel becomes more transparent as the alpha value increases. The depth of the alpha channel data can be 1, 2, 4, or 8. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can be used only if DDFXCAPS_ALPHASURFACES has been set. Used for overlays.
DDFXCAPS_BLTARITHSTRETCHY | Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink surfaces during a blit operation. Occurs along the y-axis (vertically).
DDFXCAPS_BLTARITHSTRETCHYN | Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink surfaces during a blit operation. Occurs along the y-axis (vertically), and works only for integer stretching ( x 1, x 2, and so on).
DDFXCAPS_BLTMIRRORLEFTRIGHT | Supports mirroring left to right in a blit operation.
DDFXCAPS_BLTMIRRORUPDOWN | Supports mirroring top to bottom in a blit operation.
DDFXCAPS_BLTROTATION | Supports arbitrary rotation in a blit operation.
DDFXCAPS_BLTROTATION90 | Supports 90-degree rotations in a blit operation.
DDFXCAPS_BLTSHRINKX | Supports arbitrary shrinking of a surface along the x-axis (horizontally). This flag is valid only for blit operations.
DDFXCAPS_BLTSHRINKXN | Supports integer shrinking ( x 1, x 2, and so on) of a surface along the x-axis (horizontally). This flag is valid only for blit operations.
DDFXCAPS_BLTSHRINKY | Supports arbitrary shrinking of a surface along the y-axis (vertically). This flag is valid only for blit operations.
DDFXCAPS_BLTSHRINKYN | Supports integer shrinking ( x 1, x 2, and so on) of a surface along the y-axis (vertically). This flag is valid only for blit operations.
DDFXCAPS_BLTSTRETCHX | Supports arbitrary stretching of a surface along the x-axis (horizontally). This flag is valid only for blit operations.
DDFXCAPS_BLTSTRETCHXN | Supports integer stretching ( x1, x2, and so on) of a surface along the x-axis (horizontally). This flag is valid only for blit operations.
DDFXCAPS_BLTSTRETCHY | Supports arbitrary stretching of a surface along the y-axis (vertically). This flag is valid only for blit operations.
DDFXCAPS_BLTSTRETCHYN | Supports integer stretching ( x1, x2, and so on) of a surface along the y-axis (vertically). This flag is valid only for blit operations.
DDFXCAPS_OVERLAYARITHSTRETCHY | Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink surfaces during an overlay operation. Occurs along the y-axis (vertically).
DDFXCAPS_OVERLAYARITHSTRETCHYN | Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink surfaces during an overlay operation. Occurs along the y-axis (vertically), and works only for integer stretching ( x 1, x 2, and so on).
DDFXCAPS_OVERLAYMIRRORLEFTRIGHT | Supports mirroring of overlays around the vertical axis.
DDFXCAPS_OVERLAYMIRRORUPDOWN | Supports mirroring of overlays across the horizontal axis.
DDFXCAPS_OVERLAYSHRINKX | Supports arbitrary shrinking of a surface along the x-axis (horizontally). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSHRINKXN | Supports integer shrinking ( x 1, x 2, and so on) of a surface along the x-axis (horizontally). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSHRINKY | Supports arbitrary shrinking of a surface along the y-axis (vertically). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSHRINKYN | Supports integer shrinking ( x1, x2, and so on) of a surface along the y-axis (vertically). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSTRETCHX | Supports arbitrary stretching of a surface along the x-axis (horizontally). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that stretching is available.
DDFXCAPS_OVERLAYSTRETCHXN | Supports integer stretching ( x1, x2, and so on) of a surface along the x-axis (horizontally). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that stretching is available.
DDFXCAPS_OVERLAYSTRETCHY | Supports arbitrary stretching of a surface along the y-axis (vertically). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that stretching is available.
DDFXCAPS_OVERLAYSTRETCHYN | Supports integer stretching ( x1, x2, and so on) of a surface along the y-axis (vertically). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that stretching is available.
DDGBS_CANBLT | Inquires whether a blit involving this surface can occur immediately, and returns DD_OK if the blit can be completed.
DDGBS_ISBLTDONE | Inquires whether the blit is done, and returns DD_OK if the last blit on this surface has completed.
DDGFS_CANFLIP | Inquires whether this surface can be flipped immediately. Returns DD_OK if the flip can be completed.
DDGFS_ISFLIPDONE | Inquires whether the flip has finished. Returns DD_OK if the last flip on this surface has completed.
DDLOCK_EVENT | Triggers the event when DirectDrawSurface.lock can return the surface memory requested. This flag is set if an event handle is being passed to DirectDrawSurface.lock. If multiple locks of this type are placed on a surface, events are triggered in FIFO order.
DDLOCK_READONLY | Indicates that the surface being locked will be read-only.
DDLOCK_SURFACEMEMORYPTR | Indicates that valid memory at the top of the specified rectangle should be returned. If no rectangle is specified, the top of the surface is returned. This is the default.
DDLOCK_WAIT | Typically, if a lock cannot be obtained because a blit operation is in progress, no action is taken. If this flag is set, however, DirectDrawSurface.lock retries until a lock is obtained.
DDLOCK_WRITEONLY | Indicates that the surface being locked will be write-only.
DDOVER_ADDDIRTYRECT | Adds a dirty rectangle to an emulated overlay surface.
DDOVER_ALPHADEST | Uses either the alpha information in pixel format or the alpha channel surface attached to the destination surface as the alpha channel for this overlay.
DDOVER_ALPHADESTCONSTOVERRIDE | Reserved.
DDOVER_ALPHADESTNEG | Indicates that the destination surface becomes more transparent as the alpha value increases (0 is opaque).
DDOVER_ALPHADESTSURFACEOVERRIDE | Reserved.
DDOVER_ALPHAEDGEBLEND | Reserved.
DDOVER_ALPHASRC | Uses either the alpha information in pixel format or the alpha channel surface attached to the source surface as the source alpha channel for this overlay.
DDOVER_ALPHASRCCONSTOVERRIDE | Reserved.
DDOVER_ALPHASRCNEG | Indicates that the source surface becomes more transparent as the alpha value increases (0 is opaque).
DDOVER_ALPHASRCSURFACEOVERRIDE | Reserved.
DDOVER_DDFX | Uses the overlay FX flags to define special overlay effects.
DDOVER_HIDE | Turns this overlay off.
DDOVER_KEYDEST | Uses the color key associated with the destination surface.
DDOVER_KEYDESTOVERRIDE | Reserved.
DDOVER_KEYSRC | Uses the color key associated with the source surface.
DDOVER_KEYSRCOVERRIDE | Reserved.
DDOVER_REFRESHALL | Ignores the dirty rectangle list and updates the overlay display completely. This clears the dirty rectangle list.
DDOVER_REFRESHDIRTYRECTS | Updates the overlay display using the list of dirty rectangles previously constructed for this destination. This clears the dirty rectangle list.
DDOVER_SHOW | Turns on this overlay.
DDOVERFX_ARITHSTRETCHY | If stretching, uses arithmetic stretching along the y-axis for this overlay.
DDOVERFX_MIRRORLEFTRIGHT | Mirrors the overlay around the vertical axis.
DDOVERFX_MIRRORUPDOWN | Mirrors the overlay around the horizontal axis.
DDOVERZ_INSERTINBACKOF | Inserts this overlay behind the reference overlay in the overlay chain.
DDOVERZ_INSERTINFRONTOF | Inserts this overlay in front of the reference overlay in the overlay chain.
DDOVERZ_MOVEBACKWARD | Moves this overlay one position backward in the overlay chain.
DDOVERZ_MOVEFORWARD | Moves this overlay one position forward in the overlay chain.
DDOVERZ_SENDTOBACK | Moves this overlay to the back of the overlay chain.
DDOVERZ_SENDTOFRONT | Moves this overlay to the front of the overlay chain.
DDPCAPS_1BIT | Indicates that the index is 1 bit. There are two entries in the color table.
DDPCAPS_2BIT | Indicates that the index is 2 bits. There are four entries in the color table.
DDPCAPS_4BIT | Indicates that the index is 4 bits. There are 16 entries in the color table.
DDPCAPS_8BIT | Indicates that the index is 8 bits. There are 256 entries in the color table.
DDPCAPS_8BITENTRIES | Specifies an index to an 8-bit color index. This field is valid only when used with the DDPCAPS_1BIT, DDPCAPS_2BIT, or DDPCAPS_4BIT capability and when the target surface is in 8 bits per pixel (bpp). Each color entry is 1 byte long and is an index to an 8-bpp palette on the destination surface.
DDPCAPS_ALLOW256 | Indicates that this palette can have all 256 entries defined.
DDPCAPS_INITIALIZE | Reserved.
DDPCAPS_PRIMARYSURFACE | Indicates that the palette is attached to the primary surface. Changing the palette has an immediate effect on the display unless the DDPCAPS_VSYNC capability is specified and supported.
DDPCAPS_PRIMARYSURFACELEFT | Indicates that the palette is attached to the primary surface on the left. Changing the palette has an immediate effect on the display unless the DDPCAPS_VSYNC capability is specified and supported.
DDPCAPS_VSYNC | Indicates that the palette can be modified synchronously with the monitor’s refresh rate.
DDPF_ALPHA | The pixel format describes an alpha-only surface.
DDPF_ALPHAPIXELS | The surface has alpha channel information in the pixel format.
DDPF_COMPRESSED | The surface will accept pixel data in the specified format and compress it during the write operation.
DDPF_FOURCC | The FourCC code is valid.
DDPF_PALETTEINDEXED1 | The surface is 1-bit color indexed.
DDPF_PALETTEINDEXED2 | The surface is 2-bit color indexed.
DDPF_PALETTEINDEXED4 | The surface is 4-bit color indexed.
DDPF_PALETTEINDEXED8 | The surface is 8-bit color indexed.
DDPF_PALETTEINDEXEDTO8 | The surface is 1-, 2-, or 4-bit color indexed to an 8-bit palette.
DDPF_RGB | The RGB data in the pixel format structure is valid.
DDPF_RGBTOYUV | The surface will accept RGB data and translate it during the write operation to YUV data. The format of the data to be written will be contained in the pixel format structure. The DDPF_RGB flag will be set.
DDPF_YUV | The YUV data in the pixel format structure is valid.
DDPF_ZBUFFER | The pixel format describes a z-buffer-only surface.
DDSCAPS_3D | Supported for backwards compatibility. Applications should use the DDSCAPS_3DDEVICE flag, instead.
DDSCAPS_3DDEVICE | Indicates that this surface can be used for 3D rendering. Applications can use this flag to ensure that a device that can only render to a certain heap has off-screen surfaces allocated from the correct heap. If this flag is set for a heap, the surface is not allocated from that heap.
DDSCAPS_ALLOCONLOAD | Indicates that memory for the surface is not allocated until the surface is loaded by using the Direct3dTexture.load method.
DDSCAPS_ALPHA | Indicates that this surface contains alpha information. The pixel format must be interrogated to determine whether this surface contains only alpha information or alpha information interlaced with pixel color data (such as RGBA or YUVA).
DDSCAPS_BACKBUFFER | Indicates that this surface is the back buffer of a surface flipping structure. Typically, this capability is set by the DirectDraw.createSurface method when the DDSCAPS_FLIP flag is used. Only the surface that immediately precedes the DDSCAPS_FRONTBUFFER surface has this capability set. The other surfaces are identified as back buffers by the presence of the DDSCAPS_FLIP flag, their attachment order, and the absence of the DDSCAPS_FRONTBUFFER and DDSCAPS_BACKBUFFER capabilities. If this capability is sent to the DirectDraw.createSurface method, a stand-alone back buffer is being created. After this method is called, this surface could be attached to a front buffer, another back buffer, or both to form a surface flipping structure. For more information, see DirectDrawSurface.addAttachedSurface . DirectDraw® supports an arbitrary number of surfaces in a flipping structure.
DDSCAPS_COMPLEX | Indicates a complex surface is being described. A complex surface results in the creation of more than one surface. The additional surfaces are attached to the root surface. The complex surface can be destroyed only by destroying the root.
DDSCAPS_FLIP | Indicates that this surface is a part of a surface flipping structure. When this capability is passed to the DirectDraw.createSurface method, a front buffer and one or more back buffers are created. DirectDraw® sets the DDSCAPS_FRONTBUFFER bit on the front-buffer surface and the DDSCAPS_BACKBUFFER bit on the surface adjacent to the front-buffer surface. The DDSurfaceDesc.backBufferCount field must be set to at least 1 for the method call to succeed. The DDSCAPS_COMPLEX capability must always be set when creating multiple surfaces by using the Class_DirectDraw.createSurface method.
DDSCAPS_FRONTBUFFER | Indicates that this surface is the front buffer of a surface flipping structure. This flag is typically set by the DirectDraw.createSurface method when the DDSCAPS_FLIP capability is set. If this capability is sent to the createSurface method, a stand-alone front buffer is created. This surface will not have the DDSCAPS_FLIP capability. It can be attached to other back buffers to form a flipping structure by using DirectDrawSurface.addAttachedSurface.
DDSCAPS_HWCODEC | Indicates that this surface should be able to have a stream decompressed to it by the hardware.
DDSCAPS_LIVEVIDEO | Indicates that this surface should be able to receive live video.
DDSCAPS_MIPMAP | Indicates that this surface is one level of a mipmap. This surface will be attached to other DDSCAPS_MIPMAP surfaces to form the mipmap. This can be done explicitly by creating a number of surfaces and attaching them by using the DirectDrawSurface.addAttachedSurface method, or implicitly by the DirectDraw.createSurface method. If this capability is set, DDSCAPS_TEXTURE must also be set.
DDSCAPS_MODEX | Indicates that this surface is a 320 x 200 or 320 x 240 Mode X surface.
DDSCAPS_OFFSCREENPLAIN | Indicates that this surface is any off-screen surface that is not an overlay, texture, z-buffer, front-buffer, back-buffer, or alpha surface. It is used to identify plain surfaces.
DDSCAPS_OVERLAY | Indicates that this surface is an overlay. It might or might not be directly visible, depending on whether it is currently being overlaid onto the primary surface. DDSCAPS_VISIBLE can be used to determine if it is being overlaid at the moment.
DDSCAPS_OWNDC | Indicates that this surface will have a device context (DC) association for a long period.
DDSCAPS_PALETTE | Indicates that this device driver allows unique DirectDrawPalette objects to be created and attached to this surface.
DDSCAPS_PRIMARYSURFACE | Indicates the surface is the primary surface. It represents what is visible to the user at the moment.
DDSCAPS_PRIMARYSURFACELEFT | Indicates that this surface is the primary surface for the left eye. It represents what is visible to the user’s left eye at the moment. When this surface is created, the surface with the DDSCAPS_PRIMARYSURFACE capability represents what is seen by the user’s right eye.
DDSCAPS_SYSTEMMEMORY | Indicates that this surface memory was allocated in system memory.
DDSCAPS_TEXTURE | Indicates that this surface can be used as a 3D texture. It does not indicate whether the surface is being used for that purpose.
DDSCAPS_VIDEOMEMORY | Indicates that this surface exists in display memory.
DDSCAPS_VISIBLE | Indicates that changes made to this surface are immediately visible. It is always set for the primary surface, as well as for overlays while they are being overlaid and texture maps while they are being textured.
DDSCAPS_WRITEONLY | Indicates that only write access is permitted to the surface. Read access from the surface can generate a general protection (GP) fault, but the read results from this surface will not be meaningful.
DDSCAPS_ZBUFFER | Indicates that this surface is the z-buffer. The z-buffer contains information that cannot be displayed. Instead, it contains bit-depth information that is used to determine which pixels are visible and which are obscured.
DDSCL_ALLOWMODEX | Allows the use of Mode X display modes.
DDSCL_ALLOWREBOOT | Allows CTRL+ALT+DEL to function while in exclusive (full-screen) mode.
DDSCL_EXCLUSIVE | Requests the exclusive level.
DDSCL_FULLSCREEN | Indicates that the exclusive-mode owner will be responsible for the entire primary surface. GDI can be ignored.
DDSCL_NORMAL | Indicates that the application will function as a regular Windows® application.
DDSCL_NOWINDOWCHANGES | Indicates that DirectDraw® is not allowed to minimize or restore the application window on activation.
DDSD_ALL | All input fields are valid.
DDSD_ALPHABITDEPTH | Indicates the DDSurfaceDesc.alphaBitDepth field is valid.
DDSD_BACKBUFFERCOUNT | Indicates the DDSurfaceDesc.backBufferCount field is valid.
DDSD_CAPS | Indicates the DDSurfaceDesc.ddsCaps field is valid.
DDSD_CKDESTBLT | Indicates the DDSurfaceDesc.colorkeyDestBltLow and DDSurfaceDesc.colorkeyDestBltHigh fields are valid.
DDSD_CKDESTOVERLAY | Indicates the DDSurfaceDesc.colorkeyDestOverlayLow and DDSurfaceDesc.colorkeyDestOverlayHigh fields are valid.
DDSD_CKSRCBLT | Indicates the DDSurfaceDesc.colorkeySrcBltLow and DDSurfaceDesc.colorkeySrcBltHigh fields are valid.
DDSD_CKSRCOVERLAY | Indicates the DDSurfaceDesc.colorkeySrcOverlayLow and DDSurfaceDesc.colorkeySrcOverlayHigh fields are valid.
DDSD_HEIGHT | Indicates the DDSurfaceDesc.height field is valid.
DDSD_MIPMAPCOUNT | Mip map count.
DDSD_PITCH | Indicates the DDSurfaceDesc.pitch field is valid.
DDSD_PIXELFORMAT | Reserved.
DDSD_REFRESHRATE | Refresh rate.
DDSD_WIDTH | Indicates the DDSurfaceDesc.width field is valid.
DDSD_ZBUFFERBITDEPTH | Z-buffer bit depth.
DDSVCAPS_ENIGMA | Indicates that the stereo view is accomplished using Enigma encoding.
DDSVCAPS_FLICKER | Indicates that the stereo view is accomplished using high-frequency flickering.
DDSVCAPS_REDBLUE | Indicates that the stereo view is accomplished when the viewer looks at the image through red and blue filters placed over the left and right eyes. All images must adapt their color spaces for this process.
DDSVCAPS_SPLIT | Indicates that the stereo view is accomplished with split-screen technology.
DDWAITVB_BLOCKBEGIN | Returns when the vertical-blank interval begins.
DDWAITVB_BLOCKBEGINEVENT | Triggers an event when the vertical blank begins. This value is not currently supported.
DDWAITVB_BLOCKEND | Returns when the vertical-blank interval ends and the display begins.
DPCAPS_GROUPOPTIMIZED | Indicates that the service provider bound to this DirectPlay2 object can optimize group (multicast) messaging.
DPCAPS_GUARANTEEDOPTIMIZED | Indicates that the service provider bound to this DirectPlay2 object supports guaranteed message delivery.
DPCAPS_GUARANTEEDSUPPORTED | Indicates that the DirectPlay object supports guaranteed message delivery, either because the service provider supports it or because DirectPlay implements it on a nonguaranteed service provider.
DPCAPS_ISHOST | Indicates that the DirectPlay2 object created by the calling application is the session host.
DPCAPS_KEEPALIVEOPTIMIZED | The service provider can detect when the connection to the session has been lost.
DPCPA_DTRFLOW | Indicates hardware flow control with DTR.
DPCPA_NOFLOW | Indicates no flow control.
DPCPA_RTSDTRFLOW | Indicates hardware flow control with RTS and DTR
DPCPA_RTSFLOW | Indicates hardware flow control with RTS
DPCPA_XONXOFFFLOW | Indicates software flow control (xon/xoff).
DPENUMPLAYERS_ALL | Enumerates all players.
DPENUMPLAYERS_GROUP | Enumerates groups as well as players.
DPENUMPLAYERS_LOCAL | Enumerates only those players that were created locally by this DirectPlay® object.
DPENUMPLAYERS_REMOTE | Enumerates only those players that were created by remote DirectPlay® objects.
DPENUMPLAYERS_SESSION | Enumerates the players in the session or the group in the session.
DPENUMSESSIONS_ALL | Enumerates all active sessions, whether they are available to join or not. Sessions where the player limit has been reached, new players have been disabled, or joining has been disabled will be enumerated. The application can examine the DPSessionDesc.flags field to determine if the session will allow new applications to join.
DPENUMSESSIONS_AVAILABLE | Enumerates all sessions with a matching password (if provided) that is allowing new applications to join.
DPESC_TIMEDOUT | The enumeration has timed out. Reset the timeOut parameter and return.
DPGET_LOCAL | Retrieves the local data set by this application.
DPGET_REMOTE | Retrieves the current data from the remote shared data space.
DPGETCAPS_GUARANTEED | Retrieves the capabilities for a guaranteed message delivery.
DPLAD_SYSTEM | Indicates that this is a system message informing the application of an event.
DPLCONNECTION_CREATESESSION | Create a new session as described in the session description.
DPLCONNECTION_JOINSESSION | Join the existing session as described in the session description
DPLSYS_APPTERMINATED | Indicates the application started by DirectPlayLobby.runApplication has terminated.
DPLSYS_CONNECTIONSETTINGSREAD | Indicates the application started by the DirectPlayLobby.runApplication method has read the connection settings.
DPLSYS_DPLAYCONNECTFAILED | Indicates the application started by DirectPlayLobby.runApplication failed to connect to a session.
DPLSYS_DPLAYCONNECTSUCCEEDED | Indicates the application started by DirectPlayLobby.runApplication has created a session and is ready for other applications to join or successfully join a session.
DPOPEN_CREATE | Creates a new instance of a gaming session.
DPOPEN_JOIN | Joins an existing instance of a gaming session.
DPPLAYERTYPE_GROUP | Indicates that the message applies to a group.
DPPLAYERTYPE_PLAYER | Indicates that the message applies to a player.
DPRECEIVE_ALL | Returns the first available message. This is the default.
DPRECEIVE_FROMPLAYER | Returns the first message from the player whose ID is specified in the PlayerIDs.sender field. System messages come from player ID DPID_SYSMSG.
DPRECEIVE_PEEK | Returns a message as specified by the other flags, but does not remove it from the message queue.
DPRECEIVE_TOPLAYER | Returns the first message intended for the player whose ID is specified in the PlayerIDs.receiver field.
DPSEND_CLOSESTREAM | Indicates that there will no longer be a lot of guaranteed messages being sent to this player.
DPSEND_GUARANTEED | Sends the message by using a guaranteed method of delivery if it is available.
DPSEND_HIGHPRIORITY | Sends the message high-priority. This will force the message to the front of the send queue for immediate transmission. The message will also go to the top of the receiving application’s receive buffer.
DPSEND_OPENSTREAM | Indicates an optimization hint to the service provider that there will be a lot of guaranteed messages being sent to this player.
DPSESSION_JOINDISABLED | No new applications can join this session. Any call to the DirectPlay2.open method with the DPOPEN_JOIN flag and the globally unique identifier (GUID) of this session instance will cause an error. If this flag is not specified, new remote applications can join the session until the session player limit is reached.
DPSESSION_KEEPALIVE | Automatically detect when remote players drop out of the game abnormally. Those players will be deleted from the session. If a temporary network outage caused the loss of the players, they will be informed when they return that they were dropped from the session. For more information, see the description for the DPSYS_SESSIONLOST system message in Using System Messages. If this flag is not specified, DirectPlay will not support this feature.
DPSESSION_MIGRATEHOST | If the current host exits, the host will attempt to migrate to another computer so that new players can continue to join. If this flag is not specified, the host will not migrate and new players cannot be created.
DPSESSION_NEWPLAYERSDISABLED | Indicates that new players cannot be created in the session. Any call to the DirectPlay2.createPlayer method by an application in the session will result in an error. Also, new applications cannot join the session. If this flag is not specified, players can be created until the session player limit is reached.
DPSESSION_NODATAMESSAGES | Do not send system messages when remote player or group data changes, by using the DirectPlay2.setPlayerData, DirectPlay2.setGroupData, DirectPlay2.setPlayerName, or DirectPlay2.setGroupName method. If this flag is not specified, messages will be generated indicating that the data changed.
DPSESSION_NOMESSAGEID | Do not attach data to messages indicating who the message is from and who it is to. Saves message overhead if this information is not relevant. (For more information, see the DirectPlay2.receive method.) If this flag is not specified, the message ID will be added.
DPSET_GUARANTEED | Propagates the data by using guaranteed messaging (if available). This flag can only be used with DPSET_REMOTE .
DPSET_LOCAL | This data is for local use only and will not be propagated.
DPSET_REMOTE | This data is for use by all the applications, and will be propagated to all the other applications in the session.
DPSYS_ADDPLAYERTOGROUP | An identifier for a system message sent when a player is added to a group.
DPSYS_CREATEPLAYERORGROUP | An identifier for a system message sent when a player or group is created in a session.
DPSYS_DELETEPLAYERFROMGROUP | An identifier for a system message sent when a player is deleted from a group.
DPSYS_DESTROYPLAYERORGROUP | An identifier for a system message sent when a player or group is deleted from a session.
DPSYS_HOST | An identifier for a system message sent when the current session host exits the session.
DPSYS_SESSIONLOST |
DPSYS_SETPLAYERORGROUPDATA | An identifier for a system message sent when the application changes remote player or group data.
DPSYS_SETPLAYERORGROUPNAME | An identifier for a system message sent when the name of a player or group has changed.
DS3D_DEFAULTDISTANCEFACTOR | An application can retrieve the current distance factor set for a listener by using the DirectSound3dListener.getDistanceFactor method. The default value is DS3D_DEFAULTDISTANCEFACTOR (1.0), meaning that one distance unit corresponds to 1 meter.
DS3D_DEFAULTDOPPLERFACTOR | DirectSound can apply to a sound up to 10 times the Doppler shift experienced in the real world by setting a Doppler factor. This Doppler factor has a range of 0 (no Doppler effects) to 10.0 (10 times the Doppler effects found in the physical world). The default value is DS3D_DEFAULTDOPPLERFACTOR (1.0).
DS3D_DEFERRED | Settings are not applied until the application calls the DirectSound3dListener.commitDeferredSettings method. This allows the application to change several settings and generate a single recalculation.
DS3D_IMMEDIATE | Settings are applied immediately, causing the system to recalculate the 3D coordinates for all 3D sound buffers.
DS3DMODE_DISABLE | Processing of 3D sound is disabled. The sound seems to originate from the center of the listener’s head.
DS3DMODE_HEADRELATIVE | Sound parameters (position, velocity, and orientation) are relative to the listener’s parameters. In this mode, the absolute parameters of the sound are updated automatically as the listener’s parameters change, so that the relative parameters remain constant.
DS3DMODE_NORMAL | Normal processing. This is the default mode.
DSBCAPS_CTRL3D | The buffer is a primary buffer that uses 3D control.
DSBCAPS_CTRLALL | The buffer must have all control capabilities.
DSBCAPS_CTRLDEFAULT | The buffer should have default control options. This is the same as specifying the DSBCAPS_CTRLPAN, DSBCAPS_CTRLVOLUME, and DSBCAPS_CTRLFREQUENCY flags.
DSBCAPS_CTRLFREQUENCY | The buffer must have frequency control capability.
DSBCAPS_CTRLPAN | The buffer must have pan control capability.
DSBCAPS_CTRLVOLUME | The buffer must have volume control capability.
DSBCAPS_GETCURRENTPOSITION2 | Indicates that DirectSoundBuffer.getCurrentPosition should use the new behavior of the play cursor. In DirectSound in DirectX 1, the play cursor was significantly ahead of the actual playing sound on emulated sound cards; it was directly behind the write cursor. Now, if the DSBCAPS_GETCURRENTPOSITION2 flag is specified, the application can get a more accurate play position. If this flag is not specified, the old behavior is preserved for compatibility. Note that this flag affects only emulated sound cards. If a DirectSound driver is present, the play cursor is accurate for DirectSound in all versions of Microsoft® DirectX™.
DSBCAPS_GLOBALFOCUS | The buffer is a global sound buffer. With this flag set, an application using DirectSound can continue to play its buffers if the user switches focus to another application, even if the new application uses DirectSound. The one exception is if you switch focus to a DirectSound application that uses the DSSCL_EXCLUSIVE or DSSCL_WRITEPRIMARY flag for its cooperative level. In this case, the global sounds from other applications will not be audible.
DSBCAPS_LOCHARDWARE | Forces the buffer to use hardware mixing, even if DSBCAPS_STATIC is not specified. If the device does not support hardware mixing or the required hardware memory is not available, the call to initialize will fail. The application must ensure that a mixing channel will be available for this buffer; this condition is not guaranteed.
DSBCAPS_LOCSOFTWARE | Forces the buffer to be stored in software memory and use software mixing, even if DSBCAPS_STATIC is specified and hardware resources are available.
DSBCAPS_PRIMARYBUFFER | Indicates that the buffer is a primary sound buffer. If this value is not specified, a secondary sound buffer will be created.
DSBCAPS_STATIC | Indicates that the buffer will be used for static sound data. Typically, these buffers are loaded once and played many times. These buffers are candidates for hardware memory.
DSBCAPS_STICKYFOCUS | Changes the focus behavior of the sound buffer. With this flag set, an application using Microsoft ® DirectSound® can continue to play its sticky focus buffers if the user switches to another application not using DirectSound. In this situation, the application’s normal buffers are muted, but the sticky focus buffers are still audible. This is useful for non-game applications, such as movie playback (ActiveMovie™), when the user wants to hear the soundtrack while typing in Microsoft® Word or Microsoft® Excel, for example. However, if the user switches to another DirectSound application, all sound buffers, both normal and sticky focus, in the previous application are muted.
DSBLOCK_FROMWRITECURSOR | Locks from the current write cursor, making a call to DirectSoundBuffer.getCurrentPosition unnecessary. If this flag is specified, the start parameter is ignored. This flag is optional.
DSBPLAY_LOOPING | Once the end of the audio buffer is reached, play restarts at the beginning of the buffer. Play continues until explicitly stopped. This flag must be set when playing primary sound buffers.
DSBSTATUS_BUFFERLOST | The buffer is lost and must be restored before it can be played or locked.
DSBSTATUS_LOOPING | The buffer is being looped. If this value is not set, the buffer will stop when it reaches the end of the sound data. Note that if this value is set, the buffer must also be playing.
DSBSTATUS_PLAYING | The buffer is playing. If this value is not set, the buffer is stopped.
DSCAPS_CERTIFIED | This driver has been tested and certified by Microsoft.
DSCAPS_CONTINUOUSRATE | The device supports all sample rates between the DSCaps.minSecondarySampleRate and DSCaps.maxSecondarySampleRate field values. Typically, this means that the actual output rate will be within +/-10Hz of the requested frequency.
DSCAPS_EMULDRIVER | The device does not have a DirectSound driver installed, so it is being emulated through the waveform-audio functions. Performance degradation should be expected.
DSCAPS_PRIMARY16BIT | The device supports primary sound buffers with 16-bit samples.
DSCAPS_PRIMARY8BIT | The device supports primary buffers with 8-bit samples.
DSCAPS_PRIMARYMONO | The device supports monophonic primary buffers.
DSCAPS_PRIMARYSTEREO | The device supports stereo primary buffers.
DSCAPS_SECONDARY16BIT | The device supports hardware-mixed secondary sound buffers with 16-bit samples.
DSCAPS_SECONDARY8BIT | The device supports hardware-mixed secondary buffers with 8-bit samples.
DSCAPS_SECONDARYMONO | The device supports hardware-mixed monophonic secondary buffers.
DSCAPS_SECONDARYSTEREO | The device supports hardware-mixed stereo secondary buffers.
DSSCL_EXCLUSIVE | Sets the application to the exclusive level. When it has the input focus, the application will be the only one audible (sounds from applications with the DSBCAPS_GLOBALFOCUS flag set will be muted). With this level, it also has all the privileges of the DSSCL_PRIORITY level. DirectSound will restore the hardware format, as specified by the most recent call to the DirectSoundBuffer.setFormat method, once the application gains the input focus. (Note that DirectSound will always restore the wave format, no matter what priority level is set.)
DSSCL_NORMAL | Sets the application to a fully cooperative status. Most applications should use this level, because it has the smoothest multitasking and resource-sharing behavior.
DSSCL_PRIORITY | Sets the application to the priority level. Applications with this cooperative level can call the DirectSoundBuffer.setFormat and DirectSound.compact methods.
DSSCL_WRITEPRIMARY | This is the highest priority level. The application has write access to the primary sound buffers. No secondary sound buffers in any application can be played.
DSSPEAKER_HEADPHONE | The speakers are headphones.
DSSPEAKER_MONO | The speakers are monaural.
DSSPEAKER_QUAD | The speakers are quadraphonic.
DSSPEAKER_STEREO | The speakers are stereo (default value).
DSSPEAKER_SURROUND | The speakers are surround sound.
JOY_BUTTON1 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON10 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON11 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON12 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON13 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON14 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON15 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON16 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON17 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON18 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON19 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON2 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON20 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON21 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON22 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON23 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON24 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON25 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON26 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON27 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON28 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON29 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON3 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON30 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON31 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON32 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON4 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON5 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON6 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON7 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON8 | Identifier for one of the up to 32 joystick buttons.
JOY_BUTTON9 | Identifier for one of the up to 32 joystick buttons.
JOY_CAL_READ3 | Reads the x, y, and z axis information, and then stores the raw values in JoyInfo.xPos , JoyInfo.yPos , and JoyInfo.zPos fields.
JOY_CAL_READ4 | Reads the rudder, x, y, and z axis information, and then stores the raw values in JoyInfo.rPos , JoyInfo.xPos , JoyInfo.yPos , and JoyInfo.zPos fields.
JOY_CAL_READ5 | Reads the rudder, x, y, z, and u axis information, and then stores the raw values in JoyInfo.rPos , JoyInfo.xPos , JoyInfo.yPos , JoyInfo.zPos , and JoyInfo.uPos fields.
JOY_CAL_READ6 | Reads the raw v axis data if a joystick minidriver is present to provide the information. Returns 0 otherwise.
JOY_CAL_READALWAYS | Reads the joystick port even if the driver does not detect a device.
JOY_CAL_READRONLY | Reads the rudder (fouth axis) information if a joystick minidriver is present to provide the data, and then stores the raw value in the JoyInfo.rPos field. Returns 0 otherwise.
JOY_CAL_READUONLY | Reads the u axis (fifth axis) information if a joystick minidriver is present to provide the data, and then stores the raw value in the JoyInfo.uPos field. Returns 0 otherwise.
JOY_CAL_READVONLY | Reads the v axis (sixth axis) information if a joystick minidriver is present to provide the data, and then stores the raw value in the JoyInfo.vPos field. Returns 0 otherwise.
JOY_CAL_READXONLY | Reads the x axis information if a joystick minidriver is present to provide the data, and then stores the raw value in the JoyInfo.xPos field.
JOY_CAL_READXYONLY | Reads the x and y axis information if a joystick minidriver is present to provide the data, and then stores the raw value in the JoyInfo.xPos and JoyInfo.yPos fields respectively.
JOY_CAL_READYONLY | Reads the y axis information if a joystick minidriver is present to provide the data, and then stores the raw value in the JoyInfo.yPos field.
JOY_CAL_READZONLY | Reads the z axis information if a joystick minidriver is present to provide the data, and then stores the raw value in the JoyInfo.zPos field.
JOY_POVBACKWARD | Point-Of-View hat is pressed backward. The value 18,000 represents an orientation of 180.00 degrees.
JOY_POVCENTERED | Point-Of-View hat is in the neutral position. The value –1 means the POV hat has no angle to report.
JOY_POVFORWARD | Point-Of_View hat is pressed forward. The value 0 represents an orientation of 0.00 degrees.
JOY_POVLEFT | Point-Of-View hat is pressed to the left. The value 27,000 represents an orientation of 270.00 degrees.
JOY_POVRIGHT | Point-Of-View hat is pressed to the right. The value 9000 represents an orientation of 90.00 degrees.
JOY_RETURNALL | Equivalent to setting all the JOY_RETURN* values except JOY_RETURNRAWDATA.
JOY_RETURNBUTTONS | The buttons field contains valid state information for each joystick button.
JOY_RETURNCENTERED | Centers the joystick neutral position to the middle value of each movement axis.
JOY_RETURNPOV | The pov field contains valid information about the Point-Of-View control, expressed in discrete units.
JOY_RETURNPOVCTS | The pov field contains valid information about the Point-Of-View control, expressed in continuous, one-hundredth of a degree units.
JOY_RETURNR | The JoyInfo.rPos field contains valid rudder information. This indicates the existance of a fourth axis.
JOY_RETURNRAWDATA | Indicates that uncalibrated joystick readings are stored in this class.
JOY_RETURNU | The JoyInfo.uPos field contains valid data for the fifth axis of the joystick. If this axis is not available, 0 is returned.
JOY_RETURNV | The JoyInfo.vPos field contains valid data for the sixth axis of the joystick. If this axis is not available, 0 is returned.
JOY_RETURNX | The JoyInfo.xPos field contains valid data for the x-coordinate of the joystick.
JOY_RETURNY | The JoyInfo.yPos member contains valid data for the y-coordinate of the joystick.
JOY_RETURNZ | The JoyInfo.zPos field contains valid data for the z-coordinate of the joystick.
JOY_USEDEADZONE | Expand the range for the neutral position of the joystick. The joystick driver returs a constant value for all positions in the dead zone.
JOYCAPS_HASPOV | The joystick has Point-Of-View information.
JOYCAPS_HASR | The joystick has rudder (fourth axis) information.
JOYCAPS_HASU | The joystick has u-coordinate information.
JOYCAPS_HASV | The joystick has v-coordinate information.
JOYCAPS_HASZ | The joystick has z-coordinate information
JOYCAPS_POV4DIR | The joystick Point-Of-View supports discrete values.
JOYCAPS_POVCTS | The joystick Point-Of-View supports continuous degree bearings.
JOYERR_BASE |
JOYERR_NOCANDO | Request was not completed.
JOYERR_NOERROR | There is no error.
JOYERR_PARMS | Bad parameters.
JOYERR_UNPLUGGED | The joystick is unplugged.
JOYSTICKID1 | Identifier of the joystick.
JOYSTICKID2 | Identifier of the joystick.


Id3dEnumDevicesCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

Id3dEnumDevicesCallback Interface

The Id3dEnumDevicesCallback Interface of the com.ms.directx package is used with enumDevices method to set the callback function to be called for each device.

public interface Id3dEnumDevicesCallback extends IUnknown
{
  // Methods
  public void callbackd3dEnumDevices(_Guid g, String devDesc,
        String devName, D3dDeviceDesc hwDevDesc,
        D3dDeviceDesc helDevDesc, IUnknown args);
}

Hierarchy

IUnknown
  |
  +--Id3dEnumDevicesCallback


Methods (Id3dEnumDevicesCallback Interface)

 Microsoft SDK for Java

Id3dEnumDevicesCallback Interface Methods

The Id3dEnumDevicesCallback Interface contains the following method:

callbackd3dEnumDevices enumerates installed Direct3D devices.


callbackd3dEnumDevices (Id3dEnumDevicesCallback Interface)

 Microsoft SDK for Java

callbackd3dEnumDevices

This method of the Id3dEnumDevicesCallback Interface enumerates installed Direct3D devices.

Syntax

public void callbackd3dEnumDevices(_Guid g, String devDesc, String devName, D3dDeviceDesc hwDevDesc, D3dDeviceDesc helDevDesc, IUnknown rgs);

Parameters

g | A _Guid object that contains a globally unique identifier (GUID).
devDesc | A textual description of the device.
devName | The device name.
hwDeviceDesc | A D3dDeviceDesc object that contains the hardware capabilities of the Direct3D device.
helDeviceDesc | A D3dDeviceDesc object that contains the emulated capabilities of the Direct3D device.
args | Application-defined data passed to this callback function.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


Id3drmCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

Id3drmCallback Interface

The Id3drmCallback Interface of the com.ms.directx package is used with Direct3dRMObject.addDestroyCallback and Direct3dRMObject.deleteDestroyCallback to set or remove the callback function to be called when an object is destroyed.

public interface Id3drmCallback extends IUnknown
{
  // Methods
  public void callbackDestroyObject(IUnknown pArgs);
}

See also

Direct3dRMAnimation, Direct3dRMAnimationSet, Direct3dRMDevice, Direct3dRMFace, Direct3dRMFrame, Direct3dRMLight, Direct3dRMMaterial, Direct3dRMMesh, Direct3dRMMeshBuilder, Direct3dRMTexture, Direct3dRMUserVisual, Direct3dRMViewport, Direct3dRMWinDevice, Direct3dRMWrap.

Hierarchy

IUnknown
  |
  +--Id3drmCallback


Methods (Id3drmCallback Interface)

 Microsoft SDK for Java

Id3drmCallback Interface Methods

The Id3drmCallback Interface contains the following method:

callbackDestroyObject enumerates an object that is being destroyed.


callbackDestroyObject (Id3drmCallback Interface)

 Microsoft SDK for Java

callbackDestroyObject

This method of the Id3drmCallback Interface enumerates an object that is being destroyed. This callback function is application-defined.

Syntax

public void callbackDestroyObject(IUnknown pArgs);

Parameters

pArgs Application-defined data passed to this callback function.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


IDeviceUpdateCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDeviceUpdateCallback Interface

The IDeviceUpdateCallback Interface of the com.ms.directx package is used with addUpdateCallback and deleteUpdateCallback to set or remove the callback function that is called whenever a device is updated.

public interface IDeviceUpdateCallback extends IUnknown
{
  // Methods
  public void callbackDeviceUpdate(Direct3dRMDevice f,
        IUnknown pArgs, int x, D3dRect update);
}

See Also

com.ms.directX.Direct3dRMDevice

Hierarchy

IUnknown
  |
  +--IDeviceUpdateCallback


Methods (IDeviceUpdateCallback Interface)

 Microsoft SDK for Java

IDeviceUpdateCallback Interface Methods

The IDeviceUpdateCallback Interface contains the following method:

callbackDeviceUpdate alerts the application whenever the device changes. This callback function is application-defined.


callbackDeviceUpdate (IDeviceUpdateCallback Interface)

 Microsoft SDK for Java

callbackDeviceUpdate

This method of the IDeviceUpdateCallback Interface alerts the application whenever the device changes. This callback function is application-defined.

Syntax

public void callbackDeviceUpdate(Direct3dRMDevice f, IUnknown pArgs, int x, D3dRect update);

Parameters

f | The Direct3dRMDevice object that this callback function applies to.
pArgs | The application-defined data passed to this callback function.
x | The number of rectangles specified in the update parameter.
update | A D3dRect object that describes the area to be updated. The coordinates are specified in device units.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


IDirect3d Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3d Interface

This is an interface of the com.ms.directx package

public interface IDirect3d extends IUnknown
{
  // Methods
  public Direct3dLight createLight();
  public Direct3dMaterial createMaterial();
  public Direct3dViewport createViewport();
  public void enumDevices(Id3dEnumDevicesCallback fn, IUnknown p);
  public void findDevice(D3dFindDeviceSearch ds,
        D3dFindDeviceResult hresult, D3dFindDeviceResult sresult);
  public _Guid findDeviceForColorModel(int cm, int hardware);
  public void initialize(_Guid id);
  public int systemBpp();
}

For a description of methods and parameters, see Direct3d.

Hierarchy

IUnknown
  |
  +--IDirect3d


Methods (IDirect3d Interface)

 Microsoft SDK for Java

IDirect3d Interface Methods

The IDirect3d Interface contains the following methods:

createLight
createMaterial
createViewport
enumDevices
findDevice
findDeviceForColorModel
initialize
systemBpp


createLight (IDirect3d Interface)

 Microsoft SDK for Java

createLight

This is a method of the IDirect3d Interface.

Syntax

public Direct3dLight createLight();


createMaterial (IDirect3d Interface)

 Microsoft SDK for Java

createMaterial

This is a method of the IDirect3d Interface.

Syntax

public Direct3dMaterial createMaterial();


createViewport (IDirect3d Interface)

 Microsoft SDK for Java

createViewport

This is a method of the IDirect3d Interface.

Syntax

public Direct3dViewport createViewport();


enumDevices (IDirect3d Interface)

 Microsoft SDK for Java

enumDevices

This is a method of the IDirect3d Interface.

Syntax

public void enumDevices(Id3dEnumDevicesCallback fn, IUnknown p);


findDevice (IDirect3d Interface)

 Microsoft SDK for Java

findDevice

This is a method of the IDirect3d Interface.

Syntax

public void findDevice(D3dFindDeviceSearch ds, D3dFindDeviceResult hresult, D3dFindDeviceResult sresult);


findDeviceForColorModel (IDirect3d Interface)

 Microsoft SDK for Java

findDeviceForColorModel

This is a method of the IDirect3d Interface.

Syntax

public _Guid findDeviceForColorModel(int cm, int hardware);


initialize (IDirect3d Interface)

 Microsoft SDK for Java

initialize

This is a method of the IDirect3d Interface.

Syntax

public void initialize(_Guid id);


systemBpp (IDirect3d Interface)

 Microsoft SDK for Java

systemBpp

This is a method of the IDirect3d Interface.

Syntax

public int systemBpp();


IDirect3dDevice Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dDevice Interface

This is an interface of the com.ms.directx package.

public interface IDirect3dDevice extends IUnknown
{
  // Methods
  public void addViewport(Direct3dViewport vport);
  public void beginScene();
  public Direct3dExecuteBuffer createExecuteBuffer(
        D3dExecuteBufferDesc Desc);
  public int createMatrix();
  public void deleteMatrix(int hdl);
  public void deleteViewport(Direct3dViewport vport);
  public void endScene();
  public void enumTextureFormats(IEnumTextureFormatsCallback fn,
        IUnknown args);
  public void execute(Direct3dExecuteBuffer eb,
        Direct3dViewport vp, int flags);
  public void flushExecuteBuffer(D3dExecuteBufferDesc buf,
        int[] buffer);
  public void getCaps(D3dDeviceDesc HWDesc, D3dDeviceDesc HELDesc);
  public Direct3d getDirect3D();
  public void getMatrix(int hdl, D3dMatrix mat);
  public void getPickRecords(int[] flags, D3dPickRecord val);
  public void getStats(D3dStats stat);
  public void initialize(Direct3d dev, _Guid g, D3dDeviceDesc Desc);
  public Direct3dViewport nextViewport(Direct3dViewport vp1,
        int flags);
  public void pick(Direct3dExecuteBuffer eb,
        Direct3dViewport vport, int flags, D3dRect Rect);
  public void setMatrix(int hdl, D3dMatrix mat);
  public void swapTextureHandles(Direct3dTexture tex1,
        Direct3dTexture tex2);
}

For a description of methods and parameters, see Direct3dDevice

Hierarchy

IUnknown
  |
  +--IDirect3dDevice


Methods (IDirect3dDevice Interface)

 Microsoft SDK for Java

IDirect3dDevice Interface Methods

The IDirect3dDevice Interface contains the following methods:

addViewport
beginScene
createExecuteBuffer createMatrix
deleteMatrix
deleteViewport
endScene
enumTextureFormats
execute
flushExecuteBuffer
getCaps
getDirect3D
getMatrix
getPickRecords
getStats
initialize
nextViewport
pick
setMatrix
swapTextureHandles


addViewport (IDirect3dDevice Interface)

 Microsoft SDK for Java

addViewport

This is a method of the IDirect3dDevice Interface.

Syntax

public void addViewport(Direct3dViewport vport);


beginScene (IDirect3dDevice Interface)

 Microsoft SDK for Java

beginScene

This is a method of the IDirect3dDevice Interface.

Syntax

public void beginScene();


createExecuteBuffer (IDirect3dDevice Interface)

 Microsoft SDK for Java

createExecuteBuffer

This is a method of the IDirect3dDevice Interface.

Syntax

public Direct3dExecuteBuffer createExecuteBuffer(D3dExecuteBufferDesc Desc);


createMatrix (IDirect3dDevice Interface)

 Microsoft SDK for Java

createMatrix

This is a method of the IDirect3dDevice Interface.

Syntax

public int createMatrix();


deleteMatrix (IDirect3dDevice Interface)

 Microsoft SDK for Java

deleteMatrix

This is a method of the IDirect3dDevice Interface.

Syntax

public void deleteMatrix(int hdl);


deleteViewport (IDirect3dDevice Interface)

 Microsoft SDK for Java

deleteViewport

This is a method of the IDirect3dDevice Interface.

Syntax

public void deleteViewport(Direct3dViewport vport);


endScene (IDirect3dDevice Interface)

 Microsoft SDK for Java

endScene

This is a method of the IDirect3dDevice Interface.

Syntax

public void endScene();


enumTextureFormats (IDirect3dDevice Interface)

 Microsoft SDK for Java

enumTextureFormats

This is a method of the IDirect3dDevice Interface.

Syntax

public void enumTextureFormats(IEnumTextureFormatsCallback fn, IUnknown args);


execute (IDirect3dDevice Interface)

 Microsoft SDK for Java

execute

This is a method of the IDirect3dDevice Interface.

Syntax

public void execute(Direct3dExecuteBuffer eb, Direct3dViewport vp, int flags);


flushExecuteBuffer (IDirect3dDevice Interface)

 Microsoft SDK for Java

flushExecuteBuffer

This is a method of the IDirect3dDevice Interface.

Syntax

public void flushExecuteBuffer(D3dExecuteBufferDesc buf, int[] buffer);


getCaps (IDirect3dDevice Interface)

 Microsoft SDK for Java

getCaps

This is a method of the IDirect3dDevice Interface.

Syntax

public void getCaps(D3dDeviceDesc HWDesc, D3dDeviceDesc HELDesc);


getDirect3D (IDirect3dDevice Interface)

 Microsoft SDK for Java

getDirect3D

This is a method of the IDirect3dDevice Interface.

Syntax

public Direct3d getDirect3D();


getMatrix (IDirect3dDevice Interface)

 Microsoft SDK for Java

getMatrix

This is a method of the IDirect3dDevice Interface.

Syntax

public void getMatrix(int hdl, D3dMatrix mat);


getPickRecords (IDirect3dDevice Interface)

 Microsoft SDK for Java

getPickRecords

This is a method of the IDirect3dDevice Interface.

Syntax

public void getPickRecords(int[] flags, D3dPickRecord val);


getStats (IDirect3dDevice Interface)

 Microsoft SDK for Java

getStats

This is a method of the IDirect3dDevice Interface.

Syntax

public void getStats(D3dStats stat);


initialize (IDirect3dDevice Interface)

 Microsoft SDK for Java

initialize

This is a method of the IDirect3dDevice Interface.

Syntax

public void initialize(Direct3d dev, _Guid g, D3dDeviceDesc Desc);


nextViewport (IDirect3dDevice Interface)

 Microsoft SDK for Java

nextViewport

This is a method of the IDirect3dDevice Interface.

Syntax

public Direct3dViewport nextViewport(Direct3dViewport vp1, int flags);


pick (IDirect3dDevice Interface)

 Microsoft SDK for Java

pick

This is a method of the IDirect3dDevice Interface.

Syntax

public void pick(Direct3dExecuteBuffer eb, Direct3dViewport vport, int flags, D3dRect Rect);


setMatrix (IDirect3dDevice Interface)

 Microsoft SDK for Java

setMatrix

This is a method of the IDirect3dDevice Interface.

Syntax

public void setMatrix(int hdl, D3dMatrix mat);


swapTextureHandles (IDirect3dDevice Interface)

 Microsoft SDK for Java

swapTextureHandles

This is a method of the IDirect3dDevice Interface.

Syntax

public void swapTextureHandles(Direct3dTexture tex1, Direct3dTexture tex2);


IDirect3dExecuteBuffer Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dExecuteBuffer Interface

This is an interface of the com.ms.directx package.

public interface IDirect3dExecuteBuffer extends IUnknown
{
  // Methods
  public int addLVertexData(D3dLVertex vertex, int bufferindex);
  public int addTLVertexData(D3dTLVertex vertex, int bufferindex);
  public int addVertexData(D3dVertex vertex, int bufferindex);
  public int exit(int bufferindex);
  public void getExecuteData(D3dExecuteData data);
  public void lock(D3dExecuteBufferDesc Desc);
  public int processVertices(int cnt, int bufferindex);
  public int processVerticesData(int flags, int start, int dest,
        int cnt, int bufferindex);
  public void setExecuteData(D3dExecuteData data);
  public int setStatus(int flags, int status, int x1, int y1,
        int x2, int y2, int bufferindex);
  public int stateLight(int cnt, int bufferindex);
  public int stateLightData(int flags, float Arg, int bufferindex);
  public int stateRender(int cnt, int bufferindex);
  public int stateRenderData(int flags, int Arg, int bufferindex);
  public int stateTransForm(int cnt, int bufferindex);
  public int stateTransFormData(int flags, int Arg,
        int bufferindex);
  public int triangleList(int cnt, int bufferindex);
  public int triangleListData(D3dTriangle triangle,
        int bufferindex);
  public void unlock();
}

For a description of methods and parameters, see Direct3dExecuteBuffer.

Hierarchy

IUnknown
  |
  +--IDirect3dExecuteBuffer


Methods (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

IDirect3dExecuteBuffer Interface Methods

The IDirect3dExecuteBuffer Interface contains the following methods:

addLVertexData
addTLVertexData
addVertexData
exit
getExecuteData
lock
processVertices
processVerticesData
setExecuteData
setStatus
stateLight
stateLightData
stateRender
stateRenderData
stateTransForm
stateTransFormData
triangleList
triangleListData
unlock


addLVertexData (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

addLVertexData

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int addLVertexData(D3dLVertex vertex, int bufferindex);


addTLVertexData (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

addTLVertexData

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int addTLVertexData(D3dTLVertex vertex, int bufferindex);


addVertexData (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

addVertexData

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int addVertexData(D3dVertex vertex, int bufferindex);


exit (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

exit

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int exit(int bufferindex);


getExecuteData (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

getExecuteData

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public void getExecuteData(D3dExecuteData data);


lock (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

lock

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public void lock(D3dExecuteBufferDesc Desc);


processVertices (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

processVertices

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int processVertices(int cnt, int bufferindex);


processVerticesData (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

processVerticesData

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int processVerticesData(int flags, int start, int dest, int cnt, int bufferindex);


setExecuteData (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

setExecuteData

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public void setExecuteData(D3dExecuteData data);


setStatus (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

setStatus

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int setStatus(int flags, int status, int x1, int y1, int x2, int y2, int bufferindex);


stateLight (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

stateLight

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int stateLight(int cnt, int bufferindex);


stateLightData (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

stateLightData

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int stateLightData(int flags, float Arg, int bufferindex);


stateRender (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

stateRender

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int stateRender(int cnt, int bufferindex);


stateRenderData (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

stateRenderData

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int stateRenderData(int flags, int Arg, int bufferindex);


stateTransForm (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

stateTransForm

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int stateTransForm(int cnt, int bufferindex);


stateTransFormData (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

stateTransFormData

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int stateTransFormData(int flags, int Arg, int bufferindex);


triangleList (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

triangleList

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int triangleList(int cnt, int bufferindex);


triangleListData (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

triangleListData

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public int triangleListData(D3dTriangle triangle, int bufferindex);


unlock (IDirect3dExecuteBuffer Interface)

 Microsoft SDK for Java

unlock

This is a method of the IDirect3dExecuteBuffer Interface.

Syntax

public void unlock();


IDirect3dLight Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dLight Interface

This is an interface of the com.ms.directx package.

public interface IDirect3dLight extends IUnknown
{
  // Methods
  public void getLight(D3dLightDesc light);
  public void setLight(D3dLightDesc light);
}

For a description of methods and parameters, see Direct3dLight

Hierarchy

IUnknown
  |
  +--IDirect3dLight


Methods (IDirect3dLight Interface)

 Microsoft SDK for Java

IDirect3dLight Interface Methods

The IDirect3dLight Interface contains the following methods:

getLight
setLight


getLight (IDirect3dLight Interface)

 Microsoft SDK for Java

getLight

This is a method of the IDirect3dLight Interface.

Syntax

public void getLight(D3dLightDesc light);


setLight (IDirect3dLight Interface)

 Microsoft SDK for Java

setLight

This is a method of the IDirect3dLight Interface.

Syntax

public void setLight(D3dLightDesc light);


IDirect3dMaterial Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dMaterial Interface

This is an interface of the com.ms.directx package.

public interface IDirect3dMaterial extends IUnknown
{
  // Methods
  public int getHandle(Direct3dDevice dev);
  public void getMaterial(D3dMaterialDesc mat);
  public void reserve();
  public void setMaterial(D3dMaterialDesc mat);
  public void unreserve();
}

For a description of methods and parameters, see Direct3dMaterial.

Hierarchy

IUnknown
  |
  +--IDirect3dMaterial


Methods (IDirect3dMaterial Interface)

 Microsoft SDK for Java

IDirect3dMaterial Interface Methods

The IDirect3dMaterial Interface contains the following methods:

getHandle
getMaterial
reserve
setMaterial
unreserve


getHandle (IDirect3dMaterial Interface)

 Microsoft SDK for Java

getHandle

This is a method of the IDirect3dMaterial Interface.

Syntax

public int getHandle(Direct3dDevice dev);


getMaterial (IDirect3dMaterial Interface)

 Microsoft SDK for Java

getMaterial

This is a method of the IDirect3dMaterial Interface.

Syntax

public void getMaterial(D3dMaterialDesc mat);


reserve (IDirect3dMaterial Interface)

 Microsoft SDK for Java

reserve

This is a method of the IDirect3dMaterial Interface.

Syntax

public void reserve();


setMaterial (IDirect3dMaterial Interface)

 Microsoft SDK for Java

setMaterial

This is a method of the IDirect3dMaterial Interface.

Syntax

public void setMaterial(D3dMaterialDesc mat);


unreserve (IDirect3dMaterial Interface)

 Microsoft SDK for Java

unreserve

This is a method of the IDirect3dMaterial Interface.

Syntax

public void unreserve();


IDirect3dRM Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRM Interface

This is an interface of the com.ms.directx package.

public interface IDirect3dRM extends IUnknown
{
  // Methods
  public void addSearchPath(String name);
  public Direct3dRMAnimation createAnimation();
  public Direct3dRMAnimationSet createAnimationSet();
  public int createColorRGB(float red, float green, float blue);
  public Direct3dRMDevice createDevice(int v1, int v2);
  public Direct3dRMDevice createDeviceFromClipper(DirectDrawClipper
        lpDDClipper, _Guid g, int width, int height);
  public Direct3dRMDevice createDeviceFromD3D(Direct3d d3d,
        Direct3dDevice dev);
  public Direct3dRMDevice createDeviceFromSurface(_Guid g,
        DirectDraw dd, DirectDrawSurface DDsBack);
  public Direct3dRMFace createFace();
  public Direct3dRMFrame createFrame(Direct3dRMFrame parent);
  public Direct3dRMLight createLight(int t, int c);
  public Direct3dRMLight createLightRGB(int lt, float vred,
        float vgreen, float vblue);
  public Direct3dRMMaterial createMaterial(float d);
  public Direct3dRMMesh createMesh();
  public Direct3dRMMeshBuilder createMeshBuilder();
  public Direct3dRM createObject(_Guid rclsid, IUnknown p,
        _Guid rid);
  public Direct3dRMVisual createShadow(Direct3dRMVisual v,
        Direct3dRMLight l, float px, float py, float pz,
        float nx, float ny, float nz);
  public Direct3dRMTexture createTexture(D3dRMImage image,
        byte[] buffer1, byte[] pal);
  public Direct3dRMTexture createTextureFromSurface(
        DirectDrawSurface ddS);
  public Direct3dRMUserVisual createUserVisual(
        IUserVisualCallback fn, IUnknown Arg);
  public Direct3dRMViewport createViewport(Direct3dRMDevice dev,
        Direct3dRMFrame fr, int l, int t, int w, int h);
  public Direct3dRMWrap createWrap(int t, Direct3dRMFrame f,
        float ox, float oy, float oz, float dx, float dy,
        float dz, float ux, float uy, float uz, float ou,
        float ov, float su, float sv);
  public void enumerateObjects(IEnumerateObjectsCallback fn,
        IUnknown pArgs);
  public Direct3dRMDeviceArray getDevices();
  public Direct3dRMObject getNamedObject(String name);
  public String getSearchPath();
  public void loadFromFileByPos(String fnam, int[] id, _Guid g, int
        cnt, int options, ILoadCallback fn1, int[] arg1,
        ILoadTextureCallback fn2, int[] arg2, Direct3dRMFrame f);
  public Direct3dRMTexture loadTexture(String name);
  public Direct3dRMTexture loadTextureFromResource(int hnd);
  public void setDefaultTextureColors(int ds);
  public void setDefaultTextureShades(int ds);
  public void setSearchPath(String name);
  public void tick(float val);
  public void vectorCrossProduct(D3dVector lpd, D3dVector lps1,
        D3dVector lps2);
  public void vectorNormalise(D3dVector d);
}

For a description of methods and parameters, see Direct3dRM.

Hierarchy

IUnknown
  |
  +--IDirect3dRM


Methods (IDirect3dRM Interface)

 Microsoft SDK for Java

IDirect3dRM Interface Methods

The IDirect3dRM Interface contains the following methods:

addSearchPath
createAnimation
createAnimationSet
createColorRGB
createDevice
createDeviceFromClipper
createDeviceFromD3D
createDeviceFromSurface
createFace
createFrame
createLight
createLightRGB
createMaterial
createMesh
createMeshBuilder
createObject
createShadow
createTexture
createTextureFromSurface
createUserVisual
createViewport
createWrap
enumerateObjects
getDevices
getNamedObject
getSearchPath
loadFromFileByPos
loadTexture
loadTextureFromResource
setDefaultTextureColors
setDefaultTextureShades
setSearchPath
tick
vectorCrossProduct
vectorNormalise


addSearchPath (IDirect3dRM Interface)

 Microsoft SDK for Java

addSearchPath

This is a method of the IDirect3dRM Interface.

Syntax

public void addSearchPath(String name);


createAnimation (IDirect3dRM Interface)

 Microsoft SDK for Java

createAnimation

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMAnimation createAnimation();


createAnimationSet (IDirect3dRM Interface)

 Microsoft SDK for Java

createAnimationSet

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMAnimationSet createAnimationSet();


createColorRGB (IDirect3dRM Interface)

 Microsoft SDK for Java

createColorRGB

This is a method of the IDirect3dRM Interface.

Syntax

public int createColorRGB(float red, float green, float blue);


createDevice (IDirect3dRM Interface)

 Microsoft SDK for Java

createDevice

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMDevice createDevice(int v1, int v2);


createDeviceFromClipper (IDirect3dRM Interface)

 Microsoft SDK for Java

createDeviceFromClipper

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMDevice createDeviceFromClipper( DirectDrawClipper lpDDClipper, _Guid g, int width, int height);


createDeviceFromD3D (IDirect3dRM Interface)

 Microsoft SDK for Java

createDeviceFromD3D

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMDevice createDeviceFromD3D(Direct3d d3d, Direct3dDevice dev);


createDeviceFromSurface (IDirect3dRM Interface)

 Microsoft SDK for Java

createDeviceFromSurface

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMDevice createDeviceFromSurface(_Guid g, DirectDraw dd, DirectDrawSurface DDsBack);


createFace (IDirect3dRM Interface)

 Microsoft SDK for Java

createFace

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMFace createFace();


createFrame (IDirect3dRM Interface)

 Microsoft SDK for Java

createFrame

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMFrame createFrame(Direct3dRMFrame parent);


createLight (IDirect3dRM Interface)

 Microsoft SDK for Java

createLight

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMLight createLight(int t, int c);


createLightRGB (IDirect3dRM Interface)

 Microsoft SDK for Java

createLightRGB

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMLight createLightRGB(int lt, float vred, float vgreen, float vblue);


createMaterial (IDirect3dRM Interface)

 Microsoft SDK for Java

createMaterial

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMMaterial createMaterial(float d);


createMesh (IDirect3dRM Interface)

 Microsoft SDK for Java

createMesh

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMMesh createMesh();


createMeshBuilder (IDirect3dRM Interface)

 Microsoft SDK for Java

createMeshBuilder

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMMeshBuilder createMeshBuilder();


createObject (IDirect3dRM Interface)

 Microsoft SDK for Java

createObject

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRM createObject(_Guid rclsid, IUnknown p, _Guid rid);


createShadow (IDirect3dRM Interface)

 Microsoft SDK for Java

createShadow

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMVisual createShadow(Direct3dRMVisual v, Direct3dRMLight l, float px, float py, float pz, float nx, float ny, float nz);


createTexture (IDirect3dRM Interface)

 Microsoft SDK for Java

createTexture

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMTexture createTexture(D3dRMImage image, byte[] buffer1, byte[] pal);


createTextureFromSurface (IDirect3dRM Interface)

 Microsoft SDK for Java

createTextureFromSurface

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMTexture createTextureFromSurface(DirectDrawSurface ddS);


createUserVisual (IDirect3dRM Interface)

 Microsoft SDK for Java

createUserVisual

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMUserVisual createUserVisual(IUserVisualCallback fn, IUnknown Arg);


createViewport (IDirect3dRM Interface)

 Microsoft SDK for Java

createViewport

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMViewport createViewport(Direct3dRMDevice dev, Direct3dRMFrame fr, int l, int t, int w, int h);


createWrap (IDirect3dRM Interface)

 Microsoft SDK for Java

createWrap

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMWrap createWrap(int t, Direct3dRMFrame f, float ox, float oy, float oz, float dx, float dy, float dz, float ux, float uy, float uz, float ou, float ov, float su, float sv);


enumerateObjects (IDirect3dRM Interface)

 Microsoft SDK for Java

enumerateObjects

This is a method of the IDirect3dRM Interface.

Syntax

public void enumerateObjects(IEnumerateObjectsCallback fn, IUnknown pArgs);


getDevices (IDirect3dRM Interface)

 Microsoft SDK for Java

getDevices

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMDeviceArray getDevices();


getNamedObject (IDirect3dRM Interface)

 Microsoft SDK for Java

getNamedObject

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMObject getNamedObject(String name);


getSearchPath (IDirect3dRM Interface)

 Microsoft SDK for Java

getSearchPath

This is a method of the IDirect3dRM Interface.

Syntax

public String getSearchPath();


loadFromFileByPos (IDirect3dRM Interface)

 Microsoft SDK for Java

loadFromFileByPos

This is a method of the IDirect3dRM Interface.

Syntax

public void loadFromFileByPos(String fnam, int[] id, _Guid g, int cnt, int options, ILoadCallback fn1, int[] arg1, ILoadTextureCallback fn2, int[] arg2, Direct3dRMFrame f);


loadTexture (IDirect3dRM Interface)

 Microsoft SDK for Java

loadTexture

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMTexture loadTexture(String name);


loadTextureFromResource (IDirect3dRM Interface)

 Microsoft SDK for Java

loadTextureFromResource

This is a method of the IDirect3dRM Interface.

Syntax

public Direct3dRMTexture loadTextureFromResource(int hnd);


setDefaultTextureColors (IDirect3dRM Interface)

 Microsoft SDK for Java

setDefaultTextureColors

This is a method of the IDirect3dRM Interface.

Syntax

public void setDefaultTextureColors(int ds);


setDefaultTextureShades (IDirect3dRM Interface)

 Microsoft SDK for Java

setDefaultTextureShades

This is a method of the IDirect3dRM Interface.

Syntax

public void setDefaultTextureShades(int ds);


setSearchPath (IDirect3dRM Interface)

 Microsoft SDK for Java

setSearchPath

This is a method of the IDirect3dRM Interface.

Syntax

public void setSearchPath(String name);


tick (IDirect3dRM Interface)

 Microsoft SDK for Java

tick

This is a method of the IDirect3dRM Interface.

Syntax

public void tick(float val);


vectorCrossProduct (IDirect3dRM Interface)

 Microsoft SDK for Java

vectorCrossProduct

This is a method of the IDirect3dRM Interface.

Syntax

public void vectorCrossProduct(D3dVector lpd, D3dVector lps1, D3dVector lps2);


vectorNormalise (IDirect3dRM Interface)

 Microsoft SDK for Java

vectorNormalise

This is a method of the IDirect3dRM Interface.

Syntax

public void vectorNormalise(D3dVector d);


IDirect3dRMAnimation Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMAnimation Interface

This is an interface of the com.ms.directx package.

public interface IDirect3dRMAnimation extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void addPositionKey(float time, float x, float y, float z)
        public void addScaleKey(float time, float x, float y,
        float z);
  public void addRotateKey(float time, D3dRMQuaternion q);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public void deleteKey(float time);
  public Direct3dRMAnimation duplicate();
  public int getAppData();
  public String getClassName();
  public String getName();
  public int getOptions();
  public void setAppData(int data);
  public void setFrame(Direct3dRMFrame frame);
  public void setName(String name);
  public void setOptions(int flags);
  public void setTime(float time);
}

For a description of methods and parameters, see Direct3dRMAnimation.

Hierarchy

IUnknown
  |
  +--IDirect3dRMAnimation


Methods (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

IDirect3dRMAnimation Interface Methods

The IDirect3dRMAnimation Interface contains the following methods:

addDestroyCallback
addPositionKey
addRotateKey
deleteDestroyCallback
deleteKey
duplicate
getAppData
getClassName
getName
getOptions
setAppData
setFrame
setName
setOptions
setTime


addDestroyCallback (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


addPositionKey (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

addPositionKey

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public void addPositionKey(float time, float x, float y, float z) public void addScaleKey(float time, float x, float y, float z);


addRotateKey (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

addRotateKey

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public void addRotateKey(float time, D3dRMQuaternion q);


deleteDestroyCallback (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


deleteKey (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

deleteKey

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public void deleteKey(float time);


duplicate (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public Direct3dRMAnimation duplicate();


getAppData (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public String getClassName();


getName (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public String getName();


getOptions (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

getOptions

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public int getOptions();


setAppData (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public void setAppData(int data);


setFrame (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

setFrame

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public void setFrame(Direct3dRMFrame frame);


setName (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public void setName(String name);


setOptions (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

setOptions

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public void setOptions(int flags);


setTime (IDirect3dRMAnimation Interface)

 Microsoft SDK for Java

setTime

This is a method of the IDirect3dRMAnimation Interface.

Syntax

public void setTime(float time);


IDirect3dRMAnimationSet Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMAnimationSet Interface

This is an interface of the com.ms.directx package.

public interface IDirect3dRMAnimationSet extends IUnknown
{
  // Methods
  public void addAnimation(Direct3dRMAnimation aid);
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void deleteAnimation(Direct3dRMAnimation aid);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMAnimationSet duplicate();
  public int getAppData();
  public String getClassName();
  public String getName();
  public void loadFromFileByPos(String filename, int position,
        int flags, ILoadTextureCallback c, IUnknown pUser,
        Direct3dRMFrame f);
  public void setAppData(int data);
  public void setName(String name);
  public void setTime(float time);
}

For a description of methods and parameters, see Direct3dRMAnimationSet.

Hierarchy

IUnknown
  |
  +--IDirect3dRMAnimationSet


Methods (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

IDirect3dRMAnimationSet Interface Methods

The IDirect3dRMAnimationSet Interface contains the following methods:

addAnimation
addDestroyCallback
deleteAnimation
deleteDestroyCallback
duplicate
getAppData
getClassName
getName
loadFromFileByPos
setAppData
setName
setTime


addAnimation (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

addAnimation

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public void addAnimation(Direct3dRMAnimation aid);


addDestroyCallback (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


deleteAnimation (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

deleteAnimation

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public void deleteAnimation(Direct3dRMAnimation aid);


deleteDestroyCallback (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public Direct3dRMAnimationSet duplicate();


getAppData (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public String getClassName();


getName (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public String getName();


loadFromFileByPos (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

loadFromFileByPos

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public void loadFromFileByPos(String filename, int position, int flags, ILoadTextureCallback c, IUnknown pUser, Direct3dRMFrame f);


setAppData (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public void setAppData(int data);


setName (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public void setName(String name);


setTime (IDirect3dRMAnimationSet Interface)

 Microsoft SDK for Java

setTime

This is a method of the IDirect3dRMAnimationSet Interface.

Syntax

public void setTime(float time);


IDirect3dRMArray Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMArray Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMArray extends IUnknown
{
  // Methods
  public int getSize();
}

For a description of methods and parameters, see Direct3dRMArray.

Hierarchy

IUnknown
  |
  +--IDirect3dRMArray


Methods (IDirect3dRMArray Interface)

 Microsoft SDK for Java

IDirect3dRMArray Interface Methods

The IDirect3dRMArray Interface contains the following method:

getSize.


getSize (IDirect3dRMArray Interface)

 Microsoft SDK for Java

getSize

This is a method of the IDirect3dRMArray Interface.

Syntax

public int getSize();


IDirect3dRMDevice Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMDevice Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMDevice extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void addUpdateCallback(IDeviceUpdateCallback fn,
        IUnknown args);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public void deleteUpdateCallback(IDeviceUpdateCallback fn,
        IUnknown args);
  public Direct3dRMDevice duplicate();
  public int getAppData();
  public int getBufferCount();
  public String getClassName();
  public int getColorModel();
  public Direct3dRMWinDevice getd3drmWinDevice();
  public Direct3dDevice getDirect3DDevice();
  public int getDither();
  public int getHeight();
  public String getName();
  public int getQuality();
  public int getShades();
  public int getTextureQuality();
  public int getTrianglesDrawn();
  public Direct3dRMViewportArray getViewports();
  public int getWidth();
  public int getWireframeOptions();
  public void init(int width, int height);
  public void initFromClipper(DirectDrawClipper DDclipper, _Guid g,
        int width, int height);
  public void initFromD3D(Direct3d d3d, Direct3dDevice dev);
  public void setAppData(int data);
  public void setBufferCount(int count);
  public void setDither(int dith);
  public void setName(String name);
  public void setQuality(int q);
  public void setShades(int s);
  public void setTextureQuality(int d);
  public void update();
}

For a description of methods and parameters, see Direct3dRMDevice.

Hierarchy

IUnknown
  |
  +--IDirect3dRMDevice


Methods (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

IDirect3dRMDevice Interface Methods

The IDirect3dRMDevice Interface of the com.ms.directx package contains the following methods:

addDestroyCallback
addUpdateCallback
deleteDestroyCallback
deleteUpdateCallback
duplicate
getAppData
getBufferCount
getClassName
getColorModel
getd3drmWinDevice
getDirect3DDevice
getDither
getHeight
getName
getQuality
getShades
getTextureQuality
getTrianglesDrawn
getViewports
getWidth
getWireframeOptions
init
initFromClipper
initFromD3D
setAppData
setBufferCount
setDither
setName
setQuality
setShades
setTextureQuality
update


addDestroyCallback (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


addUpdateCallback (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

addUpdateCallback

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void addUpdateCallback(IDeviceUpdateCallback fn, IUnknown args);


deleteDestroyCallback (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


deleteUpdateCallback (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

deleteUpdateCallback

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void deleteUpdateCallback(IDeviceUpdateCallback fn, IUnknown args);


duplicate (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMDevice Interface.

Syntax

public Direct3dRMDevice duplicate();


getAppData (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getAppData();


getBufferCount (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getBufferCount

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getBufferCount();


getClassName (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMDevice Interface.

Syntax

public String getClassName();


getColorModel (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getColorModel

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getColorModel();


getd3drmWinDevice (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getd3drmWinDevice

This is a method of the IDirect3dRMDevice Interface.

Syntax

public Direct3dRMWinDevice getd3drmWinDevice();


getDirect3DDevice (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getDirect3DDevice

This is a method of the IDirect3dRMDevice Interface.

Syntax

public Direct3dDevice getDirect3DDevice();


getDither (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getDither

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getDither();


getHeight (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getHeight

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getHeight();


getName (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMDevice Interface.

Syntax

public String getName();


getQuality (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getQuality

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getQuality();


getShades (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getShades

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getShades();


getTextureQuality (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getTextureQuality

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getTextureQuality();


getTrianglesDrawn (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getTrianglesDrawn

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getTrianglesDrawn();


getViewports (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getViewports

This is a method of the IDirect3dRMDevice Interface.

Syntax

public Direct3dRMViewportArray getViewports();


getWidth (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getWidth

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getWidth();


getWireframeOptions (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

getWireframeOptions

This is a method of the IDirect3dRMDevice Interface.

Syntax

public int getWireframeOptions();


init (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

init

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void init(int width, int height);


initFromClipper (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

initFromClipper

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void initFromClipper(DirectDrawClipper DDclipper, _Guid g, int width, int height);


initFromD3D (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

initFromD3D

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void initFromD3D(Direct3d d3d, Direct3dDevice dev);


setAppData (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void setAppData(int data);


setBufferCount (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

setBufferCount

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void setBufferCount(int count);


setDither (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

setDither

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void setDither(int dith);


setName (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void setName(String name);


setQuality (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

setQuality

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void setQuality(int q);


setShades (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

setShades

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void setShades(int s);


setTextureQuality (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

setTextureQuality

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void setTextureQuality(int d);


update (IDirect3dRMDevice Interface)

 Microsoft SDK for Java

update

This is a method of the IDirect3dRMDevice Interface.

Syntax

public void update();


IDirect3dRMDeviceArray Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMDeviceArray Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMDeviceArray extends IUnknown
{
  // Methods
  public Direct3dRMDevice getElement(int index);
  public int getSize();
}

For a description of methods and parameters, see Direct3dRMDeviceArray.

Hierarchy

IUnknown
  |
  +--IDirect3dRMDeviceArray


Methods (IDirectRMDeviceArray Interface)

 Microsoft SDK for Java

IDirect3dRMDeviceArray Interface Methods

The IDirect3dRMDeviceArray Interface contains the following methods:

getElement
getSize


getElement (IDirectRMDeviceArray Interface)

 Microsoft SDK for Java

getElement

This is a method of the IDirect3dRMDeviceArray Interface.

Syntax

public Direct3dRMDevice getElement(int index);


getSize (IDirectRMDeviceArray Interface)

 Microsoft SDK for Java

getSize

This is a method of the IDirect3dRMDeviceArray Interface.

Syntax

public int getSize();


IDirect3dRMFace Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMFace Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMFace extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void addVertex(float x, float y, float z);
  public void addVertexAndNormalIndexed(int vertex, int normal);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMFace duplicate();
  public int getAppData();
  public String getClassName();
  public int getColor();
  public Direct3dRMMaterial getMaterial();
  public String getName();
  public void getNormal(D3dVector val);
  public Direct3dRMTexture getTexture();
  public int getTextureCoordinateIndex(int which);
  public void getTextureCoordinates(int vertex, float[] u,
        float[] v);
  public void getTextureTopology(int[] u, int[] v);
  public void getVertex(int idx, D3dVector vert, D3dVector norm);
  public int getVertexCount();
  public int getVertexIndex(int which);
  public void getVertices(int[] vertex_cnt, D3dVector coord,
        D3dVector normals);
  public void getVerticesSize(int[] v_cnt);
  public void setAppData(int data);
  public void setColor(int c);
  public void setColorRGB(float r, float g, float b);
  public void setMaterial(Direct3dRMMaterial ref);
  public void setName(String name);
  public void setTexture(Direct3dRMTexture ref);
  public void setTextureCoordinates(int vertex, float u, float v);
  public void setTextureTopology(int wrap_u, int wrap_v);
}

For a description of methods and parameters, see Direct3dRMFace.

Hierarchy

IUnknown
  |
  +--IDirect3dRMFace


Methods (IDirect3dRMFace Interface)

 Microsoft SDK for Java

IDirect3dRMFace Interface Methods

The IDirect3dRMFace Interface contains the following methods:

addDestroyCallback
addVertex
addVertexAndNormalIndexed
deleteDestroyCallback
duplicate
getAppData
getClassName
getColor
getMaterial
getName
getNormal
getTexture
getTextureCoordinateIndex
getTextureCoordinates
getTextureTopology
getVertex
getVertexCount
getVertexIndex
getVertices
getVerticesSize
setAppData
setColor
setColorRGB
setMaterial
setName
setTexture
setTextureCoordinates
setTextureTopology


addDestroyCallback (IDirect3dRMFace Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMFace Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


addVertex (IDirect3dRMFace Interface)

 Microsoft SDK for Java

addVertex

This is a method of the IDirect3dRMFace Interface.

Syntax

public void addVertex(float x, float y, float z);


addVertexAndNormalIndexed (IDirect3dRMFace Interface)

 Microsoft SDK for Java

addVertexAndNormalIndexed

This is a method of the IDirect3dRMFace Interface.

Syntax

public void addVertexAndNormalIndexed(int vertex, int normal);


deleteDestroyCallback (IDirect3dRMFace Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMFace Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMFace Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMFace Interface.

Syntax

public Direct3dRMFace duplicate();


getAppData (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMFace Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMFace Interface.

Syntax

public String getClassName();


getColor (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getColor

This is a method of the IDirect3dRMFace Interface.

Syntax

public int getColor();


getMaterial (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getMaterial

This is a method of the IDirect3dRMFace Interface.

Syntax

public Direct3dRMMaterial getMaterial();


getName (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMFace Interface.

Syntax

public String getName();


getNormal (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getNormal

This is a method of the IDirect3dRMFace Interface.

Syntax

public void getNormal(D3dVector val);


getTexture (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getTexture

This is a method of the IDirect3dRMFace Interface.

Syntax

public Direct3dRMTexture getTexture();


getTextureCoordinateIndex (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getTextureCoordinateIndex

This is a method of the IDirect3dRMFace Interface.

Syntax

public int getTextureCoordinateIndex(int which);


getTextureCoordinates (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getTextureCoordinates

This is a method of the IDirect3dRMFace Interface.

Syntax

public void getTextureCoordinates(int vertex, float[] u, float[] v);


getTextureTopology (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getTextureTopology

This is a method of the IDirect3dRMFace Interface.

Syntax

public void getTextureTopology(int[] u, int[] v);


getVertex (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getVertex

This is a method of the IDirect3dRMFace Interface.

Syntax

public void getVertex(int idx, D3dVector vert, D3dVector norm);


getVertexCount (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getVertexCount

This is a method of the IDirect3dRMFace Interface.

Syntax

public int getVertexCount();


getVertexIndex (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getVertexIndex

This is a method of the IDirect3dRMFace Interface.

Syntax

public int getVertexIndex(int which);


getVertices (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getVertices

This is a method of the IDirect3dRMFace Interface.

Syntax

public void getVertices(int[] vertex_cnt, D3dVector coord, D3dVector normals);


getVerticesSize (IDirect3dRMFace Interface)

 Microsoft SDK for Java

getVerticesSize

This is a method of the IDirect3dRMFace Interface.

Syntax

public void getVerticesSize(int[] v_cnt);


setAppData (IDirect3dRMFace Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMFace Interface.

Syntax

public void setAppData(int data);


setColor (IDirect3dRMFace Interface)

 Microsoft SDK for Java

setColor

This is a method of the IDirect3dRMFace Interface.

Syntax

public void setColor(int c);


setColorRGB (IDirect3dRMFace Interface)

 Microsoft SDK for Java

setColorRGB

This is a method of the IDirect3dRMFace Interface.

Syntax

public void setColorRGB(float r, float g, float b);


setMaterial (IDirect3dRMFace Interface)

 Microsoft SDK for Java

setMaterial

This is a method of the IDirect3dRMFace Interface.

Syntax

public void setMaterial(Direct3dRMMaterial ref);


setName (IDirect3dRMFace Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMFace Interface.

Syntax

public void setName(String name);


setTexture (IDirect3dRMFace Interface)

 Microsoft SDK for Java

setTexture

This is a method of the IDirect3dRMFace Interface.

Syntax

public void setTexture(Direct3dRMTexture ref);


setTextureCoordinates (IDirect3dRMFace Interface)

 Microsoft SDK for Java

setTextureCoordinates

This is a method of the IDirect3dRMFace Interface.

Syntax

public void setTextureCoordinates(int vertex, float u, float v);


setTextureTopology (IDirect3dRMFace Interface)

 Microsoft SDK for Java

setTextureTopology

This is a method of the IDirect3dRMFace Interface.

Syntax

public void setTextureTopology(int wrap_u, int wrap_v);


IDirect3dRMFaceArray Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMFaceArray Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMFaceArray extends IUnknown
{
  // Methods
  public Direct3dRMFace getElement(int index);
  public int getSize();
}

For a description of methods and parameters, see Direct3dRMFaceArray.

Hierarchy

IUnknown
  |
  +--IDirect3dRMFaceArray


Methods (IDirect3dRMFaceArray Interface)

 Microsoft SDK for Java

IDirect3dRMFaceArray Interface Methods

The IDirect3dRMFaceArray Interface contains the following methods:

getElement
getSize


getElement (IDirect3dRMFaceArray Interface)

 Microsoft SDK for Java

getElement

This is a method of the IDirect3dRMFaceArray Interface.

Syntax

public Direct3dRMFace getElement(int index);


getSize (IDirect3dRMFaceArray Interface)

 Microsoft SDK for Java

getSize

This is a method of the IDirect3dRMFaceArray Interface.

Syntax

public int getSize();


IDirect3dRMFrame Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMFrame Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMFrame extends IUnknown
{
  // Methods
  public void addChild(Direct3dRMFrame child);
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void addLight(Direct3dRMLight val);
  public void addMoveCallback(IFrameMoveCallback fmC,
        IUnknown args);
  public void addRotation(int typ, float x, float y, float z, float
        theta);
  public void addScale(int typ, float sx, float sy, float sz);
  public void addTransform(int t, float[] val);
  public void addTranslation(int t, float x, float y, float z);
  public void addVisual(Direct3dRMVisual v);
  public void addVisualFrame(Direct3dRMFrame v);
  public void addVisualMesh(Direct3dRMMesh v);
  public void addVisualMeshBuilder(Direct3dRMMeshBuilder v);
  public void addVisualShadow(Direct3dRMShadow v);
  public void addVisualTexture(Direct3dRMTexture v);
  public void addVisualUserVisual(Direct3dRMUserVisual v);
  public void deleteChild(Direct3dRMFrame c);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public void deleteLight(Direct3dRMLight l);
  public void deleteMoveCallback(IFrameMoveCallback fn,
        IUnknown args);
  public void deleteVisual(Direct3dRMVisual v);
  public void deleteVisualFrame(Direct3dRMFrame v);
  public void deleteVisualMesh(Direct3dRMMesh v);
  public void deleteVisualMeshBuilder(Direct3dRMMeshBuilder v);
  public void deleteVisualShadow(Direct3dRMShadow v);
  public void deleteVisualTexture(Direct3dRMTexture v);
  public void deleteVisualUserVisual(Direct3dRMUserVisual v);
  public Direct3dRMFrame duplicate();
  public int getAppData();
  public Direct3dRMFrameArray getChildren();
  public String getClassName();
  public int getColor();
  public Direct3dRMLightArray getLights();
  public int getMaterialMode();
  public String getName();
  public void getOrientation(Direct3dRMFrame ref, D3dVector dir,
        D3dVector up);
  public Direct3dRMFrame getParent();
  public void getPosition(Direct3dRMFrame ref, D3dVector position);
  public void getRotation(Direct3dRMFrame ref, D3dVector axis,
        float[] theta);
  public Direct3dRMFrame getScene();
  public int getSceneBackground();
  public DirectDrawSurface getSceneBackgroundDepth();
  public int getSceneFogColor();
  public int getSceneFogEnable();
  public int getSceneFogMode();
  public void getSceneFogParams(float[] start, float[] end, float[]
        density);
  public int getSortMode();
  public Direct3dRMTexture getTexture();
  public void getTextureTopology(int[] u, int[] v);
  public void getTransform(float[] val);
  public void getVelocity(Direct3dRMFrame ref, D3dVector vel,
        int rotation);
  public Direct3dRMVisualArray getVisuals();
  public int getZbufferMode();
  public void inverseTransform(D3dVector d, D3dVector s);
  public void loadFromFileByPos(String filename, int position,
        int flags, ILoadTextureCallback c, IUnknown pUser);
  public void lookAt(Direct3dRMFrame tgt, Direct3dRMFrame ref,
        int val);
  public void move(float delta);
  public void setAppData(int data);
  public void setColor(int c);
  public void setColorRGB(float r, float g, float b);
  public void setMaterialMode(int val);
  public void setName(String name);
  public void setOrientation(Direct3dRMFrame reference, float dx,
        float dy, float dz, float ux, float uy, float uz);
  public void setPosition(Direct3dRMFrame reference, float x, float
        y, float z);
  public void setRotation(Direct3dRMFrame reference, float x, float
        y, float z, float theta);
  public void setSceneBackground(int c);
  public void setSceneBackgroundDepth(DirectDrawSurface s);
  public void setSceneBackgroundImage(Direct3dRMTexture i);
  public void setSceneBackgroundRGB(float r, float g, float b);
  public void setSceneFogColor(int c);
  public void setSceneFogEnable(int enable);
  public void setSceneFogMode(int c);
  public void setSceneFogParams(float s, float e, float d);
  public void setSortMode(int val);
  public void setTexture(Direct3dRMTexture t);
  public void setTextureTopology(int wrap_u, int wrap_v);
  public void setVelocity(Direct3dRMFrame reference, float x, float
        y, float z, int with_rotation);
  public void setZbufferMode(int val);
  public void transform(D3dVector d, D3dVector s);
}

For a description of methods and parameters, see Direct3dRMFrame

Hierarchy

IUnknown
  |
  +--IDirect3dRMFrame


Methods (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

IDirect3dRMFrame Interface Methods

The IDirect3dRMFrame Interface contains the following methods.

addChild
addDestroyCallback
addLight
addMoveCallback
addRotation
addScale
addTransform
addTranslation
addVisual
addVisualFrame
addVisualMesh
addVisualMeshBuilder
addVisualShadow
addVisualTexture
addVisualUserVisual
deleteChild
deleteDestroyCallback
deleteLight
deleteMoveCallback
deleteVisual
deleteVisualFrame
deleteVisualMesh
deleteVisualMeshBuilder
deleteVisualShadow
deleteVisualTexture
deleteVisualUserVisual
duplicate
getAppData
getChildren
getClassName
getColor
getLights
getMaterialMode
getName
getOrientation
getParent
getPosition
getRotation
getScene
getSceneBackground
getSceneBackgroundDepth
getSceneFogColor
getSceneFogEnable
getSceneFogMode
getSceneFogParams
getSortMode
getTexture
getTextureTopology
getTransform
getVelocity
getVisuals
getZbufferMode
inverseTransform
loadFromFileByPos
lookAt
move
setAppData
setColor
setColorRGB
setMaterialMode
setName
setOrientation
setPosition
setRotation
setSceneBackground
setSceneBackgroundDepth
setSceneBackgroundImage
setSceneBackgroundRGB
setSceneFogColor
setSceneFogEnable
setSceneFogMode
setSceneFogParams
setSortMode
setTexture
setTextureTopology
setVelocity
setZbufferMode
transform


addChild (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addChild

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addChild(Direct3dRMFrame child);


addDestroyCallback (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


addLight (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addLight

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addLight(Direct3dRMLight val);


addMoveCallback (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addMoveCallback

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addMoveCallback(IFrameMoveCallback fmC, IUnknown args);


addRotation (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addRotation

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addRotation(int typ, float x, float y, float z, float theta);


addScale (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addScale

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addScale(int typ, float sx, float sy, float sz);


addTransform (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addTransform

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addTransform(int t, float[] val);


addTranslation (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addTranslation

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addTranslation(int t, float x, float y, float z);


addVisual (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addVisual

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addVisual(Direct3dRMVisual v);


addVisualFrame (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addVisualFrame

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addVisualFrame(Direct3dRMFrame v);


addVisualMesh (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addVisualMesh

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addVisualMesh(Direct3dRMMesh v);


addVisualMeshBuilder (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addVisualMeshBuilder

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addVisualMeshBuilder(Direct3dRMMeshBuilder v);


addVisualShadow (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addVisualShadow

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addVisualShadow(Direct3dRMShadow v);


addVisualTexture (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addVisualTexture

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addVisualTexture(Direct3dRMTexture v);


addVisualUserVisual (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

addVisualUserVisual

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void addVisualUserVisual(Direct3dRMUserVisual v);


deleteChild (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteChild

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteChild(Direct3dRMFrame c);


deleteDestroyCallback (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


deleteLight (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteLight

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteLight(Direct3dRMLight l);


deleteMoveCallback (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteMoveCallback

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteMoveCallback(IFrameMoveCallback fn, IUnknown args);


deleteVisual (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteVisual

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteVisual(Direct3dRMVisual v);


deleteVisualFrame (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteVisualFrame

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteVisualFrame(Direct3dRMFrame v);


deleteVisualMesh (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteVisualMesh

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteVisualMesh(Direct3dRMMesh v);


deleteVisualMeshBuilder (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteVisualMeshBuilder

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteVisualMeshBuilder(Direct3dRMMeshBuilder v);


deleteVisualShadow (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteVisualShadow

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteVisualShadow(Direct3dRMShadow v);


deleteVisualTexture (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteVisualTexture

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteVisualTexture(Direct3dRMTexture v);


deleteVisualUserVisual (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

deleteVisualUserVisual

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void deleteVisualUserVisual(Direct3dRMUserVisual v);


duplicate (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMFrame Interface.

Syntax

public Direct3dRMFrame duplicate();


getAppData (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMFrame Interface.

Syntax

public int getAppData();


getChildren (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getChildren

This is a method of the IDirect3dRMFrame Interface.

Syntax

public Direct3dRMFrameArray getChildren();


getClassName (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMFrame Interface.

Syntax

public String getClassName();


getColor (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getColor

This is a method of the IDirect3dRMFrame Interface.

Syntax

public int getColor();


getLights (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getLights

This is a method of the IDirect3dRMFrame Interface.

Syntax

public Direct3dRMLightArray getLights();


getMaterialMode (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getMaterialMode

This is a method of the IDirect3dRMFrame Interface.

Syntax

public int getMaterialMode();


getName (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMFrame Interface.

Syntax

public String getName();


getOrientation (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getOrientation

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void getOrientation(Direct3dRMFrame ref, D3dVector dir, D3dVector up);


getParent (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getParent

This is a method of the IDirect3dRMFrame Interface.

Syntax

public Direct3dRMFrame getParent();


getPosition (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getPosition

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void getPosition(Direct3dRMFrame ref, D3dVector position);


getRotation (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getRotation

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void getRotation(Direct3dRMFrame ref, D3dVector axis, float[] theta);


getScene (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getScene

This is a method of the IDirect3dRMFrame Interface.

Syntax

public Direct3dRMFrame getScene();


getSceneBackground (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getSceneBackground

This is a method of the IDirect3dRMFrame Interface.

Syntax

public int getSceneBackground();


getSceneBackgroundDepth (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getSceneBackgroundDepth

This is a method of the IDirect3dRMFrame Interface.

Syntax

public DirectDrawSurface getSceneBackgroundDepth();


getSceneFogColor (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getSceneFogColor

This is a method of the IDirect3dRMFrame Interface.

Syntax

public int getSceneFogColor();


getSceneFogEnable (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getSceneFogEnable

This is a method of the IDirect3dRMFrame Interface.

Syntax

public int getSceneFogEnable();


getSceneFogMode (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getSceneFogMode

This is a method of the IDirect3dRMFrame Interface.

Syntax

public int getSceneFogMode();


getSceneFogParams (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getSceneFogParams

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void getSceneFogParams(float[] start, float[] end, float[] density);


getSortMode (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getSortMode

This is a method of the IDirect3dRMFrame Interface.

Syntax

public int getSortMode();


getTexture (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getTexture

This is a method of the IDirect3dRMFrame Interface.

Syntax

public Direct3dRMTexture getTexture();


getTextureTopology (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getTextureTopology

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void getTextureTopology(int[] u, int[] v);


getTransform (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getTransform

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void getTransform(float[] val);


getVelocity (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getVelocity

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void getVelocity(Direct3dRMFrame ref, D3dVector vel, int rotation);


getVisuals (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getVisuals

This is a method of the IDirect3dRMFrame Interface.

Syntax

public Direct3dRMVisualArray getVisuals();


getZbufferMode (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

getZbufferMode

This is a method of the IDirect3dRMFrame Interface.

Syntax

public int getZbufferMode();


inverseTransform (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

inverseTransform

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void inverseTransform(D3dVector d, D3dVector s);


loadFromFileByPos (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

loadFromFileByPos

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void loadFromFileByPos(String filename, int position, int flags, ILoadTextureCallback c, IUnknown pUser);


lookAt (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

lookAt

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void lookAt(Direct3dRMFrame tgt, Direct3dRMFrame ref, int val);


move (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

move

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void move(float delta);


setAppData (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setAppData(int data);


setColor (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setColor

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setColor(int c);


setColorRGB (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setColorRGB

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setColorRGB(float r, float g, float b);


setMaterialMode (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setMaterialMode

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setMaterialMode(int val);


setName (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setName(String name);


setOrientation (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setOrientation

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setOrientation(Direct3dRMFrame reference, float dx, float dy, float dz, float ux, float uy, float uz);


setPosition (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setPosition

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setPosition(Direct3dRMFrame reference, float x, float y, float z);


setRotation (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setRotation

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setRotation(Direct3dRMFrame reference, float x, float y, float z, float theta);


setSceneBackground (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setSceneBackground

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setSceneBackground(int c);


setSceneBackgroundDepth (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setSceneBackgroundDepth

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setSceneBackgroundDepth(DirectDrawSurface s);


setSceneBackgroundImage (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setSceneBackgroundImage

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setSceneBackgroundImage(Direct3dRMTexture i);


setSceneBackgroundRGB (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setSceneBackgroundRGB

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setSceneBackgroundRGB(float r, float g, float b);


setSceneFogColor (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setSceneFogColor

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setSceneFogColor(int c);


setSceneFogEnable (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setSceneFogEnable

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setSceneFogEnable(int enable);


setSceneFogMode (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setSceneFogMode

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setSceneFogMode(int c);


setSceneFogParams (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setSceneFogParams

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setSceneFogParams(float s, float e, float d);


setSortMode (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setSortMode

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setSortMode(int val);


setTexture (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setTexture

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setTexture(Direct3dRMTexture t);


setTextureTopology (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setTextureTopology

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setTextureTopology(int wrap_u, int wrap_v);


setVelocity (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setVelocity

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setVelocity(Direct3dRMFrame reference, float x, float y, float z, int with_rotation);


setZbufferMode (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

setZbufferMode

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void setZbufferMode(int val);


transform (IDirect3dRMFrame Interface)

 Microsoft SDK for Java

transform

This is a method of the IDirect3dRMFrame Interface.

Syntax

public void transform(D3dVector d, D3dVector s);


IDirect3dRMFrameArray Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMFrameArray Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMFrameArray extends IUnknown
{
  // Methods
  public Direct3dRMFrame getElement(int index);
  public int getSize();
}

For a description of methods and parameters, see Direct3dRMFrameArray.

Hierarchy

IUnknown
  |
  +--IDirect3dRMFrameArray


Methods (IDirect3dRMFrameArray Interface)

 Microsoft SDK for Java

IDirect3dRMFrameArray Interface Methods

The IDirect3dRMFrameArray Interface contains the following methods:

getElement
getSize


getElement (IDirect3dRMFrameArray Interface)

 Microsoft SDK for Java

getElement

This is a method of the IDirect3dRMFrameArray Interface.

Syntax

public Direct3dRMFrame getElement(int index);


getSize (IDirect3dRMFrameArray Interface)

 Microsoft SDK for Java

getSize

This is a method of the IDirect3dRMFrameArray Interface.

Syntax

public int getSize();


IDirect3dRMLight Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMLight Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMLight extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMLight duplicate();
  public int getAppData();
  public String getClassName();
  public int getColor();
  public float getConstantAttenuation();
  public Direct3dRMFrame getEnableFrame();
  public float getLinearAttenuation();
  public String getName();
  public float getPenumbra();
  public float getQuadraticAttenuation();
  public float getRange();
  public int getType();
  public float getUmbra();
  public void setAppData(int data);
  public void setColor(int c);
  public void setColorRGB(float r, float g, float b);
  public void setConstantAttenuation(float atn);
  public void setEnableFrame(Direct3dRMFrame f);
  public void setLinearAttenuation(float atn);
  public void setName(String name);
  public void setPenumbra(float p);
  public void setQuadraticAttenuation(float atn);
  public void setRange(float rng);
  public void setType(int t);
  public void setUmbra(float u);
}

For a description of methods and parameters, see Direct3dRMLight.

Hierarchy

IUnknown
  |
  +--IDirect3dRMLight


Methods (IDirect3dRMLight Interface)

 Microsoft SDK for Java

IDirect3dRMLight Interface Methods

The IDirect3dRMLight Interface contains the following methods:

addDestroyCallback
deleteDestroyCallback
duplicate
getAppData
getClassName
getColor
getConstantAttenuation
getEnableFrame
getLinearAttenuation
getName
getPenumbra
getQuadraticAttenuation
getRange
getType
getUmbra
setAppData
setColor
setColorRGB
setConstantAttenuation
setEnableFrame
setLinearAttenuation
setName
setPenumbra
setQuadraticAttenuation
setRange
setType
setUmbra


addDestroyCallback (IDirect3dRMLight Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMLight Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


deleteDestroyCallback (IDirect3dRMLight Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMLight Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMLight Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMLight Interface.

Syntax

public Direct3dRMLight duplicate();


getAppData (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMLight Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMLight Interface.

Syntax

public String getClassName();


getColor (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getColor

This is a method of the IDirect3dRMLight Interface.

Syntax

public int getColor();


getConstantAttenuation (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getConstantAttenuation

This is a method of the IDirect3dRMLight Interface.

Syntax

public float getConstantAttenuation();


getEnableFrame (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getEnableFrame

This is a method of the IDirect3dRMLight Interface.

Syntax

public Direct3dRMFrame getEnableFrame();


getLinearAttenuation (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getLinearAttenuation

This is a method of the IDirect3dRMLight Interface.

Syntax

public float getLinearAttenuation();


getName (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMLight Interface.

Syntax

public String getName();


getPenumbra (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getPenumbra

This is a method of the IDirect3dRMLight Interface.

Syntax

public float getPenumbra();


getQuadraticAttenuation (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getQuadraticAttenuation

This is a method of the IDirect3dRMLight Interface.

Syntax

public float getQuadraticAttenuation();


getRange (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getRange

This is a method of the IDirect3dRMLight Interface.

Syntax

public float getRange();


getType (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getType

This is a method of the IDirect3dRMLight Interface.

Syntax

public int getType();


getUmbra (IDirect3dRMLight Interface)

 Microsoft SDK for Java

getUmbra

This is a method of the IDirect3dRMLight Interface.

Syntax

public float getUmbra();


setAppData (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setAppData(int data);


setColor (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setColor

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setColor(int c);


setColorRGB (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setColorRGB

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setColorRGB(float r, float g, float b);


setConstantAttenuation (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setConstantAttenuation

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setConstantAttenuation(float atn);


setEnableFrame (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setEnableFrame

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setEnableFrame(Direct3dRMFrame f);


setLinearAttenuation (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setLinearAttenuation

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setLinearAttenuation(float atn);


setName (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setName(String name);


setPenumbra (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setPenumbra

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setPenumbra(float p);


setQuadraticAttenuation (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setQuadraticAttenuation

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setQuadraticAttenuation(float atn);


setRange (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setRange

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setRange(float rng);


setType (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setType

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setType(int t);


setUmbra (IDirect3dRMLight Interface)

 Microsoft SDK for Java

setUmbra

This is a method of the IDirect3dRMLight Interface.

Syntax

public void setUmbra(float u);


IDirect3dRMLightArray Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMLightArray Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMLightArray extends IUnknown
{
  // Methods
  public Direct3dRMLight getElement(int index);
  public int getSize();
}

For a description of methods and parameters, see Direct3dRMLightArray.

Hierarchy

IUnknown
  |
  +--IDirect3dRMLightArray


Methods (IDirect3dRMLightArray Interface)

 Microsoft SDK for Java

IDirect3dRMLightArray Interface Methods

The IDirect3dRMLightArray Interface contains the following methods:

getElement
getSize


getElement (IDirect3dRMLightArray Interface)

 Microsoft SDK for Java

getElement

This is a method of the IDirect3dRMLightArray Interface.

Syntax

public Direct3dRMLight getElement(int index);


getSize (IDirect3dRMLightArray Interface)

 Microsoft SDK for Java

getSize

This is a method of the IDirect3dRMLightArray Interface.

Syntax

public int getSize();


IDirect3dRMMaterial Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMMaterial Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMMaterial extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMMaterial duplicate();
  public int getAppData();
  public String getClassName();
  public void getEmissive(float[] r, float[] g, float[] b);
  public String getName();
  public float getPower();
  public void getSpecular(float[] r, float[] g, float[] b);
  public void setAppData(int data);
  public void setEmissive(float r, float g, float b);
  public void setName(String name);
  public void setPower(float power);
  public void setSpecular(float r, float g, float b);
}

For a description of methods and parameters, see Direct3dRMMaterial.

Hierarchy

IUnknown
  |
  +--IDirect3dRMMaterial


Methods (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

IDirect3dRMMaterial Interface Methods

The IDirect3dRMMaterial Interface contains the following methods:

addDestroyCallback
deleteDestroyCallback
duplicate
getAppData
getClassName
getEmissive
getName
getPower
getSpecular
setAppData
setEmissive
setName
setPower
setSpecular


addDestroyCallback (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


deleteDestroyCallback (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public Direct3dRMMaterial duplicate();


getAppData (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public String getClassName();


getEmissive (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

getEmissive

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public void getEmissive(float[] r, float[] g, float[] b);


getName (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public String getName();


getPower (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

getPower

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public float getPower();


getSpecular (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

getSpecular

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public void getSpecular(float[] r, float[] g, float[] b);


setAppData (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public void setAppData(int data);


setEmissive (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

setEmissive

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public void setEmissive(float r, float g, float b);


setName (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public void setName(String name);


setPower (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

setPower

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public void setPower(float power);


setSpecular (IDirect3dRMMaterial Interface)

 Microsoft SDK for Java

setSpecular

This is a method of the IDirect3dRMMaterial Interface.

Syntax

public void setSpecular(float r, float g, float b);


IDirect3dRMMesh Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMMesh Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMMesh extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void addGroup(int vcnt, int fcnt, int vPerFace,
        int[] fdata, int[] retId);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMMesh duplicate();
  public int getAppData();
  public void getBox(D3dRMBox vector);
  public String getClassName();
  public void getGroup(int id, int[] vcnt, int[] fcnt,
        int[] vPerFace, int[] fDataSize, int[] fdata);
  public int getGroupColor(int id);
  public int getGroupCount();
  public int getGroupMapping(int id);
  public Direct3dRMMaterial getGroupMaterial(int id);
  public int getGroupQuality(int id);
  public void getGroupSize(int id, int[] val);
  public Direct3dRMTexture getGroupTexture(int id);
  public String getName();
  public void getVertices(int id, int idx, int vCount,
        D3dRMVertex[] v);
  public void getVerticesSize(int id, int idx, int[] cnt);
  public void scale(float sx, float sy, float sz);
  public void setAppData(int data);
  public void setGroupColor(int id, int val);
  public void setGroupColorRGB(int id, float r, float g, float b);
  public void setGroupMapping(int id, int value);
  public void setGroupMaterial(int id, Direct3dRMMaterial val);
  public void setGroupQuality(int id, int value);
  public void setGroupTexture(int id, Direct3dRMTexture val);
  public void setName(String name);
  public void setVertices(int id, int idx, int vCount,
        D3dRMVertex[] v);
  public void setVerticesAsFloats(int id, int idx, int vCount,
        float[] v);
  public void translate(float tx, float ty, float tz);
}

For a description of methods and parameters, see Direct3dRMMesh.

Hierarchy

IUnknown
  |
  +--IDirect3dRMMesh


Methods (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

IDirect3dRMMesh Interface Methods

The IDirect3dRMMesh Interface contains the following methods:

addDestroyCallback
addGroup
deleteDestroyCallback
duplicate
getAppData
getBox
getClassName
getGroup
getGroupColor
getGroupCount
getGroupMapping
getGroupMaterial
getGroupQuality
getGroupSize
getGroupTexture
getName
getVertices
getVerticesSize
scale
setAppData
setGroupColor
setGroupColorRGB
setGroupMapping
setGroupMaterial
setGroupQuality
setGroupTexture
setName
setVertices
setVerticesAsFloats
translate


addDestroyCallback (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


addGroup (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

addGroup

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void addGroup(int vcnt, int fcnt, int vPerFace, int[] fdata, int[] retId);


deleteDestroyCallback (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMMesh Interface.

Syntax

public Direct3dRMMesh duplicate();


getAppData (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMMesh Interface.

Syntax

public int getAppData();


getBox (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getBox

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void getBox(D3dRMBox vector);


getClassName (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMMesh Interface.

Syntax

public String getClassName();


getGroup (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getGroup

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void getGroup(int id, int[] vcnt, int[] fcnt, int[] vPerFace, int[] fDataSize, int[] fdata);


getGroupColor (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getGroupColor

This is a method of the IDirect3dRMMesh Interface.

Syntax

public int getGroupColor(int id);


getGroupCount (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getGroupCount

This is a method of the IDirect3dRMMesh Interface.

Syntax

public int getGroupCount();


getGroupMapping (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getGroupMapping

This is a method of the IDirect3dRMMesh Interface.

Syntax

public int getGroupMapping(int id);


getGroupMaterial (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getGroupMaterial

This is a method of the IDirect3dRMMesh Interface.

Syntax

public Direct3dRMMaterial getGroupMaterial(int id);


getGroupQuality (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getGroupQuality

This is a method of the IDirect3dRMMesh Interface.

Syntax

public int getGroupQuality(int id);


getGroupSize (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getGroupSize

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void getGroupSize(int id, int[] val);


getGroupTexture (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getGroupTexture

This is a method of the IDirect3dRMMesh Interface.

Syntax

public Direct3dRMTexture getGroupTexture(int id);


getName (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMMesh Interface.

Syntax

public String getName();


getVertices (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getVertices

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void getVertices(int id, int idx, int vCount, D3dRMVertex[] v);


getVerticesSize (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

getVerticesSize

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void getVerticesSize(int id, int idx, int[] cnt);


scale (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

scale

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void scale(float sx, float sy, float sz);


setAppData (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void setAppData(int data);


setGroupColor (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

setGroupColor

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void setGroupColor(int id, int val);


setGroupColorRGB (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

setGroupColorRGB

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void setGroupColorRGB(int id, float r, float g, float b);


setGroupMapping (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

setGroupMapping

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void setGroupMapping(int id, int value);


setGroupMaterial (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

setGroupMaterial

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void setGroupMaterial(int id, Direct3dRMMaterial val);


setGroupQuality (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

setGroupQuality

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void setGroupQuality(int id, int value);


setGroupTexture (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

setGroupTexture

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void setGroupTexture(int id, Direct3dRMTexture val);


setName (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void setName(String name);


setVertices (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

setVertices

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void setVertices(int id, int idx, int vCount, D3dRMVertex[] v);


setVerticesAsFloats (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

setVerticesAsFloats

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void setVerticesAsFloats(int id, int idx, int vCount, float[] v);


translate (IDirect3dRMMesh Interface)

 Microsoft SDK for Java

translate

This is a method of the IDirect3dRMMesh Interface.

Syntax

public void translate(float tx, float ty, float tz);


IDirect3dRMMeshBuilder Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMMeshBuilder Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMMeshBuilder extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void addFace(Direct3dRMFace f);
  public void addFaces(int vCount, float[] ver, int nCount, float[]
        norm, int[] data);
  public void addFrame(Direct3dRMFrame f);
  public void addMesh(Direct3dRMMesh m);
  public void addMeshBuilder(Direct3dRMMeshBuilder mb);
  public void addNormal(float x, float y, float z);
  public void addVertex(float x, float y, float z);
  public Direct3dRMFace createFace();
  public Direct3dRMFaceArray createFaceArray(int vCount,
        float[] vertices, int nCount, float[] normals,
        int[] data);
  public Direct3dRMMesh createMesh();
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMMeshBuilder duplicate();
  public void generateNormals();
  public int getAppData();
  public void getBox(D3dRMBox retv);
  public String getClassName();
  public int getColorSource();
  public Direct3dRMMeshBuilder getd3drmMeshBuilder();
  public int getFaceCount();
  public Direct3dRMFaceArray getFaces();
  public String getName();
  public int getPerspective();
  public int getQuality();
  public void getTextureCoordinates(int idx, float[] u, float[] v);
  public int getVertexColor(int index);
  public int getVertexCount();
  public void getVertices(int[] vc, D3dVector v, int[] nc,
        D3dVector n, int[] fs, int[] fc);
  public int getVerticesSize();
  public void loadFromFileByPos(String filename, int position,
        int flags, ILoadTextureCallback c, IUnknown pUser);
  public void reserveSpace(int v_cnt, int n_cnt, int f_cnt);
  public void save(String fname, int xFormat, int save);
  public void scale(float sx, float sy, float sz);
  public void setAppData(int data);
  public void setColor(int col);
  public void setColorRGB(float red, float green, float blue);
  public void setColorSource(int val);
  public void setMaterial(Direct3dRMMaterial val);
  public void setName(String name);
  public void setNormal(int idx, float x, float y, float z);
  public void setPerspective(int persp);
  public void setQuality(int q);
  public void setTexture(Direct3dRMTexture val);
  public void setTextureCoordinates(int idx, float u, float v);
  public void setTextureTopology(int wrap_u, int wrap_v);
  public void setVertex(int idx, float x, float y, float z);
  public void setVertexColor(int idx, int c);
  public void setVertexColorRGB(int idx, float r, float g, float b);
  public void translate(float tx, float ty, float tz);
}

For a description of methods and parameters, see Direct3dRMMeshBuilder.

Hierarchy

IUnknown
  |
  +--IDirect3dRMMeshBuilder


Methods (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

IDirect3dRMMeshBuilder Interface Methods

The IDirect3dRMMeshBuilder Interface contains the following methods:

addDestroyCallback
addFace
addFaces
addFrame
addMesh
addMeshBuilder
addNormal
addVertex
createFace
createFaceArray
createMesh
deleteDestroyCallback
duplicate
generateNormals
getAppData
getBox
getClassName
getColorSource
getd3drmMeshBuilder
getFaceCount
getFaces
getName
getPerspective
getQuality
getTextureCoordinates
getVertexColor
getVertexCount
getVertices
getVerticesSize
loadFromFileByPos
reserveSpace
save
scale
setAppData
setColor
setColorRGB
setColorSource
setMaterial
setName
setNormal
setPerspective
setQuality
setTexture
setTextureCoordinates
setTextureTopology
setVertex
setVertexColor
setVertexColorRGB
translate


addDestroyCallback (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


addFace (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

addFace

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void addFace(Direct3dRMFace f);


addFaces (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

addFaces

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void addFaces(int vCount, float[] ver, int nCount, float[] norm,int[] data);


addFrame (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

addFrame

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void addFrame(Direct3dRMFrame f);


addMesh (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

addMesh

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void addMesh(Direct3dRMMesh m);


addMeshBuilder (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

addMeshBuilder

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void addMeshBuilder(Direct3dRMMeshBuilder mb);


addNormal (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

addNormal

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void addNormal(float x, float y, float z);


addVertex (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

addVertex

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void addVertex(float x, float y, float z);


createFace (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

createFace

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public Direct3dRMFace createFace();


createFaceArray (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

createFaceArray

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public Direct3dRMFaceArray createFaceArray(int vCount, float[] vertices, int nCount, float[] normals, int[] data);


createMesh (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

createMesh

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public Direct3dRMMesh createMesh();


deleteDestroyCallback (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public Direct3dRMMeshBuilder duplicate();


generateNormals (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

generateNormals

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void generateNormals();


getAppData (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public int getAppData();


getBox (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getBox

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void getBox(D3dRMBox retv);


getClassName (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public String getClassName();


getColorSource (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getColorSource

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public int getColorSource();


getd3drmMeshBuilder (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getd3drmMeshBuilder

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public Direct3dRMMeshBuilder getd3drmMeshBuilder();


getFaceCount (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getFaceCount

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public int getFaceCount();


getFaces (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getFaces

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public Direct3dRMFaceArray getFaces();


getName (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public String getName();


getPerspective (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getPerspective

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public int getPerspective();


getQuality (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getQuality

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public int getQuality();


getTextureCoordinates (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getTextureCoordinates

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void getTextureCoordinates(int idx, float[] u, float[] v);


getVertexColor (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getVertexColor

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public int getVertexColor(int index);


getVertexCount (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getVertexCount

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public int getVertexCount();


getVertices (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getVertices

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void getVertices(int[] vc, D3dVector v, int[] nc, D3dVector n, int[] fs, int[] fc);


getVerticesSize (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

getVerticesSize

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public int getVerticesSize();


loadFromFileByPos (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

loadFromFileByPos

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void loadFromFileByPos(String filename, int position, int flags, ILoadTextureCallback c, IUnknown pUser);


reserveSpace (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

reserveSpace

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void reserveSpace(int v_cnt, int n_cnt, int f_cnt);


save (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

save

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void save(String fname, int xFormat, int save);


scale (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

scale

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void scale(float sx, float sy, float sz);


setAppData (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setAppData(int data);


setColor (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setColor

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setColor(int col);


setColorRGB (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setColorRGB

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setColorRGB(float red, float green, float blue);


setColorSource (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setColorSource

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setColorSource(int val);


setMaterial (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setMaterial

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setMaterial(Direct3dRMMaterial val);


setName (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setName(String name);


setNormal (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setNormal

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setNormal(int idx, float x, float y, float z);


setPerspective (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setPerspective

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setPerspective(int persp);


setQuality (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setQuality

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setQuality(int q);


setTexture (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setTexture

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setTexture(Direct3dRMTexture val);


setTextureCoordinates (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setTextureCoordinates

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setTextureCoordinates(int idx, float u, float v);


setTextureTopology (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setTextureTopology

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setTextureTopology(int wrap_u, int wrap_v);


setVertex (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setVertex

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setVertex(int idx, float x, float y, float z);


setVertexColor (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setVertexColor

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setVertexColor(int idx, int c);


setVertexColorRGB (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

setVertexColorRGB

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void setVertexColorRGB(int idx, float r, float g, float b);


translate (IDirect3dRMMeshBuilder Interface)

 Microsoft SDK for Java

translate

This is a method of the IDirect3dRMMeshBuilder Interface.

Syntax

public void translate(float tx, float ty, float tz);


IDirect3dRMObject Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMObject Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMObject extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMObject duplicate();
  public int getAppData();
  public String getClassName();
  public String getName();
  public void setAppData(int data);
  public void setName(String name);
}

For a description of methods and parameters, see Direct3dRMObject.

Hierarchy

IUnknown
  |
  +--IDirect3dRMObject


Methods (IDirect3dRMObject Interface)

 Microsoft SDK for Java

IDirect3dRMObject Interface Methods

The IDirect3dRMObject Interface contains the following methods:

addDestroyCallback deleteDestroyCallback
duplicate
getAppData
getClassName
getName
setAppData
setName


addDestroyCallback (IDirect3dRMObject Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMObject Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


deleteDestroyCallback (IDirect3dRMObject Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMObject Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMObject Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMObject Interface.

Syntax

public Direct3dRMObject duplicate();


getAppData (IDirect3dRMObject Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMObject Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMObject Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMObject Interface.

Syntax

public String getClassName();


getName (IDirect3dRMObject Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMObject Interface.

Syntax

public String getName();


setAppData (IDirect3dRMObject Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMObject Interface.

Syntax

public void setAppData(int data);


setName (IDirect3dRMObject Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMObject Interface.

Syntax

public void setName(String name);


IDirect3dRMPickArray Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMPickArray Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMPickArray extends IUnknown
{
  // Methods
  public Direct3dRMFrameArray getPickFrame(int index, D3dRMPickDesc
        desc);
  public Direct3dRMVisual getPickVisual(int index,
        D3dRMPickDesc desc);
  public int getSize();
}

For a description of methods and parameters, see Direct3dRMPickArray.

Hierarchy

IUnknown
  |
  +--IDirect3dRMPickArray


Methods (IDirect3dRMPickArray Interface)

 Microsoft SDK for Java

IDirect3dRMPickArray Interface Methods

The IDirect3dRMPickArray Interface contains the following methods:

getPickFrame
getPickVisual
getSize


getPickFrame (IDirect3dRMPickArray Interface)

 Microsoft SDK for Java

getPickFrame

This is a method of the IDirect3dRMPickArray Interface.

Syntax

public Direct3dRMFrameArray getPickFrame(int index, D3dRMPickDesc desc);


getPickVisual (IDirect3dRMPickArray Interface)

 Microsoft SDK for Java

getPickVisual

This is a method of the IDirect3dRMPickArray Interface.

Syntax

public Direct3dRMVisual getPickVisual(int index, D3dRMPickDesc desc);


getSize (IDirect3dRMPickArray Interface)

 Microsoft SDK for Java

getSize

This is a method of the IDirect3dRMPickArray Interface.

Syntax

public int getSize();


IDirect3dRMTexture Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMTexture Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMTexture extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void changed (int pixels, int palette);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMTexture duplicate();
  public int getAppData();
  public String getClassName();
  public int getColors();
  public void getDecalOrigin(int[] x, int[] y);
  public int getDecalScale();
  public void getDecalSize(float[] w, float[] h);
  public int getDecalTransparency();
  public int getDecalTransparentColor();
  public D3dRMImage getImage();
  public void getImageBuffer(byte[] buffer1);
  public void getImagePalette(byte[] pal);
  public String getName();
  public int getShades();
  public void initFromFile(String filename);
  public void initFromResource(int rs);
  public void initFromSurface(DirectDrawSurface ddS);
  public void setAppData(int data);
  public void setColors(int c);
  public void setDecalOrigin(int x, int y);
  public void setDecalScale(int s);
  public void setDecalSize(float width, float height);
  public void setDecalTransparency(int trans);
  public void setDecalTransparentColor(int tcolor);
  public void setName(String name);
  public void setShades(int s);
}

For a description of methods and parameters, see Direct3dRMTexture.

Hierarchy

IUnknown
  |
  +--IDirect3dRMTexture


Methods (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

IDirect3dRMTexture Interface Methods

The IDirect3dRMTexture Interface contains the following methods:

addDestroyCallback
changed
deleteDestroyCallback
duplicate
getAppData
getClassName
getColors
getDecalOrigin
getDecalScale
getDecalSize
getDecalTransparency
getDecalTransparentColor
getImage
getImageBuffer
getImagePalette
getName
getShades
initFromFile
initFromResource
initFromSurface
setAppData
setColors
setDecalOrigin
setDecalScale
setDecalSize
setDecalTransparency
setDecalTransparentColor
setName
setShades


addDestroyCallback (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


changed (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

changed

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void changed(int pixels, int palette);


deleteDestroyCallback (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMTexture Interface.

Syntax

public Direct3dRMTexture duplicate();


getAppData (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMTexture Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMTexture Interface.

Syntax

public String getClassName();


getColors (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getColors

This is a method of the IDirect3dRMTexture Interface.

Syntax

public int getColors();


getDecalOrigin (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getDecalOrigin

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void getDecalOrigin(int[] x, int[] y);


getDecalScale (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getDecalScale

This is a method of the IDirect3dRMTexture Interface.

Syntax

public int getDecalScale();


getDecalSize (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getDecalSize

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void getDecalSize(float[] w, float[] h);


getDecalTransparency (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getDecalTransparency

This is a method of the IDirect3dRMTexture Interface.

Syntax

public int getDecalTransparency();


getDecalTransparentColor (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getDecalTransparentColor

This is a method of the IDirect3dRMTexture Interface.

Syntax

public int getDecalTransparentColor();


getImage (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getImage

This is a method of the IDirect3dRMTexture Interface.

Syntax

public D3dRMImage getImage();


getImageBuffer (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getImageBuffer

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void getImageBuffer(byte[] buffer1);


getImagePalette (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getImagePalette

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void getImagePalette(byte[] pal);


getName (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMTexture Interface.

Syntax

public String getName();


getShades (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

getShades

This is a method of the IDirect3dRMTexture Interface.

Syntax

public int getShades();


initFromFile (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

initFromFile

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void initFromFile(String filename);


initFromResource (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

initFromResource

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void initFromResource(int rs);


initFromSurface (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

initFromSurface

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void initFromSurface(DirectDrawSurface ddS);


setAppData (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void setAppData(int data);


setColors (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

setColors

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void setColors(int c);


setDecalOrigin (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

setDecalOrigin

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void setDecalOrigin(int x, int y);


setDecalScale (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

setDecalScale

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void setDecalScale(int s);


setDecalSize (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

setDecalSize

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void setDecalSize(float width, float height);


setDecalTransparency (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

setDecalTransparency

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void setDecalTransparency(int trans);


setDecalTransparentColor (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

setDecalTransparentColor

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void setDecalTransparentColor(int tcolor);


setName (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void setName(String name);


setShades (IDirect3dRMTexture Interface)

 Microsoft SDK for Java

setShades

This is a method of the IDirect3dRMTexture Interface.

Syntax

public void setShades(int s);


IDirect3dRMUserVisual Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMUserVisual Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMUserVisual extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMUserVisual duplicate();
  public int getAppData();
  public String getClassName();
  public String getName();
  public void setAppData(int data);
  public void setName(String name);
}

For a description of methods and parameters, see Direct3dRMUserVisual

Hierarchy

IUnknown
  |
  +--IDirect3dRMUserVisual


Methods (IDirect3dRMUserVisual Interface)

 Microsoft SDK for Java

IDirect3dRMUserVisual Interface Methods

The IDirect3dRMUserVisual Interface contains the following methods:

addDestroyCallback
deleteDestroyCallback
duplicate
getAppData
getClassName
getName
setAppData
setName


addDestroyCallback (IDirect3dRMUserVisual Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMUserVisual Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


deleteDestroyCallback (IDirect3dRMUserVisual Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMUserVisual Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMUserVisual Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMUserVisual Interface.

Syntax

public Direct3dRMUserVisual duplicate();


getAppData (IDirect3dRMUserVisual Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMUserVisual Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMUserVisual Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMUserVisual Interface.

Syntax

public String getClassName();


getName (IDirect3dRMUserVisual Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMUserVisual Interface.

Syntax

public String getName();


setAppData (IDirect3dRMUserVisual Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMUserVisual Interface.

Syntax

public void setAppData(int data);


setName (IDirect3dRMUserVisual Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMUserVisual Interface.

Syntax

public void setName(String name);


IDirect3dRMViewport Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMViewport Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMViewport extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void clear();
  public void configure(int x, int y, int width, int height);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMViewport duplicate();
  public void forceUpdate(int x1, int y1, int x2, int y2);
  public int getAppData();
  public float getBack();
  public Direct3dRMFrame getCamera();
  public String getClassName();
  public Direct3dRMDevice getDevice();
  public Direct3dViewport getDirect3DViewport();
  public float getField();
  public float getFront();
  public int getHeight();
  public String getName();
  public void getPlane(float[] l, float[] r, float[] b, float[] t);
  public int getProjection();
  public int getUniformScaling();
  public int getWidth();
  public int getX();
  public int getY();
  public void inverseTransform(D3dVector d, D3dRMvector4d s);
  public Direct3dRMPickArray pick(int x, int y);
  public void render(Direct3dRMFrame f);
  public void setAppData(int data);
  public void setBack(float v);
  public void setCamera(Direct3dRMFrame f);
  public void setField(float v);
  public void setFront(float v);
  public void setName(String name);
  public void setPlane(float left, float right, float bottom, float
        top);
  public void setProjection(int val);
  public void setUniformScaling(int flag);
  public void transform(D3dRMvector4d d, D3dVector s);
}

For a description of methods and parameters, see Direct3dRMViewport.

Hierarchy

IUnknown
  |
  +--IDirect3dRMViewport


Methods (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

IDirect3dRMViewport Interface Methods

The IDirect3dRMViewport Interface contains the following methods:

addDestroyCallback
clear
configure
deleteDestroyCallback
duplicate
forceUpdate
getAppData
getBack
getCamera
getClassName
getDevice
getDirect3DViewport
getField
getFront
getHeight
getName
getPlane
getProjection
getUniformScaling
getWidth
getX
getY
inverseTransform
pick
render
setAppData
setBack
setCamera
setField
setFront
setName
setPlane
setProjection
setUniformScaling
transform


addDestroyCallback (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


clear (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

clear

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void clear();


configure (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

configure

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void configure(int x, int y, int width, int height);


deleteDestroyCallback (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMViewport Interface.

Syntax

public Direct3dRMViewport duplicate();


forceUpdate (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

forceUpdate

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void forceUpdate(int x1, int y1, int x2, int y2);


getAppData (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMViewport Interface.

Syntax

public int getAppData();


getBack (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getBack

This is a method of the IDirect3dRMViewport Interface.

Syntax

public float getBack();


getCamera (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getCamera

This is a method of the IDirect3dRMViewport Interface.

Syntax

public Direct3dRMFrame getCamera();


getClassName (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMViewport Interface.

Syntax

public String getClassName();


getDevice (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getDevice

This is a method of the IDirect3dRMViewport Interface.

Syntax

public Direct3dRMDevice getDevice();


getDirect3DViewport (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getDirect3DViewport

This is a method of the IDirect3dRMViewport Interface.

Syntax

public Direct3dViewport getDirect3DViewport();


getField (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getField

This is a method of the IDirect3dRMViewport Interface.

Syntax

public float getField();


getFront (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getFront

This is a method of the IDirect3dRMViewport Interface.

Syntax

public float getFront();


getHeight (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getHeight

This is a method of the IDirect3dRMViewport Interface.

Syntax

public int getHeight();


getName (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMViewport Interface.

Syntax

public String getName();


getPlane (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getPlane

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void getPlane(float[] l, float[] r, float[] b, float[] t);


getProjection (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getProjection

This is a method of the IDirect3dRMViewport Interface.

Syntax

public int getProjection();


getUniformScaling (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getUniformScaling

This is a method of the IDirect3dRMViewport Interface.

Syntax

public int getUniformScaling();


getWidth (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getWidth

This is a method of the IDirect3dRMViewport Interface.

Syntax

public int getWidth();


getX (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getX

This is a method of the IDirect3dRMViewport Interface.

Syntax

public int getX();


getY (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

getY

This is a method of the IDirect3dRMViewport Interface.

Syntax

public int getY();


inverseTransform (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

inverseTransform

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void inverseTransform(D3dVector d, D3dRMvector4d s);


pick (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

pick

This is a method of the IDirect3dRMViewport Interface.

Syntax

public Direct3dRMPickArray pick(int x, int y);


render (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

render

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void render(Direct3dRMFrame f);


setAppData (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void setAppData(int data);


setBack (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

setBack

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void setBack(float v);


setCamera (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

setCamera

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void setCamera(Direct3dRMFrame f);


setField (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

setField

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void setField(float v);


setFront (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

setFront

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void setFront(float v);


setName (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void setName(String name);


setPlane (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

setPlane

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void setPlane(float left, float right, float bottom, float top);


setProjection (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

setProjection

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void setProjection(int val);


setUniformScaling (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

setUniformScaling

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void setUniformScaling(int flag);


transform (IDirect3dRMViewport Interface)

 Microsoft SDK for Java

transform

This is a method of the IDirect3dRMViewport Interface.

Syntax

public void transform(D3dRMvector4d d, D3dVector s);


IDirect3dRMViewportArray Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMViewportArray Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMViewportArray extends IUnknown
{
  // Methods
  public Direct3dRMViewport getElement(int index);
  public int getSize();
}

For a description of methods and parameters, see Direct3dRMViewportArray.

Hierarchy

IUnknown
  |
  +--IDirect3dRMViewportArray


Methods (IDirect3dRMViewportArray Interface)

 Microsoft SDK for Java

IDirect3dRMViewportArray Interface Methods

The IDirect3dRMViewportArray Interface contains the following methods:

getElement
getSize


getElement (IDirect3dRMViewportArray Interface)

 Microsoft SDK for Java

getElement

This is a method of the IDirect3dRMViewportArray Interface.

Syntax

public Direct3dRMViewport getElement(int index);


getSize (IDirect3dRMViewportArray Interface)

 Microsoft SDK for Java

getSize

This is a method of the IDirect3dRMViewportArray Interface.

Syntax

public int getSize();


IDirect3dRMVisual Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMVisual Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMVisual extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMVisual duplicate();
  public int getAppData();
  public String getClassName();
  public Direct3dRMMeshBuilder getd3drmMeshBuilder();
  public String getName();
  public void setAppData(int data);
  public void setName(String name);
}

For a description of methods and parameters, see Direct3dRMVisual.

Hierarchy

IUnknown
  |
  +--IDirect3dRMVisual


Methods (IDirect3dRMVisual Interface)

 Microsoft SDK for Java

IDirect3dRMVisual Interface Methods

The IDirect3dRMVisual Interface contains the following methods:

addDestroyCallback deleteDestroyCallback
duplicate
getAppData
getClassName
getd3drmMeshBuilder
getName
setAppData
setName


addDestroyCallback (IDirect3dRMVisual Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMVisual Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


deleteDestroyCallback (IDirect3dRMVisual Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMVisual Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMVisual Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMVisual Interface.

Syntax

public Direct3dRMVisual duplicate();


getAppData (IDirect3dRMVisual Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMVisual Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMVisual Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMVisual Interface.

Syntax

public String getClassName();


getd3drmMeshBuilder (IDirect3dRMVisual Interface)

 Microsoft SDK for Java

getd3drmMeshBuilder

This is a method of the IDirect3dRMVisual Interface.

Syntax

public Direct3dRMMeshBuilder getd3drmMeshBuilder();


getName (IDirect3dRMVisual Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMVisual Interface.

Syntax

public String getName();


setAppData (IDirect3dRMVisual Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMVisual Interface.

Syntax

public void setAppData(int data);


setName (IDirect3dRMVisual Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMVisual Interface.

Syntax

public void setName(String name);


IDirect3dRMVisualArray Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMVisualArray Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMVisualArray extends IUnknown
{
  // Methods
  public Direct3dRMVisual getElement(int index);
  public int getSize();
}

For a description of methods and parameters, see Direct3dRMVisualArray.

Hierarchy

IUnknown
  |
  +--IDirect3dRMVisualArray


Methods (IDirect3dRMVisualArray Interface)

 Microsoft SDK for Java

IDirect3dRMVisualArray Interface Methods

The IDirect3dRMVisualArray Interface contains the following methods:

getElement
getSize


getElement (IDirect3dRMVisualArray Interface)

 Microsoft SDK for Java

getElement

This is a method of the IDirect3dRMVisualArray Interface.

Syntax

public Direct3dRMVisual getElement(int index);


getSize (IDirect3dRMVisualArray Interface)

 Microsoft SDK for Java

getSize

This is a method of the IDirect3dRMVisualArray Interface.

Syntax

public int getSize();


IDirect3dRMWinDevice Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMWinDevice Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMWinDevice extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMWinDevice duplicate();
  public int getAppData();
  public String getClassName();
  public String getName();
  public void handleActivate(int wparam);
  public void handlePaint(int hdc);
  public void setAppData(int data);
  public void setName(String name);
}

For a description of methods and parameters, see Direct3dRMWinDevice.

Hierarchy

IUnknown
  |
  +--IDirect3dRMWinDevice


Methods (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

IDirect3dRMWinDevice Interface Methods

The IDirect3dRMWinDevice Interface contains the following methods:

addDestroyCallback
deleteDestroyCallback
duplicate
getAppData
getClassName
getName
handleActivate
handlePaint
setAppData
setName


addDestroyCallback (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMWinDevice Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


deleteDestroyCallback (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMWinDevice Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMWinDevice Interface.

Syntax

public Direct3dRMWinDevice duplicate();


getAppData (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMWinDevice Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMWinDevice Interface.

Syntax

public String getClassName();


getName (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMWinDevice Interface.

Syntax

public String getName();


handleActivate (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

handleActivate

This is a method of the IDirect3dRMWinDevice Interface.

Syntax

public void handleActivate(int wparam);


handlePaint (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

handlePaint

This is a method of the IDirect3dRMWinDevice Interface.

Syntax

public void handlePaint(int hdc);


setAppData (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMWinDevice Interface.

Syntax

public void setAppData(int data);


setName (IDirect3dRMWinDevice Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMWinDevice Interface.

Syntax

public void setName(String name);


IDirect3dRMWrap Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dRMWrap Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dRMWrap extends IUnknown
{
  // Methods
  public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);
  public void apply(Direct3dRMObject o);
  public void applyRelative(Direct3dRMFrame f, Direct3dRMObject o);
  public void deleteDestroyCallback(Id3drmCallback fn,
        IUnknown args);
  public Direct3dRMWrap duplicate();
  public int getAppData();
  public String getClassName();
  public String getName();
  public void setAppData(int data);
  public void setName(String name);
}

For a description of methods and parameters, see Direct3dRMWrap.

Hierarchy

IUnknown
  |
  +--IDirect3dRMWrap


Methods (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

IDirect3dRMWrap Interface Methods

The IDirect3dRMWrap Interface contains the following methods:

addDestroyCallback
apply
applyRelative
deleteDestroyCallback
duplicate
getAppData
getClassName
getName
setAppData
setName


addDestroyCallback (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

addDestroyCallback

This is a method of the IDirect3dRMWrap Interface.

Syntax

public void addDestroyCallback(Id3drmCallback fn, IUnknown Arg);


apply (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

apply

This is a method of the IDirect3dRMWrap Interface.

Syntax

public void apply(Direct3dRMObject o);


applyRelative (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

applyRelative

This is a method of the IDirect3dRMWrap Interface.

Syntax

public void applyRelative(Direct3dRMFrame f, Direct3dRMObject o);


deleteDestroyCallback (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

deleteDestroyCallback

This is a method of the IDirect3dRMWrap Interface.

Syntax

public void deleteDestroyCallback(Id3drmCallback fn, IUnknown args);


duplicate (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

duplicate

This is a method of the IDirect3dRMWrap Interface.

Syntax

public Direct3dRMWrap duplicate();


getAppData (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

getAppData

This is a method of the IDirect3dRMWrap Interface.

Syntax

public int getAppData();


getClassName (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

getClassName

This is a method of the IDirect3dRMWrap Interface.

Syntax

public String getClassName();


getName (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

getName

This is a method of the IDirect3dRMWrap Interface.

Syntax

public String getName();


setAppData (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

setAppData

This is a method of the IDirect3dRMWrap Interface.

Syntax

public void setAppData(int data);


setName (IDirect3dRMWrap Interface)

 Microsoft SDK for Java

setName

This is a method of the IDirect3dRMWrap Interface.

Syntax

public void setName(String name);


IDirect3dTexture Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dTexture Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dTexture extends IUnknown
{
  // Methods
  public int getHandle(Direct3dDevice dev);
  public void initialize(Direct3dDevice dev,
        DirectDrawSurface surf);
  public void load(Direct3dTexture tex);
  public void paletteChanged(int start, int count);
  public void unload();
}

For a description of methods and parameters, see Direct3dTexture.

Hierarchy

IUnknown
  |
  +--IDirect3dTexture


Methods (IDirect3dTexture Interface)

 Microsoft SDK for Java

IDirect3dTexture Interface Methods

The IDirect3dTexture Interface contains the following methods:

getHandle
initialize
load
paletteChanged
unload


getHandle (IDirect3dTexture Interface)

 Microsoft SDK for Java

getHandle

This is a method of the IDirect3dTexture Interface.

Syntax

public int getHandle(Direct3dDevice dev);


initialize (IDirect3dTexture Interface)

 Microsoft SDK for Java

initialize

This is a method of the IDirect3dTexture Interface.

Syntax

public void initialize(Direct3dDevice dev, DirectDrawSurface surf);


load (IDirect3dTexture Interface)

 Microsoft SDK for Java

load

This is a method of the IDirect3dTexture Interface.

Syntax

public void load(Direct3dTexture tex);


paletteChanged (IDirect3dTexture Interface)

 Microsoft SDK for Java

paletteChanged

This is a method of the IDirect3dTexture Interface.

Syntax

public void paletteChanged(int start, int count);


unload (IDirect3dTexture Interface)

 Microsoft SDK for Java

unload

This is a method of the IDirect3dTexture Interface.

Syntax

public void unload();


IDirect3dViewport Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirect3dViewport Interface

This is an interface of the com.ms.directX package.

public interface IDirect3dViewport extends IUnknown
{
  // Methods
  public void clear(D3dRect rec, int flags);
  public void getBackground(int[] hdl, int[] stat);
  public DirectDrawSurface getBackgroundDepth(int[] status);
  public void getViewport(D3dViewportDesc vp);
  public void setBackground(int hdl);
  public void setBackgroundDepth(DirectDrawSurface surface);
  public void setViewport(D3dViewportDesc vp);
}

For a description of methods and parameters, see Direct3dViewport.

Hierarchy

IUnknown
  |
  +--IDirect3dViewport


Methods (IDirect3dViewport Interface)

 Microsoft SDK for Java

IDirect3dViewport Interface Methods

The IDirect3dViewport Interface contains following methods:

clear
getBackground
getBackgroundDepth
getViewport
setBackground
setBackgroundDepth
setViewport


clear (IDirect3dViewport Interface)

 Microsoft SDK for Java

clear

This is a method of the IDirect3dViewport Interface.

Syntax

public void clear(D3dRect rec, int flags);


getBackground (IDirect3dViewport Interface)

 Microsoft SDK for Java

getBackground

This is a method of the IDirect3dViewport Interface.

Syntax

public void getBackground(int[] hdl, int[] stat);


getBackgroundDepth (IDirect3dViewport Interface)

 Microsoft SDK for Java

getBackgroundDepth

This is a method of the IDirect3dViewport Interface.

Syntax

public DirectDrawSurface getBackgroundDepth(int[] status);


getViewport (IDirect3dViewport Interface)

 Microsoft SDK for Java

getViewport

This is a method of the IDirect3dViewport Interface.

Syntax

public void getViewport(D3dViewportDesc vp);


setBackground (IDirect3dViewport Interface)

 Microsoft SDK for Java

setBackground

This is a method of the IDirect3dViewport Interface.

Syntax

public void setBackground(int hdl);


setBackgroundDepth (IDirect3dViewport Interface)

 Microsoft SDK for Java

setBackgroundDepth

This is a method of the IDirect3dViewport Interface.

Syntax

public void setBackgroundDepth(DirectDrawSurface surface);


setViewport (IDirect3dViewport Interface)

 Microsoft SDK for Java

setViewport

This is a method of the IDirect3dViewport Interface.

Syntax

public void setViewport(D3dViewportDesc vp);


IDirectDraw Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectDraw Interface

This is an interface of the com.ms.directX package.

public interface IDirectDraw extends IUnknown
{
  // Methods
  public void Compact();
  public DirectDrawClipper createClipper(int flags);
  public Direct3d createD3D();
  public DirectDrawPalette createPalette(int flags, byte[] pe);
  public DirectDrawSurface createSurface(DDSurfaceDesc dd);
  public DirectDrawSurface duplicateSurface(DirectDrawSurface ddIn);
  public void enumDisplayModes(int d, DDSurfaceDesc s,
        IUnknown args, IEnumModesCallback fn);
  public void enumSurfaces(int d, DDSurfaceDesc s, IUnknown args,
        IEnumSurfacesCallback fn);
  public void flipToGDISurface();
  public int getAvailableTotalMem();
  public void getCaps(DDCaps DriverCaps, DDCaps HELcaps);
  public void getDisplayMode(DDSurfaceDesc surface);
  public int getFourCCCodes(int[] size);
  public int getFreeMem();
  public DirectDrawSurface getGDISurface();
  public int getMonitorFrequency();
  public int getNumFourCCCodes();
  public int getScanLine();
  public int getVerticalBlankStatus();
  public DirectDrawPalette loadPaletteFromBitmap(String bName);
  public void restoreDisplayMode();
  public void SetCooperativeLevel(int hdl, int flags);
  public void setDisplayMode(int w, int h, int bpp, int ref,
        int mode);
  public int systemBpp();
  public int tickCount();
  public void waitForVerticalBlank(int flags, int handle);
}

For a description of methods and parameters, see DirectDraw.

Hierarchy

IUnknown
  |
  +--IDirectDraw


Methods (IDirectDraw Interface)

 Microsoft SDK for Java

IDirectDraw Interface Methods

The IDirectDraw Interface contains the following methods:

Compact
createClipper
createD3D
createPalette
createSurface
duplicateSurface
enumDisplayModes
enumSurfaces
flipToGDISurface
getAvailableTotalMem
getCaps
getDisplayMode
getFourCCCodes
getFreeMem
getGDISurface
getMonitorFrequency
getNumFourCCCodes
getScanLine
getVerticalBlankStatus
loadPaletteFromBitmap
restoreDisplayMode
SetCooperativeLevel
setDisplayMode
systemBpp
tickCount
waitForVerticalBlank


Compact (IDirectDraw Interface)

 Microsoft SDK for Java

Compact

This is a method of the IDirectDraw Interface.

Syntax

public void Compact();


createClipper (IDirectDraw Interface)

 Microsoft SDK for Java

createClipper

This is a method of the IDirectDraw Interface.

Syntax

public DirectDrawClipper createClipper(int flags);


createD3D (IDirectDraw Interface)

 Microsoft SDK for Java

createD3D

This is a method of the IDirectDraw Interface.

Syntax

public Direct3d createD3D();


createPalette (IDirectDraw Interface)

 Microsoft SDK for Java

createPalette

This is a method of the IDirectDraw Interface.

Syntax

public DirectDrawPalette createPalette(int flags, byte[] pe);


createSurface (IDirectDraw Interface)

 Microsoft SDK for Java

createSurface

This is a method of the IDirectDraw Interface.

Syntax

public DirectDrawSurface createSurface(DDSurfaceDesc dd);


duplicateSurface (IDirectDraw Interface)

 Microsoft SDK for Java

duplicateSurface

This is a method of the IDirectDraw Interface.

Syntax

public DirectDrawSurface duplicateSurface(DirectDrawSurface ddIn);


enumDisplayModes (IDirectDraw Interface)

 Microsoft SDK for Java

enumDisplayModes

This is a method of the IDirectDraw Interface.

Syntax

public void enumDisplayModes(int d, DDSurfaceDesc s, IUnknown args, IEnumModesCallback fn);


enumSurfaces (IDirectDraw Interface)

 Microsoft SDK for Java

enumSurfaces

This is a method of the IDirectDraw Interface.

Syntax

public void enumSurfaces(int d, DDSurfaceDesc s, IUnknown args, IEnumSurfacesCallback fn);


flipToGDISurface (IDirectDraw Interface)

 Microsoft SDK for Java

flipToGDISurface

This is a method of the IDirectDraw Interface.

Syntax

public void flipToGDISurface();


getAvailableTotalMem (IDirectDraw Interface)

 Microsoft SDK for Java

getAvailableTotalMem

This is a method of the IDirectDraw Interface.

Syntax

public int getAvailableTotalMem();


getCaps (IDirectDraw Interface)

 Microsoft SDK for Java

getCaps

This is a method of the IDirectDraw Interface.

Syntax

public void getCaps(DDCaps DriverCaps, DDCaps HELcaps);


getDisplayMode (IDirectDraw Interface)

 Microsoft SDK for Java

getDisplayMode

This is a method of the IDirectDraw Interface.

Syntax

public void getDisplayMode(DDSurfaceDesc surface);


getFourCCCodes (IDirectDraw Interface)

 Microsoft SDK for Java

getFourCCCodes

This is a method of the IDirectDraw Interface.

Syntax

public int getFourCCCodes(int[] size);


getFreeMem (IDirectDraw Interface)

 Microsoft SDK for Java

getFreeMem

This is a method of the IDirectDraw Interface.

Syntax

public int getFreeMem();


getGDISurface (IDirectDraw Interface)

 Microsoft SDK for Java

getGDISurface

This is a method of the IDirectDraw Interface.

Syntax

public DirectDrawSurface getGDISurface();


getMonitorFrequency (IDirectDraw Interface)

 Microsoft SDK for Java

getMonitorFrequency

This is a method of the IDirectDraw Interface.

Syntax

public int getMonitorFrequency();


getNumFourCCCodes (IDirectDraw Interface)

 Microsoft SDK for Java

getNumFourCCCodes

This is a method of the IDirectDraw Interface.

Syntax

public int getNumFourCCCodes();


getScanLine (IDirectDraw Interface)

 Microsoft SDK for Java

getScanLine

This is a method of the IDirectDraw Interface.

Syntax

public int getScanLine();


getVerticalBlankStatus (IDirectDraw Interface)

 Microsoft SDK for Java

getVerticalBlankStatus

This is a method of the IDirectDraw Interface.

Syntax

public int getVerticalBlankStatus();


loadPaletteFromBitmap (IDirectDraw Interface)

 Microsoft SDK for Java

loadPaletteFromBitmap

This is a method of the IDirectDraw Interface.

Syntax

public DirectDrawPalette loadPaletteFromBitmap(String bName);


restoreDisplayMode (IDirectDraw Interface)

 Microsoft SDK for Java

restoreDisplayMode

This is a method of the IDirectDraw Interface.

Syntax

public void restoreDisplayMode();


SetCooperativeLevel (IDirectDraw Interface)

 Microsoft SDK for Java

SetCooperativeLevel

This is a method of the IDirectDraw Interface.

Syntax

public void SetCooperativeLevel(int hdl, int flags);


setDisplayMode (IDirectDraw Interface)

 Microsoft SDK for Java

setDisplayMode

This is a method of the IDirectDraw Interface.

Syntax

public void setDisplayMode(int w, int h, int bpp, int ref, int mode);


systemBpp (IDirectDraw Interface)

 Microsoft SDK for Java

systemBpp

This is a method of the IDirectDraw Interface.

Syntax

public int systemBpp();


tickCount (IDirectDraw Interface)

 Microsoft SDK for Java

tickCount

This is a method of the IDirectDraw Interface.

Syntax

public int tickCount();


waitForVerticalBlank (IDirectDraw Interface)

 Microsoft SDK for Java

waitForVerticalBlank

This is a method of the IDirectDraw Interface.

Syntax

public void waitForVerticalBlank(int flags, int handle);


IDirectDrawBitmap Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectDrawBitmap Interface

This is an interface of the com.ms.directX package.

public interface IDirectDrawBitmap extends IUnknown
{
  // Methods
  public void filename(String val);
  public int height();
  public void initHeight(int val);
  public void initWidth(int val);
  public int loaded();
  public int width();
}

For a description of methods and parameters, see DirectDrawBitmap.

Hierarchy

IUnknown
  |
  +--IDirectDrawBitmap


Methods (IDirectDrawBitmap Interface)

 Microsoft SDK for Java

IDirectDrawBitmap Interface Methods

The IDirectDrawBitmap Interface contains the following methods:

filename
height
initHeight
initWidth
loaded
width


filename (IDirectDrawBitmap Interface)

 Microsoft SDK for Java

filename

This is a method of the IDirectDrawBitmap Interface.

Syntax

public void filename(String val);


height (IDirectDrawBitmap Interface)

 Microsoft SDK for Java

height

This is a method of the IDirectDrawBitmap Interface.

Syntax

public int height();


initHeight (IDirectDrawBitmap Interface)

 Microsoft SDK for Java

initHeight

This is a method of the IDirectDrawBitmap Interface.

Syntax

public void initHeight(int val);


initWidth (IDirectDrawBitmap Interface)

 Microsoft SDK for Java

initWidth

This is a method of the IDirectDrawBitmap Interface.

Syntax

public void initWidth(int val);


loaded (IDirectDrawBitmap Interface)

 Microsoft SDK for Java

loaded

This is a method of the IDirectDrawBitmap Interface.

Syntax

public int loaded();


width (IDirectDrawBitmap Interface)

 Microsoft SDK for Java

width

This is a method of the IDirectDrawBitmap Interface.

Syntax

public int width();


IDirectDrawClipper Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectDrawClipper Interface

This is an interface of the com.ms.directX package.

public interface IDirectDrawClipper extends IUnknown
{
  // Methods
  public void getClipList(Rect rec, int[] rects, int count,
        Rect boundingrec);
  public int getClipListSize(Rect rec);
  public int getHWnd();
  public void initialize(DirectDraw dd, int flags);
  public int isClipListChanged();
  public void setClipList(Rect rec, int[] rects, int count);
  public void setHWnd(int flags, int hdl);
}

For a description of methods and parameters, see DirectDrawClipper.

Hierarchy

IUnknown
  |
  +--IDirectDrawClipper


Methods (IDirectDrawClipper Interface)

 Microsoft SDK for Java

IDirectDrawClipper Interface Methods

The IDirectDrawClipper Interface contains the following methods:

getClipList
getClipListSize
getHWnd
initialize
isClipListChanged
setClipList
setHWnd


getClipList (IDirectDrawClipper Interface)

 Microsoft SDK for Java

getClipList

This is a method of the IDirectDrawClipper Interface.

Syntax

public void getClipList(Rect rec, int[] rects, int count, Rect boundingrec);


getClipListSize (IDirectDrawClipper Interface)

 Microsoft SDK for Java

getClipListSize

This is a method of the IDirectDrawClipper Interface.

Syntax

public int getClipListSize(Rect rec);


getHWnd (IDirectDrawClipper Interface)

 Microsoft SDK for Java

getHWnd

This is a method of the IDirectDrawClipper Interface.

Syntax

public int getHWnd();


initialize (IDirectDrawClipper Interface)

 Microsoft SDK for Java

initialize

This is a method of the IDirectDrawClipper Interface.

Syntax

public void initialize(DirectDraw dd, int flags);


isClipListChanged (IDirectDrawClipper Interface)

 Microsoft SDK for Java

isClipListChanged

This is a method of the IDirectDrawClipper Interface.

Syntax

public int isClipListChanged();


setClipList (IDirectDrawClipper Interface)

 Microsoft SDK for Java

setClipList

This is a method of the IDirectDrawClipper Interface.

Syntax

public void setClipList(Rect rec, int[] rects, int count);


setHWnd (IDirectDrawClipper Interface)

 Microsoft SDK for Java

setHWnd

This is a method of the IDirectDrawClipper Interface.

Syntax

public void setHWnd(int flags, int hdl);


IDirectDrawPalette Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectDrawPalette Interface

This is an interface of the com.ms.directX package.

public interface IDirectDrawPalette extends IUnknown
{
  // Methods
  public int getCaps();
  public void getEntries(int flags, int start, int count,
        byte[] val);
  public void internalAttachDD(DirectDraw dd);
  public void setEntries(int flags, int start, int count,
        byte[] val);
}

For a description of methods and parameters, see DirectDrawPalette.

Hierarchy

IUnknown
  |
  +--IDirectDrawPalette


Methods (IDirectDrawPalette Interface)

 Microsoft SDK for Java

IDirectDrawPalette Interface Methods

The IDirectDrawPalette Interface contains the following methods:

getCaps
getEntries
internalAttachDD
setEntries


getCaps (IDirectDrawPalette Interface)

 Microsoft SDK for Java

getCaps

This is a method of the IDirectDrawPalette Interface.

Syntax

public int getCaps();


getEntries (IDirectDrawPalette Interface)

 Microsoft SDK for Java

getEntries

This is a method of the IDirectDrawPalette Interface.

Syntax

public void getEntries(int flags, int start, int count, byte[] val);


internalAttachDD (IDirectDrawPalette Interface)

 Microsoft SDK for Java

internalAttachDD

This is a method of the IDirectDrawPalette Interface.

Syntax

public void internalAttachDD(DirectDraw dd);


setEntries (IDirectDrawPalette Interface)

 Microsoft SDK for Java

setEntries

This is a method of the IDirectDrawPalette Interface.

Syntax

public void setEntries(int flags, int start, int count, byte[] val);


IDirectDrawSurface Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectDrawSurface Interface

This is an interface of the com.ms.directX package.

public interface IDirectDrawSurface extends IUnknown
{
  // Methods
  public void addAttachedSurface(DirectDrawSurface ddS);
  public void addOverlayDirtyRect(Rect r);
  public int blt(Rect dest, DirectDrawSurface ddS, Rect src,
        int flags);
  public int bltColorFill(Rect dest, int fillValue);
  public int bltFast(int dx, int dy, DirectDrawSurface ddS,
        Rect src, int trans);
  public int bltFx(Rect dest, DirectDrawSurface ddS, Rect src,
        int flags, DDBltFx bltFx);
  public void copyBitmap(DirectDrawBitmap val, int cx, int cy,
        int dx, int dy);
  public Direct3dDevice create3DDevice(_Guid g);
  public void deleteAttachedSurface(int flags,
        DirectDrawSurface ddS);
  public void enumAttachedSurfaces(IUnknown args,
        IEnumSurfacesCallback fn);
  public void enumOverlayZOrders(int flags, IUnknown args,
        IEnumZOrdersCallback fn);
  public void flip(DirectDrawSurface ddS, int flags);
  public void flush(Rect r, DDSurfaceDesc d, int flags, int hnd,
        int[] memory);
  public DirectDrawSurface getAttachedSurface(int caps);
  public int getBltStatus(int flags);
  public int getCaps();
  public DirectDrawClipper getClipper();
  public void getColorKey(int flags, DDColorKey val);
  public int getDC();
  public IUnknown getDDInterface();
  public int getFlipStatus(int flags);
  public int getOverlayPositionX();
  public int getOverlayPositionY();
  public DirectDrawPalette getPalette();
  public void getPixelFormat(DDPixelFormat pf);
  public void getSurfaceDesc(DDSurfaceDesc surface);
  public int isLost();
  public void lock(Rect r, DDSurfaceDesc d, int flags, int hnd,
        int[] memory);
  public void releaseDC(int hdc);
  public int restore();
  public void setClipper(DirectDrawClipper val);
  public void setColorKey(int flags, DDColorKey val);
  public void setOverlayPosition(int x, int y);
  public void setPalette(DirectDrawPalette ddp);
  public void unlock(DDSurfaceDesc data);
  public void updateOverlay(Rect r, DirectDrawSurface ddS, Rect d,
        int flags);
  public void updateOverlayDisplay(int flags);
  public void updateOverlayZOrder(int flags, DirectDrawSurface ddS);
}

For a description of methods and parameters, see DirectDrawSurface.

Hierarchy

IUnknown
  |
  +--IDirectDrawSurface


Methods (IDirectDrawSurface Interface)

 Microsoft SDK for Java

IDirectDrawSurface Interface Methods

The IDirectDrawSurface Interface contains the following methods:

addAttachedSurface
addOverlayDirtyRect
blt
bltColorFill
bltFast
bltFx
copyBitmap
create3DDevice
deleteAttachedSurface
enumAttachedSurfaces
enumOverlayZOrders
flip
flush
getAttachedSurface
getBltStatus
getCaps
getClipper
getColorKey
getDC
getDDInterface
getFlipStatus
getOverlayPositionX
getOverlayPositionY
getPalette
getPixelFormat
getSurfaceDesc
isLost
lock
releaseDC
restore
setClipper
setColorKey
setOverlayPosition
setPalette
unlock
updateOverlay
updateOverlayDisplay
updateOverlayZOrder


addAttachedSurface (IDirectDrawSurface Interface)

 Microsoft SDK for Java

addAttachedSurface

This is a method of the IDirectDrawSurface Interface.

Syntax

public void addAttachedSurface(DirectDrawSurface ddS);


addOverlayDirtyRect (IDirectDrawSurface Interface)

 Microsoft SDK for Java

addOverlayDirtyRect

This is a method of the IDirectDrawSurface Interface.

Syntax

public void addOverlayDirtyRect(Rect r);


blt (IDirectDrawSurface Interface)

 Microsoft SDK for Java

blt

This is a method of the IDirectDrawSurface Interface.

Syntax

public int blt(Rect dest, DirectDrawSurface ddS, Rect src, int flags);


bltColorFill (IDirectDrawSurface Interface)

 Microsoft SDK for Java

bltColorFill

This is a method of the IDirectDrawSurface Interface.

Syntax

public int bltColorFill(Rect dest, int fillValue);


bltFast (IDirectDrawSurface Interface)

 Microsoft SDK for Java

bltFast

This is a method of the IDirectDrawSurface Interface.

Syntax

public int bltFast(int dx, int dy, DirectDrawSurface ddS, Rect src, int trans);


bltFx (IDirectDrawSurface Interface)

 Microsoft SDK for Java

bltFx

This is a method of the IDirectDrawSurface Interface.

Syntax

public int bltFx(Rect dest, DirectDrawSurface ddS, Rect src, int flags, DDBltFx bltFx);


copyBitmap (IDirectDrawSurface Interface)

 Microsoft SDK for Java

copyBitmap

This is a method of the IDirectDrawSurface Interface.

Syntax

public void copyBitmap(DirectDrawBitmap val, int cx, int cy, int dx, int dy);


create3DDevice (IDirectDrawSurface Interface)

 Microsoft SDK for Java

create3DDevice

This is a method of the IDirectDrawSurface Interface.

Syntax

public Direct3dDevice create3DDevice(_Guid g);


deleteAttachedSurface (IDirectDrawSurface Interface)

 Microsoft SDK for Java

deleteAttachedSurface

This is a method of the IDirectDrawSurface Interface.

Syntax

public void deleteAttachedSurface(int flags, DirectDrawSurface ddS);


enumAttachedSurfaces (IDirectDrawSurface Interface)

 Microsoft SDK for Java

enumAttachedSurfaces

This is a method of the IDirectDrawSurface Interface.

Syntax

public void enumAttachedSurfaces(IUnknown args, IEnumSurfacesCallback fn);


enumOverlayZOrders (IDirectDrawSurface Interface)

 Microsoft SDK for Java

enumOverlayZOrders

This is a method of the IDirectDrawSurface Interface.

Syntax

public void enumOverlayZOrders(int flags, IUnknown args, IEnumZOrdersCallback fn);


flip (IDirectDrawSurface Interface)

 Microsoft SDK for Java

flip

This is a method of the IDirectDrawSurface Interface.

Syntax

public void flip(DirectDrawSurface ddS, int flags);


flush (IDirectDrawSurface Interface)

 Microsoft SDK for Java

flush

This is a method of the IDirectDrawSurface Interface.

Syntax

public void flush(Rect r, DDSurfaceDesc d, int flags, int hnd, int[] memory);


getAttachedSurface (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getAttachedSurface

This is a method of the IDirectDrawSurface Interface.

Syntax

public DirectDrawSurface getAttachedSurface(int caps);


getBltStatus (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getBltStatus

This is a method of the IDirectDrawSurface Interface.

Syntax

public int getBltStatus(int flags);


getCaps (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getCaps

This is a method of the IDirectDrawSurface Interface.

Syntax

public int getCaps();


getClipper (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getClipper

This is a method of the IDirectDrawSurface Interface.

Syntax

public DirectDrawClipper getClipper();


getColorKey (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getColorKey

This is a method of the IDirectDrawSurface Interface.

Syntax

public void getColorKey(int flags, DDColorKey val);


getDC (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getDC

This is a method of the IDirectDrawSurface Interface.

Syntax

public int getDC();


getDDInterface (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getDDInterface

This is a method of the IDirectDrawSurface Interface.

Syntax

public IUnknown getDDInterface();


getFlipStatus (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getFlipStatus

This is a method of the IDirectDrawSurface Interface.

Syntax

public int getFlipStatus(int flags);


getOverlayPositionX (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getOverlayPositionX

This is a method of the IDirectDrawSurface Interface.

Syntax

public int getOverlayPositionX();


getOverlayPositionY (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getOverlayPositionY

This is a method of the IDirectDrawSurface Interface.

Syntax

public int getOverlayPositionY();


getPalette (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getPalette

This is a method of the IDirectDrawSurface Interface.

Syntax

public DirectDrawPalette getPalette();


getPixelFormat (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getPixelFormat

This is a method of the IDirectDrawSurface Interface.

Syntax

public void getPixelFormat(DDPixelFormat pf);


getSurfaceDesc (IDirectDrawSurface Interface)

 Microsoft SDK for Java

getSurfaceDesc

This is a method of the IDirectDrawSurface Interface.

Syntax

public void getSurfaceDesc(DDSurfaceDesc surface);


isLost (IDirectDrawSurface Interface)

 Microsoft SDK for Java

isLost

This is a method of the IDirectDrawSurface Interface.

Syntax

public int isLost();


lock (IDirectDrawSurface Interface)

 Microsoft SDK for Java

lock

This is a method of the IDirectDrawSurface Interface.

Syntax

public void lock(Rect r, DDSurfaceDesc d, int flags, int hnd, int[] memory);


releaseDC (IDirectDrawSurface Interface)

 Microsoft SDK for Java

releaseDC

This is a method of the IDirectDrawSurface Interface.

Syntax

public void releaseDC(int hdc);


restore (IDirectDrawSurface Interface)

 Microsoft SDK for Java

restore

This is a method of the IDirectDrawSurface Interface.

Syntax

public int restore();


setClipper (IDirectDrawSurface Interface)

 Microsoft SDK for Java

setClipper

This is a method of the IDirectDrawSurface Interface.

Syntax

public void setClipper(DirectDrawClipper val);


setColorKey (IDirectDrawSurface Interface)

 Microsoft SDK for Java

setColorKey

This is a method of the IDirectDrawSurface Interface.

Syntax

public void setColorKey(int flags, DDColorKey val);


setOverlayPosition (IDirectDrawSurface Interface)

 Microsoft SDK for Java

setOverlayPosition

This is a method of the IDirectDrawSurface Interface.

Syntax

public void setOverlayPosition(int x, int y);


setPalette (IDirectDrawSurface Interface)

 Microsoft SDK for Java

setPalette

This is a method of the IDirectDrawSurface Interface.

Syntax

public void setPalette(DirectDrawPalette ddp);


unlock (IDirectDrawSurface Interface)

 Microsoft SDK for Java

unlock

This is a method of the IDirectDrawSurface Interface.

Syntax

public void unlock(DDSurfaceDesc data);


updateOverlay (IDirectDrawSurface Interface)

 Microsoft SDK for Java

updateOverlay

This is a method of the IDirectDrawSurface Interface.

Syntax

public void updateOverlay(Rect r, DirectDrawSurface ddS, Rect d, int flags);


updateOverlayDisplay (IDirectDrawSurface Interface)

 Microsoft SDK for Java

updateOverlayDisplay

This is a method of the IDirectDrawSurface Interface.

Syntax

public void updateOverlayDisplay(int flags);


updateOverlayZOrder (IDirectDrawSurface Interface)

 Microsoft SDK for Java

updateOverlayZOrder

This is a method of the IDirectDrawSurface Interface.

Syntax

public void updateOverlayZOrder(int flags, DirectDrawSurface ddS);


IDirectInput Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectInput Interface

This is an interface of the com.ms.directX package.

public interface IDirectInput extends IUnknown
{
  // Methods
  public void getDevCaps(int joyid, JoyCaps pjc);
  public String getDevCapsOEMVxd(int joyid);
  public String getDevCapsProductName(int joyid);
  public String getDevCapsRegKey(int joyid);
  public int getNumDevs();
  public void getPos(int joyid, JoyInfo info);
}

For a description of methods and parameters, see DirectInput.

Hierarchy

IUnknown
  |
  +--IDirectInput


Methods (IDirectInput Interface)

 Microsoft SDK for Java

IDirectInput Interface Methods

The IDirectInput Interface contains the following methods:

getDevCaps
getDevCapsOEMVxd
getDevCapsProductName
getDevCapsRegKey
getNumDevs
getPos


getDevCaps (IDirectInput Interface)

 Microsoft SDK for Java

getDevCaps

This is a method of the IDirectInput Interface.

Syntax

public void getDevCaps(int joyid, JoyCaps pjc);


getDevCapsOEMVxd (IDirectInput Interface)

 Microsoft SDK for Java

getDevCapsOEMVxd

This is a method of the IDirectInput Interface.

Syntax

public String getDevCapsOEMVxd(int joyid);


getDevCapsProductName (IDirectInput Interface)

 Microsoft SDK for Java

getDevCapsProductName

This is a method of the IDirectInput Interface.

Syntax

public String getDevCapsProductName(int joyid);


getDevCapsRegKey (IDirectInput Interface)

 Microsoft SDK for Java

getDevCapsRegKey

This is a method of the IDirectInput Interface.

Syntax

public String getDevCapsRegKey(int joyid);


getNumDevs (IDirectInput Interface)

 Microsoft SDK for Java

getNumDevs

This is a method of the IDirectInput Interface.

Syntax

public int getNumDevs();


getPos (IDirectInput Interface)

 Microsoft SDK for Java

getPos

This is a method of the IDirectInput Interface.

Syntax

public void getPos(int joyid, JoyInfo info);


IDirectPlay2 Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectPlay2 Interface

This is an interface of the com.ms.directX package.

public interface IDirectPlay2 extends IUnknown
{
  // Methods
  public void addPlayerToGroup(int groupId, int playerId);
  public void close();
  public IDirectPlay2 create(_Guid guid);
  public int createGroup(String friendlyName, String formalName,
        byte[] data, int dataSize);
  public int createPlayer(String friendlyName, String formalName,
        int receiveEvent, byte[] data, int dataSize);
  public void deletePlayerFromGroup(int groupId, int playerId);
  public void destroyGroup(int groupId);
  public void destroyPlayer(int playerId);
  public void enumGroupPlayers(int groupId, _Guid sessionGuid,
        IEnumPlayersCallback2 callback, IUnknown context,
        int flags);
  public void enumGroups(_Guid sessionGuid,
        IEnumPlayersCallback2 callback, IUnknown context,
        int flags);
  public void enumPlayers(_Guid sessionGuid,
        IEnumPlayersCallback2 callback, IUnknown context,
        int flags);
  public void enumServiceProviders(
        IEnumServiceProvidersCallback callback, IUnknown context);
  public void enumSessions(DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password, int timeOut,
        IEnumSessionsCallback2 callback, IUnknown context,
        int flags);
  public void getCaps(DPCaps caps, int flags);
  public void getGroupData(int groupId, byte[] data,
        int[] dataSize, int flags);
  public String getGroupFormalName(int groupId);
  public String getGroupFriendlyName(int groupId);
  public int getMessageCount(int playerId);
  public void getPlayerAddress(int playerId, byte[] addressData,
        int[] addressSize);
  public int getPlayerAddressSize(int playerId);
  public void getPlayerCaps(int playerId, DPCaps caps, int flags);
  public void getPlayerData(int playerId, byte[] data,
        int[] dataSize, int flags);
  public String getPlayerFormalName(int playerId);
  public String getPlayerFriendlyName(int playerId);
  public void getSessionDesc(DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String[] sessionName, String[] password);
  public void initialize(_Guid guid);
  public void open(DPSessionDesc sessionDesc, _Guid sessionGuid,
        _Guid applicationGuid, String sessionName,
        String password, int flags);
  public void receive(int[] fromPlayerId, int[] toPlayerId,
        int flags, byte[] data, int[] dataSize);
  public int receiveSize(int flags);
  public void send(int fromPlayerId, int toPlayerId, int flags,
        byte[] data, int dataSize);
  public void setGroupData(int groupId, byte[] data, int dataSize,
        int flags);
  public void setGroupName(int groupId, String friendlyName, String
        formalName, int flags);
  public void setPlayerData(int playerId, byte[] data,
        int dataSize, int flags);
  public void setPlayerName(int playerId, String friendlyName,
        String formalName, int flags);
  public void setSessionDesc(DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password, int flags);
}

For a description of methods and parameters, see DirectPlay2.

Hierarchy

IUnknown
  |
  +--IDirectPlay2


Methods (IDirectPlay2 Interface)

 Microsoft SDK for Java

IDirectPlay2 Interface Methods

The IDirectPlay2 Interface contains the following methods:

addPlayerToGroup
close
create
createGroup
createPlayer
deletePlayerFromGroup
destroyGroup
destroyPlayer
enumGroupPlayers
enumGroups
enumPlayers
enumServiceProviders
enumSessions
getCaps
getGroupData
getGroupFormalName
getGroupFriendlyName
getMessageCount
getPlayerAddress
getPlayerAddressSize
getPlayerCaps
getPlayerData
getPlayerFormalName
getPlayerFriendlyName
getSessionDesc
initialize
open
receive
receiveSize
send
setGroupData
setGroupName
setPlayerData
setPlayerName
setSessionDesc


addPlayerToGroup (IDirectPlay2 Interface)

 Microsoft SDK for Java

addPlayerToGroup

This is a method of the IDirectPlay2 Interface.

Syntax

public void addPlayerToGroup(int groupId, int playerId);


close (IDirectPlay2 Interface)

 Microsoft SDK for Java

close

This is a method of the IDirectPlay2 Interface.

Syntax

public void close();


create (IDirectPlay2 Interface)

 Microsoft SDK for Java

create

This is a method of the IDirectPlay2 Interface.

Syntax

public IDirectPlay2 create(_Guid guid);


createGroup (IDirectPlay2 Interface)

 Microsoft SDK for Java

createGroup

This is a method of the IDirectPlay2 Interface.

Syntax

public int createGroup(String friendlyName, String formalName, byte[] data, int dataSize);


createPlayer (IDirectPlay2 Interface)

 Microsoft SDK for Java

createPlayer

This is a method of the IDirectPlay2 Interface.

Syntax

public int createPlayer(String friendlyName, String formalName, int receiveEvent, byte[] data, int dataSize);


deletePlayerFromGroup (IDirectPlay2 Interface)

 Microsoft SDK for Java

deletePlayerFromGroup

This is a method of the IDirectPlay2 Interface.

Syntax

public void deletePlayerFromGroup(int groupId, int playerId);


destroyGroup (IDirectPlay2 Interface)

 Microsoft SDK for Java

destroyGroup

This is a method of the IDirectPlay2 Interface.

Syntax

public void destroyGroup(int groupId);


destroyPlayer (IDirectPlay2 Interface)

 Microsoft SDK for Java

destroyPlayer

This is a method of the IDirectPlay2 Interface.

Syntax

public void destroyPlayer(int playerId);


enumGroupPlayers (IDirectPlay2 Interface)

 Microsoft SDK for Java

enumGroupPlayers

This is a method of the IDirectPlay2 Interface.

Syntax

public void enumGroupPlayers(int groupId, _Guid sessionGuid, IEnumPlayersCallback2 callback, IUnknown context, int flags);


enumGroups (IDirectPlay2 Interface)

 Microsoft SDK for Java

enumGroups

This is a method of the IDirectPlay2 Interface.

Syntax

public void enumGroups(_Guid sessionGuid, IEnumPlayersCallback2 callback, IUnknown context, int flags);


enumPlayers (IDirectPlay2 Interface)

 Microsoft SDK for Java

enumPlayers

This is a method of the IDirectPlay2 Interface.

Syntax

public void enumPlayers(_Guid sessionGuid, IEnumPlayersCallback2 callback, IUnknown context, int flags);


enumServiceProviders (IDirectPlay2 Interface)

 Microsoft SDK for Java

enumServiceProviders

This is a method of the IDirectPlay2 Interface.

Syntax

public void enumServiceProviders(IEnumServiceProvidersCallback callback, IUnknown context);


enumSessions (IDirectPlay2 Interface)

 Microsoft SDK for Java

enumSessions

This is a method of the IDirectPlay2 Interface.

Syntax

public void enumSessions(DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String sessionName, String password, int timeOut, IEnumSessionsCallback2 calback, IUnknown context, int flags);


getCaps (IDirectPlay2 Interface)

 Microsoft SDK for Java

getCaps

This is a method of the IDirectPlay2 Interface.

Syntax

public void getCaps(DPCaps caps, int flags);


getGroupData (IDirectPlay2 Interface)

 Microsoft SDK for Java

getGroupData

This is a method of the IDirectPlay2 Interface.

Syntax

public void getGroupData(int groupId, byte[] data, int[] dataSize, int flags);


getGroupFormalName (IDirectPlay2 Interface)

 Microsoft SDK for Java

getGroupFormalName

This is a method of the IDirectPlay2 Interface.

Syntax

public String getGroupFormalName(int groupId);


getGroupFriendlyName (IDirectPlay2 Interface)

 Microsoft SDK for Java

getGroupFriendlyName

This is a method of the IDirectPlay2 Interface.

Syntax

public String getGroupFriendlyName(int groupId);


getMessageCount (IDirectPlay2 Interface)

 Microsoft SDK for Java

getMessageCount

This is a method of the IDirectPlay2 Interface.

Syntax

public int getMessageCount(int playerId);


getPlayerAddress (IDirectPlay2 Interface)

 Microsoft SDK for Java

getPlayerAddress

This is a method of the IDirectPlay2 Interface.

Syntax

public void getPlayerAddress(int playerId, byte[] addressData, int[] addressSize);


getPlayerAddressSize (IDirectPlay2 Interface)

 Microsoft SDK for Java

getPlayerAddressSize

This is a method of the IDirectPlay2 Interface.

Syntax

public int getPlayerAddressSize(int playerId);


getPlayerCaps (IDirectPlay2 Interface)

 Microsoft SDK for Java

getPlayerCaps

This is a method of the IDirectPlay2 Interface.

Syntax

public void getPlayerCaps(int playerId, DPCaps caps, int flags);


getPlayerData (IDirectPlay2 Interface)

 Microsoft SDK for Java

getPlayerData

This is a method of the IDirectPlay2 Interface.

Syntax

public void getPlayerData(int playerId, byte[] data, int[] dataSize, int flags);


getPlayerFormalName (IDirectPlay2 Interface)

 Microsoft SDK for Java

getPlayerFormalName

This is a method of the IDirectPlay2 Interface.

Syntax

public String getPlayerFormalName(int playerId);


getPlayerFriendlyName (IDirectPlay2 Interface)

 Microsoft SDK for Java

getPlayerFriendlyName

This is a method of the IDirectPlay2 Interface.

Syntax

public String getPlayerFriendlyName(int playerId);


getSessionDesc (IDirectPlay2 Interface)

 Microsoft SDK for Java

getSessionDesc

This is a method of the IDirectPlay2 Interface.

Syntax

public void getSessionDesc(DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String[] sessionName, String[] password);


initialize (IDirectPlay2 Interface)

 Microsoft SDK for Java

initialize

This is a method of the IDirectPlay2 Interface.

Syntax

public void initialize(_Guid guid);


open (IDirectPlay2 Interface)

 Microsoft SDK for Java

open

This is a method of the IDirectPlay2 Interface.

Syntax

public void open(DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String sessionName, String password, int flags);


receive (IDirectPlay2 Interface)

 Microsoft SDK for Java

receive

This is a method of the IDirectPlay2 Interface.

Syntax

public void receive(int[] fromPlayerId, int[] toPlayerId, int flags, byte[] data, int[] dataSize);


receiveSize (IDirectPlay2 Interface)

 Microsoft SDK for Java

receiveSize

This is a method of the IDirectPlay2 Interface.

Syntax

public int receiveSize(int flags);


send (IDirectPlay2 Interface)

 Microsoft SDK for Java

send

This is a method of the IDirectPlay2 Interface.

Syntax

public void send(int fromPlayerId, int toPlayerId, int flags, byte[] data, int dataSize);


setGroupData (IDirectPlay2 Interface)

 Microsoft SDK for Java

setGroupData

This is a method of the IDirectPlay2 Interface.

Syntax

public void setGroupData(int groupId, byte[] data, int dataSize, int flags);


setGroupName (IDirectPlay2 Interface)

 Microsoft SDK for Java

setGroupName

This is a method of the IDirectPlay2 Interface.

Syntax

public void setGroupName(int groupId, String friendlyName, String formalName, int flags);


setPlayerData (IDirectPlay2 Interface)

 Microsoft SDK for Java

setPlayerData

This is a method of the IDirectPlay2 Interface.

Syntax

public void setPlayerData(int playerId, byte[] data, int dataSize, int flags);


setPlayerName (IDirectPlay2 Interface)

 Microsoft SDK for Java

setPlayerName

This is a method of the IDirectPlay2 Interface.

Syntax

public void setPlayerName(int playerId, String friendlyName, String formalName, int flags);


setSessionDesc (IDirectPlay2 Interface)

 Microsoft SDK for Java

setSessionDesc

This is a method of the IDirectPlay2 Interface.

Syntax

public void setSessionDesc(DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String sessionName, String password, int flags);


IDirectPlayLobby Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectPlayLobby Interface

This is an interface of the com.ms.directX package.

public interface IDirectPlayLobby
{
  // Methods
  public IDirectPlay2 connect();
  public IDirectPlayLobby create(_Guid guid);
  public void createAddress(_Guid spGuid, _Guid addressTypeGuid,
        String addressString, byte[] addressData,
        int[] addressSize);
  public int createAddressSize(_Guid spGuid, _Guid addressTypeGuid,
        String addressString);
  public void enumAddress(IEnumAddressCallback callback,
        byte[] addressData, int addressSize, IUnknown context);
  public void enumAddressTypes(IEnumAddressTypesCallback callback,
        _Guid spGuid, IUnknown context, int flags);
  public void enumLocalApplications(
        IEnumLocalApplicationsCallback callback,
        IUnknown context, int flags);
  public void enumServiceProviders(
        IEnumServiceProvidersCallback callback, IUnknown context);
  public void getConnectionSettings(int applicationId,
        int[] connectionFlags, DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String[] sessionName, String[] password,
        String[] playerShortName, String[] playerLongName,
        _Guid guidSP, byte[] addressData, int[] addressSize);
  public int getConnectionSettingsAddressSize(int applicationId);
  public void receiveLobbyMessage(int applicationId, int[] flags,
        byte[] data, int[] dataSize);
  public void receiveLobbyMessageSize(int applicationId,
        int[] flags, int[] dataSize);
  public void runApplication(int[] applicationId,
        int connectionFlags, DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password,
        String playerShortName, String playerLongName,
        _Guid spGuid, byte[] addressData, int addressSize,
        int receiveEvent);
  public void sendLobbyMessage(int applicationId, byte[] data,
        int dataSize);
  public void setConnectionSettings(int applicationId,
        int connectionFlags, DPSessionDesc sessionDesc,
        _Guid sessionGuid, _Guid applicationGuid,
        String sessionName, String password,
        String playerShortName, String playerLongName,
        _Guid spGuid, byte[] addressData, int addressSize);
  public void setLobbyMessageEvent(int applicationId,
        int receiveEvent);
}

For a description of methods and parameters, see DirectPlayLobby.


Methods (IDirectPlayLobby Interface)

 Microsoft SDK for Java

IDirectPlayLobby Interface Methods

The IDirectPlayLobby Interface contains the following methods:

connect
create
createAddress
createAddressSize
enumAddress
enumAddressTypes
enumLocalApplications
enumServiceProviders
getConnectionSettings
getConnectionSettingsAddressSize
receiveLobbyMessage
receiveLobbyMessageSize
runApplication
sendLobbyMessage
setConnectionSettings
setLobbyMessageEvent


connect (IDirectPlayLobby Interface)

 Microsoft SDK for Java

connect

This is a method of the IDirectPlayLobby Interface.

Syntax

public IDirectPlay2 connect();


create (IDirectPlayLobby Interface)

 Microsoft SDK for Java

create

This is a method of the IDirectPlayLobby Interface.

Syntax

public IDirectPlayLobby create(_Guid guid);


createAddress (IDirectPlayLobby Interface)

 Microsoft SDK for Java

createAddress

This is a method of the IDirectPlayLobby Interface.

Syntax

public void createAddress(_Guid spGuid, _Guid addressTypeGuid, String addressString, byte[] addressData, int[] addressSize);


createAddressSize (IDirectPlayLobby Interface)

 Microsoft SDK for Java

createAddressSize

This is a method of the IDirectPlayLobby Interface.

Syntax

public int createAddressSize(_Guid spGuid, _Guid addressTypeGuid, String addressString);


enumAddress (IDirectPlayLobby Interface)

 Microsoft SDK for Java

enumAddress

This is a method of the IDirectPlayLobby Interface.

Syntax

public void enumAddress(IEnumAddressCallback callback, byte[] addressData, int addressSize, IUnknown context);


enumAddressTypes (IDirectPlayLobby Interface)

 Microsoft SDK for Java

enumAddressTypes

This is a method of the IDirectPlayLobby Interface.

Syntax

public void enumAddressTypes(IEnumAddressTypesCallback callback, _Guid spGuid, IUnknown context, int flags);


enumLocalApplications (IDirectPlayLobby Interface)

 Microsoft SDK for Java

enumLocalApplications

This is a method of the IDirectPlayLobby Interface.

Syntax

public void enumLocalApplications(IEnumLocalApplicationsCallback callback, IUnknown context, int flags);


enumServiceProviders (IDirectPlayLobby Interface)

 Microsoft SDK for Java

enumServiceProviders

This is a method of the IDirectPlayLobby Interface.

Syntax

public void enumServiceProviders(IEnumServiceProvidersCallback callback, IUnknown context);


getConnectionSettings (IDirectPlayLobby Interface)

 Microsoft SDK for Java

getConnectionSettings

This is a method of the IDirectPlayLobby Interface.

Syntax

public void getConnectionSettings(int applicationId, int[] connectionFlags, DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String[] sessionName, String[] password, String[] playerShortName, String[] playerLongName, _Guid guidSP, byte[] addressData, int[] addressSize);


getConnectionSettingsAddressSize (IDirectPlayLobby Interface)

 Microsoft SDK for Java

getConnectionSettingsAddressSize

This is a method of the IDirectPlayLobby Interface.

Syntax

public int getConnectionSettingsAddressSize(int applicationId);


receiveLobbyMessage (IDirectPlayLobby Interface)

 Microsoft SDK for Java

receiveLobbyMessage

This is a method of the IDirectPlayLobby Interface.

Syntax

public void receiveLobbyMessage(int applicationId, int[] flags, byte[] data, int[] dataSize);


receiveLobbyMessageSize (IDirectPlayLobby Interface)

 Microsoft SDK for Java

receiveLobbyMessageSize

This is a method of the IDirectPlayLobby Interface.

Syntax

public void receiveLobbyMessageSize(int applicationId, int[] flags, int[] dataSize);


runApplication (IDirectPlayLobby Interface)

 Microsoft SDK for Java

runApplication

This is a method of the IDirectPlayLobby Interface.

Syntax

public void runApplication(int[] applicationId, int connectionFlags, DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGud, String sessionName, String password, String playerShortName, String playerLongName, _Guid spGuid, byte[] addressData, int addressSize, int receiveEvent);


sendLobbyMessage (IDirectPlayLobby Interface)

 Microsoft SDK for Java

sendLobbyMessage

This is a method of the IDirectPlayLobby Interface.

Syntax

public void sendLobbyMessage(int applicationId, byte[] data, int dataSize);


setConnectionSettings (IDirectPlayLobby Interface)

 Microsoft SDK for Java

setConnectionSettings

This is a method of the IDirectPlayLobby Interface.

Syntax

public void setConnectionSettings(int applicationId, int connectionFlags, DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String sesionName, String password, String playerShortName, String playerLongName, _Guid spGuid, byte[] addressData, int addressSize);


setLobbyMessageEvent (IDirectPlayLobby Interface)

 Microsoft SDK for Java

setLobbyMessageEvent

This is a method of the IDirectPlayLobby Interface.

Syntax

public void setLobbyMessageEvent(int applicationId, int receiveEvent);


IDirectSound Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectSound Interface

This is an interface of the com.ms.directX package.

public interface IDirectSound extends IUnknown
{
  // Methods
  public void compact();
  public DirectSoundBuffer createSoundBuffer(
        DSBufferDesc bufferDesc, byte[] format);
  public DirectSoundBuffer duplicateSoundBuffer(
        DirectSoundBuffer original);
  public void enumSoundDrivers(IEnumSoundDriversCallback callback,
        IUnknown context);
  public void getCaps(DSCaps caps);
  public void getSpeakerConfig(int[] speakerConfig);
  public void initialize(_Guid guid);
  public void setCooperativeLevel(int hwnd, int level);
  public void setSpeakerConfig(int speakerConfig);
}

For a description of methods and parameters, see DirectSound.

Hierarchy

IUnknown  |
  +--IDirectSound


Methods (IDirectSound Interface)

 Microsoft SDK for Java

IDirectSound Interface Methods

The IDirectSound Interface contains the following methods:

compact
createSoundBuffer
duplicateSoundBuffer
enumSoundDrivers
getCaps
getSpeakerConfig
initialize
setCooperativeLevel
setSpeakerConfig


compact (IDirectSound Interface)

 Microsoft SDK for Java

compact

This is a method of the IDirectSound Interface.

Syntax

public void compact();


createSoundBuffer (IDirectSound Interface)

 Microsoft SDK for Java

createSoundBuffer

This is a method of the IDirectSound Interface.

Syntax

public DirectSoundBuffer createSoundBuffer(DSBufferDesc bufferDesc, byte[] format);


duplicateSoundBuffer (IDirectSound Interface)

 Microsoft SDK for Java

duplicateSoundBuffer

This is a method of the IDirectSound Interface.

Syntax

public DirectSoundBuffer duplicateSoundBuffer(DirectSoundBuffer original);


enumSoundDrivers (IDirectSound Interface)

 Microsoft SDK for Java

enumSoundDrivers

This is a method of the IDirectSound Interface.

Syntax

public void enumSoundDrivers(IEnumSoundDriversCallback callback, IUnknown context);


getCaps (IDirectSound Interface)

 Microsoft SDK for Java

getCaps

This is a method of the IDirectSound Interface.

Syntax

public void getCaps(DSCaps caps);


getSpeakerConfig (IDirectSound Interface)

 Microsoft SDK for Java

getSpeakerConfig

This is a method of the IDirectSound Interface.

Syntax

public void getSpeakerConfig(int[] speakerConfig);


initialize (IDirectSound Interface)

 Microsoft SDK for Java

initialize

This is a method of the IDirectSound Interface.

Syntax

public void initialize(_Guid guid);


setCooperativeLevel (IDirectSound Interface)

 Microsoft SDK for Java

setCooperativeLevel

This is a method of the IDirectSound Interface.

Syntax

public void setCooperativeLevel(int hwnd, int level);


setSpeakerConfig (IDirectSound Interface)

 Microsoft SDK for Java

setSpeakerConfig

This is a method of the IDirectSound Interface.

Syntax

public void setSpeakerConfig(int speakerConfig);


IDirectSound3dBuffer Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectSound3dBuffer Interface

This is an interface of the com.ms.directX package.

public interface IDirectSound3dBuffer extends IUnknown
{
  // Methods
  public void getAllParameters(DS3dBuffer buffer);
  public void getConeAngles(int[] inCone, int[] outCone);
  public void getConeOrientation(D3dVector orientation);
  public void getConeOutsideVolume(int[] coneOutsideVolume);
  public void getMaxDistance(float[] maxDistance);
  public void getMinDistance(float[] minDistance);
  public void getMode(int[] mode);
  public void getPosition(D3dVector position);
  public void getVelocity(D3dVector velocity);
  public void setAllParameters(DS3dBuffer buffer, int applyFlag);
  public void setConeAngles(int inCone, int outCone, int applyFlag);
  public void setConeOrientation(float x, float y, float z,
        int applyFlag);
  public void setConeOutsideVolume(int coneOutsideVolume,
        int applyFlag);
  public void setMaxDistance(float maxDistance, int applyFlag);
  public void setMinDistance(float minDistance, int applyFlag);
  public void setMode(int mode, int applyFlag);
  public void setPosition(float x, float y, float z, int applyFlag);
  public void setVelocity(float x, float y, float z, int applyFlag);
}

For a description of methods and parameters, see DirectSound3dBuffer.

Hierarchy

IUnknown
  |
  +--IDirectSound3dBuffer


Methods (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

IDirectSound3dBuffer Interface Methods

The IDirectSound3dBuffer Interface contains the following methods:

getAllParameters
getConeAngles
getConeOrientation
getConeOutsideVolume
getMaxDistance
getMinDistance
getMode
getPosition
getVelocity
setAllParameters
setConeAngles
setConeOrientation
setConeOutsideVolume
setMaxDistance
setMinDistance
setMode
setPosition
setVelocity


getAllParameters (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

getAllParameters

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void getAllParameters(DS3dBuffer buffer);


getConeAngles (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

getConeAngles

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void getConeAngles(int[] inCone, int[] outCone);


getConeOrientation (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

getConeOrientation

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void getConeOrientation(D3dVector orientation);


getConeOutsideVolume (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

getConeOutsideVolume

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void getConeOutsideVolume(int[] coneOutsideVolume);


getMaxDistance (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

getMaxDistance

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void getMaxDistance(float[] maxDistance);


getMinDistance (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

getMinDistance

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void getMinDistance(float[] minDistance);


getMode (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

getMode

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void getMode(int[] mode);


getPosition (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

getPosition

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void getPosition(D3dVector position);


getVelocity (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

getVelocity

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void getVelocity(D3dVector velocity);


setAllParameters (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

setAllParameters

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void setAllParameters(DS3dBuffer buffer, int applyFlag);


setConeAngles (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

setConeAngles

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void setConeAngles(int inCone, int outCone, int applyFlag);


setConeOrientation (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

setConeOrientation

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void setConeOrientation(float x, float y, float z, int applyFlag);


setConeOutsideVolume (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

setConeOutsideVolume

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void setConeOutsideVolume(int coneOutsideVolume, int applyFlag);


setMaxDistance (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

setMaxDistance

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void setMaxDistance(float maxDistance, int applyFlag);


setMinDistance (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

setMinDistance

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void setMinDistance(float minDistance, int applyFlag);


setMode (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

setMode

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void setMode(int mode, int applyFlag);


setPosition (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

setPosition

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void setPosition(float x, float y, float z, int applyFlag);


setVelocity (IDirectSound3dBuffer Interface)

 Microsoft SDK for Java

setVelocity

This is a method of the IDirectSound3dBuffer Interface.

Syntax

public void setVelocity(float x, float y, float z, int applyFlag);


IDirectSound3dListener Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectSound3dListener Interface

This is an interface of the com.ms.directX package.

public interface IDirectSound3dListener extends IUnknown
{
  // Methods
  public void commitDeferredSettings();
  public void getAllParameters(DS3dListener listener);
  public void getDistanceFactor(float[] distanceFactor);
  public void getDopplerFactor(float[] dopplerFactor);
  public void getOrientation(D3dVector orientFront,
        D3dVector orientTop);
  public void getPosition(D3dVector position);
  public void getRolloffFactor(float[] rolloffFactor);
  public void getVelocity(D3dVector velocity);
  public void setAllParameters(DS3dListener listener,
        int applyFlag);
  public void setDistanceFactor(float distanceFactor,
        int applyFlag);
  public void setDopplerFactor(float dopplerFactor, int applyFlag);
  public void setOrientation(float xFront, float yFront,
        float zFront, float xTop, float yTop, float zTop,
        int applyFlag);
  public void setPosition(float x, float y, float z, int applyFlag);
  public void setRolloffFactor(float rolloffFactor, int applyFlag);
  public void setVelocity(float x, float y, float z, int applyFlag);
}

For a description of methods and parameters, see DirectSound3dListener.

Hierarchy

IUnknown
  |
  +--IDirectSound3dListener


Methods (IDirectSound3dListener Interface)

 Microsoft SDK for Java

IDirectSound3dListener Interface Methods

The IDirectSound3dListener Interface contains the following methods:

commitDeferredSettings
getAllParameters
getDistanceFactor
getDopplerFactor
getOrientation
getPosition
getRolloffFactor
getVelocity
setAllParameters
setDistanceFactor
setDopplerFactor
setOrientation
setPosition
setRolloffFactor
setVelocity


commitDeferredSettings (IDirectSound3dListener Interface)

 Microsoft SDK for Java

commitDeferredSettings

This is a method of the IDirectSound3dListener Interface.

Syntax

public void commitDeferredSettings();


getAllParameters (IDirectSound3dListener Interface)

 Microsoft SDK for Java

getAllParameters

This is a method of the IDirectSound3dListener Interface.

Syntax

public void getAllParameters(DS3dListener listener);


getDistanceFactor (IDirectSound3dListener Interface)

 Microsoft SDK for Java

getDistanceFactor

This is a method of the IDirectSound3dListener Interface.

Syntax

public void getDistanceFactor(float[] distanceFactor);


getDopplerFactor (IDirectSound3dListener Interface)

 Microsoft SDK for Java

getDopplerFactor

This is a method of the IDirectSound3dListener Interface.

Syntax

public void getDopplerFactor(float[] dopplerFactor);


getOrientation (IDirectSound3dListener Interface)

 Microsoft SDK for Java

getOrientation

This is a method of the IDirectSound3dListener Interface.

Syntax

public void getOrientation(D3dVector orientFront, D3dVector orientTop);


getPosition (IDirectSound3dListener Interface)

 Microsoft SDK for Java

getPosition

This is a method of the IDirectSound3dListener Interface.

Syntax

public void getPosition(D3dVector position);


getRolloffFactor (IDirectSound3dListener Interface)

 Microsoft SDK for Java

getRolloffFactor

This is a method of the IDirectSound3dListener Interface.

Syntax

public void getRolloffFactor(float[] rolloffFactor);


getVelocity (IDirectSound3dListener Interface)

 Microsoft SDK for Java

getVelocity

This is a method of the IDirectSound3dListener Interface.

Syntax

public void getVelocity(D3dVector velocity);


setAllParameters (IDirectSound3dListener Interface)

 Microsoft SDK for Java

setAllParameters

This is a method of the IDirectSound3dListener Interface.

Syntax

public void setAllParameters(DS3dListener listener, int applyFlag);


setDistanceFactor (IDirectSound3dListener Interface)

 Microsoft SDK for Java

setDistanceFactor

This is a method of the IDirectSound3dListener Interface.

Syntax

public void setDistanceFactor(float distanceFactor, int applyFlag);


setDopplerFactor (IDirectSound3dListener Interface)

 Microsoft SDK for Java

setDopplerFactor

This is a method of the IDirectSound3dListener Interface.

Syntax

public void setDopplerFactor(float dopplerFactor, int applyFlag);


setOrientation (IDirectSound3dListener Interface)

 Microsoft SDK for Java

setOrientation

This is a method of the IDirectSound3dListener Interface.

Syntax

public void setOrientation(float xFront, float yFront, float zFront, float xTop, float yTop, float zTop, int applyFlag);


setPosition (IDirectSound3dListener Interface)

 Microsoft SDK for Java

setPosition

This is a method of the IDirectSound3dListener Interface.

Syntax

public void setPosition(float x, float y, float z, int applyFlag);


setRolloffFactor (IDirectSound3dListener Interface)

 Microsoft SDK for Java

setRolloffFactor

This is a method of the IDirectSound3dListener Interface.

Syntax

public void setRolloffFactor(float rolloffFactor, int applyFlag);


setVelocity (IDirectSound3dListener Interface)

 Microsoft SDK for Java

setVelocity

This is a method of the IDirectSound3dListener Interface.

Syntax

public void setVelocity(float x, float y, float z, int applyFlag);


IDirectSoundBuffer Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectSoundBuffer Interface

This is an interface of the com.ms.directX package.

public interface IDirectSoundBuffer extends IUnknown
{
  // Methods
  public void getCaps(DSBCaps caps);
  public void getCurrentPosition(DSCursors cursors);
  public void getFormat(byte[] format, int size);
  public int getFormatSize();
  public int getFrequency();
  public int getPan();
  public int getStatus();
  public int getVolume();
  public void play(int flags);
  public void restore();
  public void setCurrentPosition(int newPosition);
  public void setFormat(byte[] format);
  public void setFrequency(int frequency);
  public void setPan(int pan);
  public void setVolume(int volume);
  public void stop();
  public void transferToSoundBuffer(DSResourceDesc resourceDesc,
        int flags);
  public void writeBuffer(int start, int size, byte[] buffer,
        int flags);
}

For a description of methods and parameters, see DirectSoundBuffer.

Hierarchy

IUnknown
  |
  +--IDirectSoundBuffer


Methods (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

IDirectSoundBuffer Interface Methods

The IDirectSoundBuffer Interface contains the following methods:

getCaps
getCurrentPosition
getFormat
getFormatSize
getFrequency
getPan
getStatus
getVolume
play
restore
setCurrentPosition
setFormat
setFrequency
setPan
setVolume
stop
transferToSoundBuffer
writeBuffer


getCaps (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

getCaps

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void getCaps(DSBCaps caps);


getCurrentPosition (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

getCurrentPosition

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void getCurrentPosition(DSCursors cursors);


getFormat (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

getFormat

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void getFormat(byte[] format, int size);


getFormatSize (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

getFormatSize

This is a method of the IDirectSoundBuffer Interface.

Syntax

public int getFormatSize();


getFrequency (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

getFrequency

This is a method of the IDirectSoundBuffer Interface.

Syntax

public int getFrequency();


getPan (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

getPan

This is a method of the IDirectSoundBuffer Interface.

Syntax

public int getPan();


getStatus (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

getStatus

This is a method of the IDirectSoundBuffer Interface.

Syntax

public int getStatus();


getVolume (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

getVolume

This is a method of the IDirectSoundBuffer Interface.

Syntax

public int getVolume();


play (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

play

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void play(int flags);


restore (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

restore

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void restore();


setCurrentPosition (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

setCurrentPosition

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void setCurrentPosition(int newPosition);


setFormat (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

setFormat

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void setFormat(byte[] format);


setFrequency (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

setFrequency

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void setFrequency(int frequency);


setPan (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

setPan

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void setPan(int pan);


setVolume (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

setVolume

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void setVolume(int volume);


stop (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

stop

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void stop();


transferToSoundBuffer (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

transferToSoundBuffer

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void transferToSoundBuffer(DSResourceDesc resourceDesc, int flags);


writeBuffer (IDirectSoundBuffer Interface)

 Microsoft SDK for Java

writeBuffer

This is a method of the IDirectSoundBuffer Interface.

Syntax

public void writeBuffer(int start, int size, byte[] buffer, int flags);


IDirectSoundResource Interface (com.ms.directX Package)

 Microsoft SDK for Java

IDirectSoundResource Interface

This is an interface of the com.ms.directX package.

public interface IDirectSoundResource extends IUnknown
{
  // Methods
  public void loadWaveFile(String name,
        DSResourceDesc resourceDesc, byte[] wave);
  public void loadWaveResource(int handle,
        DSResourceDesc resourceDesc, byte[] wave);
  public void readBuffer(int sourceIndex, int destIndex, int size,
        DSResourceDesc resourceDesc, byte[] buffer, int maxbuf);
}

For a description of methods and parameters, see DirectSoundResource.

Hierarchy

IUnknown
  |
  +--IDirectSoundResource


Methods (IDirectSoundResource Interface)

 Microsoft SDK for Java

IDirectSoundResource Interface Methods

The IDirectSoundResource Interface contains the following methods:

loadWaveFile
loadWaveResource
readBuffer


loadWaveFile (IDirectSoundResource Interface)

 Microsoft SDK for Java

loadWaveFile

This is a method of the IDirectSoundResource Interface.

Syntax

public void loadWaveFile(String name, DSResourceDesc resourceDesc, byte[] wave);


loadWaveResource (IDirectSoundResource Interface)

 Microsoft SDK for Java

loadWaveResource

This is a method of the IDirectSoundResource Interface.

Syntax

public void loadWaveResource(int handle, DSResourceDesc resourceDesc, byte[] wave);


readBuffer (IDirectSoundResource Interface)

 Microsoft SDK for Java

readBuffer

This is a method of the IDirectSoundResource Interface.

Syntax

public void readBuffer(int sourceIndex, int destIndex, int size, DSResourceDesc resourceDesc, byte[] buffer, int maxbuf);


IEnumAddressCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumAddressCallback Interface

This is an interface of the com.ms.directX package.

public interface IEnumAddressCallback extends IUnknown
{
  // Methods
  public void callbackEnumAddress(_Guid typeGuid,
        byte[] addressData, int addressSize, IUnknown context);
}

Hierarchy

IUnknown
  |
  +--IEnumAddressCallback


Methods (IEnumAddressCallback Interface)

 Microsoft SDK for Java

IEnumAddressCallback Interface Methods

The IEnumAddressCallback Interface contains the following method:

callbackEnumAddress is an application-defined callback function for the DirectPlayLobby.enumAddress method.


callbackEnumAddress (IEnumAddressCallback Interface)

 Microsoft SDK for Java

callbackEnumAddress

This method of the IEnumAddressCallback Interface is an application-defined callback function for the DirectPlayLobby.enumAddress method.

Syntax

public void callbackEnumAddress(_Guid typeGuid, byte[] addressData, int addressSize, IUnknown context);

Parameters

typeGuid | A globally unique identifier (GUID) indicating the type of this data chunk.
addressData | The address of the constant data.
addressSize | The size of the address.
context | The context passed to the callback function.


IEnumAddressTypesCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumAddressTypesCallback Interface

This is an interface of the com.ms.directX package.

public interface IEnumAddressTypesCallback extends IUnknown
{
  // Methods
  public void callbackEnumAddressTypes(_Guid typeGuid,
        IUnknown context);
}

Hierarchy

IUnknown
  |
  +--IEnumAddressTypesCallback


Methods (IEnumAddressTypesCallback Interface)

 Microsoft SDK for Java

IEnumAddressTypesCallback Interface Methods

The IEnumAddressTypesCallback Interface contains the following method:

callbackEnumAddressTypes is an application-defined callback function for the DirectPlayLobby enumAddressTypes method.


callbackEnumAddressTypes (IEnumAddressTypesCallback Interface)

 Microsoft SDK for Java

callbackEnumAddressTypes

This method of the IEnumAddressTypesCallback Interface is an application-defined callback function for the DirectPlayLobby.enumAddressTypes method.

Syntax

public void callbackEnumAddressTypes(_Guid typeGuid, IUnknown context);

Parameters

typeGuid | A globally unique identifier (GUID) indicating the address type. Predefined address types are DPAID_Phone, DPAID_Inet, and DPAID_ComPort.
context | The context passed to the callback function.


IEnumerateObjectsCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumerateObjectsCallback Interface

The IEnumerateObjectsCallback Interface of the com.ms.directX package is used with Direct3dRM.enumerateObjects to set the callback function to be called for each active Direct3dRM object.

public interface IEnumerateObjectsCallback extends IUnknown
{
  // Methods
  public void callbackEnumerateObjects(IDirect3dRM f,
        IUnknown pArgs);
}

Hierarchy

IUnknown
  |
  +--IEnumerateObjectsCallback


Methods (IEnumerateObjectsCallback Interface)

 Microsoft SDK for Java

IEnumerateObjectsCallback Interface Methods

The IEnumerateObjectsCallback Interface contains the following method:

callbackEnumerateObjects enumerates objects. This callback function is application-defined.


callbackEnumerateObjects (IEnumerateObjectsCallback Interface)

 Microsoft SDK for Java

callbackEnumerateObjects

This method of the IEnumerateObjectsCallback Interface enumerates objects. This callback function is application-defined.

Syntax

public void callbackEnumerateObjects(IDirect3dRM f, IUnknown pArgs);

Parameters

f | A Direct3dRM object.
pArgs | The application-defined data passed to this callback function.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


IEnumLocalApplicationsCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumLocalApplicationsCallback Interface

This is an interface of the com.ms.directX package.

public interface IEnumLocalApplicationsCallback extends IUnknown
{
  // Methods
  public void callbackLocalApplications(_Guid applicationGuid,
        String applicationName, IUnknown context);
}

Hierarchy

IUnknown
  |
  +--IEnumLocalApplicationsCallback


Methods (IEnumLocalApplicationsCallback Interface)

 Microsoft SDK for Java

IEnumLocalApplicationsCallback Interface Methods

The IEnumLocalApplicationsCallback Interface contains the following method:

callbackLocalApplications is an application-defined callback function for the DirectPlayLobby.enumLocalApplications method.


callbackLocalApplications (IEnumLocalApplicationsCallback Interface)

 Microsoft SDK for Java

callbackLocalApplications

This method of the IEnumLocalApplicationsCallback Interface is an application-defined callback function for the DirectPlayLobby.enumLocalApplications method.

Syntax

public void callbackLocalApplications(_Guid applicationGuid, String applicationName, IUnknown context);

Parameters

applicationGuid | A globally unique identifier of the application. being enumerated.
applicationName | The name of the application being enumerated.
context | The context passed from the enumLocalApplications call.


IEnumModesCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumModesCallback Interface

The IEnumModesCallback Interface of the com.ms.directX package is used with enumDisplayModes to set the callback function to be called for each display mode exposed by the hardware.

public interface IEnumModesCallback extends IUnknown
{
  // Methods
  public void callbackEnumModes(DDSurfaceDesc desc, IUnknown Ctxt);
}

Hierarchy

IUnknown
  |
  +--IEnumModesCallback


Methods (IEnumModesCallback Interface)

 Microsoft SDK for Java

IEnumModesCallback Interface Methods

The IEnumModesCallback Interface contains the following method:

callbackEnumModes is an application-defined callback procedure.


callbackEnumModes (IEnumModesCallback Interface)

 Microsoft SDK for Java

callbackEnumModes

This method of the IEnumModesCallback Interface is an application-defined callback procedure.

Syntax

public void callbackEnumModes(DDSurfaceDesc desc, IUnknown Ctxt);

Parameters

desc | A DDSurfaceDesc object that provides the monitor frequency and the mode that can be created. This data is read-only.
ctxt | Application-defined data that is passed to the callback function each time the function is called.


IEnumPlayersCallback2 Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumPlayersCallback2 Interface

The IEnumPlayersCallback2 Interface of the com.ms.directX package is used with the DirectPlay2.enumGroupPlayers, DirectPlay2.enumGroups, and DirectPlay2.enumPlayers methods to set the callback function to be called for each group or player.

public interface IEnumPlayersCallback2 extends IUnknown
{
  // Methods
  public void callbackEnumPlayers(int playerId, int playerType,
        String playerShortName, String playerLongName, int flags,
        IUnknown context);
}

Hierarchy

IUnknown
  |
  +--IEnumPlayersCallback2

You can use the DirectPlay2.stopEnumPlayers method to stop a player enumeration.


Methods (IEnumPlayersCallback2 Interface)

 Microsoft SDK for Java

IEnumPlayersCallback2 Interface Methods

The IEnumPlayersCallback2 Interface contains the following method:

callbackEnumPlayers is an application-defined callback procedure.


callbackEnumPlayers (IEnumPlayersCallback2 Interface)

 Microsoft SDK for Java

callbackEnumPlayers

This method of the IEnumPlayersCallback2 Interface is an application-defined callback procedure.

Syntax

public void callbackEnumPlayers(int playerId, int playerType, String playerShortName, String playerLongName, int flags, IUnknown context);

Parameters

playerId | ID of the player or group being enumerated.
playerType | The type of player, either DPPLAYERTYPE_GROUP or DPPLAYERTYPE_PLAYER.
playerShortName | The short name of the player.
playerLongName | The long name of the player.
flags | Specifies the flags that were passed to the enumGroups enumGroupPlayers, or enumPlayers, method.
context | The caller-defined context.


IEnumServiceProvidersCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumServiceProvidersCallback Interface

The IEnumServiceProvidersCallback Interface of the com.ms.directX package is used with the DirectPlay2.enumServiceProviders method to enumerate service providers installed on the system.

You can use the DirectPlay2.stopEnumServiceProviders method to stop a service provider enumeration.

public interface IEnumServiceProvidersCallback extends IUnknown
{
  // Methods
  public void callbackEnumServiceProviders(_Guid spGuid,
        String spName, int majorVer, int minorVer,
        IUnknown context);
}

Hierarchy

IUnknown
  |
  +--IEnumServiceProvidersCallback


Methods (IEnumServiceProvidersCallback Interface)

 Microsoft SDK for Java

IEnumServiceProvidersCallback Interface Methods

The IEnumServiceProvidersCallback Interface contains the following method:

callbackEnumServiceProviders is an application-defined callback method used to enumerate DirectPlay service providers installed on a system.


callbackEnumServiceProviders (IEnumServiceProvidersCallback Interface)

 Microsoft SDK for Java

callbackEnumServiceProviders

This method of the IEnumServiceProvidersCallback Interface is an application-defined callback method used to enumerate DirectPlay service providers installed on a system.

Syntax

public void callbackEnumServiceProviders(_Guid spGuid, String spName, int majorVer, int minorVer, IUnknown context);

Parameters

spGuid | The unique identifier of the Microsoft® DirectPlay® service provider.
spName | A string containing the driver description.
majorVer | The major version number of the driver.
minorVer | The minor version number of the driver.
context | An application-defined context.


IEnumSessionsCallback2 Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumSessionsCallback2 Interface

The IEnumSessionsCallback2 Interface of the com.ms.directX package is used with DirectPlay2.enumSessions to set the callback function to be called for each active session.

You must use the DirectPlay2.stopEnumSessions to stop a session enumeration, or the enumeration will continue infinitely.

public interface IEnumSessionsCallback2 extends IUnknown
{
  // Methods
  public void callbackEnumSessions(DPSessionDesc sessionDesc, _Guid
        instanceGuid, _Guid applicationGuid, String sessionName,
        String password, int[] timeOut, int flags, IUnknown
        context);
}

Hierarchy

IUnknown
  |
  +--IEnumSessionsCallback2


Methods (IEnumSessionsCallback2 Interface)

 Microsoft SDK for Java

IEnumSessionsCallback2 Interface Methods

The IEnumSessionsCallback2 Interface contains the following method:

callbackEnumSessions enumerates sessions.


callbackEnumSessions (IEnumSessionsCallback2 Interface)

 Microsoft SDK for Java

callbackEnumSessions

This method of the IEnumSessionsCallback2 Interface enumerates sessions. This is an application-defined callback procedure.

Syntax

public void callbackEnumSessions(DPSessionDesc sessionDesc, _Guid instanceGuid, _Guid applicationGuid, String sessionName, String password, int[] timeOut, int flags, IUnknown context);

Parameters

sessionDesc | A DPSessionDesc object describing the enumerated session. This parameter will be set to null if the enumeration has timed out.
instanceGuid | A globally unique identifier (GUID) of the session instance.
applicationGuid | The GUID for the application running in the session instance. It uniquely identifies the application so that Microsoft® DirectPlay® connects only to other computers running the same application. This member can be set to GUID_NULL to enumerate sessions for any application.
sessionName | The Unicode string containing the name of the session. Use these members only if the IDirectPlay2 interface is in use.
password | The Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use.
timeOut | The array variable that contains the current time-out value. This can be reset when the DPESC_TIMEDOUT flag is returned if you want to wait longer for sessions to reply.
flags | Typically, this flag is set to zero. DPESC_TIMEDOUT The enumeration has timed out. Reset timeOut and return 1 to continue, or 0 to stop the enumeration.
context | The caller-defined context.


IEnumSoundDriversCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumSoundDriversCallback Interface

This is an interface of the com.ms.directX package.

public interface IEnumSoundDriversCallback extends IUnknown
{
  // Methods
  public void callbackEnumSoundDrivers(_Guid guid,
        String description, String moduleName, IUnknown context);
}

Hierarchy

IUnknown
  |
  +--IEnumSoundDriversCallback


Methods (IEnumSoundDriversCallback Interface)

 Microsoft SDK for Java

IEnumSoundDriversCallback Interface Methods

The IEnumSoundDriversCallback Interface contains the following method:

callbackEnumSoundDrivers enumerates Microsoft® DirectSound® drivers.


callbackEnumSoundDrivers (IEnumSoundDriversCallback Interface)

 Microsoft SDK for Java

callbackEnumSoundDrivers

This method of the IEnumSoundDriversCallback Interface enumerates Microsoft® DirectSound® drivers. This callback function is application-defined.

Syntax

public void callbackEnumSoundDrivers(_Guid guid, String description, String moduleName, IUnknown context);

Parameters

guid | The globally unique identifier (GUID) that identifies the DirectSound driver being enumerated. This value can be passed to the DirectSound.initialize function to create a DirectSound object for that driver.
description | A null-terminated string that provides a textual description of the DirectSound device.
moduleName | A null-terminated string that specifies the module name of the DirectSound driver corresponding to this device.
context | Application-defined data that is passed to each callback function.


IEnumSurfacesCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumSurfacesCallback Interface

This is an interface of the com.ms.directX package is used with DirectDraw.enumSurfaces and DirectDrawSurface.enumAttachedSurfaces to set the callback function to be called for each specified surface.

public interface IEnumSurfacesCallback extends IUnknown
{
  // Methods
  public void callbackEnumSurfaces(DirectDrawSurface f,
        DDSurfaceDesc surfDesc, IUnknown ctxt);
}

See Also

com.ms.directX.DirectDraw, com.ms.directX.DirectDrawSurface

Hierarchy

IUnknown
  |
  +--IEnumSurfacesCallback


Methods (IEnumSurfacesCallback Interface)

 Microsoft SDK for Java

IEnumSurfacesCallback Interface Methods

The IEnumSurfacesCallback Interface contains the following method:

callbackEnumSurfaces enumerates surfaces.


callbackEnumSurfaces (IEnumSurfacesCallback Interface)

 Microsoft SDK for Java

callbackEnumSurfaces

This method of the IEnumSurfacesCallback Interface enumerates surfaces.

Syntax

public void callbackEnumSurfaces(DirectDrawSurface f, DDSurfaceDesc surfDesc, IUnknown ctxt);

Parameters

f | The DirectDrawSurface object.
surfDesc | A DDSurfaceDesc object that describes the surface.
ctxt | An application-defined structure that will be passed to the callback function each time the function is called.


IEnumTextureFormatsCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumTextureFormatsCallback Interface

The IEnumTextureFormatsCallback Interface of the com.ms.directX package is used with Direct3dDevice.enumTextureFormats to set the callback function to be called for each texture format for a device.

public interface IEnumTextureFormatsCallback extends IUnknown
{
  // Methods
  public void callbackEnumTextureFormats(DDSurfaceDesc surfDesc,
        IUnknown userArg);
}

Hierarchy

IUnknown
  |
  +--IEnumTextureFormatsCallback


Methods (IEnumTextureFormatsCallback Interface)

 Microsoft SDK for Java

IEnumTextureFormatsCallback Interface Methods

The IEnumTextureFormatsCallback Interface contains the following method:

callbackEnumTextureFormats is a prototype definition for the callback function to enumerate texture formats.


callbackEnumTextureFormats (IEnumTextureFormatsCallback Interface)

 Microsoft SDK for Java

callbackEnumTextureFormats

This method of the IEnumTextureFormatsCallback Interface is a prototype definition for the callback function to enumerate texture formats.

Syntax

public void callbackEnumTextureFormats(DDSurfaceDesc surfDesc, IUnknown userArg);

Parameters

surfDesc | A DDSurfaceDesc object containing the texture information.
userArg | An application-defined data passed to this callback function.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


IEnumZOrdersCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IEnumZOrdersCallback Interface

The IEnumZOrdersCallback Interface of the com.ms.directX package is used with DirectDrawSurface.enumOverlayZOrders to set the callback function to be called for each overlay on the given surface.

public interface IEnumZOrdersCallback extends IUnknown
{
  // Methods
  public void callbackEnumOverlayZOrders(DirectDrawSurface f,
        IUnknown context);
}

Hierarchy

IUnknown
  |
  +--IEnumZOrdersCallback


Methods (IEnumZOrdersCallback Interface)

 Microsoft SDK for Java

IEnumZOrdersCallback Interface Methods

The IEnumZOrdersCallback Interface contains the following method:

callbackEnumOverlayZOrders enumerates overlays for the surface.


callbackEnumOverlayZOrders (IEnumZOrdersCallback Interface)

 Microsoft SDK for Java

callbackEnumOverlayZOrders

This method of the IEnumZOrdersCallback Interface enumerates overlays for the surface.

Syntax

public void callbackEnumOverlayZOrders(DirectDrawSurface f, IUnknown context);

Parameters

f | The surface being overlaid on this surface.
context | An application-defined structure that will be passed to the callback function each time the function is called.


IframeMoveCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IFrameMoveCallback Interface

The IFrameMoveCallback Interface of the com.ms.directX package is used with Direct3dRMFrame.addMoveCallback and Direct3dRMFrame.deleteMoveCallback to set or remove the callback function to be called when a frame is moved.

public interface IFrameMoveCallback extends IUnknown
{
  // Methods
  public void callbackFrameMove(Direct3dRMFrame f, IUnknown pArgs,
        float delta);
}

Hierarchy

IUnknown
  |
  +--IFrameMoveCallback


Methods (IFrameMoveCallback Interface)

 Microsoft SDK for Java

IFrameMoveCallback Interface Methods

The IFrameMoveCallback Interface contains the following method:

callbackFrameMove enables an application to apply customized algorithms when a frame is moved or updated.


callbackFrameMove (IFrameMoveCallback Interface)

 Microsoft SDK for Java

callbackFrameMove

This method of the IFrameMoveCallback Interface enables an application to apply customized algorithms when a frame is moved or updated. You can use this callback function to compensate for changing frame rates. This callback function is application-defined.

Syntax

public void callbackFrameMove(Direct3dRMFrame f, IUnknown pArgs, float delta);

Parameters

f | The Direct3dRMFrame object that is being moved.
pArgs | Application-defined data passed to this callback function.
delta | The amount of change to apply to the movement. There are two components to the change in position of a frame: linear and rotational. The change in each component is equal to velocity_of_component x delta. Although either or both of these velocities can be set relative to any frame, the system automatically converts them to velocities relative to the parent frame for the purpose of applying time deltas.

Remarks

Your application can synthesize the acceleration of a frame relative to its parent frame. To do so, on each tick, your application should set the velocity of the child frame, relative to itself to (a units per tick) x 1 tick, where a is the required acceleration. This is equal to a x delta units per tick. Internally, a x delta units per tick relative to the child frame is converted to (v + (a x delta )) units per tick relative to the parent frame, where v is the current velocity of the child relative to the parent.

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first and then calls their callback functions in the order in which they were created.


ILoadCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

ILoadCallback Interface

The ILoadCallback Interface of the com.ms.directX package is used with Direct3dRM.loadFromFileByPos to set the callback function to be called when an object is loaded.

public interface ILoadCallback extends IUnknown
{
  // Methods
  public void callbackLoad(Direct3dRM obj, _Guid id, IUnknown args);
}

Hierarchy

IUnknown
  |
  +--ILoadCallback


Methods (ILoadCallback Interface)

 Microsoft SDK for Java

ILoadCallback Interface Methods

The ILoadCallback Interface contains the following method:

callbackLoad loads objects.


callbackLoad (ILoadCallback Interface)

 Microsoft SDK for Java

callbackLoad

This method of the ILoadCallback Interface loads objects. This callback function is application-defined.

Syntax

public void callbackLoad(Direct3dRM obj, _Guid id, IUnknown args);

Parameters

obj | The Direct3dRM object being loaded.
id | The globally unique identifier (GUID) of the object being loaded.
args | Application-defined data passed to this callback function.

Remarks

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


ILoadTextureCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

ILoadTextureCallback Interface

The ILoadTextureCallback Interface of the com.ms.directX package is used with methods, such as Direct3dRM.loadFromFileByPos to set the callback function to be called when loading a texture.

public interface ILoadTextureCallback extends IUnknown
{
  // Methods
  public Direct3dRMTexture callbackLoadTexture(String text_name,
        IUnknown pArgs);
}

See Also

com.ms.directX.Direct3dRM, com.ms.directX.Direct3dRMAnimation, com.ms.directX.Direct3dRMFrame, com.ms.directX.Direct3dRMMeshBuilder

Hierarchy

IUnknown
  |
  +--ILoadTextureCallback


Methods (ILoadTextureCallback Interface)

 Microsoft SDK for Java

ILoadTextureCallback Interface Methods

The ILoadTextureCallback Interface contains the following method:

callbackLoadTexture loads texture maps from a file.


callbackLoadTexture (ILoadTextureCallback Interface)

 Microsoft SDK for Java

callbackLoadTexture

This method of the ILoadTextureCallback Interface loads texture maps from a file. This callback function is application-defined.

Syntax

public Direct3dRMTexture callbackLoadTexture(String text_name, IUnknown pArgs);

Return Value

Returns the Direct3dRMTexture object if successful; otherwise, returns null.

Parameters

text_name | The name of the texture.
pArgs | The application-specific data.

Remarks

Applications can use this callback function to implement support for textures that are not in the Microsoft® Windows® bitmap (.bmp) or Portable Pixmap (.ppm) P6 format.

When determining the order in which to call callback functions, the system searches the objects highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


IUserVisualCallback Interface (com.ms.directX Package)

 Microsoft SDK for Java

IUserVisualCallback Interface

The IUserVisualCallback Interface of the com.ms.directX package is used with Direct3dRM.createUserVisual and Direct3dRMUserVisual.init to set the callback function to be called to render an application-defined visual.

public interface IUserVisualCallback extends IUnknown
{
  // Methods
  public void callbackUserVisual(Direct3dRMUserVisual uv,
        IUnknown arg, int[] r, Direct3dRMDevice d,
        Direct3dRMViewport v);
}

Hierarchy

IUnknown
  |
  +--IUserVisualCallback


Methods (IUserVisualCallback Interface)

 Microsoft SDK for Java

IUserVisualCallback Interface Methods

The IUserVisualCallback Interface contains the following method:

callbackUserVisual alerts an application that supplies user-visual objects that it should execute the execute buffer.


callbackUserVisual (IUserVisualCallback Interface)

 Microsoft SDK for Java

callbackUserVisual

This method of the IUserVisualCallback Interface alerts an application that supplies user-visual objects that it should execute the execute buffer. This function is application-defined.

Syntax

public void callbackUserVisual(Direct3dRMUserVisual uv, IUnknown arg, int[] r, Direct3dRMDevice d, Direct3dRMViewport v);

Parameters

uv | The Direct3dRMUserVisual object.
Arg | Application-defined data passed to this callback function.
r An array variable that contains a value of user visual reason type:

D3DRMUSERVISUAL_CANSEE

The application should set this parameter to TRUE if the user-visual object is visible in the viewport. In this case, the application uses the device specified in the v parameter.

D3DRMUSERVISUAL_RENDER

The application should render the user-visual element. In this case, the application uses the device specified in the d parameter.
d | A Direct3dRMDevice object used to render the Direct3dRMUserVisual object.
v | A Direct3dRMViewport object used to determine whether the Direct3dRMUserVisual object is visible.

Remarks

When determining the order in which to call callback functions, the system searches the objects that are highest in the hierarchy first, and then calls their callback functions in the order in which they were created.


com.ms.dll Package Overview

Microsoft Packages Overview

The com.ms.dll package helps you link your Java code with dynamic-link libraries (DLLs). You can use the methods in the com.ms.dll package along with Microsoft® J/Direct™ technology to call functions located in Win32 DLLs, OLE API functions, and third-party DLLs. This overview discusses some of the most frequently used classes of the package.

This package contains the following:

Classes

Hierarchy

The DllLib class offers a variety of methods that are used in conjunction with the @dll.import directive. The ptrToXXX methods can be used to treat a parameter as a LPTSTR. Several copy methods, as well as read and write methods, allow your Java code to read and write data from raw pointers. The ptrToStruct method provides another way to read and write data through a raw pointer by wrapping the raw pointer in an instance of a class that was declared with the @dll.struct directive. DllLib also contains methods that copy strings to native memory blocks, convert native strings to Java String objects, and free and allocate native memory blocks.

You can extend the Callback class to create Callback objects in Java. Your derived Callback class must contain one non-static method whose name is callback (all lowercase). The callback method has limited return types, and all the parameters must be of type int. After the Callback class has been created, you can use the @dll.import compiler directive to call a Win32 function that takes a Callback as a parameter.

The Root class provides a way for you to protect a Java object from garbage collection by creating a 32-bit root handle for the object. This is helpful when you have created a Callback object that will be used across function calls. By wrapping the Callback inside a root handle, you can keep the Callback from being reclaimed by garbage collection. When you no longer need the Callback, you should explicitly free its root handle using the dll.Root.free method.

You can use the Win32Exception class to create objects that contain error descriptions for error codes set by Win32 functions. When you call Win32 functions using the @dll.import compiler directive, you can use the setLastError modifier to tell the VM to capture the error code immediately after the function is called. You can then use the dll.dllLib.getLastWin32Error method to obtain the error code, and you can wrap it in a Java Win32Exception object that describes the error.

See Also

Java/Win32 Integration with J/Direct Compiler Directives Reference


Classes (com.ms.dll Package)

 Microsoft SDK for Java

com.ms.dll Package Classes

The com.ms.dll package contains the following classes:

ArrayWithOffset class is used to encapsulate a pointer into an array, for use with Microsoft® J/Direct™ methods.

Callback class creates a native callback for Microsoft® Win32® APIs such as EnumWindows.

DllLib class contains methods for linking to dynamic-link libraries (DLLs).

ParameterCountMismatchError class represents objects that contain the number of parameters expected and the number of objects actually passed to a method.

Root class allows you to create an opaque 32-bit root handle to any Java object.

Win32Exception class provides access to objects that contain error codes and error descriptions for errors set by Microsoft® Win32® functions.


Hierarchy (com.ms.dll Package)

 Microsoft SDK for Java

com.ms.dll Package Hierarchy

The com.ms.dll package has the following hierarchy:

Object
  |
  +--ArrayWithOffset
  |
  +--Callback
  |
  +--DllLib
  |
  +--Root
  |
RuntimeException
  |
  +--ParameterCountMismatchError
  |
  +--Win32Exception


ArrayWithOffset Class (com.ms.dll Package)

 Microsoft SDK for Java

ArrayWithOffset Class

The ArrayWithOffset class of the com.ms.dll package is used to encapsulate a pointer into an array for use with J/Direct methods.

public final class ArrayWithOffset
{
  // Constructors
  public ArrayWithOffset(Object objArray, int nOffsetBytes);
  public ArrayWithOffset(byte[] array, int nOffsetBytes);
  public ArrayWithOffset(short[] array, int nOffsetBytes);
  public ArrayWithOffset(int[] array, int nOffsetBytes);
  public ArrayWithOffset(long[] array, int nOffsetBytes);
  public ArrayWithOffset(float[] array, int nOffsetBytes);
  public ArrayWithOffset(double[] array, int nOffsetBytes);
  public ArrayWithOffset(char[] array, int nOffsetBytes);
  public ArrayWithOffset(boolean[] array, int nOffsetBytes);

  // Methods
  public Object getArray();
  public int getOffset();
}

When used as a parameter to a J/Direct method, an ArrayWithOffset instance is marshaled to a pointer to the given byte offset in the given array. No bounds checks are performed on the offset given in the constructor. Instances of this class are immutable; once created, they cannot be modified.


Constructors (ArrayWithOffset Class)

 Microsoft SDK for Java

ArrayWithOffset Class Constructors

The ArrayWithOffset class contains the following constructors:

ArrayWithOffset(Object objArray, int nOffsetBytes)
ArrayWithOffset(byte[] array, int nOffsetBytes)
ArrayWithOffset(short[] array, int nOffsetBytes)
ArrayWithOffset(int[] array, int nOffsetBytes)
ArrayWithOffset(long[] array, int nOffsetBytes)
ArrayWithOffset(float[] array, int nOffsetBytes)
ArrayWithOffset(double[] array, int nOffsetBytes)
ArrayWithOffset(char[] array, int nOffsetBytes)
ArrayWithOffset(boolean[] array, int nOffsetBytes)

ArrayWithOffset(Object objArray, int nOffsetBytes)

Generic constructor that expects an array of primitive type and an offset in bytes.

Syntax

public ArrayWithOffset(Object objArray, int nOffsetBytes);

Parameters

objArray | An array of primitive data type.
nOffsetBytes | Offset in bytes.

ArrayWithOffset(byte[] array, int nOffsetBytes)

Constructor that expects a byte array and an offset in bytes.

Syntax

public ArrayWithOffset(byte[] array, int nOffsetBytes);

Parameters

array | A byte array.
nOffsetBytes | Offset in bytes.

ArrayWithOffset(short[] array, int nOffsetBytes)

Constructor that expects a short array and an offset in bytes.

Syntax

public ArrayWithOffset(short[] array, int nOffsetBytes);

Parameters

array | A short array.
nOffsetBytes | Offset in bytes.

ArrayWithOffset(int[] array, int nOffsetBytes)

Constructor that expects an integer array and an offset in bytes.

Syntax

public ArrayWithOffset(int[] array, int nOffsetBytes);

Parameters

array | An integer array.
nOffsetBytes | Offset in bytes.

ArrayWithOffset(long[] array, int nOffsetBytes)

Constructor that expects a long array and an offset in bytes.

Syntax

public ArrayWithOffset(long[] array, int nOffsetBytes);

Parameters

array | A long array.
nOffsetBytes | Offset in bytes.

ArrayWithOffset(float[] array, int nOffsetBytes)

Constructor that expects a float array and an offset in bytes.

Syntax

public ArrayWithOffset(float[] array, int nOffsetBytes);

Parameters

array | A float array.
nOffsetBytes | Offset in bytes.

ArrayWithOffset(double[] array, int nOffsetBytes)

Constructor that expects a double array and an offset in bytes.

Syntax

public ArrayWithOffset(double[] array, int nOffsetBytes);

Parameters

array | A double array.
nOffsetBytes | Offset in bytes.

ArrayWithOffset(char[] array, int nOffsetBytes)

Constructor that expects a character array and an offset in bytes.

Syntax

public ArrayWithOffset(char[] array, int nOffsetBytes);

Parameters

array | A char array.
nOffsetBytes | Offset in bytes.

ArrayWithOffset(boolean[] array, int nOffsetBytes)

Constructor that expects a Boolean array and an offset in bytes.

Syntax

public ArrayWithOffset(boolean[] array, int nOffsetBytes);

Parameters

array | A Boolean array.
nOffsetBytes | Offset in bytes.


Methods (ArrayWithOffset Class)

 Microsoft SDK for Java

ArrayWithOffset Class Methods

The ArrayWithOffset class contains the following methods:

getArray returns the wrapped array.
getOffset returns the offset in bytes.


getArray (ArrayWithOffset Class)

 Microsoft SDK for Java

getArray

This method of the ArrayWithOffset class returns the wrapped array.

Syntax

public Object getArray();

Return Value

m_objArray, the wrapped array.


getOffset (ArrayWithOffset Class)

 Microsoft SDK for Java

getOffset

This method of the ArrayWithOffset class returns the offset in bytes.

Syntax

public int getOffset();

Return Value

m_nOffsetBytes, the offset in bytes.


Callback Class (com.ms.dll Package)

 Microsoft SDK for Java

Callback Class

The Callback class of the com.ms.dll package creates a native callback for Win32 APIs such as EnumWindows.

public class Callback
{
  // Constructors
  protected Callback();

  // Methods
  protected void finalize();
}

The Callback class can only be instantiated by a subclass constructor. Therefore, you must extend this class to use it. Each subclass must include a non-static method named callback, whose parameters are all integers and whose return type is either int or void. If a method that meets these requirements cannot be found anywhere in the inheritance hierarchy, construction will fail.

The callback method that is declared in a subclass creates a native callback that accepts as many 4-byte parameters as there are integer parameters to the callback method. The native callback returns a single 4-byte value, and that is the value returned by the callback method. If the callback method throws an uncaught Java exception, a zero is returned to the callback method's native caller.

To implement callbacks that take non-integer arguments such as strings or structures, you need to convert the integer argument (which typically corresponds to a native pointer) to a convenient Java type.

The Callback class is generally used for callbacks that exist only during the call of a single API. However, this class can also be used for persistent callbacks as long as you ensure that there is at least one Java reference to the Callback object for as long as the native code needs the callback.

For examples that show how you can declare and invoke DLL functions that take callbacks, see Callbacks.


Constructors (Callback Class)

 Microsoft SDK for Java

Callback Class Constructors

The Callback class contains the following constructor:

Callback()

Creates a Callback object. Because you must extend the Callback class to instantiate it, this constructor is used only by subclass constructors.

Syntax

protected Callback();


Methods (Callback Class)

 Microsoft SDK for Java

Callback class Methods

The Callback class contains the following method:

finalize performs cleanup before garbage collection.


finalize (Callback Class)

 Microsoft SDK for Java

finalize

This method of the Callback class performs cleanup before garbage collection.

Syntax

protected void finalize();


DllLib Class (com.ms.dll Package)

 Microsoft SDK for Java

DllLib Class

The DllLib class of the com.ms.dll package contains methods for linking to dynamic-link libraries (DLLs).

public class DllLib
{
  // Fields
  public static final int systemDefaultCharSize;

  // Methods
  public static int addrOf(int root);
  public static int addrOfPinnedObject(int nHandleIndex);
  public static int allocCoTaskMem(int cb);
  public static int allocHGlobal(int cb);
  public static void copy(byte jasrc[],
    int elemidx, int pdst, int nelems);
  public static void copy(char jasrc[],
    int elemidx, int pdst, int nelems);
  public static void copy(short jasrc[],
    int elemidx, int pdst, int nelems);
  public static void copy(int jasrc[],
    int elemidx, int pdst, int nelems);
  public static void copy(long jasrc[],
    int elemidx, int pdst, int nelems);
  public static void copy(float jasrc[],
    int elemidx, int pdst, int nelems);
  public static void copy(double jasrc[],
    int elemidx, int pdst, int nelems);
  public static void copy(Object jasrc,
    int ofs, int pdst, int cb);
  public static void copy(int psrc, byte jadst[], int elemidx,
    int nelems);
  public static void copy(int psrc, char jadst[], int elemidx,
    int nelems);
  public static void copy(int psrc, short jadst[], int elemidx,
    int nelems);
  public static void copy(int psrc, int jadst[], int elemidx,
    int nelems);
  public static void copy(int psrc, long jadst[], int elemidx,
    int nelems);
  public static void copy(int psrc, float jadst[], int elemidx,
    int nelems);
  public static void copy(int psrc, double jadst[], int elemidx,
    int nelems);
  public static void copy(int psrc, Object jadst, int ofs, int cb);
  public static void copyUni(int psrc, char jadst[], int elemidx,
    int nelems);
  public static void freeCoTaskMem(int ptr);
  public static void freeHGlobal(int hglobal);
  public static final int getLastWin32Error();
  public static void freePinnedHandle(int nHandleIndex);
  public static int getPinnedHandle(Object obj);
  public static ObjectgetPinnedObject(int nHandleIndex);
  public static boolean isStruct(Class structCls);
  public native static boolean isStruct(Field structField);
  public static int numParamBytes(Method m);
  public native static int offsetOf(Field structField);
  public static int offsetOf(Class structCls,
    String fieldName) throws SecurityException;
  public static native void prelink(Method method);
  public static void prelinkAll(Class cls);
  public static native void propagateStructFields(Object structObj,
    boolean fromNative);
  public static String ptrToString(int ptr);
  public static String ptrToStringAnsi(int ptr);
  public static String ptrToStringUni(int ptr);
  public static native Object ptrToStruct(Class structClass, int ptr,
    boolean fFreeIndirectNativeMemory);
  public static native byte read1(Object ptr, int ofs);
  public static native byte read1(int ptr, int ofs);
  public static byte read1(int ptr);
  public static native short read2(Object ptr, int ofs);
  public static native short read2(int ptr, int ofs);
  public static short read2(int ptr);
  public static native int read4(Object ptr, int ofs);
  public static native int read4(int ptr, int ofs);
  public static int read4(int ptr);
  public static native long read8(Object ptr, int ofs);
  public static native long read8(int ptr, int ofs);
  public static long read8(int ptr);
  public static native void release(Object o);
  public native static void resize(Object structObj, int newsize);
  public static int sizeOf(Class structCls);
  public native static int sizeOf(Object structObj);
  public static int stringToCoTaskMem(String s);
  public static int stringToCoTaskMemAnsi(String s);
  public static int stringToCoTaskMemUni(String s);
  public static int stringToHGlobal(String s);
  public static int stringToHGlobalAnsi(String s);
  public static int stringToHGlobalUni(String s);
  public static final void throwWin32Exception();
  public static native void write1(Object ptr, int ofs, byte val);
  public static native void write1(int ptr, int ofs, byte val);
  public static void write1(int ptr, byte val);
  public static native void write2(Object ptr, int ofs, short val);
  public static native void write2(int ptr, int ofs, short val);
  public static void write2(int ptr, short val);
  public static native void write2(Object ptr, int ofs, char val);
  public static native void write2(int ptr, int ofs, char val);
  public static void write2(int ptr, char val);
  public static native void write4(Object ptr, int ofs, int val);
  public static native void write4(int ptr, int ofs, int val);
  public static void write4(int ptr, int val);
  public static native void write8(Object ptr, int ofs, long val);
  public static native void write8(int ptr, int ofs, long val);
  public static void write8(int ptr, long val);
}

All methods in the DllLib class are static; therefore, you do not need to instantiate this class to use its methods. The methods and fields of the DllLib class provide support for J/Direct technology.

J/Direct allows you to specify the auto modifier with the @dll.import directive to call the optimal version of a DLL function, depending on the platform you are using. To find out what version is optimal for your platform, you can examine the systemDefaultCharSize field. This field is set to 1 for ANSI system, and 2 for Unicode systems.

There are several DllLib methods that help you read and write from raw pointers returned by DLL functions. You can use the ptrToStruct method, which casts a raw pointer to a structure, to cast the raw pointer to a reference to a class declared with @dll.struct. For an example that illustrates this technique, see Raw Pointers.

There are other situations where the ptrToStruct method can be helpful. Because there is no direct support for pointers inside structures, you could represent a structure with an embedded pointer by declaring the pointer field as type int and calling DLL functions to allocate the memory. Then you can call ptrToStruct to map the memory blocks onto @dll.struct classes so that you can initialize the blocks.

The DllLib methods ptrToStringAnsi, ptrToStringUni, and ptrToString are used to convert a string to a java.lang.String object when you want to treat a raw pointer as a pointer to a string. The following example shows how you can interpret a raw pointer as a pointer to a Unicode string:

import com.ms.dll.*;

int rawPtr = ...;  // value of rawPtr is returned by a DLL function
String s = DllLib.ptrToStringUni(rawPtr);

The addrOf method can be used to get the address of a callback. For instance, when you want to embed a callback inside a structure, you would call the com.ms.dll.Root.alloc method to wrap the Callback in a root handle. Next, you would pass the root handle to the addrOf method to obtain native address of the callback. Then, you can store the address as an integer.

The getLastWin32Error method helps you obtain the error code set by a DLL function. For an example that shows how to do this, see Obtaining the Error Code Set By a DLL Function.

The copy methods in DllLib allow you to copy data between various types of Java arrays and raw pointers. You could use these methods to read or write data from raw pointers returned by DLL functions.


Methods (DllLib Class)

 Microsoft SDK for Java

DllLib Class Methods

The DllLib class contains the following methods:

addrOf returns the address of a native structure wrapped by an @dll.struct object.
addrOfPinnedObject returns the address of the object's data while an object is pinned.
allocCoTaskMem allocates a native memory block by invoking the Win32 function CoTaskMemAlloc.
allocHGlobal allocates a native memory block using GlobalAlloc (GMEM_FIXED).
copy copies a number of bytes from a Java array to the destination indicated by a raw native pointer.
copyUni copies a number of characters to a Java array from the source indicated by a raw native pointer.
freeCoTaskMem frees a native memory block by invoking the Win32 function CoTaskMemFree.
freeHGlobal frees a native memory block by invoking the Win32 function GlobalFree.
freePinnedHandle frees a previously-allocated pinned handle.
getLastWin32Error returns the Microsoft® Win32® error code set by the last DLL-imported method (declared with the setLastError modifier) invoked on the current thread.
getPinnedHandle pins an object.
getPinnedObject retrieves the object that is encapsulated by a pinned handle.
isStruct determines whether a class represents a native structure.
numParamBytes prelinks the specified method and returns the number of bytes of memory required to store the method's parameters.
offsetOf returns the offset (measured in bytes) of a member of a native structure.
prelink preloads the native library and performs a type analysis on an @dll.import method to ensure that the types are compatible with DLL calling.
prelinkAll calls the prelink method on all methods of a class.
propagateStructFields propagates the fields from the native memory block to the Java object or from the Java object to the native memory block.
ptrToString converts a native string to a java.lang.String object.
ptrToStringAnsi converts a native string in ANSI format to a java.lang.String object.
ptrToStringUni converts a native string in Unicode format to a java.lang.String object.
ptrToStruct maps a raw pointer onto a structure.
read1 reads one byte of data from the memory location that is specified by a base address and an offset.
read2 reads two bytes of data from the memory location that is specified by a base address and an offset.
read4 reads four bytes of data from the memory location that is specified by a base address and an offset.
read8 reads eight bytes of data from the memory location that is specified by a base address and an offset.
release frees the native memory associated with an object declared using the @dll.struct compiler directive, if that memory would normally have been released by garbage collection.
resize reallocates the native memory block represented by an object declared using the @dll.struct directive.
sizeOf returns the size in bytes of the native structure represented by the specified class.
stringToCoTaskMem copies a string into a native memory block by using either ANSI or Unicode format depending on the auto mode setting.
stringToCoTaskMemAnsi copies a string into a native memory block in ANSI format.
stringToCoTaskMemUni copies a string into a native memory block in Unicode format.
stringToHGlobal copies a string into a native memory block, using either ANSI or Unicode format, depending on the auto mode setting.
stringToHGlobalAnsi copies a string into a native memory block in ANSI format.
stringToHGlobalUni copies a string into a native memory block in Unicode format.
throwWin32Exception throws a Win32Exception using the error code set by the last DLL-imported method (declared with the setLastError modifier) that is invoked on the current thread.
write1 writes one byte of data to the memory location that is specified by a base address and an offset.
write2 writes two bytes of data to the memory location that is specified by a base address and an offset.
write4 writes four bytes of data to the memory location that is specified by a base address and an offset.
write8 writes eight bytes of data to the memory location that is specified by a base address and an offset.


addrOf (DllLib Class)

 Microsoft SDK for Java

addrOf

This method of the DllLib class returns the address of a native structure wrapped by an @dll.struct object.

Syntax

public static int addrOf(int root);

Note To use this method, you must first call the Root.alloc method to wrap the object in a root handle. Then, pass the root handle to the addrOf method. This extra step is required because of the garbage-collected nature of Java. (If the addrOf method took an object directly, there would be nothing to prevent the object from being reclaimed by garbage collection before the returned address could be used.)

Return Value

Returns the address of the native structure.

Parameters

root A root handle obtained by calling Root.alloc.

Exceptions

SecurityException if called by an untrusted applet.


addrOfPinnedObject (DllLib Class)

 Microsoft SDK for Java

addrOfPinnedObject

This method of the DllLib class returns the address of the object's data while an object is pinned.

Syntax

public static int addrOfPinnedObject(int nHandleIndex);

While an address is pinned, it will not be reclaimed by the garbage collector and will not move in memory. You must specifically free this handle by calling freePinnedHandle. For performance reasons, objects should not be pinned for long periods of time. Generally, you will pin an array during some native I/O operation, and then unpin it.

Note Only single-dimension arrays of primitive types can be pinned.

Return Value

Returns the address of the object that is encapsulated by the given pinned handle.

Parameters

nHandleIndex A pinned handle that is obtained by calling getPinnedHandle.


allocCoTaskMem (DllLib Class)

 Microsoft SDK for Java

allocCoTaskMem

This method of the DllLib class allocates a native memory block by invoking the Win32 function CoTaskMemAlloc.

Syntax

public static int allocCoTaskMem(int cb);

Return Value

Returns a pointer to the allocated block.

Parameters

cb The required size of the memory block (in bytes).

Exceptions

OutOfMemoryError if allocation fails.


allocHGlobal (DllLib Class)

 Microsoft SDK for Java

allocHGlobal

This method of the DllLib class allocates a native memory block using GlobalAlloc (GMEM_FIXED).

Syntax

public static int allocHGlobal(int cb);

Return Value

Returns a pointer to the allocated block.

Parameters

cb The required size of the memory block (in bytes).

Exceptions

OutOfMemoryError if allocation fails.


copy (DllLib Class)

 Microsoft SDK for Java

copy

The copy method of the DllLib class contains the following signatures:

copy(byte jasrc[], int elemidx, int pdst, int nelems)
copy(char jasrc[], int elemidx, int pdst, int nelems)
copy(short jasrc[], int elemidx, int pdst, int nelems)
copy(int jasrc[], int elemidx, int pdst, int nelems)
copy(long jasrc[], int elemidx, int pdst, int nelems)
copy(float jasrc[], int elemidx, int pdst, int nelems)
copy(double jasrc[], int elemidx, int pdst, int nelems)
copy(Object jasrc, int ofs, int pdst, int cb)
copy(int psrc, byte jadst[], int elemidx, int nelems)
copy(int psrc, char jadst[], int elemidx, int nelems)
copy(int psrc, short jadst[], int elemidx, int nelems)
copy(int psrc, int jadst[], int elemidx, int nelems)
copy(int psrc, long jadst[], int elemidx, int nelems)
copy(int psrc, float jadst[], int elemidx, int nelems)
copy(int psrc, double jadst[], int elemidx, int nelems)
copy(int psrc, Object jadst, int ofs, int cb)

copy(byte jasrc[], int elemidx, int pdst, int nelems)

Copies a number of bytes from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(byte jasrc[], int elemidx, int pdst, int nelems);

Parameters

jasrc | The Java array to copy bytes from.
elemidx | The offset that indicates the location in the Java array where the first byte to be copied is located.
pdst | A raw pointer to the destination of the copy.
nelems | The number of bytes to copy.

copy(char jasrc[], int elemidx, int pdst, int nelems)

Copies a number of characters from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(char jasrc[], int elemidx, int pdst, int nelems);

Parameters

jasrc | The Java array to copy the characters from.
elemidx | The offset that indicates the location in the Java array where the first character to be copied is located.
pdst | A raw pointer to the destination of the copy.
nelems | The number of characters to copy.

copy(short jasrc[], int elemidx, int pdst, int nelems)

Copies a number of short integers from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(short jasrc[], int elemidx, int pdst, int nelems);

Parameters

jasrc | The Java array to copy the short integers from.
elemidx | The offset that indicates the location in the Java array where the first short integer to be copied is located.
pdst | A raw pointer to the destination of the copy.
nelems | The number of short integers to copy.

copy(int jasrc[], int elemidx, int pdst, int nelems)

Copies a number of integers from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(int jasrc[], int elemidx, int pdst, int nelems);

Parameters

jasrc | The Java array to copy the integers from.
elemidx | The offset that indicates the location in the Java array where the first integer to be copied is located.
pdst | A raw pointer to the destination of the copy.
nelems | The number of integers to copy.

copy(long jasrc[], int elemidx, int pdst, int nelems)

Copies a number of long integers from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(long jasrc[], int elemidx, int pdst, int nelems);

Parameters

jasrc | The Java array to copy the long integers from.
elemidx | The offset that indicates where in the Java array to copy the first long integer.
pdst | A raw pointer to the destination of the copy.
nelems | The number of long integers to copy.

copy(float jasrc[], int elemidx, int pdst, int nelems)

Copies 32-bit floating-point numbers from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(float jasrc[], int elemidx, int pdst, int nelems);

Parameters

jasrc | The Java array to copy the floating-point numbers from.
elemidx | The offset that indicates the location in the Java array where the first floating-point number to be copied is located.
pdst | A raw pointer to the destination of the copy.
nelems | The number of floating-point numbers to copy.

copy(double jasrc[], int elemidx, int pdst, int nelems)

Copies 64-bit floating-point numbers (doubles) from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(double jasrc[], int elemidx, int pdst, int nelems);

Parameters

jasrc | The Java array to copy the doubles from.
elemidx | The offset that indicates the location in the Java array where the first double to be copied is located.
pdst | A raw pointer to the destination of the copy.
nelems | The number of doubles to copy.

copy(Object jasrc, int ofs, int pdst, int cb)

Copies a native structure to the destination indicated by a raw native pointer. The Java object that represents the native structure must have been declared using the @dll.struct compiler directive.

Syntax

public static void copy(Object jasrc, int ofs, int pdst, int cb);

Parameters

jasrc | The native structure to copy from.
ofs | The offset that indicates where in the object the first byte to copy is located.
pdst | A raw pointer to the destination of the copy.
cb | The number of bytes to copy.

copy(int psrc, byte jadst[], int elemidx, int nelems)

Copies a number of bytes to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(int psrc, byte jadst[], int elemidx, int nelems);

Parameters

psrc | A raw pointer to the source of the copy.
jadst | The Java array to copy the bytes to.
elemidx | The offset that indicates the location in the Java array where the first byte is copied to.
nelems | The number of bytes to copy.

copy(int psrc, char jadst[], int elemidx, int nelems)

Copies a number of characters to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(int psrc, char jadst[], int elemidx, int nelems);

Parameters

psrc | A raw pointer to the source of the copy.
jadst | The Java array to copy the characters to.
elemidx | The offset that indicates the location in the Java array where the first character is copied to.
nelems | The number of characters to copy.

copy(int psrc, short jadst[], int elemidx, int nelems)

Copies a number of short integers to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(int psrc, short jadst[], int elemidx, int nelems);

Parameters

psrc | A raw pointer to the source of the copy.
jadst | The Java array to copy the short integers to.
elemidx | The offset that indicates the location in the Java array where the first short integer is copied to.
nelems | The number of short integers to copy.

copy(int psrc, int jadst[], int elemidx, int nelems)

Copies a number of integers to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(int psrc, int jadst[], int elemidx, int nelems);

Parameters

psrc | A raw pointer to the source of the copy.
jadst | The Java array to copy the integers to.
elemidx | The offset that indicates the location in the Java array where the first integer is copied to.
nelems | The number of integers to copy.

copy(int psrc, long jadst[], int elemidx, int nelems)

Copies a number of long integers to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(int psrc, long jadst[], int elemidx, int nelems);

Parameters

psrc | A raw pointer to the source of the copy.
jadst | The Java array to copy the long integers to.
elemidx | The offset that indicates the location in the Java array where the first long integer is copied to.
nelems | The number of long integers to copy.

copy(int psrc, float jadst[], int elemidx, int nelems)

Copies 32-bit floating-point numbers to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(int psrc, float jadst[], int elemidx, int nelems);

Parameters

psrc | A raw pointer to the source of the copy.
jadst | The Java array to copy the floats to.
elemidx | The offset that indicates the location in the Java array where the first floating-point number is copied to.
nelems | The number of floats to copy.

copy(int psrc, double jadst[], int elemidx, int nelems)

Copies 64-bit floating-point numbers (doubles) to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Syntax

public static void copy(int psrc, double jadst[], int elemidx, int nelems);

Parameters

psrc | A raw pointer to the source of the copy.
jadst | The Java array to copy the doubles to.
elemidx | The offset that indicates the location in the Java array where the first double is copied to.
nelems | The number of doubles to copy.

copy(int psrc, Object jadst, int ofs, int cb)

Copies a number of bytes to a native structure from the source indicated by a raw native pointer. The Java object that represents the native structure must be declared using the @dll.struct compiler directive.

Syntax

public static void copy(int psrc, Object jadst, int ofs, int cb);

Parameters

psrc | A raw pointer to the source of the copy.
jadst | The native structure to copy to.
ofs | The offset that indicates the location in the object where the first byte is copied to.
cb | The number of bytes to copy.


copyUni (DllLib Class)

 Microsoft SDK for Java

copyUni

This method of the DllLib class copies a number of characters to a Java array from the source indicated by a raw native pointer. The native string is assumed to be in Unicode format.

Syntax

public static void copyUni(int psrc, char jadst[], int elemidx, int nelems);

Parameters

psrc | A raw pointer to the source of the copy.
jadst | The Java array to copy the characters to.
elemidx | The offset that indicates the location in the Java array where the first character is copied to.
nelems | The number of characters to copy.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


freeCoTaskMem (DllLib Class)

 Microsoft SDK for Java

freeCoTaskMem

This method of the DllLib class frees a native memory block by invoking the Win32 function CoTaskMemFree. Any global memory handle that has a zero high-order word is safely ignored.

Syntax

public static void freeCoTaskMem(int ptr);

Parameters

ptr The memory block to free.


freeHGlobal (DllLib Class)

 Microsoft SDK for Java

freeHGlobal

This method of the DllLib class frees a native memory block by invoking the Win32 function GlobalFree. Any global memory handle that has a zero high-order word is safely ignored.

Syntax

public static void freeHGlobal(int hglobal);

Parameters

hglobal The global memory handle to free.


freePinnedHandle (DllLib Class)

 Microsoft SDK for Java

freePinnedHandle

This method of the DllLib class frees a previously-allocated pinned handle. This necessarily unpins the object (unless it has been pinned multiple times) and invalidates the address (if any) returned by addrOfPinnedHandle for this handle.

Syntax

public static void freePinnedHandle(int nHandleIndex);

Parameters

nHandleIndex The handle of the pinned object to free.


getLastWin32Error (DllLib Class)

 Microsoft SDK for Java

getLastWin32Error

This method of the DllLib class returns the Microsoft® Win32® error code set by the last DLL-imported method (declared with the setLastError modifier) invoked on the current thread.

Note Only DLL methods declared with the setLastError modifier can set error codes.

Syntax

public static final int getLastWin32Error();

Return Value

Returns the last saved Win32 error code.


getPinnedHandle (DllLib Class)

 Microsoft SDK for Java

getPinnedHandle

This method of the DllLib class pins an object. After pinning an object, you can legally call addrOfPinnedObject to obtain the address of the object's data. While an object is pinned, it will not be reclaimed by the garbage collector and will not move in memory.

You must specifically free this handle via freePinnedHandle. For performance reasons, objects should not be pinned for long periods of time. Generally, you will pin an array during some native I/O operation, and then unpin it.

Note Only single-dimension arrays of primitive types can be pinned.

Syntax

public static int getPinnedHandle(Object obj);

Return Value

Returns a handle to the pinned object.

Parameters

obj The object to be pinned.


getPinnedObject (DllLib Class)

 Microsoft SDK for Java

getPinnedObject

This method of the DllLib class retrieves the object that is encapsulated by a pinned handle.

Syntax

public static int getPinnedObject(int handle);

Return Value

Returns the object that is encapsulated by a pinned handle.

Parameters

handle The pinned handle of the object.


isStruct (DllLib Class)

 Microsoft SDK for Java

isStruct

The isStruct method of the DllLib class contains the following signatures:

isStruct(Class structCls)
isStruct(Field structField)

isStruct(Class structCls)

Determines whether a class represents a native structure.

Syntax

public static boolean isStruct(Class structCls);

Return Value

Returns true if the class represents a native structure; otherwise, returns false.

Parameters

structCls The class to examine.

isStruct(Field structField)

Determines whether a field represents a field in a native structure.

Syntax

public native static boolean isStruct(Field structField);

Return Value

Returns true if the field represents a field in a native structure; otherwise, returns false.

Parameters

structField The field to examine.


numParamBytes (DllLib Class)

 Microsoft SDK for Java

numParamBytes

This method of the DllLib class prelinks the specified method and returns the number of bytes of memory required to store the method's parameters.

Syntax

public static int numParamBytes(Method m);

Return Value

Returns the number of bytes of memory required to store the method's parameters.

Parameters

m The method to be prelinked.


offsetOf (DllLib Class)

 Microsoft SDK for Java

offsetOf

The offsetOf method of the DllLib class contains the following signatures:

offsetOf(Field structField)
offsetOf(Class structCls, String fieldName)

offsetOf(Field structField)

Returns the offset (measured in bytes) of a member of a native structure. The class, which is represented by structField.getClass, must have been declared using the @dll.struct compiler directive (or @com.struct).

Note The getClass method is from the java.lang.Object class.

Syntax

public native static int offsetOf(Field structField);

Return Value

Returns the size of the native structure (in bytes).

Parameters

structField The field to obtain the offset of.

offsetOf(Class structCls, String fieldName)

Returns the offset (measured in bytes) of a member of a native structure. The class, which is represented by structCls, must have been declared using the @dll.struct compiler directive (or @com.struct).

Syntax

public static int offsetOf(Class structCls, String fieldName) throws SecurityException;

Return Value

Returns the size of the native structure in bytes.

Parameters

structCls | The class declared by using @dll.struct.
fieldName | The name of the field to examine.

Exceptions

SecurityException if the caller lacks permissions to use the java.lang.reflect API.


prelink (DllLib Class)

 Microsoft SDK for Java

prelink

This method of the DllLib class preloads the native library and performs a type analysis on an @dll.import method to ensure that the types are compatible with DLL calling. If this method is called multiple times on the same method (or on a method that does not link to a DLL), the call is safely ignored.

Syntax

public static native void prelink(Method method);

Parameters

method The method to prelink.

Remarks

This work is normally performed on the first call to the @dll.import method. The prelink method can be used to force the type analysis to be done before the first call to the @dll.import method. This can help with performance tuning, debugging, or both.


prelinkAll (DllLib Class)

 Microsoft SDK for Java

prelinkAll

This method of the DllLib class calls the prelink method on all methods of a class. This method is provided primarily for debugging purposes because it can expose errors in DLL-linked methods.

Syntax

public static void prelinkAll(Class cls);

Parameters

cls The class to prelink.


propagateStructFields (DllLib Class)

 Microsoft SDK for Java

propagateStructFields

This method of the DllLib class propagates the fields from the native memory block to the Java object or from the Java object to the native memory block. The contents of some complex field types, such as arrays, are cached in garbage-collected memory, so writes or reads of these fields do not access the native memory block. By calling this method, the contents of the native memory block and the Java object are synchronized.

Syntax

public static native void propagateStructFields(Object structObj, boolean fromNative);

Parameters

structObj | The object declared using @dll.struct.
fromNative | The direction to propagate the fields.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


ptrToString (DllLib Class)

 Microsoft SDK for Java

ptrToString

This method of the DllLib class converts a native string to a java.lang.String object. The native string is assumed to be in ANSI format if the auto mode is ANSI; otherwise, Unicode format is assumed. A string that has the high-order word set to zero is allowed and is converted to null.

Syntax

public static String ptrToString(int ptr);

Return Value

Returns the Java string that represents the native string.

Parameters

ptr The native string to convert.


ptrToStringAnsi (DllLib Class)

 Microsoft SDK for Java

ptrToStringAnsi

This method of the DllLib class converts a native string in ANSI format to a java.lang.String object. A string that has the high-order word set to zero is legal and is converted to null.

Syntax

public static String ptrToStringAnsi(int ptr);

Return Value

Returns the Java string that represents the native string.

Parameters

ptr The string pointer to convert.


ptrToStringUni (DllLib Class)

 Microsoft SDK for Java

ptrToStringUni

This method of the DllLib class converts a native string in Unicode format to a java.lang.String object. A string that has the high-order word set to zero is legal and is converted to null.

Syntax

public static String ptrToStringUni(int ptr);

Return Value

Returns the Java string that represents the native string.

Parameters

ptr The string pointer to convert.


ptrToStruct (DllLib Class)

 Microsoft SDK for Java

ptrToStruct

This method of the DllLib class maps a raw pointer onto a structure. This method simulates a C-style cast of an arbitrary pointer to a structure.

Syntax

public static native Object ptrToStruct(Class structClass, int ptr, boolean fFreeIndirectNativeMemory);

Return Value

Returns an instance of structClass.

Parameters

structClass | The structure to map the raw pointer to. This class must have been declared using @dll.struct.
ptr | The raw pointer to be mapped.
fFreeIndirectNativeMemory | If true, the native memory used for any reference fields (strings, interfaces, and so on) are released appropriately.

Note The ptrToStruct method was added as of versions 2925 through 3167 of the Microsoft virtual machine.


read1 (DllLib Class)

 Microsoft SDK for Java

read1

The read1 method of the DllLib class contains the following signatures:

read1(Object ptr, int ofs)
read1(int ptr, int ofs)
read1(int ptr)

read1(Object ptr, int ofs)

Reads one byte of data from the memory location that is specified by a base address and an offset.

Syntax

public static native byte read1(Object ptr, int ofs);

Return Value

Returns the byte that is read.

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.

read1(int ptr, int ofs)

Reads one byte of data from the memory location that is specified by a base address and an offset.

Syntax

public static native byte read1(int ptr, int ofs);

Return Value

Returns the byte that is read.

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.

read1(int ptr)

Reads a byte from a specified memory location.

Syntax

public static byte read1(int ptr);

Return Value

Returns the byte that is read.

Parameters

ptr The address in memory where the byte to be read is located.


read2 (DllLib Class)

 Microsoft SDK for Java

read2

The read2 method of the DllLib class contains the following signatures:

read2(Object ptr, int ofs)
read2(int ptr, int ofs)
read2(int ptr)

read2(Object ptr, int ofs)

Reads two bytes of data from the memory location that is specified by a base address and an offset.

Syntax

public static native short read2(Object ptr, int ofs);

Return Value

Returns the bytes that are read.

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.

read2(int ptr, int ofs)

Reads two bytes of data from the memory location that is specified by a base address and an offset.

Sytnax

public static native short read2(int ptr, int ofs);

Return Value

Returns the bytes that are read.

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.

read2(int ptr)

Reads a short integer from a specified memory location.

Syntax

public static short read2(int ptr);

Return Value

Returns the short integer that is read.

Parameters

ptr The address in memory where the short integer to be read is located.


read4 (DllLib Class)

 Microsoft SDK for Java

read4

The read4 method of the DllLib class contains the following signatures:

read4(Object ptr, int ofs)
read4(int ptr, int ofs)
read4(int ptr)

read4(Object ptr, int ofs)

Reads four bytes of data from the memory location that is specified by a base address and an offset.

Syntax

public static native int read4(Object ptr, int ofs);

Return Value

Returns the bytes that are read.

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.

read4(int ptr, int ofs)

Reads four bytes of data from the memory location that is specified by a base address and an offset.

Syntax

public static native int read4(int ptr, int ofs);

Return Value

Returns the bytes that are read.

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.

read4(int ptr)

Reads an integer from a specified memory location.

Syntax

public static int read4(int ptr);

Return Value

Returns the integer that is read.

Parameters

ptr The address in memory where the integer to be read is located.


read8 (DllLib Class)

 Microsoft SDK for Java

read8

The read8 method of the DllLib class contains the following signatures:

read8(Object ptr, int ofs)
read8(int ptr, int ofs)
read8(int ptr)

read8(Object ptr, int ofs)

Reads eight bytes of data from the memory location that is specified by a base address and an offset.

Syntax

public static native long read8(Object ptr, int ofs);

Return Value

Returns the bytes that are read.

ptr | The base address to write to.
ofs | The offset from the base address.

read8(int ptr, int ofs)

Reads eight bytes of data from the memory location that is specified by a base address and an offset.

Syntax

public static native long read8(int ptr, int ofs);

Return Value

Returns the bytes that are read.

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.

read8(int ptr)

Reads a long integer from a specified memory location.

Syntax

public static long read8(int ptr);

Return Value

Returns the long integer that is read.

Parameters

ptr The base address to write to.


release (DllLib Class)

 Microsoft SDK for Java

release

This method of the DllLib class frees the native memory associated with an object declared using the @dll.struct compiler directive, if that memory would normally have been released by garbage collection. If the object is not declared using @dll.struct, or if the native memory associated with the object is not owned by the garbage-collector, this method does nothing.

Syntax

public static native void release(Object o);

Parameters

o The object to be freed.


resize (DllLib Class)

 Microsoft SDK for Java

resize

This method of the DllLib class reallocates the native memory block represented by an object declared using the @dll.struct directive. The object must have been created by executing "new" from Java (as opposed to being created to wrap an external pointer). The new block will preserve the contents of the old block as much as possible. If the new block is larger than the old block, the remaining portion will be zero-initialized.

This method is normally invoked from a constructor and can be used to implement structures that vary in size.

Syntax

public native static void resize(Object structObj, int newsize);

Parameters

structObj | The structure to resize.
newsize | The new size (in bytes).


sizeOf (DllLib Class)

 Microsoft SDK for Java

sizeOf

The sizeOf method of the DllLib class contains the following signatures:

sizeOf(Class structCls)
sizeOf(Object structObj)

sizeOf(Class structCls)

Returns the size in bytes of the native structure represented by the specified class. The class must have been declared using the @dll.struct compiler directive (or @com.struct).

Syntax

public static int sizeOf(Class structCls);

Return Value

Returns the size of the native structure (in bytes).

Parameters

structCls The class to examine.

sizeOf(Object structObj)

Returns the size in bytes of an instance of a J/Direct structure.

Syntax

public native static int sizeOf(Object structObj);

Return Value

Returns the size of the object.

Parameters

structObj The object whose size is being determined.

You can use this method to declare a self-describing structure that will be used in a DLL call, as in the following example:

/** @dll.struct() */
class STARTUPINFO
{
  public int cb = DllLib.sizeOf(this);
  public int lpReserved;
  public int lpDesktop;
  ...
}

// now you can use an instance of STARTUPINFO in a DLL call


stringToCoTaskMem (DllLib Class)

 Microsoft SDK for Java

stringToCoTaskMem

This method of the DllLib class copies a string into a native memory block by using either ANSI or Unicode format depending on the auto mode setting. The memory block is allocated by using the Win32 function CoTaskMemAlloc.

Syntax

public static int stringToCoTaskMem(String s);

Return Value

Returns a pointer to the block that contains the string in the specified format.

Parameters

s The string to copy.

Remarks

You can use the freeCoTaskMem method to release the block from Java.

Important Note On Windows NT, if you use the stringToCoTaskMem method with the Comctl32.ListView_InsertColumn function, you might not get the results you expect. Instead, you should use the stringToCoTaskAnsi method as shown in the following example:

lvc1.pszText = DllLib.stringToCoTaskMemAnsi("C Column"); // Notice the Ansi suffix
int1 = Comctl32.ListView_InsertColumn(hWindLV1, 1, lvc1);


stringToCoTaskMemAnsi (DllLib Class)

 Microsoft SDK for Java

stringToCoTaskMemAnsi

This method of the DllLib class copies a string into a native memory block in ANSI format. The memory block is allocated by using the Win32 function CoTaskMemAlloc.

Syntax

public static int stringToCoTaskMemAnsi(String s);

Return Value

Returns a pointer to the block that contains the specified string in ANSI format.

Parameters

s The string to copy.

Remarks

You can use the freeCoTaskMem method to release the block from Java.

stringToCoTaskMemAnsi was added as of versions 2437 through 2925 of the Microsoft virtual machine.


stringToCoTaskMemUni (DllLib Class)

 Microsoft SDK for Java

stringToCoTaskMemUni

This method of the DllLib class copies a string into a native memory block in Unicode format. The memory block is allocated by using the Win32 function CoTaskMemAlloc.

Syntax

public static int stringToCoTaskMemUni(String s);

Return Value

Returns a pointer to the block that contains the specified string in Unicode format.

Parameters

s The string to copy.

Remarks

You can use the freeCoTaskMem method to release the block from Java.


stringToHGlobal (DllLib Class)

 Microsoft SDK for Java

stringToHGlobal

This method of the DllLib class copies a string into a native memory block, using either ANSI or Unicode format, depending on the auto mode setting. The memory block is allocated by using GlobalAlloc (GMEM_FIXED).

Syntax

public static int stringToHGlobal(String s);

Return Value

Returns a pointer to the block that contains the specified string.

Parameters

s The string to copy.

Remarks

You can use the freeHGlobal method to release the block from Java.


stringToHGlobalAnsi (DllLib Class)

 Microsoft SDK for Java

stringToHGlobalAnsi

This method of the DllLib class copies a string into a native memory block in ANSI format. The memory block is allocated by using GlobalAlloc (GMEM_FIXED).

Syntax

public static int stringToHGlobalAnsi(String s);

Return Value

Returns a pointer to the block that contains the specified string in ANSI format.

Parameters

s The string to copy.

Remarks

You can use the freeHGlobal method to release the block from Java.

stringToHGlobalAnsi was added as of versions 2437 through 2925 of the Microsoft virtual machine.


stringToHGlobalUni (DllLib Class)

 Microsoft SDK for Java

stringToHGlobalUni

This method of the DllLib class copies a string into a native memory block in Unicode format. The memory block is allocated by using GlobalAlloc (GMEM_FIXED).

Syntax

public static int stringToHGlobalUni(String s);

Return Value

Returns a pointer to the block that contains the specified string in Unicode format.

Parameters

s The string to copy.

Remarks

You can use the freeHGlobal method to release the block from Java.


throwWin32Exception (DllLib Class)

 Microsoft SDK for Java

throwWin32Exception

This method of the DllLib class throws a Win32Exception using the error code set by the last DLL-imported method (declared with the setLastError modifier) that is invoked on the current thread.

Note Only DLL methods declared with the setLastError modifier can set error codes.

Syntax

public static final void throwWin32Exception();


write1 (DllLib Class)

 Microsoft SDK for Java

write1

The write1 method of the DllLib class contains the following signatures:

write1(Object ptr, int ofs, byte val)
write1(int ptr, int ofs, byte val)
write1(int ptr, byte val)

write1(Object ptr, int ofs, byte val)

Writes one byte of data to the memory location that is specified by a base address and an offset.

Syntax

public static native void write1(Object ptr, int ofs, byte val);

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.
val | The value to write.

write1(int ptr, int ofs, byte val)

Writes one byte of data to the memory location that is specified by a base address and an offset.

Syntax

public static native void write1(int ptr, int ofs, byte val);

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.
val | The value to write.

write1(int ptr, byte val)

Writes a byte to the specified memory location.

Syntax

public static void write1(int ptr, byte val);

Parameters

ptr | The address in memory where the byte will be written.
val | The value to write.


write2 (DllLib Class)

 Microsoft SDK for Java

write2

The write2 method of the DllLib class contains the following signatures:

write2(Object ptr, int ofs, short val)
write2(int ptr, int ofs, short val)
write2(int ptr, short val)
write2(Object ptr, int ofs, char val)
write2(int ptr, int ofs, char val)
write2(int ptr, char val)

write2(Object ptr, int ofs, short val)

Writes two bytes of data to the memory location that is specified by a base address and an offset.

Syntax

public static native void write2(Object ptr, int ofs, short val);

Parameters

pt | The base address to write to.
ofs | The offset from the base address.
val | The value to write.

write2(int ptr, int ofs, short val)

Writes two bytes of data to the memory location that is specified by a base address and an offset.

Syntax

public static native void write2(int ptr, int ofs, short val);

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.
val | The value to write.

write2(int ptr, short val)

Writes a short integer to the specified memory location.

Syntax

public static void write2(int ptr, short val);

Parameters

ptr | The address in memory where the short integer will be written.
val | The value to write.

write2(Object ptr, int ofs, char val)

Writes two bytes of data to the memory location that is specified by a base address and an offset.

Syntax

public static native void write2(Object ptr, int ofs, char val);

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.
val | The value to write.

write2(int ptr, int ofs, char val)

Writes two bytes of data to the memory location that is specified by a base address and an offset.

Syntax

public static native void write2(int ptr, int ofs, char val);

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.
val | The value to write.

write2(int ptr, char val)

Writes a character to the specified memory location.

Syntax

public static void write2(int ptr, char val);

Parameters

ptr | The address in memory where the character will be written.
val | The value to write.


write4 (DllLib Class)

 Microsoft SDK for Java

write4

The write4 method of the DllLib class contains the following signatures:

write4(Object ptr, int ofs, int val)
write4(int ptr, int ofs, int val)
write4(int ptr, int val)

write4(Object ptr, int ofs, int val)

Writes four bytes of data to the memory location that is specified by a base address and an offset.

Syntax

public static native void write4(Object ptr, int ofs, int val);

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.
val | The value to write.

write4(int ptr, int ofs, int val)

Writes four bytes of data to the memory location that is specified by a base address and an offset.

Syntax

public static native void write4(int ptr, int ofs, int val);

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.
val | The value to write.

write4(int ptr, int val)

Writes an integer to the specified memory location.

Syntax

public static void write4(int ptr, int val);

Parameters

ptr | The address in memory where the integer will be written.
val | The value to write.


write8 (DllLib Class)

 Microsoft SDK for Java

write8

The write8 method of the DllLib class contains the following signatures:

write8(Object ptr, int ofs, long val)
write8(int ptr, int ofs, long val)
write8(int ptr, long val)

write8(Object ptr, int ofs, long val)

Writes eight bytes of data to the memory location that is specified by a base address and an offset.

Syntax

public static native void write8(Object ptr, int ofs, long val);

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.
val | The value to write.

write8(int ptr, int ofs, long val)

Writes eight bytes of data to the memory location that is specified by a base address and an offset.

Syntax

public static native void write8(int ptr, int ofs, long val);

Parameters

ptr | The base address to write to.
ofs | The offset from the base address.
val | The value to write.

write8(int ptr, long val)

Writes a long integer to the specified memory location.

Syntax

public static void write8(int ptr, long val);

Parameters

ptr | The address in memory where the long integer will be written.
val | The value to write.


Fields (DllLib Class)

 Microsoft SDK for Java

DllLib Class Fields

The DllLib class contains the following field.

systemDefaultCharSize Contains the preferred character size of the host system (1 for ANSI, 2 for Unicode). The value of this class variable indicates the mode that a DLL-imported method will link in when the auto modifier is used with the @dll.import compiler directive.


ParameterCountMismatchError Class (com.ms.dll Package)

 Microsoft SDK for Java

ParameterCountMismatchError Class

The ParameterCountMismatchError class of the com.ms.dll package represents objects that contain the number of parameters expected and the number of objects actually passed to a method.

public class ParameterCountMismatchError extends RuntimeException
{
  // Constructors
  public ParameterCountMismatchError();
  public ParameterCountMismatchError(int expected, int passed);
}

ParameterCountMismatchError objects are thrown by the Microsoft VM under debugging mode if a function called with J/Direct accepts fewer or more parameters than was passed in. For more information on using J/Direct, see Java/Win32 Integration with J/Direct.

Hierarchy

RuntimeException
  |
  +--ParameterCountMismatchError


Constructors (ParameterCountMismatchError Class)

 Microsoft SDK for Java

ParameterCountMismatchError Class Constructors

The ParameterCountMismatchError class contains the following constructors:

ParameterCountMismatchError()
ParameterCountMismatchError(int expected, int passed)

ParameterCountMismatchError()

Constructs a ParameterCountMismatchError object.

Syntax

public ParameterCountMismatchError();

ParameterCountMismatchError(int expected, int passed)

Constructs a ParameterCountMismatchError object from the number of parameters passed and the number of parameters expected.

Syntax

public ParameterCountMismatchError(int expected, int passed);

Parameters

expected | The number of parameters expected.
passed | The number of parameters actually passed.


Root Class (com.ms.dll Package)

 Microsoft SDK for Java

Root Class

The Root class of the com.ms.dll package allows you to create an opaque 32-bit root handle to any Java object.

public class Root
{
  // Methods
  public static int alloc(Object object);
  public static void free(int root);
  public static Object get(int root);
}

A root handle prevents the contained Java object from being reclaimed by garbage collection, so that the Java object can be safely stored in native data structures. This technique is valuable when using DLL functions that take callback parameters.

For example, when a callback will be used across function calls, you need to protect the Callback object from being reclaimed. You should wrap the Callback inside a root handle and then explicitly free the root handle when you no longer need the Callback.

Suppose you have declared a class called EnumWindowsProc that extends Callback and that will be used across function calls. To protect an instance of this class from garbage collection, you could write the following code:

EnumWindowsProc MyCallback = new EnumWindowsProc;
int rootHandle = Root.alloc(MyCallback);
// use the Callback across function calls
// until you're done
Root.free(rootHandle);

For more information about declaring and invoking DLL functions that take callbacks, see Callbacks.


Methods (Root Class)

 Microsoft SDK for Java

Root Class Methods

The Root class contains the following methods:

alloc creates a new root handle.
free releases a root handle.
get extracts the Java object protected by a root handle.


alloc (Root Class)

 Microsoft SDK for Java

alloc

This method of the Root class creates a new root handle.

Note Root handles require explicit deallocation using the free method. The object will not be reclaimed by the garbage collector until the free method is called.

Syntax

public static int alloc(Object object);

Return Value

Returns a new root handle that protects the object from garbage collection.

Parameters

object The object that the root handle is created for.


free (Root Class)

 Microsoft SDK for Java

free

This method of the Root class releases a root handle.

Syntax

public static void free(int root);

Parameters

root The handle to release.


get (Root Class)

 Microsoft SDK for Java

get

This method of the Root class extracts the Java object protected by a root handle.

Syntax

public static Object get(int root);

Return Value

Returns the Java object protected by the root handle.

Parameters

root The handle to dereference.


Win32Exception Class (com.ms.dll Package)

 Microsoft SDK for Java

Win32Exception Class

The Win32Exception class of the com.ms.dll package provides access to objects that contain error codes and error descriptions for errors set by Microsoft® Win32® functions.

public class Win32Exception extends RuntimeException
{
  // Constructors
  public Win32Exception(int errorcode);
  public Win32Exception(int errorcode, String message);

  // Methods
  public int getErrorCode();
  public static String getErrorDescription(int errorcode);
}

To set an error code, a Win32 function must be imported using the @dll.import directive with the setLastError modifier. This modifier tells the Microsoft VM to capture the error code immediately after invoking the method. To retrieve the error code, you can invoke the com.ms.dll.dllLib.getLastWin32Error method.

Suppose you have imported the Win32 function FindClose, which returns status information through the error code. You can call the FindClose method, retrieve the error code, and wrap the error code in a Win32Exception object as shown by the following example:

import com.ms.dll.*;

boolean successful = FindClose(hFindFile);
if (!successful) {
  Win32Exception e =
        new Win32Exception(DllLib.getLastWin32Error());
}

Note You cannot reliably retrieve error codes by using the Win32 function GetLastError. This is because the Microsoft VM, while executing function calls of its own, might overwrite the error code before you retrieve it.

To learn how to import DLL functions such as FindClose, see @dll.import.

Hierarchy

RuntimeException
  |
  +--Win32Exception


Constructors (Win32Exception Class)

 Microsoft SDK for Java

Win32Exception Class Constructors

The Win32Exception contains the following constructors:

Win32Exception(int errorcode)
Win32Exception(int errorcode, String message)

Win32Exception(int errorcode)

Creates a Win32Exception object initialized with an error code.

Syntax

public Win32Exception(int errorcode);

Parameters

errorcode The error code.

Win32Exception(int errorcode, String message)

Creates a Win32Exception object initialized with an error code and an error description.

Syntax

public Win32Exception(int errorcode, String message);

Parameters

errorcode | The error code.
message | The error description.


Methods (Win32Exception Class)

 Microsoft SDK for Java

Win32Exception Class Methods

The Win32Exception class contains the following methods:

getErrorCode retrieves the error code associated with the Win32Exception object.
getErrorDescription retrieves the error description associated with a Win32 error code.


getErrorCode (Win32Exception Class)

 Microsoft SDK for Java

getErrorCode

This method of the Win32Exception class retrieves the error code associated with the Win32Exception object.

Syntax

public int getErrorCode();

Return Value

Returns the error code associated with the Win32Exception object.


getErrorDescription (Win32Exception Class)

 Microsoft SDK for Java

getErrorDescription

This method of the Win32Exception class retrieves the error description associated with a Win32 error code.

Syntax

public static String getErrorDescription(int errorcode);

Return Value

Returns the error description.

Parameters

errorcode The error code.


com.ms.ie Package Overview

Microsoft Packages Overview

The com.ms.ie package provides the classes and interfaces needed by Java programs and applets to access and host the Web browser for Microsoft® Windows®.

This package contains the following:

Classes

Interfaces

Hierarchy

Note When using the com.ms.ie classes with Microsoft® Internet Explorer 5.0, some of its functionality will not be available. Shell automation objects that were moved to shdoc401.dll from shdocvw.dll are inaccessible, and ClassDefNotFound exceptions are thrown when the Favorites menu is opened, disabling much of the Favorites menu functionality.

For more information about the usage of Web browser interfaces, see the Platform SDK and MSDN™ Library documentation on shdocvw.dll and the WebBrowser control.


Classes (com.ms.ie package)

 Microsoft SDK for Java

com.ms.ie Package Classes

The com.ms.ie package contains the following classes:

InternetExplorer controls a remote instance of the Microsoft® Internet Explorer application through Automation.

WebBrowser adds browsing capabilities to applications.


Interfaces (com.ms.ie package)

 Microsoft SDK for Java

com.ms.ie Package Interfaces

The com.ms.ie package contains the following interfaces:

CommandStateChangeConstants defines the constants for the CommandStateChange method of the DWebBrowserEvents2 interface.

DWebBrowserEvents is an older version of the event sink interface that is superseded by DWebBrowserEvents2.

DWebBrowserEvents2 is the Web browser control events interface.

DWebBrowserEventsEventListener is an event listener for the WebBrowser class.

IShellUIHelper is the shell user interface helper control interface.

IWebBrowser is part of an older version of the Web browser interface that is superseded by IWebBrowser2.

IWebBrowser2 enables applications to implement an instance of the WebBrowser control or control an instance of the Microsoft® Internet Explorer application.

OLECMDEXECOPT specifies command execution options.

OLECMDF defines the values returned by the InternetExplorer.QueryStatusWB or WebBrowser.QueryStatusWB method.

OLECMDID defines the constants for specifying which command to execute.

tagREADYSTATE is an enumeration of constants that indicate what state an object is in, such as loading, loaded, or uninitialized.


com.ms.ie Package Hierarchy

The com.ms.ie package has the following hierarchy:

java.lang.Object
  |
  +--CScriptErrorList (IScriptErrorList)
  |
  +--DWebBrowserEvents2EventMulticaster (DWebBrowserEvents2)
  |    (Used internally to track listener objects)
  |
  +--DWebBrowserEventsEventMulticaster (DWebBrowserEvents)
  |    (Used internally to track listener objects)
  |
  +--InternetExplorer (IWebBrowser2,IWebBrowserApp)
  |
  +--SearchAssistantOC (ISearchAssistantOC2)
  |
  +--ShellBrowserWindow (IWebBrowser2,IWebBrowserApp)
  |
  +--ShellNameSpace (IShellNameSpace)
  |
  +--ShellUIHelper (IShellUIHelper)
  |
  +--ShellWindows (IShellWindows)
  |
  +--WebBrowser (com.ms.activeX.ActiveXControl)
  |
  +--WebBrowserEventMulticaster (DWebBrowserEvents2)
  |    (Used internally to track listener objects)
  |
  +--WebBrowserRaw (IWebBrowser,IWebBrowser2)
  |
  +--WebBrowser_V1 (com.ms.activeX.ActiveXControl)
  |
  +--WebBrowser_V1EventMulticaster (DWebBrowserEvents)
  |    (Used internally to track listener objects)
  |
  +--WebBrowser_V1Raw (IWebBrowser,IWebBrowser2)

CommandStateChangeConstants
DShellNameSpaceEvents
DShellWindowsEvents
DWebBrowserEvents
DWebBrowserEvents2
DWebBrowserEvents2EventListener
DWebBrowserEventsEventListener
IScriptErrorList
ISearch
ISearchAssistantOC
ISearchAssistantOC2
ISearches
IShellFavoritesNameSpace
IShellNameSpace
IShellUIHelper
IShellWindows
IWebBrowser
IWebBrowser2
IWebBrowserApp
OLECMDEXECOPT
OLECMDF
OLECMDID
ShellWindowFindWindowOptions
ShellWindowTypeConstants
tagREADYSTATE
WebBrowserEventListener
WebBrowser_V1EventListener
_SearchAssistantEvents


InternetExplorer Class

The InternetExplorer class of the com.ms.ie package controls a remote instance of the Microsoft® Internet Explorer application through Automation.

public class InternetExplorer implements com.ms.com.IUnknown,
com.ms.com.NoAutoScripting, com.ms.ie.IWebBrowser2,
com.ms.ie.IWebBrowserApp
{
  // Methods
  public native void ClientToWindow(int[] pcx, int[] pcy);
  public native void ExecWB(int cmdID, int cmdexecopt, com.ms.com.Variant
pvaIn, com.ms.com.Variant pvaOut);
  public native boolean getAddressBar();
  public native Object getApplication();
  public native boolean getBusy();
  public native Object getContainer();
  public native Object getDocument();
  public native String getFullName();
  public native boolean getFullScreen();
  public native int getHWND();
  public native int getHeight();
  public native int getLeft();
  public native String getLocationName();
  public native String getLocationURL();
  public native boolean getMenuBar();
  public native String getName();
  public native boolean getOffline();
  public native Object getParent();
  public native String getPath();
  public native com.ms.com.Variant GetProperty(String Property);
  public native int getReadyState();
  public native boolean getRegisterAsBrowser();
  public native boolean getRegisterAsDropTarget();
  public native boolean getResizable();
  public native boolean getSilent();
  public native boolean getStatusBar();
  public native String getStatusText();
  public native boolean getTheaterMode();
  public native int getToolBar();
  public native int getTop();
  public native boolean getTopLevelContainer();
  public native String getType();
  public native boolean getVisible();
  public native int getWidth();
  public native void GoBack();
  public native void GoForward();
  public native void GoHome();
  public native void GoSearch();
  public native void Navigate2(com.ms.com.Variant URL,
com.ms.com.Variant Flags, com.ms.com.Variant TargetFrameName,
com.ms.com.Variant PostData, com.ms.com.Variant Headers);
  public native void Navigate(String URL, com.ms.com.Variant Flags,
com.ms.com.Variant TargetFrameName,
com.ms.com.Variant PostData, com.ms.com.Variant Headers);
  public native void PutProperty(String Property,
com.ms.com.Variant vtValue);
  public native int QueryStatusWB(int cmdID);
  public native void Quit();
  public native void Refresh2(com.ms.com.Variant Level);
  public native void Refresh();
  public native void setAddressBar(boolean Visible);
  public native void setFullScreen(boolean FullScreen);
  public native void setHeight(int Pixels);
  public native void setLeft(int Pixels);
  public native void setMenuBar(boolean Visible);
  public native void setOffline(boolean Offline);
  public native void setRegisterAsBrowser(boolean Register);
  public native void setRegisterAsDropTarget(boolean Register);
  public native void setResizable(boolean Resizable);
  public native void setSilent(boolean Silent);
  public native void setStatusBar(boolean On);
  public native void setStatusText(String StatusText);
  public native void setTheaterMode(boolean TheaterMode);
  public native void setToolBar(int Value);
  public native void setTop(int Pixels);
  public native void setVisible(boolean Visible);
  public native void setWidth(int Pixels);
  public native void ShowBrowserBar(com.ms.com.Variant pvaClsid,
com.ms.com.Variant pvarShow, com.ms.com.Variant pvarSize);
  public native void Stop();
}


Methods (InternetExplorer Class)

 Microsoft SDK for Java

InternetExplorer Class Methods

The InternetExplorer class contains the following methods:

ClientToWindow converts the client coordinates of a point to window coordinates.

ExecWB implements a wrapper that allows you to execute a command on an OLE object using the IOleCommandTarget::Exec method.

getAddressBar retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer object's address bar is visible.

getApplication retrieves the Automation interface supported by the Microsoft® Internet Explorer application.

getBusy retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is engaged in a downloading operation or other activity.

getContainer retrieves a pointer to the IDispatch interface of the container.

getDocument retrieves a pointer to the IDispatch interface of the Active Document object.

getFullName retrieves the fully qualified path of the Microsoft® Internet Explorer executable file.

getFullScreen retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is in full-screen or normal window mode.

getHWND retrieves the handle to the Microsoft® Internet Explorer main window.

getHeight retrieves the height of the Microsoft® Internet Explorer main window.

getLeft retrieves the screen coordinate of the left edge of the Microsoft® Internet Explorer main window.

getLocationName retrieves the name of the resource that Microsoft® Internet Explorer is currently displaying.

getLocationURL retrieves the URL of the resource that Microsoft® Internet Explorer is currently displaying.

getMenuBar retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer menu bar is visible.

getName retrieves the name of the object that contains the WebBrowser control used by Microsoft® Internet Explorer.

getOffline retrieves a Boolean value indicating whether the WebBrowser control is currently operating in offline mode.

getParent retrieves a pointer to the IDispatch interface of the object that is the container of the WebBrowser control.

getPath retrieves the full path of the Microsoft® Internet Explorer application.

GetProperty retrieves the value of a property associated with the given object.

getReadyState retrieves the ready state of the object.

getRegisterAsBrowser retrieves a Boolean value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

getRegisterAsDropTarget retrieves a Boolean value indicating whether the WebBrowser control is registered as a drop target for navigation.

getResizable retrieves the InternetExplorer object's resizable property.

getSilent retrieves a Boolean value indicating whether any dialog boxes can be shown.

getStatusBar retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer status bar is visible.

getStatusText retrieves the text of the Microsoft® Internet Explorer status bar.

getTheaterMode retrieves a value indicating whether the WebBrowser control is in theater mode.

getToolBar retrieves a value that indicates whether the Microsoft® Internet Explorer toolbar is visible.

getTop retrieves the screen coordinate of the top edge of the Microsoft® Internet Explorer main window.

getTopLevelContainer retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is the top-level container of the WebBrowser control.

getType retrieves the type name of the contained document object.

getVisible retrieves a Boolean value that indicates whether the object is visible or hidden.

getWidth retrieves the width of the Microsoft® Internet Explorer main window.

GoBack navigates backward one item in the history list.

GoForward navigates forward one item in the history list.

GoHome navigates to the current home or start page.

GoSearch navigates to the current search page.

Navigate navigates to a resource identified by a Uniform Resource Locator (URL) or to the file identified by a full path.

Navigate2 navigates the browser to a location that may not be able to be expressed as a URL, such as a pointer to an item identifier list (PIDL) for an entity in the Windows shell namespace.

PutProperty sets the value of a property associated with the given object.

QueryStatusWB implements a wrapper that allows you to query an OLE object for the status of commands using the IOleCommandTarget::QueryStatus method.

Quit closes the Microsoft® Internet Explorer application.

Refresh reloads the file that Microsoft® Internet Explorer is currently displaying.

Refresh2 reloads the file that Microsoft® Internet Explorer is currently displaying. Unlike IWebBrowser2.Refresh, this method contains a parameter that specifies the refresh level.

setAddressBar shows or hides the Microsoft® Internet Explorer object's address bar.

setFullScreen sets Microsoft® Internet Explorer to either full-screen or normal window mode.

setHeight sets the height of the Microsoft® Internet Explorer main window.

setLeft sets the horizontal position of the Microsoft® Internet Explorer main window.

setMenuBar shows or hides the Microsoft® Internet Explorer menu bar.

setOffline sets a value indicating whether the WebBrowser control is currently operating in offline mode. In offline mode, the browser is forced to read HTML pages from the local cache rather than from the source document.

setRegisterAsBrowser sets a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

setRegisterAsDropTarget sets a value indicating whether the WebBrowser control is registered as a drop target for navigation.

setResizable sets the Microsoft® Internet Explorer object's resizable property.

setSilent sets a value indicating whether any dialog boxes can be shown.

setStatusBar shows or hides the Microsoft® Internet Explorer status bar.

setStatusText sets the text of the Microsoft® Internet Explorer status bar.

setTheaterMode sets the TheaterMode property for the WebBrowser control.

setToolBar shows or hides the Microsoft® Internet Explorer toolbar.

setTop sets the vertical position of the Microsoft® Internet Explorer main window.

setVisible sets the visibility state of the object.

setWidth sets the width of the Microsoft® Internet Explorer main window.

ShowBrowserBar shows or hides a specified browser bar.

Stop cancels any pending navigation or download operation and stops any dynamic page elements, such as background sounds and animations.


ClientToWindow (InternetExplorer Class)

 Microsoft SDK for Java

ClientToWindow

This method of the InternetExplorer class converts the client coordinates of a point to window coordinates.

Syntax

public native void ClientToWindow(int[] pcx, int[] pcy);

Parameters

pcx | Specifies the x-coordinate of the point in client coordinates.
pcy | Specifies the y-coordinate of the point in client coordinates.


ExecWB (InternetExplorer Class)

 Microsoft SDK for Java

ExecWB

This method of the InternetExplorer class implements a wrapper that allows you to execute a command on an OLE object using the IOleCommandTarget::Exec method.

Syntax

public native void ExecWB(int cmdID, int cmdexecopt, com.ms.com.Variant pvaIn, com.ms.com.Variant pvaOut);

Parameters

cmdID | The identifier of the command to execute.
cmdexecopt | The options set for executing the command.
pvaIn | A variant used for specifying command input arguments.
pvaOut | A variant used for specifying command output arguments.


getAddressBar (InternetExplorer Class)

 Microsoft SDK for Java

getAddressBar

This method of the InternetExplorer class retrieves a Boolean value that indicates whether the Internet Explorer object's address bar is visible.

Syntax

public native boolean getAddressBar();


getApplication (InternetExplorer Class)

 Microsoft SDK for Java

getApplication

This method of the InternetExplorer class retrieves the Automation interface supported by the Microsoft® Internet Explorer application.

Syntax

public native java.lang.Object getApplication();


getBusy (InternetExplorer Class)

 Microsoft SDK for Java

getBusy

This method of the InternetExplorer class retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is engaged in a downloading operation or other activity.

Syntax

public native boolean getBusy();


getContainer (InternetExplorer Class)

 Microsoft SDK for Java

getContainer

This method of the InternetExplorer class retrieves a pointer to the IDispatch interface of the container.

Syntax

public native java.lang.Object getContainer();


getDocument (InternetExplorer Class)

 Microsoft SDK for Java

getDocument

This method of the InternetExplorer class retrieves a pointer to the IDispatch interface of the Active Document object.

Syntax

public native java.lang.Object getDocument();


getFullName (InternetExplorer Class)

 Microsoft SDK for Java

getFullName

This method of the InternetExplorer class retrieves the fully qualified path of the Microsoft® Internet Explorer executable file.

Syntax

public native java.lang.String getFullName();


getFullScreen (InternetExplorer Class)

 Microsoft SDK for Java

getFullScreen

This method of the InternetExplorer class retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is in full-screen or normal window mode.

Syntax

public native boolean getFullScreen();


getHeight (InternetExplorer Class)

 Microsoft SDK for Java

getHeight

This method of the InternetExplorer class retrieves the height of the Microsoft® Internet Explorer main window.

Syntax

public native int getHeight();


getHWND (InternetExplorer Class)

 Microsoft SDK for Java

getHWND

This method of the InternetExplorer class retrieves the handle to the Microsoft® Internet Explorer main window.

Syntax

public native int getHWND();


getLeft (InternetExplorer Class)

 Microsoft SDK for Java

getLeft

This method of the InternetExplorer class retrieves the screen coordinate of the left edge of the Microsoft® Internet Explorer main window.

Syntax

public native int getLeft();


getLocationName (InternetExplorer Class)

 Microsoft SDK for Java

getLocationName

This method of the InternetExplorer class retrieves the name of the resource that Microsoft® Internet Explorer is currently displaying.

Syntax

public native java.lang.String getLocationName();


getLocationURL (InternetExplorer Class)

 Microsoft SDK for Java

getLocationURL

This method of the InternetExplorer class retrieves the URL of the resource that Microsoft® Internet Explorer is currently displaying.

Syntax

public native java.lang.String getLocationURL();


getMenuBar (InternetExplorer Class)

 Microsoft SDK for Java

getMenuBar

This method of the InternetExplorer class retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer menu bar is visible.

Syntax

public native boolean getMenuBar();


getName (InternetExplorer Class)

 Microsoft SDK for Java

getName

This method of the InternetExplorer class retrieves the name of the object that contains the WebBrowser control used by Microsoft® Internet Explorer.

Syntax

public native java.lang.String getName();


getOffline (InternetExplorer Class)

 Microsoft SDK for Java

getOffline

This method of the InternetExplorer class retrieves a Boolean value indicating whether the WebBrowser control is currently operating in offline mode.

Syntax

public native boolean getOffline();


getParent (InternetExplorer Class)

 Microsoft SDK for Java

getParent

This method of the InternetExplorer class retrieves a pointer to the IDispatch interface of the object that is the container of the WebBrowser control.

Syntax

public native java.lang.Object getParent();


getPath (InternetExplorer Class)

 Microsoft SDK for Java

getPath

This method of the InternetExplorer class retrieves the full path of the Microsoft® Internet Explorer application.

Syntax

public native java.lang.String getPath();


GetProperty (InternetExplorer Class)

 Microsoft SDK for Java

GetProperty

This method of the InternetExplorer class retrieves the value of a property associated with the given object.

Syntax

public native com.ms.com.Variant GetProperty(java.lang.String Property);

Parameters

Property The name of the property to retrieve.


getReadyState (InternetExplorer Class)

 Microsoft SDK for Java

getReadyState

This method of the InternetExplorer class retrieves the ready state of the object.

Syntax

public native int getReadyState();


getRegisterAsBrowser (InternetExplorer Class)

 Microsoft SDK for Java

getRegisterAsBrowser

This method of the InternetExplorer class retrieves a Boolean value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

Syntax

public native boolean getRegisterAsBrowser();


getRegisterAsDropTarget (InternetExplorer Class)

 Microsoft SDK for Java

getRegisterAsDropTarget

This method of the InternetExplorer class retrieves a Boolean value indicating whether the WebBrowser control is registered as a drop target for navigation.

Syntax

public native boolean getRegisterAsDropTarget();


getResizable (InternetExplorer Class)

 Microsoft SDK for Java

getResizable

This method of the InternetExplorer class retrieves the InternetExplorer object's resizable property.

Syntax

public native boolean getResizable();


getSilent (InternetExplorer Class)

 Microsoft SDK for Java

getSilent

This method of the InternetExplorer class retrieves a Boolean value indicating whether any dialog boxes can be shown.

Syntax

public native boolean getSilent();


getStatusBar (InternetExplorer Class)

 Microsoft SDK for Java

getStatusBar

This method of the InternetExplorer class retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer status bar is visible.

Syntax

public native boolean getStatusBar();


getStatusText (InternetExplorer Class)

 Microsoft SDK for Java

getStatusText

This method of the InternetExplorer class retrieves the text of the Microsoft® Internet Explorer status bar.

Syntax

public native java.lang.String getStatusText();


getTheaterMode (InternetExplorer Class)

 Microsoft SDK for Java

getTheaterMode

This method of the InternetExplorer class retrieves a value indicating whether the WebBrowser control is in theater mode.

Syntax

public native boolean getTheaterMode();


getToolBar (InternetExplorer Class)

 Microsoft SDK for Java

getToolBar

This method of the InternetExplorer class retrieves a value that indicates whether the Microsoft® Internet Explorer toolbar is visible.

Syntax

public native int getToolBar();


getTop (InternetExplorer Class)

 Microsoft SDK for Java

getTop

This method of the InternetExplorer class retrieves the screen coordinate of the top edge of the Microsoft® Internet Explorer main window.

Syntax

public native int getTop();


getTopLevelContainer (InternetExplorer Class)

 Microsoft SDK for Java

getTopLevelContainer

This method of the InternetExplorer class retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is the top-level container of the WebBrowser control.

Syntax

public native boolean getTopLevelContainer();


getType (InternetExplorer Class)

 Microsoft SDK for Java

getType

This method of the InternetExplorer class retrieves the type name of the contained document object.

Syntax

public native java.lang.String getType();


getVisible (InternetExplorer Class)

 Microsoft SDK for Java

getVisible

This method of the InternetExplorer class retrieves a Boolean value that indicates whether the object is visible or hidden.

Syntax

public native boolean getVisible();


getWidth (InternetExplorer Class)

 Microsoft SDK for Java

getWidth

This method of the InternetExplorer class retrieves the width of the Microsoft® Internet Explorer main window.

Syntax

public native int getWidth();


GoBack (InternetExplorer Class)

 Microsoft SDK for Java

GoBack

This method of the InternetExplorer class navigates backward one item in the history list.

Syntax

public native void GoBack();


GoForward (InternetExplorer Class)

 Microsoft SDK for Java

GoForward

This method of the InternetExplorer class navigates forward one item in the history list.

Syntax

public native void GoForward();


GoHome (InternetExplorer Class)

 Microsoft SDK for Java

GoHome

This method of the InternetExplorer class navigates to the current home or start page.

Syntax

public native void GoHome();


GoSearch (InternetExplorer Class)

 Microsoft SDK for Java

GoSearch

This method of the InternetExplorer class navigates to the current search page.

Syntax

public native void GoSearch();


Navigate (InternetExplorer Class)

 Microsoft SDK for Java

Navigate

This method of the InternetExplorer class navigates to a resource identified by a Uniform Resource Locator (URL) or to the file identified by a full path.

Syntax

public native void Navigate(java.lang.String URL,
com.ms.com.Variant Flags, com.ms.com.Variant TargetFrameName,
com.ms.com.Variant PostData, com.ms.com.Variant Headers);

Parameters

URL | Required. A string expression that evaluates to the URL, full path, or Universal Naming Convention (UNC) location and name of the resource to display.
Flags | Optional. A value that specifies whether to add the resource to the history list, whether to read from or write to the cache, and whether to display the resource in a new window. It can be a combination of the following values: navOpenInNewWindow 1 Open the resource or file in a new window. navNoHistory 2 Do not add the resource or file to the history list. The new page replaces the current page in the list. navNoReadFromCache 4 Do not read from the disk cache for this navigation. navNoWriteToCache 8 Do not write the results of this navigation to the disk cache.
TargetFrameName | Optional. A string expression that evaluates to the name of an HTML frame in the URL to display in the browser window. The possible values for this parameter are: _BLANK Load the link into a new unnamed window. _PARENT Load the link into the immediate parent of the document the link is in. _SELF Load the link into the same window the link was clicked in. _TOP Load the link into the full body of the current window. <WINDOW_NAME> A named HTML frame. If no frame or window exists that matches the specified target name, a new window is opened for the specified link.
PostData | Optional. Data to send to the server during the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form to a program or script. If this parameter does not specify any post data, the Navigate method issues an HTTP GET transaction. PostData is ignored if the URL is not an HTTP URL.
Headers | Optional. A value that specifies additional HTTP headers to send to the server. These headers are added to the default Microsoft® Internet Explorer headers. The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code. Headers is ignored if the URL is not an HTTP URL.


Navigate2 (InternetExplorer Class)

 Microsoft SDK for Java

Navigate2

This method of the InternetExplorer class navigates the browser to a location that may not be able to be expressed as a URL, such as a pointer to an item identifier list (PIDL) for an entity in the Microsoft® Windows® shell namespace.

Syntax

public native void Navigate2(com.ms.com.Variant URL,
com.ms.com.Variant Flags, com.ms.com.Variant TargetFrameName,
com.ms.com.Variant PostData, com.ms.com.Variant Headers);

Parameters

URL | Required. A string expression that evaluates to the URL, full path, or Universal Naming Convention (UNC) location and the name of the resource to display.
Flags | Optional. A value that specifies whether to add the resource to the history list, whether to read from or write to the cache, and whether to display the resource in a new window. It can be a combination of the following values: navOpenInNewWindow 1 Open the resource or file in a new window. navNoHistory 2 Do not add the resource or file to the history list. The new page replaces the current page in the list. navNoReadFromCache 4 Do not read from the disk cache for this navigation. navNoWriteToCache 8 Do not write the results of this navigation to the disk cache.
TargetFrameName | Optional. A string expression that evaluates to the name of an HTML frame in the URL to display in the browser window. The possible values for this parameter are: _BLANK Load the link into a new unnamed window. _PARENT Load the link into the immediate parent of the document the link is in. _SELF Load the link into the same window the link was clicked in. _TOP Load the link into the full body of the current window. <WINDOW_NAME> A named HTML frame. If no frame or window exists that matches the specified target name, a new window is opened for the specified link.
PostData | Optional. Data to send to the server during the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form to a program or script. If this parameter does not specify any post data, the Navigate2 method issues an HTTP GET transaction. PostData is ignored if the URL is not an HTTP URL.
Headers | Optional. A value that specifies additional HTTP headers to send to the server. These headers are added to the default Microsoft® Internet Explorer headers. The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code. Headers is ignored if the URL is not an HTTP URL.


PutProperty (InternetExplorer Class)

 Microsoft SDK for Java

PutProperty

This method of the InternetExplorer class sets the value of a property associated with the given object.

Syntax

public native void PutProperty(java.lang.String Property, com.ms.com.Variant vtValue);

Parameters

Property | The name of the property to set.
vtValue | The new value of the property.


QueryStatusWB (InternetExplorer Class)

 Microsoft SDK for Java

QueryStatusWB

This method of the InternetExplorer class implements a wrapper that allows you to query an OLE object for the status of commands using the IOleCommandTarget::QueryStatus method.

Syntax

public native int QueryStatusWB(int cmdID);

Parameters

cmdID The identifier of the command on which the caller needs status information. This will be one of the OLECMDID values.


Quit (InternetExplorer Class)

 Microsoft SDK for Java

Quit

This method of the InternetExplorer class closes the Microsoft® Internet Explorer application.

Syntax

public native void Quit();


Refresh (InternetExplorer Class)

 Microsoft SDK for Java

Refresh

This method of the InternetExplorer class reloads the file that Microsoft® Internet Explorer is currently displaying.

Syntax

public native void Refresh();


Refresh2 (InternetExplorer Class)

 Microsoft SDK for Java

Refresh2

This method of the InternetExplorer class reloads the file that Microsoft® Internet Explorer is currently displaying. Unlike IWebBrowser2.Refresh, this method contains a parameter that specifies the refresh level.

Syntax

public native void Refresh2(com.ms.com.Variant Level);

Parameters

Level Optional. An optional value that specifies the refresh level. It can be one of the following constants or values:

REFRESH_NORMAL 0

Perform a lightweight refresh that does not include sending the HTTP "pragma:nocache" header to the server.

REFRESH_IFEXPIRED 1

Perform a lightweight refresh if the page has expired.

REFRESH_COMPLETELY 3

Perform a full refresh that includes sending a "pragma:nocache" header to the server (HTTP URLs only).


setAddressBar (InternetExplorer Class)

 Microsoft SDK for Java

setAddressBar

This method of the InternetExplorer class shows or hides the Microsoft® Internet Explorer object's address bar.

Syntax

public native void setAddressBar(boolean Value);

Parameters

Value Boolean expression that determines whether the address bar is visible. If TRUE, the address bar is visible; if FALSE, it is hidden. The default value is TRUE.


setFullScreen (InternetExplorer Class)

 Microsoft SDK for Java

setFullScreen

This method of the InternetExplorer class sets Microsoft® Internet Explorer to either full-screen or normal window mode.

Syntax

public native void setFullScreen(boolean pbFullScreen);

Parameters

pbFullScreen If TRUE, the browser window is maximized; if FALSE, it is not.


setHeight (InternetExplorer Class)

 Microsoft SDK for Java

setHeight

This method of the InternetExplorer class sets the height of the Microsoft® Internet Explorer main window.

Syntax

public native void setHeight(int Pixels);

Parameters

Pixels The vertical dimension of the frame window, in pixels.


setLeft (InternetExplorer Class)

 Microsoft SDK for Java

setLeft

This method of the InternetExplorer class sets the horizontal position of the Microsoft® Internet Explorer main window.

Syntax

public native void setLeft(int Pixels);

Parameters

Pixels The distance between the internal left edge of the WebBrowser control and the left edge of its container, in pixels.


setMenuBar (InternetExplorer Class)

 Microsoft SDK for Java

setMenuBar

This method of the InternetExplorer class shows or hides the Microsoft® Internet Explorer menu bar.

Syntax

public native void setMenuBar(boolean Visible);

Parameters

Visible Determines whether the menu bar is visible. If TRUE, the menu bar is visible; if FALSE, it is hidden. The default value is TRUE.


setOffline (InternetExplorer Class)

 Microsoft SDK for Java

setOffline

This method of the InternetExplorer class sets a value indicating whether the WebBrowser control is currently operating in offline mode. In offline mode, the browser is forced to read HTML pages from the local cache rather than from the source document.

Syntax

public native void setOffline(boolean Offline);

Parameters

Offline Determines whether the WebBrowser control is in offline mode. If TRUE, the WebBrowser will read data about its current URL from its local cache. If FALSE, it will attempt to read the source document. The default value is FALSE.


setRegisterAsBrowser (InternetExplorer Class)

 Microsoft SDK for Java

setRegisterAsBrowser

This method of the InternetExplorer class sets a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

Syntax

public native void setRegisterAsBrowser(boolean Register);

Parameters

Register Determines whether Microsoft® Internet Explorer is registered as a top-level browser. If TRUE, the WebBrowser is registered as a top-level browser; if FALSE, it is not a top-level browser. The default value is FALSE.


setRegisterAsDropTarget (InternetExplorer Class)

 Microsoft SDK for Java

setRegisterAsDropTarget

This method of the InternetExplorer class sets a value indicating whether the WebBrowser control is registered as a drop target for navigation.

Syntax

public native void setRegisterAsDropTarget(boolean Register);

Parameters

Register Determines whether Internet Explorer is registered as a drop target for navigation. If TRUE, the WebBrowser is registered as a drop target; if FALSE, it is not a drop target. The default value is FALSE.


setResizable (InternetExplorer Class)

 Microsoft SDK for Java

setResizable

This method of the InternetExplorer class sets the Microsoft® Internet Explorer object's resizable property.

Syntax

public native void setResizable(boolean Resizable);

Parameters

Resizable Sets the object's resizable property. If this value is TRUE, the object can be resized. If this value is FALSE, the object cannot be resized. The default value is TRUE.


setSilent (InternetExplorer Class)

 Microsoft SDK for Java

setSilent

This method of the InternetExplorer class sets a value indicating whether any dialog boxes can be shown.

Syntax

public native void setSilent(boolean Silent);

Parameters

Silent Determines whether the WebBrowser can show any message or dialog boxes. If TRUE, dialog boxes will not be displayed; if FALSE, dialog boxes will be displayed. The default value is FALSE. Critical errors and security alerts are not suppressed.


setStatusBar (InternetExplorer Class)

 Microsoft SDK for Java

setStatusBar

This method of the InternetExplorer class shows or hides the Microsoft® Internet Explorer status bar.

Syntax

public native void setStatusBar(boolean On);

Parameters

On Determines whether the status bar is visible. If TRUE, the status bar is visible; if FALSE, it is hidden. The default is TRUE.


setStatusText (InternetExplorer Class)

 Microsoft SDK for Java

setStatusText

This method of the InternetExplorer class sets the text of the Microsoft® Internet Explorer status bar.

Syntax

public native void setStatusText(java.lang.String StatusText);

Parameters

StatusText The text for the status bar.


setTheaterMode (InternetExplorer Class)

 Microsoft SDK for Java

setTheaterMode

This method of the InternetExplorer class sets the TheaterMode property for the WebBrowser control.

Syntax

public native void setTheaterMode(boolean TheaterMode);

Parameters

TheaterMode Determines whether Microsoft® Internet Explorer is in theater or normal window mode. If TRUE, the object is in theater mode; if FALSE, it is in normal mode. The default value is FALSE.


setToolBar (InternetExplorer Class)

 Microsoft SDK for Java

setToolBar

This method of the InternetExplorer class shows or hides the Microsoft® Internet Explorer toolbar.

Syntax

public native void setToolBar(int Value);

Parameters

Value Determines whether the toolbar is visible. If TRUE, the toolbar is visible; if FALSE, it is hidden. The default is TRUE.


setTop (InternetExplorer Class)

 Microsoft SDK for Java

setTop

This method of the InternetExplorer class sets the vertical position of the Microsoft® Internet Explorer main window.

Syntax

public native void setTop(int Pixels);

Parameters

Pixels Specifies the distance of the top of the Microsoft® Internet Explorer main window from the top of the screen, in pixels.


setVisible (InternetExplorer Class)

 Microsoft SDK for Java

setVisible

This method of the InternetExplorer class sets the visibility state of the object.

Syntax

public native void setVisible(boolean Visible);

Parameters

Visible Specifies the visible state of Microsoft® Internet Explorer. If TRUE, the window is visible; if FALSE, it is hidden. The default value is FALSE.


setWidth (InternetExplorer Class)

 Microsoft SDK for Java

setWidth

This method of the InternetExplorer class sets the width of the Microsoft® Internet Explorer main window.

Syntax

public native void setWidth(int Pixels);

Parameters

Pixels Specifies the horizontal dimension of the frame window, in pixels.


ShowBrowserBar (InternetExplorer Class)

 Microsoft SDK for Java

ShowBrowserBar

This method of the InternetExplorer class shows or hides a specified browser bar.

Syntax

public native void ShowBrowserBar(com.ms.com.Variant pvaClsid,
com.ms.com.Variant pvarShow, com.ms.com.Variant pvarSize);

Parameters

pvaClsid | Required. A string containing the class identifier of the browser bar to show or hide. This object must be registered as an Explorer Bar object with the CATID_InfoBand component category. The standard browser bars use the following class identifiers: Browser Bar NameClass ID Search{30D02401-6A81-11D0-8274-00C04FD5AE38} Favorites{EFA24E61-B078-11D0-89E4-00C04FC9E26E} History{EFA24E62-B078-11D0-89E4-00C04FC9E26E} Channels{EFA24E63-B078-11D0-89E4-00C04FC9E26E}
pvarShow | Optional. A Boolean value that specifies whether the browser bar should be shown or hidden. If this is TRUE, the browser bar is shown. If this is FALSE, the browser bar is hidden. The default value is TRUE.
pvarSize | Optional. Not currently used.


Stop (InternetExplorer Class)

 Microsoft SDK for Java

Stop

This method of the InternetExplorer class cancels any pending navigation or download operation and stops any dynamic page elements, such as background sounds and animations.

Syntax

public native void Stop();


WebBrowser Class (com.ms.ie package)

 Microsoft SDK for Java

WebBrowser Class

The WebBrowser class of the com.ms.ie package adds browsing capabilities to applications. This class extends com.ms.activeX.ActiveXControl, making it easy to use this control from an AWT-based application. Applications hosting this control will support browsing sites on the World Wide Web, as well as directories on the local computer and on network servers.

public synchronized class WebBrowser extends com.ms.activeX.ActiveXControl
{
  // Methods
  public synchronized String _getName();
  public synchronized Object _getParent();
  public synchronized void _setVisible(boolean Visible);
  public void addDWebBrowserEventsEventListener
(DWebBrowserEventsEventListener listener);
  public void addWebBrowserEventListener(
WebBrowserEventListener listener);
  public abstract void ClientToWindow(int[] pcx, int[] pcy);
  public synchronized void enableEvents();
  public abstract void ExecWB(int cmdID, int cmdexecopt,
com.ms.com.Variant pvaIn, com.ms.com.Variant pvaOut);
  public synchronized boolean getAddressBar();
  public synchronized Object getApplication();
  public synchronized boolean getBusy();
  public synchronized Object getContainer();
  public synchronized Object getDocument();
  public synchronized String getFullName();
  public synchronized boolean getFullScreen();
  public synchronized int getHWND();
  public synchronized int getHeight();
  public synchronized int getLeft();
  public synchronized String getLocationName();
  public synchronized String getLocationURL();
  public synchronized boolean getMenuBar();
  public synchronized boolean getOffline();
  public synchronized String getPath();
  public synchronized int getReadyState();
  public synchronized boolean getRegisterAsBrowser();
  public synchronized boolean getRegisterAsDropTarget();
  public synchronized boolean getResizable();
  public synchronized boolean getSilent();
  public synchronized boolean getStatusBar();
  public synchronized String getStatusText();
  public synchronized boolean getTheaterMode();
  public synchronized int getToolBar();
  public synchronized int getTop();
  public synchronized boolean getTopLevelContainer();
  public synchronized String getType();
  public synchronized boolean getVisible();
  public synchronized int getWidth();
  public abstract void GoBack();
  public abstract void GoForward();
  public abstract void GoHome();
  public abstract com.ms.com.Variant GetProperty(String Property);
  public abstract void GoSearch();
  public abstract void Navigate(String URL, com.ms.com.Variant Flags,
com.ms.com.Variant TargetFrameName, com.ms.com.Variant PostData,
com.ms.com.Variant Headers);
  public abstract void Navigate2(com.ms.com.Variant URL,
com.ms.com.Variant Flags, com.ms.com.Variant TargetFrameName,
com.ms.com.Variant PostData, com.ms.com.Variant Headers);
  public abstract void PutProperty(String Property,
com.ms.com.Variant vtValue);
  public abstract int QueryStatusWB(int cmdID);
  public abstract void Quit();
  public abstract void Refresh();
  public abstract void Refresh2(com.ms.com.Variant Level);
  public void removeDWebBrowserEventsEventListener(DWebBrowserEventsEventListener listner);
  public void removeWebBrowserEventListener(WebBrowserEventListener listener);
  public synchronized void setAddressBar(boolean Visible);
  public synchronized void setFullScreen(boolean FullScreen);
  public synchronized void setHeight(int Pixels);
  public synchronized void setLeft(int Pixels);
  public synchronized void setMenuBar(boolean Visible);
  public synchronized void setOffline(boolean Offline);
  public synchronized void setRegisterAsBrowser(boolean Register);
  public synchronized void setRegisterAsDropTarget(boolean Register);
  public synchronized void setResizable(boolean Resizable);
  public synchronized void setSilent(boolean Silent);
  public synchronized void setStatusBar(boolean On);
  public synchronized void setStatusText(String StatusText);
  public synchronized void setTheaterMode(boolean TheaterMode);
  public synchronized void setToolBar(int Value);
  public synchronized void setTop(int Pixels);
  public synchronized void setWidth(int Pixels);
  public abstract void ShowBrowserBar(com.ms.com.Variant pvaClsid,
com.ms.com.Variant pvarShow, com.ms.com.Variant pvarSize);
  public abstract void Stop();
}


Methods (WebBrowser Class)

 Microsoft SDK for Java

WebBrowser Class Methods

The WebBrowser class has the following methods:

_getName retrieves the name of the object that contains the WebBrowser control used by Microsoft® Internet Explorer.

_getParent retrieves a pointer to the IDispatch interface of the object that is the container of the WebBrowser control.

_setVisible sets the visibility state of the object.

addDWebBrowserEventsEventListener registers the specified listener to receive DWebBrowserEvents events.

addWebBrowserEventListener registers the specified listener to receive WebBrowserEvent events.

ClientToWindow converts the client coordinates of a point to window coordinates.

enableEvents registers the WebBrowser control to receive events.

ExecWB implements a wrapper that allows you to execute a command on an OLE object using the IOleCommandTarget::Exec method.

getAddressBar retrieves a Boolean value that indicates whether the Internet Explorer object's address bar is visible.

getApplication retrieves the automation interface supported by the Microsoft® Internet Explorer application.

getBusy retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is engaged in a downloading operation or other activity.

getContainer retrieves a pointer to the IDispatch interface of the container.

getDocument retrieves a pointer to the IDispatch interface of the Active Document object.

getFullName retrieves the fully qualified path of the Microsoft® Internet Explorer executable file.

getFullScreen retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is in full-screen or normal window mode.

getHeight retrieves the height of the Microsoft® Internet Explorer main window.

getHWND retrieves the handle to the Microsoft® Internet Explorer main window.

getLeft retrieves the screen coordinate of the left edge of the Microsoft® Internet Explorer main window.

getLocationName retrieves the name of the resource that Microsoft® Internet Explorer is currently displaying.

getLocationURL retrieves the URL of the resource that Microsoft® Internet Explorer is currently displaying.

getMenuBar retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer menu bar is visible.

getOffline retrieves a Boolean value indicating whether the WebBrowser control is currently operating in offline mode.

getPath retrieves the full path of the Microsoft® Internet Explorer application.

GetProperty retrieves the value of a property associated with the given object.

getReadyState retrieves the ready state of the object.

getRegisterAsBrowser retrieves a Boolean value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

getRegisterAsDropTarget retrieves a Boolean value indicating whether the WebBrowser control is registered as a drop target for navigation.

getResizable retrieves the InternetExplorer object's resizable property.

getSilent retrieves a Boolean value indicating whether any dialog boxes can be shown.

getStatusBar retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer status bar is visible.

getStatusText retrieves the text of the Microsoft® Internet Explorer status bar.

getTheaterMode retrieves a value indicating whether the WebBrowser control is in theater mode.

getToolBar retrieves a value that indicates whether the Microsoft® Internet Explorer toolbar is visible.

getTop retrieves the screen coordinate of the top edge of the Microsoft® Internet Explorer main window.

getTopLevelContainer retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is the top-level container of the WebBrowser control.

getType retrieves the type name of the contained document object.

getVisible retrieves a Boolean value that indicates whether the object is visible or hidden.

getWidth retrieves the width of the Microsoft® Internet Explorer main window.

GoBack navigates backward one item in the history list.

GoForward navigates forward one item in the history list.

GoHome navigates to the current home or start page.

GoSearch navigates to the current search page.

Navigate navigates to a resource identified by a Uniform Resource Locator (URL) or to the file identified by a full path.

Navigate2 navigates the browser to a location that may not be able to be expressed as a URL, such as a pointer to an item identifier list (PIDL) for an entity in the Microsoft® Windows® shell namespace.

PutProperty sets the value of a property associated with the given object.

QueryStatusWB implements a wrapper that allows you to query an OLE object for the status of commands using the IOleCommandTarget::QueryStatus method.

Quit closes the Microsoft® Internet Explorer application.

Refresh reloads the file that Microsoft® Internet Explorer is currently displaying.

Refresh2 reloads the file that Microsoft® Internet Explorer is currently displaying. Unlike IWebBrowser2::Refresh, this method contains a parameter that specifies the refresh level.

removeDWebBrowserEventsEventListener removes the specified listener so it no longer receives events.

removeWebBrowserEventListener removes the specified listener so it no longer receives events.

setAddressBar shows or hides the Microsoft® Internet Explorer object's address bar.

setFullScreen sets Microsoft® Internet Explorer to either full-screen or normal window mode.

setHeight sets the height of the Microsoft® Internet Explorer main window.

setLeft sets the horizontal position of the Microsoft® Internet Explorer main window.

setMenuBar shows or hides the Microsoft® Internet Explorer menu bar.

setOffline sets a value indicating whether the WebBrowser control is currently operating in offline mode. In offline mode, the browser is forced to read HTML pages from the local cache rather than from the source document.

setRegisterAsBrowser sets a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

setRegisterAsDropTarget sets a value indicating whether the WebBrowser control is registered as a drop target for navigation.

setResizable sets the Microsoft® Internet Explorer object's resizable property.

setSilent sets a value indicating whether any dialog boxes can be shown.

setStatusBar shows or hides the Microsoft® Internet Explorer status bar.

setStatusText sets the text of the Microsoft® Internet Explorer status bar.

setTheaterMode sets the TheaterMode property for the WebBrowser control.

setToolBar shows or hides the Microsoft® Internet Explorer toolbar.

setTop sets the vertical position of the Microsoft® Internet Explorer main window.

setWidth sets the width of the Microsoft® Internet Explorer main window.

ShowBrowserBar shows or hides a specified browser bar.

Stop cancels any pending navigation or download operation and stops any dynamic page elements, such as background sounds and animations.


_getName (WebBrowser Class)

 Microsoft SDK for Java

_getName

This method of the WebBrowser class retrieves the name of the object that contains the WebBrowser control used by Microsoft® Internet Explorer.

Syntax

public synchronized java.lang.String _getName();


_getParent (WebBrowser Class)

 Microsoft SDK for Java

_getParent

This method of the WebBrowser class retrieves a pointer to the IDispatch interface of the object that contains the WebBrowser control.

Syntax

public synchronized java.lang.Object _getParent();


_setVisible (WebBrowser Class)

 Microsoft SDK for Java

_setVisible

This method of the WebBrowser class sets the visibility state of the object.

Syntax

public synchronized void _setVisible(boolean pBool);

Parameters

pBool Specifies the visible state of Microsoft® Internet Explorer. If TRUE, the window is visible; if FALSE, it is hidden. The default value is FALSE.


addDWebBrowserEventsEventListener (WebBrowser Class)

 Microsoft SDK for Java

addDWebBrowserEventsEventListener

This method of the WebBrowser class registers the specified listener to receive DWebBrowserEvents events.

Syntax

public void addDWebBrowserEventsEventListener(DWebBrowserEventsEventListener
listener);

Parameters

listener The listener that is to receive DWebBrowserEvents2 events.


addWebBrowserEventListener (WebBrowser Class)

 Microsoft SDK for Java

addWebBrowserEventListener

This method of the WebBrowser class registers the specified listener to receive WebBrowserEvent events.

Syntax

public void addWebBrowserEventListener(WebBrowserEventListener
listener);

Parameters

listener The listener that is to receive WebBrowserEvent events.


ClientToWindow (WebBrowser Class)

 Microsoft SDK for Java

ClientToWindow

This method of the WebBrowser class converts the client coordinates of a point to window coordinates.

Syntax

public synchronized void ClientToWindow(int[] pcx, int[] pcy);

Parameters

pcx | Specifies the x-coordinate of the point in client coordinates.
pcy | Specifies the y-coordinate of the point in client coordinates.


enableEvents (WebBrowser Class)

 Microsoft SDK for Java

enableEvents

This method of the WebBrowser class registers the WebBrowser control to receive events.

Syntax

public synchronized void enableEvents();


ExecWB (WebBrowser Class)

 Microsoft SDK for Java

ExecWB

This method of the WebBrowser class implements a wrapper that allows you to execute a command on an OLE object using the IOleCommandTarget::Exec method.

Syntax

public synchronized void ExecWB(int cmdID, int cmdexecopt,
com.ms.com.Variant pvaIn, com.ms.com.Variant pvaOut);

Parameters

cmdID | The identifier of the command to execute.
cmdexecopt | The options set for executing the command.
pvaIn | A variant used for specifying command input arguments.
pvaOut | A variant used for specifying command output arguments.


getAddressBar (WebBrowser Class)

 Microsoft SDK for Java

getAddressBar

This method of the WebBrowser class retrieves a Boolean value that indicates whether the Internet Explorer object's address bar is visible.

Syntax

public synchronized boolean getAddressBar();


getApplication (WebBrowser Class)

 Microsoft SDK for Java

getApplication

This method of the WebBrowser class retrieves the Automation interface supported by the Microsoft® Internet Explorer application.

Syntax

public synchronized java.lang.Object getApplication();


getBusy (WebBrowser Class)

 Microsoft SDK for Java

getBusy

This method of the WebBrowser class retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is engaged in a downloading operation or other activity.

Syntax

public synchronized boolean getBusy();


getContainer (WebBrowser Class)

 Microsoft SDK for Java

getContainer

This method of the WebBrowser class retrieves a pointer to the IDispatch interface of the container.

Syntax

public synchronized java.lang.Object getContainer();


getDocument (WebBrowser Class)

 Microsoft SDK for Java

getDocument

This method of the WebBrowser class retrieves a pointer to the IDispatch interface of the Active Document object.

Syntax

public synchronized java.lang.Object getDocument();


getFullName (WebBrowser Class)

 Microsoft SDK for Java

getFullName

This method of the WebBrowser class retrieves the fully qualified path of the Microsoft® Internet Explorer executable file.

Syntax

public synchronized java.lang.String getFullName();


getFullScreen (WebBrowser Class)

 Microsoft SDK for Java

getFullScreen

This method of the WebBrowser class retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is in full-screen or normal window mode.

Syntax

public synchronized boolean getFullScreen();


getHeight (WebBrowser Class)

 Microsoft SDK for Java

getHeight

This method of the WebBrowser class retrieves the height of the Microsoft® Internet Explorer main window.

Syntax

public synchronized int getHeight();


getHWND (WebBrowser Class)

 Microsoft SDK for Java

getHWND

This method of the WebBrowser class retrieves the handle to the Microsoft® Internet Explorer main window.

Syntax

public synchronized int getHWND();


getLeft (WebBrowser Class)

 Microsoft SDK for Java

getLeft

This method of the WebBrowser class retrieves the screen coordinate of the left edge of the Microsoft® Internet Explorer main window.

Syntax

public synchronized int getLeft();


getLocationName (WebBrowser Class)

 Microsoft SDK for Java

getLocationName

This method of the WebBrowser class retrieves the name of the resource that Microsoft® Internet Explorer is currently displaying.

Syntax

public synchronized java.lang.String getLocationName();


getLocationURL (WebBrowser Class)

 Microsoft SDK for Java

getLocationURL

This method of the WebBrowser class retrieves the URL of the resource that Microsoft® Internet Explorer is currently displaying.

Syntax

public synchronized java.lang.String getLocationURL();


getMenuBar (WebBrowser Class)

 Microsoft SDK for Java

getMenuBar

This method of the WebBrowser class retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer menu bar is visible.

Syntax

public synchronized boolean getMenuBar();


getOffline (WebBrowser Class)

 Microsoft SDK for Java

getOffline

This method of the WebBrowser class retrieves a Boolean value indicating whether the WebBrowser control is currently operating in offline mode.

Syntax

public synchronized boolean getOffline();


getPath (WebBrowser Class)

 Microsoft SDK for Java

getPath

This method of the WebBrowser class retrieves the full path of the Microsoft® Internet Explorer application.

Syntax

public synchronized java.lang.String getPath();


GetProperty (WebBrowser Class)

 Microsoft SDK for Java

GetProperty

This method of the WebBrowser class retrieves the value of a property associated with the given object.

Syntax

public synchronized com.ms.com.Variant GetProperty(String Property);

Parameters

Property The name of the property to retrieve.


getReadyState (WebBrowser Class)

 Microsoft SDK for Java

getReadyState

This method of the WebBrowser class retrieves the ready state of the object.

Syntax

public synchronized int getReadyState();


getRegisterAsBrowser (WebBrowser Class)

 Microsoft SDK for Java

getRegisterAsBrowser

This method of the WebBrowser class retrieves a Boolean value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

Syntax

public synchronized boolean getRegisterAsBrowser();


getRegisterAsDropTarget (WebBrowser Class)

 Microsoft SDK for Java

getRegisterAsDropTarget

This method of the WebBrowser class retrieves a Boolean value indicating whether the WebBrowser control is registered as a drop target for navigation.

Syntax

public synchronized boolean getRegisterAsDropTarget();


getResizable (WebBrowser Class)

 Microsoft SDK for Java

getResizable

This method of the WebBrowser class retrieves the InternetExplorer object's resizable property.

Syntax

public synchronized boolean getResizable();


getSilent (WebBrowser Class)

 Microsoft SDK for Java

getSilent

This method of the WebBrowser class retrieves a Boolean value indicating whether any dialog boxes can be shown.

Syntax

public synchronized boolean getSilent();


getStatusBar (WebBrowser Class)

 Microsoft SDK for Java

getStatusBar

This method of the WebBrowser class retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer status bar is visible.

Syntax

public synchronized boolean getStatusBar();


getStatusText (WebBrowser Class)

 Microsoft SDK for Java

getStatusText

This method of the WebBrowser class retrieves the text of the Microsoft® Internet Explorer status bar.

Syntax

public synchronized java.lang.String getStatusText();


getTheaterMode (WebBrowser Class)

 Microsoft SDK for Java

getTheaterMode

This method of the WebBrowser class retrieves a value indicating whether the WebBrowser control is in theater mode.

Syntax

public synchronized boolean getTheaterMode();


getToolBar (WebBrowser Class)

 Microsoft SDK for Java

getToolBar

This method of the WebBrowser class retrieves a value that indicates whether the Microsoft® Internet Explorer toolbar is visible.

Syntax

public synchronized int getToolBar();


getTop (WebBrowser Class)

 Microsoft SDK for Java

getTop

This method of the WebBrowser class retrieves the screen coordinate of the top edge of the Microsoft® Internet Explorer main window.

Syntax

public synchronized int getTop();


getTopLevelContainer (WebBrowser Class)

 Microsoft SDK for Java

getTopLevelContainer

This method of the WebBrowser class retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is the top-level container of the WebBrowser control.

Syntax

public synchronized boolean getTopLevelContainer();


getType (WebBrowser Class)

 Microsoft SDK for Java

getType

This method of the WebBrowser class retrieves the type name of the contained document object.

Syntax

public synchronized java.lang.String getType();


getVisible (WebBrowser Class)

 Microsoft SDK for Java

getVisible

This method of the WebBrowser class retrieves a Boolean value that indicates whether the object is visible or hidden.

Syntax

public synchronized boolean getVisible();


getWidth (WebBrowser Class)

 Microsoft SDK for Java

getWidth

This method of the WebBrowser class retrieves the width of the Microsoft® Internet Explorer main window.

Syntax

public synchronized int getWidth();


GoBack (WebBrowser Class)

 Microsoft SDK for Java

GoBack

This method of the WebBrowser class navigates backward one item in the history list.

Syntax

public synchronized void GoBack();


GoForward (WebBrowser Class)

 Microsoft SDK for Java

GoForward

This method of the WebBrowser class navigates forward one item in the history list.

Syntax

public synchronized void GoForward();


GoHome (WebBrowser Class)

 Microsoft SDK for Java

GoHome

This method of the WebBrowser class navigates to the current home or start page.

Syntax

public synchronized void GoHome();


GoSearch (WebBrowser Class)

 Microsoft SDK for Java

GoSearch

This method of the WebBrowser class navigates to the current search page.

Syntax

public synchronized void GoSearch();


Navigate (WebBrowser Class)

 Microsoft SDK for Java

Navigate

This method of the WebBrowser class navigates to a resource identified by a Uniform Resource Locator (URL) or to the file identified by a full path.

Syntax

public synchronized void Navigate(java.lang.String URL,
com.ms.com.Variant Flags, com.ms.com.Variant TargetFrameName,
com.ms.com.Variant PostData, com.ms.com.Variant Headers);

Parameters

URL | Required. A string expression that evaluates to the URL, full path, or Universal Naming Convention (UNC) the location and name of the resource to display.
Flags | Optional. A value that specifies whether to add the resource to the history list, whether to read from or write to the cache, and whether to display the resource in a new window. It can be a combination of the following values: navOpenInNewWindow 1 Open the resource or file in a new window. navNoHistory 2 Do not add the resource or file to the history list. The new page replaces the current page in the list. navNoReadFromCache 4 Do not read from the disk cache for this navigation. navNoWriteToCache 8 Do not write the results of this navigation to the disk cache.
TargetFrameName | Optional. String expression that evaluates to the name of an HTML frame in the URL to display in the browser window. The possible values for this parameter are: _BLANK Load the link into a new unnamed window. _PARENT Load the link into the immediate parent of the document the link is in. _SELF Load the link into the same window the link was clicked in. _TOP Load the link into the full body of the current window. <WINDOW_NAME> A named HTML frame. If no frame or window exists that matches the specified target name, a new window is opened for the specified link.
PostData | Optional. Data to send to the server during the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form to a program or script. If PostData does not specify any post data, the Navigate method issues an HTTP GET transaction. PostData is ignored if the URL is not an HTTP URL.
Headers | Optional. A value that specifies additional HTTP headers to send to the server. These headers are added to the default Microsoft® Internet Explorer headers. The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code. Headers is ignored if the URL is not an HTTP URL.


Navigate2 (WebBrowser Class)

 Microsoft SDK for Java

Navigate2

This method of the WebBrowser class navigates the browser to a location that may not be able to be expressed as a URL, such as a pointer to an item identifier list (PIDL) for an entity in the Microsoft® Windows® shell namespace.

Syntax

public synchronized void Navigate2(com.ms.com.Variant URL,
com.ms.com.Variant Flags, com.ms.com.Variant TargetFrameName,
com.ms.com.Variant PostData, com.ms.com.Variant Headers);

Parameters

URL | Required. A string expression that evaluates to the URL, full path, or Universal Naming Convention (UNC) the location and name of the resource to display.
Flags | Optional. A value that specifies whether to add the resource to the history list, whether to read from or write to the cache, and whether to display the resource in a new window. It can be a combination of the following values: navOpenInNewWindow 1 Open the resource or file in a new window. navNoHistory 2 Do not add the resource or file to the history list. The new page replaces the current page in the list. navNoReadFromCache 4 Do not read from the disk cache for this navigation. navNoWriteToCache 8 Do not write the results of this navigation to the disk cache.
TargetFrameName | Optional. String expression that evaluates to the name of an HTML frame in the URL to display in the browser window. The possible values for this parameter are: _BLANK Load the link into a new unnamed window. _PARENT Load the link into the immediate parent of the document the link is in. _SELF Load the link into the same window the link was clicked in. _TOP Load the link into the full body of the current window. <WINDOW_NAME> A named HTML frame. If no frame or window exists that matches the specified target name, a new window is opened for the specified link.
PostData | Optional. Data to send to the server during the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form to a program or script. If PostData does not specify any post data, the Navigate2 method issues an HTTP GET transaction. PostData is ignored if the URL is not an HTTP URL.
Headers | Optional. A value that specifies additional HTTP headers to send to the server. These headers are added to the default Microsoft® Internet Explorer headers. The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code. Headers is ignored if the URL is not an HTTP URL.


PutProperty (WebBrowser Class)

 Microsoft SDK for Java

PutProperty

This method of the WebBrowser class sets the value of a property associated with the given object.

Syntax

public synchronized void PutProperty(java.lang.String Property, com.ms.com.Variant vtValue);

Parameters

Property | The name of the property to set.
vtValue | The new value of the property.


QueryStatusWB (WebBrowser Class)

 Microsoft SDK for Java

QueryStatusWB

This method of the WebBrowser class implements a wrapper that allows you to query an OLE object for the status of commands using the IOleCommandTarget::QueryStatus method.

Syntax

public synchronized int QueryStatusWB(int cmdID);

Parameters

cmdID The identifier of the command on which the caller needs status information. This will be one of the OLECMDID values.


Quit (WebBrowser Class)

 Microsoft SDK for Java

Quit

This method of the WebBrowser class closes the Microsoft® Internet Explorer application.

Syntax

public synchronized void Quit();


Refresh (WebBrowser Class)

 Microsoft SDK for Java

Refresh

This method of the WebBrowser class reloads the file that Microsoft® Internet Explorer is currently displaying.

Syntax

public synchronized void Refresh();


Refresh2 (WebBrowser Class)

 Microsoft SDK for Java

Refresh2

This method of the WebBrowser class reloads the file that Microsoft® Internet Explorer is currently displaying. Unlike IWebBrowser2::Refresh, this method contains a parameter that specifies the refresh level.

Syntax

public synchronized void Refresh2(com.ms.com.Variant Level);

Parameters

Level Optional. An optional value that specifies the refresh level. It can be one of the following constants or values:

REFRESH_NORMAL 0

Perform a lightweight refresh that does not include sending the HTTP "pragma:nocache" header to the server.

REFRESH_IFEXPIRED 1

Perform a lightweight refresh if the page has expired.

REFRESH_COMPLETELY 3

Perform a full refresh that includes sending a "pragma:nocache" header to the server (HTTP URLs only).


removeDWebBrowserEventsEventListener (WebBrowser Class)

 Microsoft SDK for Java

removeDWebBrowserEventsEventListener

This method of the WebBrowser class removes the specified listener so it no longer receives events.

Syntax

public void
removeDWebBrowserEventsEventListener
(DWebBrowserEventsEventListener listener);

Parameters

listener The listener to be removed.


removeWebBrowserEventListener (WebBrowser Class)

 Microsoft SDK for Java

removeWebBrowserEventListener

This method of the WebBrowser class removes the specified listener so it no longer receives events.

Syntax

public void removeWebBrowserEventListener(WebBrowserEventListener listener);

Parameters

listener The listener to be removed.


setAddressBar (WebBrowser Class)

 Microsoft SDK for Java

setAddressBar

This method of the WebBrowser class shows or hides the Microsoft® Internet Explorer object's address bar.

Syntax

public synchronized void setAddressBar(boolean Value);

Parameters

Value Boolean expression that determines whether the address bar is visible. If TRUE, the address bar is visible; if FALSE, it is hidden. The default value is TRUE.


setFullScreen (WebBrowser Class)

 Microsoft SDK for Java

setFullScreen

This method of the WebBrowser class sets Microsoft® Internet Explorer to either full-screen or normal window mode.

Syntax

public synchronized void setFullScreen(boolean pbFullScreen);

Parameters

pbFullScreen If TRUE, the browser window is maximized; if FALSE, it is not.


setHeight (WebBrowser Class)

 Microsoft SDK for Java

setHeight

This method of the WebBrowser class sets the height of the Microsoft® Internet Explorer main window.

Syntax

public synchronized void setHeight(int Pixels);

Parameters

Pixels The vertical dimension of the frame window, in pixels.


setLeft (WebBrowser Class)

 Microsoft SDK for Java

setLeft

This method of the WebBrowser class sets the horizontal position of the Microsoft® Internet Explorer main window.

Syntax

public synchronized void setLeft(int Pixels);

Parameters

Pixels The distance between the internal left edge of the WebBrowser control and the left edge of its container, in pixels.


setMenuBar (WebBrowser Class)

 Microsoft SDK for Java

setMenuBar

This method of the WebBrowser class shows or hides the Microsoft® Internet Explorer menu bar.

Syntax

public synchronized void setMenuBar(boolean Visible);

Parameters

Visible Determines whether the menu bar is visible. If TRUE, the menu bar is visible; if FALSE, it is hidden. The default value is TRUE.


setOffline (WebBrowser Class)

 Microsoft SDK for Java

setOffline

This method of the WebBrowser class sets a value indicating whether the WebBrowser control is currently operating in offline mode. In offline mode, the browser is forced to read HTML pages from the local cache rather than from the source document.

Syntax

public synchronized void setOffline(boolean Offline);

Parameters

Offline Determines whether the WebBrowser control is in offline mode. If TRUE, the WebBrowser will read data about its current URL from its local cache. If FALSE, it will attempt to read the source document. The default value is FALSE.


setRegisterAsBrowser (WebBrowser Class)

 Microsoft SDK for Java

setRegisterAsBrowser

This method of the WebBrowser class sets a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

Syntax

public synchronized void setRegisterAsBrowser(boolean Register);

Parameters

Register Determines whether Microsoft® Internet Explorer is registered as a top-level browser. If TRUE, the WebBrowser is registered as a top-level browser; if FALSE, it is not a top-level browser. The default value is FALSE.


setRegisterAsDropTarget (WebBrowser Class)

 Microsoft SDK for Java

setRegisterAsDropTarget

This method of the WebBrowser class sets a value indicating whether the WebBrowser control is registered as a drop target for navigation.

Syntax

public synchronized void setRegisterAsDropTarget(boolean Register);

Parameters

Register Determines whether Internet Explorer is registered as a drop target for navigation. If TRUE, the WebBrowser is registered as a drop target; if FALSE, it is not a drop target. The default value is FALSE.


setResizable (WebBrowser Class)

 Microsoft SDK for Java

setResizable

This method of the WebBrowser class sets the Microsoft® Internet Explorer object's resizable property.

Syntax

public synchronized void setResizable(boolean Resizable);

Parameters

Resizable Sets the object's resizable property. If this value is TRUE, the object can be resized. If this value is FALSE, the object cannot be resized. The default value is TRUE.


setSilent (WebBrowser Class)

 Microsoft SDK for Java

setSilent

This method of the WebBrowser class sets a value indicating whether any dialog boxes can be shown.

Syntax

public synchronized void setSilent(boolean pbSilent);

Parameters

pbSilent Determines whether the WebBrowser can show any message or dialog boxes. If TRUE, dialog boxes will not be displayed; if FALSE, dialog boxes will be displayed. The default value is FALSE. Critical errors and security alerts are not suppressed.


setStatusBar (WebBrowser Class)

 Microsoft SDK for Java

setStatusBar

This method of the WebBrowser class shows or hides the Microsoft® Internet Explorer status bar.

Syntax

public synchronized void setStatusBar(boolean On);

Parameters

On Determines whether the status bar is visible. If TRUE, the status bar is visible; if FALSE, it is hidden. The default is TRUE.


setStatusText (WebBrowser Class)

 Microsoft SDK for Java

setStatusText

This method of the WebBrowser class sets the text of the Microsoft® Internet Explorer status bar.

Syntax

public synchronized void setStatusText(java.lang.String StatusText);

Parameters

StatusText The text for the status bar.


setTheaterMode (WebBrowser Class)

 Microsoft SDK for Java

setTheaterMode

This method of the WebBrowser class sets the TheaterMode property for the WebBrowser control.

Syntax

public synchronized void setTheaterMode(boolean TheaterMode);

Parameters

TheaterMode Determines whether Microsoft® Internet Explorer is in theater or normal window mode. If TRUE, the object is in theater mode; if FALSE, it is in normal mode. The default value is FALSE.


setToolBar (WebBrowser Class)

 Microsoft SDK for Java

setToolBar

This method of the WebBrowser class shows or hides the Microsoft® Internet Explorer toolbar.

Syntax

public synchronized void setToolBar(int Value);

Parameters

Value Determines whether the toolbar is visible. If TRUE, the toolbar is visible; if FALSE, it is hidden. The default is TRUE.


setTop (WebBrowser Class)

 Microsoft SDK for Java

setTop

This method of the WebBrowser class sets the vertical position of the Microsoft® Internet Explorer main window.

Syntax

public synchronized void setTop(int Pixels);

Parameters

Pixels Specifies the distance of the top of the Microsoft® Internet Explorer main window from the top of the screen, in pixels.


setWidth (WebBrowser Class)

 Microsoft SDK for Java

setWidth

This method of the WebBrowser class sets the width of the Microsoft® Internet Explorer main window.

Syntax

public synchronized void setWidth(int Pixels);

Parameters

Pixels Specifies the horizontal dimension of the frame window, in pixels.


ShowBrowserBar (WebBrowser Class)

 Microsoft SDK for Java

ShowBrowserBar

This method of the WebBrowser class shows or hides a specified browser bar.

Syntax

public synchronized void ShowBrowserBar(com.ms.com.Variant pvaClsid,
com.ms.com.Variant pvarShow, com.ms.com.Variant pvarSize);

Parameters

pvaClsid | Required. A string containing the class identifier of the browser bar to show or hide. This object must be registered as an Explorer Bar object with the CATID_InfoBand component category. The standard browser bars use the following class identifiers: Browser Bar NameClass ID Search{30D02401-6A81-11D0-8274-00C04FD5AE38} Favorites{EFA24E61-B078-11D0-89E4-00C04FC9E26E} History{EFA24E62-B078-11D0-89E4-00C04FC9E26E} Channels{EFA24E63-B078-11D0-89E4-00C04FC9E26E}
pvarShow | Optional. A Boolean value that specifies whether the browser bar should be shown or hidden. If this is TRUE, the browser bar is shown. If this is FALSE, the browser bar is hidden. The default value is TRUE.
pvarSize | Optional. Not currently used.


Stop (WebBrowser Class)

 Microsoft SDK for Java

Stop

This method of the WebBrowser class cancels any pending navigation or download operation and stops any dynamic page elements, such as background sounds and animations.

Syntax

public synchronized void Stop();


CommandStateChangeConstants Interface

The CommandStateChangeConstants interface of the com.ms.ie package defines the constants for the CommandStateChange method of the DWebBrowserEvents2 interface.

public interface CommandStateChangeConstants
{
  // Fields
  public static final int CSC_NAVIGATEBACK;
  public static final int CSC_NAVIGATEFORWARD;
  public static final int CSC_UPDATECOMMANDS;
}


Fields (CommandStateChangeConstants Interface)

 Microsoft SDK for Java

CommandStateChangeConstants Interface Fields

The CommandStateChangeConstants interface has the fields shown in the following table.

Field | Value | Description
CSC_UPDATECOMMANDS | -1 | The enabled state of a toolbar button may have changed; the Enable parameter should be ignored.
CSC_NAVIGATEFORWARD | 1 | The enabled state of the Forward button has changed.
CSC_NAVIGATEBACK | 3 | The enabled state of the Back button has changed.


DWebBrowserEvents Interface (com.ms.ie package)

 Microsoft SDK for Java

DWebBrowserEvents Interface

The DWebBrowserEvents interface of the com.ms.ie package is an older version of the event sink interface that is superseded by DWebBrowserEvents2.

public interface DWebBrowserEvents extends IUnknown
{
  // Methods
  public abstract void BeforeNavigate(String URL, int Flags, String TargetFrameName,
com.ms.com.Variant PostData,
String Headers, boolean[] Cancel);
  public abstract void CommandStateChange(int Command, boolean Enable);
  public abstract void DownloadBegin();
  public abstract void DownloadComplete();
  public abstract void FrameBeforeNavigate(String URL, int Flags, String TargetFrameName,
com.ms.com.Variant PostData, String Headers, boolean[] Cancel);
  public abstract void FrameNavigateComplete(String URL);
  public abstract void FrameNewWindow(String URL, int Flags, String TargetFrameName,
com.ms.com.Variant PostData, String Headers, boolean[] Cancel);
  public abstract void NavigateComplete(String URL);
  public abstract void NewWindow(String URL, int Flags, String TargetFrameName, com.ms.com.Variant PostData,
String Headers, boolean[] Processed);
  public abstract void ProgressChange(int Progress, int ProgressMax);
  public abstract void PropertyChange(String Property);
  public abstract void Quit(boolean[] Cancel);
  public abstract void StatusTextChange(String Text);
  public abstract void TitleChange(String Text);
  public abstract void WindowActivate();
  public abstract void WindowMove();
  public abstract void WindowResize();
}


Methods (DWebBrowserEvents Interface)

 Microsoft SDK for Java

DWebBrowserEvents Interface Methods

The DWebBrowserEvents interface has the following methods:

BeforeNavigate fires before a navigation occurs in the given WebBrowser (on either a window or frame set element).

CommandStateChange notifies an application that the enabled state of a WebBrowser command has changed.

DownloadBegin notifies an application that a navigation operation is beginning.

DownloadComplete notifies an application that a document has reached the READYSTATE_COMPLETE state.

FrameBeforeNavigate is fired when a new hyperlink is being navigated to in a frame.

FrameNavigateComplete is fired when a new hyperlink is being navigated to in a frame.

FrameNewWindow is fired when a new window should be created.

NavigateComplete fires after a navigation to a hyperlink is completed (on either a window or frame set element).

NewWindow occurs when a new window is to be created for displaying a resource.

ProgressChange notifies an application that the progress of a download operation has been updated.

PropertyChange notifies an application that the PutProperty method has changed the value of a property.

Quit notifies an application that the Microsoft® Internet Explorer application is ready to quit.

StatusTextChange notifies an application that the text of the status bar associated with the WebBrowser control has changed.

TitleChange notifies an application if the title of a document in the WebBrowser control becomes available or changes.

WindowActivate is fired when a window has been activated.

WindowMove is fired when a window has been moved.

WindowResize is fired when a window has been sized.


BeforeNavigate (DWebBrowserEvents Interface)

 Microsoft SDK for Java

BeforeNavigate

This method of the DWebBrowserEvents interface fires before a navigation occurs in the given WebBrowser (on either a window or frame set element).

Syntax

public void BeforeNavigate(java.lang.String URL, int Flags,
java.lang.String TargetFrameName, com.ms.com.Variant PostData,
java.lang.String Headers, boolean[] Cancel);

Parameters

URL | [in] The URL to be navigated to.
Flags | [in] Reserved for future use.
TargetFrameName | [in] The string that contains the name of the frame in which to display the resource; NULL if no named frame is targeted for the resource.
PostData | [in] The address of data to send to the server if the HTTP POST transaction is being used.
Headers | [in] Additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code.
Cancel | [out] The address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.


CommandStateChange (DWebBrowserEvents Interface)

 Microsoft SDK for Java

CommandStateChange

This method of the DWebBrowserEvents interface notifies an application that the enabled state of a WebBrowser command has changed.

Syntax

public void CommandStateChange(int Command, boolean Enable);

Parameters

Command | [in] The identifier of the command whose enabled state has changed.
Enable | [in] The enabled state. This parameter is TRUE if the command is enabled, or FALSE if it is disabled.


DownloadBegin (DWebBrowserEvents Interface)

 Microsoft SDK for Java

DownloadBegin

This method of the DWebBrowserEvents interface notifies an application that a navigation operation is beginning.

Syntax

public void DownloadBegin();


DownloadComplete (DWebBrowserEvents Interface)

 Microsoft SDK for Java

DownloadComplete

This method of the DWebBrowserEvents interface notifies an application that a document has reached the READYSTATE_COMPLETE state.

Syntax

public void DownloadComplete();


FrameBeforeNavigate (DWebBrowserEvents Interface)

 Microsoft SDK for Java

FrameBeforeNavigate

This method of the DWebBrowserEvents interface is fired when a new hyperlink is being navigated to in a frame.

Syntax

public void FrameBeforeNavigate(java.lang.String URL, int Flags,
java.lang.String TargetFrameName, com.ms.com.Variant PostData,
java.lang.String Headers, boolean[] Cancel);

Parameters

URL | [in] The URL to be navigated to.
Flags | [in] Reserved for future use.
TargetFrameName | [in] The string that contains the name of the frame in which to display the resource, or NULL if no named frame is targeted for the resource.
PostData | [in] The address of data to send to the server if the HTTP POST transaction is being used.
Headers | [in] Additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code.
Cancel | [out] The address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.


FrameNavigateComplete (DWebBrowserEvents Interface)

 Microsoft SDK for Java

FrameNavigateComplete

This method of the DWebBrowserEvents interface is fired when a new hyperlink is being navigated to in a frame.

Syntax

public void FrameNavigateComplete(java.lang.String URL);

Parameters

URL [in] The URL, UNC file name, or PIDL that was navigated to.


FrameNewWindow (DWebBrowserEvents Interface)

 Microsoft SDK for Java

FrameNewWindow

This method of the DWebBrowserEvents interface is fired when a new window should be created.

Syntax

public void FrameNewWindow(java.lang.String URL, int Flags,
java.lang.String TargetFrameName, com.ms.com.Variant PostData,
java.lang.String Headers, boolean[] Processed);

Parameters

URL | [in] The URL to be navigated to.
Flags | [in] Reserved for future use.
TargetFrameName | [in] The string that contains the name of the frame in which to display the resource, or NULL if no named frame is targeted for the resource.
PostData | [in] The address of data to send to the server if the HTTP POST transaction is being used.
Headers | [in] Additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code.
Processed | [out] The address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation or to FALSE to allow it to proceed.


NavigateComplete (DWebBrowserEvents Interface)

 Microsoft SDK for Java

NavigateComplete

This method of the DWebBrowserEvents interface fires after a navigation to a hyperlink is completed (on either a window or frame set element).

Syntax

public void NavigateComplete(java.lang.String URL);

Parameters

URL [in] The URL, UNC file name, or PIDL that was navigated to.


NewWindow (DWebBrowserEvents Interface)

 Microsoft SDK for Java

NewWindow

This method of the DWebBrowserEvents interface occurs when a new window is to be created for displaying a resource. This event precedes the creation of a new window from within the WebBrowser (for example, in response to a navigation targeted to a new window, or to a scripted window.open method).

Syntax

public void NewWindow(java.lang.String URL, int Flags,
java.lang.String TargetFrameName,
com.ms.com.Variant PostData, java.lang.String Headers,
boolean[] Processed);

Parameters

URL | [in] The URL to be navigated to.
Flags | [in] Reserved for future use.
TargetFrameName | [in] The string that contains the name of the frame in which to display the resource, or NULL if no named frame is targeted for the resource.
PostData | [in] The address of data to send to the server if the HTTP POST transaction is being used.
Headers | [in] Additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code.
Processed | [out] The address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.


ProgressChange (DWebBrowserEvents Interface)

 Microsoft SDK for Java

ProgressChange

This method of the DWebBrowserEvents interface notifies an application that the progress of a download operation has been updated.

Syntax

public void ProgressChange(int Progress, int ProgressMax);

Parameters

Progress | [in] The amount of total progress to show, or -1 when progress is complete.
ProgressMax | [in] The maximum progress value.


PropertyChange (DWebBrowserEvents Interface)

 Microsoft SDK for Java

PropertyChange

This method of the DWebBrowserEvents interface notifies an application that the PutProperty method has changed the value of a property.

Syntax

public void PropertyChange(java.lang.String Property);

Parameters

Property Caller-allocated buffer that contains the name of the property.


Quit (DWebBrowserEvents Interface)

 Microsoft SDK for Java

Quit

This method of the DWebBrowserEvents interface notifies an application that the Internet Explorer application is ready to quit.

Syntax

public void Quit(boolean[] Cancel);

Parameters

Cancel A Boolean flag that is set to TRUE to quit the application, FALSE otherwise.


StatusTextChange (DWebBrowserEvents Interface)

 Microsoft SDK for Java

StatusTextChange

This method of the DWebBrowserEvents interface notifies an application that the text of the status bar associated with the WebBrowser control has changed.

Syntax

public void StatusTextChange(java.lang.String Text);

Parameters

Text [in] The new status bar text.


TitleChange (DWebBrowserEvents Interface)

 Microsoft SDK for Java

TitleChange

This method of the DWebBrowserEvents interface notifies an application if the title of a document in the WebBrowser control becomes available or changes.

Syntax

public void TitleChange(java.lang.String Text);

Parameters

Text [in] The caller-allocated buffer that contains the new document title.


WindowActivate (DWebBrowserEvents Interface)

 Microsoft SDK for Java

WindowActivate

This method of the DWebBrowserEvents interface is fired when window has been activated.

Syntax

public void WindowActivate();


WindowMove (DWebBrowserEvents Interface)

 Microsoft SDK for Java

WindowMove

This method of the DWebBrowserEvents interface is fired when window has been moved.

Syntax

public void WindowMove();


WindowResize (DWebBrowserEvents Interface)

 Microsoft SDK for Java

WindowResize

This method of the DWebBrowserEvents interface is fired when a window has been sized.

Syntax

public void WindowResize();


DWebBrowserEvents2 Interface (com.ms.ie package)

 Microsoft SDK for Java

DWebBrowserEvents2 Interface

The DWebBrowserEvents2 interface of the com.ms.ie package is the Web browser control events interface.

public interface DWebBrowserEvents2 extends IUnknown
{
  // Methods
  public abstract void BeforeNavigate2(Object pDisp, com.ms.com.Variant URL, com.ms.com.Variant Flags,
com.ms.com.Variant TargetFrameName, com.ms.com.Variant PostData,
com.ms.com.Variant Headers, boolean[]Cancel);
  public abstract void CommandStateChange(int Command, boolean Enable);
  public abstract void DocumentComplete(Object pDisp,
com.ms.com.Variant URL);
  public abstract void DownloadBegin();
  public abstract void DownloadComplete();
  public abstract void NavigateComplete2(Object pDisp,
com.ms.com.Variant URL);
  public abstract void NewWindow2(Object[] pDisp, boolean[] Cancel);
  public abstract void OnFullScreen(boolean FullScreen);
  public abstract void OnMenuBar(boolean MenuBar);
  public abstract void OnQuit();
  public abstract void OnStatusBar(boolean StatusBar);
  public abstract void OnTheaterMode(boolean TheaterMode);
  public abstract void OnToolBar(boolean ToolBar);
  public abstract void OnVisible(boolean Visible);
  public abstract void ProgressChange(int Progress, int ProgressMax);
  public abstract void PropertyChange(String szProperty);
  public abstract void StatusTextChange(String Text);
  public abstract void TitleChange(String Text);
}


Methods (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

DWebBrowserEvents2 Interface Methods

The DWebBrowserEvents2 interface has the following methods:

BeforeNavigate2 fires before a navigation occurs in the given WebBrowser control (on either a window or frame set element).

CommandStateChange notifies an application that the enabled state of a WebBrowser command has changed.

DocumentComplete notifies an application that a document has reached the READYSTATE_COMPLETE state.

DownloadBegin notifies an application that a navigation operation is beginning.

DownloadComplete occurs when a navigation operation finishes, is halted, or fails.

NavigateComplete2 fires after a navigation to a hyperlink is completed (on either a window or frame set element).

NewWindow2 occurs when a new window is to be created for displaying a resource. This event precedes the creation of a new window from within the WebBrowser (for example, in response to a navigation targeted to a new window, or to a scripted window.open method).

OnFullScreen occurs when the FullScreen property has changed.

OnMenuBar occurs when the MenuBar property is changed.

OnQuit notifies an application that the Internet Explorer application is ready to quit.

OnStatusBar occurs when the StatusBar property is changed.

OnTheaterMode occurs when the TheaterMode property is changed.

OnToolBar occurs when the ToolBar property is changed.

OnVisible occurs when the window for the WebBrowser should be shown/hidden. This allows the host window to behave the same way the Microsoft® Internet Explorer window would.

ProgressChange notifies an application that the progress of a download operation has been updated.

PropertyChange notifies an application that the PutProperty method has changed the value of a property.

StatusTextChange notifies an application that the text of the status bar associated with the WebBrowser control has changed.

TitleChange notifies an application if the title of a document in the WebBrowser control becomes available or changes.


BeforeNavigate2 (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

BeforeNavigate2

This method of the DWebBrowserEvents2 interface fires before a navigation occurs in the given WebBrowser control (on either a window or frame set element).

Syntax

public void BeforeNavigate2(java.lang.Object pDisp, com.ms.com.Variant URL, com.ms.com.Variant Flags, com.ms.com.Variant TargetFrameName, com.ms.com.Variant PostData, com.ms.com.Variant Headers, boolean[] Cancel);

Parameters

pDisp | in] The address of the IDispatch interface for the WebBrowser object that represents the window or frame. This interface can be queried for the IWebBrowser2 interface.
URL | [in] The URL to be navigated to.
Flags | [in] Reserved for future use.
TargetFrameName | [in] The string that contains the name of the frame in which to display the resource, or NULL if no named frame is targeted for the resource.
PostData | [in] The address of data to send to the server if the HTTP POST transaction is being used.
Headers | [in] Additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code.
Cancel | [out] The address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.


CommandStateChange (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

CommandStateChange

This method of the DWebBrowserEvents2 interface notifies an application that the enabled state of a WebBrowser command has changed.

Syntax

public void CommandStateChange(int Command, boolean Enable);

Parameters

Command | [in] The identifier of the command whose enabled state has changed.
Enable | [in] The enabled state. This parameter is TRUE if the command is enabled, or FALSE if it is disabled.


DocumentComplete (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

DocumentComplete

This method of the DWebBrowserEvents2 interface notifies an application that a document has reached the READYSTATE_COMPLETE state.

Syntax

public void DocumentComplete(java.lang.Object pDisp, com.ms.com.Variant URL);

Parameters

pDisp | [in] Address of the IDispatch interface for the WebBrowser object that represents the window or frame in which the document has loaded. This interface can be queried for the IWebBrowser2 interface.
URL | [in] The string expression that evaluates to the URL, UNC file name, or PIDL that was navigated to. Note that this URL can be different from the URL that the browser was told to navigate to. One reason is that this URL is the canonicalized and qualified URL. For example, if an application specified a URL of "www.microsoft.com" in a call to the Navigate or Navigate2 method, the URL passed by DocumentComplete would be "http://www.microsoft.com/". Also, if the server has redirected the browser to a different URL, the redirected URL will be reflected here.


DownloadBegin (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

DownloadBegin

This method of the DWebBrowserEvents2 interface notifies an application that a navigation operation is beginning.

Syntax

public void DownloadBegin();


DownloadComplete (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

DownloadComplete

This method of the DWebBrowserEvents2 interface occurs when a navigation operation finishes, is halted, or fails. DownloadComplete fires after a navigation to a hyperlink is completed (on either a window or frame set element).

Syntax

public void DownloadComplete();


NavigateComplete2 (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

NavigateComplete2

This method of the DWebBrowserEvents2 interface fires after a navigation to a hyperlink is completed (on either a window or frame set element).

Syntax

public void NavigateComplete2(java.lang.Object pDisp, com.ms.com.Variant URL);

Parameters

pDisp | [in] The address of the IDispatch interface for the WebBrowser object that represents the window or frame in which the document has loaded. This interface can be queried for the IWebBrowser2 interface.
URL | [in] The string expression that evaluates to the URL, UNC file name, or PIDL that was navigated to. Note that this URL can be different from the URL that the browser was told to navigate to. One reason is that this URL is the canonicalized and qualified URL. For example, if an application specified a URL of "www.microsoft.com" in a call to the Navigate or Navigate2 method, the URL passed by DocumentComplete would be "http://www.microsoft.com/". Also, if the server has redirected the browser to a different URL, the redirected URL will be reflected here.


NewWindow2 (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

NewWindow2

This method of the DWebBrowserEvents2 interface occurs when a new window is to be created for displaying a resource. This event precedes the creation of a new window from within the WebBrowser (for example, in response to a navigation targeted to a new window, or to a scripted window.open method).

Syntax

public void NewWindow2(java.lang.Object[] ppDisp, boolean[] Cancel);

Parameters

ppDisp | [out] The address of an interface pointer that, optionally, receives the IDispatch interface pointer of a new WebBrowser or InternetExplorer object.
Cancel | [out] The address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or FALSE to allow it to proceed.


OnFullScreen (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

OnFullScreen

This method of the DWebBrowserEvents2 interface occurs when the FullScreen property has changed.

Syntax

public void OnFullScreen(boolean FullScreen);

Parameters

FullScreen [in] The Boolean value that is nonzero if Microsoft® Internet Explorer is in full-screen mode, or zero otherwise.


OnMenuBar (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

OnMenuBar

This method of the DWebBrowserEvents2 interface occurs when the MenuBar property is changed.

Syntax

public void OnMenuBar(boolean MenuBar);

Parameters

MenuBar [in] The Boolean value that is nonzero if Microsoft® Internet Explorer's menu bar is visible, or zero otherwise.


OnQuit (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

OnQuit

This method of the DWebBrowserEvents2 interface notifies an application that the Microsoft® Internet Explorer application is ready to quit.

Syntax

public void OnQuit();


OnStatusBar (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

OnStatusBar

This method of the DWebBrowserEvents2 interface occurs when the StatusBar property is changed.

Syntax

public void OnStatusBar(boolean StatusBar);

Parameters

StatusBar [in] The Boolean value that is nonzero if Microsoft® Internet Explorer's status bar is visible, or zero otherwise.


OnTheaterMode (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

OnTheaterMode

This method of the DWebBrowserEvents2 interface occurs when the TheaterMode property is changed.

Syntax

public void OnTheaterMode(boolean TheaterMode);

Parameters

TheaterMode [in] The Boolean value that is nonzero if Microsoft® Internet Explorer is in theater mode, or zero otherwise.


OnToolBar (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

OnToolBar

This method of the DWebBrowserEvents2 interface occurs when the ToolBar property is changed.

Syntax

public void OnToolBar(boolean ToolBar);

Parameters

ToolBar [in] The Boolean value that is nonzero if Microsoft® Internet Explorer's toolbar is visible, or zero otherwise.


OnVisible (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

OnVisible

This method of the DWebBrowserEvents2 interface occurs when the window for the WebBrowser should be shown/hidden. This allows the host window to behave the same way the Microsoft® Internet Explorer window would.

Syntax

public void OnVisible(boolean Visible);

Parameters

Visible [in] The Boolean value that is nonzero if the object is visible, or zero otherwise.


ProgressChange (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

ProgressChange

This method of the DWebBrowserEvents2 interface notifies an application that the progress of a download operation has been updated.

Syntax

public void ProgressChange(int Progress, int ProgressMax);

Parameters

Progress | [in] The amount of total progress to show, or -1 when progress is complete.
ProgressMax | [in] The maximum progress value.


PropertyChange (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

PropertyChange

This method of the DWebBrowserEvents2 interface notifies an application that the PutProperty method has changed the value of a property.

Syntax

public void PropertyChange(java.lang.String szProperty);

Parameters

szProperty The caller-allocated buffer that contains the name of the property.


StatusTextChange (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

StatusTextChange

This method of the DWebBrowserEvents2 interface notifies an application that the text of the status bar associated with the WebBrowser control has changed.

Syntax

public void StatusTextChange(java.lang.String Text);

Parameters

Text [in] The new status bar text.


TitleChange (DWebBrowserEvents2 Interface)

 Microsoft SDK for Java

TitleChange

This method of the DWebBrowserEvents2 interface notifies an application if the title of a document in the WebBrowser control becomes available or changes.

Syntax

public void TitleChange(java.lang.String Text);

Parameters

Text [in] The caller-allocated buffer that contains the new document title.


DWebBrowserEventsEventListener Interface (com.ms.ie package)

 Microsoft SDK for Java

DWebBrowserEventsEventListener Interface

The DWebBrowserEventsEventListener interface of the com.ms.ie package is an event listener for the WebBrowser class.

public interface DWebBrowserEventsEventListener
{
  // Methods
  public abstract void BeforeNavigate(String URL, int Flags, String
TargetFrameName, com.ms.com.Variant PostData,
String Headers, boolean[]Cancel);
  public abstract void CommandStateChange(int Command, boolean Enable);
  public abstract void DownloadBegin();
  public abstract void DownloadComplete();
  public abstract void FrameBeforeNavigate(String URL, int Flags, String TargetFrameName,
com.ms.com.Variant PostData, String Headers, boolean[] Cancel);
  public abstract void FrameNavigateComplete(String URL);
  public abstract void FrameNewWindow(String URL, int Flags, String TargetFrameName, com.ms.com.Variant PostData,
String Headers, boolean[] Cancel);
  public abstract void NavigateComplete(String URL);
  public abstract void NewWindow(String URL, int Flags, String
TargetFrameName, com.ms.com.Variant PostData,
String Headers, boolean[] Processed);
  public abstract void ProgressChange(int Progress, int ProgressMax);
  public abstract void PropertyChange(String Property);
  public abstract void Quit(boolean[] Cancel);
  public abstract void StatusTextChange(String Text);
  public abstract void TitleChange(String Text);
  public abstract void WindowActivate();
  public abstract void WindowMove();
  public abstract void WindowResize();
}


Methods (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

DWebBrowserEventsEventListener Interface Methods

The DWebBrowserEventsEventListener interface has the following methods:

BeforeNavigate fires before a navigation occurs in the given WebBrowser control (on either a window or frame set element).

CommandStateChange notifies an application that the enabled state of a WebBrowser command has changed.

DownloadBegin notifies an application that a navigation operation is beginning.

DownloadComplete occurs when a navigation operation finishes, is halted, or fails.

FrameBeforeNavigate is fired when a new hyperlink is being navigated to in a frame.

FrameNavigateComplete is fired when a new hyperlink is being navigated to in a frame.

FrameNewWindow is fired when a new window should be created.

NavigateComplete fires after a navigation to a hyperlink is completed (on either a window or frame set element).

NewWindow occurs when a new window is to be created for displaying a resource.

ProgressChange notifies an application that the progress of a download operation has been updated.

PropertyChange notifies an application that the PutProperty method has changed the value of a property.

Quit notifies an application that the Internet Explorer application is ready to quit.

StatusTextChange notifies an application that the text of the status bar associated with the WebBrowser control has changed.

TitleChange notifies an application if the title of a document in the WebBrowser control becomes available or changes.

WindowActivate is fired when a window has been activated.

WindowMove is fired when a window has been moved.

WindowResize is fired when a window has been sized.


BeforeNavigate (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

BeforeNavigate

This method of the DWebBrowserEventsEventListener interface fires before a navigation occurs in the given WebBrowser control (on either a window or frame set element).

Syntax

public void BeforeNavigate(java.lang.String URL, int Flags,
java.lang.String TargetFrameName, com.ms.com.Variant PostData,
java.lang.String Headers, boolean[] Cancel);

Parameters

URL | [in] The URL to be navigated to.
Flags | [in] Reserved for future use.
TargetFrameName | [in] The string that contains the name of the frame in which to display the resource, or NULL if no named frame is targeted for the resource.
PostData | [in] The address of data to send to the server if the HTTP POST transaction is being used.
Headers | [in] Additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code.
Cancel | [out] The address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.


CommandStateChange (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

CommandStateChange

This method of the DWebBrowserEventsEventListener interface notifies an application that the enabled state of a WebBrowser command has changed.

Syntax

public void CommandStateChange(int Command, boolean Enable);

Parameters

Command | [in] The identifier of the command whose enabled state has changed.
Enable | [in] The enabled state. This parameter is TRUE if the command is enabled, or FALSE if it is disabled.


DownloadBegin (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

DownloadBegin

This method of the DWebBrowserEventsEventListener interface notifies an application that a navigation operation is beginning.

Syntax

public void DownloadBegin();


DownloadComplete (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

DownloadComplete

This method of the DWebBrowserEventsEventListener interface occurs when a navigation operation finishes, is halted, or fails.

Syntax

public void DownloadComplete();


FrameBeforeNavigate (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

FrameBeforeNavigate

This method of the DWebBrowserEventsEventListener interface is fired when a new hyperlink is being navigated to in a frame.

Syntax

public void FrameBeforeNavigate(java.lang.String URL, int Flags,
java.lang.String TargetFrameName, com.ms.com.Variant PostData,
java.lang.String Headers, boolean[] Cancel);

Parameters

URL | [in] The URL to be navigated to.
Flags | [in] Reserved for future use.
TargetFrameName | [in] The string that contains the name of the frame in which to display the resource, or NULL if no named frame is targeted for the resource.
PostData | [in] The address of data to send to the server if the HTTP POST transaction is being used.
Headers | [in] Additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code.
Cancel | [out] The address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.


FrameNavigateComplete (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

FrameNavigateComplete

This method of the DWebBrowserEventsEventListener interface is fired when a new hyperlink is being navigated to in a frame.

Syntax

public void FrameNavigateComplete(java.lang.String URL);

Parameters

URL [in] The URL, UNC file name, or PIDL that was navigated to.


FrameNewWindow (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

FrameNewWindow

This method of the DWebBrowserEventsEventListener interface is fired when a new window should be created.

Syntax

public void FrameNewWindow(java.lang.String URL, int Flags,
java.lang.String TargetFrameName, com.ms.com.Variant PostData,
java.lang.String Headers, boolean[] Processed);

Parameters

URL | [in] The URL to be navigated to.
Flags | [in] Reserved for future use.
TargetFrameName | [in] The string that contains the name of the frame in which to display the resource, or NULL if no named frame is targeted for the resource.
PostData | [in] The address of data to send to the server if the HTTP POST transaction is being used.
Headers | [in] Additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code.
Processed | [out] The address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.


NavigateComplete (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

NavigateComplete

This method of the DWebBrowserEventsEventListener interface fires after a navigation to a hyperlink is completed (on either a window or frame set element).

Syntax

public void NavigateComplete(java.lang.String URL);

Parameters

URL [in] The URL, UNC file name, or PIDL that was navigated to.


NewWindow (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

NewWindow

This method of the DWebBrowserEventsEventListener interface occurs when a new window is to be created for displaying a resource. This event precedes the creation of a new window from within the WebBrowser (for example, in response to a navigation targeted to a new window, or to a scripted window.open method).

Syntax

public void NewWindow(java.lang.String URL, int Flags,
java.lang.String TargetFrameName, com.ms.com.Variant PostData,
java.lang.String Headers, boolean[] Processed);

Parameters

URL | [in] The URL to be navigated to.
Flags | [in] Reserved for future use.
TargetFrameName | [in] The string that contains the name of the frame in which to display the resource, or NULL if no named frame is targeted for the resource.
PostData | [in] The address of data to send to the server if the HTTP POST transaction is being used.
Headers | [in] Additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code.
Processed | [out] The address of a cancel flag. An application can set this parameter to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.


ProgressChange (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

ProgressChange

This method of the DWebBrowserEventsEventListener interface notifies an application that the progress of a download operation has been updated.

Syntax

public void ProgressChange(int Progress, int ProgressMax);

Parameters

Progress | [in] The amount of total progress to show, or -1 when progress is complete.
ProgressMax | [in] The maximum progress value.


PropertyChange (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

PropertyChange

This method of the DWebBrowserEventsEventListener interface notifies an application that the PutProperty method has changed the value of a property.

Syntax

public void PropertyChange(java.lang.String Property);

Parameters

Property The caller-allocated buffer that contains the name of the property.


Quit (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

Quit

This method of the DWebBrowserEventsEventListener interface notifies an application that the Microsoft® Internet Explorer application is ready to quit.

Syntax

public void Quit(boolean[] Cancel);

Parameters

Cancel A Boolean flag that is set to TRUE to quit the application, FALSE otherwise.


StatusTextChange (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

StatusTextChange

This method of the DWebBrowserEventsEventListener interface notifies an application that the text of the status bar associated with the WebBrowser control has changed.

Syntax

public void StatusTextChange(java.lang.String Text);

Parameters

Text [in] The new status bar text.


TitleChange (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

TitleChange

This method of the DWebBrowserEventsEventListener interface notifies an application if the title of a document in the WebBrowser control becomes available or changes.

Syntax

public void TitleChange(java.lang.String Text);

Parameters

Text [in] The caller-allocated buffer that contains the new document title.


WindowActivate (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

WindowActivate

This method of the DWebBrowserEventsEventListener interface is fired when a window has been activated.

Syntax

public void WindowActivate();


WindowMove (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

WindowMove

This method of the DWebBrowserEventsEventListener interface is fired when a window has been moved.

Syntax

public void WindowMove();


WindowResize (DWebBrowserEventsEventListener Interface)

 Microsoft SDK for Java

WindowResize

This method of the DWebBrowserEventsEventListener interface is fired when a window has been sized.

Syntax

public void WindowResize();


IShellUIHelper Interface (com.ms.ie package)

 Microsoft SDK for Java

IShellUIHelper Interface

The IShellUIHelper interface of the com.ms.ie package is the shell user interface helper control interface.

public interface IShellUIHelper extends IUnknown
{
  // Methods
  public abstract void AddChannel(String URL);
  public abstract void AddDesktopComponent(String URL, String Type, com.ms.com.Variant Left,
com.ms.com.Variant Top, com.ms.com.Variant Width,
com.ms.com.Variant Height);
  public abstract void AddFavorite(String URL, com.ms.com.Variant Title);
  public abstract void AutoCompleteSaveForm(com.ms.com.Variant Form);
  public abstract void ImportExportFavorites(boolean Import, String ImpExpPath);
  public abstract boolean IsSubscribed(String URL);
  public abstract void NavigateAndFind(String URL, String Query, com.ms.com.Variant TargetFrame);
  public abstract com.ms.com.Variant ShowBrowserUI(String Name, com.ms.com.Variant pvarIn);
}


Methods (IShellUIHelper Interface)

 Microsoft SDK for Java

IShellUIHelper Interface Methods

The IShellUIHelper interface has the following methods:

AddChannel adds a new channel to the list of channels.

AddDesktopComponent adds an item to the Microsoft® Active Desktop™.

AddFavorite displays the default user interface for creating a favorite, which is initialized using the specified parameters.

AutoCompleteSaveForm saves a specified form to AutoComplete data storage.

ImportExportFavorites handles the importing and exporting of Microsoft® Internet Explorer favorites.

IsSubscribed verifies if the user is subscribed to the specified URL.

NavigateAndFind navigates to the specified URL and selects the specified text.

ShowBrowserUI invokes the browser UI.


AddChannel (IShellUIHelper Interface)

 Microsoft SDK for Java

AddChannel

This method of the IShellUIHelper interface adds a new channel to the list of channels.

Syntax

public void AddChannel(java.lang.String URL);

Parameters

URL The URL of the channel's Channel Definition Format (CDF) file.


AddDesktopComponent (IShellUIHelper Interface)

 Microsoft SDK for Java

AddDesktopComponent

This method of the IShellUIHelper interface adds an item to the Microsoft® Active Desktop™.

Syntax

public void AddDesktopComponent(java.lang.String URL,
java.lang.String Type, com.ms.com.Variant Left,
com.ms.com.Variant Top, com.ms.com.Variant Width,
com.ms.com.Variant Height);

Parameters

URL | The string value that contains the URL of the desktop item.
Type | The string value that contains the desktop item type.
Left | The address of a VARIANT structure that contains the coordinate of the left edge of the desktop item. Passing this address is optional.
Top | The address of a VARIANT structure that contains the coordinate of the top edge of the desktop item. Passing this address is optional.
Width | The address of a VARIANT structure that contains the width of the desktop item. Passing this address is optional.
Height | The address of a VARIANT structure that contains the height of the desktop item. Passing this address is optional.


AddFavorite (IShellUIHelper Interface)

 Microsoft SDK for Java

AddFavorite

This method of the IShellUIHelper interface displays the default user interface for creating a favorite, which is initialized using the specified parameters.

Syntax

public void AddFavorite(java.lang.String URL, com.ms.com.Variant Title);

Parameters

URL | The string value that contains the URL.
Title | The string value that contains the name to be associated with the URL. You may pass an empty string.


AutoCompleteSaveForm (IShellUIHelper Interface)

 Microsoft SDK for Java

AutoCompleteSaveForm

This method of the IShellUIHelper interface saves a specified form to AutoComplete data storage.

Syntax

public void AutoCompleteSaveForm(com.ms.com.Variant Form);

Parameters

Form The address of a VARIANT that contains the form to save.


ImportExportFavorites (IShellUIHelper Interface)

 Microsoft SDK for Java

ImportExportFavorites

This method of the IShellUIHelper interface handles the importing and exporting of Microsoft® Internet Explorer favorites.

Syntax

public void ImportExportFavorites(boolean fImport,
java.lang.String strImpExpPath);

Parameters

fImport | The VARIANT_BOOL value that specifies if this is an import or export operation. VARIANT_TRUE indicates an import operation, while VARIANT_FALSE indicates an export operation.
strImpExpPath | The string value that contains the path to the location of the import or export file.


IsSubscribed (IShellUIHelper Interface)

 Microsoft SDK for Java

IsSubscribed

This method of the IShellUIHelper interface verifies if the user is subscribed to the specified URL.

Syntax

public boolean IsSubscribed(java.lang.String URL);

Parameters

URL The URL to check.


NavigateAndFind (IShellUIHelper Interface)

 Microsoft SDK for Java

NavigateAndFind

This method of the IShellUIHelper interface navigates to the specified URL and selects the specified text.

Syntax

public void NavigateAndFind(java.lang.String URL,
java.lang.String strQuery,
com.ms.com.Variant varTargetFrame);

Parameters

URL | The string value that contains the URL to navigate to.
strQuery | The string value that contains the specified text to select.
varTargetFrame | The address of a VARIANT that contains the name of the target frame.


ShowBrowserUI (IShellUIHelper Interface)

 Microsoft SDK for Java

ShowBrowserUI

This method of the IShellUIHelper interface invokes the browser UI.

Syntax

public com.ms.com.Variant ShowBrowserUI(java.lang.String bstrName,
com.ms.com.Variant pvarIn);

Parameters

bstrName | The string that contains the name of the UI to display.
pvarIn | The address of a VARIANT argument that is specific to the UI.


IWebBrowser2 Interface (com.ms.ie package)

 Microsoft SDK for Java

IWebBrowser2 Interface

The IWebBrowser2 interface of the com.ms.ie package enables applications to implement an instance of the WebBrowser control or control an instance of the Microsoft® Internet Explorer application.

public interface IWebBrowser2 extends IWebBroswerApp
{
  // Methods
  public abstract void ClientToWindow(int[] pcx, int[] pcy);
  public abstract void ExecWB(int cmdID, int cmdexecopt,
com.ms.com.Variant pvaIn, com.ms.com.Variant pvaOut);
  public abstract boolean getAddressBar();
  public abstract Object getApplication();
  public abstract boolean getBusy();
  public abstract Object getContainer();
  public abstract Object getDocument();
  public abstract String getFullName();
  public abstract boolean getFullScreen();
  public abstract int getHWND();
  public abstract int getHeight();
  public abstract int getLeft();
  public abstract String getLocationName();
  public abstract String getLocationURL();
  public abstract boolean getMenuBar();
  public abstract String getName();
  public abstract boolean getOffline();
  public abstract Object getParent();
  public abstract String getPath();
  public abstract com.ms.com.Variant GetProperty(String Property);
  public abstract int getReadyState();
  public abstract boolean getRegisterAsBrowser();
  public abstract boolean getRegisterAsDropTarget();
  public abstract boolean getResizable();
  public abstract boolean getSilent();
  public abstract boolean getStatusBar();
  public abstract String getStatusText();
  public abstract boolean getTheaterMode();
  public abstract int getToolBar();
  public abstract int getTop();
  public abstract boolean getTopLevelContainer();
  public abstract String getType();
  public abstract boolean getVisible();
  public abstract int getWidth();
  public abstract void GoBack();
  public abstract void GoForward();
  public abstract void GoHome();
  public abstract void GoSearch();
  public abstract void Navigate2(com.ms.com.Variant URL,
com.ms.com.Variant Flags, com.ms.com.Variant TargetFrameName,
com.ms.com.Variant PostData, com.ms.com.Variant Headers);
  public abstract void Navigate(String URL, com.ms.com.Variant Flags,
com.ms.com.Variant TargetFrameName, com.ms.com.Variant PostData,
com.ms.com.Variant Headers);
  public abstract void PutProperty(String Property, com.ms.com.Variant
vtValue);
  public abstract int QueryStatusWB(int cmdID);
  public abstract void Quit();
  public abstract void Refresh2(com.ms.com.Variant Level);
  public abstract void Refresh();
  public abstract void setAddressBar(boolean Visible);
  public abstract void setFullScreen(boolean FullScreen);
  public abstract void setHeight(int Pixels);
  public abstract void setLeft(int Pixels);
  public abstract void setMenuBar(boolean Visible);
  public abstract void setOffline(boolean Offline);
  public abstract void setRegisterAsBrowser(boolean Register);
  public abstract void setRegisterAsDropTarget(boolean Register);
  public abstract void setResizable(boolean Resizable);
  public abstract void setSilent(boolean Silent);
  public abstract void setStatusBar(boolean On);
  public abstract void setStatusText(String StatusText);
  public abstract void setTheaterMode(boolean TheaterMode);
  public abstract void setToolBar(int Value);
  public abstract void setTop(int Pixels);
  public abstract void setVisible(boolean Visible);
  public abstract void setWidth(int Pixels);
  public abstract void ShowBrowserBar(com.ms.com.Variant pvaClsid,
com.ms.com.Variant pvarShow, com.ms.com.Variant pvarSize);
  public abstract void Stop();
}


Methods (IWebBrowser2 Interface)

 Microsoft SDK for Java

IWebBrowser2 Interface Methods

The IWebBrowser2 interface has the following methods:

ClientToWindow converts the client coordinates of a point to window coordinates.

ExecWB implements a wrapper that allows you to execute a command on an OLE object using the IOleCommandTarget::Exec method.

getAddressBar retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer object's address bar is visible.

getApplication retrieves the Automation interface supported by the Microsoft® Internet Explorer application.

getBusy retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is engaged in a downloading operation or other activity.

getContainer retrieves a pointer to the IDispatch interface of the container.

getDocument retrieves a pointer to the IDispatch interface of the Active Document object.

getFullName retrieves the fully qualified path of the Microsoft® Internet Explorer executable file.

getFullScreen retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is in full-screen or normal window mode.

getHeight retrieves the height of the Microsoft® Internet Explorer main window.

getHWND retrieves the handle to the Microsoft® Internet Explorer main window.

getLeft retrieves the screen coordinate of the left edge of the Microsoft® Internet Explorer main window.

getLocationName retrieves the name of the resource that Microsoft® Internet Explorer is currently displaying.

getLocationURL retrieves the URL of the resource that Microsoft® Internet Explorer is currently displaying.

getMenuBar retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer menu bar is visible.

getName retrieves the name of the object that contains the WebBrowser control used by Microsoft® Internet Explorer.

getOffline retrieves a Boolean value indicating whether the WebBrowser control is currently operating in offline mode.

getParent retrieves a pointer to the IDispatch interface of the object that is the container of the WebBrowser control.

getPath retrieves the full path of the Microsoft® Internet Explorer application.

GetProperty retrieves the value of a property associated with the given object.

getReadyState retrieves the ready state of the object.

getRegisterAsBrowser retrieves a Boolean value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

getRegisterAsDropTarget retrieves a Boolean value indicating whether the WebBrowser control is registered as a drop target for navigation.

getResizable retrieves the InternetExplorer object's resizable property.

getSilent retrieves a Boolean value indicating whether any dialog boxes can be shown.

getStatusBar retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer status bar is visible.

getStatusText retrieves the text of the Microsoft® Internet Explorer status bar.

getTheaterMode retrieves a value indicating whether the WebBrowser control is in theater mode.

getToolBar retrieves a value that indicates whether the Microsoft® Internet Explorer toolbar is visible.

getTop retrieves the screen coordinate of the top edge of the Microsoft® Internet Explorer main window.

getTopLevelContainer retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is the top-level container of the WebBrowser control.

getType retrieves the type name of the contained document object.

getVisible retrieves a Boolean value that indicates whether the object is visible or hidden.

getWidth retrieves the width of the Microsoft® Internet Explorer main window.

GoBack navigates backward one item in the history list.

GoForward navigates forward one item in the history list.

GoHome navigates to the current home or start page.

GoSearch navigates to the current search page.

Navigate navigates to a resource identified by a Uniform Resource Locator (URL) or to the file identified by a full path.

Navigate2 navigates the browser to a location that may not be able to be expressed as a URL, such as a pointer to an item identifier list (PIDL) for an entity in the Microsoft® Windows® shell namespace.

PutProperty sets the value of a property associated with the given object.

QueryStatusWB implements a wrapper that allows you to query an OLE object for the status of commands using the IOleCommandTarget::QueryStatus method.

Quit closes the Microsoft® Internet Explorer application.

Refresh reloads the file that Microsoft® Internet Explorer is currently displaying.

Refresh2 reloads the file that Microsoft® Internet Explorer is currently displaying. Unlike IWebBrowser2.Refresh, this method contains a parameter that specifies the refresh level.

setAddressBar shows or hides the Microsoft® Internet Explorer object's address bar.

setFullScreen sets Microsoft® Internet Explorer to either full-screen or normal window mode.

setHeight sets the height of the Microsoft® Internet Explorer main window.

setLeft sets the horizontal position of the Microsoft® Internet Explorer main window.

setMenuBar shows or hides the Microsoft® Internet Explorer menu bar.

setOffline sets a value indicating whether the WebBrowser control is currently operating in offline mode. In offline mode, the browser is forced to read HTML pages from the local cache rather than from the source document.

setRegisterAsBrowser sets a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

setRegisterAsDropTarget sets a value indicating whether the WebBrowser control is registered as a drop target for navigation.

setResizable sets the Microsoft® Internet Explorer object's resizable property.

setSilent sets a value indicating whether any dialog boxes can be shown.

setStatusBar shows or hides the Microsoft® Internet Explorer status bar.

setStatusText sets the text of the Microsoft® Internet Explorer status bar.

setTheaterMode sets the TheaterMode property for the WebBrowser control.

setToolBar shows or hides the Microsoft® Internet Explorer toolbar.

setTop sets the vertical position of the Microsoft® Internet Explorer main window.

setVisible sets the visibility state of the object.

setWidth sets the width of the Microsoft® Internet Explorer main window.

ShowBrowserBar shows or hides a specified browser bar.

Stop cancels any pending navigation or download operation and stops any dynamic page elements, such as background sounds and animations.


ClientToWindow (IWebBrowser2 Interface)

 Microsoft SDK for Java

ClientToWindow

This method of the IWebBrowser2 interface converts the client coordinates of a point to window coordinates.

Syntax

public void ClientToWindow(int[] pcx, int[] pcy);

Parameters

pcx | Specifies the x-coordinate of the point in client coordinates.
pcy | Specifies the y-coordinate of the point in client coordinates.


ExecWB (IWebBrowser2 Interface)

 Microsoft SDK for Java

ExecWB

This method of the IWebBrowser2 interface implements a wrapper that allows you to execute a command on an OLE object using the IOleCommandTarget::Exec method.

Syntax

public void ExecWB(int cmdID, int cmdexecopt,
com.ms.com.Variant pvaIn, com.ms.com.Variant pvaOut);

Parameters

cmdID | [in] The OLECMDID value that specifies the command to execute.
cmdexecopt | [in] The OLECMDEXECOPT value that specifies the command options.
pvaIn | [in] The address of a VARIANT structure that contains command input arguments. This argument can be NULL.
pvaOut | [out, in] The address of a VARIANT structure that receives command output. This argument can be NULL.


getAddressBar (IWebBrowser2 Interface)

 Microsoft SDK for Java

getAddressBar

This method of the IWebBrowser2 interface retrieves a Boolean value that indicates whether the Internet Explorer object's address bar is visible.

Syntax

public boolean getAddressBar();


getApplication (IWebBrowser2 Interface)

 Microsoft SDK for Java

getApplication

This method of the IWebBrowser2 interface retrieves the automation interface supported by the Microsoft® Internet Explorer application.

Syntax

public java.lang.Object getApplication();


getBusy (IWebBrowser2 Interface)

 Microsoft SDK for Java

getBusy

This method of the IWebBrowser2 interface retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is engaged in a downloading operation or other activity.

Syntax

public boolean getBusy();


getContainer (IWebBrowser2 Interface)

 Microsoft SDK for Java

getContainer

This method of the IWebBrowser2 interface retrieves a pointer to the IDispatch interface of the container.

Syntax

public java.lang.Object getContainer();


getDocument (IWebBrowser2 Interface)

 Microsoft SDK for Java

getDocument

This method of the IWebBrowser2 interface retrieves a pointer to the IDispatch interface of the Active Document object.

Syntax

public java.lang.Object getDocument();


getFullName (IWebBrowser2 Interface)

 Microsoft SDK for Java

getFullName

This method of the IWebBrowser2 interface retrieves the fully qualified path of the Microsoft® Internet Explorer executable file.

Syntax

public java.lang.String getFullName();


getFullScreen (IWebBrowser2 Interface)

 Microsoft SDK for Java

getFullScreen

This method of the IWebBrowser2 interface retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is in full-screen or normal window mode.

Syntax

public boolean getFullScreen();


getHeight (IWebBrowser2 Interface)

 Microsoft SDK for Java

getHeight

This method of the IWebBrowser2 interface retrieves the height of the Microsoft® Internet Explorer main window.

Syntax

public int getHeight();


getHWND (IWebBrowser2 Interface)

 Microsoft SDK for Java

getHWND

This method of the IWebBrowser2 interface retrieves the handle to the Microsoft® Internet Explorer main window.

Syntax

public int getHWND();


getLeft (IWebBrowser2 Interface)

 Microsoft SDK for Java

getLeft

This method of the IWebBrowser2 interface retrieves the screen coordinate of the left edge of the Microsoft® Internet Explorer main window.

Syntax

public int getLeft();


getLocationName (IWebBrowser2 Interface)

 Microsoft SDK for Java

getLocationName

This method of the IWebBrowser2 interface retrieves the name of the resource that Microsoft® Internet Explorer is currently displaying.

Syntax

public java.lang.String getLocationName();


getLocationURL (IWebBrowser2 Interface)

 Microsoft SDK for Java

getLocationURL

This method of the IWebBrowser2 interface retrieves the URL of the resource that Microsoft® Internet Explorer is currently displaying.

Syntax

public java.lang.String getLocationURL();


getMenuBar (IWebBrowser2 Interface)

 Microsoft SDK for Java

getMenuBar

This method of the IWebBrowser2 interface retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer menu bar is visible.

Syntax

public boolean getMenuBar();


getName (IWebBrowser2 Interface)

 Microsoft SDK for Java

getName

This method of the IWebBrowser2 interface retrieves the name of the object that contains the WebBrowser control used by Microsoft® Internet Explorer.

Syntax

public java.lang.String getName();


getOffline (IWebBrowser2 Interface)

 Microsoft SDK for Java

getOffline

This method of the IWebBrowser2 interface retrieves a Boolean value indicating whether the WebBrowser control is currently operating in offline mode.

Syntax

public boolean getOffline();


getParent (IWebBrowser2 Interface)

 Microsoft SDK for Java

getParent

This method of the IWebBrowser2 interface retrieves a pointer to the IDispatch interface of the object that is the container of the WebBrowser control.

Syntax

public java.lang.Object getParent();


getPath (IWebBrowser2 Interface)

 Microsoft SDK for Java

getPath

This method of the IWebBrowser2 interface retrieves the full path of the Microsoft® Internet Explorer application.

Syntax

public java.lang.String getPath();


GetProperty (IWebBrowser2 Interface)

 Microsoft SDK for Java

GetProperty

This method of the IWebBrowser2 interface retrieves the value of a property associated with the given object.

Syntax

public com.ms.com.Variant GetProperty(java.lang.String Property);

Parameters

Property The name of the property to retrieve.


getReadyState (IWebBrowser2 Interface)

 Microsoft SDK for Java

getReadyState

This method of the IWebBrowser2 interface retrieves the ready state of the object.

Syntax

public int getReadyState();


getRegisterAsBrowser (IWebBrowser2 Interface)

 Microsoft SDK for Java

getRegisterAsBrowser

This method of the IWebBrowser2 interface retrieves a Boolean value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

Syntax

public boolean getRegisterAsBrowser();


getRegisterAsDropTarget (IWebBrowser2 Interface)

 Microsoft SDK for Java

getRegisterAsDropTarget

This method of the IWebBrowser2 interface retrieves a Boolean value indicating whether the WebBrowser control is registered as a drop target for navigation.

Syntax

public boolean getRegisterAsDropTarget();


getResizable (IWebBrowser2 Interface)

 Microsoft SDK for Java

getResizable

This method of the IWebBrowser2 interface retrieves the InternetExplorer object's resizable property.

Syntax

public boolean getResizable();


getSilent (IWebBrowser2 Interface)

 Microsoft SDK for Java

getSilent

This method of the IWebBrowser2 interface retrieves a Boolean value indicating whether any dialog boxes can be shown.

Syntax

public boolean getSilent();


getStatusBar (IWebBrowser2 Interface)

 Microsoft SDK for Java

getStatusBar

This method of the IWebBrowser2 interface retrieves a Boolean value that indicates whether the Microsoft® Internet Explorer status bar is visible.

Syntax

public boolean getStatusBar();


getStatusText (IWebBrowser2 Interface)

 Microsoft SDK for Java

getStatusText

This method of the IWebBrowser2 interface retrieves the text of the Microsoft® Internet Explorer status bar.

Syntax

public java.lang.String getStatusText();


getTheaterMode (IWebBrowser2 Interface)

 Microsoft SDK for Java

getTheaterMode

This method of the IWebBrowser2 interface retrieves a value indicating whether the WebBrowser control is in theater mode.

Syntax

public boolean getTheaterMode();


getToolBar (IWebBrowser2 Interface)

 Microsoft SDK for Java

getToolBar

This method of the IWebBrowser2 interface retrieves a value that indicates whether the Microsoft® Internet Explorer toolbar is visible.

Syntax

public int getToolBar();


getTop (IWebBrowser2 Interface)

 Microsoft SDK for Java

getTop

This method of the IWebBrowser2 interface retrieves the screen coordinate of the top edge of the Microsoft® Internet Explorer main window.

Syntax

public int getTop();


getTopLevelContainer (IWebBrowser2 Interface)

 Microsoft SDK for Java

getTopLevelContainer

This method of the IWebBrowser2 interface retrieves a Boolean value that indicates whether Microsoft® Internet Explorer is the top-level container of the WebBrowser control.

Syntax

public boolean getTopLevelContainer();


getType (IWebBrowser2 Interface)

 Microsoft SDK for Java

getType

This method of the IWebBrowser2 interface retrieves the type name of the contained document object.

Syntax

public java.lang.String getType();


getVisible (IWebBrowser2 Interface)

 Microsoft SDK for Java

getVisible

This method of the IWebBrowser2 interface retrieves a Boolean value that indicates whether the object is visible or hidden.

Syntax

public boolean getVisible();


getWidth (IWebBrowser2 Interface)

 Microsoft SDK for Java

getWidth

This method of the IWebBrowser2 interface retrieves the width of the Microsoft® Internet Explorer main window.

Syntax

public int getWidth();


GoBack (IWebBrowser2 Interface)

 Microsoft SDK for Java

GoBack

This method of the IWebBrowser2 interface navigates backward one item in the history list.

Syntax

public void GoBack();


GoForward (IWebBrowser2 Interface)

 Microsoft SDK for Java

GoForward

This method of the IWebBrowser2 interface navigates forward one item in the history list.

Syntax

public void GoForward();


GoHome (IWebBrowser2 Interface)

 Microsoft SDK for Java

GoHome

This method of the IWebBrowser2 interface navigates to the current home or start page.

Syntax

public void GoHome();


GoSearch (IWebBrowser2 Interface)

 Microsoft SDK for Java

GoSearch

This method of the IWebBrowser2 interface navigates to the current search page.

Syntax

public void GoSearch();


Navigate (IWebBrowser2 Interface)

 Microsoft SDK for Java

Navigate

This method of the IWebBrowser2 interface navigates to a resource identified by a Uniform Resource Locator (URL) or to the file identified by a full path.

Syntax

public void Navigate(java.lang.String URL,
com.ms.com.Variant Flags, com.ms.com.Variant TargetFrameName,
com.ms.com.Variant PostData, com.ms.com.Variant Headers);

Parameters

URL | The caller-allocated string that specifies the URL to navigate to or the full path of the file to display.
Flags | The address of a variable that specifies whether to add the resource to the history list, whether to read to or write from the cache, and whether to display the resource in a new window.
TargetFrameName | The address of a string that contains the name of the frame in which to display the resource.
PostData | The address of data to send with the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form. If this parameter does not specify any post data, Navigate issues an HTTP GET transaction. This parameter is ignored if the URL is not an HTTP URL.
Headers | The address of a value that contains the HTTP headers to send to the server. These headers are added to the default Microsoft® Internet Explorer headers. The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code. This parameter is ignored if the URL is not an HTTP URL.


Navigate2 (IWebBrowser2 Interface)

 Microsoft SDK for Java

Navigate2

This method of the IWebBrowser2 interface navigates the browser to a location that may not be able to be expressed as a URL, such as a pointer to an item identifier list (PIDL) for an entity in the Microsoft® Windows® shell namespace.

Syntax

public void Navigate2(com.ms.com.Variant URL,
com.ms.com.Variant Flags, com.ms.com.Variant TargetFrameName,
com.ms.com.Variant PostData, com.ms.com.Variant Headers);

Parameters

URL | The caller-allocated string that specifies the URL to navigate to or the full path of the file to display.
Flags | The address of a variable that specifies whether to add the resource to the history list, whether to read to or write from the cache, and whether to display the resource in a new window.
TargetFrameName | The address of a string that contains the name of the frame in which to display the resource.
PostData | The address of data to send with the HTTP POST transaction. For example, the POST transaction is used to send data gathered by an HTML form. If this parameter does not specify any post data, Navigate issues an HTTP GET transaction. This parameter is ignored if the URL is not an HTTP URL.
Headers | The address of a value that contains the HTTP headers to send to the server. These headers are added to the default Microsoft® Internet Explorer headers. The headers can specify things such as the action required of the server, the type of data being passed to the server, or a status code. This parameter is ignored if the URL is not an HTTP URL.


PutProperty (IWebBrowser2 Interface)

 Microsoft SDK for Java

PutProperty

This method of the IWebBrowser2 interface sets the value of a property associated with the given object.

Syntax

public void PutProperty(java.lang.String Property,
com.ms.com.Variant vtValue);

Parameters

Property | The name of the property to set.
vtValue | The new value of the property.


QueryStatusWB (IWebBrowser2 Interface)

 Microsoft SDK for Java

QueryStatusWB

This method of the IWebBrowser2 interface implements a wrapper that allows you to query an OLE object for the status of commands using the IOleCommandTarget::QueryStatus method.

Syntax

public int QueryStatusWB(int cmdID);

Parameters

cmdID The identifier of the command on which the caller needs status information. This will be one of the OLECMDID values.


Quit (IWebBrowser2 Interface)

 Microsoft SDK for Java

Quit

This method of the IWebBrowser2 interface closes the Microsoft® Internet Explorer application.

Syntax

public void Quit();


Refresh (IWebBrowser2 Interface)

 Microsoft SDK for Java

Refresh

This method of the IWebBrowser2 interface reloads the file that Microsoft® Internet Explorer is currently displaying.

Syntax

public void Refresh();


Refresh2 (IWebBrowser2 Interface)

 Microsoft SDK for Java

Refresh2

This method of the IWebBrowser2 interface reloads the file that Microsoft® Internet Explorer is currently displaying. Unlike IWebBrowser2.Refresh, this method contains a parameter that specifies the refresh level.

Syntax

public void Refresh2(com.ms.com.Variant Level);

Parameters

Level The address of a variable that specifies the level of refresh operation to perform.


setAddressBar (IWebBrowser2 Interface)

 Microsoft SDK for Java

setAddressBar

This method of the IWebBrowser2 interface shows or hides the Microsoft® Internet Explorer object's address bar.

Syntax

public void setAddressBar(boolean Value);

Parameters

Value The Boolean expression that determines whether the address bar is visible. If TRUE, the address bar is visible; if FALSE, it is hidden. The default value is TRUE.


setFullScreen (IWebBrowser2 Interface)

 Microsoft SDK for Java

setFullScreen

This method of the IWebBrowser2 interface sets Microsoft® Internet Explorer to either full-screen or normal window mode.

Syntax

public void setFullScreen(boolean pbFullScreen);

Parameters

pbFullScreen If TRUE, the browser window is maximized; if FALSE, it is not.


setHeight (IWebBrowser2 Interface)

 Microsoft SDK for Java

setHeight

This method of the IWebBrowser2 interface sets the height of the Microsoft® Internet Explorer main window.

Syntax

public void setHeight(int Pixels);

Parameters

Pixels The vertical dimension of the frame window, in pixels.


setLeft (IWebBrowser2 Interface)

 Microsoft SDK for Java

setLeft

This method of the IWebBrowser2 interface sets the horizontal position of the Microsoft® Internet Explorer main window.

Syntax

public void setLeft(int Pixels);

Parameters

Pixels The distance between the internal left edge of the WebBrowser control and the left edge of its container, in pixels.


setMenuBar (IWebBrowser2 Interface)

 Microsoft SDK for Java

setMenuBar

This method of the IWebBrowser2 interface shows or hides the Microsoft® Internet Explorer menu bar.

Syntax

public void setMenuBar(boolean Visible);

Parameters

Visible Determines whether the menu bar is visible. If TRUE, the menu bar is visible; if FALSE, it is hidden. The default value is TRUE.


setOffline (IWebBrowser2 Interface)

 Microsoft SDK for Java

setOffline

This method of the IWebBrowser2 interface sets a value indicating whether the WebBrowser control is currently operating in offline mode. In offline mode, the browser is forced to read HTML pages from the local cache rather than from the source document.

Syntax

public void setOffline(boolean Offline);

Parameters

Offline Determines whether the WebBrowser control is in offline mode. If TRUE, the WebBrowser will read data about its current URL from its local cache. If FALSE, it will attempt to read the source document. The default value is FALSE.


setRegisterAsBrowser (IWebBrowser2 Interface)

 Microsoft SDK for Java

setRegisterAsBrowser

This method of the IWebBrowser2 interface sets a value indicating whether the WebBrowser control is registered as a top-level browser for target name resolution.

Syntax

public void setRegisterAsBrowser(boolean Register);

Parameters

Register Determines whether Microsoft® Internet Explorer is registered as a top-level browser. If TRUE, the WebBrowser control is registered as a top-level browser; if FALSE, it is not a top-level browser. The default value is FALSE.


setRegisterAsDropTarget (IWebBrowser2 Interface)

 Microsoft SDK for Java

setRegisterAsDropTarget

This method of the IWebBrowser2 interface sets a value indicating whether the WebBrowser control is registered as a drop target for navigation.

Syntax

public void setRegisterAsDropTarget(boolean Register);

Parameters

Register Determines whether Internet Explorer is registered as a drop target for navigation. If TRUE, the WebBrowser is registered as a drop target; if FALSE, it is not a drop target. The default value is FALSE.


setResizable (IWebBrowser2 Interface)

 Microsoft SDK for Java

setResizable

This method of the IWebBrowser2 interface sets the Microsoft® Internet Explorer object's resizable property.

Syntax

public void setResizable(boolean Resizable);

Parameters

Resizable Sets the object's resizable property. If this value is TRUE, the object can be resized. If this value is FALSE, the object cannot be resized. The default value is TRUE.


setSilent (IWebBrowser2 Interface)

 Microsoft SDK for Java

setSilent

This method of the IWebBrowser2 interface sets a value indicating whether any dialog boxes can be shown.

Syntax

public void setSilent(boolean Silent);

Parameters

Silent Determines whether the WebBrowser can show any message or dialog boxes. If TRUE, dialog boxes will not be displayed; if FALSE, dialog boxes will be displayed. The default value is FALSE. Critical errors and security alerts are not suppressed.


setStatusBar (IWebBrowser2 Interface)

 Microsoft SDK for Java

setStatusBar

This method of the IWebBrowser2 interface shows or hides the Microsoft® Internet Explorer status bar.

Syntax

public void setStatusBar(boolean On);

Parameters

On Determines whether the status bar is visible. If TRUE, the status bar is visible; if FALSE, it is hidden. The default is TRUE.


setStatusText (IWebBrowser2 Interface)

 Microsoft SDK for Java

setStatusText

This method of the IWebBrowser2 interface sets the text of the Microsoft® Internet Explorer status bar.

Syntax

public void setStatusText(java.lang.String StatusText);

Parameters

StatusText The text for the status bar.


setTheaterMode (IWebBrowser2 Interface)

 Microsoft SDK for Java

setTheaterMode

This method of the IWebBrowser2 interface sets the TheaterMode property for the WebBrowser control.

Syntax

public void setTheaterMode(boolean TheaterMode);

Parameters

TheaterMode Determines whether Microsoft® Internet Explorer is in theater or normal window mode. If TRUE, the object is in theater mode; if FALSE, it is in normal mode. The default value is FALSE.


setToolBar (IWebBrowser2 Interface)

 Microsoft SDK for Java

setToolBar

This method of the IWebBrowser2 interface shows or hides the Microsoft® Internet Explorer toolbar.

Syntax

public void setToolBar(int Value);

Parameters

Value Determines whether the toolbar is visible. If TRUE, the toolbar is visible; if FALSE, it is hidden. The default is TRUE.


setTop (IWebBrowser2 Interface)

 Microsoft SDK for Java

setTop

This method of the IWebBrowser2 interface sets the vertical position of the Microsoft® Internet Explorer main window.

Syntax

public void setTop(int Pixels);

Parameters

Pixels Specifies the distance of the top of the Microsoft® Internet Explorer main window from the top of the screen, in pixels.


setVisible (IWebBrowser2 Interface)

 Microsoft SDK for Java

setVisible

This method of the IWebBrowser2 interface sets the visibility state of the object.

Syntax

public void setVisible(boolean Visible);

Parameters

Visible Specifies the visible state of Microsoft® Internet Explorer. If TRUE, the window is visible; if FALSE, it is hidden. The default value is FALSE.


setWidth (IWebBrowser2 Interface)

 Microsoft SDK for Java

setWidth

This method of the IWebBrowser2 interface sets the width of the Microsoft® Internet Explorer main window.

Syntax

public void setWidth(int Pixels);

Parameters

Pixels Specifies the horizontal dimension of the frame window, in pixels.


ShowBrowserBar (IWebBrowser2 Interface)

 Microsoft SDK for Java

ShowBrowserBar

This method of the IWebBrowser2 interface shows or hides a specified browser bar.

Syntax

public void ShowBrowserBar(com.ms.com.Variant pvaClsid,
com.ms.com.Variant pvarShow, com.ms.com.Variant pvarSize);

Parameters

pvaClsid | Address of a string VARIANT that contains the class identifier of the browser bar to show or hide.
pvarShow | Address of a VARIANT that specifies if the browser bar should be shown or hidden. If this is nonzero, the browser bar is shown. If this is zero, the browser bar is hidden.
pvarSize | Not currently used.


Stop (IWebBrowser2 Interface)

 Microsoft SDK for Java

Stop

This method of the IWebBrowser2 interface cancels any pending navigation or download operation and stops any dynamic page elements, such as background sounds and animations.

Syntax

public void Stop();


OLECMDEXECOPT Interface (com.ms.ie package)

 Microsoft SDK for Java

OLECMDEXECOPT Interface

The OLECMDEXECOPT interface of the com.ms.ie package specifies command execution options.

public interface OLECMDEXECOPT
{
  // Fields
  public static final int OLECMDEXECOPT_DODEFAULT;
  public static final int OLECMDEXECOPT_DONTPROMPTUSER;
  public static final int OLECMDEXECOPT_PROMPTUSER;
  public static final int OLECMDEXECOPT_SHOWHELP;
}


Fields (OLECMDEXECOPT Interface)

 Microsoft SDK for Java

OLECMDEXECOPT Interface Fields

The OLECMDEXECOPT interface has the fields shown in the following table.

Field | Value | Description
OLECMDEXECOPT_DODEFAULT | 0 | Prompts the user for input or not, whichever is the default behavior.
OLECMDEXECOPT_PROMPTUSER | 1 | Executes the command after obtaining user input.
OLECMDEXECOPT_DONTPROMPTUSER | 2 | Executes the command without prompting the user. For example, clicking the Print toolbar button causes a document to be immediately printed without user input.
OLECMDEXECOPT_SHOWHELP | 3 | Shows Help for the corresponding command, but does not execute it.


OLECMDF Interface (com.ms.ie package)

 Microsoft SDK for Java

OLECMDF Interface

The OLECMDF interface of the com.ms.ie package defines the values returned by the InternetExplorer.QueryStatusWB or WebBrowser.QueryStatusWB method.

public interface OLECMDF
{
  // Fields
  public static final int OLECMDF_ENABLED;
  public static final int OLECMDF_LATCHED;
  public static final int OLECMDF_NINCHED;
  public static final int OLECMDF_SUPPORTED;
}


Fields (OLECMDF Interface)

 Microsoft SDK for Java

OLECMDF Interface Fields

The OLECMDF interface has the following fields:

Field | Value | Description
OLECMDF_SUPPORTED | 1 | The command is supported by this object.
OLECMDF_ENABLED | 2 | The command is available and enabled.
OLECMDF_LATCHED | 3 | The command is an on-off toggle and is currently on.
OLECMDF_NINCHED | 4 | Reserved for future use.


OLECMDID Interface (com.ms.ie package)

 Microsoft SDK for Java

OLECMDID Interface

The OLECMDID interface of the com.ms.ie package defines the constants for specifying which command to execute.

public interface OLECMDID
{
  // Fields
  public static final int OLECMDID_CLEARSELECTION;
  public static final int OLECMDID_COPY;
  public static final int OLECMDID_CUT;
  public static final int OLECMDID_GETZOOMRANGE;
  public static final int OLECMDID_HIDETOOLBARS;
  public static final int OLECMDID_NEW;
  public static final int OLECMDID_OPEN;
  public static final int OLECMDID_PAGESETUP;
  public static final int OLECMDID_PASTE;
  public static final int OLECMDID_PASTESPECIAL;
  public static final int OLECMDID_PRINT;
  public static final int OLECMDID_PRINTPREVIEW;
  public static final int OLECMDID_PROPERTIES;
  public static final int OLECMDID_REDO;
  public static final int OLECMDID_REFRESH;
  public static final int OLECMDID_SAVE;
  public static final int OLECMDID_SAVEAS;
  public static final int OLECMDID_SAVECOPYAS;
  public static final int OLECMDID_SELECTALL;
  public static final int OLECMDID_SETDOWNLOADSTATE;
  public static final int OLECMDID_SETPROGRESSMAX;
  public static final int OLECMDID_SETPROGRESSPOS;
  public static final int OLECMDID_SETPROGRESSTEXT;
  public static final int OLECMDID_SETTITLE;
  public static final int OLECMDID_SPELL;
  public static final int OLECMDID_STOP;
  public static final int OLECMDID_STOPDOWNLOAD;
  public static final int OLECMDID_UNDO;
  public static final int OLECMDID_UPDATECOMMANDS;
  public static final int OLECMDID_ZOOM;
}


Fields (OLECMDID Interface)

 Microsoft SDK for Java

OLECMDID Interface Fields

The OLECMDID interface has the fields shown in the following table.

Field | Value | Description
OLECMDID_OPEN | 1 | File menu, Open command.
OLECMDID_NEW | 2 | File menu, New command.
OLECMDID_SAVE | 3 | File menu, Save command.
OLECMDID_SAVEAS | 4 | File menu, Save As command.
OLECMDID_SAVECOPYAS | 5 | File menu, Save Copy As command.
OLECMDID_PRINT | 6 | File menu, Print command
OLECMDID_PRINTPREVIEW | 7 | File menu, Print Preview command.
OLECMDID_PAGESETUP | 8 | File menu, Page Setup command.
OLECMDID_SPELL | 9 | Tools menu, Spelling command.
OLECMDID_PROPERTIES | 10 | File menu, Properties command.
OLECMDID_CUT | 11 | Edit menu, Cut command.
OLECMDID_COPY | 12 | Edit menu, Copy command.
OLECMDID_PASTE | 13 | Edit menu, Paste command.
OLECMDID_PASTESPECIAL | 14 | Edit menu, Paste Special command.
OLECMDID_UNDO | 15 | Edit menu, Undo command.
OLECMDID_REDO | 16 | Edit menu, Redo command
OLECMDID_SELECTALL | 17 | Edit menu, Select All command.
OLECMDID_CLEARSELECTION | 18 | Edit menu, Clear command
OLECMDID_ZOOM | 19 | View menu, Zoom command ( details follow).
OLECMDID_GETZOOMRANGE | 20 | Retrieves the zoom range applicable to View, Zoom (details follow).
OLECMDID_UPDATECOMMANDS | 21 | Informs the receiver, usually a frame, of state changes. The receiver can then query the status of the commands whenever convenient.
OLECMDID_REFRESH | 22 | Asks the receiver to refresh its display. Implemented by the document/object.
OLECMDID_STOP | 23 | Stops all current processing. Implemented by the document/object.
OLECMDID_HIDETOOLBARS | 24 | View Menu, Toolbars command. Implemented by the document/object to hide its toolbars.
OLECMDID_SETPROGRESSMAX | 25 | Sets the maximum value of a progress indicator if one is owned by the receiving object, usually a frame. The minimum value is always zero.
OLECMDID_SETPROGRESSPOS | 26 | Sets the current value of a progress indicator if one is owned by the receiving object, usually a frame.
OLECMDID_SETPROGRESSTEXT | 27 | Sets the text contained in a progress indicator if one is owned by the receiving object, usually a frame. If the receiver currently has no progress indicator, this text should be displayed in the status bar (if one exists) as with IOleInPlaceFrame::SetStatusText.
OLECMDID_SETTITLE | 28 | Sets the title bar text of the receiving object, usually a frame.
OLECMDID_SETDOWNLOADSTATE | 29 | Called by the object when downloading state changes. Takes a VT_BOOL parameter, which is TRUE if the object is downloading data and FALSE if it not. Primarily implemented by the frame.
OLECMDID_STOPDOWNLOAD | 30 | Stops the download when executed. Typically, this command is propagated to all contained objects. When queried, sets MSOCMDF_ENABLED. Implemented by the document/object.


tagREADYSTATE Interface (com.ms.ie package)

 Microsoft SDK for Java

tagREADYSTATE Interface

The tagREADYSTATE interface of the com.ms.ie package is an enumeration of constants that indicate what state an object is in, such as loading, loaded, or uninitialized.

public interface tagREADYSTATE
{
  // Fields
  public static final int READYSTATE_COMPLETE;
  public static final int READYSTATE_INTERACTIVE;
  public static final int READYSTATE_LOADED;
  public static final int READYSTATE_LOADING;
  public static final int READYSTATE_UNINITIALIZED;
}


Fields (tagREADYSTATE Interface)

 Microsoft SDK for Java

tagREADYSTATE Interface Fields

The tagREADYSTATE interface has the fields shown in the following table.

Field | Value | Description
READYSTATE_UNINITIALIZED | 0 | Default initialization state.
READYSTATE_LOADING | 1 | Object is currently loading its properties.
READYSTATE_LOADED | 2 | Object has been initialized.
READYSTATE_INTERACTIVE | 3 | Object is interactive, but not all its data is available.
READYSTATE_COMPLETE | 4 | Object has received all its data.


com.ms.io Package Overview

Microsoft Packages Overview

The com.ms.io package contains a variety of classes that provide access to specialized input and output operations.

This package contains the following:

Classes

Hierarchy

You can use the classes in the com.ms.io package to manipulate path strings (Path), create file dialog boxes (UserFileDialog), resolve a class with a non-system class loader (ObjectInputStreamWithLoader), and read and write from specialized input streams.

The following table lists the classes in com.ms.io that represent I/O streams.

Class | Basic functionality
IntArrayOutputStream | An output stream for primitive integers.
SystemInputStream | An input stream that can be handed to untrusted code.
SystemOutputStream | An output stream that can be handed to untrusted code.
OffsetInputStreamFilter | A filter input stream that keeps track of the byte offset into the stream.

Example

The following code sample opens a file using a file dialog box, and then writes an array of bytes to the file.

import com.ms.io.UserFileDialog;
import java.io.FileOutputStream;
import java.awt.Frame;

public class MySample
{
  // Parent represents the container of the dialog box.
  public void dbOpen(Frame parent, byte[] buffer){
    UserFileDialog db = new UserFileDialog(parent,"Open a File");
    FileOutputStream stream = db.openFileForWriting();
    try{
      stream.write(buffer);
    }
    catch(IOException e) {
      System.out.println("I/O error occurred.");
    }
  }
}


Classes (com.ms.io Package)

 Microsoft SDK for Java

com.ms.io Package Classes

The com.ms.io package contains the following classes:

IntArrayOutputStream Class provides methods that create and manipulate output streams for primitive integers.

ObjectInputStreamWithLoader Class provides methods that allow a class to be resolved by using an existing ClassLoader instance instead of the system class loader.

OffsetInputStreamFilter Class represents a filter input stream that keeps track of the byte offset into the stream.

Path Class provides methods for checking and manipulating strings that represent paths.

SystemInputStream Class provides methods that allow an application to hand an input stream to untrusted code and prevent the untrusted code from closing it.

SystemOutputStream Class provides methods that allow an application to hand an output stream to untrusted code and prevent the untrusted code from closing it.

UserFileDialog Class provides methods for creating and displaying dialog boxes that can open files for reading, writing, and random access.


Hierarchy (com.ms.io Package)

 Microsoft SDK for Java

com.ms.io Package Hierarchy

The com.ms.io package has the following hierarchy:

Object
  |
  +--Path
  |
  +--UserFileDialog

OutputStream
  |
  +--IntArrayOutputStream (Cloneable)

ObjectInputStream
  |
  +--ObjectInputStreamWithLoader

FilterInputStream
  |
  +--OffsetInputStreamFilter
  |
  +--SystemInputStream

FilterOutputStream
  |
  +--SystemOutputStream


IntArrayOutputStream Class (com.ms.io Package)

 Microsoft SDK for Java

IntArrayOutputStream Class

The IntArrayOutputStream Class of the com.ms.io package provides methods that create and manipulate output streams for primitive integers.

public class IntArrayOutputStream extends java.io.OutputStream
             implements Cloneable
{
  // Constructors
  public IntArrayOutputStream();
  public IntArrayOutputStream(int size);
  public IntArrayOutputStream(int[] stuff);

  // Methods
  public synchronized void append(int n);
  public synchronized void appendTo(IntArrayOutputStream out);
  public synchronized void appendTo(IntArrayOutputStream out,
        int s, int len);
  public synchronized int capacity();
  public IntArrayOutputStream copy();
  public synchronized int copyInto(int[] dest);
  public synchronized int elementAt(int ofs);
  public synchronized int elementFromEnd(int ofs);
  public synchronized int ensureCapacity(int capacity);
  public int[] getIntArray();
  public synchronized void getInts(int[] dest, int s, int len);
  public synchronized void insertElements(int ofs, int n);
  public boolean isEmpty();
  public synchronized void putElement(int ofs, int value);
  public synchronized int reduceCapacity(int capacity);
  public synchronized void removeElements(int ofs, int n);
  public void reset();
  public synchronized void setIntArray(int[] array);
  public synchronized void shrinkToFit();
  public int size();
  public synchronized int[] toIntArray();
  public String toString();
  public synchronized void truncate(int newsize);
  public void write(int[] src);
  public void write(int b) throws IOException;
  public synchronized void write(int[] src, int s, int len);
}

Hierarchy

OutputStream
  |
  +--IntArrayOutputStream


Constructors (IntArrayOutputStream Class)

 Microsoft SDK for Java

IntArrayOutputStream Class Constructors

The IntArrayOutputStream Class contains the following constructors:

IntArrayOutputStream()
IntArrayOutputStream(int size)
IntArrayOutputStream(int[] stuff)

IntArrayOutputStream()

Creates an IntArrayOutputStream object that can hold 16 integers.

Syntax

public IntArrayOutputStream();

IntArrayOutputStream(int size)

Creates an IntArrayOutputStream object that can hold the specified number of integers.

Syntax

public IntArrayOutputStream(int size);

Parameters

size The number of integers that the output stream can hold.

IntArrayOutputStream(int[] stuff)

Creates an IntArrayOutputStream object initialized with integer values.

Syntax

public IntArrayOutputStream(int[] stuff);

Parameters

stuff The initial values for the output stream.


Methods (IntArrayOutputStream Class)

 Microsoft SDK for Java

IntArrayOutputStream Class Methods

The IntArrayOutputStream Class contains the following methods:

append appends an integer to the output stream.
appendTo appends the contents of the output stream onto another IntArrayOutputStream.
capacity retrieves the maximum number of integers that the IntArrayOutputStream object can hold.
copy creates a deep copy of the output stream.
copyInto copies the contents of the output stream into an array of integers.
elementAt retrieves an element from the output stream at a specified offset.
elementFromEnd retrieves an element from the output stream at a specified offset, relative to the end of the stream.
ensureCapacity ensures that the IntArrayOutputStream object has enough storage capacity for the specified number of integers.
getIntArray retrieves the array of integers represented by the IntArrayOutputStream object.
getInts copies integers from the output stream to an array.
insertElements inserts zero-initialized elements into the IntArrayOutputStream object.
isEmpty determines whether the IntArrayOutputStream object is empty.
putElement replaces an element in the output stream at a specified offset.
reduceCapacity shrinks the storage of the IntArrayOutputStream object to the requested capacity.
removeElements removes elements from the IntArrayOutputStream object.
reset sets the number of integers in the IntArrayOutputStream object to zero.
setIntArray sets the values of the IntArrayOutputStream object.
shrinkToFit reduces the capacity of the IntArrayOutputStream object to the number of integers currently in the output stream.
size retrieves the number of integers in the IntArrayOutputStream object.
toIntArray makes a copy of the array of integers represented by the IntArrayOutputStream object.
toString converts the output stream to string form.
truncate decreases the number of integers in the IntArrayOutputStream object to the specified number.
write appends an array of integers to the output stream.


append (IntArrayOutputStream Class)

 Microsoft SDK for Java

append

This method of the IntArrayOutputStream Class appends an integer to the output stream.

Syntax

public synchronized void append(int n);

Parameters

n The value to append to the output stream.


appendTo (IntArrayOutputStream Class)

 Microsoft SDK for Java

appendTo

The appendTo method of the IntArrayOutputStream Class contains the following signatures:

appendTo(IntArrayOutputStream out)
appendTo(IntArrayOutputStream out, int s, int len)

appendTo(IntArrayOutputStream out)

Appends the contents of the output stream onto another IntArrayOutputStream.

Syntax

public synchronized void appendTo(IntArrayOutputStream out);

Parameters

out The output stream to append the stream to.

appendTo(IntArrayOutputStream out, int s, int len)

Appends integers from this output stream onto another IntArrayOutputStream, beginning at a specified offset in this output stream.

Syntax

public synchronized void appendTo(IntArrayOutputStream out, int s, int len);

Parameters

out | The output stream to append the integers to.
s | The offset in this output stream where the first integer to append is located.
len | The number of integers in this output stream to append.

Exceptions

ArrayIndexOutOfBoundsException if the offset is negative, or if the specified number of integers to append exceeds the amount available from the specified offset.


capacity (IntArrayOutputStream Class)

 Microsoft SDK for Java

capacity

This method of the IntArrayOutputStream Class retrieves the maximum number of integers that the IntArrayOutputStream object can hold.

Syntax

public synchronized int capacity();

Return Value

Returns the maximum capacity of the output stream.


copy (IntArrayOutputStream Class)

 Microsoft SDK for Java

copy

This method of the IntArrayOutputStream Class creates a deep copy of the output stream.

Syntax

public IntArrayOutputStream copy();

Return Value

Returns the copy of the output stream.


copyInto (IntArrayOutputStream Class)

 Microsoft SDK for Java

copyInto

This method of the IntArrayOutputStream Class copies the contents of the output stream into an array of integers.

Syntax

public synchronized int copyInto(int[] dest);

Return Value

Returns the number of elements copied.

Parameters

dest The destination array that the output stream is copied into.


elementAt (IntArrayOutputStream Class)

 Microsoft SDK for Java

elementAt

This method of the IntArrayOutputStream Class retrieves an element from the output stream at a specified offset.

Syntax

public synchronized int elementAt(int ofs);

Return Value

Returns the value of the retrieved element.

Parameters

cfs The offset in the output stream where the element to retrieve is located.


elementFromEnd (IntArrayOutputStream Class)

 Microsoft SDK for Java

elementFromEnd

This method of the IntArrayOutputStream Class retrieves an element from the output stream at a specified offset, relative to the end of the stream.

Syntax

public synchronized int elementFromEnd(int ofs);

Return Value

Returns the value of the retrieved element.

Parameters

ofs The offset from the end of the output stream where the element to retrieve is located.


ensureCapacity (IntArrayOutputStream Class)

 Microsoft SDK for Java

ensureCapacity

This method of the IntArrayOutputStream Class ensures that the IntArrayOutputStream object has enough storage capacity for the specified number of integers. If current capacity exceeds the specified capacity, the current capacity remains unchanged.

Syntax

public synchronized int ensureCapacity(int capacity);

Return Value

Returns the actual capacity of the output stream.

Parameters

capacity The minimum required capacity of the output stream.


getIntArray (IntArrayOutputStream Class)

 Microsoft SDK for Java

getIntArray

This method of the IntArrayOutputStream Class retrieves the array of integers represented by the IntArrayOutputStream object.

Syntax

public int[] getIntArray();

Return Value

Returns the array of integers represented by the output stream.


getInts (IntArrayOutputStream Class)

 Microsoft SDK for Java

getInts

This method of the IntArrayOutputStream Class copies integers from the output stream to an array. The first integer copied is located at the beginning of the stream; it is copied to the specified offset in the array.

Syntax

public synchronized void getInts(int[] dest, int s, int len);

Parameters

dest | The array that receives the integers.
s | The offset in the array where the first integer is copied to.
len | The number of integers in the output stream to copy.

Exceptions

ArrayIndexoutOfBoundsException if the offset is negative, if copying the integers will exceed the capacity of the array, or if the specified number of integers to append exceeds the amount available from the specified offset.


insertElements (IntArrayOutputStream Class)

 Microsoft SDK for Java

insertElements

This method of the IntArrayOutputStream Class inserts zero-initialized elements into the IntArrayOutputStream object.

Syntax

public synchronized void insertElements(int ofs, int n);

Parameters

ofs | The offset in the output stream where the elements are inserted.
n | The number of zero-initialized elements to insert.


isEmpty (IntArrayOutputStream Class)

 Microsoft SDK for Java

isEmpty

This method of the IntArrayOutputStream Class determines whether the IntArrayOutputStream object is empty.

Syntax

public boolean isEmpty();

Return Value

Returns true if the output stream is empty; otherwise, returns false.


putElement (IntArrayOutputStream Class)

 Microsoft SDK for Java

putElement

This method of the IntArrayOutputStream Class replaces an element in the output stream at a specified offset.

Syntax

public synchronized void putElement(int ofs, int value);

Parameters

ofs | The offset in the output stream of the element to be replaced.
value | The value for the new element.

Exceptions

ArrayIndexOutOfBoundsException if the offset exceeds or equals the number of elements currently in the stream.


reduceCapacity (IntArrayOutputStream Class)

 Microsoft SDK for Java

reduceCapacity

This method of the IntArrayOutputStream Class shrinks the storage of the IntArrayOutputStream object to the requested capacity. If the requested capacity is greater than or equal to the capacity of the output stream, the capacity of the output stream remains unchanged.

Syntax

public synchronized int reduceCapacity(int capacity);

Return Value

Returns the actual capacity of the output stream.

Parameters

capacity The maximum required capacity of the output stream.

Exceptions

ArrayIndexOutOfBoundsException if the number of integers currently in the output stream exceeds the requested capacity.


removeElements (IntArrayOutputStream Class)

 Microsoft SDK for Java

removeElements

This method of the IntArrayOutputStream Class removes elements from the IntArrayOutputStream object.

Syntax

public synchronized void removeElements(int ofs, int n);

Parameters

ofs | The offset in the output stream where the first element to remove is located.
n | The number of elements to remove.


reset (IntArrayOutputStream Class)

 Microsoft SDK for Java

reset

This method of the IntArrayOutputStream Class sets the number of integers in the IntArrayOutputStream object to zero.

Syntax

public void reset();


setIntArray (IntArrayOutputStream Class)

 Microsoft SDK for Java

setIntArray

This method of the IntArrayOutputStream Class sets the values of the IntArrayOutputStream object.

Syntax

public synchronized void setIntArray(int[] array);

Parameters

array The array that contains the new values.


shrinkToFit (IntArrayOutputStream Class)

 Microsoft SDK for Java

shrinkToFit

This method of the IntArrayOutputStream Class reduces the capacity of the IntArrayOutputStream object to the number of integers currently in the output stream.

Syntax

public synchronized void shrinkToFit();


size (IntArrayOutputStream Class)

 Microsoft SDK for Java

size

This method of the IntArrayOutputStream Class retrieves the number of integers in the IntArrayOutputStream object.

Syntax

public int size();

Return Value

Returns the number of integers in the output stream.


toIntArray (IntArrayOutputStream Class)

 Microsoft SDK for Java

toIntArray

This method of the IntArrayOutputStream Class makes a copy of the array of integers represented by the IntArrayOutputStream object.

Syntax

public synchronized int[] toIntArray();

Return Value

Returns a copy of the integers represented by the output stream.


toString (IntArrayOutputStream Class)

 Microsoft SDK for Java

toString

This method of the IntArrayOutputStream Class converts the output stream to string form.

Syntax

public String toString();

Return Value

Returns the output stream in string form.


truncate (IntArrayOutputStream Class)

 Microsoft SDK for Java

truncate

This method of the IntArrayOutputStream Class decreases the number of integers in the IntArrayOutputStream object to the specified number.

Syntax

public synchronized void truncate(int newsize);

Parameters

newsize The number of integers that the truncated output stream will hold.

Exceptions

ArrayIndexOutOfBoundsException if the specified number exceeds or equals the number of integers currently in the output stream.


write (IntArrayOutputStream Class)

 Microsoft SDK for Java

write

The write method of the IntArrayOutputStream Class contains the following signatures:

write(int[] src)
write(int b)
write(int[] src, int s, int len)

write(int[] src)

Appends an array of integers to the output stream.

Syntax

public void write(int[] src);

Parameters

src The array of integers to append to the output stream.

write(int b)

Appends a byte to the output stream. This method blocks until the byte is actually written.

Syntax

public void write(int b) throws IOException;

Parameters

b The byte to append.

Exceptions

IOException if the byte cannot be appended to the output stream.

write(int[] src, int s, int len)

Appends a number of integers from the specified array to the output stream, starting with the integer at offset s in the array.

Syntax

public synchronized void write(int[] src, int s, int len);

Parameters

src | The array of integers to append to the output stream.
s | The offset in the array, where the first integer to append is located.
len | The number of integers to append.


ObjectInputStreamWithLoader Class (com.ms.io Package)

 Microsoft SDK for Java

ObjectInputStreamWithLoader Class

The ObjectInputStreamWithLoader Class of the com.ms.io package provides methods that allow a class to be resolved by using an existing ClassLoader instance instead of the system class loader. It extends the java.io.ObjectInputStream class, which delegates class resolution to the java.lang.ClassLoader supplied at construction time.

public class ObjectInputStreamWithLoader extends ObjectInputStream
{
  // Constructors
  public ObjectInputStreamWithLoader(InputStream in,
        ClassLoader loader) throws IOException,
        StreamCorruptedException;

  // Methods
  protected Class resolveClass(ObjectStreamClass classDesc)
        throws IOException, ClassNotFoundException;
}

Hierarchy

ObjectInputStream
  |
  +--ObjectInputStreamWithLoader


Constructors (ObjectInputStreamWithLoader Class)

 Microsoft SDK for Java

ObjectInputStreamWithLoader Class Constructors

The ObjectInputStreamWithLoader Class contains the following constructor:

ObjectInputStreamWithLoader(InputStream in, ClassLoader loader)

Creates an ObjectInputStreamWithLoader object, using the specified input stream and class loader.

Syntax

public ObjectInputStreamWithLoader(InputStream in, ClassLoader loader) throws IOException, StreamCorruptedException;

Parameters

in | The input stream that is used to create the object.
loader | The existing ClassLoader instance.

Exceptions

IllegalArgumentException if loader is null.

IOException if an error is encountered while using the underlying stream.

StreamCorruptedException if the version or magic number is incorrect.


Methods (ObjectInputStreamWithLoader Class)

 Microsoft SDK for Java

ObjectInputStreamWithLoader Class Methods

The ObjectInputStreamWithLoader Class contains the following method:

resolveClass instructs the class loader that is associated with the ObjectInputStreamWithLoader object to load the class indicated by the specified ObjectStreamClass object.


resolveClass (ObjectInputStreamWithLoader Class)

 Microsoft SDK for Java

resolveClass

This method of the ObjectInputStreamWithLoader Class instructs the class loader that is associated with the ObjectInputStreamWithLoader object to load the class indicated by the specified ObjectStreamClass object.

Syntax

protected Class resolveClass(ObjectStreamClass classDesc) throws IOException, ClassNotFoundException;

Return Value

Returns the loaded class.

Parameters

classDesc The ObjectStreamClass object that indicates the class to load.

Exceptions

ClassNotFoundException if the class to load cannot be found.

IOException if the loader encounters an error while reading the class.


OffsetInputStreamFilter Class (com.ms.io Package)

 Microsoft SDK for Java

OffsetInputStreamFilter Class

The OffsetInputStreamFilter Class of the com.ms.io package represents a filter input stream that keeps track of the byte offset into the stream.

public class OffsetInputStreamFilter extends FilterInputStream
{
  // Constructors
  public OffsetInputStreamFilter(InputStream i);

  // Methods
  public long getOffset();
  public void mark(int readlimit);
  public synchronized int read() throws IOException;
  public synchronized int read(byte b[], int off, int len)
        throws IOException;
  public void reset() throws IOException;
  public synchronized long skip(long n) throws IOException;
  public synchronized long skipToAlignment(int align)
        throws IOException;
}

Hierarchy

FilterInputStream
  |
  +--OffsetInputStreamFilter


Constructors (OffsetInputStreamFilter Class)

 Microsoft SDK for Java

OffsetInputStreamFilter Class Constructors

The OffsetInputStreamFilter Class contains the following constructor:

OffsetInputStreamFilter(InputStream i)

Creates an OffsetInputStreamFilter object from the specified input stream.

Syntax

public OffsetInputStreamFilter(InputStream i);

Parameters

i The input stream.


Methods (OffsetInputStreamFilter Class)

 Microsoft SDK for Java

OffsetInputStreamFilter Class Methods

The OffsetInputStreamFilter Class contains the following methods:

getOffset retrieves the current byte offset into the input stream.
mark marks the current position in the input stream.
read reads a single byte from the input stream.
reset resets the byte offset of the input stream to the last marked position.
skip skips a number of bytes in the input stream and updates the byte offset to reflect the new position in the stream.
skipToAlignment skips bytes in the input stream until the byte offset is a multiple of the alignment.


getOffset (OffsetInputStreamFilter Class)

 Microsoft SDK for Java

getOffset

This method of the OffsetInputStreamFilter Class retrieves the current byte offset into the input stream.

Syntax

public long getOffset();

Return Value

Returns the current byte offset into the input stream.


mark (OffsetInputStreamFilter Class)

 Microsoft SDK for Java

mark

This method of the OffsetInputStreamFilter Class marks the current position in the input stream.

Syntax

public void mark(int readlimit);

Parameters

readlimit The number of bytes that can be read without invalidating the mark.


read (OffsetInputStreamFilter Class)

 Microsoft SDK for Java

read

The read method of the OffsetInputStreamFilter Class contains the following signatures:

read()
read(byte b[], int off, int len)

read()

Reads a single byte from the input stream.

Syntax

public synchronized int read() throws IOException;

Return Value

Returns the byte that was read from the input stream.

Exceptions

IOException if an error occurs while attempting to read.

read(byte b[], int off, int len)

Reads a sequence of bytes from the input stream into the buffer.

Syntax

public synchronized int read(byte b[], int off, int len) throws IOException;

Return Value

Returns the number of bytes read.

Parameters

b | The buffer to store the bytes in.
off | The offset in the buffer where the first byte read is stored.
len | The number of bytes to read.

Exceptions

IOException if an error occurs while attempting to read.


reset (OffsetInputStreamFilter Class)

 Microsoft SDK for Java

reset

This method of the OffsetInputStreamFilter Class resets the byte offset of the input stream to the last marked position.

Syntax

public void reset() throws IOException;

Exceptions

IOException if the mark is invalid or has not been set.


skip (OffsetInputStreamFilter Class)

 Microsoft SDK for Java

skip

This method of the OffsetInputStreamFilter Class skips a number of bytes in the input stream and updates the byte offset to reflect the new position in the stream.

Syntax

public synchronized long skip(long n) throws IOException;

Return Value

Returns the actual number of bytes skipped.

Parameters

n The number of bytes to skip.

Exceptions

IOException if an I/O error occurs.


skipToAlignment (OffsetInputStreamFilter Class)

 Microsoft SDK for Java

skipToAlignment

This method of the OffsetInputStreamFilter Class skips bytes in the input stream until the byte offset is a multiple of the alignment.

Syntax

public synchronized long skipToAlignment(int align) throws IOException;

Return Value

Returns the actual number of bytes skipped.

Parameters

align The alignment.

Exceptions

IOException if an I/O error occurs.


Path Class (com.ms.io Package)

 Microsoft SDK for Java

Path Class

The Path Class of the com.ms.io package provides methods for checking and manipulating strings that represent paths.

public class Path
{
  // Methods
  public static String append(String stPath1, String stPath2);
  public static String getExtension(String stPath);
  public static boolean hasExecExtensionType(String stPath);
  public static boolean isRoot(String stPath);
  public static boolean isValidFileChar(char ch);
  public static String removeBeginEndQuotes(String stPath);
  public static String removeTrailingSlash(String stPath);
  public static String validateFilename(String origfilename,
        char replch) throws IOException;
}


Methods (Path Class)

 Microsoft SDK for Java

Path Class Methods

The Path Class contains the following methods:

append appends one path string to another.
getExtension retrieves the extension of the file name.
hasExecExtensionType determines whether the path string ends in .exe, .com, .bat, .pif, or .cmd.
isRoot determines whether the path string is a root path.
isValidFileChar determines whether a character can be used in a file name.
removeBeginEndQuotes removes leading and trailing quotes from the path string, if there are any.
removeTrailingSlash removes a trailing backslash unless the path is a root path.
validateFilename checks a file name, and if it is not valid, attempts to correct it.


append (Path Class)

 Microsoft SDK for Java

append

This method of the Path Class appends one path string to another. If necessary, a separator is inserted between the path strings.

Syntax

public static String append(String stPath1, String stPath2);

Return Value

Returns the string that consists of the second path appended to the first.

Parameters

stPath1 | The first path.
stPath2 | The second path, which will be appended to the first path.


getExtension (Path Class)

 Microsoft SDK for Java

getExtension

This method of the Path Class retrieves the extension of the file name. If there is no extension, this method returns null.

Syntax

public static String getExtension(String stPath);

Return Value

Returns the extension of the file name.

Parameters

stPath The path string.


hasExecExtensionType (Path Class)

 Microsoft SDK for Java

hasExecExtensionType

This method of the Path Class determines whether the path string ends in .exe, .com, .bat, .pif, or .cmd.

Syntax

public static boolean hasExecExtensionType(String stPath);

Return Value

Returns true if the path string ends in .exe, .com, .bat, .pif, or .cmd; otherwise, returns false.

Parameters

stPath The path string.


isRoot (Path Class)

 Microsoft SDK for Java

isRoot

This method of the Path Class determines whether the path string is a root path. For example, the following strings are root paths: "\", "c:\", "\\server\", and "\\server\share".

Syntax

public static boolean isRoot(String stPath);

Return Value

Returns true if the path string is a root path; otherwise, returns false.

Parameters

stPath The path string.


isValidFileChar (Path Class)

 Microsoft SDK for Java

isValidFileChar

This method of the Path Class determines whether a character can be used in a file name.

Syntax

public static boolean isValidFileChar(char ch);

Return Value

Returns true if the character can be used in a file name; otherwise, returns false.

Parameters

ch The character that is checked to see if it is valid in a file name.


removeBeginEndQuotes (Path Class)

 Microsoft SDK for Java

removeBeginEndQuotes

This method of the Path Class removes leading and trailing quotes from the path string, if there are any.

Syntax

public static String removeBeginEndQuotes(String stPath);

Return Value

Returns the path string with quotes removed.

Parameters

stPath The path string to remove quotes from.


removeTrailingSlash (Path Class)

 Microsoft SDK for Java

removeTrailingSlash

This method of the Path Class removes a trailing backslash unless the path is a root path.

Syntax

public static String removeTrailingSlash(String stPath);

Return Value

Returns the path string without the trailing backslash. If the path is a root path, it remains unchanged.

Parameters

stPath The path string.


validateFilename (Path Class)

 Microsoft SDK for Java

validateFilename

This method of the Path Class checks a file name, and if it is not valid, attempts to correct it.

Syntax

public static String validateFilename(String origfilename, char replch) throws IOException;

Return Value

Returns a valid file name or the original file name, if it is already valid.

Parameters

origfilename | The file name to check and correct.
replch | The character to replace invalid characters with.

Exceptions

IOException if the file name cannot be corrected.


SystemInputStream Class (com.ms.io Package)

 Microsoft SDK for Java

SystemInputStream Class

The SystemInputStream Class of the com.ms.io package provides methods that allow an application to hand an input stream to untrusted code and prevent the untrusted code from closing it. System.in objects are wrapped with this class, which extends the FilterInputStream class.

public class SystemInputStream extends FilterInputStream
{
  // Constructors
  public SystemInputStream(InputStream out, int id);

  // Methods
  public void close() throws IOException;
}

Hierarchy

FilterInputStream
  |
  +--SystemInputStream


Constructors (SystemInputStream Class)

 Microsoft SDK for Java

SystemInputStream Class Constructors

The SystemInputStream Class contains the following constructor:

SystemInputStream(InputStream out, int id)

Creates a SystemInputStream object by using the specified input stream and an identifier. The identifier will be used for security checks.

Syntax

public SystemInputStream(InputStream out, int id);

Parameters

out | The input stream.
id | The identifier for the new SystemInputStream object.


Methods (SystemInputStream Class)

 Microsoft SDK for Java

SystemInputStream Class Methods

The SystemInputStream Class contains the following method:

close closes the system input stream.


close (SystemInputStream Class)

 Microsoft SDK for Java

close

This method of the SystemInputStream Class closes the system input stream.

Syntax

public void close() throws IOException;

Exceptions

IOException if an I/O error occurs while attempting to close the output stream.


SystemOutputStream Class (com.ms.io Package)

 Microsoft SDK for Java

SystemOutputStream Class

The SystemOutputStream Class of the com.ms.io package provides methods that allow an application to hand an output stream to untrusted code and prevent the untrusted code from closing it. System.out and System.err objects are wrapped with this class, which extends the FilterOutputStream class.

public class SystemOutputStream extends FilterOutputStream
{
  // Constructors
  public SystemOutputStream(OutputStream out, int id);

  // Methods
  public void close() throws IOException;
  public void write(byte b[], int off, int len) throws IOException;
}

Hierarchy

FilterOutputStream
  |
  +--SystemOutputStream


Constructors (SystemOutputStream Class)

 Microsoft SDK for Java

SystemOutputStream Class Constructors

The SystemOutputStream Class contains the following constructor:

SystemOutputStream(OutputStream out, int id)

Creates a SystemOutputStream object by using the specified output stream and an identifier. The identifier will be used for security checks.

Syntax

public SystemOutputStream(OutputStream out, int id);

Parameters

out | The output stream.
id | The identifier for the new SystemOutputStream object.


Methods (SystemOutputStream Class)

 Microsoft SDK for Java

SystemOutputStream Class Methods

The SystemOutputStream Class contains the following methods:

close closes the system output stream.
write writes bytes to the output stream from an array, starting at a specified offset in the array.


close (SystemOutputStream Class)

 Microsoft SDK for Java

close

This method of the SystemOutputStream Class closes the system output stream.

Syntax

public void close() throws IOException;

Exceptions

IOException if an error occurs while attempting to close the output stream.


write (SystemOutputStream Class)

 Microsoft SDK for Java

write

This method of the SystemOutputStream Class writes bytes to the output stream from an array, starting at a specified offset in the array.

Syntax

public void write(byte b[], int off, int len) throws IOException;

Parameters

b | The array to write from.
off | The offset in the array, where the first byte to write is located.
len | The number of bytes to write.

Exceptions

IOException if an error occurs while attempting to write to the output stream.


UserFileDialog Class (com.ms.io Package)

 Microsoft SDK for Java

UserFileDialog Class

The UserFileDialog Class of the com.ms.io package provides methods for creating and displaying dialog boxes that can open files for reading, writing, and random access.

public final class UserFileDialog
{
  // Constructors
  public UserFileDialog(Frame parent,String title);

  // Methods
  public String getFileName();
  public synchronized FileInputStream openFileForReading()
        throws IOException;
  public synchronized FileOutputStream openFileForWriting()
        throws IOException;
  public synchronized RandomAccessFile openRandomAccessFile(
        String mode) throws IOException;
}


Constructors (UserFileDialog Class)

 Microsoft SDK for Java

UserFileDialog Class Constructors

The UserFileDialog Class contains the following constructor:

UserFileDialog(Frame parent,String title)

Creates a UserFileDialog object that represents a file dialog box. After creating the UserFileDialog object, you can use one of the following methods to display the dialog box and open a file:

openFileForReading
openFileForWriting
openRandomAccessFile

Syntax

public UserFileDialog(Frame parent,String title);

Parameters

parent | The owner of the file dialog box.
title | The title of the file dialog box.


Methods (UserFileDialog Class)

 Microsoft SDK for Java

UserFileDialog Class Methods

The UserFileDialog Class contains the following methods:

getFileName retrieves the name of the last file opened with a dialog box if a successful file open operation has been performed with the dialog box.
openFileForReading displays a dialog box that allows the user to open a file for reading.
openFileForWriting displays a dialog box that allows the user to open a file for writing.
openRandomAccessFile displays a dialog box that allows the user to open a file for random access.


getFileName (UserFileDialog Class)

 Microsoft SDK for Java

getFileName

This method of the UserFileDialog Class retrieves the name of the last file opened with a dialog box if a successful file open operation has been performed with the dialog box. This method returns null if the dialog box has never been used to open a file or if the last attempt to open a file with the dialog box failed for any reason.

Syntax

public String getFileName();

Return Value

Returns the name of the last file successfully opened with this dialog box; returns null if the last attempt failed or if the dialog box has never been used to open a file.


openFileForReading (UserFileDialog Class)

 Microsoft SDK for Java

openFileForReading

This method of the UserFileDialog Class displays a dialog box that allows the user to open a file for reading. If the user selects a file, then a FileInputStream object for that file is returned. If the user cancels the dialog box, null is returned. To determine the name of the file that was opened, you can use the getFileName method.

Syntax

public synchronized FileInputStream openFileForReading() throws IOException;

Return Value

Returns a FileInputStream object if the user selects a file or returns null if the user cancels the dialog box.

Exceptions

SecurityException if the caller does not have permission to initiate user-directed file I/O.

IOException if an I/O error occurs while attempting to open the file.


openFileForWriting (UserFileDialog Class)

 Microsoft SDK for Java

openFileForWriting

This method of the UserFileDialog Class displays a dialog box that allows the user to open a file for writing. If the user selects a file, then a FileOutputStream object for that file is returned. If the user cancels the dialog box, null is returned. To determine the name of the file that was opened, you can use the getFileName method.

Syntax

public synchronized FileOutputStream openFileForWriting() throws IOException;

Return Value

Returns a FileOutputStream object if the user selects a file or returns null if the user cancels the dialog box.

Exceptions

SecurityException if the caller does not have permission to initiate user-directed file I/O.

IOException if an I/O error occurs while attempting to open the file.


openRandomAccessFile (UserFileDialog Class)

 Microsoft SDK for Java

openRandomAccessFile

This method of the UserFileDialog Class displays a dialog box that allows the user to open a file for random access. If the user selects a file, then a FileInputStream object for that file is returned. If the user cancels the dialog box, null is returned. To determine the name of the file that was opened, you can use the getFileName method.

Syntax

public synchronized RandomAccessFile openRandomAccessFile( String mode) throws IOException;

Return Value

Returns a RandomAccessFile object if the user selects a file or returns null if the user cancels the dialog box.

Parameters

mode The mode to open the file in. If mode is "r", the file is opened in read-only mode. If mode is "rw", the file is opened in read-write mode.

Exceptions

IllegalArgumentException if the mode argument is not equal to "r" or to "rw".

SecurityException if the caller does not have permission to initiate user-directed file I/O.

IOException if an I/O error occurs while attempting to open the file.


com.ms.io.clientstorage Package Overview

Microsoft Packages Overview

The com.ms.io.clientstorage package contains classes that manage and enforce storage limitations for principals.

This package contains the following:

Classes

Hierarchy

The three classes in this package work together to keep track of the available storage, allocate storage, and allow information about the files to be retrieved. These classes can be used to allocate scratch space for an applet on the client's computer.

Scratch space is unshared persistent storage that is available only to the signer of the applet that created the storage. If an applet is unsigned, it can obtain and use scratch space if it runs from the class path or from a fully-trusted zone. The amount of scratch space and its location on the client computer is managed by the Microsoft VM so that the scratch space cannot be used maliciously. Scratch space is sometimes used to store configuration information for applets that are re-used.

General Class Information

The ClientStore class keeps track of all client stores. You can use this class to obtain the store for a specified principal, open a shared store, or get the store for the currently-executing principal. You can open a file for reading or writing with a specified type of accessibility. Use this class to obtain scratch space for your applet.

The ClientStore class provides access to individual client stores and enforces storage limitations. This class includes methods that allow you to delete a file, create directories, rename a file, get the length of a file, list the files in a directory, and determine whether a file exists. You can also use the ClientStore class to open a file for reading or writing (as you can with the ClientStorageManager class). The methods in this class allow you to create files and directories and obtain other information about files within your applet's scratch space.

The ClientStoreFile class manages individual files within client stores. Using the methods in this class, you can delete a file, rename it, make a directory for it, determine whether you can read from the file, get the absolute or canonical path for the file, and retrieve other information about a file. This class provides methods for manipulating an individual file within your applet's scratch space.

The following table describes the accessibility flags used to open files in the com.ms.io.clientstorage package.

Accessibility Flags

Flag name | Accessibility type
STORE_FL_ROAMING | The file is accessible to the user from any computer.
STORE_FL_LOCAL | The file is found in a computer-specific local storage area.
OPEN_FL_SHARED | The file is accessible to the user and to other authorized principals.
OPEN_FL_APPEND | When writing to a file, append to the file if it exists; otherwise, open a new file for writing.
OPEN_FL_EXPENDABLE | When the storage area is full, the file is automatically deleted if the deletion will help satisfy a new request.
OPEN_FL_WRITABLE | The file is opened with write access.

Example using com.ms.io.clientstorage

The following example uses the com.ms.io.clientstorage package to create a client store (scratch space) for an applet, write to a file called myFile.txt, and print a list of files in the current directory:

import com.ms.io.clientstorage.*;
import java.io.OutputStream;
import java.io.IOException;
import java.applet.*;

public class MySample extends Applet{

  public void outputToScratch() throws IOException {

    ClientStore s = ClientStorageManager.getStore();

    s.createDirectory("myDirectory");

    ClientStoreFile oneFile =
       new ClientStoreFile(s,"MyFile.txt");

    long x = oneFile.length();

    OutputStream stream1 = oneFile.openOutputStream();

    byte buffer1[] = {1,2,3,4,5};
    stream1.write(buffer1);
    stream1.close();

    OutputStream appendStream = s.openWritable("myFile.txt",true);
    byte buffer2[] = {11,12,13,14,15};
    appendStream.write(buffer2);
    appendStream.close();

    String fileList[] = s.listFiles(".", ClientStore.LIST_FL_RECURSE);
    for (int i = 0; i < fileList.length; i++)  {
       System.out.println(fileList[i]);
    }

    s.deleteFile("secondFile.txt");
  }
}

After compiling the MySample applet, you would place the compiled file into a cabinet file. You would then sign the file using the signcode tool, specifying a level of security that permits access to client storage.


Classes (com.ms.io.clientstorage Package)

 Microsoft SDK for Java

com.ms.io.clientstorage Classes

The com.ms.io.clientstorage package contains the following classes:

ClientStorageManager Class manages the allocation of client stores.

ClientStore Class manages client storage by enforcing storage limitations and providing access to client stores.

ClientStoreFile Class manages and provides access to individual files within client stores.


Hierarchy (com.ms.io.clientstorage Package)

 Microsoft SDK for Java

com.ms.io.clientstorage Hierarchy

The com.ms.io.clientstorage package has the following hierarchy:

Object
  |
  +--ClientStorageManager
  |
  +--ClientStore

File
  |
  +--ClientStoreFile


ClientStorageManager Class (com.ms.io.clientstorage Package)

 Microsoft SDK for Java

ClientStorageManager Class

The ClientStorageManager Class of the com.ms.io.clientstorage package manages the allocation of client stores.

public class ClientStorageManager
{
  // Methods
  public static ClientStorageManager getStorageManager();
  public static ClientStore getStore() throws IOException;
  public ClientStore getStoreForPrincipal(Principal principal,
        ClientStoragePermission data) throws IOException;
  public ClientStore getStoreFromContext() throws IOException;
  public static RandomAccessFile openRandom(String stgfilename,
        boolean writable) throws IOException;
  public static RandomAccessFile openRandom(
        String stgfilename) throws IOException;
  public static RandomAccessFile openRandom(String stgfilename,
        int flags) throws IOException;
  public static InputStream openReadable(String stgfilename,
        int flags) throws IOException;
  public static InputStream openReadable(
        String stgfilename) throws IOException;
  public static OutputStream openWritable(String stgfilename,
        int flags) throws IOException;
  public static OutputStream openWritable(
        String stgfilename) throws IOException;
  public static OutputStream openWritable(String stgfilename,
        boolean append) throws IOException;
}

The methods of the ClientStorageManager class enable you to obtain the store for a specified principal, get the shared store, or obtain the store for the currently executing principal. You can also open a file for reading or writing, and specify flags that determine the accessibility type. Enforcement of storage limitations for each principal is performed by the ClientStore class.


Methods (ClientStorageManager Class)

 Microsoft SDK for Java

ClientStorageManager Class Methods

The ClientStorageManager Class contains the following methods:

getStorageManager obtains the global storage manager.
getStore obtains the store for the currently executing principal.
getStoreForPrincipal retrieves a principal's store.
getStoreFromContext obtains the store for the currently executing principal.
openRandom opens a RandomAccessFile from the store for read or write operations.
openReadable opens a file for reading from the store for the current principal.
openWritable opens a file for writing from the store for the current principal.


getStorageManager (ClientStorageManager Class)

 Microsoft SDK for Java

getStorageManager

This method of the ClientStorageManager Class obtains the global storage manager.

Syntax

public static ClientStorageManager getStorageManager();

Return Value

Returns the global storage manager.


getStore (ClientStorageManager Class)

 Microsoft SDK for Java

getStore

This method of the ClientStorageManager Class obtains the store for the currently executing principal.

Syntax

public static ClientStore getStore() throws IOException;

Return Value

Returns the store for the currently executing principal.

Exceptions

IOException if the context cannot be determined, if no caller has a principal, or if the store for the context does not exist and an error occurs while allocating space for the store.


getStoreForPrincipal (ClientStorageManager Class)

 Microsoft SDK for Java

getStoreForPrincipal

This method of the ClientStorageManager Class retrieves a principal's store.

Syntax

public ClientStore getStoreForPrincipal(Principal principal, ClientStoragePermission data) throws IOExcetion;

Return Value

Returns a store for the specified principal.

Parameters

principal | The principal to obtain the store for.
data | The default data to give to the principal if the principal does not have a store.

Exceptions

IOException if an error occurs while allocating space for the store.


getStoreFromContext (ClientStorageManager Class)

 Microsoft SDK for Java

getStoreFromContext

This method of the ClientStorageManager Class obtains the store for the currently executing principal. This method scans the current call stack to find the store for the last non-system principal.

Syntax

public ClientStore getStoreFromContext() throws IOException;

Return Value

Returns the store for the currently executing principal.

Exceptions

IOException if the context cannot be determined, if no caller has a principal, or if the store for the context does not exist and an error occurs while allocating space for the store.

SecurityException if the caller does not have permission to access the store.


openRandom (ClientStorageManager Class)

 Microsoft SDK for Java

openRandom

The openRandom method of the ClientStorageManager Class contains the following signatures:

openRandom(String stgfilename, boolean writable)
openRandom(String stgfilename)
openRandom(String stgfilename, int flags)

openRandom(String stgfilename, boolean writable)

Opens a RandomAccessFile from the store for read or write operations.

Syntax

public static RandomAccessFile openRandom(String stgfilename, boolean writable) throws IOException;

Return Value

Returns the RandomAccessFile that is opened.

Parameters

stgfilename | The name of the file to open.
writable | Set this value to true if the file should be opened as OPEN_FL_WRITABLE; otherwise, set this value to false.

Exceptions

IOException if the method fails to open the specified file.

openRandom(String stgfilename)

Opens a RandomAccessFile from the store for read operations, with no specified flags.

Syntax

public static RandomAccessFile openRandom(String stgfilename) throws IOException;

Return Value

Returns the RandomAccessFile that is opened.

Parameters

stgfilename The name of the file to open.

Exceptions

IOException if the method fails to open the specified file.

openRandom(String stgfilename, int flags)

Opens a RandomAccessFile from the store for read or write operations.

Syntax

public static RandomAccessFile openRandom(String stgfilename, int flags) throws IOException;

Return Value

Returns the RandomAccessFile that is opened.

Parameters

stgfilename | The name of the file to open.
flags | A value that indicates the requested type of file accessibility. It can be any combination of the following accessibilities: OPEN_FL_SHARED OPEN_FL_EXPENDABLE OPEN_FL_WRITABLE STORE_FL_ROAMING STORE_FL_LOCAL

Exceptions

IOException if the method fails to create or open the specified file.


openReadable (ClientStorageManager Class)

 Microsoft SDK for Java

openReadable

The openReadable method of the ClientStorageManager Class contains the following signatures:

openReadable(String stgfilename, int flags)
openReadable(String stgfilename)

openReadable(String stgfilename, int flags)

Opens a file for reading from the store for the current principal.

Syntax

public static InputStream openReadable(String stgfilename, int flags) throws IOException;

Return Value

Returns the file that is open for reading.

Parameters

stgfilename | The name of the file to open.
flags | A value that indicates the requested type of file accessibility. It can be any combination of the flags OPEN_FL_SHARED, STORE_FL_ROAMING, or STORE_FL_LOCAL from the ClientStore class.

Exceptions

Throws IOException if the file does not exist or cannot be opened for reading.

openReadable(String stgfilename)

Opens a file for reading from the store for the current principal.

Syntax

public static InputStream openReadable(String stgfilename) throws IOException;

Return Value

Returns the file that is open for reading.

Parameters

stgfilename The name of the file to open.

Exceptions

IOException if the file does not exist or cannot be opened.


openWritable (ClientStorageManager Class)

 Microsoft SDK for Java

openWritable

The openWritable method of the ClientStorageManager Class contains the following signatures:

openWritable(String stgfilename, int flags)
openWritable(String stgfilename)
openWritable(String stgfilename, boolean append)

openWritable(String stgfilename, int flags)

Opens a file for writing from the store for the current principal. If the file already exists, it is truncated unless the ClientStore.OPEN_FL_APPEND flag is provided.

Syntax

public static OutputStream openWritable(String stgfilename, int flags) throws IOException;

Return Value

Returns the output stream that is open for writing.

Parameters

stgfilename | The name of the file to open for writing.
flags | A value that indicates the requested type of file accessibility. This value can be any combination of the flags OPEN_FL_APPEND, OPEN_FL_SHARED, STORE_FL_ROAMING, or STORE_FL_LOCAL from the ClientStore class.

Exceptions

IOException if the file could not be created or truncated.

openWritable(String stgfilename)

Opens a file for writing from the store for the current principal. If the file already exists, it is truncated.

Syntax

public static OutputStream openWritable(String stgfilename) throws IOException;

Return Value

Returns the file that is open for writing.

Parameters

stgfilename The name of the storage file to open.

Exceptions

IOException if the file could not be created or truncated.

openWritable(String stgfilename, boolean append)

Opens a file for writing from the store for the current principal. If the file already exists, it is truncated or appended.

Syntax

public static OutputStream openWritable(String stgfilename, boolean append) throws IOException;

Return Value

Returns the file that is open for writing.

Parameters

stgfilename | The name of the storage file to open.
append | The value that indicates whether to append to an existing file. If the value is true, append to the existing file; otherwise, do not append.

Exceptions

IOException if the file could not be created or truncated.


ClientStore Class (com.ms.io.clientstorage Package)

 Microsoft SDK for Java

ClientStore Class

The ClientStore Class of the com.ms.io.clientstorage package helps manage client storage by enforcing storage limitations and providing access to client stores. It includes methods for creating directories, renaming files, getting a list of files in a directory, deleting files, and reading or writing to a file.

public class ClientStore
{
  // Fields
  public static final int LIST_FL_NO_DIRECTORIES;
  public static final int LIST_FL_NO_FILES;
  public static final int LIST_FL_RECURSE;
  public static final int OPEN_FL_APPEND;
  public static final int OPEN_FL_EXPENDABLE;
  public static final int OPEN_FL_SHARED;
  public static final int OPEN_FL_WRITABLE;
  public static final int STORE_FL_LOCAL;
  public static final int STORE_FL_ROAMING;

  // Methods
  public boolean canAccessRoamingFiles();
  public void copyFile(String curstgfilename,
        String newstgfilename) throws IOException;
  public void copyFile(String curstgfilename, int curflags, String
        newstgfilename, int newflags) throws IOException;
  public void createDirectories(String stgdirpath)
        throws IOException;
  public void createDirectories(String stgdirpath,
        int flags) throws IOException;
  public void createDirectory(String stgdirname)
        throws IOException;
  public void createDirectory(String stgdirname, int flags) throws
        IOException;
  public void deleteDirectory(String stgfilename)
        throws IOException;
  public void deleteDirectory(String stgfilename,
        int flags) throws IOException;
  public void deleteFile(String stgfilename) throws IOException;
  public void deleteFile(String stgfilename, int flags)
        throws IOException;
  public boolean equals(Object o);
  public boolean fileExists(String stgfilename) throws IOException;
  public boolean fileExists(String stgfilename, int flags)
        throws IOException;
  protected void finalize();
  public String getCurrentDirectory();
  public long getFileSize(String stgfilename) throws IOException;
  public long getFileSize(String stgfilename, int flags)
        throws IOException;
  public long getLastModificationTime(String stgfilename)
        throws IOException;
  public long getLastModificationTime(String stgfilename,
        int flags) throws IOException;
  public long getStorageLimit();
  public long getStorageRemaining();
  public long getStorageUsed();
  public long getStorageUsed(int flags);
  public boolean isDirectory(String stgfilename)
        throws IOException;
  public boolean isDirectory(String stgfilename, int flags) throws
        IOException;
  public boolean isExpendable(String stgfilename)
        throws IOException;
  public boolean isExpendable(String stgfilename,
        int flags) throws IOException;
  public boolean isFile(String stgfilename) throws IOException;
  public boolean isFile(String stgfilename, int flags)
        throws IOException;
  public String[] listFiles(String stgdir) throws IOException;
  public String[] listFiles(String stgdir,
        FilenameFilter filter) throws IOException;
  public String[] listFiles(String stgdir, int flags)
        throws IOException;
  public String[] listFiles(String stgdir, FilenameFilter filter,
        int flags) throws IOException;
  public void markFileAsExpendable(String stgfilename,
        boolean deletewhenfull) throws IOException;
  public void markFileAsExpendable(String stgfilename, int flags,
        boolean deletewhenfull) throws IOException;
  public RandomAccessFile openRandom(String stgfilename,
        boolean writable) throws IOException;
  public RandomAccessFile openRandom(String stgfilename,
        int flags) throws IOException;
  public RandomAccessFile openRandom(String stgfilename)
        throws IOException;
  public InputStream openReadable(String stgfilename,
        int flags) throws IOException;
  public InputStream openReadable(String stgfilename)
        throws IOException;
  public OutputStream openWritable(String stgfilename,
        int flags) throws IOException;
  public OutputStream openWritable(String stgfilename)
        throws IOException;
  public OutputStream openWritable(String stgfilename,
        boolean append) throws IOException;
  public boolean purgeExpendableFiles(long spacerequired,
        int flags) throws IOException;
  public boolean purgeExpendableFiles(long spacerequired)
        throws IOException;
  public boolean purgeExpendableFiles() throws IOException;
  public void renameFile(String curstgfilename,
        String newstgfilename) throws IOException;
  public void renameFile(String curstgfilename, int curflags,
        String newstgfilename, int newflags) throws IOException;
  public void setCurrentDirectory(String newcurdir)
        throws IOException;
  public void setStorageLimit(long newlimit) throws IOException;
}


Methods (ClientStore Class)

 Microsoft SDK for Java

ClientStore Class Methods

The ClientStore Class contains the following methods:

canAccessRoamingFiles determines whether the principal can access roaming files.
copyFile copies the contents of an existing file to a new file, with the same flags set.
createDirectories ensures that the specified directory path exists.
createDirectory creates a new directory.
deleteDirectory deletes the specified directory.
deleteFile deletes the specified file.
equals determines whether the current object is equal to the specified object.
fileExists determines whether the specified file exists.
finalize performs any necessary cleanup before garbage collection.
getCurrentDirectory gets the current directory in the store.
getFileSize retrieves the size of the specified file, measured in bytes.
getLastModificationTime retrieves the time that the specified file was last modified.
getStorageLimit retrieves the amount of storage space allocated to the principal.
getStorageRemaining retrieves the principal's remaining storage.
getStorageUsed retrieves the amount of storage space the principal has used.
isDirectory determines whether the specified file is a directory.
isExpendable determines whether the specified file can be deleted when the client storage becomes full.
isFile determines whether the specified file is a "normal" file.
listFiles lists files in the specified directory.
markFileAsExpendable marks the specified file so that it is automatically deleted when the storage area is full.
openRandom opens a RandomAccessFile from the store for read or write operations.
openReadable opens an existing file for reading.
openWritable opens a file for writing.
purgeExpendableFiles searches for files that are marked as expendable.
renameFile gives an existing file a new name, possibly moving it to a new directory.
setCurrentDirectory sets the current directory in the store.
setStorageLimit sets the amount of storage space allocated to the principal.


canAccessRoamingFiles (ClientStore Class)

 Microsoft SDK for Java

canAccessRoamingFiles

This method of the ClientStore Class determines whether the principal can access roaming files.

Syntax

public boolean canAccessRoamingFiles();

Return Value

Returns true if the principal can access roaming files; otherwise, returns false.


copyFile (ClientStore Class)

 Microsoft SDK for Java

copyFile

The copyFile method of the ClientStore Class contains the following signatures:

copyFile(String curstgfilename, String newstgfilename)
copyFile(String curstgfilename, int curflags, String newstgfilename, int newflags)

copyFile(String curstgfilename, String newstgfilename)

Copies the contents of an existing file to a new file, with the same flags set.

Syntax

public void copyFile(String curstgfilename, String newstgfilename) throws IOException;

Parameters

curstgfilename | The name of the file to copy from.
newstgfilename | The name of the newly created file.

Exceptions

IOException if either one or the other file name is not valid, if curstgfilename cannot be found, or if either file name is a directory.

copyFile(String curstgfilename, int curflags, String newstgfilename, int newflags)

Copies the contents of an existing files to a new file. If OOPEN_FL_SHARED and OPEN_FL_EXPENDABLE are set for the existing file, the new file will be created with these same flags.

Syntax

public void copyFile(String curstgfilename, int curflags, String newstgfilename, int newflags) thows IOException;

Parameters

curstgfilename | The name of the file to copy from.
curflags | A value that indicates the storage area in which to find curstgfilename. It can be either or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.
newstgfilename | The name of the newly created file.
newflags | A value that indicates the storage area in which to create newstgfilename. It can be either or both of the following: STORE_FL_LOCAL STORE_FL_ROAMING

Exceptions

IOException if either one or the other file name is not valid, if curstgfilename cannot be found, or if either file name is a directory.


createDirectories (ClientStore Class)

 Microsoft SDK for Java

createDirectories

The createDirectories method of the ClientStore Class contains the following signatures:

createDirectories(String stgdirpath)
createDirectories(String stgdirpath, int flags)

createDirectories(String stgdirpath)

Ensures that the specified directory path exists. Missing path components are created if they do not exist.

Syntax

public void createDirectories(String stgdirpath) throws IOException;

Parameters

stgdirpath The path of the directory to create.

Exceptions

IOException if the directory already exists or if the directory name already exists as a file.

createDirectories(String stgdirpath, int flags)

Ensures that the specified directory path exists. Missing path components are created if they do not exist.

Syntax

public void createDirectories(String stgdirpath, int flags) throws IOException;

Parameters

stgdirpath | The name of the directory to create.
flags | A value that indicates the storage area in which to create the components of stgdirpath. It can be either or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.

Exceptions

IOException if the directory already exists or the directory name already exists as a file.


createDirectory (ClientStore Class)

 Microsoft SDK for Java

createDirectory

The createDirectory method of the ClientStore Class contains the following signatures:

createDirectory(String stgdirname)
createDirectory(String stgdirname, int flags)

createDirectory(String stgdirname)

Creates a new directory.

Syntax

public void createDirectory(String stgdirname) throws IOException;

Parameters

stgdirname The name of the directory to create.

Exceptions

IOException if the directory already exists or if the directory name already exists as a file.

createDirectory(String stgdirname, int flags)

Creates a new directory.

Syntax

public void createDirectory(String stgdirname, int flags) throws IOException;

Parameters

stgdirname | The name of the directory to create.
flags | A value that indicates the storage area in which to create stgdirname. It can be either or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.

Exceptions

IOException if the directory already exists or the directory name already exists as a file.


deleteDirectory (ClientStore Class)

 Microsoft SDK for Java

deleteDirectory

The deleteDirectory method of the ClientStore Class contains the following signatures:

deleteDirectory(String stgfilename)
deleteDirectory(String stgfilename, int flags)

deleteDirectory(String stgfilename)

Deletes the specified directory.

Syntax

public void deleteDirectory(String stgfilename) throws IOException;

Parameters

stgfilename The name of the directory to delete.

Exceptions

IOException if the directory name is not valid.

deleteDirectory(String stgfilename, int flags)

Deletes a specified directory.

Syntax

public void deleteDirectory(String stgfilename, int flags) throws IOException;

Parameters

stgfilename | The name of the directory to delete.
flags | A value that indicates the storage area from which to delete stgfilename. It can be either or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.

Exceptions

IOException if the directory name is not valid.


deleteFile (ClientStore Class)

 Microsoft SDK for Java

deleteFile

The deleteFile method of the ClientStore Class contains the following signatures:

deleteFile(String stgfilename)
deleteFile(String stgfilename, int flags)

deleteFile(String stgfilename)

Deletes the specified file.

Syntax

public void deleteFile(String stgfilename) throws IOException;

Parameters

stgfilename The name of the file to delete.

Exceptions

IOException if there is an error while attempting to delete the file.

deleteFile(String stgfilename, int flags)

Deletes the specified file.

Syntax

public void deleteFile(String stgfilename, int flags) throws IOException;

Parameters

stgfilename | The name of the file to delete.
flags | A value that indicates the storage area in which to delete stgfilename. It can be either or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.

Exceptions

IOException if there is an error while attempting to delete the file.


equals (ClientStore Class)

 Microsoft SDK for Java

equals

This method of the ClientStore Class determines whether the current object is equal to the specified object.

Syntax

public boolean equals(Object o);

Return Value

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

Parameters

o The object that the current object is being compared against.


fileExists (ClientStore Class)

 Microsoft SDK for Java

fileExists

The fileExists method of the ClientStore Class contains the following signatures:

fileExists(String stgfilename)
fileExists(String stgfilename, int flags)

fileExists(String stgfilename)

Determines whether the specified file exists.

Syntax

public boolean fileExists(String stgfilename) throws IOException;

Return Value

Returns true if the file exists; otherwise, returns false.

Parameters

stgfilename The name of the file whose existence is being determined.

Exceptions

IOException if the specified file is a directory.

fileExists(String stgfilename, int flags)

Determines whether the specified file exists.

Syntax

public boolean fileExists(String stgfilename, int flags) throws IOException;

Return Value

Returns true if the file exists; otherwise, returns false.

Parameters

stgfilename | The name of the file whose existence is being determined.
flags | A value that indicates the storage area in which to search for stgfilename. This value should be one or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.


finalize (ClientStore Class)

 Microsoft SDK for Java

finalize

This method of the ClientStore Class performs any necessary cleanup before garbage collection.

Syntax

protected void finalize();


getCurrentDirectory (ClientStore Class)

 Microsoft SDK for Java

getCurrentDirectory

This method of the ClientStore Class gets the current directory in the store.

Syntax

public String getCurrentDirectory();

Return Value

Returns the name of the current directory.


getFileSize (ClientStore Class)

 Microsoft SDK for Java

getFileSize

The getFileSize method of the ClientStore Class contains the following signatures:

getFileSize(String stgfilename)
getFileSize(String stgfilename, int flags)

getFileSize(String stgfilename)

Retrieves the size of the specified file, measured in bytes.

Syntax

public long getFileSize(String stgfilename) throws IOException;

Return Value

Returns the size of the file, in bytes.

Parameters

stgfilename The name of the file whose size is being measured.

Exceptions

IOException if the file name is not valid or if the file cannot be found.

getFileSize(String stgfilename, int flags)

Retrieves the size of the specified file, in bytes.

Syntax

public long getFileSize(String stgfilename, int flags) throws IOException;

Return Value

Returns the size of the file, in bytes.

Parameters

Stgfilename | The name of the file whose size is being measured.
Flags | A value that indicates the storage area in which to search for stgfilename. It can one or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.

Exceptions

IOException if the file name is not valid or the file cannot be found.


getLastModificationTime (ClientStore Class)

 Microsoft SDK for Java

getLastModificationTime

The getLastModificationTime method of the ClientStore Class contains the following signatures:

getLastModificationTime(String stgfilename)
getLastModificationTime(String stgfilename, int flags)

getLastModificationTime(String stgfilename)

Retrieves the time that the specified file was last modified.

Syntax

public long getLastModificationTime(String stgfilename) throws IOException;

CAUTION The return value is system-dependent and should only be used to compare with values returned by lastModified. It should not be interpreted as an absolute time.

Return Value

Returns the time that the file specified by this object was last modified.

Parameters

stgfilename The name of the file whose last modification time is being retrieved.

Exceptions

IOException if the file name is invalid or if the file does not exist.

getLastModificationTime(String stgfilename, int flags)

Retrieves the time that the specified file was last modified.

Syntax

public long getLastModificationTime(String stgfilename, int flags) throws IOException;

CAUTION The return value is system-dependent and should only be used to compare with values returned by lastModified. It should not be interpreted as an absolute time.

Return Value

Returns the time that the file specified by this object was last modified.

Parameters

stgfilename | The name of the file whose last modification time is being retrieved.
flags | A value that indicates the storage area in which to search for stgfilename. It can be one or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.

Exceptions

IOException if the file name is invalid or if the file does not exist.


getStorageLimit (ClientStore Class)

 Microsoft SDK for Java

getStorageLimit

This method of the ClientStore Class retrieves the amount of storage space allocated to the principal.

Syntax

public long getStorageLimit();

Return Value

Returns the amount of storage space allocated to the principal, in bytes.


getStorageRemaining (ClientStore Class)

 Microsoft SDK for Java

getStorageRemaining

This method of the ClientStore Class retrieves the principal's remaining storage.

Syntax

public long getStorageRemaining();

Return Value

Returns the principal's remaining storage, in bytes.


getStorageUsed (ClientStore Class)

 Microsoft SDK for Java

getStorageUsed

The getStorageUsed method of the ClientStore Class contains the following signatures:

getStorageUsed()
getStorageUsed(int flags)

getStorageUsed()

Retrieves the amount of storage space the principal has used.

Syntax

public long getStorageUsed();

Return Value

Returns the amount of space used, in bytes.

getStorageUsed(int flags)

Retrieves the amount of storage space the principal has used.

Syntax

public long getStorageUsed(int flags);

Return Value

Returns the amount of space used, in bytes.

Parameters

flags A value that indicates the storage area in which to find the space used for. It can be one or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.


isDirectory (ClientStore Class)

 Microsoft SDK for Java

isDirectory

The isDirectory method of the ClientStore Class contains the following signatures:

isDirectory(String stgfilename)
isDirectory(String stgfilename, int flags)

isDirectory(String stgfilename)

Determines whether the specified file is a directory.

Syntax

public boolean isDirectory(String stgfilename) throws IOException;

Return Value

Returns true if the file is a directory; otherwise, returns false.

Parameters

stgfilename The name of the file.

Exceptions

IOException if the file name is not valid or if the file cannot be found.

isDirectory(String stgfilename, int flags)

Determines whether the specified file is a directory.

Syntax

public boolean isDirectory(String stgfilename, int flags) throws IOException;

Return Value

Returns true if the file is a directory; otherwise, returns false.

Parameters

stgfilename | The name of the file.
flags | A value that indicates the storage area in which to search for stgfilename. It can be one or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.

Exceptions

IOException if the file name is not valid or if the file cannot be found.


isExpendable (ClientStore Class)

 Microsoft SDK for Java

isExpendable

The isExpendable method of the ClientStore Class contains the following signatures:

isExpendable(String stgfilename)
isExpendable(String stgfilename, int flags)

isExpendable(String stgfilename)

Determines whether the specified file can be deleted when the client storage becomes full.

Syntax

public boolean isExpendable(String stgfilename) throws IOException;

Return Value

Returns true if the file was opened with the OPEN_FL_EXPENDABLE flag.

Parameters

stgfilename The name of the file to check.

Exceptions

IOException if the file name is not valid or if the file cannot be found.

See Also

OPEN_FL_EXPENDABLE, markFileAsExpendable, purgeExpendableFiles

isExpendable(String stgfilename, int flags)

Determines whether the specified file can be deleted when the client storage becomes full.

Syntax

public boolean isExpendable(String stgfilename, int flags) throws IOException;

Return Value

Returns true if the file was opened with the OPEN_FL_EXPENDABLE flag.

Parameters

stgfilename | The name of the file to check.
flags | A value that indicates the storage area in which to search for stgfilename. It can be one or both of STORE_FL_LOCAL and STORE_FL_ROAMING.

Exceptions

IOException if the file name is not valid or if the file cannot be found.


isFile (ClientStore Class)

 Microsoft SDK for Java

isFile

The isFile method of the ClientStore Class contains the following signatures:

isFile(String stgfilename)
isFile(String stgfilename, int flags)

isFile(String stgfilename)

Determines whether the specified file is a "normal" file. A file is normal if it is not a directory and if it satisfies other system-dependent criteria. Any non-directory file created by a Java application is guaranteed to be a normal file.

Syntax

public boolean isFile(String stgfilename) throws IOException;

Return Value

Returns true if the file is normal; otherwise, returns false.

Parameters

stgfilename The name of the file.

isFile(String stgfilename, int flags)

Determines whether the specified file is a "normal" file. A file is normal if it is not a directory and if it satisfies other system-dependent criteria. Any non-directory file created by a Java application is guaranteed to be a normal file.

Syntax

public boolean isFile(String stgfilename, int flags) throws IOException;

Return Value

Returns true if the file is normal; otherwise, returns false.

Parameters

stgfilename | The name of the file.
flags | A value that indicates the storage area in which to search for stgfilename. It can be one or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.

Exceptions

IOException if the file name is not valid or if the file cannot be found.


listFiles (ClientStore Class)

 Microsoft SDK for Java

listFiles

The listFiles method of the ClientStore Class contains the following signatures:

listFiles(String stgdir)
listFiles(String stgdir, FilenameFilter filter)
listFiles(String stgdir, int flags)
listFiles(String stgdir, FilenameFilter filter, int flags)

listFiles(String stgdir)

Lists files in the specified directory.

Syntax

public String[] listFiles(String stgdir) throws IOException;

Return Value

Returns the names of the files in the specified directory.

Parameters

stgdir The directory to list files in. If null, the current directory is used.

Exceptions

IOException if the specified directory is not valid.

listFiles(String stgdir, FilenameFilter filter)

Lists files in the specified directory.

Syntax

public String[] listFiles(String stgdir, FilenameFilter filter) throws IOException;

Parameters

stgdir | The directory to list files in. If null, the current directory is used.
filter | The filter that determines which files to list. File patterns, such as "*.txt", can be specified by using the com.ms.util.WildcardExpression class.

Exceptions

IOException if the specified directory is not valid.

listFiles(String stgdir, int flags)

Lists files in the specified directory.

Syntax

public String[] listFiles(String stgdir, int flags) throws IOException;

Return Value

Returns a String list of the files in the directory.

Parameters

stgdir | The directory to list files in. If null, the current directory is used.
flags | The listing modifiers for this method. This value should be one or both of LIST_FL_RECURSE and LIST_FL_NO_DIRECTORIES to control the listing behavior, and one or both of STORE_FL_LOCAL and STORE_FL_ROAMING to select the storage area to list files in.

Exceptions

IOException if the specified directory is invalid.

listFiles(String stgdir, FilenameFilter filter, int flags)

Lists files in the specified directory.

Syntax

public String[] listFiles(String stgdir, FilenameFilter filter, int flags) throws IOException;

Return Value

Returns a String list of the files in the directory.

Parameters

stgdir | The directory to list files in. If null, the current directory is used.
filter | The filter that determines which files to list. File patterns, such as "*.txt," can be specified by using the com.ms.util.WildcardExpression class.
flags | The listing modifiers for this method. This value should be one or both of LIST_FL_RECURSE and LIST_FL_NO_DIRECTORIES to control the listing behavior, and one or both of STORE_FL_LOCAL and STORE_FL_ROAMING to select the storage area to list files in.

Exceptions

IOException if the directory is invalid.


markFileAsExpendable (ClientStore Class)

 Microsoft SDK for Java

markFileAsExpendable

The markFileAsExpendable method of the ClientStore Class contains the following signatures:

markFileAsExpendable(String stgfilename, boolean deletewhenfull)
markFileAsExpendable(String stgfilename, int flags, boolean deletewhenfull)

markFileAsExpendable(String stgfilename, boolean deletewhenfull)

Marks the specified file so that it is automatically deleted when the storage area is full.

Syntax

public void markFileAsExpendable(String stgfilename, boolean deletewhenfull) throws IOExceptin;

Parameters

stgfilename | The name of the file to mark.
deletewhenfull | Set this value to true if the file is to be deleted when the client storage area is full; otherwise, set this value to false.

Exceptions

IOException if the file name is not valid, if the file cannot be found, or if the file name specifies a directory.

See Also

OPEN_FL_EXPENDABLE

markFileAsExpendable(String stgfilename, int flags, boolean deletewhenfull)

Marks the specified file so that it is automatically deleted when the storage area is full.

Syntax

public void markFileAsExpendable(String stgfilename, int flags, boolean deletewhenfull) throws IOException;

Parameters

stgfilename | The name of the file to mark.
flags | A value that indicates the storage area from which to delete stgfilename. It can be either or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.
deletewhenfull | Set this value to true if the file is to be deleted when the client storage area is full; otherwise, set this value to false.

Exceptions

IOException if the file name is not valid, if the file cannot be found, or if the file name specifies a directory.

See Also

OPEN_FL_EXPENDABLE


openRandom (ClientStore Class)

 Microsoft SDK for Java

openRandom

The openRandom method of the ClientStore Class contains the following signatures:

openRandom(String stgfilename, boolean writable)
openRandom(String stgfilename, int flags)
openRandom(String stgfilename)

openRandom(String stgfilename, boolean writable)

Opens a RandomAccessFile from the store for read or write operations.

Syntax

public RandomAccessFile openRandom(String stgfilename, boolean writable) throws IOException;

Return Value

Returns the RandomAccessFile that is opened.

Parameters

stgfilename | The name of the file to open.
writable | Set this value to true if the file is to be opened as OPEN_FL_WRITABLE; otherwise, set this value to false.

Exceptions

IOException if the method fails to create or open the specified file.

openRandom(String stgfilename, int flags)

Opens a RandomAccessFile from the store for read or write operations.

Syntax

public RandomAccessFile openRandom(String stgfilename, int flags) throws IOException;

Return Value

Returns the RandomAccessFile that is opened.

Parameters

stgfilename | The name of the file to open.
flags | A value that indicates the requested type of file accessibility. It can be any combination of the following accessibilities: STORE_FL_LOCAL STORE_FL_ROAMING OPEN_FL_EXPENDABLE OPEN_FL_WRITABLE OPEN_FL_SHARED

Exceptions

IOException if the method fails to create or open the specified file.

openRandom(String stgfilename)

Opens a RandomAccessFile from the store for read operations, with no specified flags.

Syntax

public RandomAccessFile openRandom(String stgfilename) throws IOException;

Return Value

Returns the RandomAccessFile that is opened.

Parameters

stgfilename The name of the file to open.

Exceptions

IOException if the method fails to open the specified file.


openReadable (ClientStore Class)

 Microsoft SDK for Java

openReadable

The openReadable method of the ClientStore Class contains the following signatures:

openReadable(String stgfilename, int flags)
openReadable(String stgfilename)

openReadable(String stgfilename, int flags)

Opens an existing file for reading.

Syntax

public InputStream openReadable(String stgfilename, int flags) throws IOException;

Return Value

Returns the input stream that is open for reading.

Parameters

stgfilename | The name of the file to open for reading.
flags | A value that indicates the requested type of file accessibility. It can be one or both of STORE_FL_ROAMING and STORE_FL_LOCAL.

Exceptions

IOException if the method fails to create the file or if there is an error while attempting to truncate an existing file.

openReadable(String stgfilename)

Opens an existing file for reading.

Syntax

public InputStream openReadable(String stgfilename) throws IOException;

Return Value

Returns the input stream that is open for reading.

Parameters

stgfilename The name of the file to open for reading.

Exceptions

IOException if the method fails to create the file or if there is an error while attempting to truncate an existing file.


openWritable (ClientStore Class)

 Microsoft SDK for Java

openWritable

The openWritable method of the ClientStore Class contains the following signatures:

openWritable(String stgfilename, int flags)
openWritable(String stgfilename)
openWritable(String stgfilename, boolean append)

openWritable(String stgfilename, int flags)

Opens a file for writing. If the file already exists, it is truncated unless the OPEN_FL_APPEND flag is provided.

Syntax

public OutputStream openWritable(String stgfilename, int flags) throws IOException;

Return Value

Returns the output stream that is open for writing.

Parameters

stgfilename | The name of the file to open for writing.
flags | A value that indicates the requested type of file accessibility. It can be any combination of the following accessibilities: OPEN_FL_SHARED STORE_FL_ROAMING OPEN_FL_APPEND OPEN_FL_EXPENDABLE OPEN_FL_WRITABLE STORE_FL_LOCAL

Exceptions

IOException if the method fails to create the file or if there is an error while attempting to truncate an existing file.

openWritable(String stgfilename)

Opens a file for writing. If the file already exists, it is truncated.

Syntax

public OutputStream openWritable(String stgfilename) throws IOException;

Return Value

Returns the output stream that is open for writing.

Parameters

stgfilename The name of the file to open for writing.

Exceptions

IOException if the method fails to create the file or if there is an error while attempting to truncate an existing file.

openWritable(String stgfilename, boolean append)

Opens a file for writing. If the file already exists, it is truncated or appended, depending on the value of append.

Syntax

public OutputStream openWritable(String stgfilename, boolean append) throws IOException;

Return Value

Returns the output stream that is open for writing.

Parameters

stgfilename | The storage file to open.
append | The value that determines whether to append to an existing file. If true, appends to an existing file; otherwise, truncates an existing file.

Exceptions

IOException if the file could not be created or truncated.


purgeExpendableFiles (ClientStore Class)

 Microsoft SDK for Java

purgeExpendableFiles

The purgeExpendableFiles method of the ClientStore Class contains the following signatures:

purgeExpendableFiles(long spacerequired, int flags)
purgeExpendableFiles(long spacerequired)
purgeExpendableFiles()

purgeExpendableFiles(long spacerequired, int flags)

Searches for files that are marked as expendable. If files are found and the total space used by the found files exceeds spacerequired, the found files are deleted. A file can be marked expendable by using the markFileAsExpendable method or by creating the file with the OPEN_FL_EXPENDABLE flag.

Syntax

public boolean purgeExpendableFiles(long spacerequired, int flags) throws IOException;

Return Value

Returns true if files were deleted; otherwise, returns false.

Parameters

spacerequired | The number of bytes needed. If spacerequired is set to 0, all the files marked as expendable are deleted.
flags | A value that indicates the storage area from which to delete stgfilename. It can be either or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.

Exceptions

IOException if an error occurs while deleting the files.

purgeExpendableFiles(long spacerequired)

Searches for files that are marked as expendable. If files are found and the total space used by the found files exceeds spacerequired, the found files are deleted. A file can be marked expendable by using the markFileAsExpendable method or by creating the file with the OPEN_FL_EXPENDABLE flag.

Syntax

public boolean purgeExpendableFiles(long spacerequired) throws IOException;

Return Value

Returns true if files were deleted; otherwise, returns false.

Parameters

spacerequired The number of bytes needed. If spacerequired is set to 0, all the files found are deleted.

Exceptions

IOException if an error occurs while deleting the files.

purgeExpendableFiles()

Deletes all files that are marked as expendable. Files are marked expendable by using the markFileAsExpendable method or by creating them with the OPEN_FL_EXPENDABLE flag.

Syntax

public boolean purgeExpendableFiles() throws IOException;

Return Value

Returns true if files were deleted; otherwise, returns false.

Exceptions

IOException if an error occurs while deleting the files.


renameFile (ClientStore Class)

 Microsoft SDK for Java

renameFile

The renameFile method of the ClientStore Class contains the following signatures:

renameFile(String curstgfilename, String newstgfilename)
renameFile(String curstgfilename, int curflags, String newstgfilename, int newflags)

renameFile(String curstgfilename, String newstgfilename)

Gives an existing file a new name, possibly moving it to a new directory.

Syntax

public void renameFile(String curstgfilename, String newstgfilename) throws IException;

Parameters

curstgfilename | The file to rename.
newstgfilename | The new name of the file.

Exceptions

Throws IOException if any one of the following is true:

  • Either of the filenames is not valid.

  • The source file cannot be found.

  • The source file name is a file and the destination is a directory.

renameFile(String curstgfilename, int curflags, String newstgfilename, int newflags)

Renames and assigns new flags to an existing file.

Syntax

public void renameFile(String curstgfilename, int curflags, String newstgfilename, int newflags) throw IOException;

Parameters

curstgfilename | The file to rename.
curflags | A value that indicates the storage area in which to find curstgfilename. It can be either or both of the STORE_FL_LOCAL and STORE_FL_ROAMING flags.
newstgfilename | The new name of the file.
newflags | The new flags that are set for the file. This value can be any combination of the following: STORE_FL_LOCAL STORE_FL_ROAMING OPEN_FL_EXPENDABLE

Exceptions

IOException if one of the following is true:

  • Either one or the other file name is not valid.

  • The source file cannot be found.

  • The source file name is a directory and the destination is a file.

  • The source file name is a file and the destination is a directory.


setCurrentDirectory (ClientStore Class)

 Microsoft SDK for Java

setCurrentDirectory

This method of the ClientStore Class sets the current directory in the store.

Syntax

public void setCurrentDirectory(String newcurdir) throws IOException;

Parameters

newcurdir The new current directory.

Exceptions

IOException if the specified directory is not valid.


setStorageLimit (ClientStore Class)

 Microsoft SDK for Java

setStorageLimit

This method of the ClientStore Class sets the amount of storage space allocated to the principal. All callers of this method must be fully trusted.

Syntax

public void setStorageLimit(long newlimit) throws IOException;

Parameters

newlimit The amount of space allocated, in bytes.

Exceptions

IOException if the new limit could not be set.

SecurityException if any caller is not fully trusted.


Fields (ClientStore Class)

 Microsoft SDK for Java

ClientStore Class Fields

The ClientStore Class contains the following fields.

LIST_FL_NO_DIRECTORIES | Indicates that list operations do not include directories.
LIST_FL_NO_FILES | Indicates that list operations do not include files.
LIST_FL_RECURSE | Indicates that list operations find files recursively. When used in conjunction with a filter, the directory will be recursed only if the filter returns true.
OPEN_FL_APPEND | Indicates a type of accessibility for a file that is opened with the openWritable method. If the file already exists, it will be appended. If the file does not exist, a new file is opened for writing.
OPEN_FL_EXPENDABLE | Indicates a type of accessibility for a file that is automatically deleted when the storage area is full, if deleting the file will help satisfy a request for opening a new file.
OPEN_FL_SHARED | Indicates a type of accessibility for a file that is opened with the openWritable or the openReadable method. Opening the file with this accessibility type makes the file accessible to other principals co-signed or otherwise authorized by the owning principal.
OPEN_FL_WRITABLE | Indicates a type of accessibility for a file that is opened with the openRandom method. The file is opened with write access.
STORE_FL_LOCAL | Indicates a type of accessibility for a file that is manipulated by various other methods. If this type of accessibility is specified, the file must be found in a computer-specific local storage area.
STORE_FL_ROAMING | Indicates a type of accessibility for a file that is opened with the openWritable or openReadable method. Opening a file with this accessibility type makes the file accessible to the user from any computer that the user logs on to. The file that is opened will be added to the user's profile.


ClientStoreFile Class (com.ms.io.clientstorage Package)

 Microsoft SDK for Java

ClientStoreFile Class

The ClientStoreFile Class of the com.ms.io.clientstorage package manages and provides access to individual files within client stores.

public class ClientStoreFile extends File
{
  // Constructors
  public ClientStoreFile(String stgfilename) throws IOException;
  public ClientStoreFile(ClientStore store,
        String stgfilename) throws IOException;
  public ClientStoreFile(String stgfilename, int flags)
        throws IOException;
  public ClientStoreFile(ClientStore store, String stgfilename,
        int flags) throws IOException;

  // Methods
  public boolean canRead();
  public boolean canWrite();
  public boolean delete();
  public boolean equals(Object obj);
  public boolean exists();
  public String getAbsolutePath();
  public String getCanonicalPath() throws IOException;
  public boolean isAbsolute();
  public boolean isDirectory();
  public boolean isFile();
  public long lastModified();
  public long length();
  public String[] list();
  public String[] list(FilenameFilter filter);
  public boolean mkdir();
  public boolean mkdirs();
  public InputStream openInputStream() throws IOException;
  public OutputStream openOutputStream() throws IOException;
  public OutputStream openOutputStream(boolean append)
        throws IOException;
  public RandomAccessFile openRandom() throws IOException;
  public RandomAccessFile openRandom(boolean writable)
        throws IOException;
  public boolean renameTo(File dest);
}

Using the methods in this class, you can delete a file, rename it, make a directory for it, determine whether you can read from the file, get the absolute or canonical path for the file, and retrieve other file characteristics.

This class extends the java.io.File class and uses the java.io.File.getPath method to retrieve the pathfor the ClientStoreFile object.

Hierarchy

File
  |
  +--ClientStoreFile


Constructors (ClientStoreFile Class)

 Microsoft SDK for Java

ClientStoreFile Class Constructors

The ClientStoreFile Class contains the following constructors:

ClientStoreFile(String stgfilename)
ClientStoreFile(ClientStore store, String stgfilename)
ClientStoreFile(String stgfilename, int flags)
ClientStoreFile(ClientStore store, String stgfilename, int flags)

ClientStoreFile(String stgfilename)

Creates a ClientStoreFile object from the specified file name.

Syntax

public ClientStoreFile(String stgfilename) throws IOException;

Return Value

Returns the ClientStoreFile object that represents the specified file.

Parameters

stgfilename The name of the file.

Exceptions

IOException if there is an I/O error.

ClientStoreFile(ClientStore store, String stgfilename)

Creates a ClientStoreFile object from the file name and the ClientStore object that the file is located in.

Syntax

public ClientStoreFile(ClientStore store, String stgfilename) throws IOException;

Return Value

Returns the ClientStoreFile object representing the file that is located in the client store.

Parameters

store | The client store that contains the specified file.
stgfilename | The name of the file.

Exceptions

IOException if there is an I/O error.

ClientStoreFile(String stgfilename, int flags)

Creates a ClientStoreFile object from the file name and any specified file flags.

Syntax

public ClientStoreFile(String stgfilename, int flags) throws IOException;

Return Value

Returns the ClientStoreFile object representing the file that is located in the client store.

Parameters

stgfilename | The name of the file.
flags | The flags that can be used with any of the file operations in this class. They can be any combination of the following: OPEN_FL_SHARED STORE_FL_ROAMING OPEN_FL_APPEND OPEN_FL_EXPENDABLE OPEN_FL_WRITABLE STORE_FL_LOCAL

Exceptions

IOException if there is an I/O error.

ClientStoreFile(ClientStore store, String stgfilename, int flags)

Creates a ClientStoreFile object from the file name, the ClientStore object that the file is located in, and any specified file flags.

Syntax

public ClientStoreFile(ClientStore store, String stgfilename, int flags) throws IOException;

Return Value

Returns the ClientStoreFile object representing the file that is located in the client store.

Parameters

store | The client store that contains the specified file.
stgfilename | The name of the file.
flags | The flags that can be used with any of the file operations in this class. They can be any combination of the following: OPEN_FL_SHARED STORE_FL_ROAMING OPEN_FL_APPEND OPEN_FL_EXPENDABLE OPEN_FL_WRITABLE STORE_FL_LOCAL

Exceptions

IOException if there is an I/O error.


Methods (ClientStoreFile Class)

 Microsoft SDK for Java

ClientStoreFile Class Methods

The ClientStoreFile Class contains the following methods:

canRead determines whether the application can read from the specified file.
canWrite determines whether the application can write to this file.
delete deletes the file specified by the ClientStoreFile object.
equals determines whether this ClientStoreFile instance is equal to another object.
exists determines whether this ClientStoreFile object exists.
getAbsolutePath retrieves the absolute path of the file represented by this object.
getCanonicalPath retrieves the canonical form of this ClientStoreFile object's path.
isAbsolute determines whether the file represented by this ClientStoreFile object is an absolute path.
isDirectory determines whether the file represented by this ClientStoreFile object is a directory.
isFile determines whether the file represented by this ClientStoreFile object is a "normal" file.
lastModified retrieves the time that the file represented by this ClientStoreFile object was last modified.
length retrieves the length of the file represented by this ClientStoreFile object.
list returns a list of the files in the directory specified by the ClientStoreFile object.
mkdir creates a directory whose path is specified by the ClientStoreFile object.
mkdirs creates a directory whose path is specified by the ClientStoreFile object, including any necessary parent directories.
openInputStream opens an input stream to the file.
openOutputStream opens an output stream to the file.
openRandom opens a RandomAccessFile from the store for read operations, with no specified flags.
renameTo renames the file specified by this ClientStoreFile object to have the path given by the File argument.


canRead (ClientStoreFile Class)

 Microsoft SDK for Java

canRead

This method of the ClientStoreFile Class determines whether the application can read from the specified file.

Syntax

public boolean canRead();

Return Value

Returns true if the file specified by this object exists and the application can read the file; otherwise, returns false.


canWrite (ClientStoreFile Class)

 Microsoft SDK for Java

canWrite

This method of the ClientStoreFile Class determines whether the application can write to this file.

Syntax

public boolean canWrite();

Return Value

Returns true if the application is allowed to write to the file whose name is specified by this object; otherwise, returns false.


delete (ClientStoreFile Class)

 Microsoft SDK for Java

delete

This method of the ClientStoreFile Class deletes the file specified by the ClientStoreFile object.

Syntax

public boolean delete();

Return Value

Returns true if the file is successfully deleted; otherwise, returns false.


equals (ClientStoreFile Class)

 Microsoft SDK for Java

equals

This method of the ClientStoreFile Class determines whether this ClientStoreFile instance is equal to another object.

Syntax

public boolean equals(Object obj);

Return Value

Returns false if obj is not an instance of ClientStoreFile or if the file specified by this instance is not identical to the object specified by obj; otherwise, returns true.

Parameters

obj The object that the ClientStoreFile instance is being compared with.


exists (ClientStoreFile Class)

 Microsoft SDK for Java

exists

This method of the ClientStoreFile Class determines whether this ClientStoreFile object exists.

Syntax

public boolean exists();

Return Value

Returns true if the file specified by this object exists; otherwise, returns false.


getAbsolutePath (ClientStoreFile Class)

 Microsoft SDK for Java

getAbsolutePath

This method of the ClientStoreFile Class retrieves the absolute path of the file represented by this object.

Syntax

public String getAbsolutePath();

Return Value

Returns an absolute path for this ClientStoreFile object.

Remarks

If the ClientStoreFile object represents an absolute path, this method returns the path. Otherwise, it returns a path that is a concatenation of the current storage directory, the separator character, and the path of this file object.


getCanonicalPath (ClientStoreFile Class)

 Microsoft SDK for Java

getCanonicalPath

This method of the ClientStoreFile Class retrieves the canonical form of this ClientStoreFile object's path. The precise definition of the canonical form is system-dependent, but it usually specifies an absolute path in which all relative references and references to the current user directory have been completely resolved. The canonical form of a path of a nonexistent file cannot be defined.

Syntax

public String getCanonicalPath() throws IOException;

Return Value

Returns the canonical form of the object's path.

Exceptions

IOException if an I/O error occurs. Errors are possible because the construction of the canonical path might require file system queries.


isAbsolute (ClientStoreFile Class)

 Microsoft SDK for Java

isAbsolute

This method of the ClientStoreFile Class determines whether the file represented by this ClientStoreFile object is an absolute path.

Syntax

public boolean isAbsolute();

Return Value

Returns true if the path indicated by the ClientStoreFile object is an absolute path; otherwise, returns false.

Remarks

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 Microsoft® 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. This method uses the java.io.File.separator field to retrieve the separator for the file system.


isDirectory (ClientStoreFile Class)

 Microsoft SDK for Java

isDirectory

This method of the ClientStoreFile Class determines whether the file represented by this ClientStoreFile object is a directory.

Syntax

public boolean isDirectory();

Return Value

Returns true if this ClientStoreFile object exists and is a directory; otherwise, returns false.


isFile (ClientStoreFile Class)

 Microsoft SDK for Java

isFile

This method of the ClientStoreFile Class determines whether the file represented by this ClientStoreFile 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.

Syntax

public boolean isFile();

Return Value

Returns true if the file specified by this object exists and is a normal file; otherwise, returns false.


lastModified (ClientStoreFile Class)

 Microsoft SDK for Java

lastModified

This method of the ClientStoreFile Class retrieves the time that the file represented by this ClientStoreFile object was last modified.

Syntax

public long lastModified();

CAUTION The return value is system dependent and should only be used to compare with other values returned by lastModified. It should not be interpreted as an absolute time.

Return Value

Returns the time the file specified by this object was last modified, or 0L if the specified file does not exist.


length (ClientStoreFile Class)

 Microsoft SDK for Java

length

This method of the ClientStoreFile Class retrieves the length of the file represented by this ClientStoreFile object.

Syntax

public long length();

Return Value

Returns the length, in bytes, of the file specified by this object, or 0L if the specified file does not exist.


list (ClientStoreFile Class)

 Microsoft SDK for Java

list

The list method of the ClientStoreFile Class contains the following signatures:

list()
list(FilenameFilter filter)

list()

Returns a list of the files in the directory specified by the ClientStoreFile object.

Syntax

public String[] list();

Return Value

Returns an array that contains the names of files in the specified directory. This list does not include the current directory or the parent directory ("." and ".." on Unix systems).

list(FilenameFilter filter)

Retrieves a list of files that satisfy the specified filter and are located in the directory specified by the ClientStoreFile object. The filter parameter, which is an instance of a class that implements the java.io.FilenameFilter interface, indicates the properties that the file must have to be included in the returned list of files.

Syntax

public String[] list(FilenameFilter filter);

Return Value

Returns an array that contains the names of files in the specified directory. This list does not include the current directory or the parent directory ("." and ".." on Unix systems).

Parameters

filter A file name filter.


mkdir (ClientStoreFile Class)

 Microsoft SDK for Java

mkdir

This method of the ClientStoreFile Class creates a directory whose path is specified by the ClientStoreFile object.

Syntax

public boolean mkdir();

Return Value

Returns true if the directory could be created; otherwise, returns false.


mkdirs (ClientStoreFile Class)

 Microsoft SDK for Java

mkdirs

This method of the ClientStoreFile Class creates a directory whose path is specified by the ClientStoreFile object, including any necessary parent directories.

Syntax

public boolean mkdirs();

Return Value

Returns true if the directory (or directories) could be created; otherwise, returns false.


openInputStream (ClientStoreFile Class)

 Microsoft SDK for Java

openInputStream

This method of the ClientStoreFile Class opens an input stream to the file.

Syntax

public InputStream openInputStream() throws IOException;

Return Value

Returns the InputStream that is open for reading.

Exceptions

IOException if the file could not be created or truncated.


openOutputStream (ClientStoreFile Class)

 Microsoft SDK for Java

openOutputStream

This openOutputStream method of the ClientStoreFile Class contains the following signatures:

openOutputStream()
openOutputStream(boolean append)

openOutputStream()

Opens an output stream to the file.

Syntax

public OutputStream openOutputStream() throws IOException;

Return Value

Returns the OutputStream that is open for writing.

Exceptions

IOException if the file could not be created or truncated.

openOutputStream(boolean append)

Opens an output stream to the file, optionally appending to an existing file.

Syntax

public OutputStream openOutputStream(boolean append) throws IOException;

Return Value

Returns the output stream that is open for writing.

Parameters

append The value that determines whether to append to an existing file. If true, this method appends to an existing file; otherwise, it truncates an existing file.

Exceptions

IOException if the file could not be created or truncated.


openRandom (ClientStoreFile Class)

 Microsoft SDK for Java

openRandom

The openRandom method of the ClientStoreFile Class contains the following signatures:

openRandom()
openRandom(boolean writable)

openRandom()

Opens a RandomAccessFile from the store for read operations, with no specified flags.

Syntax

public RandomAccessFile openRandom() throws IOException;

Return Value

Returns the RandomAccessFile that is opened.

Exceptions

IOException if the method fails to open the specified file.

openRandom(boolean writable)

Opens a RandomAccessFile from the store for read or write operations, with no specified flags.

Syntax

public RandomAccessFile openRandom(boolean writable) throws IOException;

Return Value

Returns the RandomAccessFile that is opened.

Parameters

writable Set this value to true if the file should be opened as OPEN_FL_WRITABLE; otherwise, set writable to false.

Exceptions

IOException if the method fails to open the specified file.


renameTo (ClientStoreFile Class)

 Microsoft SDK for Java

renameTo

This method of the ClientStoreFile Class renames the file specified by this ClientStoreFile object to have the path given by the File argument.

Syntax

public boolean renameTo(File dest);

Return Value

Returns true if the renaming succeeds; otherwise, returns false.

Parameters

dest The new file name.


com.ms.lang Package Overview

Microsoft Packages Overview

The com.ms.lang package provides access to Microsoft® Win32® system-level support that is not available through the standard package language. It extends java.lang and supplies Java system enhancement, keyboard switching, and registry manipulation classes.

This package contains the following:

Classes

Hierarchy

The Microsoft® Windows® registry plays a key role in Microsoft® Windows® 98 and Microsoft® Windows NT® operations. It is an access-restricted database that stores many critical application and operating system values. Although many of the common registry functions such as RegCreateKeyEx and RegOpenKeyEx are not implemented, the Java class RegKey handles many of the same operations.


Classes (com.ms.lang Package)

 Microsoft SDK for Java

com.ms.lang Package Classes

The com.ms.lang package contains the following classes:

Delegate class supports delegation.

MulticastDelegate class supports multicast delegates.

MulticastNotSupportedException class indicates that a delegate type does not support multicasting.

RegKey class produces Windows registry access objects.

RegKeyEnumValue class is created and returned by the RegKey.enumValue method.

RegKeyEnumValueByteArray class is created when RegKey.enumValue returns a byte array.

RegKeyEnumValueInt class is created when RegKey.enumValue returns a integer.

RegKeyEnumValueString class is created as a result of returning a string from RegKey.enumValue.

RegKeyException class signals that an I/O exception has occurred.

RegQueryInfo class queries registry access objects.

SystemThread class represents a thread that is always created in the system thread group (the highest level thread group, which has no parent).

SystemX class provides system enhancements that implement extended functionality.


Hierarchy (com.ms.lang Package)

 Microsoft SDK for Java

com.ms.lang Package Hierarchy

The com.ms.lang package has the following Hierarchy:

Object
  |
  +--Delegate(Cloneable)
  |  |
  |  +--MulticastDelegate
  |
  +--RegKey
  |
  +--RegKeyEnumValue
  |  |
  |  +--RegKeyEnumValueByteArray
  |  |
  |  +--RegKeyEnumValueInt
  |  |
  |  +--RegKeyEnumValueString
  |
  +--RegQueryInfo
  |
  +--SystemX

IOException
  |
  +--RegKeyException

RuntimeException
  |
  +--MulticastNotSupportedException

Thread
  |
  +--SystemThread


Delegate Class (com.ms.lang Package)

 Microsoft SDK for Java

Delegate Class

The Delegate Class of the com.ms.lang package supports delegation. With delegation, an outer object acts as a client of an inner object.

Note Instances of this class can be marshalled to IDispatchEx function pointers. For any class derived from Delegate, its DISPID_VALUE is mapped to the delegate's invoke() method. Scripting engines will call Invoke(DISPID_VALUE) with a set of parameters. These parameters are then run through the VM's auto-marshaler, and the invoke() method is called. Microsoft® Internet Explorer, version 4.0 and later, uses IDispatchEx::InvokeEx with the security parameter, so the security of the calling web page is inserted on the stack as is done for normal Automation calls.

public abstract class Delegate implements java.lang.Cloneable
{
  // Constructors
  protected Delegate(Object objTarget, String strMethodName,
    String strMethodSignature);

  // Methods
  public Object clone();
  public static final Delegate combine(Delegate delA, Delegate delB);
  public static final Delegate combine(Delegate[] rgDelegates);
  protected Delegate combine(Delegate delTail)
    throws MulticastNotSupportedException;
  public final Object dynamicInvoke(Object[] args)
    throws IllegalArgumentException, InvocationTargetException;
  public boolean equals(Object objOther);
  public Delegate[] getInvocationList();
  public final Method getMethod();
  public final Object getTarget();
  public int hashCode();
  protected final Object invokeHelper(Object[] args) throws Throwable;
  protected Delegate remove(Delegate delValue);
  public static final Delegate remove(Delegate delSource,
    Delegate delValue);
}


Constructors (Delegate Class)

 Microsoft SDK for Java

Delegate Class Constructors

The Delegate class contains the following constructor:

Delegate(Object objTarget, String strMethodName, String strMethodSignature)

Constructs a delegate that references a given object and a given method of that object. Since Delegate is an abstract class, this constructor is never invoked directly. Instead, subclasses of Delegate should implement a constructor with the same parameters and simply call this inherited constructor. The strMethodName parameter must denote a method in the target object with a signature that is identical to the invoke method of the specific delegate implementation. If this is not the case, a RuntimeException is thrown.

Syntax

protected Delegate(Object objTarget, String strMethodName, String strMethodSignature);

Parameters

objTarget | The target object of the delegate.
strMethodName | The name of the target method of the delegate.
strMethodSignature | The parameter signature of the target method.


Methods (Delegate Class)

 Microsoft SDK for Java

Delegate Class Methods

The Delegate class contains the following methods:

clone creates a copy of this delegate.
combine combines two Delegates to form a single Delegate.
dynamicInvoke invokes the target method referenced by the Delegate on the target object referenced by the delegate with the given parameters.
equals compares two Delegate objects.
getInvocationList returns the invocation list of this Delegate.
getMethod returns the method referenced by this delegate.
getTarget returns the target object referenced by this delegate.
hashCode returns a hash code for this Delegate.
invokeHelper invokes the target method referenced by the delegate on the target object referenced by the delegate with the given parameters.
remove returns a Delegate with an invocation list determined by a value parameter.


clone (Delegate Class)

 Microsoft SDK for Java

clone

This method of the Delegate class creates a copy of this delegate.

Syntax

public Object clone();

Return Value

Returns a copy of this delegate.


combine (Delegate Class)

 Microsoft SDK for Java

combine

This method of the Delegate class contains the following signatures.

combine(Delegate delA, Delegate delB)
combine(Delegate[] rgDelegates)
combine(Delegate delTail)

combine(Delegate delA, Delegate delB)

This method of the Delegate class combines two Delegates to form a single Delegate. If both a and b are null, the result is null. If either a or b is null, the result is the non-null Delegate. If neither a nor b is null, the result is a new Delegate with an invocation list formed by concatenating the invocation lists of a and b, in that order. It is not considered an error for the invocation list to contain duplicate entries, that is, entries that refer to the same method on the same object. If neither a nor b is null, but a and b are of different actual types, an IllegalArgumentException is thrown. If neither a nor b is null, and a and b are of the same actual type, but that type doesn't derive from MulticastDelegate, a MulticastNotSupportedException exception is thrown.

Syntax

public static final Delegate combine(Delegate delA, Delegate delB);

Parameters

delA | One of the two Delegates.
delB | One of the two Delegates.

combine(Delegate[] rgDelegates)

This method of the Delegate class combines the Delegates given by the Delegates array parameter to form a single Delegate with an invocation list consisting of the concatenation of the invocation lists of each of the Delegates in the array in order. The Delegates in the array must all be of the same actual type. The array can contain null entries, which are ignored. If the array parameter is null or empty, or if the resulting invocation list is empty, the result is null. If the Delegates in the array are not all the same actual type, an IllegalArgumentException is thrown. If the Delegates in the array are of a type that doesn't derive from MulticastDelegate, and if the resulting invocation list would have more than one entry, a MulticastNotSupportedException exception is thrown.

Syntax

public static final Delegate combine(Delegate[] rgDelegates);

Parameters

rgDelegates A Delegate array.

combine(Delegate delTail)

This method of the Delegate class combines this Delegate with the given Delegate. This method is overridden in the MulticastDelegate class to support multicasting.

Syntax

protected Delegate combine(Delegate delTail) throws MulticastNotSupportedException;

Parameters

delTail A given Delegate.


dynamicInvoke (Delegate Class)

 Microsoft SDK for Java

dynamicInvoke

This method of the Delegate class invokes the target method referenced by the Delegate on the target object referenced by the delegate with the given parameters. The parameters must be packaged as an Object array according to the rules of Java Reflection.

Syntax

public final Object dynamicInvoke(Object[] args) throws IllegalArgumentException, InvocationTargetException;

Parameters

args Invocation of the target method.

Return Value

Returns null if the delegate type is void. For other delegate types, returns an Object that must be unwrapped or typecast to produce a correctly typed value.


equals (Delegate Class)

 Microsoft SDK for Java

equals

This method of the Delegate class compares two Delegate objects.

Syntax

public boolean equals(Object objOther);

Parameters

objOther The Delegate object to compare.

Return Value

Returns true if and only if the argument is not null and is a Delegate object that has the same target and method as this Delegate object.


getInvocationList (Delegate Class)

 Microsoft SDK for Java

getInvocationList

This method of the Delegate class returns the invocation list of this Delegate. The invocation list of each of the elements in the returned array is guaranteed to have only one entry.

Syntax

public Delegate[] getInvocationList();

Return Value

For unicast Delegates, returns an array with a single element. For multicast Delegates, might return an array with more than one element.


getMethod (Delegate Class)

 Microsoft SDK for Java

getMethod

This method of the Delegate class returns the method referenced by this delegate.

Syntax

public final Method getMethod();


getTarget (Delegate Class)

 Microsoft SDK for Java

getTarget

This method of the Delegate class returns the target object referenced by this delegate. The returned value is null if the delegate references a static method.

Syntax

public final Object getTarget();

Return Value

Returns the target object, or null if the object is a static method.


hashCode (Delegate Class)

 Microsoft SDK for Java

hashCode

This method of the Delegate class returns a hash code for this Delegate. If two Delegates compare equals according to Delegate.equals, they will have the same hash code.

Syntax

public int hashCode();

Return Value

Returns a hash code for this Delegate.


invokeHelper (Delegate Class)

 Microsoft SDK for Java

invokeHelper

This method of the Delegate class invokes the delegate's target method on the delegate's target object with the given parameters. The parameters must be packaged as an Object array according to the rules of Java Reflection.

Syntax

protected final Object invokeHelper(Object[] args) throws Throwable;

Parameters

args The target method invocation.

Return Value

Returns an object that must be unwrapped or typecast to produce a correctly typed value. If the delegate type is void, this method returns null.


remove (Delegate Class)

 Microsoft SDK for Java

remove

This method of the Delegate class contains the following signatures.

remove(Delegate delValue)
remove(Delegate delSource, Delegate delValue)

remove(Delegate delValue)

This method of the Delegate class returns a Delegate with an invocation list formed by removing the last occurrence (if any) of the Delegate given by the value parameter from the invocation list of this Delegate. This method is overridden in the MulticastDelegate class to support multicasting.

Syntax

protected Delegate remove(Delegate delValue);

Parameters

delValue The Delegate value.

remove(Delegate delSource, Delegate delValue)

This method of the Delegate class returns a Delegate with an invocation list formed by removing the last occurrence (if any) of the Delegate given by the value parameter from the invocation list of the Delegate given by the source parameter. The Delegate removed from the invocation list is the last Delegate that refers to the same method on the same object as the value parameter. If the value parameter is null, or if the Delegate given by the value parameter does not appear on the invocation list of the source, the result is the source parameter. If the resulting invocation list is empty, the result is null. If the source parameter is null, the result is null.

Syntax

public static final Delegate remove(Delegate delSource, Delegate delValue);

Parameters

delSource | Delegate source.
delValue | Delegate value.


MulticastDelegate Class (com.ms.lang Package)

 Microsoft SDK for Java

MulticastDelegate Class

The MulticastDelegate class of the com.ms.lang package supports multicast Delegates.

public abstract class MulticastDelegate extends Delegate
{
  // Constructors
  protected MulticastDelegate(Object objTarget, String strMethodName, String strMethodSignature);

  // Methods
  protected Delegate combine(Delegate delTail);
  protected Delegate remove(Delegate delValue);
  public Delegate[] getInvocationList();
  public boolean equals(Object objOther);
  public int hashCode();
  protected final void invokeHelperMulticast(Object[] args)
    throws Throwable;
}


Constructors (MulticastDelegate Class)

 Microsoft SDK for Java

MulticastDelegate Class Constructors

The MulticastDelegate class contains the following constructor.

MulticastDelegate(Object objTarget, String strMethodName, String strMethodSignature)

Constructs a multicast delegate that references a given object and a given method of that object.

Syntax

protected MulticastDelegate(Object objTarget, String strMethodName, String strMethodSignature);

Parameters

objTarget | The target object of the multicast delegate.
strMethodName | The name of the target method of the multicast delegate.
strMethodSignature | The parameter signature of the target method.


Methods (MulticastDelegate Class)

 Microsoft SDK for Java

MulticastDelegate Class Methods

The MulticastDelegate class contains the following methods.

combine combines a MulticastDelegate with a given Delegate.
equals compares two MulticastDelegate objects.
getInvocationList returns the invocation list of this MulticastDelegate.
hashCode returns a hash code for this Delegate.
invokeHelperMulticast invokes the target method referenced by the delegate on the target object referenced by the delegate with the given parameters.
remove returns a MulticastDelegate with an invocation list determined by the source parameter.


combine (MulticastDelegate Class)

 Microsoft SDK for Java

combine

This method of the MulticastDelegate class combines this MulticastDelegate with the given Delegate.

Syntax

protected Delegate combine(Delegate delTail);

Parameters

delTail A given Delegate.


equals (MulticastDelegate Class)

 Microsoft SDK for Java

equals

This method of the MulticastDelegate class compares two Delegate objects.

Syntax

public boolean equals(Object objOther);

Parameters

objOther The Delegate object to compare.

Return Value

The result is true if and only if the argument is not null, the length of the invocation list l1 for the argument is equal to the length of the invocation list l2 for this Delegate, and for all i in (0;l1.length), l1[i] has the same target and method as l2[i].

This method overrides Delegate.equals.


getInvocationList (MulticastDelegate Class)

 Microsoft SDK for Java

getInvocationList

This method of the MulticastDelegate class returns the invocation list of this MulticastDelegate. The resulting array might have more than one element. The invocation list of each of the elements in the returned array is guaranteed to have only one entry.

Syntax

public Delegate[] getInvocationList();

This method overrides Delegate.getInvocationList.


hashCode (MulticastDelegate Class)

 Microsoft SDK for Java

hashCode

This method of the MulticastDelegate class returns a hash code for this Delegate. If two Delegates compare equals according to Delegate.equals, they will have the same hash code.

Syntax

public int hashCode();

This method overrides Delegate.hashCode.


invokeHelperMulticast (MulticastDelegate Class)

 Microsoft SDK for Java

invokeHelperMulticast

This method of the MulticastDelegate class invokes the delegate's target method on the delegate's target object with the given parameters for each delegate in the invocation list. The parameters must be packaged as an Object array according to the rules of Java Reflection.

Syntax

protected final void invokeHelperMulticast(Object[] args) throws Throwable;

Parameters

args The invocation parameters.


remove (MulticastDelegate Class)

 Microsoft SDK for Java

remove

This method of the MulticastDelegate class returns a Delegate with an invocation list. This list is formed by removing the last occurrence (if any) of the delValue parameter's Delegate from the invocation list of this MulticastDelegate.

Syntax

protected Delegate remove(Delegate delValue);

Parameters

delValue Gives the invocation list.

This method overrides Delegate.remove.


MulticastNotSupportedException Class (com.ms.lang Package)

 Microsoft SDK for Java

MulticastNotSupportedException Class

The MulticastNotSupportedException Class of the com.ms.lang package is thrown by Delegate.combine to indicate that a delegate type does not support multicasting. To support multicasting, a delegate type must implement the Multicast interface.

public class MulticastNotSupportedException extends java.lang.RuntimeException
{
  // Constructors
  public MulticastNotSupportedException();
  public MulticastNotSupportedException(String strInfo);
}


Constructors (MulticastNotSupportedException Class)

 Microsoft SDK for Java

MulticastNotSupportedException Class Constructors

The MulticastNotSupportedException class contains the following constructors.

MulticastNotSupportedException()
MulticastNotSupportedException(String strInfo)

MulticastNotSupportedException()

The default constructor.

Syntax

public MulticastNotSupportedException();

MulticastNotSupportedException(String strInfo)

A constructor that takes a string argument.

Syntax

public MulticastNotSupportedException(String strInfo);


RegKey Class (com.ms.lang Package)

 Microsoft SDK for Java

RegKey Class

The RegKey class of the com.ms.lang package produces Windows registry access objects.

public class RegKey
{
  // Fields
  public final static int CLASSES_ROOT;
  public final static int KEYOPEN_ALL;
  public final static int KEYOPEN_CREATE;
  public final static int KEYOPEN_READ;
  public final static int KEYOPEN_WRITE;
  public final static int LOCALMACHINE_ROOT;
  public final static int USER_ROOT;
  public final static int USERS_ROOT;

  // Constructors
  public RegKey(RegKey rkParent, String subKey, int access)
        throws RegKeyException;
  public RegKey(int rootID, String subKey, int access)
        throws RegKeyException;
  public RegKey(int rootID,String subKey) throws RegKeyException;

  // Methods
  public void close();
  public void deleteSubKey(String sub);
  public void deleteValue(String val);
  public String enumKey(int idx);
  public RegKeyEnumValue enumValue(int idx);
  public void finalize();
  public void flush();
  public byte[] getBinaryValue(String name);
  public int getIntValue(String name);
  public int getIntValue(String name, int defval);
  public final static RegKey getRootKey(int id);
  public String getStringValue(String name);
  public String getStringValue(String name,String defval);
  public void loadKey(String subKey, String fileName);
  public RegQueryInfo queryInfo();
  public void replace(String subKey, String newFile,
        String oldFile);
  public void restore( String filename, boolean vol );
  public void setValue(String subKey, String val);
  public void setValue(String subKey, byte val[]);
  public void setValue(String subKey, int val);
  public String toString();
  public void unload(String subKey);
  public RegKeyValueEnumerator values();
}


Constructors (RegKey Class)

 Microsoft SDK for Java

RegKey Class Constructors

The RegKey class contains the following constructors.

RegKey(RegKey rkParent, String subKey, int access)
RegKey(int rootID, String subKey, int access)
RegKey(int rootID,String subKey)

RegKey(RegKey rkParent, String subKey, int access)

Creates the specified key. If the key already exists in the Windows registry, the method opens it.

Syntax

public RegKey(RegKey rkParent, String subKey, int access) throws RegKeyException;

Parameters

rkParent The currently open key or any of the following predefined reserved identifiers:
  • null

  • HKEY_CLASSES_ROOT,

  • HKEY_CURRENT_USER,

  • HKEY_LOCAL_MACHINE

  • HKEY_USERS

The key created is a subkey of the key identified by the rkParent parameter. If the applet is running in a browser or another protected environment, this parameter must be null.

subKey | The string specifying the name of a subkey that this method opens or creates. must be a subkey of the key identified by the rkParent parameter. This subkey must not begin with the backslash character (\). The rkParent parameter cannot be null.
access | The read-write access privileges for the key.

Exceptions

com.ms.lang.RegKeyException if the key cannot be created.

RegKey(int rootID, String subKey, int access)

A convenience constructor that performs Regkey.getRootKey automatically.

Syntax

public RegKey(int rootID, String subKey, int access) throws RegKeyException;

Parameters

rootID | The rootID of the key.
subKey | A string specifying the name of a subkey that this method opens or creates. The subkey must not begin with the backslash character (\). The rkParent parameter cannot be null.
access | The read-write access for the key.

RegKey(int rootID,String subKey)

Opens a key for reading.

Syntax

public RegKey(int rootID,String subKey) throws RegKeyException;

Parameters

rootID | The root identifier of the key.
subKey | A string specifying the name of a subkey that this method opens or creates. The subkey must not begin with the backslash character (\). This parameter cannot be null.


Methods (RegKey Class)

 Microsoft SDK for Java

RegKey Class Methods

The RegKey class contains the following methods.

close closes a key when it is no longer needed.
deleteSubKey removes a subkey from the key.
deleteValue deletes a value from the key.
enumKey enumerates a key's subkeys.
enumValue enumerates values of the key.
finalize frees the resources associated with a RegKey object.
flush flushes the key to the registry on disk.
getBinaryValue queries a byte array from the registry.
getIntValue queries an integer value from the registry.
getRootKey retrieves a top-level key.
getStringValue queries a string value from the registry.
loadKey loads a new hive into the registry.
queryInfo retrieves information about the key.
replace replaces the file supporting a key and all its subkeys with another file.
restore restores a subkey from a file.
setValue sets a string value into a subkey.
toString returns a string representation of the key.
unload unloads a hive from the registry.
values returns an enumeration of the subkey values of this registry key.


close (RegKey Class)

 Microsoft SDK for Java

close

This method of the RegKey class closes a key when it is no longer needed.

Syntax

public void close();

Remarks

As the system registry keys must be written out to disk, the keys must be closed when no longer needed. After this, the keys must not be used again.


deleteSubKey (RegKey Class)

 Microsoft SDK for Java

deleteSubKey

This method of the RegKey class removes a subkey from the key.

Syntax

public void deleteSubKey(String sub);

Parameters

sub The subkey removed from the key.

Exceptions

IOException if the subkey removal is unsuccessful.


deleteValue (RegKey Class)

 Microsoft SDK for Java

deleteValue

This method of the RegKey class deletes a value from the key.

Syntax

public void deleteValue(String val);

Parameters

val The name of the value that is deleted.


enumKey (RegKey Class)

 Microsoft SDK for Java

enumKey

This method of the RegKey class enumerates a key's subkeys.

Syntax

public String enumKey(int idx);

Return Value

Returns the enumeration value of the subkey by index (see RegKeyEnumValue).

Parameters

idx The enumeration index.


enumValue (RegKey Class)

 Microsoft SDK for Java

enumValue

This method of the RegKey class enumerates values of the key.

Syntax

public RegKeyEnumValue enumValue(int idx);

Return Value

Returns the subkey name of the subkey.

Parameters

idx The enumeration index.


finalize (RegKey Class)

 Microsoft SDK for Java

finalize

This method of the RegKey class frees the resources associated with a RegKey object.

Syntax

public void finalize();


flush (RegKey Class)

 Microsoft SDK for Java

flush

This method of the RegKey class flushes the key to the registry on disk.

Syntax

public void flush();


getBinaryValue (RegKey Class)

 Microsoft SDK for Java

getBinaryValue

This method of the RegKey class queries a byte array from the registry.

Syntax

public byte[] getBinaryValue(String name);

Return Value

Returns the byte array contained in the subKey.

Parameters

name The subKey containing the value requested. The name must be a subkey of the current key.


getIntValue (RegKey Class)

 Microsoft SDK for Java

getIntValue

The getIntValue method of the RegKey class contains the following signatures.

getIntValue(String name)
getIntValue(String name, int defval)

getIntValue(String name)

Queries an integer value from the registry.

Syntax

public int getIntValue(String name);

Return Value

Returns the integer value contained in the subKey.

Parameters

name The subKey containing the value wanted. The name must be a subkey of the current key.

getIntValue(String name, int defval)

Queries an integer value from the registry. The name is a subkey of the current key. If the named value does not exist in the registry, the default value is returned.

Syntax

public int getIntValue(String name, int defval);

Return Value

Returns the integer value contained in the subKey or the default value if the named value does not exist in the registry.

Parameters

name | The subkey containing the value wanted.
defval | The default value.


getRootKey (RegKey Class)

 Microsoft SDK for Java

getRootKey

This method of the RegKey class retrieves a top-level key.

Syntax

public final static RegKey getRootKey(int id);

Parameters

id The identifier of the top-level key.


getStringValue (RegKey Class)

 Microsoft SDK for Java

getStringValue

The getStringValue method of the RegKey class contains the following signatures.

getStringValue(String name)
getStringValue(String name,String defval)

getStringValue(String name)

Queries a string value from the registry. The name is a subkey of the current key.

Syntax

public String getStringValue(String name);

Return Value

Returns the String value contained in the subKey.

Parameters

name The subKey containing the requested value.

getStringValue(String name,String defval)

Queries a string value from the registry. The name is a subkey of the current key. If the named value does not exist in the registry, the specified default value is returned.

Syntax

public String getStringValue(String name,String defval);

Return Value

Returns the default value if the named value does not exist in the registry. Otherwise, the method returns the string value contained in the subkey.

Parameters

name | The subkey containing the requested string.
defval | The default value to return.


loadKey (RegKey Class)

 Microsoft SDK for Java

loadKey

This method of the RegKey class loads a new hive into the registry.

Syntax

public void loadKey(String subKey, String fileName);

Parameters

subKey | The name of the subkey created to contain the new hive.
fileName | The name of a file that contains the registry information.


queryInfo (RegKey Class)

 Microsoft SDK for Java

queryInfo

This method of the RegKey class retrieves information about the key.

Syntax

public RegQueryInfo queryInfo();

Return Value

Returns a RegQueryInfo object containing the information.


replace (RegKey Class)

 Microsoft SDK for Java

replace

This method of the RegKey class replaces the file supporting a key and all its subkeys with another file. The next time the system is started, the key and subkey values are stored in the new file.

Syntax

public void replace(String subKey, String newFile, String oldFile);

Parameters

subKey | The subkey, whose values are stored in the new file.
newFile | The name of the new file.
oldFile | The name of the old file.


restore (RegKey Class)

 Microsoft SDK for Java

restore

This method of the RegKey class restores a subkey from a file.

Syntax

public void restore( String filename, boolean vol );

Parameters

filename | The filename.
vol | The value returned is true if the hive is volatile; otherwise, the value is false.


setValue (RegKey Class)

 Microsoft SDK for Java

setValue

The setValue method of the RegKey class contains the following signatures.

setValue(String subKey, String val)
setValue(String subKey, byte val[])
setValue(String subKey, int val)

setValue(String subKey, String val)

Sets a string value into a subkey.

Syntax

public void setValue(String subKey, String val);

Parameters

subKey | The subkey that holds the value.
val | The string that is written out.

setValue(String subKey, byte val[])

Sets a byte array into a subkey.

Syntax

public void setValue(String subKey, byte val[]);

Parameters

subKey | The subkey that holds the value.
val | The array that is written out.

setValue(String subKey, int val)

Sets an integer value into a subkey.

Syntax

public void setValue(String subKey, int val);

Parameters

subKey | The subkey that holds the value.
val | The integer that is written out.


toString (RegKey Class)

 Microsoft SDK for Java

toString

This method of the RegKey class returns a string representation of the key.

Syntax

public String toString();

Return Value

Returns a string containing the path information in the form: "[RegKey: <path>]".


unload (RegKey Class)

 Microsoft SDK for Java

unload

This method of the RegKey class unloads a hive from the registry.

Syntax

public void unload(String subKey);

Parameters

subKey The subkey that is unloaded.


values (RegKey Class)

 Microsoft SDK for Java

values

This method of the RegKey class returns an enumeration of the subkey values of this registry key.

Syntax

public RegKeyValueEnumerator values();

Return Value

Returns a RegKeyValueEnumerator object, used to enumerate the list of subkeys.


Fields (RegKey Class)

 Microsoft SDK for Java

RegKey Class Fields

The RegKey class contains the following fields.

CLASSES_ROOT | An identifier that signifies that the HKEY_CLASSES_ROOT key must be returned.
KEYOPEN_ALL | An identifier that signifies a key must be opened for read-write access.
KEYOPEN_CREATE | An identifier that signifies a key must be created, not opened.
KEYOPEN_READ | An identifier that signifies a key must be opened for read-only access.
KEYOPEN_WRITE | An identifier that signifies a key must be opened for write access.
LOCALMACHINE_ROOT | An identifier that signifies that the HKEY_LOCAL_MACHINE key must be returned.
USER_ROOT | An identifier that signifies that the HKEY_CURRENT_USER key must be returned.
USERS_ROOT | An identifier that signifies that the HKEY_USERS key must be returned.


RegKeyEnumValue Class (com.ms.lang Package)

 Microsoft SDK for Java

RegKeyEnumValue Class

The RegKeyEnumValue Class of the com.ms.lang package is created and returned by the RegKey.enumValue method.

public abstract class RegKeyEnumValue
{
  // Fields
  public String name;
  public final int REGTYPE_BINARY;
  public final int REGTYPE_DWORD;
  public final int REGTYPE_DWORD_BIG_ENDIAN;
  public final int REGTYPE_DWORD_LITTLE_ENDIAN;
  public final int REGTYPE_EXPAND_SZ;
  public final int REGTYPE_LINK;
  public final int REGTYPE_MULTI_SZ;
  public final int REGTYPE_NONE;
  public final int REGTYPE_RESOURCE_LIST;
  public final int REGTYPE_SZ;
  public int theType;
  public static final int TYPE_BINARY;
  public static final int TYPE_DWORD;
  public static final int TYPE_EXPAND_STRING;
  public static final int TYPE_NONE;
  public static final int TYPE_STRING;

  // Methods
  public String getName();
  public int getType();
  public boolean isBinary();
  public boolean isDword();
  public boolean isString();
}


Methods (RegKeyEnumValue Class)

 Microsoft SDK for Java

RegKeyEnumValue Class Methods

The RegKeyEnumValue class contains the following methods.

getName retrieves the registry name.
getType retrieves the registry type.
isBinary determines if the registry value is binary.
isDword determines if the registry value is a double word value.
isString determines if the registry value is a string.


getName (RegKeyEnumValue Class)

 Microsoft SDK for Java

getName

This method of the RegKeyEnumValue class retrieves the registry name.

Syntax

public String getName();

Return Value

Returns the registry value name.


getType (RegKeyEnumValue Class)

 Microsoft SDK for Java

getType

This method of the RegKeyEnumValue class retrieves the registry type.

Syntax

public int getType();

Return Value

Returns the registry value type.


isBinary (RegKeyEnumValue Class)

 Microsoft SDK for Java

isBinary

This method of the RegKeyEnumValue class determines if the registry value is binary.

Syntax

public boolean isBinary();

Return Value

Returns true if the registry value is binary, in which case the object is the RegKeyEnumValueByteArray type; otherwise, returns false.

See Also

RegKeyEnumValueByteArray


isDword (RegKeyEnumValue Class)

 Microsoft SDK for Java

isDword

This method of the RegKeyEnumValue class determines if the registry value is a double word value.

Syntax

public boolean isDword();

Return Value

Returns true if the registry value is a double word value, in which case the object is the RegKeyEnumValueInt type; otherwise, returns false.

See Also

RegKeyEnumValueInt


isString (RegKeyEnumValue Class)

 Microsoft SDK for Java

isString

This method of the RegKeyEnumValue class determines if the registry value is a string.

Syntax

public boolean isString();

Return Value

Returns true if the registry value is a string, in which case the object is the RegKeyEnumValueString type; otherwise, returns false.

See Also

RegKeyEnumValueString


Fields (RegKeyEnumValue Class)

 Microsoft SDK for Java

RegKeyEnumValue Class Fields

The RegKeyEnumValue class contains the following fields.

name | The registry name.
REGTYPE_BINARY | Indicates that the registry type is a binary value.
REGTYPE_DWORD | Indicates that the registry type is a double word value.
REGTYPE_DWORD_BIG_ENDIAN | Indicates that the registry type is a 32-bit number in big endian format.
REGTYPE_DWORD_LITTLE_ENDIAN | Indicates that the registry type is a 32-bit number in little endian format.
REGTYPE_EXPAND_SZ | Indicates that the registry type is a string that contains unexpanded references to environment variables (for example "%PATH%").
REGTYPE_LINK | Indicates that the registry type is a link.
REGTYPE_MULTI_SZ | Indicates that the registry type is an array of null-terminated strings, terminated by two null characters.
REGTYPE_NONE | Indicates no defined value type.
REGTYPE_RESOURCE_LIST | Indicates that the registry type is a device-driver resource list.
REGTYPE_SZ | Indicates that the registry type is a string.
theType | The registry type.
TYPE_BINARY | Static alias for REGTYPE_BINARY.
TYPE_DWORD | Static alias for REGTYPE_DWORD.
TYPE_EXPAND_STRING | Static alias for REGTYPE_EXPAND_SZ.
TYPE_NONE | Static alias for REGTYPE_NONE.
TYPE_STRING | Static alias for REGTYPE_SZ.


RegKeyEnumValueByteArray Class (com.ms.lang Package)

 Microsoft SDK for Java

RegKeyEnumValueByteArray Class

The RegKeyEnumValueByteArray Class of the com.ms.lang package is created when RegKey.enumValue returns a byte array.

public class RegKeyEnumValueByteArray extends RegKeyEnumValue
{
  // Fields
  public byte value[]

  // Methods
  public byte[] getValue();
  public String toString();
}

Hierarchy

RegKeyEnumValue
  |
  +--RegKeyEnumValueByteArray


Methods (RegKeyEnumValueByteArray Class)

 Microsoft SDK for Java

RegKeyEnumValueByteArray Class Methods

The RegKeyEnumValueByteArray class contains the following methods.

getValue retrieves the binary contents of the registry value.
toString retrieves a string representation of the object.


getValue (RegKeyEnumValueByteArray Class)

 Microsoft SDK for Java

getValue

This method of the RegKeyEnumValueByteArray class retrieves the binary contents of the registry value.

Syntax

public byte[] getValue();

Return Value

Returns the byte array.


toString (RegKeyEnumValueByteArray Class)

 Microsoft SDK for Java

toString

This method of the RegKeyEnumValueByteArray class retrieves a string representation of the object.

Syntax

public String toString();

Return Value

Returns a string with the form, "com.ms.lang.RegKeyEnumValueByteArray: name = value (type = type)"


Fields (RegKeyEnumValueByteArray Class)

 Microsoft SDK for Java

RegKeyEnumValueByteArray Class Fields

The RegKeyEnumValueByteArray class contains the following field.

value[] The byte array value.


RegKeyEnumValueInt Class (com.ms.lang Package)

 Microsoft SDK for Java

RegKeyEnumValueInt Class

The RegKeyEnumValueInt Class of the com.ms.lang package is created when RegKey.enumValue returns an integer.

public class RegKeyEnumValueInt extends RegKeyEnumValue
{
  // Fields
  public int value;

  // Methods
  public int getValue();
  public String toString();
}

Hierarchy

RegKeyEnumValue
  |
  +--RegKeyEnumValueInt


Methods (RegKeyEnumValueInt Class)

 Microsoft SDK for Java

RegKeyEnumValueInt Class Methods

The RegKeyEnumValueInt class contains the following methods.

getValue retrieves the double-word contents of the registry value.
toString retrieves a string representation of the object.


getValue (RegKeyEnumValueInt Class)

 Microsoft SDK for Java

getValue

This method of the RegKeyEnumValueInt class retrieves the double-word contents of the registry value.

Syntax

public int getValue();

Return Value

Returns the registry value.


toString (RegKeyEnumValueInt Class)

 Microsoft SDK for Java

toString

This method of the RegKeyEnumValueInt class retrieves a string representation of the object.

Syntax

public String toString();

Return Value

Returns a string of the form, "com.ms.lang.RegKeyEnumValueInt: name = value (type = type)"


Fields (RegKeyEnumValueInt Class)

 Microsoft SDK for Java

RegKeyEnumValueInt Class Fields

The RegKeyEnumValueInt class contains the following field.

value The integer value.


RegKeyEnumValueString Class (com.ms.lang Package)

 Microsoft SDK for Java

RegKeyEnumValueString Class

The RegKeyEnumValueString Class of the com.ms.lang package is created as a result of returning a string from RegKey.enumValue.

public class RegKeyEnumValueString extends RegKeyEnumValue
{
  // Fields
  public String value;

  // Methods
  public String getValue();
  public String toString();
}

Hierarchy

RegKeyEnumValue
  |
  +--RegKeyEnumValueString


Methods (RegKeyEnumValueString Class)

 Microsoft SDK for Java

RegKeyEnumValueString Class Methods

The RegKeyEnumValueString class contains the following methods.

getValue retrieves the string contents of this registry value.
toString retrieves a string representation of the object.


getValue (RegKeyEnumValueString Class)

 Microsoft SDK for Java

getValue

This method of the RegKeyEnumValueString class retrieves the string contents of this registry value.

Syntax

public String getValue();

Return Value

Returns the registry value.


toString (RegKeyEnumValueString Class)

 Microsoft SDK for Java

toString

This method of the RegKeyEnumValueString class retrieves a string representation of the object.

Syntax

public String toString();

Return Value

Returns a string of the form, "com.ms.lang.RegKeyEnumValueString: name = value (type = type)"


Fields (RegKeyEnumValueString Class)

 Microsoft SDK for Java

RegKeyEnumValueString Class Fields

The RegKeyEnumValueString class contains the following field.

value The string value.


RegKeyException Class (com.ms.lang Package)

 Microsoft SDK for Java

RegKeyException Class

The RegKeyException Class of the com.ms.lang package signals that an I/O exception has occurred.

public class RegKeyException extends IOException
{
  // Constructors
  public RegKeyException();
  public RegKeyException(String s);
}

Hierarchy

IOException
  |
  +--RegKeyException


Constructors (RegKeyException Class)

 Microsoft SDK for Java

RegKeyException Class Constructors

The RegKeyException Class contains the following constructors.

RegKeyException()
RegKeyException(String s)

RegKeyException()

Constructs a RegKeyException with no detail message.

Syntax

public RegKeyException();

RegKeyException(String s)

Constructs a RegKeyException object with a detail message.

Syntax

public RegKeyException(String s);

Parameters

s The detail message, which is a string that describes the specified exception.


RegQueryInfo Class (com.ms.lang Package)

 Microsoft SDK for Java

RegQueryInfo Class

The RegQueryInfo Class of the com.ms.lang package queries registry access objects.

public class RegQueryInfo
{
  // Fields
  public Date lastWriteTime;
  public int maxClassLen;
  public int maxSubKeyLen;
  public int maxValueLen;
  public int maxValueNameLen;
  public int securityDescriptor;
  public int subKeys;
  public String theClass;
  public int values;
}


Fields (RegQueryInfo Class)

 Microsoft SDK for Java

RegQueryInfo Class Fields

The RegQueryInfo Class contains the following fields.

lastWriteTime | The most recent write time. If you are querying the registry on a computer running Windows NT, this method returns the last time that the key or any of its value entries was modified. If you are querying the registry on a computer running Microsoft® Windows® 98, this method returns null. This is because the Windows 98 operating system does not keep track of registry key last write time information.
maxClassLen | The length, in characters, of the longest string specifying a subkey class.
maxSubKeyLen | The length, in characters, of the key's subkey with the longest name.
maxValueLen | The length, in bytes, of the longest data component among the key's values.
maxValueNameLen | The length, in characters, of the key's subkey with the longest name. The count returned does not include the terminating null character.
securityDescriptor | The length, in bytes, of the security descriptor.
subKeys | The number of subkeys contained by the key.
theClass | The String class buffer address.
values | The number of value entries associated with the key.


SystemThread Class (com.ms.lang Package)

 Microsoft SDK for Java

SystemThread Class

The SystemThread class of the com.ms.lang package represents a thread that is always created in the system thread group (the highest level thread group, which has no parent). Untrusted code cannot create threads in the system thread group.

public class SystemThread extends Thread
{
  // Constructors
  public SystemThread();
  public SystemThread(String name);
  public SystemThread(Runnable target);
  public SystemThread(Runnable target,String name);

  // Methods
  public static ThreadGroup getSystemThreadGroup();
}

Hierarchy

Thread
  |
  +--SystemThread

See Also

java.lang.Thread, java.lang.ThreadGroup


Constructors (SystemThread Class)

 Microsoft SDK for Java

SystemThread Class Constructors

The SystemThread class contains the following constructors.

SystemThread()
SystemThread(String name)
SystemThread(Runnable target)
SystemThread(Runnable target,String name)

SystemThread()

Creates a new SystemThread object. This constructor has the same effect as making the following call when group is the system thread group:

Thread(group, null , null)

Syntax

public SystemThread();

See Also

java.lang.ThreadGroup, java.lang.Runnable, java.lang.String

SystemThread(String name)

Creates a new SystemThread object. When group is the system thread group, this constructor has the same effect as making the following call:

Thread(group, null , name)

Syntax

public SystemThread(String name);

Parameters

name The name of the new thread.

See Also

java.lang.ThreadGroup, java.lang.Runnable, java.lang.String

SystemThread(Runnable target)

Creates a new SystemThread object. When group is the system thread group, this constructor has the same effect as making the following call:

Thread(group, target, null)

Syntax

public SystemThread(Runnable target);

Parameters

target The object whose run method is called.

See Also

java.lang.ThreadGroup, java.lang.Runnable, java.lang.String

SystemThread(Runnable target, String name)

Creates a new SystemThread object. When group is the system thread group, this constructor has the same effect as making the following call:

Thread(group, target , name)

Syntax

public SystemThread(Runnable target, String name);

Parameters

target | The object whose run method is called.
name | The name of the new thread.

See Also

java.lang.ThreadGroup, java.lang.Runnable, java.lang.String


Methods (SystemThread Class)

 Microsoft SDK for Java

SystemThread Class Methods

The SystemThread class contains the following method.

getSystemThreadGroup retrieves the system thread group.


getSystemThreadGroup (SystemThread Class)

 Microsoft SDK for Java

getSystemThreadGroup

This method of the SystemThread class retrieves the system thread group.

Syntax

public static ThreadGroup getSystemThreadGroup();

Return Value

Returns the ThreadGroup object of the system thread group.


SystemX Class (com.ms.lang Package)

 Microsoft SDK for Java

SystemX Class

The SystemX class of the com.ms.lang package provides system enhancements that implement extended functionality. The SystemX class cannot be instantiated or subclassed because all the methods and variables are static.

public final class SystemX
{
  // Fields
  public static final int LANG_AFRIKAANS;
  public static final int LANG_ALBANIAN;
  public static final int LANG_ARABIC;
  public static final int LANG_BASQUE;
  public static final int LANG_BULGARIAN;
  public static final int LANG_BYELORUSSIAN;
  public static final int LANG_CATALAN;
  public static final int LANG_CHINESE;
  public static final int LANG_CROATIAN;
  public static final int LANG_CZECH;
  public static final int LANG_DANISH;
  public static final int LANG_DUTCH;
  public static final int LANG_ENGLISH;
  public static final int LANG_ESTONIAN;
  public static final int LANG_FINNISH;
  public static final int LANG_FRENCH;
  public static final int LANG_GERMAN;
  public static final int LANG_GREEK;
  public static final int LANG_HEBREW;
  public static final int LANG_HUNGARIAN;
  public static final int LANG_ICELANDIC;
  public static final int LANG_INDONESIAN;
  public static final int LANG_ITALIAN;
  public static final int LANG_JAPANESE;
  public static final int LANG_KOREAN;
  public static final int LANG_LATVIAN;
  public static final int LANG_LITHUANIAN;
  public static final int LANG_NORWEGIAN;
  public static final int LANG_POLISH;
  public static final int LANG_PORTUGUESE;
  public static final int LANG_ROMANIAN;
  public static final int LANG_RUSSIAN;
  public static final int LANG_SLOVAK;
  public static final int LANG_SLOVENIAN;
  public static final int LANG_SORBIAN;
  public static final int LANG_SPANISH;
  public static final int LANG_SWEDISH;
  public static final int LANG_THAI;
  public static final int LANG_TURKISH;
  public static final int LANG_UKRAINIAN;
  public static final int SUBLANG_CHINESE_HONGKONG;
  public static final int SUBLANG_CHINESE_SIMPLIFIED;
  public static final int SUBLANG_CHINESE_SINGAPORE;
  public static final int SUBLANG_CHINESE_TRADITIONAL;
  public static final int SUBLANG_DUTCH_BELGIAN;
  public static final int SUBLANG_ENGLISH_AUS;
  public static final int SUBLANG_ENGLISH_CAN;
  public static final int SUBLANG_ENGLISH_EIRE;
  public static final int SUBLANG_ENGLISH_NZ;
  public static final int SUBLANG_ENGLISH_UK;
  public static final int SUBLANG_ENGLISH_US;
  public static final int SUBLANG_FRENCH;
  public static final int SUBLANG_FRENCH_BELGIAN;
  public static final int SUBLANG_FRENCH_CANADIAN;
  public static final int SUBLANG_FRENCH_SWISS;
  public static final int SUBLANG_GERMAN;
  public static final int SUBLANG_GERMAN_AUSTRIAN;
  public static final int SUBLANG_GERMAN_SWISS;
  public static final int SUBLANG_ITALIAN;
  public static final int SUBLANG_ITALIAN_SWISS;
  public static final int SUBLANG_NORWEGIAN_BOKMAL;
  public static final int SUBLANG_NORWEGIAN_NYNORSK;
  public static final int SUBLANG_PORTUGUESE;
  public static final int SUBLANG_PORTUGUESE_BRAZILIAN;
  public static final int SUBLANG_SPANISH;
  public static final int SUBLANG_SPANISH_MEXICAN;
  public static final int SUBLANG_SPANISH_MODERN;

  // Methods
  public native static boolean arrayCompare(Object P[], int pStart,
    Object Q[], int qStart, int count);
  public native void blockcopy(Object objSrc, int nSrcOffset,
    Object objDest, int nDestOffset, int cBytes);
  public static native int compareString(int lcid, int flags,
    String string1, String string2);
  public static void exitProcessAfterMainThreadReturns(boolean value);
  public static native void gc();
  public static InputManagerListener getDefaultInputManager();
  public static InputManagerListener getInputManager();
  public static int getKeyboardLanguage();
  public static String getKeyboardLanguageName(int id);
  public static int getKeyboardLanguages(int array[]);
  public static int [] getKeyboardLanguages();
  public static int getNumKeyboardLanguages();
  public native static boolean isLocalCharDBCSLeadByte(byte local);
  public static byte JavaStringToLocalString(char Uni);
  public static byte[] JavaStringToLocalString(char C[]);
  public static byte[] JavaStringToLocalString(char C[], int off,
    int len);
  public static String LocalStringToJavaString(String local);
  public static char[] LocalStringToJavaString(byte B[]);
  public static char[] LocalStringToJavaString(char B[]);
  public static char[] LocalStringToJavaString(byte B[], int off,
    int len);
  public static char[] LocalStringToJavaString(char B[], int off,
    int len);
  public static char LocalStringToJavaString(byte local);
  public static void setInputManager(InputManagerListener imm,
    boolean retainCurrentList);
  public static boolean setKeyboardLanguage(Applet App,
    int idLanguage);
}


Methods (SystemX Class)

 Microsoft SDK for Java

SystemX Class Methods

The SystemX class contains the following methods.

arrayCompare compares two arrays.
blockcopy copies an array from the specified source array, beginning at the specified byte offset, to the specified byte offset of the destination array.
compareString compares two strings using the Win32 CompareString with the supplied locale identifier and flags.
exitProcessAfterMainThreadReturns terminates a process when the thread that is executing main() returns.
gc runs the garbage collector.
getDefaultInputManager finds the default system input manager.
getInputManager retrieves the current input method manager.
getKeyboardLanguage retrieves the currently active keyboard language.
getKeyboardLanguageName retrieves the keyboard language name.
getKeyboardLanguages retrieves a list of the keyboard languages currently active in the system.
getNumKeyboardLanguages finds the number of active keyboard languages in the system.
isLocalCharDBCSLeadByte checks if a local code page character is a lead byte for DBCS systems.
JavaStringToLocalString converts a Java character to a character in the local code page.
LocalStringToJavaString converts a string from a local code page to Unicode.
setInputManager sets a new input method manager.
setKeyboardLanguage sets a new active keyboard language.


arrayCompare (SystemX Class)

 Microsoft SDK for Java

arrayCompare

This method of the SystemX class compares two arrays.

Syntax

public native static boolean arrayCompare(Object P[], int pStart, Object Q[], int qStart, int count);

Return Value

Returns true if the two arrays are equal; otherwise, the method returns false.

Parameters

P | The first array.
pStart | The first element of the first array.
Q | The second array.
qStart | The first element of the second array.
count | The number of elements compared.

Exceptions

nullPointerArray occurs if there are not enough items in the arrays.


blockcopy (SystemX Class)

 Microsoft SDK for Java

blockcopy

This method of the SystemX class copies an array from the specified source array, beginning at the specified byte offset, to the specified byte offset of the destination array.

Syntax

public native static void blockcopy(Object objSrc, int nSrcOffset, Object objDest, int nDestOffset, int cBytes);

Unlike java.lang.System.arraycopy, the source and destination arrays must be of primitive type, although not necessarily of the same primitive type. This method essentially performs a memory copy between arrays, ignoring byte endianness. A subsequence of bytes are copied from the source array, referenced by objSrc, to the destination array, referenced by objDest. The number of bytes copied is equal to the cBytes parameter. The components at byte offsets nSrcOffset through nSrcOffset+cBytes-1 in the source array are copied into destination array starting at byte offset nDestOffset.

If the objSrc and objDest parameters refer to the same array object, the copying is performed as if the bytes at byte offset nSrcOffset through nSrcOffset+cBytes-1 were first copied to a temporary array, and then the contents of the temporary array were copied into the destination array starting at byte offset nDestOffset.

If either of the following statements are true, an ArrayStoreException is thrown and the destination is not modified:

  • The objSrc argument refers to an object that is not an array of primitive type.

  • The objDest argument refers to an object that is not an array of primitive type.

Otherwise, if any of the following statements are true, an ArrayIndexOutOfBoundsException is thrown and the destination is not modified:

  • The nSrcOffset argument is negative.

  • The nDestOffset argument is negative.

  • The cBytes argument is negative.

  • nSrcOffset+cBytes is greater than the number of bytes in objSrc, the source array.

  • nDstOffset+cBytes is greatet than the number of bytes in objDest, the destination array.

Parameters

objSrc | The source array.
nSrcOffset | The start byte offset in the source array.
objDest | The destination array.
nDestOffset | The start byte offset in the destination data.
cBytes | The number of bytes to be copied.

Exceptions

ArrayIndexOutOfBoundsException occurs if copying would cause access of data outside array bounds.

ArrayStoreException occurs if objSrc or objDest is not an array of primitive type.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


compareString (SystemX Class)

 Microsoft SDK for Java

compareString

This method of the SystemX class compares two strings using the Win32 CompareString and the supplied locale identifier and flags. This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.

Syntax

public static native void compareString(int lcid, int flags, String tring1, String string2);

Parameters

lcid | The locale identifier.
flags | Used to compare strings.
string1 | A string to be compared.
string2 | A string to be compared.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


exitProcessAfterMainThreadReturns (SystemX Class)

 Microsoft SDK for Java

exitProcessAfterMainThreadReturns

This method of the SystemX class enables Win32-style process semantics, where once the thread that is executing main() returns, the process is terminated. The calling code must have the permissions to exit the virtual machine.

Syntax

public static void exitProcessAfterMainThreadReturns(boolean value);

Parameters

value A boolean flag that determines whether the process should be terminated.

Remarks

This method was added as of versions 2437 through 2925 of the Microsoft virtual machine.


gc (SystemX Class)

 Microsoft SDK for Java

gc

This method of the SystemX class runs the garbage collector.

Syntax

public static native void gc();

Remarks

Calling the gc method causes the virtual machine to perform garbage collection. When program control returns from the method call, the virtual machine has made a best effort to reclaim space from all unused objects.

See Also

java.lang.Runtime.gc, java.lang.System.gc


getDefaultInputManager (SystemX Class)

 Microsoft SDK for Java

getDefaultInputManager

This method of the SystemX class finds the default system input manager.

Syntax

public static InputManagerListener getDefaultInputManager();

Return Value

Returns the default system input manager.


getInputManager (SystemX Class)

 Microsoft SDK for Java

getInputManager

This method of the SystemX class retrieves the current input method manager.

Syntax

public static InputManagerListener getInputManager();

Return Value

Returns null if an input method manager is not running.


getKeyboardLanguage (SystemX Class)

 Microsoft SDK for Java

getKeyboardLanguage

This method of the SystemX class retrieves the currently active keyboard language.

Syntax

public static int getKeyboardLanguage();

Return Value

Returns the currently active keyboard language.


getKeyboardLanguageName (SystemX Class)

 Microsoft SDK for Java

getKeyboardLanguageName

This method of the SystemX class retrieves the keyboard language name.

Syntax

public static String getKeyboardLanguageName(int id);

Return Value

Returns the name of the language.

Parameters

id Specifies the identifier of the keyboard language.


getKeyboardLanguages (SystemX Class)

 Microsoft SDK for Java

getKeyboardLanguages

The getKeyboardLanguages method of the SystemX class contains the following signatures.

getKeyboardLanguages(int array[])
getKeyboardLanguages()

getKeyboardLanguages(int array[])

Retrieves a list of the keyboard languages currently active in the system.

Syntax

public static int getKeyboardLanguages(int array[]);

Return Value

Returns the number of active languages.

Parameters

array The list of keyboard language identifiers.

getKeyboardLanguages()

Retrieves a list of the keyboard languages currently active in the system.

Syntax

public static int [] getKeyboardLanguages();

Return Value

Returns an array containing the active languages.


getNumKeyboardLanguages (SystemX Class)

 Microsoft SDK for Java

getNumKeyboardLanguages

This method of the SystemX class finds the number of active keyboard languages in the system.

Syntax

public static int getNumKeyboardLanguages();

Return Value

Returns the number of active keyboard languages in the system.


isLocalCharDBCSLeadByte (SystemX Class)

 Microsoft SDK for Java

isLocalCharDBCSLeadByte

This method of the SystemX class checks if a local code page character is a lead byte for DBCS systems.

Syntax

public native static boolean isLocalCharDBCSLeadByte(byte local);

Return Value

Returns true if the local code page is DBCS; otherwise, returns false.

Parameters

local The local code page character.


JavaStringToLocalString (SystemX Class)

 Microsoft SDK for Java

JavaStringToLocalString

The JavaStringToLocalString method of the SystemX class contains the following signatures.

JavaStringToLocalString(char Uni)
JavaStringToLocalString(char C[])
JavaStringToLocalString(char C[], int off, int len)

JavaStringToLocalString(char Uni)

Converts a Java character to a character in the local code page.

Syntax

public static byte JavaStringToLocalString(char Uni);

Return Value

Returns the local code page string.

Parameters

Uni The Java character.

JavaStringToLocalString(char C[])

Converts a character array to a byte array in the local code page.

Syntax

public static byte[] JavaStringToLocalString(char C[]);

Return Value

Returns the local representation of the array.

Parameters

C The Java character array.

JavaStringToLocalString(char C[], int off, int len)

Converts a character array to a byte array in the local code page.

Syntax

public static byte[] JavaStringToLocalString(char C[], int off, int len);

Return Value

Returns the local representation of the array.

Parameters

C | The Java character array.
off | The starting point within the array.
len | The number of characters to convert.

See Also

LocalStringToJavaString


LocalStringToJavaString (SystemX Class)

 Microsoft SDK for Java

LocalStringToJavaString

The LocalStringToJavaString method of the SystemX class contains the following signatures.

LocalStringToJavaString(String local)
LocalStringToJavaString(byte B[])
LocalStringToJavaString(char B[])
LocalStringToJavaString(byte B[], int off, int len)
LocalStringToJavaString(char B[], int off, int len)
LocalStringToJavaString(byte local)

LocalStringToJavaString(String local)

Converts a string from a local code page to Unicode.

Syntax

public static String LocalStringToJavaString(String local);

Return Value

Returns the Unicode representation of the string.

Parameters

local The local code page string.

Remarks

Java internally uses the Unicode encoding system. Unfortunately, this means more than just using 16-bits per character in the local code page. For example, character 149 in the Microsoft® Windows® code page used in the United States (code page 1252) is a bullet. This is not true for the Macintosh or for many UNIX systems. So, if you make this a hard-coded value, the bullet does not appear correctly on other platforms.

LocalStringToJavaString(byte B[])

Converts a byte array from a local code page to an Unicode-filled character array.

Syntax

public static char[] LocalStringToJavaString(byte B[]);

Return Value

Returns the Unicode representation of the array.

Parameters

B The local code page string.

LocalStringToJavaString(char B[])

Converts a char array from a local code page to an Unicode-filled character array.

Syntax

public static char[] LocalStringToJavaString(char B[]);

Return Value

Returns the Unicode representation of the array.

Parameters

B The local code page array.

LocalStringToJavaString(byte B[], int off, int len)

Converts a part of a byte array from a local code page to a Unicode-filled character array.

Syntax

public static char[] LocalStringToJavaString(byte B[], int off, int len);

Return Value

Returns the Unicode representation of the array.

Parameters

B | The local code page array.
off | The starting point within the array.
len | The length of the segment to convert.

LocalStringToJavaString(char B[], int off, int len)

Converts a part of a character array from a local code page to an Unicode-filled character array.

Syntax

public static char[] LocalStringToJavaString(char B[], int off, int len);

Return Value

Returns the Unicode representation of the array.

Parameters

B | The local code page array.
off | The starting point within the array.
len | The number of characters to convert.

LocalStringToJavaString(byte local)

Converts a byte from a local code page to a Unicode character.

Syntax

public static char LocalStringToJavaString(byte local);

Return Value

Returns the Unicode representation of the array.

Parameters

local The local code page string.


setInputManager (SystemX Class)

 Microsoft SDK for Java

setInputManager

This method of the SystemX class sets a new input method manager.

Syntax

public static void setInputManager(InputManagerListener imm, boolean retainCurrentList);

Parameters

imm | The new input method manager. Set to null to disable input method manager services. If the new manager inherits the IME list from the previous one, set retainCurrentList to true.
retainCurrentList | The parameter returns true if the new input method manager inherits the list of IMEs. Otherwise, returns false.


setKeyboardLanguage (SystemX Class)

 Microsoft SDK for Java

setKeyboardLanguage

This method of the SystemX class sets a new active keyboard language.

Syntax

public static boolean setKeyboardLanguage(Applet App, int idLanguage);

Return Value

Returns true if the action was successful. Otherwise, false is returned.

Parameters

App | The applet to set the language.
idLanguage | The language to activate.


Fields (SystemX Class)

 Microsoft SDK for Java

SystemX Class Fields

The SystemX class contains the following fields.

LANG_AFRIKAANS | The Afrikaans language constant.
LANG_ALBANIAN | The Albanian language constant.
LANG_ARABIC | The Arabic language constant.
LANG_BASQUE | The Basque language constant.
LANG_BULGARIAN | The Bulgarian language constant.
LANG_BYELORUSSIAN | The Byelorussian language constant.
LANG_CATALAN | The Catalan language constant.
LANG_CHINESE | The generic Chinese language constant.
LANG_CROATIAN | The Croatian language constant.
LANG_CZECH | The Czech language constant.
LANG_DANISH | The Danish language constant.
LANG_DUTCH | The Dutch language constant.
LANG_ENGLISH | The English language constant.
LANG_ESTONIAN | The Estonian language constant.
LANG_FINNISH | The Finnish language constant.
LANG_FRENCH | The French language constant.
LANG_GERMAN | The German language constant.
LANG_GREEK | The Greek language constant.
LANG_HEBREW | The Hebrew language constant.
LANG_HUNGARIAN | The Hungarian language constant.
LANG_ICELANDIC | The Icelandic language constant.
LANG_INDONESIAN | The Indonesian language constant.
LANG_ITALIAN | The Italian language constant.
LANG_JAPANESE | The Japanese language constant.
LANG_KOREAN | The Korean language constant.
LANG_LATVIAN | The Latvian language constant.
LANG_LITHUANIAN | The Lithuanian language constant.
LANG_NORWEGIAN | The Norwegian language constant.
LANG_POLISH | The Polish language constant.
LANG_PORTUGUESE | The Portuguese language constant.
LANG_ROMANIAN | The Romanian language constant.
LANG_RUSSIAN | The Russian language constant.
LANG_SLOVAK | The Slovakian language constant.
LANG_SLOVENIAN | The Slovenian language constant.
LANG_SORBIAN | The Sorbian language constant.
LANG_SPANISH | The Spanish language constant.
LANG_SWEDISH | The Swedish language constant.
LANG_THAI | The Thai language constant.
LANG_TURKISH | The Turkish language constant.
LANG_UKRAINIAN | The Ukrainian language constant.
SUBLANG_CHINESE_HONGKONG | The Hong Kong SAR, PRC Chinese language constant.
SUBLANG_CHINESE_SIMPLIFIED | The Simplified Chinese language constant.
SUBLANG_CHINESE_SINGAPORE | The Singapore Chinese language constant.
SUBLANG_CHINESE_TRADITIONAL | The Traditional Chinese language constant.
SUBLANG_DUTCH_BELGIAN | The Belgian Dutch language constant.
SUBLANG_ENGLISH_AUS | The Australian English language constant.
SUBLANG_ENGLISH_CAN | The Canadian English language constant.
SUBLANG_ENGLISH_EIRE | The Eire (Irish) English language constant.
SUBLANG_ENGLISH_NZ | The New Zealand English language constant.
SUBLANG_ENGLISH_UK | The United Kingdom English language constant.
SUBLANG_ENGLISH_US | The United States English language constant.
SUBLANG_FRENCH | The French language constant.
SUBLANG_FRENCH_BELGIAN | The Belgian French language constant.
SUBLANG_FRENCH_CANADIAN | The French Canadian language constant.
SUBLANG_FRENCH_SWISS | The Swiss French language constant.
SUBLANG_GERMAN | The German language constant.
SUBLANG_GERMAN_AUSTRIAN | The Austrian German language constant.
SUBLANG_GERMAN_SWISS | The Swiss German language constant.
SUBLANG_ITALIAN | The Italian language constant.
SUBLANG_ITALIAN_SWISS | The Italian Swiss language constant.
SUBLANG_NORWEGIAN_BOKMAL | The Bokmal Norwegian language constant.
SUBLANG_NORWEGIAN_NYNORSK | The Nynorsk Norwegian language constant.
SUBLANG_PORTUGUESE | The Portuguese language constant.
SUBLANG_PORTUGUESE_BRAZILIAN | The Portuguese Brazilian language constant.
SUBLANG_SPANISH | The Spanish language constant.
SUBLANG_SPANISH_MEXICAN | The Spanish Mexican language constant.
SUBLANG_SPANISH_MODERN | The modern Spanish language constant.


com.ms.license Package Overview

Microsoft Packages Overview

The com.ms.license package includes classes that support Java object licensing files. Licensing files are used to license a Java class, package, or archive to a particular user or for a trial period (or both).

This package contains the following:

Classes

Interfaces

Hierarchy

Java object license files are stored in an encrypted eXtended Markup Language (.xml) file with the following format:

<license>

        <licensedescriptor>
                <name>name</name>
                <type>CLASS|PACKAGE|ARCHIVE</type>
                <style>DESIGN|RUNTIME</style>
                <server>URL</server>
                <user>username</user>
                <date>date</date>
                <key>key-string</key>
        </licensedescriptor>

</license>

The .xml file must be named license.xml, and either be located in the same directory as the files that it licenses, or at a URL specified in License.validate. License.xml may have only one <license> tag pair, but as many <licensedescriptor> pairs as needed to license the contents of the current directory.

Licenses may be either RUNTIME or DESIGN. If the style is DESIGN, the license is checked when the container is in design mode. If the style is RUNTIME, the license manager will fail and throw a LicenseException (this prevents developers from incorporating a runtime component into an application).


Classes (com.ms.license Package)

 Microsoft SDK for Java

com.ms.license Package Classes

The com.ms.license package contains the following classes:

License Class supports the validate method, which is used to validate a license for a Java object.

LicenseException Class represents an exception that is thrown when a Java object tries to access a license that either does not exist or is not valid.


Interfaces (com.ms.license Package)

 Microsoft SDK for Java

com.ms.license Package Interfaces

The com.ms.license package contains the following interfaces:

LicenseDescriptor Interface describes the signature of a license object.

LicenseManager Interface serves as a specification for how to implement a license manager.


Hierarchy (com.ms.license Package)

 Microsoft SDK for Java

com.ms.license Package Hierarchy

The com.ms.license package has the following hierarchy:

Object
  |
  +--License

Exception
  |
  +--LicenseException

LicenseDescriptor
LicenseManager


License Class (com.ms.license Package)

 Microsoft SDK for Java

License Class

The License Class of the com.ms.license package supports the validate method, which is used to validate a license for a Java object.

public class License
{
  // Methods
  public static void validate(Object obj, String server,
        String lic, boolean runtime) throws LicenseException;
}


Methods (License Class)

 Microsoft SDK for Java

License Class Methods

The License Class contains the following method:

validate validates a license for a Java object.


validate (License Class)

 Microsoft SDK for Java

validate

This method of the License Class validates a license for a Java object. An object can call the License.validate method and specify if the license file is necessary at runtime. If runtime is false, the license manager will not check the license.xml file at runtime. If run-time is true, the license.xml file is required and needs to be packaged with the component.

Syntax

public static void validate(Object obj, String server, String lic, boolean run-time) throws LicenseException;

Parameters

obj | The object to find the license for.
server | The server URL to get the license.xml file from if the license is server-side. Set this parameter to null if the license is client-side (the license.xml file is located in the same directory as the class, package, or archive).
lic | The string to use for license comparison.
run-time | The license is runtime only.

Exceptions

com.ms.license.LicenseException if the validation fails.


LicenseException Class (com.ms.license Package)

 Microsoft SDK for Java

LicenseException Class

The LicenseException Class of the com.ms.license package represents an exception that is thrown when a Java object tries to access a license that either does not exist or is not valid.

public class LicenseException extends Exception
{
  // Fields
  public static final int EXPIRED;
  public static final int INVALID;
  public static final int INVALID_USER;
  public static final int KEY_DOES_NOT_MATCH;
  public static final int NO_DESCRIPTORS;
  public static final int NOT_FOUND;
  public static final int READ_ERROR;
  public static final int RUNTIME_ONLY;
  public static final int WRITE_ERROR;

  // Constructors
  public LicenseException();
  public LicenseException(String s);
  public LicenseException(int id, String s);

  // Methods
  public int getID();
}

Hierarchy

Exception
  |
  +--LicenseException


Constructors (LicenseException Class)

 Microsoft SDK for Java

LicenseException Class Constructors

The LicenseException Class contains the following constructors:

LicenseException()
LicenseException(String s)jsdk
LicenseException(int id, String s)

LicenseException()

Creates a LicenseException without a detailed message.

Syntax

public LicenseException;

LicenseException(String s)

Creates a LicenseException with a detailed message.

Syntax

public LicenseException(String s);

Parameters

s The detailed message.

LicenseException(int id, String s)

Creates a new LicenseException with an identifier and a detailed message.

Syntax

public LicenseException(int id, String s);

Parameters

id | The exception identifier. This can be one of the following identifiers:
 | INVALID | NOT_FOUND | NO_DESCRIPTORS
 | WRITE_ERROR | KEY_DOES_NOT_MATCH | READ_ERROR
 | EXPIRED | RUNTIME_ONLY | INVALID_USER
s | The detailed message.


Methods (LicenseException Class)

 Microsoft SDK for Java

LicenseException Class Methods

The LicenseException Class contains the following method:

getID retrieves the exception identifier.


getID (LicenseException Class)

 Microsoft SDK for Java

getID

This method of the The LicenseException Class retrieves the exception identifier.

Syntax

public int getID();

Return Value

Returns the exception identifier. This can be one of the following identifiers.

INVALID | NOT_FOUND | NO_DESCRIPTORS
READ_ERROR | WRITE_ERROR | KEY_DOES_NOT_MATCH


Fields (LicenseException Class)

 Microsoft SDK for Java

LicenseException Class Fields

The LicenseException Class contains the following fields.

EXPIRED | An exception identifier that indicates the license is expired.
INVALID | An exception identifier that indicates that the license is invalid.
INVALID_USER | An exception identifier that indicates an invalid user argument.
KEY_DOES_NOT_MATCH | An exception identifier that indicates the key does not match.
NO_DESCRIPTORS | An exception identifier that indicates there are no descriptors for the license.
NOT_FOUND | An exception identifier that indicates that the license cannot be found.
READ_ERROR | An exception identifier that indicates there was a read error while reading the license.
RUNTIME_ONLY | An exception identifier that indicates the license has a RUNTIME style.
WRITE_ERROR | An exception identifier that indicates there was a write error.


LicenseDescriptor Interface (com.ms.license Package)

 Microsoft SDK for Java

LicenseDescriptor Interface

The LicenseDescriptor Interface of the com.ms.license package describes the signature of a license object. The descriptor allows access to the different fields of a license.

public interface LicenseDescriptor
{
  // Fields
  public static final int ARCHIVE;
  public static final int CLASS;
  public static final int DESIGN;
  public static final int PACKAGE;
  public static final int RUNTIME;

  // Methods
  public java.util.Date getDate();
  public String getKey();
  public String getName();
  public java.net.URL getServer();
  public int getStyle();
  public int getType();
  public String getUser();
  public void setDate(java.util.Date date);
  public void setKey(String key);
  public void setName(String name);
  public void setServer(java.net.URL server);
  public void setStyle(int style) throws Exception;
  public void setType(int type) throws Exception;
  public void setUser(String user);
}


Methods (LicenseDescriptor Interface)

 Microsoft SDK for Java

LicenseDescriptor Interface Methods

The LicenseDescriptor Interface contains the following methods:

getDate retrieves the expiration date of the license.
getKey retrieves the license string that is used for validation of the license.
getName retrieves the name of the class, package, or archive licensed by the license file.
getServer retrieves the server where the true license file is stored for this object.
getStyle retrieves the license style.
getType retrieves the type of license from the descriptor object.
getUser retrieves the user that is able to use the license.
setDate sets the expiration date in the license descriptor.
setKey sets the license string that is used to validate the license.
setName sets the name of the class, package, or archive that is licensed by the license descriptor.
setServer sets the server attribute for the license descriptor.
setStyle sets the license style. If style is zero, the method defaults to a design time license.
setType sets the type of license.
setUser sets the valid user for the license.


getDate (LicenseDescriptor Interface)

 Microsoft SDK for Java

getDate

This method of the LicenseDescriptor Interface retrieves the expiration date of the license.

Syntax

public java.util.Date getDate();

Return Value

Returns the expiration date. If the returned date is null, the license does not have an expiration.

See Also

setDate


getKey (LicenseDescriptor Interface)

 Microsoft SDK for Java

getKey

This method of the LicenseDescriptor Interface retrieves the license string that is used for validation of the license.

Syntax

public String getKey();

Return Value

Returns the license string to validate.

See Also

setKey


getName (LicenseDescriptor Interface)

 Microsoft SDK for Java

getName

This method of the LicenseDescriptor Interface retrieves the name of the class, package, or archive licensed by the license file.

Syntax

public String getName();

Return Value

Returns the name of the class, package, or archive.

See Also

setName


getServer (LicenseDescriptor Interface)

 Microsoft SDK for Java

getServer

This method of the LicenseDescriptor Interface retrieves the server where the true license file is stored for this object.

Syntax

public java.net.URL getServer();

Return Value

Returns the URL location of the server.

See Also

setServer


getStyle (LicenseDescriptor Interface)

 Microsoft SDK for Java

getStyle

This method of the LicenseDescriptor Interface retrieves the license style. By default, all licenses are design time licenses. However, a user can have a runtime only license.

Syntax

public int getStyle();

Return Value

Returns the style of license, either DESIGN or RUNTIME.

See Also

setStyle


getType (LicenseDescriptor Interface)

 Microsoft SDK for Java

getType

This method of the LicenseDescriptor Interface retrieves the type of license from the descriptor object.

Syntax

public int getType();

Return Value

Returns the type of license. This can be one of the following:

CLASS
ARCHIVE
PACKAGE

See Also

setType


getUser (LicenseDescriptor Interface)

 Microsoft SDK for Java

getUser

This method of the LicenseDescriptor Interface retrieves the user that is able to use the license.

Syntax

public String getUser();

Return Value

Returns the username.

See Also

setUser


setDate (LicenseDescriptor Interface)

 Microsoft SDK for Java

setDate

This method of the LicenseDescriptor Interface sets the expiration date in the license descriptor.

Syntax

public void setDate(java.util.Date date);

Parameters

date The expiration date.

See Also

getDate


setKey (LicenseDescriptor Interface)

 Microsoft SDK for Java

setKey

This method of the LicenseDescriptor Interface sets the license string that is used to validate the license.

Syntax

public void setKey(String key);

Parameters

key The license string.

See Also

getKey


setName (LicenseDescriptor Interface)

 Microsoft SDK for Java

setName

This method of the LicenseDescriptor Interface sets the name of the class, package, or archive that is licensed by the license descriptor.

Syntax

public void setName(String name);

Parameters

name The name of the class, package, or archive (.cab, .jar, and .ccf formats are currently supported).

See Also

getName


setServer (LicenseDescriptor Interface)

 Microsoft SDK for Java

setServer

This method of the LicenseDescriptor Interface sets the server attribute for the license descriptor.

Syntax

public void setServer(java.net.URL server);

Parameters

server The URL location of the server to get a remote license from.

See Also

getServer


setStyle (LicenseDescriptor Interface)

 Microsoft SDK for Java

setStyle

This method of the LicenseDescriptor Interface sets the license style. If style is zero, the method defaults to a design time license.

Syntax

public void setStyle(int style) throws Exception;

Parameters

style The style of license. This can be either DESIGN or RUNTIME.

Exceptions

Exception if the style is invalid.

See Also

getStyle


setType (LicenseDescriptor Interface)

 Microsoft SDK for Java

setType

This method of the LicenseDescriptor Interface sets the type of license.

Syntax

public void setType(int type) throws Exception;

Parameters

type Sets the type of license. The type can be one of the following:

CLASS
ARCHIVE
PACKAGE

Exceptions

Exception if the license type is not valid.

See Also

getType


setUser (LicenseDescriptor Interface)

 Microsoft SDK for Java

setUser

This method of the LicenseDescriptor Interface sets the valid user for the license.

Syntax

public void setUser(String user);

Parameters

user The username.

See Also

getUser


Fields (LicenseDescriptor Interface)

 Microsoft SDK for Java

LicenseDescriptor Class Fields

The LicenseDescriptor Interface contains the following fields.

ARCHIVE | The archive license type.
CLASS | The class license type. The CLASS type is the default type if none is specified in the license.xml file.
DESIGN | The design license style.
PACKAGE | The package license type.
RUNTIME | The runtime license style.


LicenseManager Interface (com.ms.license Package)

 Microsoft SDK for Java

LicenseManager Interface

The LicenseManager Interface of the com.ms.license package serves as a specification for how to implement a license manager. It describes all the facilities needed to perform the licensing function.

public interface LicenseManager
{
  // Methods
  public void decrypt() throws LicenseException;
  public void encrypt() throws LicenseException;
  public LicenseDescriptor[] getLicenseDescriptors();
  public void readLicense(Object obj) throws java.io.IOException;
  public void readLicense(String server) throws java.io.IOException;
  public void writeLicense(PrintStream stream,
        LicenseDescriptor desc[]) throws java.io.IOException;
}


Methods (LicenseManager Interface)

 Microsoft SDK for Java

LicenseManager Interface Methods

The LicenseManager Interface contains the following methods:

decrypt calls the decryption engine to decrypt a license file.
encrypt calls the encryption engine to encrypt a license file.
getLicenseDescriptors retrieves the license descriptors for the object.
readLicense reads a license file from a disk.
writeLicense creates a new license file and writes the contents of the LicenseDescriptor objects.


decrypt (LicenseManager Interface)

 Microsoft SDK for Java

decrypt

This method of the LicenseManager Interface calls the decryption engine to decrypt a license file.

Syntax

public void decrypt() throws LicenseException;

Exceptions

com.ms.license.LicenseException if the license could not be decrypted.


encrypt (LicenseManager Interface)

 Microsoft SDK for Java

encrypt

This method of the LicenseManager Interface calls the encryption engine to encrypt a license file.

Syntax

public void encrypt() throws LicenseException;

Exceptions

com.ms.license.LicenseException if the license could not be encrypted.


getLicenseDescriptors (LicenseManager Interface)

 Microsoft SDK for Java

getLicenseDescriptors

This method of the LicenseManager Interface retrieves the license descriptors for the object.

Syntax

public LicenseDescriptor[] getLicenseDescriptors();

Return Value

Returns LicenseDescriptor An array of LicenseDescriptor objects.


readLicense (LicenseManager Interface)

 Microsoft SDK for Java

readLicense

The readLicense method of the LicenseManager Interface contains the following signatures:

readLicense(Object obj)
readLicense(String server)

readLicense(Object obj)

Reads a license file from a disk.

Syntax

public void readLicense(Object obj) throws java.io.IOException;

Return Value

No return value.

Exception

IOException if the read failed.

Parameters

obj The object used to read the license file.

readLicense(String server)

Reads a license from a server.

Syntax

public void readLicense(String server) throws java.io.IOException;

Parameters

server The server to get the license file from.

Exceptions

IOException if the read failed.


writeLicense (LicenseManager Interface)

 Microsoft SDK for Java

writeLicense

This method of the LicenseManager Interface creates a new license file and writes the contents of the LicenseDescriptor objects.

Syntax

public void writeLicense(PrintStream stream, LicenseDescriptor desc[]) throws java.io.IOException;

Parameters

stream | The stream to write the license file to.
desc | An array of LicenseDescriptor objects.

Exceptions

IOException if the write failed.


com.ms.net.wininet Package Overview

Microsoft Packages Overview

The com.ms.net.wininet package contains the implementation of URL sockets.

This package contains the following:

Classes


Classes (com.ms.net.wininet Package)

 Microsoft SDK for Java

com.ms.net.wininet Package Classes

Microsoft Packages Overview

The com.ms.net.wininet package contains the following class:

WininetStreamHandlerFactory class contains a method that creates a URLStreamHandler object for a specified protocol.


WininetStreamHandlerFactory class (com.ms.net.wininet Package)

 Microsoft SDK for Java

WininetStreamHandlerFactory Class

The WininetStreamHandlerFactory class of the com.ms.net.wininet package contains a method that creates a URLStreamHandler object for a specified protocol.

Calls to java.net.URL.setURLStreamHandlerFactory (new com.ms.net.wininet.WininetStreamHandlerFactory( ) ) use Win32's wininet as the handler for http and https URLs. This is the same handler that is installed by default when running applets.

Also by default, http URLs are handled through sockets in Java. They do not use the Temporary Internet Files cache or similar features. If you do not use the WininetStreamHandlerFactory class, https is unsupported by default.

public class WininetStreamHandlerFactory implements java.net.URLStreamHandlerFactory
{
  // Methods
  public java.net.URLStreamHandler createURLStreamHandler(String protocol);
}


Methods (WininetStreamHandlerFactory Class)

 Microsoft SDK for Java

WininetStreamHandlerFactory Class Methods

The WininetStreamHandlerFactory class contains the following method.

createURLStreamHandler creates a URLStreamHandler object for a specified protocol.


createURLStreamHandler (WininetStreamHandlerFactory Class)

 Microsoft SDK for Java

createURLStreamHandler

This method of the WininetStreamHandlerFactory class creates a URLStreamHandler object for a specified protocol.

Syntax

public java.net.URLStreamHandler createURLStreamHandler(String protocol);

Parameters

protocol The specified protocol.


com.ms.object Package Overview

Microsoft Packages Overview

The com.ms.object package provides classes and interfaces for implementing data transfer operations.

This package contains the following:

Classes

Interfaces

Hierarchy

Many of the classes and interfaces in the com.ms.object package are designed to facilitate data transfer. The Transfer, TransferSession, and MetaObject interfaces and the Category class define the basic protocol for data transfer. The ObjectBag and SimpleTransferSession classes provide default implementations for commonly used interfaces.

During data transfer, a data recipient obtains a TransferSession and acts upon it. The recipient might, for example, interrogate the session to determine the types of transfers supported (by using the getAvailableEffects and getPreferredEffects methods). The recipient might also ask the session for the data being transferred (by using the getTransferData method). The data is represented in the form of a MetaObject, which can also be interrogated to determine what forms the transferred data can take.

The com.ms.object package also contains classes and interfaces that allow Java components to obtain a system service. For instance, a Java component that is hosted inside a Microsoft® ActiveX® container might want to obtain the ActiveXControlServices system service. To obtain a system service, a Java component that implements the ISiteable interface could query for and obtain an ISite object. This site object could then be queried for the service using the IServiceObjectProvider.queryService method. If the requested service is not available, a ServiceNotFoundException is thrown.

Examples

The recipient might want to support transfer of text in HTML format if it is available and fall back to plain text if HTML is not available. The following example illustrates how to interrogate the MetaObject to determine whether HTML is supported:

class Recipient
{
   Category htmlCategory = new Category("text/html");
   Category plainCategory = new Category("text/plain");

   // This method interrogates a MetaObject for data transfer.
   public void interrogate(MetaObject data)
   {
     try
     {
        Class streamClass = Class.forName("java.io.InputStream");
        if (data.hasObject(htmlCategory, streamClass))
        {
          InputStream stream = data.getObject(htmlCategory,
                                              streamClass);
          // Do something with HTML stream.
        }
        else if (data.hasObject(plainCategory, streamClass))
        {
          InputStream stream = data.getObject(plainCategory,
                                              streamClass);
          // Do something with plain text stream.
        }
     }
     catch(ClassNotFoundException e)
     {
     }
   }
}

For recipients that support many formats, it might be more efficient to enumerate the formats supported by the MetaObject. Using this technique, a recipient can determine possible actions based on the types of data that are offered.

class Recipient
{
   Category htmlCategory = new Category("text/html");
   Category plainCategeory = new Category ("text/plain");

   // The recipient may keep private flags to track what can
   // be done with the data.
   private static final int HAS_HTML = 1;
   private static final int HAS_TEXT = 2;

   // This method determines the values of the HAS_HTML
   // and HAS_TEXT flags based on the data being offered.
   public int interrogate(MetaObject data)
   {
     private int avail = 0;

     try
     {
        Class streamClass = Class.forName("java.io.InputStream");
        Enumeration categories = data.objectCategories();
        if (categories != null)
        {
          while (categories.hasMoreElements())
          {
             Category category = (Category)categories.nextElement();
             if (category.equals(htmlCategory))
                avail |= HAS_HTML;
             else if (category.equals(plainCategory))
                avail |= HAS_TEXT;
          }
        }
     }
     catch (ClassNotFoundException e)
     {
     }

     return avail;
  }
}


Classes (com.ms.object Package)

 Microsoft SDK for Java

com.ms.object Package Classes

The com.ms.object package contains the following classes:

Category Class provides an abstract type identity.

ObjectBag Class is a default implementation of the MetaObject interface that can be used to implement delayed rendering.

ServiceNotFoundException Class represents an exception indicating that a requested service was not available.

SimpleTransferSession Class is a default implementation of the TransferSession interface.


Interfaces (com.ms.object Package)

 Microsoft SDK for Java

com.ms.object Package Interfaces

The com.ms.object package contains the following interfaces:

IServiceObjectProvider Interface defines a method used to request a service from an object.

ISite Interface defines the removeSiteable method, which is called when an ISiteable object detaches itself from a site.

ISiteable Interface defines methods that set and retrieve the ISite object that is associated with an ISiteable object.

MetaObject Interface defines an abstraction for an object that has multiple identities.

Transfer Interface provides constants that represent transfer effects.

TransferSession Interface defines a data transfer session abstraction that is used to describe a transfer operation.


Hierarchy (com.ms.object Package)

 Microsoft SDK for Java

com.ms.object Package Hierarchy

The com.ms.object package has the following hierarchy:

Object

  |
  +-- ObjectBag (MetaObject)
  |
  +-- SimpleTransferSession(TransferSession)
  |
  +-- Category

Exception

  |
  +-- ServiceNotFoundException

TransferSession

Transfer

IServiceObjectProvider

ISite

ISiteable

MetaObject


Category Class (com.ms.object Package)

 Microsoft SDK for Java

Category Class

The Category Class of the com.ms.object package provides an abstract type identity. Category objects are used to describe the types of objects that are supported by a MetaObject.

public class Category
{
  // Constructors
  public Category(String name);

  // Methods
  public boolean equals(Category other);
  public boolean equals(Object other);
  public String getName();
  public int hashCode();
  public String toString();
}


Constructors (Category Class)

 Microsoft SDK for Java

Category Class Constructors

The Category Class contains the following constructor:

Category(String name)

Creates a new Category object with the specified name.

Syntax

public Category(String name);

Parameters

name The name for the new category.


Methods (Category Class)

 Microsoft SDK for Java

Category Class Methods

The Category contains the following methods:

equals tests a category for equality with another category.
getName retrieves the name of the category.
hashCode retrieves the category's hash code.
toString produces a summary string for the category.


equals (Category Class)

 Microsoft SDK for Java

equals

The equals method of the Object Class contains the following signatures:

equals(Category other)
equals(Object other)

equals(Category other)

Tests a category for equality with another category. Two categories are equal if they have the same name.

Syntax

public boolean equals(Category other);

Return Value

Returns true if other is not null and the two categories have the same name; otherwise, returns false.

Parameters

other The other Category object to test for equality.

equals(Object other)

Tests a category for equality with another object.

Syntax

public boolean equals(Object other);

Return Value

Returns true if the other object is a category and the two categories are equal; otherwise, returns false.

Parameters

other The other object to test for equality.


getName (Category Class)

 Microsoft SDK for Java

getName

This method of the Category Class retrieves the name of the category.

Syntax

public String getName();

Return Value

Returns a String that identifies the category.


hashCode (Category Class)

 Microsoft SDK for Java

hashCode

This method of the Category Class retrieves the category's hash code.

Syntax

public int hashCode();

Return Value

Returns an integer hash code for the category.


toString (Category Class)

 Microsoft SDK for Java

toString

This method of the Category Class produces a summary string for the category.

Syntax

public String toString();

Return Value

Returns a String that describes the category by using the name of the category.


ObjectBag Class (com.ms.object Package)

 Microsoft SDK for Java

ObjectBag Class

The Object Bag Class of the com.ms.object package is a default implementation of the MetaObject interface that can be used to implement delayed rendering.

public class ObjectBag implements MetaObject
{
  // Constructors
  public ObjectBag();
  public ObjectBag(MetaObject renderer);

  // Methods
  public void addObject(Category category, Class cls, Object object);
  public Object getObject(Category category, Class cls);
  public boolean hasObject(Category category, Class cls);
  public Enumeration objectCategories();
  public Enumeration objectClasses(Category category);
}

Delayed rendering allows a data source to support several different data formats and convert these formats as necessary, based on the requirements of the recipient.

For instance, a word processor might have an internal text representation, but it might also know how to convert its text representation to plain text, rich text, or other formats. Instead of providing all possible conversions when it constructs the MetaObject for a data transfer, the word processor could run the conversion on demand, depending on the format required by the recipient.

To implement delayed rendering, a data source might implement a MetaObject that always does format conversions and then wrap an ObjectBag around it. When the ObjectBag is asked for a data format it does not support, it asks the source MetaObject to obtain the data, thereby running the conversion. The converted data is then stored in the ObjectBag for future use.


Constructors (ObjectBag Class)

 Microsoft SDK for Java

ObjectBag Class Constructors

The ObjectBag Class contains the following constructors:

ObjectBag()
ObjectBag(MetaObject renderer)

ObjectBag()

Creates an assignable ObjectBag object with no delayed renderer.

Syntax

public ObjectBag();

ObjectBag(MetaObject renderer)

Creates an ObjectBag object with a delayed renderer.

Syntax

public ObjectBag(MetaObject renderer);

Parameters

renderer The MetaObject that the ObjectBag should use for delayed rendering.


Methods (ObjectBag Class)

 Microsoft SDK for Java

Object Bag Methods

The ObjectBag Class contains the following methods:

addObject adds an object to the ObjectBag.
getObject requests an object with the specified category and class from the ObjectBag.
hasObject determines whether the specified category and class are supported by the ObjectBag.
objectCategories enumerates the categories in the ObjectBag.
objectClasses enumerates the classes in the ObjectBag that are in the specified category.


addObject (ObjectBag Class)

 Microsoft SDK for Java

addObject

This method of the ObjectBag Class adds an object to the ObjectBag.

Syntax

public void addObject(Category category, Class cls, Object object);

Parameters

category | The Category of the object being added.
cls | The Class of the object being added. If cls is null, the class is inferred from the specified Object.
object | The object to add to the object bag.


getObject (ObjectBag Class)

 Microsoft SDK for Java

getObject

This method of the ObjectBag Class requests an object with the specified category and class from the ObjectBag.

Syntax

public Object getObject(Category category, Class cls);

Return Value

Returns an object with the specified category and class.

Parameters

category | The Category object that represents the category that is requested.
cls | The Class object that represents the class that is requested.


hasObject (ObjectBag Class)

 Microsoft SDK for Java

hasObject

This method of the ObjectBag Class determines whether the specified category and class are supported by the ObjectBag.

Syntax

public boolean hasObject(Category category, Class cls);

Return Value

Returns true if the ObjectBag supports the specified category and class; otherwise, returns false.

Parameters

category | The Category object that represents the category being queried for.
cls | The Class object that represents the class being queried for.


objectCategories (ObjectBag Class)

 Microsoft SDK for Java

objectCategories

This method of the ObjectBag Class enumerates the categories in the ObjectBag.

Syntax

public Enumeration objectCategories();

Return Value

Returns an Enumeration of the categories in the ObjectBag.


objectClasses (ObjectBag Class)

 Microsoft SDK for Java

objectClasses

This method of the ObjectBag Class enumerates the classes in the ObjectBag that are in the specified category.

Syntax

public Enumeration objectClasses(Category category);

Return Value

Returns an Enumeration of the classes in the ObjectBag that are in the specified category.

Parameters

category

The category that identifies which classes to enumerate.


ServiceNotFoundException Class (com.ms.object Package)

 Microsoft SDK for Java

ServiceNotFoundException Class

The ServiceNotFoundException Class of the com.ms.object package represents an exception indicating that a requested service was not available.

public class ServiceNotFoundException extends Exception
{
  // Constructors
  public ServiceNotFoundException();
  public ServiceNotFoundException(String s);
}

Hierarchy

Exception
  |
  +--ServiceNotFoundException


Constructors (ServiceNotFoundException Class)

 Microsoft SDK for Java

ServiceNotFoundException Class Constructors

The ServiceNotFoundException Class contains the following constructors:

ServiceNotFoundException()
ServiceNotFoundException(String s)

ServiceNotFoundException()

Creates a ServiceNotFoundException with no detail message.

Syntax

public ServiceNotFoundException();

ServiceNotFoundException(String s)

Creates a ServiceNotFoundException with the specified detail message.

Syntax

public ServiceNotFoundException(String s);

Parameters

s The detail message.


SimpleTransferSession Class (com.ms.object Package)

 Microsoft SDK for Java

SimpleTransferSession Class

The SimpleTransferSession Class of the com.ms.object package is a default implementation of the TransferSession interface.

public class SimpleTransferSession implements TransferSession
{
  // Constructors
  public SimpleTransferSession(MetaObject data, int available);
  public SimpleTransferSession(MetaObject data, int available, int preferred);

  // Methods
  public void deleteSource();
  public int getAvailableEffects();
  public int getPreferredEffects();
  public MetaObject getTransferData();
}

If you do not want to customize the behavior of a TransferSession but you want to source some data, the SimpleTransferSession class might be sufficient for your needs.

Be aware that this class does not support the Transfer.MOVE transfer effect because it requires an implementation of TransferSession.deleteSource (which the SimpleTransferSession class does not provide). To remedy this situation, you could extend the SimpleTransferSession class to gain the TransferSession implementation and then override the deleteSource method.


Constructors (SimpleTransferSession Class)

 Microsoft SDK for Java

SimpleTransferSession Class Constructors

The SimpleTransferSession Class contains the following constructors:

SimpleTransferSession(MetaObject data, int available)
SimpleTransferSession(MetaObject data, int available, int preferred)

SimpleTransferSession(MetaObject data, int available)

Creates a SimpleTransferSession object with a data object and the specified available transfers. The preferred transfers of the SimpleTransferSession object default to the specified available transfers.

Syntax

public SimpleTransferSession(MetaObject data, int available);

Parameters

data | The MetaObject that represents the data that is transferred by the transfer session.
available | A value that identifies the available transfer effects. It can be any one or a combination of the following values: NONE, COPY, MOVE, or LINK.

SimpleTransferSession(MetaObject data, int available, int preferred)

Creates a SimpleTransferSession data transfer session object with a data object and specified available and preferred transfer effects.

Syntax

public SimpleTransferSession(MetaObject data, int available, int preferred);

Parameters

data | A MetaObject that represents the data that is transferred by the transfer session.
available | A value that identifies the available transfer effects. It can be any one or a combination of the following values: NONE, COPY, MOVE, or LINK.
preferred | An integer that identifies the preferred transfer effects. It can be any one or a combination of the following values: NONE, COPY, MOVE, or LINK.


Methods (SimpleTransferSession Class)

 Microsoft SDK for Java

SimpleTransferSession Class Methods

The SimpleTransferSession Class contains the following methods:

deleteSource this method does nothing.
getAvailableEffects retrieves the Transfer effects that are available in the session.
getPreferredEffects retrieves the Transfer effects that are preferred by the originator of the session.
getTransferData retrieves the data that is associated with the session.


deleteSource (SimpleTransferSession Class)

 Microsoft SDK for Java

deleteSource

This method of the SimpleTransferSession Class does nothing.

Syntax

public void deleteSource();


getAvailableEffects (SimpleTransferSession Class)

 Microsoft SDK for Java

getAvailableEffects

This method of the SimpleTransferSession Class retrieves the Transfer effects that are available in the session.

Syntax

public int getAvailableEffects();

Return Value

Returns a value that identifies the available transfer effects. It can be any one or a combination of the following values:

NONE, COPY, MOVE, or LINK.


getPreferredEffects (SimpleTransferSession Class)

 Microsoft SDK for Java

getPreferredEffects

This method of the SimpleTransferSession Class retrieves the Transfer effects that are preferred by the originator of the session.

Syntax

public int getPreferredEffects();

Return Value

Returns a value that identifies the preferred transfer effects. It can be any one or a combination of the following values:

NONE, COPY, MOVE, or LINK.


getTransferData (SimpleTransferSession Class)

 Microsoft SDK for Java

getTransferData

This method of the SimpleTransferSession Class retrieves the data that is associated with the session.

Syntax

public MetaObject getTransferData();

Return Value

Returns a MetaObject that represents the data offered for transfer.


IServiceObjectProvider Interface (com.ms.object Package)

 Microsoft SDK for Java

IServiceObjectProvider Interface

The IServiceObjectProvider Interface of the com.ms.object package defines a method that is used to request a service from an object.

public interface IServiceObjectProvider
{
  // Methods
  public Object queryService(Object id) throws ServiceNotFoundException;
}


Methods (IServiceObjectProvider Interface)

 Microsoft SDK for Java

IServiceObjectProvider Interface Methods

The IServiceObjectProvider Interface contains the following method:

queryService requests a service from an object.


queryService (IServiceObjectProvider Interface)

 Microsoft SDK for Java

queryService

This method of the IServiceObjectProvider Interface requests a service from an object. The object that provides the service can be the current object or a different object.

To determine whether the object supports the requested service, a typical implementation would check to see if any of the following items are true:

  • The object is an instance of the requested service.

  • The object implements the requested service.

  • The object can construct or use another object that is an instance of or implements the requested service.

If the object does not support the requested service, it delegates the method call to an upper level object (such as a containing frame). Finally, if no object in the chain supports the requested service, a ServiceNotFoundException is thrown.

Syntax

public Object queryService(Object id) throws ServiceNotFoundException;

Return Value

Returns the service object, if it is available.

Parameters

id The identifier of the requested service.

Exceptions

ServiceNotFoundException if no object supports the requested service.


ISite Interface (com.ms.object Package)

 Microsoft SDK for Java

ISite Interface

The ISite Interface of the com.ms.object package defines the removeSiteable method, which is called when an ISiteable object detaches itself from a site.

public interface ISite extends IServiceObjectProvider
{
  // Methods
  public void removeSiteable(ISiteable siteable);
}

Hierarchy

IServiceObjectProvider
  |
  +--ISite


Methods (ISite Interface)

 Microsoft SDK for Java

ISite Interface Methods

The ISite Interface contains the following method:

removeSiteable notifies the site that the ISiteable object is detaching itself from the site.


removeSiteable (ISite Interface)

 Microsoft SDK for Java

removeSiteable

This method of the ISite Interface notifies the site that the ISiteable object is detaching itself from the site. This notification provides an opportunity for the site to perform any cleanup, such as removing the ISiteable object from its list of objects.

An ISiteable object calls this method whenever its site changes (because the setSite method has been called) or when the ISiteable object is no longer bound to the site.

Syntax

public void removeSiteable(ISiteable siteable);

Parameters

siteable The object that is detaching from the site.


ISiteable Interface (com.ms.object Package)

 Microsoft SDK for Java

ISiteable Interface

The ISiteable Interface of the com.ms.object package interface defines methods that set and retrieve the ISite object that is associated with an ISiteable object.

public interface ISiteable
{
  // Methods
  public ISite getSite();
  public void setSite(ISite site);
}


Methods (ISiteable Interface)

 Microsoft SDK for Java

ISiteable Interface Methods

The ISiteable Interface contains the following methods:

getSite retrieves the ISite object for this instance.
setSite sets the ISite object for this instance.


getSite (ISiteable Interface)

 Microsoft SDK for Java

getSite

This method of the ISiteable Interface retrieves the ISite object for this instance.

Syntax

public ISite getSite();

Return Value

Returns the ISite object for this instance. If no ISite object is currently set, null is returned.


setSite (ISiteable Interface)

 Microsoft SDK for Java

setSite

This method of the ISiteable Interface sets the ISite object for this instance. Any references to an existing site or to any services provided through the ISite object are discarded.

For the sake of serialization, the object should mark the field containing this site as "transient."

Syntax

public void setSite(ISite site);

Parameters

site The ISite object for this instance (can be null).


MetaObject Interface (com.ms.object Package)

 Microsoft SDK for Java

MetaObject Interface

The MetaObject Interface of the com.ms.object package defines an abstraction for an object that has multiple identities. A class that implements the MetaObject interface can be used to represent data that is being transferred.

public interface MetaObject
{
  // Methods
  public Object getObject(Category category, Class cls);
  public boolean hasObject(Category category, Class cls);
  public Enumeration objectCategories();
  public Enumeration objectClasses(Category category);
}


Methods (MetaObject Interface)

 Microsoft SDK for Java

MetaObject Interface Methods

The MetaObject Interface contains the following methods:

getObject retrieves an object instance that matches the specified Category and Class objects.
hasObject determines whether the specified Category and Class are supported by the MetaObject.
objectCategories enumerates the categories that are supported by the MetaObject.
objectClasses enumerates the classes that are used to describe the specified category.


getObject (MetaObject Interface)

 Microsoft SDK for Java

getObject

This method of the MetaObject Interface retrieves an object instance that matches the specified Category and Class objects. Either one (but not both) of the parameters can be null.

Syntax

public Object getObject(Category category, Class cls);

Return Value

Returns an object that matches the specified Category and Class; returns null if no matching object is available.

Parameters

category | The Category of the requested object. If a null Category object is specified, the Category is derived from the name of the specified class.
cls | The Class of the requested object. If a null Class is specified, the request is for any object in the specified category.


hasObject (MetaObject Interface)

 Microsoft SDK for Java

hasObject

This method of the MetaObject Interface determines whether the specified Category and Class are supported by the MetaObject. Either one (but not both) of the parameters can be null.

Syntax

public boolean hasObject(Category category, Class cls);

Return Value

Returns true if an object that matches the specified Category and Class is available; otherwise, returns false.

Parameters

category | The Category that is requested. If a null Category object is specified, the category is derived from the name of the specified class.
cls | The Class that is requested. If a null Class is specified, the request is for any class in the specified category.


objectCategories (MetaObject Interface)

 Microsoft SDK for Java

objectCategories

This method of the MetaObject Interface enumerates the categories that are supported by the MetaObject.

Syntax

public Enumeration objectCategories();

Return Value

Returns an Enumeration of the Category objects that are supported.


objectClasses (MetaObject Interface)

 Microsoft SDK for Java

objectClasses

This method of the MetaObject Interface enumerates the classes that are used to describe the specified category.

Syntax

public Enumeration objectClasses(Category category);

Return Value

Returns an Enumeration of Class objects in the specified Category that are supported by the MetaObject.

Parameters

category The Category to enumerate Class objects from.


Transfer Interface (com.ms.object Package)

 Microsoft SDK for Java

Transfer Interface

The Transfer Interface of the com.ms.object package provides constants that represent transfer effects. These constants are used by the TransferSession interface and the SimpleTransferSession class.

public interface Transfer
{
  // Fields
  public static final int COPY;
  public static final int LINK;
  public static final int MOVE;
  public static final int NONE;
}


Fields (Transfer Interface)

 Microsoft SDK for Java

Transfer Interface Fields

The Transfer Interface contains the following fields.

COPY | A value indicating that the transfer copies data.
LINK | A value indicating that the transfer links to data.
MOVE | A value indicating that the transfer moves data.
NONE | A value indicating that there is no current transfer.


TransferSession Interface (com.ms.object Package)

 Microsoft SDK for Java

TransferSession Interface

The TransferSession Interface of the com.ms.object package defines a data transfer session abstraction that is used to describe a transfer operation.

public interface TransferSession extends Transfer
{
  // Methods
  public void deleteSource();
  public int getAvailableEffects();
  public int getPreferredEffects();
  public MetaObject getTransferData();
}

The source of a transfer creates a TransferSession and then initiates the transfer. During data transfer, a recipient obtains a TransferSession and acts on it by interrogating it for the transfer effects supported and the data being transferred.

Hierarchy

Transfer
  |
  +--TransferSession


Methods (TransferSession Interface)

 Microsoft SDK for Java

TransferSession Interface Methods

The TransferSession Interface contains the following methods:

deleteSource deletes the source data.
getAvailableEffects retrieves the Transfer effects that are available in the session.
getPreferredEffects retrieves the Transfer effects that are preferred by the originator of the session.
getTransferData retrieves the data that is associated with the session.


deleteSource (TransferSession Interface)

 Microsoft SDK for Java

deleteSource

This method of the TransferSession Interface deletes the source data. This method facilitates MOVE operations where the destination is only capable of performing a COPY operation. That is, instead of performing a MOVE operation, a COPY operation can be performed and then the data can be deleted from the source.

Syntax

public void deleteSource();


getAvailableEffects (TransferSession Interface)

 Microsoft SDK for Java

getAvailableEffects

This method of the TransferSession Interface retrieves the Transfer effects that are available in the session.

Syntax

public int getAvailableEffects();

Return Value

Returns a value that identifies the available transfer effects. It can be any one (or a combination of) the following values:

NONE, COPY, MOVE, or LINK.


getPreferredEffects (TransferSession Interface)

 Microsoft SDK for Java

getPreferredEffects

This method of the TransferSession Interface retrieves the Transfer effects that are preferred by the originator of the session.

Syntax

public int getPreferredEffects();

Return Value

Returns a value that identifies the preferred transfer effects. It can be any one (or a combination of) the following values:

NONE, COPY, MOVE, or LINK.


getTransferData (TransferSession Interface)

 Microsoft SDK for Java

getTransferData

This method of the TransferSession Interface retrieves the data that is associated with the session.

Syntax

public MetaObject getTransferData();

Return Value

Returns a MetaObject that represents the data offered for transfer.


com.ms.object.dragdrop Package Overview

Microsoft Packages Overview

The com.ms.object.dragdrop package provides classes and interfaces for implementing visual drag-and-drop operations.

This package contains the following:

Classes

Interfaces

Hierarchy

The com.ms.object.dragdrop package uses the transfer model defined in the com.ms.object package, adding behavior that is specific to visual drag-and-drop operations. The basic dragdrop protocol is defined by the DragHandler, DragSession, and DragSource interfaces. The DragHelper and DragProxy classes help developers implement the dragdrop protocol for objects that are not supported by the system. DragProxy is a simple DragHandler implementation that forwards all calls to a specified DragHandler, with an optional offset to the drag coordinates. The DragHelper class implements the DragHandler interface and distributes DragHandler method calls to child handlers.

The DragHandler interface is implemented by recipients who want to receive drops from a drag source. This interface contains methods for notifying the recipient when the object has entered, exited, moved, or has been dropped by the user. DragSession extends the TransferSession interface and adds the concepts of modifier keys and mouse state. The DragSession interface is generally implemented by the dragdrop implementation. To customize the behavior of a drag operation as it progresses, you can implement the DragSource interface, which provides capabilities such as cursor control.

Drag Handler Example

This example shows how to implement a DragHandler. In particular, this class implements a ColorTile object that can receive a new color (java.awt.Color) by a drag-and-drop operation.

class ColorTile extends Canvas implements DragHandler
{
   static final private Class colorClass = new Color( ).getClass( );

   Color color;
   Color colorHot;
   boolean hot = false;

   public ColorTile(Color c, int x, int y)
   {
      super( );
      initFromColor(c);
      reshape(16 * x + 64, 16 * y + 64, 128, 128);
   }

   private void initFromColor(Color c)
   {
      color = c.darker( );
      colorHot = c;
      hotTrack(hot);
   }

   private void hotTrack(boolean hot)
   {
      this.hot = hot;

      Color c = hot? colorHot : color;
      setBackground(c);

      if (isShowing( ))
         repaint( );
   }

   public void dragEnter(DragSession session)
   {
      hotTrack(true);
   }

   public void dragLeave( )
   {
      hotTrack(false);
   }

   public int dragOver(DragSession session, int x, int y)
   {
      //Interrogate the data to see if there is a color.

      MetaObject data = session.getTransferData( );
      if ((data !=      null) && data.hasObject(null, colorClass))
      {
         //There is a color. Return a value that indicates
         // that we can copy it if the source is allowing copy
         // operations.
         return session.getAvailableEffects( ) & Transfer.COPY;
      }

      return Transfer.NONE;
   }

   public void drop(DragSession session int x, int y)
   {
       MetaObject data = session.getTransferData( );
       if (data != null)
       {
          Object object = data.getObject(null, colorClass);
          if (object instanceof Color)
             initFromColor((Color)object);
       }
    }
}

Drag Session Examples

Starting a drag session differs, depending on whether you are using AFC or AWT. Two code samples follow: the first is for AWT, and the second is for AFC.

AWT Example

import java.awt.*;
import com.ms.object.*;
import com.ms.object.dragdrop.*;
import com.ms.awt.WDragSession;

class DragMeAWT extends Canvas
{
//...
  public boolean mouseDown(Event e, int x, int y)
  {
    ObjectBag data = new ObjectBag();
    data.addObject(null, null, Color.red);
    WDragSession.beginDrag(data, Transfer.COPY | Transfer.LINK);

    return true;
  }
}

AFC Example

import com.ms.ui.*;
import com.ms.object.*;
import com.ms.object.dragdrop.*;
import java.awt.Color;

class DragMeAFC extends UICanvas
{
//...
  public boolean mouseDown(Event e, int x, int y)
  {
    ObjectBag data = new ObjectBag();
    data.addObject(null, null, Color.red);
    UIDragDrop.beginDrag(data, Transfer.COPY | Transfer.LINK);

    return true;
  }
}


Classes (com.ms.object.dragdrop Package)

 Microsoft SDK for Java

com.ms.object.dragdrop Package Classes

The com.ms.object.dragdrop package contains the following classes:

DragHelper Class provides a default implementation for a dragdrop protocol involving a set of objects that the system does not support.

DragProxy Class provides a DragHandler implementation that forwards calls to another specified DragHandler.


Interfaces (com.ms.object.dragdrop Package)

 Microsoft SDK for Java

com.ms.object.dragdrop Package Interfaces

The com.ms.object.dragdrop package contains the following interfaces:

DragHandler Interface defines methods that handle drag operations relative to other objects.

DragSession Interface defines drag modifiers used with drag-and-drop operations.

DragSource Interface defines constants and methods that can be used by the source object of a dragdrop data transfer session.


Hierarchy (com.ms.object.dragdrop Package)

 Microsoft SDK for Java

com.ms.object.dragdrop Package Hierarchy

The com.ms.object.dragdrop package has the following hierarchy:

Object
  |
  +-- DragHelper (DragHandler)
  |
  +-- DragProxy (DragHandler)

DragSource
DragSession
DragHandler


DragHelper Class (com.ms.object.dragdrop Package)

 Microsoft SDK for Java

DragHelper Class

The DragHelper Class of the com.ms.object.dragdrop package provides a default implementation for a dragdrop protocol involving a set of objects that the system does not support. For instance, if you are designing a tree control that is not composed of system components, you could use this class (along with the DragProxy class) to help implement the enter, continue, leave, and drop behaviors over the subelements in your tree.

public abstract class DragHelper implements DragHandler
{
  // Methods
  public void dragEnter(DragSession session);
  public void dragLeave();
  public int dragOver(DragSession session, int x, int y);
  public void drop(DragSession session, int x, int y);
  protected abstract Object findDragObject(DragSession session, int
        x, int y);
  protected abstract DragHandler getDragHandler(
        DragSession session, Object object);
  protected void trackDragStatus(DragSession session,
        Object object, int effect);
}

Typically, you would extend the DragHelper class, providing hit-testing code to implement the findDragObject and getDragHandler methods.

When a drag method is called on a class that extends DragHelper, the drag method calls the findDragObject method to hit-test the coordinates in the drag method. The derived class returns an Object that represents the hit result.

If the Object has changed since the last hit-test, the drag helper then calls the getDragHandler method to obtain a DragHandler for the new hit Object. In addition, the derived class can override the trackDragStatus method to implement highlighting or some other form of feedback.


Methods (DragHelper Class)

 Microsoft SDK for Java

DragHelper Class Methods

The DragHelper Class contains the following methods:

dragEnter notifies the recipient when a source object enters the space that is defined by a container, window, or object.
dragLeave notifies the recipient when a source object exits the space that is defined by a container, window, or object.
dragOver notifies the recipient when a source object continues through the space that is defined by a container, window, or object.
drop notifies the recipient when a source object is dropped at a new location.
findDragObject provides a hit-test of the coordinates in the drag method.
getDragHandler retrieves the DragHandler object for the specified drag session.
trackDragStatus is not currently implemented.


dragEnter (DragHelper Class)

 Microsoft SDK for Java

dragEnter

This method of the DragHelper Class notifies the recipient when a source object enters the space that is defined by a container, window, or object.

Syntax

public void dragEnter(DragSession session);

Parameters

session The DragSession object that represents the current drag operation.


dragLeave (DragHelper Class)

 Microsoft SDK for Java

dragLeave

This method of the DragHelper Class notifies the recipient when a source object exits the space that is defined by a container, window, or object.

Syntax

public void dragLeave();


dragOver (DragHelper Class)

 Microsoft SDK for Java

dragOver

This method of the DragHelper Class notifies the recipient when a source object continues through the space that is defined by a container, window, or object.

Syntax

public int dragOver(DragSession session, int x, int y);

Return Value

Returns one or more of the following values:

NONE, COPY, MOVE, or LINK.

Parameters

session | The DragSession object that represents the current drag operation.
x | The x-coordinate of the current cursor position.
y | The y-coordinate of the current cursor position.


drop (DragHelper Class)

 Microsoft SDK for Java

drop

This method of the DragHelper Class notifies the recipient when a source object is dropped at a new location.

Syntax

public void drop(DragSession session, int x, int y);

Parameters

session | The DragSession object that represents the current drag operation.
x | The x-coordinate of the current cursor position.
y | The y-coordinate of the current cursor position.


findDragObject (DragHelper Class)

 Microsoft SDK for Java

findDragObject

This method of the DragHelper Class provides a hit-test of the coordinates in the drag method.

Syntax

protected abstract Object findDragObject(DragSession session, int x, int y);

Return Value

Returns the object that represents the hit result.

Parameters

session | The DragSession object that represents the current drag operation.
x | The x-coordinate to hit-test.
y | The y-coordinate to hit-test.


getDragHandler (DragHelper Class)

 Microsoft SDK for Java

getDragHandler

This method of the DragHelper Class retrieves the DragHandler object for the specified drag session.

Syntax

protected abstract DragHandler getDragHandler(DragSession session, Object object);

Return Value

Returns a DragHandler for the drag-and-drop operation.

Parameters

session | The DragSession object that represents the current drag operation.
object | The object returned by the findDragObject method.


trackDragStatus (DragHelper Class)

 Microsoft SDK for Java

trackDragStatus

This method of the DragHelper Class is not currently implemented. It is called by the dragEnter, dragOver, and dragLeave methods to track the status of the current drag operation.

Syntax

protected void trackDragStatus(DragSession session, Object object, int effect)

Parameters

session | The DragSession object that represents the current drag operation.
object | The object that is being dragged.
effect | The value that indicates the drag status.


DragProxy Class (com.ms.object.dragdrop Package)

 Microsoft SDK for Java

DragProxy Class

The DragProxy Class of the com.ms.object.dragdrop package provides a DragHandler implementation that forwards calls to another specified DragHandler. Optionally, x and y offsets can be set and retrieved for a DragProxy object.

public class DragProxy implements DragHandler
{
  // Constructors
  public DragProxy();
  public DragProxy(DragHandler handler);
  public DragProxy(DragHandler handler, int xOffset, int yOffset);

  // Methods
  public void dragEnter(DragSession session);
  public void dragLeave();
  public int dragOver(DragSession session, int x, int y);
  public void drop(DragSession session, int x, int y);
  public DragHandler getHandler();
  public Point getOffset();
  public void setHandler(DragHandler handler);
  public void setHandler(DragHandler handler, int xOffset,
        int yOffset);
  public void setOffset(Point offset);
  public void setOffset(int xOffset, int yOffset);
}


Constructors (DragProxy Class)

 Microsoft SDK for Java

DragProxy Class Constructors

The DragProxy Class contains the following constructors:

DragProxy()
DragProxy(DragHandler handler)
DragProxy(DragHandler handler, int xOffset, int yOffset)

DragProxy()

Creates a new DragProxy object.

Syntax

public DragProxy();

DragProxy(DragHandler handler)

Creates a new DragProxy object that has the specified drag handler.

Syntax

public DragProxy(DragHandler handler);

Parameters

handler The drag handler to assign to the DragProxy instance.

DragProxy(DragHandler handler, int xOffset, int yOffset)

Creates a new DragProxy object that has the specified drag handler, x offset, and y offset.

Syntax

public DragProxy(DragHandler handler, int xOffset, int yOffset);

Parameters

handler | The drag handler for the DragProxy object.
xOffset | The x offset for the DragProxy object.
yOffset | The y offset for the DragProxy object.


Methods (DragProxy Class)

 Microsoft SDK for Java

DragProxy Class Methods

The DragProxy Class contains the following methods:

dragEnter notifies the recipient when a source object enters the space defined by a container, window, or object.
dragLeave notifies the recipient when a source object exits the space defined by a container, window, or object.
dragOver notifies the recipient when a source object continues through the space defined by a container, window, or object.
drop notifies the recipient when a source object is dropped at a new location.
getHandler retrieves the drag handler for the DragProxy object.
getOffset retrieves the offset for the DragProxy object.
setHandler sets the drag handler for the DragProxy object.
setOffset sets the x offset and y offset of the DragProxy object based on a specified Point object.


dragEnter (DragProxy Class)

 Microsoft SDK for Java

dragEnter

This method of the DragProxy Class notifies the recipient when a source object enters the space defined by a container, window, or object.

Syntax

public void dragEnter(DragSession session);

arameters

session The DragSession object that represents the current drag operation.


dragLeave (DragProxy Class)

 Microsoft SDK for Java

dragLeave

This method of the DragProxy Class notifies the recipient when a source object exits the space defined by a container, window, or object.

Syntax

public void dragLeave();


dragOver (DragProxy Class)

 Microsoft SDK for Java

dragOver

This method of the DragProxy Class notifies the recipient when a source object continues through the space defined by a container, window, or object.

Syntax

public int dragOver(DragSession session, int x, int y);

Return Value

Returns one or more of the following values:

NONE, COPY, MOVE, or LINK.

Parameters

session | The DragSession object that represents the current drag operation.
x | The x-coordinate of the current cursor position.
y | The y-coordinate of the current cursor position.


drop (DragProxy Class)

 Microsoft SDK for Java

drop

This method of the DragProxy Class notifies the recipient when a source object is dropped at a new location.

Syntax

public void drop(DragSession session, int x, int y);

Parameters

session | The DragSession object that represents the current drag operation.
x | The x-coordinate of the current cursor position.
y | The y-coordinate of the current cursor position.


getHandler (DragProxy Class)

 Microsoft SDK for Java

getHandler

This method of the DragProxy Class retrieves the drag handler for the DragProxy object.

Syntax

public DragHandler getHandler();

Return Value

Returns the drag handler for the DragProxy object.


getOffset (DragProxy Class)

 Microsoft SDK for Java

getOffset

This method of the DragProxy Class retrieves the offset for the DragProxy object.

Syntax

public Point getOffset();

Return Value

Returns the Point object that represents the x offset and y offset of the DragProxy object.


setHandler (DragProxy Class)

 Microsoft SDK for Java

setHandler

The setHandler method of the DragProxy Class contains the following signatures:

setHandler(DragHandler handler)
setHandler(DragHandler handler, int xOffset, int yOffset)

setHandler(DragHandler handler)

Sets the drag handler for the DragProxy object.

Syntax

public void setHandler(DragHandler handler);

Parameters

handler The new handler for the DragProxy object.

setHandler(DragHandler handler, int xOffset, int yOffset)

Sets the drag handler and the x and y offsets for the DragProxy object.

Syntax

public void setHandler(DragHandler handler, int xOffset, int yOffset);

Parameters

handler | The new handler for the DragProxy object.
xOffset | The new x offset for the DragProxy object.
yoffset | The new y offset for the DragProxy object.


setOffset (DragProxy Class)

 Microsoft SDK for Java

setOffset

The setOffset method of the DragProxy Class contains the following signatures:

setOffset(Point offset)
setOffset(int xOffset, int yOffset)

setOffset(Point offset)

Sets the x offset and y offset of the DragProxy object based on a specified Point object.

Syntax

public void setOffset(Point offset);

Parameters

offset The Point object that represents an x offset and y offset.

setOffset(int xOffset, int yOffset)

Sets the x offset and y offset of the DragProxy object.

Syntax

public void setOffset(int xOffset, int yOffset);

Parameters

xOffset | The new value for the x offset.
yOffset | The new value for the y offset.


DragHandler Interface (com.ms.object.dragdrop Package)

 Microsoft SDK for Java

DragHandler Interface

The DragHandler Interface of the com.ms.object.dragdrop package defines methods that handle drag operations relative to other objects.

public interface DragHandler
{
  // Methods
  public void dragEnter(DragSession session);
  public void dragLeave();
  public int dragOver(DragSession session, int x, int y);
  public void drop(DragSession session, int x, int y);
}

A recipient would implement this interface to receive drops from a drag source. There are methods in this interface that notify the recipient when the object has entered, left, moved, or might have been dropped by the user.

To view an example that implements a DragHandler, see the com.ms.object.dragdrop overview.


Methods (DragHandler Interface)

 Microsoft SDK for Java

DragHandler Interface Methods

The DragHandler Interface contains the following methods:

dragEnter notifies the recipient when a source object enters the space that is defined by a container, window, or object.
dragLeave notifies the recipient when a source object exits the space that is defined by a container, window, or object.
dragOver notifies the recipient when a source object continues through the space that is defined by a container, window, or object.
drop notifies the recipient when a source object is dropped at a new location.


dragEnter (DragHandler Interface)

 Microsoft SDK for Java

dragEnter

This method of the DragHandler Interface notifies the recipient when a source object enters the space that is defined by a container, window, or object.

Syntax

public void dragEnter(DragSession session);

Parameters

session The DragSession object that represents the current drag operation.


dragLeave (DragHandler Interface)

 Microsoft SDK for Java

dragLeave

This method of the DragHandler Interface notifies the recipient when a source object exits the space that is defined by a container, window, or object.

Syntax

public void dragLeave();


dragOver (DragHandler Interface)

 Microsoft SDK for Java

dragOver

This method of the DragHandler Interface notifies the recipient when a source object continues through the space that is defined by a container, window, or object.

Syntax

public int dragOver(DragSession session, int x, int y);

Return Value

Returns one or more of the following values:

NONE, COPY, MOVE, or LINK.

Parameters

session | The DragSession object that represents the current drag operation.
x | The x-coordinate of the current cursor position.
y | The y-coordinate of the current cursor position.


drop (DragHandler Interface)

 Microsoft SDK for Java

drop

This method of the DragHandler Interface notifies the recipient when a source object is dropped at a new location.

Syntax

public void drop(DragSession session, int x, int y);

Parameters

session | The DragSession object that represents the current drag operation.
x | The x-coordinate of the current cursor position.
y | The y-coordinate of the current cursor position.


DragSession Interface (com.ms.object.dragdrop Package)

 Microsoft SDK for Java

DragSession Interface

The DragSession Interface of the com.ms.object.dragdrop package defines drag modifiers used with drag-and-drop operations.

public interface DragSession extends TransferSession
{
  // Fields
  public static final int ALT;
  public static final int CONTROL;
  public static final int LBUTTON;
  public static final int MBUTTON;
  public static final int RBUTTON;
  public static final int SHIFT;

  // Methods
  public int getDragModifiers();
}

These constants represent the mouse state and keyboard modifiers such as the CTRL, ALT, and SHIFT keys. In most cases, this interface should be implemented by a class that implements the dragdrop protocol.

Hierarchy

TransferSession  |
  +--DragSession


Methods (DragSession Interface)

 Microsoft SDK for Java

DragSession Interface Methods

The DragSession Interface contains the following method:

getDragModifiers retrieves the drag modifiers for the current drag operation.


getDragModifiers (DragSession Interface)

 Microsoft SDK for Java

getDragModifiers

This method of the DragSession Interface retrieves the drag modifiers for the current drag operation.

Syntax

public int getDragModifiers();

Return Value

Returns any one or a combination of the following modifiers.

LBUTTON, | MBUTTON, | RBUTTON,
CONTROL, | SHIFT, or | ALT.


Fields (DragSession Interface)

 Microsoft SDK for Java

DragSession Interface Fields

The DragSession Interface contains the following fields.

ALT | A drag modifier indicating that the ALT key is pressed.
CONTROL | A drag modifier indicating that the CTRL key is pressed.
LBUTTON | A drag modifier indicating that the left mouse button is pressed.
MBUTTON | A drag modifier indicating that the middle button of a three-button mouse is pressed.
RBUTTON | A drag modifier indicating that the right mouse button is pressed.
SHIFT | A drag modifier indicating that the SHIFT key is pressed.


DragSource Interface (com.ms.object.dragdrop Package)

 Microsoft SDK for Java

DragSource Interface

The DragSource Interface of the com.ms.object.dragdrop package defines constants and methods that can be used by the source object of a dragdrop data transfer session. This interface allows a source object to customize the behavior of a drag operation as it progresses.

public interface DragSource
{
  // Fields
  public static final int CANCEL;
  public static final int CONTINUE;
  public static final int DEFAULT ACTION;
  public static final int DROP;

  // Methods
  public Object queryDragCursor(int effect);
  public int queryDragStatus(int modifiers);
}

The queryDragStatus method can be used to query the current drag status of a dragged object. Drag status depends on whether the source object is able to transfer data from its current location to the current location of the mouse.

The queryDragCursor method retrieves an appropriate cursor for the drag operation, depending on the drag status. The cursor for a drag operation that can transfer the object to the current location is different from a cursor that cannot transfer the object.


Methods (DragSource Interface)

 Microsoft SDK for Java

DragSource Interface Methods

The DragSource Interface contains the following methods:

queryDragCursor retrieves the current effect image used by the cursor as it drags an object across windows and icons.
queryDragStatus determines the current status of the drag operation.


queryDragCursor (DragSource Interface)

 Microsoft SDK for Java

queryDragCursor

This method of the DragSource Interface retrieves the current effect image used by the cursor as it drags an object across windows and icons.

Syntax

public Object queryDragCursor(int effect);

Return Value

Returns a cursor object that reflects the specified effect.

Parameters

effect The effect that the cursor provides an image for. This value can be one of the following drag effects:

CONTINUE, CANCEL, DROP, or DEFAULT ACTION


queryDragStatus (DragSource Interface)

 Microsoft SDK for Java

queryDragStatus

This method of the DragSource Interface determines the current status of the drag operation.

Syntax

public int queryDragStatus(int modifiers);

Return Value

Returns a drag status flag depending on the current status of the drag session. This value can be one or more of the following drag effects:

CONTINUE, CANCEL, DROP, or DEFAULT ACTION

Parameters

modifiers | A flag that indicates the drag modifier for the drag operation. It can be any one of the following drag modifiers:
 | LBUTTON, | MBUTTON, | RBUTTON,
 | CONTROL, | SHIFT, or | ALT.


Fields (DragSource Interface)

 Microsoft SDK for Java

DragSource Interface Fields

The DragSource Interface contains the following fields.

CANCEL | A drag-effect flag that indicates the drag operation has been cancelled.
CONTINUE | A drag-effect flag that indicates the dragged object cannot be dropped, but can continue.
DEFAULT_ACTION | A drag-effect flag that indicates that the system will determine what to do.
DROP | A drag-effect flag that indicates the dragged object can be dropped at the current location.


com.ms.security Package Overview

Microsoft Packages Overview

The com.ms.security package provides access to the security system of the Microsoft virtual machine (Microsoft VM). The security system is based on associating sets of permissions with individual classes so that the Microsoft VM can examine the call stack to determine what permissions are valid in a given context. This discussion includes a Classes Overview and examples.

This package contains the following:

Classes

Interfaces

Hierarchy

Classes Overview

The StandardSecurityManager class implements a granular, permission-based security policy. The StandardSecurityManager is the installed security manager within the Microsoft VM for all Java code (except Java applications), and it processes security checks for the standard Java APIs. The StandardSecurityManager.checkXXX methods call the PolicyEngine.checkPermission methods to do the stack crawl that actually determines whether the specified operation is permitted. For instance, if your code creates a new java.io.FileOutputStream object and then attempts to write to that file, the Microsoft VM calls the StandardSecurityManager's checkWrite method, passing in the name of the file you want to write to. If the security check fails, a SecurityExceptionEx is thrown.

The PolicyEngine class contains methods that check for a particular type of permission, using either a deep or a shallow security check. A deep security check examines the call stack (beginning with the immediate caller to PolicyEngine and working backwards) and determines whether each class on the stack has the specified permission. If any class does not have the specified permission, the security check fails. If the right to the specified permission has been explicitly asserted, the stack crawl terminates immediately and the security check passes. If the right to the specified permission has been explicitly denied, the stack crawl terminates immediately and the security check fails. A shallow security check requires that you specify a skip set that indicates a set of classes to ignore during the security check. During a shallow security check, only the first class found outside the skip set is examined for the specified permission. To learn more about security checks and how to assert, deny, or revert a permission, see the PolicyEngine class.

Each permission class must implement the IPermission interface. Optionally, one or both of the IAdjustablePermission and the IEncodablePermission interfaces can be implemented. If the IAdjustablePermission interface is implemented, a permission object can be adjusted to give context information. For instance, the ThreadPermission class implements IAdjustablePermission. Therefore, a ThreadPermission object can be adjusted to indicate a ThreadGroup object that classes with the ThreadPermission should have access to. If a permission class implements the IEncodablePermission interface, the permission object can encode itself for use in digital signatures. The encoding formats that are supported (HTML, ASN, text, and others) are supplied by constants in the EncodeFormats class.

Permission types are identified by the constants in the PermissionID class. Except for PermissionID.SYSTEM, each constant corresponds to the name of a permission class that implements that type of permission. For instance, the PermissionID.REGISTRY value corresponds to the com.ms.security.permissions.RegistryPermission class. PermissionID objects are passed to the PolicyEngine.checkPermission(PermissionID,Object) methods to indicate the type of permission being checked. If you have designed a custom permission class and need a PermissionID that identifies your new class, you can call the PolicyEngine.permissionNameToID method to create a PermissionID. You can also use permissionNameToID to convert a predefined system permission name to its corresponding PermissionID.

Several of the predefined classes in the com.ms.security.permissions package implement the ISecurityRequest interface. An instance of a class that implements ISecurityRequest represents both a PermissionID and one or more parameters that are relevant to the permission type. To do a parameterized security check for a permission that has a corresponding ISecurityRequest class, you should pass an ISecurityRequest object of the appropriate type to the PolicyEngine.checkPermission(ISecurityRequest) method. The example at the end of this overview shows how to do a parameterized security check using an ISecurityRequest object. To learn more about doing security checks for predefined permissions, see the Using ISecurityRequest Objects To Perform Security Checks section of the com.ms.security.permissions overview. The com.ms.security.permissions overview also provides a list of classes that implement ISecurityRequest.

Permission objects can be grouped into a PermissionSet or a PermissionDataSet. A PermissionSet object is immutable, so you could turn your PermissionDataSet into a PermissionSet to protect your permission objects from modification. However, if you want to enumerate the permissions in the set, they must be in the form of a PermissionDataSet so that you can use the PermissionDataSetEnumerator methods. Similarly, when a set of permissions is ready to be encoded for use in a digital signature, the set must be in the form of a PermissionDataSet object. However, when the permission set is associated with a particular class (using the SecurityClassLoader methods), it should be in PermissionSet form so that it cannot be modified.

The PermissionUtils class supplies a variety of useful methods whose functionality falls into one of three categories.

  • Deep copy helpers to use when implementing IPermission.copy.

  • Comparison helpers to use when implementing SetComparison.compareSet methods.

  • Combine helpers to use when implementing IPermission.combine.

security Examples

The following example illustrates one way to do a parameterized security check for the PropertyPermission that indicates permission to read the java.class.path property:

// Create a request object
PropertyAccessRequest par =
   new PropertyAccessRequest("java.class.path");
PolicyEngine.checkPermission(par);

Suppose you want to create a set of three permissions and mark a new class with those permissions. The following code could be written within a class that extends the SecurityClassLoader class:

// Create the PermissionDataSet.
PermissionDataSet pds = new PermissionDataSet();

// Create a permission object.
PropertyPermission perm1 =
   new PropertyPermission();
perm1.addAllowedProperties("java.*");

// Add the permission to the set.
pds.add(PermissionID.PROPERTY,perm1);

// Create a second permission object.
SystemStreamsPermission perm2 =
   new SystemStreamsPermission();
perm2.setCanSetSystemIn(true);

// Add the second permission to the set.
pds.add(PermissionID.SYSSTREAMS,perm2);

// Create a third permission object.
FileIOPermission perm3 = new FileIOPermission();
perm3.AddReadableFile("MySample.txt",true);
perm3.AddDeleteableFile("Useless.txt",true);

// Add the third permission to the set.
pds.add(PermissionID.FILEIO);

// Convert to a PermissionSet.
PermissionSet permSet = pds.toPermissionSet();

...
// Obtain the Principal  (prince)
// Obtain the class name (classname)
// Obtain the class data (classdata)
...

int len = classdata.length;

// Mark the class with the PermissionSet.
Class cl = defineClass(classname,classdata,0,
                       len,permSet,prince);


Classes (com.ms.security Package)

 Microsoft SDK for Java

com.ms.security Package Classes

The com.ms.security package contains the following classes:

EncodeFormats Class contains values that are used to encode permissions or retrieve information about permissions.

PermissionDataSet Class represents sets of permission objects.

PermissionDataSetEnumerator Class implements an enumeration of the permission identifiers stored within a PermissionDataSet object.

PermissionID Class represents objects that are used to identify permission types.

PermissionRequestDeniedException Class is thrown by a security system component when a security check fails because a permission has been explicitly denied.

PermissionSet Class represents an immutable form of a PermissionDataSet object.

PermissionTreeOutput Class is used to create a tree representation of the permissions.

PermissionUtils Class provides routines used by the permission classes.

PolicyEngine Class exposes methods that perform permission-based security checks.

SecurityClassLoader Class provides methods that associate permissions with classes.

SecurityExceptionEx Class represents security exceptions that are thrown by a component of the security system to indicate a security violation.

StandardSecurityManager Class defines a security policy that uses the permission model to perform security checks.


Interfaces (com.ms.security Package)

 Microsoft SDK for Java

com.ms.security Interfaces

The com.ms.security package contains the following interfaces:

IadjustablePermission Interface provides a method for modifying a permission object to give context information.

IencodablePermission Interface provides methods that allow permissions to represent their internal state in any desired format.

Ipermission Interface must be implemented by all classes that represent permissions.

IsecurityRequest Interface is used to associate specific types of objects with specific permission types.


Hierarchy (com.ms.security Package)

 Microsoft SDK for Java

com.ms.security Hierarchy

The com.ms.security package has the following hierarchy:

Object
  |
  +--EncodeFormats
  |
  +--PermissionDataSet (IEncodablePermission, com.ms.util.SetComparison)
  |
  +--PermissionDataSetEnumerator (Enumeration)
  |
  +--PermissionID
  |
  +--PermissionSet
  |
  +--PermissionUtils
  |
  +--PolicyEngine

ClassLoader
  |
  +--SecurityClassLoader

SecurityException
  |
  +--SecurityExceptionEx
     |
     +--PermissionRequestDeniedException

SecurityManager
  |
  +--StandardSecurityManager

OutputStream
  |
  +--PermissionTreeOutput

IAdjustablePermission

IEncodablePermission

IPermission

ISecurityRequest


EncodeFormats Class (com.ms.security Package)

 Microsoft SDK for Java

EncodeFormats Class

The EncodeFormats Class of the com.ms.security package contains values that are used to encode permissions or retrieve information about permissions.

public class EncodeFormats
{
  // Fields
  public static final String ASN1;
  public static final String DEFAULT;
  public static final String DESCRIPTION;
  public static final String DISPLAY;
  public static final String DISPLAYNAME;
  public static final String DISPLAYTREE;
  public static final String HTML;
  public static final String INI;
  public static final String PICS;
  public static final String TEXT;
  public static final String XML;
}


Fields (EncodeFormats Class)

 Microsoft SDK for Java

EncodeFormats Class Fields

The EncodeFormats Class contains the following fields.

ASN1 | The value that indicates the ASN (Abstract Syntax Notation) format.
DEFAULT | The value that indicates the default format.
DESCRIPTION | A value used to return a description of a permission.
DISPLAY | A value used to return information about a permission.
DISPLAYNAME | A value used for retrieving friendly names (for example, ToolTips text).
DISPLAYTREE | A value used for displaying permissions in tree form in the security dialog box.
HTML | The value that indicates the HTML format.
INI | Reserved.
PICS | Reserved.
TEXT | The value that indicates the text format.
XML | The value that indicates the XML (eXtensible Markup Language) format.


PermissionDataSet Class (com.ms.security Package)

 Microsoft SDK for Java

PermissionDataSet Class

The PermissionDataSet Class of the com.ms.security package represents sets of permission objects.

public class PermissionDataSet implements IEncodablePermission,
             com.ms.util.SetComparison
{
  // Constructors
  public PermissionDataSet();
  public PermissionDataSet(PermissionDataSet other);

  // Methods
  public synchronized boolean add(PermissionID pid,
        IPermission perm);
  public void adjust(String tag, Object adjustment);
  public void adjustForCodebase(URL codebase);
  public void adjustWithReflectionLoader(ClassLoader cl);
  public void adjustWithThreadGroup(ThreadGroup tg);
  public synchronized PermissionDataSet combine(
        PermissionDataSet other);
  public synchronized int compare(PermissionDataSet other);
  public int compareSet(Object other);
  public synchronized PermissionDataSet copy();
  public boolean decode(String tag, InputStream data);
  public PermissionDataSetEnumerator elements();
  public boolean encode (String tag, OutputStream out);
  public synchronized IPermission find(PermissionID pid);
  public boolean isFullyTrusted();
  public String mapFormat(String format);
  public void remove(PermissionID pid);
  public void setFullyTrusted(boolean flag);
  public int size();
  public String[] supportedFormats();
  public synchronized PermissionSet toPermissionSet();
  public String toString();
}

Methods are provided for normal container operations such as insertion, deletion, and enumeration.

While in the PermissionDataSet form, the set can be manipulated freely. However, if the PermissionDataSet is converted to a PermissionSet, the new set cannot be modified.

This class implements the IEncodablePermission and the com.ms.util.SetComparison interfaces.


Constructors (PermissionDataSet Class)

 Microsoft SDK for Java

PermissionDataSet Class Constructors

The PermissionDataSet Class contains the following constructors:

PermissionDataSet()
PermissionDataSet(PermissionDataSet other)

PermissionDataSet()

Creates a new, empty set of permission objects.

Syntax

public PermissionDataSet();

PermissionDataSet(PermissionDataSet other)

Creates a new set of permission objects, based on an existing PermissionDataSet object. The new set will be a copy of the existing set.

Syntax

public PermissionDataSet(PermissionDataSet other);

Parameters

other The existing PermissionDataSet object.


Methods (PermissionDataSet Class)

 Microsoft SDK for Java

PermissionDataSet Class Methods

The PermissionDataSet Class contains the following methods:

add adds a permission to the set.
adjust adjusts each permission in the set with the given parameters.
adjustForCodebase adjusts a PermissionDataSet object to include additional access based on a codebase URL.
adjustWithReflectionLoader adjusts a PermissionDataSet with a class loader that indicates whether reflection access to a given class is allowed.
adjustWithThreadGroup adjusts a PermissionDataSet object to include additional thread access, based on a master thread group.
combine combines the data in the permission set with another permission set, and returns it as a third permission set.
compare compares the permissions in the PermissionDataSet object against the permissions in another set.
compareSet compares the PermissionDataSet object to another set.
copy copies the permission set.
decode decodes the contents of the specified data stream into a set of permission objects.
elements returns an enumeration of the permission types stored within this PermissionDataSet object.
encode encodes the contents of the set of permissions and sends encoded data to the specified stream.
find looks for a specific type of permission in the set.
isFullyTrusted determines whether the state of the permission set is fully trusted.
mapFormat given an encoding type, returns a tag which can then be used to perform encode and decode operations.
remove removes a permission from the set.
setFullyTrusted sets the fully trusted state of the permission set.
size retrieves the number of permissions objects contained in the set.
supportedFormats returns the encoding formats that the PermissionDataSet supports.
toPermissionSet turns the PermissionDataSet into a PermissionSet.
toString converts the contents of the PermissionDataSet object to its textual form.


add (PermissionDataSet Class)

 Microsoft SDK for Java

add

This method of the PermissionDataSet Class adds a permission to the set.

Syntax

public synchronized boolean add(PermissionID pid,IPermission perm);

Return Value

Returns false if a permission of the same type already exists in the set; otherwise, returns true.

Parameters

pid | The permission type.
perm | The permission object.

Remarks

The permission is specified by its type, and an IPermission instance that corresponds to that type must be specified. If a permission of that type already exists in the set, the add operation fails.


adjust (PermissionDataSet Class)

 Microsoft SDK for Java

adjust

This method of the PermissionDataSet Class adjusts each permission in the set with the given parameters.

Syntax

public void adjust(String tag, Object adjustment);

Parameters

tag | The adjustment type.
adjustment | The adjustment-specific object.

Remarks

This method calls the adjustPermission method on all the permission objects in the set that implement the IAdjustablePermission interface.


adjustForCodebase (PermissionDataSet Class)

 Microsoft SDK for Java

adjustForCodebase

This method of the PermissionDataSet Class adjusts a PermissionDataSet object to include additional access based on a codebase URL.

Syntax

public void adjustForCodebase(URL codebase);

Parameters

codebase The URL instance to pass as the second parameter when calling the adjustPermission method on the permission objects.

Remarks

This method calls adjustPermission("codebase",codebase) on all the permission objects in the set that implement the IAdjustablePermission interface.


adjustWithReflectionLoader (PermissionDataSet Class)

 Microsoft SDK for Java

adjustWithReflectionLoader

This method of the PermissionDataSet Class adjusts a PermissionDataSet with a class loader that indicates whether reflection access to a given class is allowed.

Syntax

public void adjustWithReflectionLoader(ClassLoader cl);

Parameters

cl The class loader instance to pass as the second parameter when calling the adjustPermission method on the permission objects.

Remarks

This method calls adjustPermission("classloader",cl) on all the permission objects in the set that implement the IAdjustablePermission interface.


adjustWithThreadGroup (PermissionDataSet Class)

 Microsoft SDK for Java

adjustWithThreadGroup

This method of the PermissionDataSet Class adjusts a PermissionDataSet object to include additional thread access, based on a master thread group.

Syntax

public void adjustWithThreadGroup(ThreadGroup tg);

Parameters

tg The master thread group that is passed as the second parameter when calling the adjustPermission method on the permission objects.

Remarks

This method calls adjustPermission("threadgroup",tg) on all the permission objects in the set that implement the IAdjustablePermission interface.


combine (PermissionDataSet Class)

 Microsoft SDK for Java

combine

This method of the PermissionDataSet Class combines the data in the permission set with another permission set, and returns it as a third permission set.

Syntax

public synchronized PermissionDataSet combine(PermissionDataSet other);

Return Value

Returns a new PermissionDataSet object that contains the combined permissions.

Parameters

other The permission set to combine with the first set.


compare (PermissionDataSet Class)

 Microsoft SDK for Java

compare

This method of the PermissionDataSet Class compares the permissions in the PermissionDataSet object against the permissions in another set.

Syntax

public synchronized int compare(PermissionDataSet other);

Return Value

Returns one of the following com.ms.util.SetComparison result codes:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

other The second permission set to compare against the first.


compareSet (PermissionDataSet Class)

 Microsoft SDK for Java

compareSet

This method of the PermissionDataSet Class compares the PermissionDataSet object to another set.

Syntax

public int compareSet(Object other);

Return Value

Returns one of the following com.ms.util.SetComparison result codes:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

other The object that the PermissionDataSet object is being compared with.


copy (PermissionDataSet Class)

 Microsoft SDK for Java

copy

This method of the PermissionDataSet Class copies the permission set.

Syntax

public synchronized PermissionDataSet copy();

Return Value

Returns a copy of the set.


decode (PermissionDataSet Class)

 Microsoft SDK for Java

decode

This method of the PermissionDataSet Class decodes the contents of the specified data stream into a set of permission objects.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding process is completed successfully; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct this object from. The type of data in the stream is specified by the tag parameter.


elements (PermissionDataSet Class)

 Microsoft SDK for Java

elements

This method of the PermissionDataSet Class returns an enumeration of the permission types stored within this PermissionDataSet object. This method calls the constructor for the PermissionDataSetEnumerator class.

Syntax

public PermissionDataSetEnumerator elements();

Return Value

Returns the enumeration object.


encode (PermissionDataSet Class)

 Microsoft SDK for Java

encode

This method of the PermissionDataSet Class encodes the contents of the set of permissions and sends encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding process is completed successfully; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The stream to write the encoded data to.


find (PermissionDataSet Class)

 Microsoft SDK for Java

find

This method of the PermissionDataSet Class looks for a specific type of permission in the set.

Syntax

public synchronized IPermission find(PermissionID pid);

Return Value

Returns the permission object, if one is found; otherwise, returns null.

Parameters

pid The type of permission to find.


isFullyTrusted (PermissionDataSet Class)

 Microsoft SDK for Java

isFullyTrusted

This method of the PermissionDataSet Class determines whether the state of the permission set is fully trusted.

Syntax

public boolean isFullyTrusted();

Return Value

Returns true if the permission set is fully trusted; otherwise, returns false.


mapFormat (PermissionDataSet Class)

 Microsoft SDK for Java

mapFormat

This method of the PermissionDataSet Class given an encoding type, returns a tag which can then be used to perform encode and decode operations.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag for the specified encoding format. If the specified format is not supported, null is returned.

Parameters

format The requested encoding format.


remove (PermissionDataSet Class)

 Microsoft SDK for Java

remove

This method of the PermissionDataSet Class removes a permission from the set. If a permission of the specified type exists within the permission set, this method removes it.

Syntax

public void remove(PermissionID pid);

Parameters

pid The type of permission to remove.


setFullyTrusted (PermissionDataSet Class)

 Microsoft SDK for Java

setFullyTrusted

This method of the PermissionDataSet Class sets the fully trusted state of the permission set. If the flag parameter is true, the set is put in the special "fully trusted" state, and it is considered to contain all possible permissions.

Syntax

public void setFullyTrusted(boolean flag);

Parameters

flag The value that indicates how to set the state. If the value is true, the state will be set to fully trusted. If the value is false, the state will no longer be set to fully trusted.


size (PermissionDataSet Class)

 Microsoft SDK for Java

size

This method of the PermissionDataSet Class retrieves the number of permissions objects contained in the set.

Syntax

public int size();

Return Value

Returns the number of permission objects in the set.


supportedFormats (PermissionDataSet Class)

 Microsoft SDK for Java

supportedFormats

This method of the PermissionDataSet Class returns the encoding formats that the PermissionDataSet supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array that contains identifiers for the supported formats.


toPermissionSet (PermissionDataSet Class)

 Microsoft SDK for Java

toPermissionSet

This method of the PermissionDataSet Class turns the PermissionDataSet into a PermissionSet. The PermissionSet form is immutable and can no longer be modified.

Syntax

public synchronized PermissionSet toPermissionSet();

Return Value

Returns the PermissionSet object that is an immutable form of the PermissionDataSet object.


toString (PermissionDataSet Class)

 Microsoft SDK for Java

toString

This method of the PermissionDataSet Class converts the contents of the PermissionDataSet object to its textual form.

Syntax

public String toString();

Return Value

Returns the textual form of the permission data set.


PermissionDataSetEnumerator Class (com.ms.security Package)

 Microsoft SDK for Java

PermissionDataSetEnumerator Class

The PermissionDataSetEnumerator Class of the com.ms.security package implements an enumeration of the permission identifiers stored within a PermissionDataSet object. To acquire a PermissionDataSetEnumerator object for a particular PermissionDataSet, call the PermissionDataSet.elements method.

public class PermissionDataSetEnumerator implements Enumeration
{
  // Methods
  public boolean hasMoreElements();
  public boolean hasMorePermissionIDs();
  public Object nextElement();
  public PermissionID nextPermissionID();
}

See Also

com.ms.security.PermissionDataSet


Methods (PermissionDataSetEnumerator Class)

 Microsoft SDK for Java

PermissionDataSetEnumerator Class Methods

The PermissionDataSetEnumerator Class contains the following methods:

hasMoreElements determines whether the enumeration contains additional elements.
hasMorePermissionIDs determines whether the enumeration contains additional PermissionID objects.
nextElement retrieves the next PermissionID from the enumeration.
nextPermissionID retrieves the next PermissionID object from the enumeration.


hasMoreElements (PermissionDataSetEnumerator Class)

 Microsoft SDK for Java

hasMoreElements

This method of the PermissionDataSetEnumerator Class determines whether the enumeration contains additional elements. This method implements the java.util.Enumeration.hasMoreElements method.

Syntax

public boolean hasMoreElements();

Return Value

Returns true if the enumeration contains additional elements; otherwise, returns false.


hasMorePermissionIDs (PermissionDataSetEnumerator Class)

 Microsoft SDK for Java

hasMorePermissionIDs

This method of the PermissionDataSetEnumerator Class determines whether the enumeration contains additional PermissionID objects.

Syntax

public boolean hasMorePermissionIDs();

Return Value

Returns true if the enumeration contains additional PermissionID objects; otherwise, returns false.


nextElement (PermissionDataSetEnumerator Class)

 Microsoft SDK for Java

nextElement

This method of the PermissionDataSetEnumerator Class retrieves the next PermissionID from the enumeration. This method implements the java.util.Enumeration.nextElement method.

Syntax

public Object nextElement();

Return Value

Returns the next PermissionID object from the enumeration.

Exceptions

java.util.NoSuchElementException if no more PermissionID objects exist in the enumeration.


nextPermissionID (PermissionDataSetEnumerator Class)

 Microsoft SDK for Java

nextPermissionID

This method of the PermissionDataSetEnumerator Class retrieves the next PermissionID object from the enumeration.

Syntax

public PermissionID nextPermissionID();

Return Value

Returns the next PermissionID object from the enumeration.

Exceptions

java.util.NoSuchElementException if no more PermissionID objects exist in the enumeration.


PermissionID Class (com.ms.security Package)

 Microsoft SDK for Java

PermissionID Class

The PermissionID Class of the com.ms.security package represents objects that are used to identify permission types.

public final class PermissionID
{
  // Fields
  public final static PermissionID CLIENTSTORE;
  public final static PermissionID EXEC;
  public final static PermissionID FILEIO;
  public final static PermissionID MULTIMEDIA;
  public final static PermissionID NETIO;
  public final static PermissionID PRINTING;
  public final static PermissionID PROPERTY;
  public final static PermissionID REFLECTION;
  public final static PermissionID REGISTRY;
  public final static PermissionID SECURITY;
  public final static PermissionID SYSSTREAMS;
  public final static PermissionID SYSTEM;
  public final static PermissionID THREAD;
  public final static PermissionID UI;
  public final static PermissionID USERFILEIO;

  // Methods
  public String toString();
}

The members of this class are constants that represent and identify standard system permissions.

Since there is no public constructor for this class, PermissionID objects cannot be directly created. Instead, they can be retrieved using the PolicyEngine.permissionNameToID method.

Some security APIs allow you to pass the name of the permission instead of a PermissionID object. However, the APIs that take a PermissionID object are usually faster than the variations that take permission names. This is because the APIs that take a permission name must first look up the name to map it to the corresponding PermissionID object.


Methods (PermissionID Class)

 Microsoft SDK for Java

PermissionID Class Methods

The PermissionID Class contains the following method:

toString converts the permission identifier to its string representation.


toString (PermissionID Class)

 Microsoft SDK for Java

toString

This method of the PermissionID Class converts the permission identifier to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the permission identifier.


Fields (PermissionID Class)

 Microsoft SDK for Java

PermissionID Class Fields

The PermissionID Class contains the following fields.

CLIENTSTORE | The permission identifier representing the permission type that controls access to the client storage APIs. This identifier corresponds to the permission implementation in the com.ms.security.permissions.ClientStoragePermission class.
EXEC | The permission identifier representing the permission type that controls the ability to execute applications. This identifier corresponds to the permission implementation in the com.ms.security.permissions.ExecutionPermission class.
FILEIO | A permission identifier representing the permission type that controls the ability to perform file I/O operations. This identifier corresponds to the permission implementation in the com.ms.security.permissions.FileIOPermission class.
MULTIMEDIA | This identifier corresponds to the permission implementation in the com.ms.security.permissions.MultimediaPermission class.
NETIO | The permission identifier representing the permission type that controls networking operations. This identifier corresponds to the permission implementation in the com.ms.security.permissions.NetIOPermission class.
PRINTING | The permission identifier representing the permission type that controls the ability to use the printing APIs. This identifier corresponds to the permission implementation in the com.ms.security.permissions.PrintingPermission class.
PROPERTY | The permission identifier representing the permission type that controls access to the system properties. This identifier corresponds to the permission implementation in the com.ms.security.permissions.PropertyPermission class.
REFLECTION | The permission identifier representing the permission type that controls the ability to use the reflection APIs. This identifier corresponds to the permission implementation in the com.ms.security.permissions.ReflectionPermission class.
REGISTRY | The permission identifier representing the permission type that controls access to the system registry. This identifier corresponds to the permission implementation in the com.ms.security.permissions.RegistryPermission class.
SECURITY | The permission identifier representing the permission type that controls access to the JDK security APIs. This identifier corresponds to the permission implementation in the com.ms.security.permissions.SecurityPermission class.
SYSSTREAMS | The permission identifier representing the permission type that controls the ability to set the system streams. This identifier corresponds to the permission implementation in the com.ms.security.permissions.SystemStreamsPermission class.
SYSTEM | A special permission identifier that represents all possible permissions. This identifier does not correspond to a specific permission class.
THREAD | The permission identifier representing the permission type that controls threading operations. This identifier corresponds to the permission implementation in the com.ms.security.permissions.ThreadPermission class.
UI | The permission identifier representing the permission type that controls access to extended AWT functionality. This identifier corresponds to the permission implementation in the com.ms.security.permissions.UIPermission class.
USERFILEIO | The permission identifier representing the permission type that controls access to user-directed file I/O. This identifier corresponds to the permission implementation in the com.ms.security.permissions.UserFileIOPermission class.


PermissionRequestDeniedException Class (com.ms.security Package)

 Microsoft SDK for Java

PermissionRequestDeniedException Class

The PermissionRequestDeniedException Class of the com.ms.security package represents a security exception that is thrown by a component of the security system when a security check fails because a permission has been explicitly denied.

public class PermissionRequestDeniedException extends SecurityExceptionEx
{
  // Constructors
  public PermissionRequestDeniedException();
  public PermissionRequestDeniedException(String detail);
}

Permissions are explicitly denied using the PolicyEngine.denyPermission method. This class extends the SecurityExceptionEx class.

Hierarchy

SecurityException
  |
  +--SecurityExceptionEx
    |
    +--PermissionRequestDeniedException


Constructors (PermissionRequestDeniedException Class)

 Microsoft SDK for Java

PermissionRequestDeniedException Class Constructors

The PermissionRequestDeniedException Class contains the following constructors:

PermissionRequestDeniedException()
PermissionRequestDeniedException(String detail)

PermissionRequestDeniedException()

Creates an instance of PermissionRequestDeniedException.

Syntax

public PermissionRequestDeniedException();

PermissionRequestDeniedException(String detail)

Creates an instance of PermissionRequestDeniedException with the specified detail description.

Syntax

public PermissionRequestDeniedException(String detail);

Parameters

detail The detail description that describes the error.


PermissionSet Class (com.ms.security Package)

 Microsoft SDK for Java

PermissionSet Class

The PermissionSet Class of the com.ms.security package represents an immutable form of a PermissionDataSet object.

public final class PermissionSet
{
  // Constructors
  public PermissionSet(PermissionDataSet pds);

  // Methods
  public PermissionDataSet getPermissions();
}

After a PermissionDataSet object has been converted to a PermissionSet object, the contents of the permission set can no longer be modified.

The SecurityClassLoader.defineClass method, which attaches a set of permissions to a class, requires a PermissionSet as one of its parameters.


Constructors (PermissionSet Class)

 Microsoft SDK for Java

PermissionSet Class Constructors

The PermissionSet Class contains the following constructor:

PermissionSet(PermissionDataSet pds)

Creates a PermissionSet object from a PermissionDataSet object. The contents of the PermissionDataSet object are copied to the PermissionSet so that any future changes to the PermissionDataSet will not affect the PermissionSet.

Syntax

public PermissionSet(PermissionDataSet pds);

Parameters

pds The PermissionDataSet to copy.


Methods (PermissionSet Class)

 Microsoft SDK for Java

PermissionSet Class Methods

The PermissionSet Class contains the following method:

getPermissions copies the contents of the PermissionSet, and then returns it as a PermissionDataSet that can be examined and modified.


getPermissions (PermissionSet Class)

 Microsoft SDK for Java

getPermissions

This method of the PermissionSet Class copies the contents of the PermissionSet, and then returns it as a PermissionDataSet that can be examined and modified. Any changes to the resulting PermissionDataSet will not affect the original PermissionSet.

Syntax

public PermissionDataSet getPermissions();

Return Value

Returns a copy of the contents of the PermissionSet as a PermissionDataSet.


PermissionTreeOutput Class (com.ms.security Package)

 Microsoft SDK for Java

PermissionTreeOutput Class

The PermissionTreeOutput Class of the com.ms.security package is used to create a tree representation of the permissions.

public class PermissionTreeOutput extends OutputStream
{
  // Constructors
  public PermissionTreeOutput();

  // Methods
  public void addField();
  public void addNode(int level);
  public void addPermission(int level, IPermission perm);
  public void addPermission(int level, IPermission perm,
        boolean highRisk);
  public int count();
  public void setStartLevel(int sl);
  public int startLevel();
  public String toString();
  public void writeField(String s) throws IOException;
  public void writeNode(String s, int level) throws IOException;
  public void writePermission(String s, int level,
        IPermission perm) throws IOException;
  public void writePermission(String s, int level,
        IPermission perm, boolean highRisk) throws IOException;
}

In the security dialog boxes for Microsoft® Internet Explorer version 4.01, the permissions are displayed in the form of a tree control decorated with icons that indicate risk factors.

This class is used with the IEncodablePermission.encode method and the EncodeFormats.DISPLAYTREE format. To be displayed correctly in the security dialog boxes, a permission must be able to handle the EncodeFormat.DISPLAYTREE encoding type. The method that encodes the permission in DISPLAYTREE format should ensure that the OutputStream that receives the encoding is an instance of PermissionTreeOutput. Then the writePermission, writeNode, and writeField methods can be used to display information about the permission.

For instance, to add a title node for displaying the permission, you would use one of the writePermission methods. To add a sub-node heading for grouping related permission parameters, use the writeNode method. To add a leaf node that contains a specific parameter value, use the writeField method.

Example

The code produces the tree as displayed in the following example. For brevity, only the mapFormat and encode methods are shown. However, your class would need to implement all the methods of the IEncodablePermission and IPermission interfaces.

public class MyPermission implements IPermission, IEncodablePermission
{
  private String treedisplaytag = "someString";
  private boolean param1;
  private int param2;
  private String param3;

  // Methods and data members are omitted for brevity.

  // Map the supported formats to tags.
  public String mapFormat(String format)
  {
    if (format == EncodeFormats.DISPLAYTREE)
      return treedisplaytag;

    // else check to see if format represents
    // another supported format.
    ...
  }

  // Encode the permission to a supported format.
  public boolean encode(String tag, OutputStream myStream)
  {
    if (tag.equals(treedisplaytag))
    {
      return encodeTreeDisplay(myStream);
    }

    // else check to see if the tag indicates
    // another supported encoding.
    ...
  }

  // Encode the permission to the DISPLAYTREE format.
  boolean encodeTreeDisplay(OutputStream myStream)
  {
    if(myStream instanceof PermissionTreeOutput)
    {
      PermissionTreeOutput tree = (PermissionTreeOutput) myStream;
      treeDisplay(tree);
      return true;
    }
    else return false;
  }

  // Write information to the tree.
  void treeDisplay(PermissionTreeOutput treeDisplay)
  {
    treeDisplay.writePermission("My Sample Permission", 0, this);
    treeDisplay.writeNode("Parameter 1", 1);
    treeDisplay.writeField("this.param1");
    treeDisplay.writeNode("Parameter 2", 1);
    treeDisplay.writeNode("Sub-Param 2", 2);
    treeDisplay.writeField("this.param2");
    treeDisplay.writeNode("Parameter 3", 1);
    .
    .
    .
  }
}

The displayed tree:

+--+ My Sample Permission
   |
   +--+ Parameter 1
   |  |
   |  +--- X (the value of param1)
   |
   +--+ Parameter 2
   |  |
   |  +--+ Sub-Param 2
   |     |
   |     +--- Y (the value of sub-param2)
   |
   +--+ Parameter 3
   .
   .
   .

See Also

com.ms.security.IEncodablePermission

Hierarchy

OutputStream
  |
  +--PermissionTreeOutput


Constructors (PermissionTreeOutput Class)

 Microsoft SDK for Java

PermissionTreeOutput Class Constructors

The PermissionTreeOutput Class contains the following constructor:

PermissionTreeOutput()

Creates a new PermissionTreeOutput stream.

Syntax

public PermissionTreeOutput();


Methods (PermissionTreeOutput Class)

 Microsoft SDK for Java

PermissionTreeOutput Class Methods

The PermissionTreeOutput Class contains the following methods:

addField creates a leaf in the tree for displaying permission parameters.
addNode creates a new node for displaying a header for permission data.
addPermission inserts a node for the specified permission and assigns it a risk value based on the default permission set.
count retrieves the number of elements in the tree.
setStartLevel sets the depth of the root node. Use this method when combining two (or more) separate trees into one tree.
startLevel retrieves the starting level of the root node.
toString converts the display tree to a String where the nodes and values are delimited by tabs and newline characters.
writeField creates a leaf with the specified string as its value.
writeNode creates a node with the specified string as the name for a new node in the display tree.
writePermission creates a node with the specified string as the name for a new permission in the display tree.


addField (PermissionTreeOutput Class)

 Microsoft SDK for Java

addField

This method of the PermissionTreeOutput Class creates a leaf in the tree for displaying permission parameters.

Syntax

public void addField();


addNode (PermissionTreeOutput Class)

 Microsoft SDK for Java

addNode

This method of the PermissionTreeOutput Class creates a new node for displaying a header for permission data.

Syntax

public void addNode(int level);

Parameters

level The depth of the tree at which to place the node.


addPermission (PermissionTreeOutput Class)

 Microsoft SDK for Java

addPermission

The addPermission method of the PermissionTreeOutput Class contains the following signatures:

addPermission(int level, IPermission perm)
addPermission(int level, IPermission perm, boolean highRisk)

addPermission(int level, IPermission perm)

Inserts a node for the specified permission and assigns it a risk value based on the default permission set.

Syntax

public void addPermission(int level, IPermission perm);

Parameters

level | The depth of the tree at which to place the node.
perm | The permission that is being displayed at the current node.

addPermission(int level, IPermission perm, boolean highRisk)

Inserts a node for the specified permission. If the permission is not explicitly high risk, it is checked against the default sets to determine the risk factor.

Syntax

public void addPermission(int level, IPermission perm, boolean highRisk);

Parameters

level | The depth of the tree at which to place the node.
perm | The permission that is being displayed at the current node.
highRisk | Specifies whether this permission should be flagged as high risk.


count (PermissionTreeOutput Class)

 Microsoft SDK for Java

count

This method of the PermissionTreeOutput Class retrieves the number of elements in the tree.

Syntax

public int count();

Return Value

Returns the number of elements in the tree.


setStartLevel (PermissionTreeOutput Class)

 Microsoft SDK for Java

setStartLevel

This method of the PermissionTreeOutput Class sets the depth of the root node. Use this method when combining two (or more) separate trees into one tree.

Syntax

public void setStartLevel(int sl);

Parameters

sl The depth of the root node.


startLevel (PermissionTreeOutput Class)

 Microsoft SDK for Java

startLevel

This method of the PermissionTreeOutput Class retrieves the starting level of the root node.

Syntax

public int startLevel();

Return Value

Returns the depth of the root node.


toString (PermissionTreeOutput Class)

 Microsoft SDK for Java

toString

This method of the PermissionTreeOutput Class converts the display tree to a String where the nodes and values are delimited by tabs and newline characters.

Syntax

public String toString();

Return Value

Returns a formatted text version of the tree.


writeField (PermissionTreeOutput Class)

 Microsoft SDK for Java

writeField

This method of the PermissionTreeOutput Class creates a leaf with the specified string as its value.

Syntax

public void writeField(String s) throws IOException;

Parameters

s The value to display at the leaf that is created.

Exceptions

IOException if an error occurs while writing to the output stream.


writeNode (PermissionTreeOutput Class)

 Microsoft SDK for Java

writeNode

This method of the PermissionTreeOutput Class creates a node with the specified string as the name for a new node in the display tree.

Syntax

public void writeNode(String s, int level) throws IOException;

Parameters

s | The name of the node.
level | The depth of the tree at which to place the node.

Exceptions

IOException if an error occurs while writing to the output stream.


writePermission (PermissionTreeOutput Class)

 Microsoft SDK for Java

writePermission

The writePermission method of the PermissionTreeOutput Class contains the following signatures:

writePermission(String s, int level, IPermission perm)
writePermission(String s, int level, IPermission perm, boolean highRisk)

writePermission(String s, int level, IPermission perm)

Creates a node with the specified string as the name for a new permission in the display tree.

Syntax

public void writePermission(String s, int level, IPermission perm) throws IOException;

Parameters

s | The name of the permission.
level | The depth of the tree at which to place the node.
perm | The permission that is being displayed at the current node.

Exceptions

IOException if an error occurs while writing to the output stream.

writePermission(String s, int level, IPermission perm, boolean highRisk)

Creates a node with the specified string as the name for a new permission in the display tree. In addition, the permission can be flagged as high risk.

Syntax

public void writePermission(String s, int level, IPermission perm, boolean highRisk) throws IOException;

Parameters

s | The name of the permission.
level | The depth of the tree at which to place the node.
perm | The permission that is being displayed at the current node.
highRisk | Specifies whether this permission should be flagged as high risk.

Exceptions

IOException if an error occurs while writing to the output stream.


PermissionUtils Class (com.ms.security Package)

 Microsoft SDK for Java

PermissionUtils Class

The PermissionUtils Class of the com.ms.security package provides routines used by the permission classes.

public class PermissionUtils
{
  // Methods
  public static String ArraytoString(Object o);
  public static IntRanges[] combineArraysOfIntRanges(
        IntRanges[] r1, IntRanges[] r2);
  public static String[] combineArraysOfStrings(String[] list1,
        String[] list2);
  public static WildcardExpression combinePatterns(
        WildcardExpression spec1, WildcardExpression spec2);
  public static Vector combineVectorsOfIntRanges(Vector v1, Vector
        v2);
  public static int compareArraysOfStrings(String[] list1,
        String[] list2, int cmp);
  public static int compareBooleans(boolean f1, boolean f2,
        int prevcmp);
  public static int compareFlags(int flags1, int flags2, int mask,
        int prevcmp);
  public static int compareIncludeExcludePatterns(
        WildcardExpression include1, WildcardExpression exclude1,
        WildcardExpression include2, WildcardExpression exclude2,
        int cmp );
  public static int compareInclusiveBooleans(boolean f1,
        boolean f2, int prevcmp);
  public static int compareInclusiveFlags(int flags1, int flags2,
        int mask, int prevcmp);
  public static int compareLimits(long limit1, long limit2,
        int prevcmp);
  public static String ComparisonResulttoString(int cmp);
  public static Vector concatVectors(Vector v1, Vector v2);
  public static IntRanges[] copyArrayOfIntRanges(IntRanges[] ap);
  public static Vector[] copyArrayOfVectorsOfIntRanges(
        Vector[] av);
  public static WildcardExpression[] copyArrayOfWildcardExpressions
        (WildcardExpression[] ap);
  public static Vector copyVectorOfIntRanges(Vector v);
  public static int invertComparisonResult(int cmp);
  public static int mergeComparisonResults(int cmp1, int cmp2);
  public static String[] parseStringIntoArray(String str,
        String delims);
}

The PermissionUtils class includes several methods that assist with copying, comparing, and combining assorted types of elements of permissions. Three categories of functions describe the methods in this class:

  • Deep copy helpers for implementing IPermission.copy. The object returned is completely independent of the original, and changes made to the original or to the copy will not affect the other. In other words, containers return a new container, containing a clone of each element; elements that are containers recursively copy their elements.

  • Comparison helpers for implementing compareSet. These helper methods include methods for comparing simple types and String arrays. The mergeComparisonResults method is also included for combining the results for individual aspects of a permission into a single result for the entire permission.

  • Combining helpers for implementing IPermission.combine. With one exception, which is the concatVectors method, all of these methods return the concatenation of deep copies of two objects.


Methods (PermissionUtils Class)

 Microsoft SDK for Java

PermissionUtils Class Methods

The PermissionUtils Class contains the following methods:

ArraytoString recursively constructs a string representation for an array of any type and for each of its elements.
combineArraysOfIntRanges copies two arrays of IntRanges into a new array.
combineArraysOfStrings copies two arrays of strings into a new list.
combinePatterns combines two WildcardExpression objects.
combineVectorsOfIntRanges combines two vectors containing IntRanges objects.
compareArraysOfStrings compares two arrays of strings.
compareBooleans compares two booleans.
compareFlags compares two sets of flags.
compareIncludeExcludePatterns compares sets of resources specified by include/exclude patterns.
compareInclusiveBooleans compares two booleans that represent inclusive access to resources.
compareInclusiveFlags compares two sets of flags that represent inclusive access to resources.
compareLimits compares two positive numerical limits.
ComparisonResulttoString converts com.ms.util.SetComparison results to a string format.
concatVectors combines two vectors by copying their contents into a new Vector.
copyArrayOfIntRanges returns a deep copy of an array of IntRanges objects.
copyArrayOfVectorsOfIntRanges returns a deep copy of an array of Vectors containing IntRanges objects.
copyArrayOfWildcardExpressions returns a deep copy of an array of WildcardExpressions.
copyVectorOfIntRanges returns a deep copy of a vector of IntRanges objects.
invertComparisonResult inverts comparison results.
mergeComparisonResults merges the comparison results from SetComparison.compareSet of two different sets into one, as though they were part of the same set.
parseStringIntoArray splits a string into an array of strings at the specified delimiters.


ArraytoString (PermissionUtils Class)

 Microsoft SDK for Java

ArraytoString

This method of the PermissionUtils Class recursively constructs a string representation for an array of any type and for each of its elements.

Syntax

public static String ArraytoString(Object o);

Return Value

Returns a string representation of the specified array.

Parameters

o The array to construct the string representation of. The component type can be any class type or any primitive type.

Exceptions

IllegalArgumentException if the specified object is not an array.


combineArraysOfIntRanges (PermissionUtils Class)

 Microsoft SDK for Java

combineArraysOfIntRanges

This method of the PermissionUtils Class copies two arrays of IntRanges into a new array. The elements are copied using IntRanges.copy.

Syntax

public static IntRanges[] combineArraysOfIntRanges(IntRanges[] r1, IntRanges[] r2);

Return Value

Returns a new array containing copies of the elements of r1, followed by copies of the elements of r2.

Parameters

r1 | The first array of IntRanges, or null.
r2 | The second array of IntRanges, or null.


combineArraysOfStrings (PermissionUtils Class)

 Microsoft SDK for Java

combineArraysOfStrings

This method of the PermissionUtils Class copies two arrays of strings into a new list. The strings in list1 are copied first into the new list, followed by the strings in list2.

Syntax

public static String[] combineArraysOfStrings(String[] list1, String[] list2);

Return Value

Returns a new list containing copies of the strings in list1, followed by copies of the strings in list2.

Parameters

list1 | The first list of strings, or null.
list2 | The second list of strings, or null.


combinePatterns (PermissionUtils Class)

 Microsoft SDK for Java

combinePatterns

This method of the PermissionUtils Class combines two WildcardExpression objects. The resulting expression will first match any strings that are matched by the first expressions, followed by the strings matched by the second expression. The combined expression is independent of the original expressions; changes to the combined expression will not affect the originals and vice versa.

Syntax

public static WildcardExpression combinePatterns(WildcardExpression spec1, WildcardExpression spec2);

Return Value

Returns a new expression, matching any strings matched by spec1 or spec2, in that order.

Parameters

spec1 | The first source expression to combine, or null.
spec2 | The second source expression to combine, or null.


combineVectorsOfIntRanges (PermissionUtils Class)

 Microsoft SDK for Java

combineVectorsOfIntRanges

This method of the PermissionUtils Class combines two vectors containing IntRanges objects.

Syntax

public static Vector combineVectorsOfIntRanges(Vector v1, Vector v2);

Return Value

Returns a new vector containing the elements of v1, followed by the elements of v2.

Parameters

v1 | The first Vector of IntRanges, or null.
v2 | The second Vector of IntRanges, or null.


compareArraysOfStrings (PermissionUtils Class)

 Microsoft SDK for Java

compareArraysOfStrings

This method of the PermissionUtils Class compares two arrays of strings.

Syntax

public static int compareArraysOfStrings(String[] list1, String[] list2, int cmp);

Return Value

Returns a new comparison result, merged with the specified previous comparison result using mergeComparisonResults.

Parameters

list1 | The first list of strings, or null.
list2 | The second list of strings, or null.
cmp | A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.


compareBooleans (PermissionUtils Class)

 Microsoft SDK for Java

compareBooleans

This method of the PermissionUtils Class compares two booleans. Each boolean represents access to resources that are independent of the other resources of the permissions.

Syntax

public static int compareBooleans(boolean f1, boolean f2, int prevcmp);

Return Value

Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.

Boolean Comparisons

f1 | f2 | Result before merging
true | true | SetComparison.EQUAL
true | false | SetComparison.EMPTY_SUPERSET
false | true | SetComparison.EMPTY_SUBSET
false | false | SetComparison.EMPTY

Parameters

f1 | If true, access to the resource in the first permission is granted; otherwise, access is denied.
f2 | If true, access to the resource in the second permission is granted; otherwise, access is denied.
prevcmp | A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.


compareFlags (PermissionUtils Class)

 Microsoft SDK for Java

compareFlags

This method of the PermissionUtils Class compares two sets of flags. Each flag represents access to resources that are independent of other resources of the permissions. The flags to be compared are selected by a bitmask and are compared as a unit.

Syntax

public static int compareFlags(int flags1, int flags2, int mask, int prevcmp);

Return Value

Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.

Flag Comparisons

flags1 & mask | flags2 & mask | Result before merging
nonzero | nonzero | SetComparison.EQUAL
nonzero | zero | SetComparison.EMPTY_SUPERSET
zero | nonzero | SetComparison.EMPTY_SUBSET
zero | zero | SetComparison.EMPTY

Parameters

flags1 | The flags that determine access to resources in the first permission.
flags2 | The flags that determine access to resources in the second permission.
mask | A bitmask that is combined with the flags (using the logical AND operator (&)) to determine which resources are to be compared as a unit.
prevcmp | A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.


compareIncludeExcludePatterns (PermissionUtils Class)

 Microsoft SDK for Java

compareIncludeExcludePatterns

This method of the PermissionUtils Class compares sets of resources specified by include/exclude patterns. The include pattern specifies resources for which access will be granted, and the exclude rules specify resources that are to be excluded from the include rules.

Syntax

public static int compareIncludeExcludePatterns(WildcardExpression include1, WildcardExpression exclude1, WildcardExpression include2, WildcardExpression exclude2, int cmp);

Include/Exclude Pair Comparisons

Pair 1 | Pair 2 | Result
include * | include * | SUBSET
exclude *.txt |  |
include * | include *.doc | SUPERSET
exclude *.txt |  |
include * | include * | OVERLAP
exclude *.txt | exclude *.doc |
include * | include * | SUBSET
exclude *.txt | exclude MyText.txt |
include * | include *.txt | DISJOINT
exclude *.txt |  |

Return Value

Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.

Parameters

include1 | For the first permission, the patterns that specify resources to grant access to, or null.
exclude1 | For the first permission, the patterns that specify resources to exclude from the include rules.
include2 | For the second permission, the patterns that specify resources to grant access to.
exclude2 | For the second permission, the patterns that specify resources to exclude from the include rules.
cmp | A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.

Exceptions

IllegalArgumentException if any of the exclude rules are not a subset of one or more of the include rules, or if the exclude rules are specified without the include rules.


compareInclusiveBooleans (PermissionUtils Class)

 Microsoft SDK for Java

compareInclusiveBooleans

This method of the PermissionUtils Class compares two booleans that represent inclusive access to resources. A boolean value of false means that access to resources can be granted; a value of true means that more resources will be granted. Typically, this comparator is used only when the possession of the permission itself has meaning, because it becomes impossible to determine DISJOINT or EMPTY permissions after use of this comparator.

Syntax

public static int compareInclusiveBooleans(boolean f1, boolean f2, int prevcmp);

Return Value

Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.

Boolean Comparisons

f1 | f2 | Result before merging
true | true | SetComparison.EQUAL
true | false | SetComparison.SUPERSET
false | true | SetComparison.SUBSET
false | false | SetComparison.EQUAL

Parameters

f1 | A flag that specifies the type of access to the resource in the first permission. If false, access to the resource is not denied; if true, more privileged access to the resource is granted.
f2 | A flag that specifies the type of access to the resource in the second permission. If false, access to the resource is not denied; if true, more privileged access to the resource is granted.
prevcmp | A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.


compareInclusiveFlags (PermissionUtils Class)

 Microsoft SDK for Java

compareInclusiveFlags

This method of the PermissionUtils Class compares two sets of flags that represent inclusive access to resources. The flags to be compared are selected by a bitmask and are compared as a unit. A clear flag means that access to resources can be granted; a set flag means that more resources will be granted. Typically, this comparator is only used when the possession of the permission itself has meaning, because it becomes impossible to determine DISJOINT or EMPTY permissions after use of this comparator.

Syntax

public static int compareInclusiveFlags(int flags1, int flags2, int mask, int prevcmp);

Return Value

Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.

Flag Comparisons

flags1 & mask | flags2 & mask | Result before merging
nonzero | nonzero | SetComparison.EQUAL
nonzero | zero | SetComparison.SUPERSET
zero | nonzero | SetComparison.SUBSET
zero | zero | SetComparison.EQUAL

Parameters

flags1 | The flags that specify the type of access to the resource in the first permission. If bits are clear, access to the resource is not denied; if bits are set, more privileged access to the resource is granted.
flags2 | The flags that specify the type of access to the resource in the second permission. If bits are clear, access to the resource is not denied; if bits are set, more privileged access to the resource is granted.
mask | A bitmask that is combined with the flags (using the logical AND operator (&)) to determine which resources to compare as a unit.
prevcmp | A previous comparison result for other resources of the permissions. For the first resource of a permission, this is typically SetComparison.EMPTY.


compareLimits (PermissionUtils Class)

 Microsoft SDK for Java

compareLimits

This method of the PermissionUtils Class compares two positive numerical limits. A higher value is considered more privileged.

Syntax

public static int compareLimits(long limit1, long limit2, int prevcmp);

Return Value

Returns a new comparison result, merged with the previous comparison result using mergeComparisonResults.

Limit Comparisons

limit1 | limit2 | Result before merging
0 | 0 | SetComparison.EMPTY
>0 | 0 | SetComparison.EMPTY_SUPERSET
0 | >0 | SetComparison.EMPTY_SUBSET
>limit2 | >0 | SetComparison.SUPERSET
>0 | >limit1 | SetComparison.SUBSET
=limit2 | =limit1 | SetComparison.EQUAL

Parameters

limit1 | The first numerical limit.
limit2 | The second numerical limit.
prevcmp | A previous comparison result.


ComparisonResulttoString (PermissionUtils Class)

 Microsoft SDK for Java

ComparisonResulttoString

This method of the PermissionUtils Class converts com.ms.util.SetComparison results to a string format.

Syntax

public static String ComparisonResulttoString(int cmp);

Return Value

Returns one of the following result strings:

"empty" (EMPTY)

"equal" (EQUAL)

"disjoint" (DISJOINT)

"overlap" (OVERLAP)

"inclusive subset" (SUBSET)

"inclusive superset" (SUPERSET)

"empty subset" (EMPTY_SUBSET)

"empty superset" (EMPTY_SUPERSET)

Parameters

cmp A comparison result from the SetComparison.compareSet method.


concatVectors (PermissionUtils Class)

 Microsoft SDK for Java

concatVectors

This method of the PermissionUtils Class combines two vectors by copying their contents into a new Vector.

Syntax

public static Vector concatVectors(Vector v1, Vector v2);

CAUTION This is not a deep copy. It is only safe for use with the IPermission.combine method when the element type is immutable, such as the String type.

Return Value

Returns a new vector containing the elements of v1, followed by the elements of v2. If either of the vectors are null, the other non-null vector is returned.

Parameters

v1 | The first vector to combine, or null.
v2 | The second vector to combine, or null.


copyArrayOfIntRanges (PermissionUtils Class)

 Microsoft SDK for Java

copyArrayOfIntRanges

This method of the PermissionUtils Class returns a deep copy of an array of IntRanges objects. Each element is copied using the IntRanges.copy method.

Syntax

public static IntRanges[] copyArrayOfIntRanges(IntRanges[] ap);

Return Value

Returns null if ap is null; otherwise, returns a new array that contains copies of the elements of ap.

Parameters

ap An array of IntRanges, or null. The array can contain null elements.


copyArrayOfVectorsOfIntRanges (PermissionUtils Class)

 Microsoft SDK for Java

copyArrayOfVectorsOfIntRanges

This method of the PermissionUtils Class returns a deep copy of an array of Vectors containing IntRanges objects. Each Vector is copied using copyVectorOfIntRanges.

Syntax

public static Vector[] copyArrayOfVectorsOfIntRanges(Vector[] av);

Return Value

Returns null if av is null; otherwise, a new array of vectors is returned that contains new vectors with copies of their elements.

Parameters

av An array of Vectors, or null. The elements of the array or the vectors can be null.


copyArrayOfWildcardExpressions (PermissionUtils Class)

 Microsoft SDK for Java

copyArrayOfWildcardExpressions

This method of the PermissionUtils Class returns a deep copy of an array of WildcardExpressions. Each expression is copied using WildcardExpression.copy.

Syntax

public static WildcardExpression[] copyArrayOfWildcardExpressions( WildcardExpression[] ap);

Return Value

Returns null if ap is null; otherwise, a new array is returned that contains copies of the elements of ap.

Parameters

ap An array of WildcardExpressions, or null.


copyVectorOfIntRanges (PermissionUtils Class)

 Microsoft SDK for Java

copyVectorOfIntRanges

This method of the PermissionUtils Class returns a deep copy of a vector of IntRanges objects. Each element is copied using the IntRanges.copy method.

Syntax

public static Vector copyVectorOfIntRanges(Vector v);

Return Value

Returns a new Vector object containing copies of the elements of v, or returns null if v is null.

Parameters

v The vector of IntRanges to copy, or null. The vector can contain null elements.


invertComparisonResult (PermissionUtils Class)

 Microsoft SDK for Java

invertComparisonResult

This method of the PermissionUtils Class inverts comparison results.

Syntax

public static int invertComparisonResult(int cmp);

Return Value

Returns the inverted comparison result, described as follows:

If cmp is SUBSET, SUPERSET is returned.

If cmp is SUPERSET, SUBSET is returned.

If cmp is EMPTY_SUBSET, EMPTY_SUPERSET is returned.

If cmp is EMPTY_SUPERSET, EMPTY_SUBSET is returned.

Any other result is not affected by this method and is simply returned. Notice that EQUAL and DISJOINT are not inverted by this method.

Parameters

cmp The result to be inverted. It can be any of the following comparison results of the compare method:

SetComparison.SUBSET returns SetComparison.SUPERSET.

SetComparison.SUPERSET returns SetComparison.SUBSET.

SetComparison.EMPTY_SUBSET returns SetComparison.EMPTY_SUPERSET.

SetComparison.EMPTY_SUPERSET returns SetComparison.EMPTY_SUBSET.


mergeComparisonResults (PermissionUtils Class)

 Microsoft SDK for Java

mergeComparisonResults

This method of the PermissionUtils Class merges the comparison results from SetComparison.compareSet of two different sets into one, as though they were part of the same set.

Syntax

public static int mergeComparisonResults(int cmp1, int cmp2);

Return Value

Returns the merged comparison result.

Parameters

cmp1 | The first comparison result.
cmp2 | The second comparison result.


parseStringIntoArray (PermissionUtils Class)

 Microsoft SDK for Java

parseStringIntoArray

This method of the PermissionUtils Class splits a string into an array of strings at the specified delimiters.

Syntax

public static String[] parseStringIntoArray(String str,String delims);

Return Value

Returns the string that results from parsing.

Parameters

str | The string that is parsed.
delims | The delimiters to use when parsing.


PolicyEngine Class (com.ms.security Package)

 Microsoft SDK for Java

PolicyEngine Class

The PolicyEngine Class of the com.ms.security package exposes methods that perform permission-based security checks.

public class PolicyEngine
{
  // Methods
  public static native void assertPermission(PermissionID pid);
  public static void checkCallerForAllPermissions(Class[] skipset);
  public static void checkCallersPermission(PermissionID pid,
        Class[] skipset);
  public static void checkCallersPermission(String pname,
        Class[] skipset);
  public static void checkCallersPermission(PermissionID pid,Object
        sreq,Class[] skipset);
  public static void checkCallersPermission(String pname,
        Object sreq,Class[] skipset);
  public static void checkCallersPermission(ISecurityRequest sreq,
        Class[] skipset);
  public static void checkClass(Class cls,PermissionID pid);
  public static void checkClass(Class cls,String pname);
  public static void checkClass(Class cls,PermissionID pid,
        Object sreq);
  public static void checkClass(Class cls,ISecurityRequest sreq);
  public static void checkClassForAllPermissions(Class cls);
  public static void checkForAllPermissions();
  public static void checkPermission(PermissionID pid);
  public static void checkPermission(String pname);
  public static void checkPermission(PermissionID pid,Object sreq);
  public static void checkPermission(String pname,Object sreq);
  public static void checkPermission(ISecurityRequest sreq);
  public static native void denyPermission(PermissionID pid);
  public static Class getClassOfCaller();
  public static Class getClassOfCaller(Class[] skip);
  public static native PermissionDataSet getPermissionsOfClass(
        Class c);
  public static native Principal getPrincipalOfClass(Class c);
  public static synchronized PermissionID permissionNameToID(String
        pname);
  public static native void revertPermission(PermissionID pid);
}

These security checks are based on a security model that allows you to associate sets of permissions with the classes in the system. Then, at any point in time, the execution context can be examined to determine which operations are allowed by the permissions active within that context. The class types found on the call stack provide the required information about the active permissions. For more information about permissions, see the com.ms.security package overview.

The PolicyEngine class provides several different ways to examine the execution context to determine whether a given operation is allowed. The two main types of security checks are deep checks and shallow checks. Deep checks examine the entire call stack to ensure that all the classes within that execution context possess a certain permission. The PolicyEngine.checkPermission methods perform deep checks. In contrast, shallow checks do not use the depth of the stack to determine when to terminate the stack crawl. They are provided as a means of implementing roughly the same type of behavior as the original JDK SecurityManager methods classDepth and classLoaderDepth. The PolicyEngine.checkCallersPermission methods perform shallow checks. In general, deep checks are preferred over shallow checks.

Deep security checks are implemented in the following way: The stack is examined, starting with the immediate caller to the PolicyEngine class and working backward.

During a deep security check, the following steps are taken.

  1. Get the set of permissions associated with the class type of the stack frame, and then find the IPermission instance for the specific type of permission that is being checked for within that set.

  2. If the permission set does not contain an instance of the type of permission that is being searched for, terminate the stack crawl. The check fails.

  3. If this is a parameterized check, call the check method (IPermission.check) on the permission instance that has been found, passing it the security request object. If the check method throws an exception, terminate the stack crawl. The check fails.

  4. If the permission type has been explicitly denied by the current stack frame (using the denyPermission method), terminate the stack crawl. The security check fails.

  5. If the permission type has been explicitly asserted by the current stack frame (using the assertPermission method), terminate the stack crawl. The security check succeeds.

  6. The current frame has passed. Continue the stack crawl with the next frame.

Shallow security checks only check the immediate caller outside a boundary that is defined by a specified skip set. A skip set is a set of classes that is ignored during the security check. The first (and only the first) class found outside of the skip set will be checked for the permissions in question.

Shallow security checks are implemented in the following way. The stack is examined, starting with the immediate caller to the PolicyEngine class, and working backward. During a shallow security check, the following steps are taken.

  1. Get the class type associated with the current stack frame. If the class type is not within the specified skip set, the frame that should be checked has been found. Proceed to step 4.

  2. The class type of the current frame is in the skip set; however, the stack frame must still be checked for any explicit assertions or denials. If the permission type has been explicitly denied by the current stack frame (using the denyPermission method), terminate the stack crawl. The security check fails. If the permission type has been explicitly asserted by the current stack frame (using the assertPermission method), terminate the stack crawl. The security check succeeds.

  3. Since this frame was in the skip set, and no assertions or denials stopped the crawl, search for the next frame and continue the crawl. Proceed to step 1.

  4. The frame to be examined has been found. Get the set of permissions associated with the class type of the stack frame, and then find the IPermission instance for the specific type of permission that is being checked for within that set.

  5. If the permission set does not contain an instance of the type of permission that is being searched for, terminate the stack crawl. The security check fails.

  6. If this is a parameterized check, call the check method (IPermission.check) on the permission instance that was found, passing it the security request object. If the check method throws an exception, terminate the stack crawl. The security check fails.

  7. The current frame has passed, so terminate the stack crawl. The security check succeeds.

Deep and shallow security checks are provided in both parameterized and unparameterized forms.

Unparameterized checks simply ensure that all the classes in question possess a certain type of permission. This type of check is used for simple permissions, like the printing permission. Either a class has the printing permission or it doesn't.

Parameterized checks are used for more complex permissions, where the parameter to the check method is an object that is specific to the permission type. For instance, when checking for the file I/O permission, you must specify exactly which file I/O operation is being attempted and which file is involved. To check file I/O permission, you would create an instance of the com.ms.security.permissions.FileIORequest class that indicates which file is involved and which I/O operation is requested. You would then call the PolicyEngine.checkPermission(ISecurityRequest) method, passing in the FileIORequest object. If the check succeeds (no SecurityException is thrown), the specified operation is allowed.


Methods (PolicyEngine Class)

 Microsoft SDK for Java

PolicyEngine Class Methods

The PolicyEngine Class contains the following methods:

assertPermission asserts the right to a certain type of permission.
checkCallerForAllPermissions performs a security check to determine whether the first calling class outside the skip set is fully trusted.
checkCallersPermission performs a security check for a specific type of permission.
checkClass performs a security check directly against a specified class.
checkClassForAllPermissions performs a security check directly against a class object.
checkForAllPermissions performs a security check to determine whether all the calling class types on the call stack are fully trusted.
checkPermission performs a security check for a specific type of permission.
denyPermission denies the right to a certain type of permission.
getClassOfCaller retrieves the class type of the caller of this method.
getPermissionsOfClass obtains the permissions of a class.
getPrincipalOfClass obtains the principal associated with a specified class.
permissionNameToID creates a PermissionID object from a permission name.
revertPermission negates the effects of any assertions (assertPermission) or denials (denyPermission) that have been performed for the specified permission type by the current stack frame.


assertPermission (PolicyEngine Class)

 Microsoft SDK for Java

assertPermission

This method of the PolicyEngine Class asserts the right to a certain type of permission. This method causes the security system to ignore your callers when you cause a security check of the asserted type to occur.

Syntax

public static native void assertPermission(PermissionID pid);

Parameters

pid The type of permission to assert.

Remarks

Normally, when checking a given permission, the security system examines every frame on the call stack to ensure that all the callers possess the ability to perform the operation in question. However, if the security system sees a stack frame where the requested permission has been asserted (with this method), the stack crawl stops early and the security check succeeds.

The asserted permission state disappears when the stack frame of the caller to assertPermission exits (by executing a return statement or throwing an exception). The revertPermission method can be used to un-assert a permission type.

The following example shows how to assert the right to perform file I/O operations:

Example

   ...
   // Assert the right to perform file I/O
   PolicyEngine.assertPermission(PermissionID.FILEIO);

   // Now, do some file operation. Since you have asserted
   // your rights to file I/O, this check will succeed even if your callers do
   // not possess the ability to perform file I/O.
   FileInputStream fis = new FileInputStream("c:\\MySample.txt");
   ...

Note To assert all permissions, pass PermissionID.SYSTEM to the assertPermission method. This assertion forces the security system to ignore your callers during all security checks. Only fully trusted code can assert the SYSTEM permission.

See Also

denyPermission, revertPermission


checkCallerForAllPermissions (PolicyEngine Class)

 Microsoft SDK for Java

checkCallerForAllPermissions

This method of the PolicyEngine Class performs a security check to determine whether the first calling class outside the skip set is fully trusted.

Syntax

public static void checkCallerForAllPermissions(Class[] skipset);

Note Permission assertions and denials of the permission type PermissionID.SYSTEM are recognized within the skip set frames. They will affect the stack crawl and could cause it to terminate early.

Parameters

skipset The set of classes to ignore on the call stack.

Exceptions

SecurityException if the security check fails.


checkCallersPermission (PolicyEngine Class)

 Microsoft SDK for Java

checkCallersPermission

The checkCallersPermission method of the PolicyEngine Class contains the following signatures:

checkCallersPermission(PermissionID pid,Class[] skipset)
checkCallersPermission(String pname,Class[] skipset)
checkCallersPermission(PermissionID pid,Object sreq, Class[] skipset)
checkCallersPermission(String pname,Object sreq, Class[] skipset)
checkCallersPermission(ISecurityRequest sreq, Class[] skipset)

checkCallersPermission(PermissionID pid,Class[] skipset)

Performs a simple (non-parameterized) security check for a specific type of permission. This check is shallow. Only the first stack frame found outside the specified skip set will be checked.

Syntax

public static void checkCallersPermission(PermissionID pid,Class[] skipset);

Note Permission assertions and denials are recognized within the skip set frames, and could cause the stack crawl to terminate early.

Parameters

pid | The type of permission to check for.
skipset | The set of classes to ignore on the call stack.

Exceptions

SecurityException if the security check fails.

checkCallersPermission(String pname,Class[] skipset)

Performs a simple (non-parameterized) security check for a specific type of permission. This check is shallow. Only the first stack frame found outside the specified skip set will be checked. A permission name is used to specify the permission type (instead of a PermissionID).

Syntax

public static void checkCallersPermission(String pname,Class[] skipset);

Note Permission assertions and denials are recognized within the skip set frames, and could cause the stack crawl to terminate early.

Parameters

pname | The name of the permission to check for.
skipset | The set of classes to ignore on the call stack.

Exceptions

SecurityException if the security check fails.

checkCallersPermission(PermissionID pid,Object sreq, Class[] skipset)

Performs a parameterized security check for a specific type of permission. The check is shallow. Only the first stack frame found outside the specified skip set will be checked.

Syntax

public static void checkCallersPermission(PermissionID pid,Object sreq, Class[] skipset);

Note Permission assertions and denials are recognized within the skip set frames, and might cause the stack crawl to terminate early.

Parameters

pid | The type of permission to check for.
sreq | The security request object that indicates the specific resource to check for within the realm of the permission type. The type of the object depends on the type of the permission being checked.
skipset | The set of classes to ignore on the call stack.

Exceptions

SecurityException if the security check fails.

checkCallersPermission(String pname,Object sreq, Class[] skipset)

Performs a parameterized security check for a specific type of permission. The check is shallow. Only the first stack frame found outside the specified skip set will be checked. A permission name is used to specify the permission type (instead of a PermissionID).

Syntax

public static void checkCallersPermission(String pname,Object sreq, Class[] skipset);

Note Permission assertions and denials are recognized within the skip set frames, and might cause the stack crawl to terminate early.

Parameters

pname | The name of the permission to check for.
sreq | The security request object.
skipset | The set of classes to ignore on the call stack.

Exceptions

SecurityException if the security check fails.

checkCallersPermission(ISecurityRequest sreq, Class[] skipset)

Performs a parameterized security check for a specific type of permission. The check is shallow. Only the first stack frame found outside the specified skip set will be checked.

This method is a variation on the checkCallersPermission(PermissionID,Object,Class[]) method, where the sreq parameter indicates the permission type, and it also represents the security request object.

Syntax

public static void checkCallersPermission(ISecurityRequest sreq, Class[] skipset);

Parameters

sreq | The object that indicates the type of permission to check for and represents the security request object.
skipset | The set of classes to ignore on the call stack.

Exceptions

SecurityException if the security check fails.


checkClass (PolicyEngine Class)

 Microsoft SDK for Java

checkClass

The checkClass method of the PolicyEngine Class contains the following signatures:

checkClass(Class cls,PermissionID pid)
checkClass(Class cls,String pname)
checkClass(Class cls,PermissionID pid,Object sreq)
checkClass(Class cls,ISecurityRequest sreq)

checkClass(Class cls,PermissionID pid)

Performs a security check directly against a specified class. If the class does not possess the specified type of permission, a SecurityException is thrown.

Syntax

public static void checkClass(Class cls,PermissionID pid);

Parameters

cls | The class to check against.
pid | The type of permission to check for.

Exceptions

SecurityException if the security check fails.

checkClass(Class cls,String pname)

Performs a security check directly against a specified class. If the class does not possess the specified type of permission, a SecurityException is thrown. The permission type is specified as a permission name (instead of a PermissionID object).

Syntax

public static void checkClass(Class cls,String pname);

Parameters

cls | The class to check against.
pname | The name of the permission to check for.

Exceptions

SecurityException if the security check fails.

checkClass(Class cls,PermissionID pid,Object sreq)

Performs a security check directly against a specified class. The class must possess the specified type of permission, and the parameterized check against the class's associated permission object must pass, or a SecurityException is thrown.

Syntax

public static void checkClass(Class cls,PermissionID pid,Object sreq);

Parameters

cls | The class to check against.
pid | The type of permission to check for.
sreq | The security request object.

Exceptions

SecurityException if the security check fails.

checkClass(Class cls,ISecurityRequest sreq)

Performs a security check directly against a specified class. The class must possess the specified type of permission, and the parameterized check against the class's associated permission object must pass, or a SecurityException is thrown.

Syntax

public static void checkClass(Class cls,ISecurityRequest sreq);

Parameters

cls | The class to check against.
sreq | The object that determines the type of permission to check for and also represents the security request object.

Remarks

This method is a variation on the checkClass(Class,PermissionID,Object) method, where the ISecurityRequest object is used to determine the permission type, and is also used as the permission request object.

Exceptions

SecurityException if the security check fails.


checkClassForAllPermissions (PolicyEngine Class)

 Microsoft SDK for Java

checkClassForAllPermissions

This method of the PolicyEngine Class performs a security check directly against a class object. If the class is not fully trusted, the security check fails.

Syntax

public static void checkClassForAllPermissions(Class cls);

Parameters

cls The class to check against.

Exceptions

SecurityException if the security check fails.


checkForAllPermissions (PolicyEngine Class)

 Microsoft SDK for Java

checkForAllPermissions

This method of the PolicyEngine Class performs a security check to determine whether all the calling class types on the call stack are fully trusted. If any of the calling classes are not fully trusted, the security check fails (a SecurityException is thrown).

Syntax

public static void checkForAllPermissions();

Note Permission assertions and denials on the permission type PermissionID.SYSTEM affect the stack crawl, causing it to terminate early without examining the entire stack.

Exceptions

SecurityException if the security check fails.


checkPermission (PolicyEngine Class)

 Microsoft SDK for Java

checkPermission

The checkPermission method of the PolicyEngine Class contains the following signatures:

checkPermission(PermissionID pid)
checkPermission(String pname)
checkPermission(PermissionID pid,Object sreq)
checkPermission(String pname,Object sreq)
checkPermission(ISecurityRequest sreq)

checkPermission(PermissionID pid)

Performs a simple (non-parameterized) security check for a specified type of permission. For the security check to pass, all the callers on the call stack must possess the specified type of permission.

Syntax

public static void checkPermission(PermissionID pid);

Note Permission assertions and denials might affect the stack crawl, which could cause it to terminate early without examining the entire stack.

Parameters

pid The type of permission to check for.

Exceptions

SecurityException if the security check fails.

checkPermission(String pname)

Performs a simple (non-parameterized) security check for a specified type of permission. A permission name is used to specify the permission type. For the security check to pass, all the callers on the call stack must possess the specified type of permission.

Syntax

public static void checkPermission(String pname);

Note Permission assertions and denials might affect the stack crawl, causing it to terminate early without examining the entire stack.

Parameters

pname The name of the permission to check for.

Exceptions

SecurityException if the security check fails.

checkPermission(PermissionID pid,Object sreq)

Performs a parameterized security check for a specific type of permission.

Syntax

public static void checkPermission(PermissionID pid,Object sreq);

Parameters

pid | The type of permission to check for.
sreq | The security request object that indicates the specific resource to check for within the realm of the permission type. The type of this object depends on the type of the permission being checked.

Remarks

For the security check to pass, all the callers on the call stack must possess the specified type of permission. In addition, all the permission objects associated with the calling class types found on the stack must validate that the operation indicated by the security request object is allowed. Validation is accomplished by calling the IPermission.check method of all the found permission instances.

Note Permission assertions and denials might affect the stack crawl, causing it to terminate early without examining the entire stack.

Exceptions

SecurityException if the security check fails.

checkPermission(String pname,Object sreq)

Performs a parameterized security check for a specific type of permission. A permission name is used to specify the permission type (instead of a PermissionID).

Syntax

public static void checkPermission(String pname,Object sreq);

Parameters

pname | The name of the permission to check for.
sreq | The security request object that indicates the specific resource to check for within the realm of the permission type. The type of this object depends on the type of the permission being checked.

Remarks

For the security check to pass, all the callers on the call stack must possess the specified type of permission. In addition, all the permission objects associated with the calling class types found on the stack must validate that the operation indicated by the security request object is allowed. Validation is accomplished by calling the IPermission.check method of all the found permission instances.

Note Permission assertions and denials might affect the stack crawl, causing it to terminate early without examining the entire stack.

Exceptions

SecurityException if the security check fails.

checkPermission(ISecurityRequest sreq)

Performs a parameterized security check for a specific type of permission. This method is a variation on the checkPermission(PermissionID,Object) method where the sreq parameter is used to determine the permission type and is also used as the security request object.

Syntax

public static void checkPermission(ISecurityRequest sreq);

Calling the checkPermission(ISecurityRequest) method is equivalent to the following call:

   checkPermission(sreq.getPermissionID(),sreq);

Parameters

sreq The object that determines the permission type and indicates the resource to check for.

Exceptions

SecurityException if the security check fails.

See Also

checkPermission(PermissionID,Object)


denyPermission (PolicyEngine Class)

 Microsoft SDK for Java

denyPermission

This method of the PolicyEngine Class denies the right to a certain type of permission. Any stack-based security checks (for the specific type of permission that has been denied) that encounter the stack frame of the caller to denyPermission will fail. This forces the methods that you call to assert their permissions (using the assertPermission method) to pass security checks.

Syntax

public static native void denyPermission(PermissionID pid);

Parameters

pid The type of permission to deny.

Remarks

Normally, when checking a given permission, the security system examines every frame on the call stack to ensure all the callers possess the ability to perform the operation in question. If the security system sees a stack frame where that permission has been denied (with this method), the stack crawl stops early and the security check fails.

The denied permission state will disappear when the stack frame of the caller to denyPermission exits (by executing a return statement or throwing an exception). The revertPermission method can be used to un-deny a permission type.

The following example shows you how to deny the right to perform file I/O operations:

   ...
   // Deny your right to perform file I/O.

   PolicyEngine.denyPermission(PermissionID.FILEIO);

   // Now, call into some other code in the MySample
   // class. If that code wants to perform some file I/O operations,
   // it must assert its rights to do so, or the file I/O
   // security checks will fail because you have denied your rights to
   // them.

   MySample.doSomething();

   ...

Note To deny all permissions, pass PermissionID.SYSTEM to the denyPermission method. This forces any code you call to assert its rights to any permissions it needs to utilize. Only fully trusted code can deny the SYSTEM permission.

See Also

assertPermission, revertPermission


getClassOfCaller (PolicyEngine Class)

 Microsoft SDK for Java

getClassOfCaller

The getClassOfCaller method of the PolicyEngine Class contains the following signatures:

getClassOfCaller()
getClassOfCaller(Class[] skip)

getClassOfCaller()

Retrieves the class type of the immediate caller of this method.

Syntax

public static Class getClassOfCaller();

Return Value

Returns the class type of the immediate caller of this method.

getClassOfCaller(Class[] skip)

Retrieves the class type of the caller of this method, skipping any classes found in the specified skip set.

Syntax

public static Class getClassOfCaller(Class[] skip);

Return Value

Returns the class type of the caller.

Parameters

skip The set of classes to ignore.


getPermissionsOfClass (PolicyEngine Class)

 Microsoft SDK for Java

getPermissionsOfClass

This method of the PolicyEngine Class obtains the permissions of a class. Only fully trusted classes are allowed to call this method.

Syntax

public static native PermissionDataSet getPermissionsOfClass(Class c);

Return Value

Returns the permissions of the specified class.

Parameters

c The class whose permissions are being obtained.


getPrincipalOfClass (PolicyEngine Class)

 Microsoft SDK for Java

getPrincipalOfClass

This method of the PolicyEngine Class obtains the principal associated with a specified class. Only fully trusted classes are allowed to call this method.

Syntax

public static native Principal getPrincipalOfClass(Class c);

Return Value

Returns the principal associated with the specified class.

Parameters

c The class to examine.

Exceptions

SecurityException if the calling class is not fully trusted.


permissionNameToID (PolicyEngine Class)

 Microsoft SDK for Java

permissionNameToID

This method of the PolicyEngine Class creates a PermissionID object from a permission name.

Syntax

public static synchronized PermissionID permissionNameToID(String pname);

Return Value

Returns the PermissionID that maps to the specified permission name.

Parameters

pname The name of the permission.

Remarks

Permission names must be the name of the class that implements the permission. The permission class must be a fully trusted system class. Only fully trusted code can create new permission identifiers.


revertPermission (PolicyEngine Class)

 Microsoft SDK for Java

revertPermission

This method of the PolicyEngine Class negates the effects of any assertions (assertPermission) or denials (denyPermission) that have been performed for the specified permission type by the current stack frame.

Syntax

public static native void revertPermission(PermissionID pid);

Parameters

pid The type of permission to revert.

The following example asserts a right, and then reverts it:

   ...

   // Assert your rights to perform file I/O operations

   PolicyEngine.assertPermission(PermissionID.FILEIO);

   // Do some file I/O. Your callers will be ignored during
   // the file I/O security check that this operation causes
   // because you have asserted your rights.

   FileInputStream fis = new FileInputStream("c:\\MySample.txt");

   // Remove the file I/O assertion.

   PolicyEngine.revertPermission(PermissionID.FILEIO);

   // Do some more file I/O. This time your callers will be
   // included in the security check since
   // your file I/O rights are no longer asserted.

   FileInputStream fis = new FileInputStream("c:\\MySample.txt");
   ...

See Also

assertPermission, denyPermission


SecurityClassLoader Class (com.ms.security Package)

 Microsoft SDK for Java

SecurityClassLoader Class

The SecurityClassLoader Class of the com.ms.security package provides methods that associate permissions with classes. You can specify the permissions and a java.security.Principal object to associate with a new class.

public abstract class SecurityClassLoader extends ClassLoader
{
  // Fields
  protected URL codeBase;
  protected ThreadGroup threadGroup;

  // Constructors
  protected SecurityClassLoader();

  // Methods
  protected final synchronized Class defineClass( String name,
        byte data[],int offset,int length,
        PermissionSet permissions,Principal principal);
  protected Class findPackageManagerClass(String name)
        throws ClassNotFoundException;
  protected Class findPackageManagerClass(String name,
        boolean fNameSpaceOnly) throws ClassNotFoundException;
  protected InputStream findPackageManagerResource(String name);
  public Object getSecurityContext();
  public ThreadGroup getThreadGroup();
  protected void setCodeBase (URL codeBase);
  protected void setPackageManagerNamespace(String namespace);
  protected void setThreadGroup(ThreadGroup tg);
}

Hierarchy

ClassLoader
  |
  +--SecurityClassLoader


Constructors (SecurityClassLoader Class)

 Microsoft SDK for Java

SecurityClassLoader Class Constructors

The SecurityClassLoader Class contains the following constructor:

SecurityClassLoader()

Instantiates a new SecurityClassLoader instance.

Syntax

protected SecurityClassLoader();

Exceptions

SecurityException if one or more callers on the current execution stack are not fully trusted.


Methods (SecurityClassLoader Class)

 Microsoft SDK for Java

SecurityClassLoader Class Methods

The SecurityClassLoader Class contains the following methods:

defineClass converts an array of bytes into an instance of Class and associates the new class with a set of permissions and a principal.
findPackageManagerClass finds a specified class from the package manager.
findPackageManagerResource retrieves an InputStream associated with a package manager resource with the specified name.
getSecurityContext retrieves the security context object associated with the class loader.
getThreadGroup retrieves the thread group associated with the loader.
setCodeBase sets the codebase URL associated with the class loader.
setPackageManagerNamespace sets the package manager namespace associated with the loader.
setThreadGroup sets the thread group associated with the class loader.


defineClass (SecurityClassLoader Class)

 Microsoft SDK for Java

defineClass

This method of the SecurityClassLoader Class converts an array of bytes into an instance of Class and associates the new class with a set of permissions and a principal.

Syntax

protected final synchronized Class defineClass(String name,byte data[],int offset,int length, PermissionSet permissions,Principal principal);

Return Value

Returns the Class object that was created from the data.

Parameters

name | The expected name of the class, using "." (not "/") as a separator, and without a trailing .class suffix. This value will be null if the name is unknown.
data | The bytes that make up the class.
offset | The start offset of the class data.
length | The length of the class data.
permissions | The permissions to associate with the new class. The value can be null, in which case the new class will have no associated permissions.
principal | The principal to associate with the new class. The value can be null, in which case the new class will have no associated principal.

Remarks

This method is similar to the java.lang.Class.defineClass method with the added ability to associate a set of permissions with a class. As with the java.lang.Class.defineClass method, the class must be resolved before it can be used.

Exceptions

ClassFormatError if the data does not contain a valid Class.


findPackageManagerClass (SecurityClassLoader Class)

 Microsoft SDK for Java

findPackageManagerClass

The findPackageManagerClass method of the SecurityClassLoader Class contains the following signatures:

findPackageManagerClass(String name)
findPackageManagerClass(String name,boolean fNameSpaceOnly)

findPackageManagerClass(String name)

Finds a specified class from the package manager. Within the package manager, this method will search for the class in both the global namespace and the namespace associated with the loader (if any). Calling this method is equivalent to calling findPackageManagerClass(name,false).

Syntax

protected Class findPackageManagerClass(String name) throws ClassNotFoundException;

Return Value

Returns a package manager class with the specified name.

Parameters

name The name of the class.

Exceptions

ClassNotFoundException if this method cannot find a definition for the class.

findPackageManagerClass(String name,boolean fNameSpaceOnly)

Finds a specified class from the package manager. If the class is found, it will be marked with the set of permissions that are associated with its package within the package manager. The principal associated with the class will be based on the principal that the package manager associates with its package.

Syntax

protected Class findPackageManagerClass(String name,boolean fNameSpaceOnly) throws ClassNotFoundException;

Return Value

Returns a package manager class with the specified name.

Parameters

name | The name of the class.
fNameSpaceOnly | The flag that indicates whether to ignore the global package manager namespace during the search for the class. If the value is true, only the package manager namespace associated with the class loader will be searched; otherwise, the global namespace and the package manager namespace will be searched.

Remarks

The fNameSpaceOnly parameter can be used to force this method to look only in the package manager namespace associated with this loader. However, only rarely would you need to exclude the global namespace from the search path. Normally, you would pass false for the fNameSpaceOnly parameter, or simply use the findPackageManagerClass method that has only one parameter.

Exceptions

ClassNotFoundException if this method cannot find a definition for the specified class.


findPackageManagerResource (SecurityClassLoader Class)

 Microsoft SDK for Java

findPackageManagerResource

This method of the SecurityClassLoader Class retrieves an InputStream associated with a package manager resource with the specified name. As with the findSystemResourceX APIs, this method expects the name to be separated with a "/". For example, the package manager resource name "my/sample/baz.gif" indicates the baz.gif file within the my.sample package.

Syntax

protected InputStream findPackageManagerResource(String name);

Return Value

Returns an InputStream associated with the resource, or null if the InputStream cannot be found.

Parameters

name The name of the resource to find.


getSecurityContext (SecurityClassLoader Class)

 Microsoft SDK for Java

getSecurityContext

This method of the SecurityClassLoader Class retrieves the security context object associated with the class loader. Currently, this returns the codebase URL.

Syntax

public Object getSecurityContext();

Return Value

Returns the codebase URL associated with the class loader.


getThreadGroup (SecurityClassLoader Class)

 Microsoft SDK for Java

getThreadGroup

This method of the SecurityClassLoader Class retrieves the thread group associated with the loader.

Syntax

public ThreadGroup getThreadGroup();

Return Value

Returns the thread group associated with the loader.


setCodeBase (SecurityClassLoader Class)

 Microsoft SDK for Java

setCodeBase

This method of the SecurityClassLoader Class sets the codebase URL associated with the class loader. Call this method before using the loader to load classes.

Syntax

protected void setCodeBase(URL codeBase);

Parameters

codeBase The codebase URL to associate with the loader.

Exceptions

SecurityException if the loader already has an associated codebase URL.


setPackageManagerNamespace (SecurityClassLoader Class)

 Microsoft SDK for Java

setPackageManagerNamespace

This method of the SecurityClassLoader Class sets the package manager namespace associated with the loader.

Syntax

protected void setPackageManagerNamespace(String namespace);

Parameters

namespace The name of the package manager namespace to associate with the loader.

Remarks

All package management class and resource loads done by this loader will look in this explicitly-named namespace in addition to the default global package manager namespace.

Exceptions

SecurityException if the loader already has an associated package manager namespace.


setThreadGroup (SecurityClassLoader Class)

 Microsoft SDK for Java

setThreadGroup

This method of the SecurityClassLoader Class sets the thread group associated with the class loader. Call this method before using the loader to load classes.

Syntax

protected void setThreadGroup(ThreadGroup tg);

Parameters

tg The thread group to associate with the class loader.

Exceptions

SecurityException if the loader already has an associated ThreadGroup object.


Fields (SecurityClassLoader Class)

 Microsoft SDK for Java

SecurityClassLoader Class Fields

The SecurityClassLoader Class contains the following fields.

codeBase | The codebase URL associated with code from the class loader.
threadGroup | The loader's thread group.

This thread group serves as the master thread group for all code associated with this class loader. For applets, each individual applet instance will have a sub-thread group of this thread group. The security system uses this thread group to determine the active context-based thread group at any given point.

For more details on how the security system uses this thread group, see the StandardSecurityManager.getThreadGroup method.


SecurityExceptionEx Class (com.ms.security Package)

 Microsoft SDK for Java

SecurityExceptionEx Class

The SecurityExceptionEx Class of the com.ms.security package represents security exceptions that are thrown by a component of the security system to indicate a security violation.

public class SecurityExceptionEx extends SecurityException
{
  // Constructors
  public SecurityExceptionEx();
  public SecurityExceptionEx(String s);

  // Methods
  public String getFailingClassName();
  public String getFailingMethodName();
  public String toString();
}

The SecurityExceptionEx class differs from the standard java.lang.SecurityException class in that it can also keep track of who caused the security violation.

This extended behavior of a SecurityExceptionEx object is currently useful only within the IPermission.check method. If an IPermission.check method, which has been called by the Microsoft VM in response to one of the PolicyEngine.checkPermission APIs, throws an instance of SecurityExceptionEx, the Microsoft VM will fill in the class and method names of the stack frame that failed the check. SecurityExceptionEx instances that are thrown in other contexts do not contain the class and method name information, and the getFailingClassName and getFailingMethodName methods will then return null.

Hierarchy

SecurityException
  |
  +--SecurityExceptionEx


Constructors (SecurityExceptionEx Class)

 Microsoft SDK for Java

SecurityExceptionEx Class Constructors

The SecurityExceptionEx Class contains the following constructors:

SecurityExceptionEx()
SecurityExceptionEx(String s)

SecurityExceptionEx()

Creates a new SecurityExceptionEx object with no detail message.

Syntax

public SecurityExceptionEx();

SecurityExceptionEx(String s)

Creates a new SecurityExceptionEx object based on the specified detail message.

Syntax

public SecurityExceptionEx(String s);

Parameters

s The detail message.


Methods (SecurityExceptionEx Class)

 Microsoft SDK for Java

SecurityExceptionEx Class Methods

The SecurityExceptionEx Class contains the following methods:

getFailingClassName retrieves the name of the class that caused the security violation.
getFailingMethodName retrieves the name of a specific method, found on the call stack, that caused a security violation.
toString converts the SecurityExceptionEx object to its string representation.


getFailingClassName (SecurityExceptionEx Class)

 Microsoft SDK for Java

getFailingClassName

This method of the SecurityExceptionEx Class retrieves the name of the class that caused the security violation. Typically, this would be the class type of a caller (found on the call stack) that lacked the proper permissions to satisfy a permission-based security check using the PolicyEngine class.

Syntax

public String getFailingClassName();

Return Value

Returns the name of the class that caused the security violation. This value might be null, depending on the context in which the SecurityExceptionEx is thrown.


getFailingMethodName (SecurityExceptionEx Class)

 Microsoft SDK for Java

getFailingMethodName

This method of the SecurityExceptionEx Class retrieves the name of a specific method, found on the call stack, that caused a security violation. Typically, a security violation occurs when the class associated with the method lacks the proper permissions to satisfy a permission-based security check using the PolicyEngine class.

Syntax

public String getFailingMethodName();

Return Value

Returns the name of the method that caused the security violation. This value might be null, depending on the context in which the SecurityExceptionEx is thrown.


toString (SecurityExceptionEx Class)

 Microsoft SDK for Java

toString

This method of the SecurityExceptionEx Class converts the SecurityExceptionEx object to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the SecurityExceptionEx object.

Remarks

The representation of a SecurityExceptionEx differs slightly from the standard java.lang.Throwable output in that it also includes the class and method name of the stack frame that caused the security violation.

The string representation of a SecurityExceptionEx object is shown in the following example:

  <ex-name>[<class>.<method>]: <detail>
  or
  <ex-name>[Unknown]: <detail>

The bracketed names have the following meanings:

<ex-name>

The name of the exception (com.ms.security.SecurityExceptionEx).

<class>

The name of the failing class.

<method>

The name of the failing method.

<detail>

The detail message.


StandardSecurityManager Class (com.ms.security Package)

 Microsoft SDK for Java

StandardSecurityManager Class

The StandardSecurityManager Class of the com.ms.security package defines a security policy that uses the permission model to perform security checks. The StandardSecurityManager.checkXXX methods call the PolicyEngine.checkPermission methods to do the stack crawl that actually determines whether the specified operation is permitted.

public class StandardSecurityManager extends java.lang.SecurityManager
{
  // Constructors
  public StandardSecurityManager();

  // Methods
  public synchronized void checkAccept(String host, int port);
  public void checkAccess(Thread t);
  public void checkAccess(ThreadGroup g);
  public void checkAwtEventQueueAccess();
  public synchronized void checkConnect(String host, int port);
  public void checkConnect(String host, int port, Object context);
  public void checkCreateClassLoader();
  public void checkDelete(String file);
  public void checkExec(String cmd);
  public void checkExit(int status);
  public void checkFileDialog();
  public void checkLink(String lib);
  public synchronized void checkListen(int port);
  public void checkMemberAccess(Class clazz, int which);
  public void checkMulticast(InetAddress maddr);
  public void checkMulticast(InetAddress maddr, byte ttl);
  public synchronized void checkMultimedia();
  public void checkPackageAccess(String pkg);
  public static void checkPackageAccessFromClassName(
        String classname);
  public synchronized void checkPackageDefinition(String pkg);
  public static void checkPackageDefinitionFromClassName(
        String classname);
  public void checkPrintJobAccess();
  public void checkPropertiesAccess();
  public void checkPropertyAccess(String key);
  public void checkRead(String file);
  public static void checkRead(URL url);
  public void checkRead(String file, Object context);
  public void checkRead(FileDescriptor fd);
  public void checkRegistry(int access, String value);
  public void checkSecurityAccess(String provider);
  public void checkSetFactory();
  public void checkSystemClipboardAccess();
  public void checkSystemStreams(int streamID);
  public boolean checkTopLevelWindow(Object window);
  public void checkWrite(String file);
  public void checkWrite(FileDescriptor fd);
  public Object getSecurityContext();
  public ThreadGroup getThreadGroup();
  public static void installStandardSecurity();
}

Hierarchy

SecurityManager
  |
  +--StandardSecurityManager


Constructors (StandardSecurityManager Class)

 Microsoft SDK for Java

StandardSecurityManager Class Constructors

The StandardSecurityManager Class contains the following constructor:

StandardSecurityManager()

Constructs and initializes a StandardSecurityManager object.

Syntax

public StandardSecurityManager();


Methods (StandardSecurityManager Class)

 Microsoft SDK for Java

StandardSecurityManager Class Methods

The StandardSecurityManager Class contains the following methods:

checkAccept determines whether classes within the current execution context, based on the call stack of the current thread, can accept a socket connection from the specified host and port.
checkAccess determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to manipulate the specified thread.
checkAwtEventQueueAccess determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to access the AWT event queue.
checkConnect determines whether classes within the current execution context, based on the call stack of the current thread, can open a socket connection to the specified host on the specified port.
checkCreateClassLoader determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to create class loader objects.
checkDelete determines whether the specified file can be deleted by the classes active within the current execution context.
checkExec determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to execute the specified application.
checkExit determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to terminate the Microsoft VM.
checkFileDialog determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to display and use file dialog boxes (java.awt.FileDialog).
checkLink determines whether the current execution context, based on the calling classes on the call stack, allows the loading of the specified native code library (DLL).
checkListen determines whether classes within the current execution context, based on the call stack of the current thread, can wait for connection requests on the specified local port number.
checkMemberAccess determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to use the reflection APIs to access members of the specified type from the specified class.
checkMulticast determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to use IP multicast.
checkMultimedia determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to utilize extended multimedia features.
checkPackageAccess determines whether access to classes within the specified package is permitted.
checkPackageAccessFromClassName checks to see if applets can access classes located in the package that contains a specified class.
checkPackageDefinition determines whether classes within the specified package can be defined.
checkPackageDefinitionFromClassName, if a security manager is installed, checks to see if applets can define classes in the package of the specified class name.
checkPrintJobAccess determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to initiate a print job.
checkPropertiesAccess determines whether the system properties object can be passed to the caller of the System.getProperties method.
checkPropertyAccess determines if the specified system property can be read by all the classes within the current execution context.
checkRead determines whether the specified file can be read by the classes active within the current execution context.
checkRegistry determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to perform the specified access to the specified portion of the registry.
checkSecurityAccess determines if classes within the current execution context, based on the call stack of the current thread, are allowed to perform a security provider-related operation (using the java.security classes).
checkSetFactory determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to install a networking object factory.
checkSystemClipboardAccess determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to access the system Clipboard.
checkSystemStreams determines if classes within the current execution context, based on the call stack of the current thread, are allowed to set the specified system stream.
checkTopLevelWindow determines if classes within the current execution context, based on the call stack of the current thread, are allowed to create top-level windows.
checkWrite determines whether the specified file can be written to by the classes active within the current execution context.
getSecurityContext retrieves the codebase URL associated with the nearest SecurityClassLoader instance found on the call stack.
getThreadGroup determines the active thread group based on the current execution context.
installStandardSecurity creates a new StandardSecurityManager and installs it as the active security manager.


checkAccept (StandardSecurityManager Class)

 Microsoft SDK for Java

checkAccept

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, can accept a socket connection from the specified host and port.

Syntax

public synchronized void checkAccept(String host, int port);

The check succeeds only if all the classes found on the call stack possess NetIOPermissions, and if those permissions allow the specified host and port for connections. This method overrides the java.lang.SecurityManager.checkAccept(String,int) method.

Parameters

host | The host.
port | The port.

Exceptions

SecurityException if the security check fails.


checkAccess (StandardSecurityManager Class)

 Microsoft SDK for Java

checkAccess

The checkAccess method of the StandardSecurityManager Class contains the following signatures:

checkAccess(Thread t)
checkAccess(ThreadGroup g)

checkAccess(Thread t)

Determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to manipulate the specified thread.

Syntax

public void checkAccess(Thread t);

Parameters

t The thread whose call stack is being checked for permissions.

Remarks

The check succeeds only if all the classes found on the call stack possess ThreadPermissions, and if those permissions allow access to the specified thread. This method overrides the java.lang.SecurityManager.checkAccess method.

Exceptions

SecurityException if the security check fails.

checkAccess(ThreadGroup g)

Determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to manipulate the specified thread group.

Syntax

public void checkAccess(ThreadGroup g);

Parameters

g The thread group whose call stack is being checked for permissions.

Remarks

The check succeeds only if all the classes found on the call stack possess ThreadPermissions, and if those permissions allow access to the specified thread group. This method overrides the java.lang.SecurityManager.checkAccess method.

Exceptions

SecurityException if the security check fails.


checkAwtEventQueueAccess (StandardSecurityManager Class)

 Microsoft SDK for Java

checkAwtEventQueueAccess

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to access the AWT event queue.

Syntax

public void checkAwtEventQueueAccess();

Remarks

The check succeeds only if all the classes found on the call stack possess UIPermissions, and those permissions allow access to the AWT event queue. This method overrides the java.lang.SecurityManager.checkAwtEventQueueAccess method.

Exceptions

SecurityException if the security check fails.


checkConnect (StandardSecurityManager Class)

 Microsoft SDK for Java

checkConnect

The checkConnect method of the StandardSecurityManager Class contains the following signatures:

checkConnect(String host, int port)
checkConnect(String host, int port, Object context)

checkConnect(String host, int port)

Determines whether classes within the current execution context, based on the call stack of the current thread, can open a socket connection to the specified host on the specified port.

Syntax

public synchronized void checkConnect(String host, int port);

Parameters

host | The host.
port | The port.

Remarks

The check succeeds only if all the classes found on the call stack possess NetIOPermissions, and if those permissions allow connections to the specified host and port. This method overrides the java.lang.SecurityManager.checkConnect(String,int) method.

Exceptions

SecurityException if the security check fails.

checkConnect(String host, int port, Object context)

Determines whether classes within the current execution context, based on the call stack of the current thread, can open a socket connection to the specified host on the specified port. This method overrides the java.lang.SecurityManager.checkConnect(String,int) method.

Syntax

public void checkConnect(String host, int port, Object context);

Note The context parameter is ignored, and this method simply forwards the check to the checkConnect(String host,int port) method.

Parameters

host | The host.
port | The port.
context | This parameter is ignored.

Exceptions

SecurityException if the security check fails.

See Also

checkConnect(String,int)


checkCreateClassLoader (StandardSecurityManager Class)

 Microsoft SDK for Java

checkCreateClassLoader

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to create class loader objects.

Syntax

public void checkCreateClassLoader();

Remarks

The check succeeds only if the calling code is fully trusted. This method overrides the java.lang.SecurityManager.checkCreateClassLoader method.

Exceptions

SecurityException if the security check fails.


checkDelete (StandardSecurityManager Class)

 Microsoft SDK for Java

checkDelete

This method of the StandardSecurityManager Class determines whether the specified file can be deleted by the classes active within the current execution context.

Syntax

public void checkDelete(String file);

Parameters

file The system-dependent filename.

Remarks

The check succeeds only if all the classes found on the call stack possess FileIOPermissions, and if those permissions allow delete access to the specified file. This method overrides the java.lang.SecurityManager.checkDelete(String) method.

Exceptions

SecurityException if the security check fails.


checkExec (StandardSecurityManager Class)

 Microsoft SDK for Java

checkExec

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to execute the specified application.

Syntax

public void checkExec(String cmd);

Parameters

cmd The application for which permission to execute is being checked.

Remarks

The check succeeds only if all the classes found on the call stack possess ExecutionPermission, and if those permissions allow the specified application to be run. This method overrides the java.lang.SecurityManager.checkExec method.

Exceptions

SecurityException if the security check fails.


checkExit (StandardSecurityManager Class)

 Microsoft SDK for Java

checkExit

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to terminate the Microsoft VM.

Syntax

public void checkExit(int status);

Parameters

status This parameter is ignored.

Remarks

The check succeeds only if all the classes found on the call stack are fully trusted. This method overrides the java.lang.SecurityManager.checkExit method.

Exceptions

SecurityException if the security check fails.


checkFileDialog (StandardSecurityManager Class)

 Microsoft SDK for Java

checkFileDialog

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to display and use file dialog boxes (java.awt.FileDialog).

Syntax

public void checkFileDialog();

Remarks

The check succeeds only if all the classes found on the call stack possess UIPermissions, and if those permissions allow the creation of file dialog boxes.

Exceptions

SecurityException if the security check fails.


checkLink (StandardSecurityManager Class)

 Microsoft SDK for Java

checkLink

This method of the StandardSecurityManager Class determines whether the current execution context, based on the calling classes on the call stack, allows the loading of the specified native code library (DLL).

Syntax

public void checkLink(String lib);

Parameters

lib The DLL for which permission to load is checked.

Remarks

The check succeeds only if the caller is fully trusted system code. This method overrides the java.lang.SecurityManager.checkLink method.

Exceptions

SecurityException if the security check fails.


checkListen (StandardSecurityManager Class)

 Microsoft SDK for Java

checkListen

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, can wait for connection requests on the specified local port number.

Syntax

public synchronized void checkListen(int port);

Parameters

port The local port from which permission to listen is being checked.

Remarks

The check succeeds only if all the classes found on the call stack possess NetIOPermissions, and if those permissions allow listening for connections on the specified port. This method overrides the java.lang.SecurityManager.checkListen(int) method.

Exceptions

SecurityException if the security check fails.


checkMemberAccess (StandardSecurityManager Class)

 Microsoft SDK for Java

checkMemberAccess

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to use the reflection APIs to access members of the specified type from the specified class.

Syntax

public void checkMemberAccess(Class clazz, int which);

Parameters

clazz | The class to which access is being checked.
which | The type of class members to which access is being checked.

Remarks

The check succeeds only if all the classes found on the call stack possess ReflectionPermissions, and if those permissions allow access to the specified class.

Exceptions

SecurityException if the security check fails.


checkMulticast (StandardSecurityManager Class)

 Microsoft SDK for Java

checkMulticast

The checkMulticast method of the StandardSecurityManager Class contains the following signatures:

checkMulticast(InetAddress maddr)
checkMulticast(InetAddress maddr, byte ttl)

checkMulticast(InetAddress maddr)

Determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to use IP multicast.

Syntax

public void checkMulticast(InetAddress maddr);

Parameters

maddr The Internet address.

Remarks

The check succeeds only if all the classes found on the call stack possess NetIOPermissions, and if those permissions allow multicast operations on the specified Internet address. This method overrides the java.lang.SecurityManager.checkMulticast(InetAddress) method.

Exceptions

SecurityException if the security check fails.

checkMulticast(InetAddress maddr, byte ttl)

Determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to use IP multicast.

Syntax

public void checkMulticast(InetAddress maddr, byte ttl);

Parameters

maddr | The Internet address.
ttl | The time to live for the packet.

Remarks

The check succeeds only if all the classes found on the call stack possess NetIOPermissions, and if those permissions allow multicast operations on the specified address. This method overrides the java.lang.SecurityManager.checkMulticast(InetAddress,byte) method.

Exceptions

SecurityException if the security check fails.


checkMultimedia (StandardSecurityManager Class)

 Microsoft SDK for Java

checkMultimedia

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to utilize extended multimedia features.

Syntax

public synchronized void checkMultimedia();

Remarks

The check succeeds only if all the classes found on the call stack possess MultimediaPermissions. This method is currently used by the com.ms.directX APIs.

Exceptions

SecurityException if the security check fails.


checkPackageAccess (StandardSecurityManager Class)

 Microsoft SDK for Java

checkPackageAccess

This method of the StandardSecurityManager Class determines whether access to classes within the specified package is permitted. Package access is denied if a system property of the form package.restrict.access.packagename exists. This method overrides the java.lang.SecurityManager.checkPackageAccess(String) method.

Syntax

public void checkPackageAccess(String pkg);

Note Because of both the nature of class loaders and the fact that this check is made at load time instead of class resolution time, no specific contextual information can be extrapolated to determine who is attempting to access the specified package. Therefore, this check does not fit into the class-granular permissions model. Its results are based on a global state, so it will always return the same result, independent of the current execution context.

Parameters

pkg The name of the package to which access is being checked.

Exceptions

SecurityException if package access is prohibited.


checkPackageAccessFromClassName (StandardSecurityManager Class)

 Microsoft SDK for Java

checkPackageAccessFromClassName

This method of the StandardSecurityManager Class, if a security manager is installed, checks to see if applets can access classes located in the package that contains a specified class.

Syntax

public static void checkPackageAccessFromClassName(String classname);

Parameters

classname The name of the class from which the package to check is determined. The class name must be separated from the package name (if any) by a dot (.).

Remarks

The checkPackageAccess method of the current security manager is called to determine whether the package access is allowed. If a security manager is not installed, this method does nothing. If the class name does not specify a package, the call succeeds.

Note This method requires a full class name. Do not trim off the class name as you would when calling java.lang.SecurityManager.checkPackageAccess.

Exceptions

SecurityException if access to the package is prohibited.


checkPackageDefinition (StandardSecurityManager Class)

 Microsoft SDK for Java

checkPackageDefinition

This method of the StandardSecurityManager Class determines whether classes within the specified package can be defined.

Syntax

public synchronized void checkPackageDefinition(String pkg);

Parameters

pkg The name of the package that determines which package to check.

Remarks

The package definition is denied if a system property of the form package.restrict.definition.packagename exists. This method overrides the java.lang.SecurityManager.checkPackageAccess(String) method.

Note Because of both the nature of class loaders and the fact that this check is made at load time instead of class resolution time, no specific contextual information can be extrapolated to determine who is attempting to define a class in the specified package. Therefore, this check cannot fit into the class-granular permissions model. This check is based on a global state, and will always return the same result, independent of the current execution context.

Exceptions

SecurityException if the package definition is prohibited.


checkPackageDefinitionFromClassName (StandardSecurityManager Class)

 Microsoft SDK for Java

checkPackageDefinitionFromClassName

This method of the StandardSecurityManager Class, if a security manager is installed, checks to see if applets can define classes in the package of the specified class name.

Syntax

public static void checkPackageDefinitionFromClassName(String classname);

Parameters

classname The name of the class that determines which package to check. The class name must be separated from the package name (if any) by a dot (.).

Remarks

The checkPackageDefinition method of the current security manager is called to determine if the package definition is allowed. If the class name does not specify a package, the call will succeed. If a security manager is not installed, this method does nothing.

Note This method expects a full class name. Do not trim off the class name as you would when calling java.lang.SecurityManager.checkPackageDefinition.

Exceptions

SecurityException if the package definition is prohibited.

See Also

checkPackageDefinition


checkPrintJobAccess (StandardSecurityManager Class)

 Microsoft SDK for Java

checkPrintJobAccess

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to initiate a print job.

Syntax

public void checkPrintJobAccess();

Remarks

The check succeeds only if all the classes found on the call stack possess UIPermissions, and if those permissions allow printing. This method overrides the java.lang.SecurityManager.checkPrintJobAccess method.

Exceptions

SecurityException if the security check fails.


checkPropertiesAccess (StandardSecurityManager Class)

 Microsoft SDK for Java

checkPropertiesAccess

This method of the StandardSecurityManager Class determines whether the system properties object can be passed to the caller of the System.getProperties method.

Syntax

public void checkPropertiesAccess();

Remarks

The check succeeds only if all the classes found on the call stack possess PropertyPermissions and if those permissions grant unlimited system properties access. This method overrides the java.lang.SecurityManager.checkPropertiesAccess method.

Exceptions

SecurityException if the security check fails.


checkPropertyAccess (StandardSecurityManager Class)

 Microsoft SDK for Java

checkPropertyAccess

This method of the StandardSecurityManager Class determines if the specified system property can be read by all the classes within the current execution context.

Syntax

public void checkPropertyAccess(String key);

Parameters

key The system property for which read access is being checked.

Remarks

The check succeeds only if all the classes found on the call stack possess PropertyPermissions and those permissions allow read access to the specified property. This method overrides the java.SecurityManager.checkPropertyAccess method.

Exceptions

SecurityException if the security check fails.


checkRead (StandardSecurityManager Class)

 Microsoft SDK for Java

checkRead

The checkRead method of the StandardSecurityManager Class contains the following signatures:

checkRead(String file)
checkRead(URL url)
checkRead(String file, Object context)
checkRead(FileDescriptor fd)

checkRead(String file)

Determines whether the specified file can be read by the classes active within the current execution context.

Syntax

public void checkRead(String file);

Parameters

file The file for which permission to be read by active classes is being checked.

Remarks

The check succeeds if all the classes found on the call stack possess FileIOPermissions and those permissions allow read access to the specified file. This method overrides the java.lang.SecurityManager.checkRead(String) method.

Exceptions

SecurityException if the security check fails.

checkRead(URL url)

Determines whether the specified URL can be read by the code in the current execution context.

Syntax

public static void checkRead(URL url);

Parameters

url The URL for which permission to read is being checked.

Remarks

If the specified URL is a file:// URL, this method performs a checkRead(String file) to determine if the file specified by the URL can be read. Otherwise, this method performs a checkConnect(url.getHost(),url.getPort()) to determine if the host/port can be connected to.

Exceptions

SecurityException if the security check fails.

checkRead(String file, Object context)

Determines whether the specified file and the specified context object can be read by the classes within the current execution context. This method overrides the java.lang.SecurityManager.checkRead method.

Syntax

public void checkRead(String file, Object context);

Note The context object must be a URL object.

Parameters

file | The system-dependent file name.
context | The URL to be checked in addition to the file.

Exceptions

SecurityException if the file is not found.

checkRead(FileDescriptor fd)

Determines whether classes within the current execution context, based on the call stack of the current thread, can use the specified FileDescriptor object to read from the file it is associated with.

Syntax

public void checkRead(FileDescriptor fd);

Parameters

fd The file descriptor associated with the file from which permission to read is being checked.

Remarks

The check succeeds only if all the classes found on the call stack are fully trusted system classes. This method overrides the java.lang.SecurityManager.checkRead(FileDescriptor) method.

Exceptions

SecurityException if the security check fails.


checkRegistry (StandardSecurityManager Class)

 Microsoft SDK for Java

checkRegistry

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to perform the specified access to the specified portion of the registry.

Syntax

public void checkRegistry(int access, String value);

access | The access type.
value | The registry key.

Remarks

The check succeeds only if all the classes found on the call stack possess RegistryPermissions, and if those permissions allow the specified access type onto the specified portion of the registry.

Exceptions

SecurityException if the security check fails.

See Also

com.ms.lang.RegKey


checkSecurityAccess (StandardSecurityManager Class)

 Microsoft SDK for Java

checkSecurityAccess

This method of the StandardSecurityManager Class determines if classes within the current execution context, based on the call stack of the current thread, are allowed to perform a security provider-related operation (using the java.security classes).

Syntax

public void checkSecurityAccess(String provider);

The check succeeds only if all the classes found on the call stack possess SecurityPermissions. This method overrides the java.lang.SecurityManager.checkSecurityAccess(String) method.

Note This check is used by the JDK security-related APIs within the java.security classes. It is not directly relevant to the Microsoft® security model.

Parameters

provider This parameter is ignored.


checkSetFactory (StandardSecurityManager Class)

 Microsoft SDK for Java

checkSetFactory

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to install a networking object factory.

Syntax

public void checkSetFactory();

Remarks

The check succeeds only if all the classes found on the call stack are fully trusted. This method overrides the java.lang.SecurityManager.checkSetFactory method.

Exceptions

SecurityException if the security check fails.


checkSystemClipboardAccess (StandardSecurityManager Class)

 Microsoft SDK for Java

checkSystemClipboardAccess

This method of the StandardSecurityManager Class determines whether classes within the current execution context, based on the call stack of the current thread, are allowed to access the system Clipboard.

Syntax

public void checkSystemClipboardAccess();

Remarks

The check succeeds only if all the classes found on the call stack possess UIPermissions, and if those permissions allow access to the system Clipboard. This method overrides the java.lang.SecurityManager.checkSystemClipboardAccess method.

Exceptions

SecurityException if the security check fails.


checkSystemStreams (StandardSecurityManager Class)

 Microsoft SDK for Java

checkSystemStreams

This method of the StandardSecurityManager Class determines if classes within the current execution context, based on the call stack of the current thread, are allowed to set the specified system stream.

Syntax

public void checkSystemStreams(int streamID);

Parameters

streamID The system stream to set. The value must be one of the following:

0

Indicates an attempt to set System.in using System.setIn.

1

Indicates an attempt to set System.out using System.setOut.

2

Indicates an attempt to set System.err using System.setErr.

Remarks

The check succeeds only if all the classes found on the call stack possess SystemStreamsPermissions, and if those permissions allow the specified stream to be modified.

This security check is called by the java.lang.System APIs that set system streams using the System.setIn, System.setOut, and System.setErr methods.

Exceptions

SecurityException if the security check fails.


checkTopLevelWindow (StandardSecurityManager Class)

 Microsoft SDK for Java

checkTopLevelWindow

This method of the StandardSecurityManager Class determines if classes within the current execution context, based on the call stack of the current thread, are allowed to create top-level windows.

Syntax

public boolean checkTopLevelWindow(Object window);

Return Value

Returns false if top-level window creation is allowed and a top-level window requires a warning banner; otherwise, returns true.

Parameters

window The top-level window.

Remarks

The check succeeds only if all the classes found on the call stack possess UIPermission, and if all those permissions allow the creation of top-level windows. If top-level window creation is not allowed, a SecurityException is thrown.

If top-level window creation is allowed, this check determines whether the top-level window for each calling class requires no warning banner. No warning banner is required if all the UIPermission objects associated with the calling classes specify that no warning banners are necessary.

This method overrides the java.lang.SecurityManager.checkTopLevelWindow method.

Exceptions

SecurityException if the security check fails.


checkWrite (StandardSecurityManager Class)

 Microsoft SDK for Java

checkWrite

The checkWrite method of the StandardSecurityManager Class contains the following signatures:

checkWrite(String file)
checkWrite(FileDescriptor fd)

checkWrite(String file)

Determines whether the specified file can be written to by the classes active within the current execution context.

The check succeeds only if all the classes found on the call stack possess FileIOPermissions and if those permissions allow write access to the specified file. This method overrides the java.lang.SecurityManager.checkWrite(String) method.

Syntax

public void checkWrite(String file);

Parameters

file The system-dependent file name.

Exceptions

SecurityException if the security check fails.

checkWrite(FileDescriptor fd)

Determines whether classes within the current execution context, based on the call stack of the current thread, can use the specified FileDescriptor object to write to the file it is associated with.

Syntax

public void checkWrite(FileDescriptor fd);

Parameters

fd The file descriptor that is associated with the file.

Remarks

The check succeeds only if all the classes found on the call stack are fully trusted system classes. This method overrides the java.lang.SecurityManager.checkWrite(FileDescriptor) method.

Exceptions

SecurityException if the security check fails.


getSecurityContext (StandardSecurityManager Class)

 Microsoft SDK for Java

getSecurityContext

This method of the StandardSecurityManager Class retrieves the codebase URL associated with the nearest SecurityClassLoader instance found on the call stack. The SecurityClassLoader instance is found by examining the classes associated with each stack frame, and then examining the class loader associated with each class.

Syntax

public Object getSecurityContext();

Return Value

Returns the URL associated with the nearest SecurityClassLoader instance.


getThreadGroup (StandardSecurityManager Class)

 Microsoft SDK for Java

getThreadGroup

This method of the StandardSecurityManager Class determines the active thread group based on the current execution context.

Syntax

public ThreadGroup getThreadGroup();

Return Value

Returns the active thread group.

Remarks

This method overrides the java.lang.SecurityManager.getThreadGroup method. This method is called by the constructors of the java.lang.Thread class. Its purpose is to ensure that new threads are created in the thread group associated with the active code instead of in the thread group of the current thread.

To understand why this scheme is useful, consider the AWT event dispatch thread, which is a system thread that lives in the system thread group. If an applet creates a new thread while executing code on the dispatch thread, the new thread will be created in the thread group associated with that applet. If, instead, an attempt had been made to create the thread in the system thread group, it is likely that the attempt would have failed because the applet code probably does not have access rights to the system thread group.

The algorithm for determining the active thread group is as follows.

  1. Based on the classes associated with each stack frame on the call stack, locate the nearest SecurityClassLoader instance.

  2. If no SecurityClassLoader is found, the active thread group is simply the thread group of the current thread, as follows:
Thread.currentThread().getThreadGroup()
  3. Otherwise, a SecurityClassLoader instance was found. If the thread group of the current thread is a child of the thread group associated with that loader, return it. Otherwise, return the thread group associated with the loader.


installStandardSecurity (StandardSecurityManager Class)

 Microsoft SDK for Java

installStandardSecurity

This method of the StandardSecurityManager Class creates a new StandardSecurityManager and installs it as the active security manager.

Syntax

public static void installStandardSecurity();

Exceptions

SecurityException if a security manager is already installed.


IAdjustablePermission Interface (com.ms.security Package)

 Microsoft SDK for Java

IAdjustablePermission Interface

The IAdjustablePermission Interface of the com.ms.security package provides a method for modifying a permission object to give context information.

public interface IAdjustablePermission
{
  // Methods
  void adjustPermission(String tag, Object adjustment);
}


Methods (IAdjustablePermission Interface)

 Microsoft SDK for Java

IAdjustablePermission Interface Methods

The IAdjustablePermission Interface contains the following method:

adjustPermission modifies the permission object so that it gives context information.


adjustPermission (IAdjustablePermission Interface)

 Microsoft SDK for Java

adjustPermission

This method of the IadjustablePermission Interface modifies the permission object so that it gives context information. The tag parameter identifies the type of adjustment being made. The adjustment parameter is an object specific to the type of adjustment being made.

Syntax

void adjustPermission(String tag, Object adjustment);

Parameters

tag | The adjustment type (see table of values below).
adjustment | The adjustment object.

The following table lists the values for the tag parameter that are recognized by the system permissions, and it also describes the corresponding adjustment objects.

Note If this method is called with an adjustment object that it does not recognize, the method does nothing. No exception is thrown.

Values for the tag Parameter

codebase | The adjustment object is the java.net.URL instance that specifies where classes that will possess the permission are loaded from. The networking I/O permission class (com.ms.security.permissions.NetIOPermission) and file I/O permission class (com.ms.security.permissions.FileIOPermission) respond to this adjustment type.
classloader | The adjustment object is the java.lang.ClassLoader instance used to load the classes that will possess the permission. The reflection permission class (com.ms.security.permissions.ReflectionPermission) responds to this adjustment type.
thread group | The adjustment object is the java.lang.ThreadGroup instance that the classes with the permission should have access to. The threading permission class (com.ms.security.permissions.ThreadPermission) responds to this adjustment type.


IEncodablePermission Interface (com.ms.security Package)

 Microsoft SDK for Java

IEncodablePermission Interface

The IEncodablePermission Interface of the com.ms.security package provides methods that allow permissions to represent their internal state in any desired format. For example, a permission can encode itself into an arbitrary binary format or a textual format.

public interface IEncodablePermission
{
  // Methods
  boolean decode(String tag, InputStream data);
  boolean encode(String tag, OutputStream data);
  String mapFormat(String format);
  String[] supportedFormats();
}

The contract with the caller of the IEncodablePermission interface can be described in the following way:

  • The caller can obtain a tag for a specified format, and then call the encode and decode methods with that tag.

  • If a caller chooses to persist the encoding, the caller must store the tag along with the encoding.

  • To decode the persisted encoding, the caller must get the tag from its storage location, and then pass it (along with the encoding) to the decode method.

  • The caller can request the tag for a specified format using the mapFormat method.

  • If the specified format is not available, the caller can obtain the default tag by passing null to the mapFormat method.

  • If the caller does not recognize the format, the caller must be able to store the default encoding in an opaque manner (as binary data of an arbitrary length).

  • An instance of any class that implements the IEncodablePermission interface is guaranteed that its default encoding can be stored.

The tag is defined by a class that implements the IEncodablePermission interface and is meaningful only to that class. It is not meaningful to any other IEncodablePermission class. The tag allows the object to do version control and to handle multiple types of encodings. The tag is an arbitrary string that the permission class decides on. It is likely that the string will contain some type of version information; its form is determined by the permission class.

This interface is useful for developers who write Java packages that are digitally signed. When the package is installed on a client's computer, the user gets a dialog box asking for permission to access certain resources. The permission needs to be attached to the digital signature so that the security system can determine what permissions are needed. The developer should create a permission class that implements IEncodablePermission. The signcode tool takes the name of the permission class, creates an instance of it, and then calls the encode method of the permission class to cause the instance to encode itself. This encoding is stored inside the digital signature, which is then attached to a package.

The security system within the Microsoft VM gets the encoding from the signature and creates an instance of the permission class. It then calls the class's decode method, passing in the tag that was used at the time of signing (the tag is part of the signature's encoding). Because signatures are static, and because the permission class can be located in any package, the current implementation of the permission class can determine what version of the IEncodablePermission class was encoded with the tag.

For example, suppose you created a package of classes that manipulate SQL databases. This package might contain applets that access portions of the database, based on a table name. You could create a database permission class called DBPermission that stores the name of an SQL table. Then you would sign each applet with the DBPermission, asking for a specific table. The DBPermission class would then be distributed with your package, and the applets are sent to Web sites that are accessed by users.

You might, at some point, enhance your package by adding the ability to restrict access to particular rows and columns of a database. You would then update your permission class to keep track of the rows and columns that can be accessed. New applets would be signed with the new permission. However, the old applets might still be in use on the Internet, signed with the old permission. The tag provides a way to identify the version used to encode a permission class.

If permissions that implement the IEncodablePermission interface are inserted into a PermissionDataSet object so that they can be used in digital signatures, the signing tool will find out whether the permissions support ASN1 format. If ASN1 is not supported, the class's default encoding will be used.


Methods (IEncodablePermission Interface)

 Microsoft SDK for Java

IEncodablePermission Interface Methods

The IEncodablePermission Interface contains the following methods:

decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
mapFormat retrieves a permission-specific tag, given an encoding format.
supportedFormats retrieves the encoding formats that the permission type supports.


decode (IEncodablePermission Interface)

 Microsoft SDK for Java

decode

This method of the IEncodablePermission Interface decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (IEncodablePermission Interface)

 Microsoft SDK for Java

encode

This method of the IEncodablePermission Interface encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

boolean encode(String tag, OutputStream data);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The output stream to send the encoded data to.


mapFormat (IEncodablePermission Interface)

 Microsoft SDK for Java

mapFormat

This method of the IEncodablePermission Interface retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


supportedFormats (IEncodablePermission Interface)

 Microsoft SDK for Java

supportedFormats

This method of the IencodablePermission Interface retrieves the encoding formats that the permission type supports.

Syntax

String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


IPermission Interface (com.ms.security Package)

 Microsoft SDK for Java

IPermission Interface

The IPermission Interface of the com.ms.security package must be implemented by all classes that represent permissions. Instances of the classes that implement this interface can be used as permissions that are attached to classes and used to perform security checks.

public interface IPermission extends com.ms.util.SetComparison
{
  // Methods
  void check(Object request) throws SecurityException ;
  IPermission combine(IPermission other) ;
  IPermission copy() ;
}

Hierarchy

SetComparison
  |
  +--IPermission


Methods (IPermission Interface)

 Microsoft SDK for Java

IPermission Interface Methods

The IPermission Interface contains the following methods:

check determines whether the permission object allows the specified action.
combine creates and returns a new permission object that is a combination of the current permission object and the specified permission object.
copy creates a new permission object that is equivalent to the current one.


check (IPermission Interface)

 Microsoft SDK for Java

check

This method of the IPermission Interface determines whether the permission object allows the specified action. The request parameter represents a request to perform a particular action. The type of the request parameter depends on the type of the permission object that is being checked.

Syntax

void check(Object request) throws SecurityException ;

Parameters

request The object that represents the action for which permission is being checked.

Exceptions

SecurityException if the state of the permission object indicates that the action is not allowed.


combine (IPermission Interface)

 Microsoft SDK for Java

combine

This method of the IPermission Interface creates and returns a new permission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

IPermission combine(IPermission other) ;

Return Value

Returns the resulting permission object.

Parameters

other The permission object that indicates additional resources to allow access to.

Exceptions

IllegalArgumentException if the specified permission object is not of the same type as the permission object it is being combined with.


copy (IPermission Interface)

 Microsoft SDK for Java

copy

This method of the IPermission Interface creates a new permission object that is equivalent to the current one. The copy operation is deep so that modifications to the copy do not affect the behavior of the original object.

Syntax

IPermission copy() ;

Return Value

Returns a permission object that is a copy of the current one.


ISecurityRequest Interface (com.ms.security Package)

 Microsoft SDK for Java

ISecurityRequest Interface

The ISecurityRequest Interface of the com.ms.security package is used to associate specific types of objects with specific permission types.

public interface ISecurityRequest
{
  // Methods
  PermissionID getPermissionID();
}

For parameterized security checks, the basic PolicyEngine APIs require you to specify both the type of permission to check, and the security request object to pass to the IPermission.check methods. However, there are also variations of the PolicyEngine check methods that take an ISecurityRequest object instead. The ISecurityRequest object identifies the permission type and also represents the security request object.

For example, the FileIORequest class implements the ISecurityRequest interface (returning PermissionID.FILEIO), so the following security checks are equivalent to each other:

  ...
  // Create an ISecurityRequest object.
  FileIORequest sreq = new FileIORequest(FileIORequest.READ,"c:\\MySample.txt");

  // The first security check.
  // The permission type is explicitly specified.
  // Use the checkPermission(PermissionID,Object) method
  // to check permissions.
  PolicyEngine.checkPermission(PermissionID.FILEIO,sreq);

  // The second security check.
  // PolicyEngine determines the permission type from
  // the FileIORequest object. It performs the same check as
  // above.
  //
  // Use the checkPermission(ISecurityRequest) method
  // to check permissions.
  PolicyEngine.checkPermission(sreq);


Methods (ISecurityRequest Interface)

 Microsoft SDK for Java

ISecurityRequest Interface Methods

The IsecurityRequest Interface contains the following method:

getPermissionID retrieves the permission type associated with the object.


getPermissionID (ISecurityRequest Interface)

 Microsoft SDK for Java

getPermissionID

This method of the ISecurityRequest Interface retrieves the permission type associated with the object.

Syntax

PermissionID getPermissionID();

Return Value

Returns the permission type associated with the object.


com.ms.security.auditing Package Overview

Microsoft Packages Overview

The com.ms.security.auditing package provides an interface that allows an auditor to determine how a security request should be displayed.

This package contains the following:

Interfaces

Hierarchy


Interfaces (com.ms.security.auditing)

 Microsoft SDK for Java

com.ms.security.auditing Package Interfaces

The com.ms.security.auditing package contains the following interface:

ISecurityAuditInfo Interface provides information to a security auditor about an audited security request.


Hierarchy (com.ms.security.auditing)

 Microsoft SDK for Java

com.ms.security.auditing Package Hierarchy

The com.ms.security.auditing package has the following hierarchy:

ISecurityAuditInfo


ISecurityAuditInfo Interface (com.ms.security.auditing Package)

 Microsoft SDK for Java

ISecurityAuditInfo Interface

The ISecurityAuditInfo Interface of the com.ms.security.auditing package provides information to a security auditor about an audited security request.

public interface ISecurityAuditInfo
{
  // Methods
  String[] getAuditDetails();
  String getAuditIdentifier();
}

It is implemented by request objects that are passed to any of the parameterized security checks of com.ms.security.PolicyEngine. If the system is configured to audit the request, the auditor uses the information from this interface to determine how to display the request.


Methods (ISecurityAuditInfo Interface)

 Microsoft SDK for Java

ISecurityAuditInfo Interface Methods

The ISecurityAuditInfo Interface contains the following methods:

getAuditDetails retrieves strings that describe the parameters of the request.
getAuditIdentifier retrieves a string that identifies the type of the audit event.


getAuditDetails (ISecurityAuditInfo Interface)

 Microsoft SDK for Java

getAuditDetails

This method of the ISecurityAuditInfo Interface retrieves strings that describe the parameters of the request. If a localized message for the request is available, the retrieved strings will be used to fill in any placeholders in the message.

Syntax

String[] getAuditDetails();

Return Value

Returns an array of strings that describe the request. If there are no parameters to describe, this method returns null.


getAuditIdentifier (ISecurityAuditInfo Interface)

 Microsoft SDK for Java

getAuditIdentifier

This method of the ISecurityAuditInfo Interface retrieves a string that identifies the type of the audit event.

Syntax

String getAuditIdentifier();

Return Value

Returns a string that identifies the audit event.

Remarks

The string retrieved will have property or package-like conventions. For example, "com.xyz.database.query.invalid" is a valid return string for this method. An auditor could use the returned string to select a localized format string for displaying the event or for determining types of events to log.


com.ms.security.permissions Package Overview

Microsoft Packages Overview

The com.ms.security package contains classes used to represent two types of objects: permission objects and ISecurityRequest objects. This overview discusses Permission Objects, ISecurityRequest Objects, Using ISecurityRequest Objects to Perform Security Checks, and Implementing a Custom Permission.

This package contains the following:

Classes

Hierarchy

Permission Objects

A permission object is an object that specifies a set of rights that can be associated with a class. Classes that represent permission objects must implement the IPermission interface. The com.ms.security.permissions package supplies several classes that represent permission objects. Each of these classes controls the ability to perform certain operations, as described in the following table.

Permission Objects Classes

ClientStoragePermission | Controls access to client-side storage.
ExecutionPermission | Controls the ability to run other programs.
FileIOPermission | Controls the ability to read, write, and delete files.
MultimediaPermission | Controls access to enhanced multimedia functionality.
NetIOPermission | Controls the ability to perform networking operations.
PrintingPermission | Controls the ability to print.
PropertyPermission | Controls the ability to access and manipulate global system properties.
ReflectionPermission | Controls the ability to perform reflection operations.
RegistryPermission | Controls the ability to access the registry.
SecurityPermission | Controls access to the java.lang.security package.
SystemStreamsPermission | Controls the ability to change the values of system streams.
ThreadPermission | Controls the ability to create and manipulate threads and thread groups.
UIPermission | Controls access to enhanced user interface functionality.
UserFileIOPermission | Controls the ability to perform user-directed file I/O.

To associate a group of permission objects with a class, you would bundle the objects together in a set (either a PermissionDataSet or a PermissionSet) and then use SecurityClassLoader methods to associate the set of permissions with a particular class. The security system for the Microsoft VM can then examine the permissions associated with the classes on the call stack to determine which permissions are allowed in a particular context. To see an example that creates a set of permissions, puts them in a PermissionSet, and then associates the PermissionSet with a class, see the Examples section of the com.ms.security overview.

ISecurityRequest Objects

An ISecurityRequest object is an instance of a class that implements the ISecurityRequest interface. The com.ms.security.permissions package supplies classes that implement the ISecurityRequest interface. These classes represent objects that have two purposes: they identify a permission type and they also represent the parameters relevant to the permission type. The following table lists each of these classes along with the permission type that each class identifies.

ISecurity Request Objects Classes

ExecutionRequest | PermissionID.EXEC
FileIORequest | PermissionID.FILEIO
NetIORequest | PermissionID.NETIO
PropertyAccessRequest | PermissionID.PROPERTY
ReflectionRequest | PermissionID.REFLECTION
RegistryRequest | PermissionID.REGISTRY
UIAccessRequest | PermissionID.UI
UserFileIOAccess | PermissionID.USERFILEIO

Instances of classes that implement ISecurityRequest are passed to PolicyEngine.checkPermission(ISecurityRequest) methods to do security checks for their respective permission types. An ISecurityRequest object contains parameters that are passed to the permission's check method. For example, to check for the registry permission, you should create and pass a RegistryRequest object to the PolicyEngine.checkPermission(ISecurityRequest) method. The parameters specified by the RegistryRequest object will be passed on to the RegistryPermission.check method.

Using ISecurityRequest Objects to Perform Security Checks

Example

To perform a non-parameterized security check such as a check for PrintingPermission, you would simply call the PolicyEngine.checkPermission(PermissionID) method, as in the following example:

// Check to see that all of your
// callers have the rights to print.
PolicyEngine.checkPermission(PermissionID.PRINTING);

Example

To perform a parameterized security check, you must past a security request object of the correct type to the PolicyEngine.checkPermission method. If the permission being checked is one of the permissions that has a corresponding ISecurityRequest object, then you should create the appropriate ISecurityRequest object and then pass it to the PolicyEngine.checkPermission(ISecurityRequest) method. The following example shows how to use a FileIORequest object to perform a security check that determines whether a file called "c:\\MyFile.txt" can be deleted:

...
// Create a FileIORequest object that indicates that you
// want to delete the file called "c:\\MyFile.txt".
FileIORequest sreq =
   new FileIORequest(FileIORequest.DELETE,"c:\\MyFile.txt");

// Check to see that all of your callers
// have the rights to delete that file.
PolicyEngine.checkPermission(sreq);
...

For parameterized security checks for a permission that does not have a predefined ISecurityRequest class (such as ThreadPermission), you must pass to the PolicyEngine.checkPermission method the PermissionID (or the name of the permission) and an Object whose type depends on the type of permission being checked. For example, to check for ThreadPermission, you would pass PermissionID.THREAD and an Object of type Thread or ThreadGroup. In general, to find out what type of Object to pass to the checkPermission method, consult the documentation for the check method of the permission you want to check.

If a security check fails, a SecurityExceptionEx is thrown. For more information about how security checks are implemented by the Microsoft VM, see the PolicyEngine class.

Implementing a Custom Permission

There may be times when you want to implement your own permission class. As mentioned above, every permission class must implement the IPermission interface. In addition, a custom permission class may need to implement the interfaces shown in the following table.

Custom Permission Class Interfaces

IencodablePermission | If instances of your custom permission class need to be encoded for storage in a digital signature, your permission class should implement the IEncodablePermission interface. The IEncodablePermission interface can also be implemented to allow a user-friendly name for the class to be displayed in security dialog boxes.
IadjustablePermission | If instances of your custom permission class need to contain context information, the permission class must implement the IAdjustablePermission interface.

The following code shows how to implement a custom permission class called NamePermission that keeps track of names that are allowed. Notice that NamePermission implements the mandatory IPermission interface.

package MyPackage;
import com.ms.security.*;

public class NamePermission implements IPermission
{
  String[] allowedNames;

  void setAllowedNames(String[] names)
  {
  // Copy the array of allowed names.
  int len = names.length;
  allowedNames = new String[len];
  System.arraycopy(names,0,allowedNames,0,len);
  }

  void check(Object request) throws SecurityException
  {
  // See if the Object is a String.
  if (!(request instanceof String) )
  throw new IllegalArgumentException("Illegal argument.");

  // See if the name is in the array of allowed names.
  for (int i= 0; i < allowedNames.length; i++ )
    if (allowedNames[i].equals( (String)request ) )
      return;

  // Not in the list, so throw exception.
  throw new SecurityException("Security check failed.");
  }

  IPermission copy()
  {
  // Create a new NamePermission object.
  NamePermission copy = new NamePermission();

  // Initialize the copy with the
  // allowed names.
  copy.setAllowedNames(allowedNames);

  return copy;
  }

  IPermission combine(IPermission other)
  {
  // See if the other permission
  // object is of the right type.
  if(!(other instanceof NamePermission))
     throw new IllegalArgumentException("Illegal argument.");

  // Create a NamePermission object.
  NamePermission comb = new NamePermission();

  // Combine the two permission objects.
  comb.allowedNames =
    PermissionUtils.combineArraysOfStrings(this.allowedNames,
                       ((NamePermission)other).allowedNames);

  // Return the combination.
  return comb;
  }

  int compare(IPermission other)
  {
  //
  if (!(other instanceof NamePermission))
     throw new IllegalArgumentException("Illegal argument.");

  // Return the result of comparing the names
  // allowed by the two permission objects.
  return PermissionUtils.compareArraysOfStrings(this.allowedNames,
                            ((NamePermission)other).allowedNames);
  }
}

You could then determine whether a particular name (such as "Pat") is allowed.

// Create a security request object.
String name = "Pat";

// Do the security check, passing
// in the security request object.
PolicyEngine.checkPermission("MyPackage.NamePermission",name);


Classes (com.ms.security.permissions Package)

 Microsoft SDK for Java

com.ms.security.permissions Package Classes

The com.ms.security.permissions package contains the following classes:

ClientStoragePermission Class represents a permission for controlling access to client-side storage that is available through the ClientStore class.

ExecutionPermission Class represents a permission that controls the ability to run other programs.

ExecutionRequest Class represents a request to execute an application.

FileIOPermission Class represents a permission that controls the ability to access files.

FileIORequest Class represents a request for access to the file system.

MultimediaPermission Class represents a permission that allows the use of enhanced multimedia functionality.

NetIOPermission Class represents a permission that controls the ability to perform networking operations.

NetIORequest Class represents a request to perform a network-related action.

PrintingPermission Class represents a permission that controls access to the printing APIs.

PropertyAccessRequest Class represents a request to access the system properties.

PropertyPermission Class represents a permission that controls the ability to access and manipulate the global system properties.

ReflectionPermission Class represents a permission that controls the ability to perform reflection operations.

ReflectionRequest Class represents a request to use the reflection APIs to gain access to members of a specified class.

RegistryPermission Class represents a permission that controls the ability to access the registry.

RegistryRequest Class represents a request for access to a registry key.

SecurityPermission Class represents a permission that controls access to the JDK security classes (the java.lang.security package).

SystemStreamsPermission Class represents a permission that controls the ability to change the values of the system streams java.lang.System.in, java.lang.System.out, and java.lang.System.err.

ThreadPermission Class represents a permission that controls the ability to create and manipulate threads and thread groups.

UIAccessRequest Class represents objects that indicate a request to use an extended aspect of the user interface APIs.

UIPermission Class represents a permission that controls the ability to use some of the enhanced functionality of the AWT.

UserFileIOAccess Class represents a request to perform a user-directed file I/O operation.

UserFileIOPermission Class represents a permission that controls the ability to perform user-directed file I/O operations using the UserFileDialog class.


Hierarchy (com.ms.security.permissions Package)

 Microsoft SDK for Java

com.ms.security.permissions Package Hierarchy

The com.ms.security.permissions package has the following hierarchy:

Object
  |
  +--ClientStoragePermission (IPermission, IEncodablePermission, Cloneable)
  |
  +--ExecutionPermission (IPermission, IEncodablePermission)
  |
  +--ExecutionRequest (ISecurityRequest)
  |
  +--FileIOPermission (IPermission, IEncodablePermission, IAdjustablePermission)
  |
  +--FileIORequest (ISecurityRequest)
  |
  +--MultimediaPermission (IPermission, IEncodablePermission)
  |
  +--NetIOPermission (IPermission, IEncodablePermission, IAdjustablePermission)
  |
  +--NetIORequest (ISecurityRequest)
  |
  +--PrintingPermission (IPermission, IEncodablePermission)
  |
  +--PropertyAccessRequest (ISecurityRequest)
  |
  +--PropertyPermission (IPermission, IEncodablePermission)
  |
  +--ReflectionPermission (IPermission, IEncodablePermission, IAdjustablePermission)
  |
  +--ReflectionRequest (ISecurityRequest)
  |
  +--RegistryPermission (IPermission, IEncodablePermission)
  |
  +--RegistryRequest (ISecurityRequest)
  |
  +--SecurityPermission (IPermission, IEncodablePermission)
  |
  +--SystemStreamsPermission (IPermission, IEncodablePermission)
  |
  +--ThreadPermission (IPermission, IEncodablePermission, IAdjustablePermission)
  |
  +--UIAccessRequest (ISecurityRequest)
  |
  +--UIPermission (IPermission, IEncodablePermission)
  |
  +--UserFileIOAccess (ISecurityRequest)
  |
  +--UserFileIOPermission (IPermission, IEncodablePermission)


ClientStoragePermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

ClientStoragePermission Class

The ClientStoragePermission Class of the com.ms.security.permissions package represents a permission for controlling access to client-side storage that is available through the ClientStore class.

public class ClientStoragePermission implements IPermission,
            IEncodablePermission, Cloneable
{
  // Fields
  public static final int FL_CANROAM;
  public static final int FL_GLOBALEXEMPT;

  // Constructors
  public ClientStoragePermission();
  public ClientStoragePermission(long limit);
  public ClientStoragePermission(long limit, int flags);

  // Methods
  public void check(Object request) throws SecurityException;
  public IPermission combine(IPermission source2);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public int getFlags();
  public long getStorageLimit();
  public String mapFormat(String format);
  public void reset();
  public void setFlags(int flags);
  public void setStorageLimit(long limit);
  public String[] supportedFormats();
  public String toString();
}

The ClientStoragePermission permission specifies a limit on the total amount of data that can be written. If the FL_GLOBALEXEMPT flag has been specified, the limit is an absolute limit. If the limit has not been specified, the amount of data written is also bounded by the global limit.

If the FL_CANROAM flag has been specified, "roaming" files can be created. Roaming files are created in the user's profile and are present on any computer the user is logged on to.


Constructors (ClientStoragePermission Class)

 Microsoft SDK for Java

ClientStoragePermission Class Constructors

The ClientStoragePermission Class contains the following constructors:

ClientStoragePermission()
ClientStoragePermission(long limit)
ClientStoragePermission(long limit, int flags)

ClientStoragePermission()

Creates a new ClientStoragePermission instance. The client storage allowed to classes with this permission has no storage space limits.

Syntax

public ClientStoragePermission();

ClientStoragePermission(long limit)

Creates a new ClientStoragePermission instance.

Syntax

public ClientStoragePermission(long limit);

Parameters

limit The client storage space limit.

Remarks

The client storage allowed to classes with this permission is limited to the specified amount of client storage space.

ClientStoragePermission(long limit, int flags)

Creates a new ClientStoragePermission instance.

Syntax

public ClientStoragePermission(long limit, int flags);

Parameters

limit | The client storage space limit.
flags | The flags that can affect the type of client storage that classes with this permission have. They can be one or both of the following: FL_CANROAM and FL_GLOBALEXEMPT.

Remarks

The client storage allowed to classes with this permission are limited to the specified amount of client storage space.


Methods (ClientStoragePermission Class)

 Microsoft SDK for Java

ClientStoragePermission Class Methods

The ClientStoragePermission Class contains the following methods:

check does nothing for this permission.
combine creates and returns a new ClientStoragePermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the ClientStoragePermission instance with a specified permission object.
copy retrieves a copy of the ClientStoragePermission object.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
getFlags retrieves the flags that control access to storage.
getStorageLimit obtains the limit on the amount of data that can be stored.
mapFormat retrieves a permission-specific tag when given an encoding format.
reset resets the permission so that no special flags are active and there is no storage space limit.
setFlags sets flags for controlling access to storage.
setStorageLimit sets a limit on the amount of data that can be stored.
supportedFormats retrieves the encoding formats that the permission type supports.
toString retrieves a textual representation of the permission object.


check (ClientStoragePermission Class)

 Microsoft SDK for Java

check

This method of the ClientStoragePermission Class does nothing for this permission.

Syntax

public void check(Object request) throws SecurityException;

Parameters

request This parameter is ignored.


combine (ClientStoragePermission Class)

 Microsoft SDK for Java

combine

This method of the ClientStoragePermission Class creates and returns a new ClientStoragePermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission source2);

Return Value

Returns the resulting ClientStoragePermission object.

Parameters

source2 The other ClientStoragePermission object to combine with.

Exceptions

IllegalArgumentException if the specified object to combine with is not an instance of ClientStoragePermission.


compareSet (ClientStoragePermission Class)

 Microsoft SDK for Java

compareSet

This method of the ClientStoragePermission Class compares the ClientStoragePermission instance with a specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the ClientStoragePermission instance is compared with.


copy (ClientStoragePermission Class)

 Microsoft SDK for Java

copy

This method of the ClientStoragePermission Class retrieves a copy of the ClientStoragePermission object.

Syntax

public IPermission copy();

Return Value

Returns the copy of the ClientStoragePermission object.


decode (ClientStoragePermission Class)

 Microsoft SDK for Java

decode

This method of the ClientStoragePermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (ClientStoragePermission Class)

 Microsoft SDK for Java

encode

This method of the ClientStoragePermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


getFlags (ClientStoragePermission Class)

 Microsoft SDK for Java

getFlags

This method of the ClientStoragePermission Class retrieves the flags that control access to storage.

Syntax

public int getFlags();

Return Value

Returns one or both of the flags that control storage access: FL_GLOBALEXEMPT and FL_CANROAM.


getStorageLimit (ClientStoragePermission Class)

 Microsoft SDK for Java

getStorageLimit

This method of the ClientStoragePermission Class obtains the limit on the amount of data that can be stored.

Syntax

public long getStorageLimit();

Return Value

Returns The storage limit in bytes.


mapFormat (ClientStoragePermission Class)

 Microsoft SDK for Java

mapFormat

This method of the ClientStoragePermission Class retrieves a permission-specific tag when given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


reset (ClientStoragePermission Class)

 Microsoft SDK for Java

reset

This method of the ClientStoragePermission Class resets the permission so that no special flags are active and there is no storage space limit.

Syntax

public void reset();


setFlags (ClientStoragePermission Class)

 Microsoft SDK for Java

setFlags

This method of the ClientStoragePermission Class sets flags for controlling access to storage.

Syntax

public void setFlags(int flags);

Parameters

flags The values that control storage access. They must be one or both FL_GLOBALEXEMPT and FL_CANROAM.


setStorageLimit (ClientStoragePermission Class)

 Microsoft SDK for Java

setStorageLimit

This method of the ClientStoragePermission Class sets a limit on the amount of data that can be stored.

Syntax

public void setStorageLimit(long limit);

Parameters

limit The amount of data that can be stored.

Remarks

If the FL_GLOBALEXEMPT flag is in effect, this limit is an absolute limit; otherwise, the amount of data stored is also bounded by the global limit.


supportedFormats (ClientStoragePermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the ClientStoragePermission Class retrieves the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (ClientStoragePermission Class)

 Microsoft SDK for Java

toString

This method of the ClientStoragePermission Class retrieves a textual representation of the permission object.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


Fields (ClientStoragePermission Class)

 Microsoft SDK for Java

ClientStoragePermission Class Fields

The ClientStoragePermission Class contains the following fields.

FL_CANROAM | The value that indicates that classes with this permission can create roaming files.
FL_GLOBALEXEMPT | The value that indicates that classes with this permission are not subject to the global scratch space limit.


ExecutionPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

ExecutionPermission Class

The ExecutionPermission Class of the com.ms.security.permissions package represents a permission that controls the ability to run other programs. The StandardSecurityManager checks for this permission type when performing the checkExec operation.

public class ExecutionPermission implements IPermission,
            IEncodablePermission
{
  // Constructors
  public ExecutionPermission();

  // Methods
  public void check(Object param);
  public IPermission combine(IPermission other);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public void excludeApplications(String pattern);
  public WildcardExpression getExcludedApplications();
  public WildcardExpression getIncludedApplications();
  public void includeApplications(String pattern);
  public boolean isUnrestricted();
  public String mapFormat(String format);
  public void reset();
  public void setUnrestricted(boolean flag);
  public String[] supportedFormats();
  public String toString();
}

See Also

com.ms.security.permissions.ExecutionRequest


Constructors (ExecutionPermission class)

 Microsoft SDK for Java

ExecutionPermission Class Constructors

The ExecutionPermission Class contains the following constructor:

ExecutionPermission()

Syntax

public ExecutionPermission();

Creates a new ExecutionPermission instance.

Remarks

The new instance does not allow access for executing applications. Use either the setUnrestricted or includeApplications methods to add applications to the permission.


Methods (ExecutionPermission class)

 Microsoft SDK for Java

ExecutionPermission Class Methods

The ExecutionPermission Class contains the following methods:

check determines whether the permission allows the applications specified in an ExecutionRequest object to be executed.
combine creates and returns a new ExecutionPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the ExecutionPermission instance with a specified permission object.
copy retrieves a copy of the ExecutionPermission instance.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
excludeApplications explicitly excludes applications from the set of programs that the permission allows.
getExcludedApplications retrieves a WildcardExpression instance that contains all the applications that have been explicitly denied.
getIncludedApplications retrieves a WildcardExpression instance that contains all the applications that have been explicitly included in the set of programs that the permission allows.
includeApplications adds specific applications to the set of programs that the permission allows.
isUnrestricted determines whether the permission object allows unrestricted access to execute applications.
mapFormat retrieves a permission-specific tag when given an encoding format.
reset resets the permission object so that it no longer allows access for executing applications.
setUnrestricted turns the unrestricted state of this permission object on or off.
supportedFormats retrieves the encoding formats that the permission type supports.
toString retrieves a textual representation of the permission object.


check (ExecutionPermission class)

 Microsoft SDK for Java

check

This method of the ExecutionPermission Class determines whether the permission allows the applications specified in an ExecutionRequest object to be executed.

Syntax

public void check(Object param);

Parameters

param The security request parameter. It must be an instance of ExecutionRequest.

To determine whether the check passes or fails using rules

  1. If this permission object allows unrestricted access, the check passes.

  2. If the specified application is within the set of explicitly denied applications, the check fails.

  3. If the specified application is within the set of explicitly allowed applications, the check succeeds; otherwise, it fails.

Exceptions

SecurityException if this permission does not allow the specified program to run.


combine (ExecutionPermission class)

 Microsoft SDK for Java

combine

This method of the ExecutionPermission Class creates and returns a new ExecutionPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission other);

Return Value

Returns the resulting ExecutionPermission object.

Parameters

other The ExecutionPermission object to combine with.

Exceptions

IllegalArgumentException if the specified object to combine with is not an instance of the ExecutionPermission class.


compareSet (ExecutionPermission class)

 Microsoft SDK for Java

compareSet

This method of the ExecutionPermission Class compares the ExecutionPermission instance with a specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the ExecutionPermission instance is compared with.


copy (ExecutionPermission class)

 Microsoft SDK for Java

copy

This method of the ExecutionPermission Class retrieves a copy of the ExecutionPermission instance.

Syntax

public IPermission copy();

Return Value

Returns a copy of the ExecutionPermission instance.


decode (ExecutionPermission class)

 Microsoft SDK for Java

decode

This method of the ExecutionPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (ExecutionPermission class)

 Microsoft SDK for Java

encode

This method of the ExecutionPermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


excludeApplications (ExecutionPermission class)

 Microsoft SDK for Java

excludeApplications

This method of the ExecutionPermission Class explicitly excludes applications from the set of programs that the permission allows.

Syntax

public void excludeApplications(String pattern);

Parameters

pattern The pattern that specifies the applications that are explicitly prohibited. It can contain wildcard expressions.

Remarks

Because all applications are prohibited by default, this call is only useful to remove programs from an expression that was previously added with an includeApplications call. For example, the following code creates an ExecutionPermission object that allows access to all .exe applications, except Notepad.exe:

   ...
   ExecutionPermission eperm = new ExecutionPermission()
   eperm.includeApplications("*.exe");
   eperm.excludeApplications("notepad.exe");
   ...

Note This method does nothing if the permission object already specifies unrestricted access.


getExcludedApplications (ExecutionPermission class)

 Microsoft SDK for Java

getExcludedApplications

This method of the ExecutionPermission Class retrieves a WildcardExpression instance that contains all the applications that have been explicitly denied.

Syntax

public WildcardExpression getExcludedApplications();

Return Value

Returns a wildcard expression that contains the denied applications.


getIncludedApplications (ExecutionPermission class)

 Microsoft SDK for Java

getIncludedApplications

This method of the ExecutionPermission Class retrieves a WildcardExpression instance that contains all the applications that have been explicitly included in the set of programs that the permission allows.

Syntax

public WildcardExpression getIncludedApplications();

Return Value

Returns the wildcard expression that contains the allowed applications.


includeApplications (ExecutionPermission class)

 Microsoft SDK for Java

includeApplications

This method of the ExecutionPermission Class adds specific applications to the set of programs that the permission allows. Applications are specified by a pattern string that can contain wildcard expressions.

Syntax

public void includeApplications(String pattern);

Examples

includeApplications("notepad.exe");

includeApplications("c:\\anything\\*.exe");

Note This method does nothing if the permission object already specifies unrestricted access.

Parameters

Pattern The pattern that specifies the applications that are allowed. It can contain wildcard expressions.

See Also

com.ms.util.WildcardExpression


isUnrestricted (ExecutionPermission class)

 Microsoft SDK for Java

isUnrestricted

This method of the ExecutionPermission Class determines whether the permission object allows unrestricted access to execute applications.

Syntax

public boolean isUnrestricted();

Return Value

Returns true if the permission object allows unrestricted access to execute applications; otherwise, returns false.


mapFormat (ExecutionPermission class)

 Microsoft SDK for Java

mapFormat

This method of the ExecutionPermission Class retrieves a permission-specific tag when given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


reset (ExecutionPermission class)

 Microsoft SDK for Java

reset

This method of the ExecutionPermission Class resets the permission object so that it no longer allows access for executing applications.

Syntax

public void reset();


setUnrestricted (ExecutionPermission class)

 Microsoft SDK for Java

setUnrestricted

This method of the ExecutionPermission Class turns the unrestricted state of this permission object on or off.

Syntax

public void setUnrestricted(boolean flag);

Parameters

flag The flag that indicates whether to turn the unrestricted state on or off. If true, this method turns the unrestricted state on; otherwise, this method turns the unrestricted state off.

Remarks

If the unrestricted state is on, the permission object allows any application to be executed by the classes that possess this permission. If the unrestricted state is off, the permission allows only the execution of applications explicitly specified by the includeApplications method. By default, the unrestricted state is off.


supportedFormats (ExecutionPermission class)

 Microsoft SDK for Java

supportedFormats

This method of the ExecutionPermission Class retrieves the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (ExecutionPermission class)

 Microsoft SDK for Java

toString

This method of the ExecutionPermission Class retrieves a textual representation of the permission object.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


ExecutionRequest Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

ExecutionRequest Class

The ExecutionRequest Class of the com.ms.security.permissions package represents a request to execute an application. It is intended to be used as the security request object for a parameterized security check involving the execution permission. The ExecutionPermission.check method expects an ExecutionRequest object as its parameter.

public class ExecutionRequest implements ISecurityRequest
{
  // Constructors
  public ExecutionRequest(String torun);

  // Methods
  public PermissionID getPermissionID();
  public String toString();
}

Example

The following example uses an ExecutionRequest object to perform a security check:

  ...

  // Create an ExecutionRequest object that indicates that you want
  // to execute the application "notepad.exe".

  ExecutionRequest sreq = new ExecutionRequest("notepad.exe");

  // Check to see that all of your callers have the rights to
  // execute the notepad program.

  PolicyEngine.checkPermission(sreq);

  ...

For more information about checking execution permissions, see the PolicyEngine class and the ExecutionPermission class.


Constructors (ExecutionRequest Class)

 Microsoft SDK for Java

ExecutionRequest Class Constructors

The ExecutionRequest Class contains the following constructor:

ExecutionRequest(String torun)

Creates an ExecutionRequest object based on the specified application to run.

Syntax

public ExecutionRequest(String torun);

Parameters

torun The application to be executed.


Methods (ExecutionRequest Class)

 Microsoft SDK for Java

ExecutionRequest Class Methods

The ExecutionRequest Class contains the following methods:

getPermissionID retrieves the permission identifier for the ExecutionRequest object.
toString converts the ExecutionRequest object to its string representation.


getPermissionID (ExecutionRequest Class)

 Microsoft SDK for Java

getPermissionID

This method of the ExecutionRequest Class retrieves the permission identifier for the ExecutionRequest object. This method satisfies the ISecurityRequest interface and returns PermissionID.EXEC to indicate that instances of the ExecutionRequest class are associated with the execution permission.

Syntax

public PermissionID getPermissionID();

Return Value

Returns PermissionID.EXEC.


toString (ExecutionRequest Class)

 Microsoft SDK for Java

toString

This method of the ExecutionRequest Class converts the ExecutionRequest object to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the ExecutionRequest object.


FileIOPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

FileIOPermission Class

The FileIOPermission Class of the com.ms.security.permissions package represents a permission that controls the ability to access files. The StandardSecurityManager checks for this permission type when performing the checkRead, checkWrite, and checkDelete operations.

public class FileIOPermission implements IPermission,
            IEncodablePermission, IAdjustablePermission
{
  // Constructors
  public FileIOPermission();

  // Methods
  public void addDeleteableFile(String filename,
        boolean allowed) throws IOException;
  public void addDeleteableFiles(String pattern, boolean allow);
  public void addFile(int access, String filename,
        boolean allowed) throws IOException;
  public void addFiles(int access, WildcardExpression newspec,
        boolean allowed);
  public void addReadableFile(String filename,
        boolean allowed) throws IOException;
  public void addReadableFiles(String pattern, boolean allow);
  public void addWriteableFile(String filename,
        boolean allowed) throws IOException;
  public void addWriteableFiles(String pattern, boolean allow);
  public void adjustPermission(String tag, Object adjustment);
  public void check(Object param) throws SecurityException;
  public IPermission combine(IPermission source2);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public boolean getCanReadFromFileURLCodebase();
  public WildcardExpression getDeleteableFiles(boolean allowed);
  public WildcardExpression getFiles(int access, boolean allowed);
  public WildcardExpression getReadableFiles(boolean allowed);
  public WildcardExpression getWriteableFiles(boolean allowed);
  public String mapFormat(String format);
  public void reset();
  public void setCanReadFromFileURLCodebase(boolean flag);
  public String[] supportedFormats();
  public String toString();
}

The permission distinguishes between the following types of file I/O access:

FileIORequest.READ

Read-only access to the contents of the file or access to information about the file, such as its length or last modification time.

FileIORequest.WRITE

Write access to the contents of the file or access to change information about the file, such as its name.

FileIORequest.DELETE

The ability to delete the file.

The specific files that the permission instance allows for each of these access types are defined by a pair of include/exclude patterns.

When permissions are checked, the requested file name is expanded to its full form using java.io.File.getCanonicalPath, so the permission objects must contain full path specifications. The addReadableFile, addWriteableFile, and addDeleteableFile methods can be used to convert a single file name to its full form and add it to the permission.

This class implements the IPermission, the IEncodablePermission, and the IAdjustablePermission interfaces.

See Also

com.ms.security.permissions.FileIORequest


Constructors (FileIOPermission class)

 Microsoft SDK for Java

FileIOPermission Class Constructors

The FileIOPermission Class contains the following constructor:

FileIOPermission()

Creates a new FileIOPermission instance.

Syntax

public FileIOPermission();

Remarks

The new instance does not allow any file I/O operations.


Methods (FileIOPermission class)

 Microsoft SDK for Java

FileIOPermission Class Methods

The FileIOPermission Class contains the following methods:

addDeleteableFile adds a file to the set, either allowing or denying that file for delete access.
addDeleteableFiles adds a pattern that specifies a set of files that are allowed or denied for deleting.
addFile adds a specific file to the permission, either allowing or denying that file for the specified access types.
addFiles adds a set of files to this permission, either allowing or denying those files for the specified access type.
addReadableFile adds a file to the set, either allowing or denying that file for read access.
addReadableFiles adds a pattern that specifies a set of files that are allowed or denied for reading.
addWriteableFile adds a file to the set, either allowing or denying that file for write access.
addWriteableFiles adds a pattern that specifies a set of files that are allowed or denied for writing.
adjustPermission adjusts the permission object with some run-time state.
check determines if the specified file I/O operation is allowed by this permission object.
combine creates and returns a new FileIOPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the FileIOPermission instance with a specified permission object.
copy retrieves a copy of the FileIOPermission instance.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
getCanReadFromFileURLCodebase returns the flag that controls whether classes that possess this permission should have read access to the directory that they were loaded from, if that location is a file:// URL.
getDeleteableFiles obtains a pattern that matches all files that are permitted or all files that are explicitly prohibited for delete access.
getFiles retrieves a WildcardExpression object that indicates all the files that this permission object matches for the specified access type.
getReadableFiles obtains a pattern that matches all files that are permitted or all files that are explicitly prohibited for read access.
getWriteableFiles obtains a pattern that matches all files that are permitted or all files that are explicitly prohibited for write access.
mapFormat retrieves a permission-specific tag when given an encoding format.
reset resets the permission state to empty.
setCanReadFromFileURLCodebase sets the flag that controls whether classes that possess this permission should have read access to the directory that they were loaded from, if that location is a file:// URL.
supportedFormats returns the encoding formats that the permission type supports.
toString retrieves a textual representation of the permission object.


addDeleteableFile (FileIOPermission class)

 Microsoft SDK for Java

addDeleteableFile

This method of the FileIOPermission Class adds a file to the set, either allowing or denying that file for delete access.

Syntax

public void addDeleteableFile(String filename, boolean allowed) throws IOException;

Parameters

filename | The name of the file to add to the permission.
allowed | The flag that indicates whether you are allowing or denying the file. If the value is true, the file is allowed; otherwise, the file is denied.

Exceptions

IOException if an error occurs while getting the full name of the file.


addDeleteableFiles (FileIOPermission class)

 Microsoft SDK for Java

addDeleteableFiles

This method of the FileIOPermission Class adds a pattern that specifies a set of files that are allowed or denied for deleting.

Syntax

public void addDeleteableFiles(String pattern, boolean allow);

Parameters

pattern | The string that indicates which files to allow or deny. It must be of the form accepted by a WildcardExpression with the ESCAPED flag enabled.
allow | The flag that indicates whether you are allowing or denying the files specified by the pattern. If the value is true, the files are allowed. Otherwise, the files are denied. You can deny files only if the file was previously allowed.


addFile (FileIOPermission class)

 Microsoft SDK for Java

addFile

This method of the FileIOPermission Class adds a specific file to the permission, either allowing or denying that file for the specified access types. The file is expanded to its fully qualified form using the java.io.File.getCanonicalPath method.

Syntax

public void addFile(int access, String filename, boolean allowed) throws IOException;

Parameters

access | An access type that is one of the following values: FileIORequest.READ, FileIORequest.WRITE, or FileIORequest.DELETE.
filename | The name of the file to add to the permission.
allowed | The flag that indicates whether you are allowing or denying the file for the specified access type. If the value is true, the file is allowed; otherwise, the file is denied.

Exceptions

IOException if an error occurs while getting the full name of the file.


addFiles (FileIOPermission class)

 Microsoft SDK for Java

addFiles

This method of the FileIOPermission Class adds a set of files to this permission, either allowing or denying those files for the specified access type. The files to be added are specified as a WildcardExpression object.

Syntax

public void addFiles(int access, WildcardExpression newspec, boolean allowed);

Parameters

access | An access type that is one of the following values: FileIORequest.READ, FileIORequest.WRITE, or FileIORequest.DELETE.
newspec | The wildcard expression that indicates the files to add.
allowed | The flag that indicates whether you are allowing or denying the file for the specified access type. If the value is true, the files are allowed; otherwise, they are denied.


addReadableFile (FileIOPermission class)

 Microsoft SDK for Java

addReadableFile

This method of the FileIOPermission Class adds a file to the set, either allowing or denying that file for read access.

Syntax

public void addReadableFile(String filename, boolean allowed) throws IOException;

Calling this method is equivalent to the following call:

addFile(FileIORequest.READ,filename,allowed)

Parameters

filename | The name of the file to add to the permission.
allowed | The flag that indicates whether you are allowing or denying the file. If the value is true, the file is allowed; otherwise, the file is denied.

Exceptions

IOException if an error occurs while getting the full name of the file.


addReadableFiles (FileIOPermission class)

 Microsoft SDK for Java

addReadableFiles

This method of the FileIOPermission Class adds a pattern that specifies a set of files that are allowed or denied for reading.

Syntax

public void addReadableFiles(String pattern, boolean allow);

Parameters

pattern | The string that indicates which files to allow or deny. It must be of the form accepted by a WildcardExpression with the ESCAPED flag enabled.
allow | The flag that indicates whether you are allowing or denying the files specified by the pattern. If the value is true, the files are allowed. Otherwise, the files are denied. You can deny files only if the file was previously allowed.


addWriteableFile (FileIOPermission class)

 Microsoft SDK for Java

addWriteableFile

This method of the FileIOPermission Class adds a file to the set, either allowing or denying that file for write access.

Syntax

public void addWriteableFile(String filename, boolean allowed) throws IOException;

Calling this method is equivalent to the following call:

addFile(FileIORequest.WRITE,filename,allowed)

Parameters

filename | The name of the file to add to the permission.
allowed | The flag that indicates whether you are allowing or denying the file. If the value is true, the file is allowed; otherwise, the file is denied.

Exceptions

IOException if an error occurs while getting the full name of the file.


addWriteableFiles (FileIOPermission class)

 Microsoft SDK for Java

addWriteableFiles

This method of the FileIOPermission Class adds a pattern that specifies a set of files that are allowed or denied for writing.

Syntax

public void addWriteableFiles(String pattern, boolean allow);

Parameters

pattern | The string that indicates which files to allow or deny. It must be of the form accepted by a WildcardExpression with the ESCAPED flag enabled.
allow | The flag that indicates whether you are allowing or denying the files specified by the pattern. If the value is true, the files are allowed. Otherwise, the files are denied. You can deny files only if the file was previously allowed.


adjustPermission (FileIOPermission class)

 Microsoft SDK for Java

adjustPermission

This method of the FileIOPermission Class adjusts the permission object with some run-time state.

Syntax

public void adjustPermission(String tag, Object adjustment);

Parameters

tag | The adjustment type. Every type except "codebase" is ignored.
adjustment | This parameter must be an instance of java.net.URL for the "codebase" tag.

Remarks

The FileIOPermission only responds to the "codebase" adjustment type, and expects the adjustment parameter to be of type URL in that case. All other adjustment types are ignored.

If the URL is a file:// URL and if the permission allows reading from file:// URL codebases, this method adds read access for the "codebase" directory (and everything below it) to the permission object.


check (FileIOPermission class)

 Microsoft SDK for Java

check

This method of the FileIOPermission Class determines if the specified file I/O operation is allowed by this permission object.

Syntax

public void check(Object param) throws SecurityException;

Parameters

param The security request parameter. It must be an instance of the FileIORequest class.

Exceptions

SecurityException if this permission does not allow the specified file I/O operation.


combine (FileIOPermission class)

 Microsoft SDK for Java

combine

This method of the FileIOPermission Class creates and returns a new FileIOPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission source2);

Return Value

Returns the resulting FileIOPermission object.

Parameters

source2 The FileIOPermission object to combine with.

Exceptions

IllegalArgumentException if the specified object to combine with is not an instance of FileIOPermission.


compareSet (FileIOPermission class)

 Microsoft SDK for Java

compareSet

This method of the FileIOPermission Class compares the FileIOPermission instance with a specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the FileIOPermission instance is compared with.


copy (FileIOPermission class)

 Microsoft SDK for Java

copy

This method of the FileIOPermission Class retrieves a copy of the FileIOPermission instance.

Syntax

public IPermission copy();

Return Value

Returns the copy of the FileIOPermission instance.


decode (FileIOPermission class)

 Microsoft SDK for Java

decode

This method of the FileIOPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (FileIOPermission class)

 Microsoft SDK for Java

encode

This method of the FileIOPermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


getCanReadFromFileURLCodebase (FileIOPermission class)

 Microsoft SDK for Java

getCanReadFromFileURLCodebase

This method of the FileIOPermission Class returns the flag that controls whether classes that possess this permission should have read access to the directory that they were loaded from, if that location is a file:// URL.

Syntax

public boolean getCanReadFromFileURLCodebase();

Return Value

Returns true if the permission allows reading from file:// URL codebases; otherwise, returns false.


getDeleteableFiles (FileIOPermission class)

 Microsoft SDK for Java

getDeleteableFiles

This method of the FileIOPermission Class obtains a pattern that matches all files that are permitted or all files that are explicitly prohibited for delete access. The allowed flag indicates whether you want to obtain the pattern that matches files that have been explicitly allowed or explicitly denied.

Syntax

public WildcardExpression getDeleteableFiles(boolean allowed);

Return Value

Returns the WildcardExpression that matches the requested files.

Parameters

allowed The flag that indicates whether you want to obtain the pattern for explicitly allowed files or explicitly denied files. If true, the method returns a pattern that matches all files that are explicitly allowed; otherwise, the method returns a pattern that matches all files that are explicitly denied.


getFiles (FileIOPermission class)

 Microsoft SDK for Java

getFiles

This method of the FileIOPermission Class retrieves a WildcardExpression object that indicates all the files that this permission object matches for the specified access type.

Syntax

public WildcardExpression getFiles(int access, boolean allowed);

Return Value

Returns the wildcard expression that indicates the matching files.

Parameters

access | An access type that is one of the following values: FileIORequest.READ, FileIORequest.WRITE, or FileIORequest.DELETE.
allowed | The flag that indicates whether this method retrieves the pattern that matches files that have been explicitly allowed or explicitly denied. If true, this method returns the pattern for files that have been explicitly allowed; otherwise, it returns the pattern for files that have been explicitly denied.


getReadableFiles (FileIOPermission class)

 Microsoft SDK for Java

getReadableFiles

This method of the FileIOPermission Class obtains a pattern that matches all files that are permitted or all files that are explicitly prohibited for read access. The allowed flag indicates whether you want to obtain the pattern that matches files that have been explicitly allowed or explicitly denied.

Syntax

public WildcardExpression getReadableFiles(boolean allowed);

Return Value

Returns the WildcardExpression that matches the requested files.

Parameters

allowed The flag that indicates whether you want to obtain the pattern for explicitly allowed files or explicitly denied files. If true, the method returns a pattern that matches all files that are explicitly allowed; otherwise, the method returns a pattern that matches all files that are explicitly denied.


getWriteableFiles (FileIOPermission class)

 Microsoft SDK for Java

getWriteableFiles

This method of the FileIOPermission Class obtains a pattern that matches all files that are permitted or all files that are explicitly prohibited for write access. The allowed flag indicates whether you want to obtain the pattern that matches files that have been explicitly allowed or explicitly denied.

Syntax

public WildcardExpression getWriteableFiles(boolean allowed);

Return Value

Returns the WildcardExpression that matches the requested files.

Parameters

allowed The flag that indicates whether you want to obtain the pattern for explicitly allowed files or explicitly denied files. If true, the method returns a pattern that matches all files that are explicitly allowed; otherwise, the method returns a pattern that matches all files that are explicitly denied.


mapFormat (FileIOPermission class)

 Microsoft SDK for Java

mapFormat

This method of the FileIOPermission Class retrieves a permission-specific tag when given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


reset (FileIOPermission class)

 Microsoft SDK for Java

reset

This method of the FileIOPermission Class resets the permission state to empty. This is a state in which the object allows no file I/O access.

Syntax

public void reset();


setCanReadFromFileURLCodebase (FileIOPermission class)

 Microsoft SDK for Java

setCanReadFromFileURLCodebase

This method of the FileIOPermission Class sets the flag that controls whether classes that possess this permission should have read access to the directory that they were loaded from, if that location is a file:// URL.

Syntax

public void setCanReadFromFileURLCodebase(boolean flag);

Parameters

flag The value that indicates whether this permission should allow reading from the "codebase" directory for file:// URLs. If true, the flag will be set so that reading is allowed; otherwise, the flag is set so that reading is not allowed.

Remarks

If the flag is set to true, a later "codebase" adjustment by using the adjustPermission method will include the "codebase" directory in the set of files that can be read by this permission. If this flag is false, a later call to the adjustPermission method will do nothing.


supportedFormats (FileIOPermission class)

 Microsoft SDK for Java

supportedFormats

This method of the FileIOPermission Class returns the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (FileIOPermission class)

 Microsoft SDK for Java

toString

This method of the FileIOPermission Class retrieves a textual representation of the permission object.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


FileIORequest Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

FileIORequest Class

The FileIORequest Class of the com.ms.security.permissions package represents a request for access to the file system. FileIORequest instances should be used as the security request objects for parameterized security checks involving the file I/O permission.

public class FileIORequest implements ISecurityRequest
{
  // Fields
  public static final int DELETE;
  public static final int READ;
  public static final int WRITE;

  // Constructors
  public FileIORequest(int type, String file);
  public FileIORequest(int type);

  // Methods
  public PermissionID getPermissionID();
  public String toString();
}

The FileIOPermission.check method expects a FileIORequest object as its parameter.

Example

The following example shows how to use a FileIORequest object to perform a security check to determine whether a file called sample.txt can be opened for reading:

  ...
  // Create a FileIORequest object that indicates that you want to
  // read the file called "c:\\sample.txt".

  FileIORequest sreq = new FileIORequest(FileIORequest.READ,"c:\\sample.txt");

  // Check to see that all of your callers
  // have the rights to read that file.

  PolicyEngine.checkPermission(sreq);
  ...

For more information about checking file I/O permissions, see the PolicyEngine class and the FileIOPermission class.


Constructors (FileIORequest Class)

 Microsoft SDK for Java

FileIORequest Class Constructors

The FileIORequest Class contains the following constructors:

FileIORequest(int type, String file)
FileIORequest(int type)

FileIORequest(int type, String file)

Creates a FileIORequest object based on the access type requested and the name of the file to which access is requested.

Syntax

public FileIORequest(int type, String file);

Parameters

type | The type of access that is requested. This value must be some combination of READ, WRITE, and DELETE.
file | The name of the file to which I/O access is requested.

FileIORequest(int type)

Creates a FileIORequest object based on the access type requested.

Syntax

public FileIORequest(int type);

Parameters

type The access type that is requested. This value must be some combination of READ, WRITE, and DELETE.


Methods (FileIORequest Class)

 Microsoft SDK for Java

FileIORequest Class Methods

The FileIORequest Class contains the following methods:

getPermissionID retrieves the permission identifier for the FileIORequest object.
toString converts the FileIORequest object to its string representation.


getPermissionID (FileIORequest Class)

 Microsoft SDK for Java

getPermissionID

This method of the FileIORequest Class retrieves the permission identifier for the FileIORequest object.

Syntax

public PermissionID getPermissionID();

Return Value

Returns PermissionID.FILEIO.

Remarks

This method satisfies the ISecurityRequest interface and returns PermissionID.FILEIO to indicate that instances of the FileIORequest class are associated with the file I/O permission.


toString (FileIORequest Class)

 Microsoft SDK for Java

toString

This method of the FileIORequest Class converts the FileIORequest object to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the FileIORequest object.


Fields (FileIORequest Class)

 Microsoft SDK for Java

FileIORequest Class Fields

The FileIORequest Class contains the following fields.

DELETE | The file I/O access type that represents an attempt to delete a file.
READ | The file I/O access type that represents an attempt to open a file for reading.
WRITE | The file I/O access type that represents an attempt to open a file for writing.


MultimediaPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

MultimediaPermission Class

The MultimediaPermission Class of the com.ms.security.permissions package represents a permission that allows the use of enhanced multimedia functionality. Currently, this permission allows access to extended aspects of the Microsoft® DirectX® APIs. Security checks for the multimedia permission are non-parameterized.

public class MultimediaPermission implements IPermission,
            IEncodablePermission
{
  // Methods
  public void check(Object request) throws SecurityException;
  public IPermission combine(IPermission other);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public String mapFormat(String format);
  public String[] supportedFormats();
  public String toString();
}

This class implements the IPermission and the IEncodablePermission interfaces.


Methods (MultimediaPermission Class)

 Microsoft SDK for Java

MultimediaPermission Class Methods

The MultimediaPermission Class contains the following methods:

check performs a check on the permission object.
combine returns a new MultimediaPermission instance.
compareSet compares the MultimediaPermission instance against the specified permission object.
copy retrieves a new instance of the MultimediaPermission class.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
mapFormat retrieves a permission-specific tag, given an encoding format.
supportedFormats retrieves the encoding formats that this permission type supports.
toString retrieves the string representation of the permission object.


check (MultimediaPermission Class)

 Microsoft SDK for Java

check

This method of the MultimediaPermission Class performs a check on the permission object. Because security checks for the multimedia permission are non-parameterized, this method always succeeds.

Syntax

public void check(Object request) throws SecurityException;

Parameters

request This parameter is ignored.


combine (MultimediaPermission Class)

 Microsoft SDK for Java

combine

This method of the MultimediaPermission Class returns a new MultimediaPermission instance. Since checks for MultimediaPermission are non-parameterized, the combine operation serves no purpose.

Syntax

public IPermission combine(IPermission other);

Return Value

Returns a new MultimediaPermission instance.

Parameters

other This parameter is ignored, but it must be an instance of the MultimediaPermission class.


compareSet (MultimediaPermission Class)

 Microsoft SDK for Java

compareSet

This method of the MultimediaPermission Class compares the MultimediaPermission instance against the specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns EQUAL if the specified object is an instance of the MultimediaPermission class.

Parameters

target The permission object that the MultimediaPermission instance is compared against. It must be an instance of the MultimediaPermission class.

Exceptions

IllegalArgumentException if the specified Object is not an instance of the MultimediaPermission class.


copy (MultimediaPermission Class)

 Microsoft SDK for Java

copy

This method of the MultimediaPermission Class retrieves a new instance of the MultimediaPermission class.

Syntax

public IPermission copy();

Return Value

Returns a new MultimediaPermission instance.


decode (MultimediaPermission Class)

 Microsoft SDK for Java

decode

This method of the MultimediaPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (MultimediaPermission Class)

 Microsoft SDK for Java

encode

This method of the MultimediaPermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


mapFormat (MultimediaPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the MultimediaPermission Class retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


supportedFormats (MultimediaPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the MultimediaPermission Class retrieves the encoding formats that this permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (MultimediaPermission Class)

 Microsoft SDK for Java

toString

This method of the MultimediaPermission Class retrieves the string representation of the permission object.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


NetIOPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

NetIOPermission Class

The NetIOPermission Class of the com.ms.security.permissions package represents a permission that controls the ability to perform networking operations.

public class NetIOPermission implements IPermission,
            IEncodablePermission, IAdjustablePermission
{
  // Fields
  public static final int ALL_API_FLAGS;
  public static final int ALLOW;
  public static final int ALLOWALL;
  public static final int ALLOWBIND;
  public static final int ALLOWCONNECT;
  public static final int ALLOWMULTICAST;
  public static final int BIND;
  public static final int CONNECT;
  public static final int DENY;
  public static final int DENYALL;
  public static final int DENYBIND;
  public static final int DENYCONNECT;
  public static final int DENYMULTICAST;
  public static final int HOSTS;
  public static final int IPS;
  public static final int MULTICAST;

  // Constructors
  public NetIOPermission();

  // Methods
  public void addAddress(int flags, InetAddress addr);
  public void addAddress(int flags, InetAddress addr,
        IntRanges ports);
  public void addAllFormsByName(int flags, String spec,
        IntRanges ports);
  public void addAllFormsByName(int flags, String spec);
  public void addConnectHost(String hostspec, boolean fAllow);
  public void addGlobalPortRules(int flags, String spec);
  public void addGlobalPorts(int flags, int start, int end);
  public void addHost(int flags, String hostspec);
  public void addHost(int flags, String hostspec, IntRanges ports);
  public void addHostRules(int flags, String spec);
  public void addIP(int flags, int addr);
  public void addIP(int flags, int addr, IntRanges ports);
  public void addIP(int flags, byte[] addr);
  public void addIP(int flags, byte[] addr, IntRanges ports);
  public void addIPRules(int flags, String spec);
  public void addIPs(int flags, int s, int e, IntRanges ports);
  public void addIPs(int flags, int s, int e);
  public void addIPs(int flags, byte[] s, byte[] e,
        IntRanges ports);
  public void addIPs(int flags, byte[] s, byte[] e);
  public void addPattern(int flags, String spec);
  public void addPattern(int flags, String spec, IntRanges ports);
  public void adjustPermission(String tag, Object adjustment);
  public void check(Object param) throws SecurityException;
  public IPermission combine(IPermission source2);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public boolean getCanConnectToFileURLCodeBase();
  public boolean getCanConnectToNonFileURLCodeBase();
  public String getGlobalPortRules(int flags);
  public IntRanges getGlobalPorts(int flags);
  public String getHostRules(int flags);
  public WildcardExpression getHosts(int flags);
  public String getIPRules(int flags);
  public IntRanges getIPs(int flags);
  public IntRanges[] getPorts(int flags);
  public String mapFormat(String format);
  public void reset();
  public void setCanConnectToFileURLCodeBase(boolean f);
  public void setCanConnectToNonFileURLCodeBase(boolean f);
  public String[] supportedFormats();
  public String toString();
}

A NetIOPermission object contains components for the following basic types of network operations:

CONNECT

The ability to have general communication with specific hosts.

BIND

The ability to accept connections on specific interfaces and ports. The ability to accept a connection from a specific host is controlled by the CONNECT rules.

MULTICAST

The ability to join specific multicast groups. Communication with specific members of the multicast group is controlled by the CONNECT rules.

For each type of operation, the permissions are specified as ranges of IP (Internet Protocol) addresses, hostname patterns, and ports. Ports can be specified for individual ranges or patterns, or for all ranges or patterns. The global port rules supercede any individual port rules.

All the permission's operators are incremental. The reset method can be used to clear an existing permission of all components.

The components of the permission can be added individually or one hostname mask/address range/port range at a time. Multiple components can also be added in string format. For example, the string ".microsoft.com;myhost.com" could be used to indicate the specific host named "myhost.com." and all host names that end in ".microsoft.com".

Address ranges have the normal dotted IP form. An asterisk (*) can be used in place of a byte to represent any valid byte. A single address can be specified, or starting and ending ranges can be delimited by a hyphen.

Port lists must have the same syntax accepted by the string constructors of the com.ms.util.IntRanges class. For example, "80,1024-2000" is a valid port list. Ports can be specified on individual hostname patterns or addresses by appending a colon and a port range. For example, "*.microsoft.com:80" and "1.2.*.*:1024-5000" are both valid port specifications.

For hostnames, multiple addresses and address ranges are delimited by semicolons. For example, "1.2.*.*;4.5.6.7-4.5.6.50" is a valid hostname.

Some of the addXXX methods in this class take a flag parameter that consists of two values combined with a logical OR operator (|). The first value specifies the connection type by using one or more of MULTICAST, BIND, or CONNECT. The second value specifies ALLOW or DENY to indicate whether the address, port, or hostname being added is supposed to use the exclude or include rules. An IllegalArgumentException is thrown by these methods if the arguments don't apply to one or more of the specified types.

The flags can be used to update multiple aspects of the permission with one method call. For example, the following code sample adds "localhost" as a hostname that can be both connected and bound to:

     NetIOPermission data;
     data.addHost(NetIOPermission.ALLOWALL, "localhost");

The getXXX methods also take a flag parameter that consists of two values combined with a logical OR operator (|). To indicate the connection type, you must specify exactly one of MULTICAST, BIND or CONNECT. If more than one of these is specified, an IllegalArgumentException is thrown. For the second value, you should specify ALLOW or DENY.

For your convenience, combination flags are provided to use for the flag parameters. With these values, you don't have to use the OR (|) operator.

ALLOWCONNECT
DENYCONNECT
ALLOWBIND
DENYBIND
ALLOWMULTICAST
DENYMULTICAST
ALLOWALL
DENYALL

The addXXX methods accept all the flags in the previous list, but the getXXX methods do not accept the last two.

Hostname masks are input to the permission as strings and retrieved as expressions.

IP addresses are only supported in 32-bit lengths. Addresses are added as integers, byte arrays (for use with the java.net.InetAddress.getAddress method), or as com.ms.util.IntRanges.

The setCanConnectToFileURLCodeBase and setCanConnectToNonFileURLCodeBase methods are used to control whether the permission allows connections to the host from which the classes with the permission were loaded. If set, the permission can be updated with the codebase by the com.ms.security.PermissionDataSet.adjustForCodebase method.


Constructors (NetIOPermission Class)

 Microsoft SDK for Java

NetIOPermission Class Constructors

The NetIOPermission Class contains the following constructor:

NetIOPermission()

Constructs an empty networking permission.

Syntax

public NetIOPermission();


Methods (NetIOPermission Class)

 Microsoft SDK for Java

NetIOPermission Class Methods

The NetIOPermission Class contains the following methods:

addAddress adds an InetAddress object to the permissions with no port rules.
addAllFormsByName adds all forms of the specified address.
addConnectHost adds an allowed or denied host name pattern to the connect permissions.
addGlobalPortRules adds global port rules for the specified connection type.
addGlobalPorts adds a global port range for the specified connection types.
addHost adds a host name pattern to the permissions with no port rules.
addHostRules adds a set of host rules and per-host port rules for the specified access types.
addIP adds a single 32-bit address to the permissions with no port rules.
addIPRules adds a set of IP rules and per-IP port rules from the string form for the specified access types.
addIPs adds a 32-bit address range to the permissions with the specified port rules and the specified access types.
addPattern parses a pattern and adds it to the permission as an IP or host rule, as appropriate.
adjustPermission adjusts this permission object with some run-time state.
check determines whether the specified networking I/O operation is allowed by the permission object.
combine creates and returns a new NetIOPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the NetIOPermission instance with a specified permission object.
copy retrieves a copy of the NetIOPermission instance.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
getCanConnectToFileURLCodeBase returns the flag that controls whether classes that possess this permission can connect back to the local host if from a file:// URL codebase.
getCanConnectToNonFileURLCodeBase retrieves the flag that controls whether classes that possess this permission can connect back to non-file:// URL codebase hosts.
getGlobalPortRules obtains the global port rules for the specified connection type in String form.
getGlobalPorts obtains the global ports rules for the specified connection type.
getHostRules obtains the combined set of hostname patterns and corresponding port rules for the specified connection type, in String form.
getHosts obtains a combined pattern that matches all the hostname patterns for the specified connection type.
getIPRules obtains the combined set of 32-bit IP ranges and corresponding port rules for the specified connection type, in String form.
getIPs obtains the combined set of 32-bit IP ranges for the specified connection type.
getPorts obtains the port rules corresponding to each of the hosts or IPs for the specified connection type.
mapFormat retrieves a permission-specific tag, given an encoding format.
reset resets the permission state to empty.
setCanConnectToFileURLCodeBase sets the flag that controls whether classes that possess this permission can connect to the local host if the codebase URL associated with the classes is a file:// URL.
setCanConnectToNonFileURLCodeBase sets the flag that controls whether classes that possess this permission can connect back to their originating host if the codebase URL is not a file:// URL.
supportedFormats retrieves the encoding formats that the permission type supports.
toString retrieves a textual representation of the permission object.


addAddress (NetIOPermission Class)

 Microsoft SDK for Java

addAddress

The addAddress of the NetIOPermission Class contains the following signatures:

addAddress(int flags, InetAddress addr)
addAddress(int flags, InetAddress addr, IntRanges ports)

addAddress(int flags, InetAddress addr)

Adds an InetAddress object to the permissions with no port rules. The permission will allow access to all ports, unless global rules have been previously specified.

Syntax

public void addAddress(int flags, InetAddress addr);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the InetAddress object being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
addr | The Internet address that the access flags apply to.

addAddress(int flags, InetAddress addr, IntRanges ports)

Adds an InetAddress object to the permissions with the specified port rules.

Syntax

public void addAddress(int flags, InetAddress addr, IntRanges ports);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be either BIND or CONNECT to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the InetAddress object being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, or DENYBIND.
addr | The Internet address that the access flags apply to.
ports | The ports that apply on the address.


addAllFormsByName (NetIOPermission Class)

 Microsoft SDK for Java

addAllFormsByName

The addAllFormsByName method of the NetIOPermission Class contains the following signatures:

addAllFormsByName(int flags, String spec, IntRanges ports)
addAllFormsByName(int flags, String spec)

addAllFormsByName(int flags, String spec, IntRanges ports)

Adds all forms of the specified address. The address is added using the following procedure:

  • If the address is in dotted IP form, it will be resolved to a hostname. The hostname and all addresses will be added. If the address cannot be resolved, only the specified address is added.

  • If the address is a hostname, it will be resolved to its addresses. The hostname and all addresses will be added. If the hostname cannot be resolved, only the specified hostname is added. The hostname will be added in its fully-qualified form.

Syntax

public void addAllFormsByName(int flags, String spec, IntRanges ports);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the address being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
spec | The textual IP or host specification.
ports | The ports that apply to the hosts or IPs.

addAllFormsByName(int flags, String spec)

Adds all forms of the specified address. The address is added using the following procedure:

  • If the address is in dotted IP form, it will be resolved to a hostname. The hostname and all addresses will be added. If the address cannot be resolved, only the specified address is added.

  • If the address is a hostname, it will be resolved to its addresses. The hostname and all addresses will be added. If the hostname cannot be resolved, only the specified hostname is added. The hostname will be added in its fully-qualified form.

Syntax

public void addAllFormsByName(int flags, String spec);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the address being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
spec | The textual IP or host specification.


addConnectHost (NetIOPermission Class)

 Microsoft SDK for Java

addConnectHost

This method of the NetIOPermission Class adds an allowed or denied hostname pattern to the connect permissions.

Syntax

public void addConnectHost(String hostspec, boolean fAllow);

Parameters

hostspec | The host specification.
fAllow | If the value is true, allow connections to the specified hosts. If the value is false, explicitly deny connections to the specified hosts.


addGlobalPortRules (NetIOPermission Class)

 Microsoft SDK for Java

addGlobalPortRules

This method of the NetIOPermission Class adds global port rules for the specified connection type.

Syntax

public void addGlobalPortRules(int flags, String spec);

Parameters

flags | The connection type, which consists of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the global port rules being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
spec | The port rules to add.


addGlobalPorts (NetIOPermission Class)

 Microsoft SDK for Java

addGlobalPorts

This method of the NetIOPermission Class adds a global port range for the specified connection types.

Syntax

public void addGlobalPorts(int flags, int start, int end);

Parameters

flags | The connection type, which consists of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the port range being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
start | The beginning range value.
end | The ending range value.


addHost (NetIOPermission Class)

 Microsoft SDK for Java

addHost

The addHost method of the NetIOPermission Class contains the following signatures:

addHost(int flags, String hostspec)
addHost(int flags, String hostspec, IntRanges ports)

addHost(int flags, String hostspec)

Adds a hostname pattern to the permissions with no port rules. The permission will allow access to all ports, unless global rules have been previously specified.

Syntax

public void addHost(int flags, String hostspec);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the 32-bit address range being added should use the include or exclude rules. For convenience, instead using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
hostspec | The host specification.

addHost(int flags, String hostspec, IntRanges ports)

Adds a hostname pattern to the permissions with the specified port rules.

Syntax

public void addHost(int flags, String hostspec, IntRanges ports);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be either BIND or CONNECT to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the hostname pattern being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, or DENYBIND.
hostspec | The host specification.
ports | The ports that apply to the hosts.


addHostRules (NetIOPermission Class)

 Microsoft SDK for Java

addHostRules

This method of the NetIOPermission Class adds a set of host rules and per-host port rules for the specified access types.

Syntax

public void addHostRules(int flags, String spec);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be either BIND or CONNECT to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the rules being added indicate inclusion or exclusion. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, or DENYBIND.
spec | The textual host/port specification.


addIP (NetIOPermission Class)

 Microsoft SDK for Java

addIP

The addIP method of the NetIOPermission Class contains the following signatures:

addIP(int flags, int addr)
addIP(int flags, int addr, IntRanges ports)
addIP(int flags, byte[] addr)
addIP(int flags, byte[] addr, IntRanges ports)

addIP(int flags, int addr)

Adds a single 32-bit address to the permissions with no port rules.

Syntax

public void addIP(int flags, int addr);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the address being added should use the include or exclude rules. For convenience, instead using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
addr | The 32-bit address.

addIP(int flags, int addr, IntRanges ports)

Adds a single 32-bit address to the permissions with the specified port rules.

Syntax

public void addIP(int flags, int addr, IntRanges ports);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be either BIND or CONNECT to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the 32-bit address being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, or DENYBIND.
addr | The 32-bit address.
ports | The ports that apply to this rule.

addIP(int flags, byte[] addr)

Adds a single address to the permissions with no port rules.

Syntax

public void addIP(int flags, byte[] addr);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the address being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
addr | The address.

addIP(int flags, byte[] addr, IntRanges ports)

Adds a single address to the permissions with the specified port rules.

Syntax

public void addIP(int flags, byte[] addr, IntRanges ports);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be either BIND or CONNECT to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the 32-bit address range being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, or DENYBIND.
addr | The 32-bit address.
ports | The ports that apply to this rule.


addIPRules (NetIOPermission Class)

 Microsoft SDK for Java

addIPRules

This method of the NetIOPermission Class adds a set of IP rules and per-IP port rules from the string form for the specified access types.

Syntax

public void addIPRules(int flags, String spec);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be either BIND or CONNECT to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the 32-bit address range being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, or DENYBIND.
spec | The textual IP/port specification.


addIPs (NetIOPermission Class)

 Microsoft SDK for Java

addIPs

The addIPs method of the NetIOPermission Class contains the following signatures:

addIPs(int flags, int s, int e, IntRanges ports)
addIPs(int flags, int s, int e)
addIPs(int flags, byte[] s, byte[] e, IntRanges ports)
addIPs(int flags, byte[] s, byte[] e)

addIPs(int flags, int s, int e, IntRanges ports)

Adds a 32-bit address range to the permissions with the specified port rules and the specified access types.

Syntax

public void addIPs(int flags, int s, int e, IntRanges ports);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be either BIND or CONNECT to specify the connect type. The second flag should be either ALLOW or DENY to indicate whether the address range being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, or DENYBIND.
s | The starting address in the range.
e | The ending address in the range.
ports | The ports that apply.

addIPs(int flags, int s, int e)

Adds a 32-bit address range to the permissions with no port rules.

Syntax

public void addIPs(int flags, int s, int e);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the 32-bit address range being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
s | The starting address in the range.
e | The ending address in the range.

addIPs(int flags, byte[] s, byte[] e, IntRanges ports)

Adds an address range to the permissions with the specified port rules.

Syntax

public void addIPs(int flags, byte[] s, byte[] e, IntRanges ports);

Parameters

flags | The access flags. The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be either BIND or CONNECT to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the address range being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, or DENYBIND.
s | The starting address in the range.
e | The ending address in the range.
ports | The ports that apply.

addIPs(int flags, byte[] s, byte[] e)

Adds an address range to the permissions with no port rules.

Syntax

public void addIPs(int flags, byte[] s, byte[] e);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the address range being added should use the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
s | The starting address in the range.
e | The ending address in the range.


addPattern (NetIOPermission Class)

 Microsoft SDK for Java

addPattern

The addPattern method of the NetIOPermission Class contains the following signatures:

addPattern(int flags, String spec)
addPattern(int flags, String spec, IntRanges ports)

addPattern(int flags, String spec)

Parses a pattern and adds it to the permission as an IP or host rule, as appropriate.

Syntax

public void addPattern(int flags, String spec);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, MULTICAST, or ALL_API_FLAGS to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the rule being added indicates inclusion or exclusion. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.
spec | The textual IP/host specification.

addPattern(int flags, String spec, IntRanges ports)

Parses a pattern and adds it to the permission as an IP or host rule, as appropriate, with the specified port rules.

Syntax

public void addPattern(int flags, String spec, IntRanges ports);

Parameters

flags | The access flags, which consist of two separate flags combined with a logical OR operator (|). The first flag should be either BIND or CONNECT to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the rule being added indicates inclusion or exclusion. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWALL, DENYALL, ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND.
spec | The textual IP/host specification.
ports | The ports that apply to the hosts or IPs.


adjustPermission (NetIOPermission Class)

 Microsoft SDK for Java

adjustPermission

This method of the NetIOPermission Class adjusts this permission object with some run-time state.

Syntax

public void adjustPermission(String tag, Object adjustment);

Parameters

tag | The adjustment type. Everything but "codebase" is ignored.
adjustment | This parameter must be an instance of java.net.URL for the "codebase" tag.

Remarks

The NetIOPermission only responds to the "codebase" adjustment type, and expects the adjustment parameter to be URL in that case. All other adjustment types are ignored.

If the URL is a file:// URL, and this permission allows connection back to the localhost if the cobebase URL is a file:// URL, localhost is added to the set of hosts that this permission allows connections to.

If the URL is not a file:// URL, and this permission allows connections back to non file:// URL hosts, the host of the codebase URL is added to the set of hosts that this permission allows connections to.


check (NetIOPermission Class)

 Microsoft SDK for Java

check

This method of the NetIOPermission Class determines whether the specified networking I/O operation is allowed by the permission object.

Syntax

public void check(Object param) throws SecurityException;

Parameters

param The security request parameter. It must be an instance of NetIORequest.

Exceptions

SecurityException if this permission does not allow the specified networking operation.


combine (NetIOPermission Class)

 Microsoft SDK for Java

combine

This method of the NetIOPermission Class creates and returns a new NetIOPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission source2);

Return Value

Returns the resulting NetIOPermission object.

Parameters

source2 The NetIOPermission to combine with.

Exceptions

IllegalArgumentException if the specified object to combine with is not an instance of NetIOPermission.


compareSet (NetIOPermission Class)

 Microsoft SDK for Java

compareSet

This method of the NetIOPermission Class compares the NetIOPermission instance with a specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the NetIOPermission instance is compared with.


copy (NetIOPermission Class)

 Microsoft SDK for Java

copy

This method of the NetIOPermission Class retrieves a copy of the NetIOPermission instance.

Syntax

public IPermission copy();

Return Value

Returns the copy of the NetIOPermission instance.


decode (NetIOPermission Class)

 Microsoft SDK for Java

decode

This method of the NetIOPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (NetIOPermission Class)

 Microsoft SDK for Java

encode

This method of the NetIOPermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


getCanConnectToFileURLCodeBase (NetIOPermission Class)

 Microsoft SDK for Java

getCanConnectToFileURLCodeBase

This method of the NetIOPermission Class returns the flag that controls whether classes that possess this permission can connect back to the local host if from a file:// URL codebase.

Syntax

public boolean getCanConnectToFileURLCodeBase();

Return Value

Returns true if the permission allows connections back to file:// URL codebase hosts; otherwise, returns false.


getCanConnectToNonFileURLCodeBase (NetIOPermission Class)

 Microsoft SDK for Java

getCanConnectToNonFileURLCodeBase

This method of the NetIOPermission Class retrieves the flag that controls whether classes that possess this permission can connect back to non-file:// URL codebase hosts.

Syntax

public boolean getCanConnectToNonFileURLCodeBase();

Return Value

Returns true if the permission allows connections back to non-file:// URL codebase hosts; otherwise, returns false.


getGlobalPortRules (NetIOPermission Class)

 Microsoft SDK for Java

getGlobalPortRules

This method of the NetIOPermission Class obtains the global port rules for the specified connection type in String form.

Syntax

public String getGlobalPortRules(int flags);

Return Value

Returns the port ranges in textual form.

Parameters

flags The connection type, which consists of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, or MULTICAST to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the rules should be obtained using the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.


getGlobalPorts (NetIOPermission Class)

 Microsoft SDK for Java

getGlobalPorts

This method of the NetIOPermission Class obtains the global ports rules for the specified connection type.

Syntax

public IntRanges getGlobalPorts(int flags);

Return Value

Returns the port ranges for the connection type.

Parameters

flags The connection type, which consists of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, or MULTICAST to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the rules should be obtained using the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.


getHostRules (NetIOPermission Class)

 Microsoft SDK for Java

getHostRules

This method of the NetIOPermission Class obtains the combined set of host name patterns and corresponding port rules for the specified connection type, in String form.

Syntax

public String getHostRules(int flags);

Return Value

Returns a String that describes the hosts that apply to the specified connection type.

Parameters

flags The connection type, which consists of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, or MULTICAST to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the rules should be obtained using the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.


getHosts (NetIOPermission Class)

 Microsoft SDK for Java

getHosts

This method of the NetIOPermission Class obtains a combined pattern that matches all the host name patterns for the specified connection type.

Syntax

public WildcardExpression getHosts(int flags);

Return Value

Returns a WildcardExpression that describes the hosts that apply to the specified connection type.

Parameters

flags The connection type, which consists of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, or MULTICAST to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the pattern should be obtained using the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.


getIPRules (NetIOPermission Class)

 Microsoft SDK for Java

getIPRules

This method of the NetIOPermission Class obtains the combined set of 32-bit IP ranges and corresponding port rules for the specified connection type, in String form.

Syntax

public String getIPRules(int flags);

Return Value

Returns the string form of the IP ranges that apply to the specified connection type.

Parameters

flags The connection type, which consists of two separate flags combined with a logical OR operator (|). The first flag should be either BIND or CONNECT to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the 32-bit IP ranges should be obtained using the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWCONNECT, DENYCONNECT, ALLOWBIND, or DENYBIND.


getIPs (NetIOPermission Class)

 Microsoft SDK for Java

getIPs

This method of the NetIOPermission Class obtains the combined set of 32-bit IP ranges for the specified connection type.

Syntax

public IntRanges getIPs(int flags);

Return Value

Returns the IP ranges that apply to the specified connection type.

Parameters

flags The connection type, which consists of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, or MULTICAST to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the IP ranges should be obtained using the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.


getPorts (NetIOPermission Class)

 Microsoft SDK for Java

getPorts

This method of the NetIOPermission Class obtains the port rules corresponding to each of the hosts or IPs for the specified connection type.

Syntax

public IntRanges[] getPorts(int flags);

Return Value

Returns the port ranges that apply to the hosts or IPs.

Parameters

flags The connection type, which consists of two separate flags combined with a logical OR operator (|). The first flag should be BIND, CONNECT, or MULTICAST to specify the connection type. The second flag should be either ALLOW or DENY to indicate whether the rules should be obtained using the include or exclude rules. For convenience, instead of using the logical OR operator with the two flags, you can use one of the combination flags: ALLOWCONNECT, DENYCONNECT, ALLOWBIND, DENYBIND, ALLOWMULTICAST, or DENYMULTICAST.


mapFormat (NetIOPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the NetIOPermission Class retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


reset (NetIOPermission Class)

 Microsoft SDK for Java

reset

This method of the NetIOPermission Class resets the permission state to empty.

Syntax

public void reset();


setCanConnectToFileURLCodeBase (NetIOPermission Class)

 Microsoft SDK for Java

setCanConnectToFileURLCodeBase

This method of the NetIOPermission Class sets the flag that controls whether classes that possess this permission can connect to the local host if the codebase URL associated with the classes is a file:// URL.

Syntax

public void setCanConnectToFileURLCodeBase(boolean f);

Parameters

f If this value is true, the permission will allow connections back to the local host if the codebase URL is a file:// URL.

Remarks

If this flag is set to true, a later "codebase" adjustment using the adjustPermission method will include the local host in the set of hosts that this permission can connect to.


setCanConnectToNonFileURLCodeBase (NetIOPermission Class)

 Microsoft SDK for Java

setCanConnectToNonFileURLCodeBase

This method of the NetIOPermission Class sets the flag that controls whether classes that possess this permission can connect back to their originating host if the codebase URL is not a file:// URL.

Syntax

public void setCanConnectToNonFileURLCodeBase(boolean f);

Parameters

f If this value is true, the permission allows connections back to the originating host if the codebase URL is not a file:// URL.

Remarks

If this flag is set to true, a later "codebase" adjustment using the adjustPermission method will include the host of the codebase URL to the set of hosts that this permission can connect to.


supportedFormats (NetIOPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the NetIOPermission Class retrieves the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (NetIOPermission Class)

 Microsoft SDK for Java

toString

This method of the NetIOPermission Class retrieves a textual representation of the permission object.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


Fields (NetIOPermission Class)

 Microsoft SDK for Java

NetIOPermission Class Fields

The NetIOPermission Class contains the following fields.

ALL_API_FLAGS | A combination of the CONNECT, BIND, and MULTICAST flags.
ALLOW | A flag that indicates that some operation should be allowed by this permission.
ALLOWALL | A combination of the ALLOW, CONNECT, and BIND flags.
ALLOWBIND | A combination of the ALLOW and BIND flags.
ALLOWCONNECT | A combination of the ALLOW and CONNECT flags.
ALLOWMULTICAST | A combination of the ALLOW and MULTICAST flags.
BIND | A flag that indicates an operation that listens on a local port for network connections from other hosts.
CONNECT | A flag that indicates a network connection operation.
DENY | A flag that indicates that some operation should be denied by this permission.
DENYALL | A combination of the DENY, CONNECT, and BIND flags.
DENYBIND | A combination of the DENY and BIND flags.
DENYCONNECT | A combination of the DENY and CONNECT flags.
DENYMULTICAST | A combination of the DENY and MULTICAST flags.
HOSTS | A flag that indicates that network computers are identified by host name.
IPS | A flag that indicates that network computers are identified by an IP address.
MULTICAST | A flag that indicates a multicast socket operation.


NetIORequest Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

NetIORequest Class

The NetIORequest Class of the com.ms.security.permissions package represents a request to perform a network-related action.

public class NetIORequest implements ISecurityRequest
{
  // Fields
  public static final int ACCEPT;
  public static final int CONNECT;
  public static final int LISTEN;
  public static final int MULTICAST;

  // Constructors
  public NetIORequest(int accesstype, String hostname);
  public NetIORequest(int accesstype, String hostname, int port);
  public NetIORequest(int accesstype, int port);
  public NetIORequest(int accesstype, InetAddress addr, int ttl);
  public NetIORequest(int accesstype, InetAddress addr);

  // Methods
  public PermissionID getPermissionID();
  public String toString();
}

Use NetIORequest objects as the security request objects for parameterized security checks involving the networking I/O permission. The NetIOPermission.check method expects a NetIORequest object as its parameter.

Example

This example shows how to use a NetIORequest object to perform a security check.

...
// Create a NetIORequest that indicates that you want to
// connect to the host 'any.thing.com'.

NetIORequest sreq = new NetIORequest(NetIORequest.CONNECT,
   "any.thing.com");

// Check to see that all of your callers have the rights to
// connect to that host.

PolicyEngine.checkPermission(sreq);
...

For more information about checking networking permissions, see the PolicyEngine class and the NetIOPermission class.


Constructors (NetIORequest Class)

 Microsoft SDK for Java

NetIORequest Class Constructors

The NetIORequest Class contains the following constructors:

NetIORequest(int accesstype, String hostname)
NetIORequest(int accesstype, String hostname, int port)
NetIORequest(int accesstype, int port)
NetIORequest(int accesstype, InetAddress addr, int ttl)
NetIORequest(int accesstype, InetAddress addr)

NetIORequest(int accesstype, String hostname)

Creates a networking I/O request that specifies an attempt to connect to the specified host or to receive connections from the specified host.

Syntax

public NetIORequest(int accesstype, String hostname);

Parameters

accesstype | The type of access requested.
hostname | The name of the host.

NetIORequest(int accesstype, String hostname, int port)

Creates a networking I/O request that specifies an attempt to connect to the specified host/port or to receive connections from the specified host on the specified port.

Syntax

public NetIORequest(int accesstype, String hostname, int port);

Parameters

accesstype | The type of access requested. The value must be CONNECT or ACCEPT.
hostname | The network host to access.
port | The port to access.

NetIORequest(int accesstype, int port)

Creates a networking I/O request that specifies an attempt to listen for networking connections on the specified port.

Syntax

public NetIORequest(int accesstype, int port);

Parameters

accesstype | The type of access requested. The value should be LISTEN.
port | The local port number to listen on.

NetIORequest(int accesstype, InetAddress addr, int ttl)

Creates a networking I/O request that specifies an attempt to perform a multicast operation to the specified Internet address with the specified time to live value.

Syntax

public NetIORequest(int accesstype, InetAddress addr, int ttl);

Parameters

accesstype | The type of access requested. The value should be MULTICAST.
addr | The Internet address.
ttl | The time to live value.

NetIORequest(int accesstype, InetAddress addr)

Creates a networking I/O request that specifies an attempt to perform a multicast operation to the specified Internet address.

Syntax

public NetIORequest(int accesstype, InetAddress addr);

Parameters

accesstype | The type of access requested. The value should be MULTICAST.
addr | The Internet address.


Methods (NetIORequest Class)

 Microsoft SDK for Java

NetIORequest Class Methods

The NetIORequest Class contains the following methods:

getPermissionID retrieves the permission identifier for the NetIORequest object.
toString converts the NetIORequest object to its string representation.


getPermissionID (NetIORequest Class)

 Microsoft SDK for Java

getPermissionID

This method of the NetIORequest Class retrieves the permission identifier for the NetIORequest object.

Syntax

public PermissionID getPermissionID();

Return Value

Returns PermissionID.NETIO.

Remarks

This method satisfies the ISecurityRequest interface and returns PermissionID.NETIO to indicate that instances of the NetIORequest class are associated with the networking permission.


toString (NetIORequest Class)

 Microsoft SDK for Java

toString

This method of the NetIORequest Class converts the NetIORequest object to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the NetIORequest object.


Fields (NetIORequest Class)

 Microsoft SDK for Java

NetIORequest Class Fields

The NetIORequest Class contains the following fields.

ACCEPT | The network I/O access type that indicates an attempt to accept network connections from a remote computer.
CONNECT | The network I/O access type that indicates an attempt to initiate a connection with a remote machine.
LISTEN | The network I/O access type that indicates an attempt to listen for networking connections on a local port.
MULTICAST | The network I/O access type that indicates an attempt to perform a multicast socket operation.


PrintingPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

PrintingPermission Class

The PrintingPermission Class of the com.ms.security.permissions package represents a permission that controls access to the printing APIs.

public class PrintingPermission implements IPermission,
            IEncodablePermission
{
  // Methods
  public void check(Object request) throws SecurityException;
  public IPermission combine(IPermission other);
  public int compareSet(Object other);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public String mapFormat(String format);
  public String[] supportedFormats();
}

Security checks for the printing permission are non-parameterized. When the permission-based security model is enabled, classes that possess the PrintingPermission can use the printing services.

This class implements the IPermission and the IEncodablePermission interfaces.


Methods (PrintingPermission Class)

 Microsoft SDK for Java

PrintingPermission Class Methods

The PrintingPermission Class contains the following methods:

check performs a check on the permission object.
combine returns a new PrintingPermission instance.
compareSet compares the PrintingPermission instance with another permission object.
copy retrieves a new instance of the PrintingPermission class.
decode decodes the contents of the specified data stream into the permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
mapFormat retrieves a permission-specific tag when given an encoding format.
supportedFormats retrieves the encoding formats that this permission type supports.


check (PrintingPermission Class)

 Microsoft SDK for Java

check

This method of the PrintingPermission Class performs a check on the permission object. Because checks for the printing permission are non-parameterized, this method always succeeds.

Syntax

public void check(Object request) throws SecurityException;

Parameters

request This parameter is ignored.


combine (PrintingPermission Class)

 Microsoft SDK for Java

combine

This method of the PrintingPermission Class returns a new PrintingPermission instance. Because checks for the printing permission are non-parameterized, the combine operation serves no purpose.

Syntax

public IPermission combine(IPermission other);

Return Value

Returns a new PrintingPermission instance.

Parameters

other This parameter is ignored, but it must be an instance of the PrintingPermission class.


compareSet (PrintingPermission Class)

 Microsoft SDK for Java

compareSet

This method of the PrintingPermission Class compares the PrintingPermission instance with another permission object.

Syntax

public int compareSet(Object other);

Return Value

Returns EQUAL if the other object is an instance of the PrintingPermission class.

Parameters

other The permission object that the PrintingPermission instance is compared with. This parameter must be an instance of the PrintingPermission class.

Exceptions

IllegalArgumentException if the specified Object is not an instance of the PrintingPermission class.


copy (PrintingPermission Class)

 Microsoft SDK for Java

copy

This method of the PrintingPermission Class retrieves a new instance of the PrintingPermission class.

Syntax

public IPermission copy();

Return Value

Returns a new PrintingPermission instance.


decode (PrintingPermission Class)

 Microsoft SDK for Java

decode

This method of the PrintingPermission Class decodes the contents of the specified data stream into the permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (PrintingPermission Class)

 Microsoft SDK for Java

encode

This method of the PrintingPermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


mapFormat (PrintingPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the PrintingPermission Class retrieves a permission-specific tag when given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


supportedFormats (PrintingPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the PrintingPermission Class retrieves the encoding formats that this permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


PropertyAccessRequest Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

PropertyAccessRequest Class

The PropertyAccessRequest Class of the com.ms.security.permissions package represents a request to access the system properties.

public class PropertyAccessRequest implements ISecurityRequest
{
  // Fields
  public static final int ALL;
  public static final int INDIVIDUAL;

  // Constructors
  public PropertyAccessRequest(int type,String param);
  public PropertyAccessRequest();
  public PropertyAccessRequest(String prop);

  // Methods
  public PermissionID getPermissionID();
  public String toString();
}

Use an instance of this class as the security request object for a parameterized security check involving the system properties permission. The PropertyPermission.check method expects a PropertyAccessRequest object as its parameter.

Example

The following example shows how to use a PropertyAccessRequest object to perform a security check:

...
// Create a PropertyAccessRequest object that indicates
// that you want to read the system property called
// java.class.path.

PropertyAccessRequest sreq =
   new PropertyAccessRequest("java.class.path");

// Check to see that all of your callers have the
// rights to read that system property.

PolicyEngine.checkPermission(sreq);
...

For more information about checking system properties, see the PolicyEngine class and the PropertyPermission class.


Constructors (PropertyAccessRequest Class)

 Microsoft SDK for Java

PropertyAccessRequest Class Constructors

The PropertyAccessRequest Class contains the following constructors:

PropertyAccessRequest(int type,String param)
PropertyAccessRequest()
PropertyAccessRequest(String prop)

PropertyAccessRequest(int type, String param)

Creates a property access request for a specified access type and a specified property.

Syntax

public PropertyAccessRequest(int type, String param);

Return Value

Returns the request object that represents a request for access to the specified property.

Parameters

type | The type of property access. This can be ALL or INDIVIDUAL.
param | If type is INDIVIDUAL, this value should be the property name for the specified access type. If type is ALL, the value should be null.

PropertyAccessRequest()

Creates a property access request that indicates a request for unrestricted access to properties.

Syntax

public PropertyAccessRequest();

Return Value

Returns the request object that indicates a request to access all system properties.

PropertyAccessRequest(String prop)

Creates a request object that represents an attempt to read the specified property.

Syntax

public PropertyAccessRequest(String prop);

Return Value

Returns the request object that represents an attempt to read the specified property.

Parameters

prop The name of the system property to read.


Methods (PropertyAccessRequest Class)

 Microsoft SDK for Java

PropertyAccessRequest Class Methods

The PropertyAccessRequest Class contains the following methods:

getPermissionID retrieves the permission identifier for the PropertyAccessRequest object.
toString converts the PropertyAccessRequest object to its string representation.


getPermissionID (PropertyAccessRequest Class)

 Microsoft SDK for Java

getPermissionID

This method of the PropertyAccessRequest Class retrieves the permission identifier for the PropertyAccessRequest object.

Syntax

public PermissionID getPermissionID();

Return Value

Returns PermissionID.PROPERTY.

Remarks

This method satisfies the ISecurityRequest interface and returns PermissionID.PROPERTY to indicate that instances of the PropertyAccessRequest class are associated with the system property permission.


toString (PropertyAccessRequest Class)

 Microsoft SDK for Java

toString

This method of the PropertyAccessRequest Class converts the PropertyAccessRequest object to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the PropertyAccessRequest object.


Fields (PropertyAccessRequest Class)

 Microsoft SDK for Java

PropertyAccessRequest Class Fields

The PropertyAccessRequest Class contains the following fields.

ALL | The system property access type that indicates the unrestricted ability to read and modify all system properties.
INDIVIDUAL | The system property access type that indicates the ability to read the contents of a single specified system property.


PropertyPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

PropertyPermission Class

The PropertyPermission Class of the com.ms.security.permissions package represents a permission that controls the ability to access and manipulate the global system properties. The StandardSecurityManager checks for this permission type when performing the checkPropertiesAccess and checkPropertyAccess operations.

public class PropertyPermission implements IPermission,
            IEncodablePermission
{
  // Constructors
  public PropertyPermission();

  // Methods
  public void addAllowedSuffix(String suffix);
  public boolean allowsUnrestrictedAccess();
  public void allowUnrestrictedAccess(boolean flag);
  public void check(Object param);
  public IPermission combine(IPermission other);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public void excludeProperties(String pattern);
  public String[] getAllowedSuffixes();
  public WildcardExpression getExcludedProperties();
  public WildcardExpression getIncludedProperties();
  public void includeProperties(String pattern);
  public String mapFormat(String format);
  public void reset();
  public String[] supportedFormats();
  public String toString();
}

This class implements the IPermission and IEncodablePermission interfaces.

See Also

com.ms.security.permissions.PropertyAccessRequest


Constructors (PropertyPermission Class)

 Microsoft SDK for Java

PropertyPermission Class Constructors

The PropertyPermission Class contains the following constructor:

PropertyPermission()

Creates a new PropertyPermission instance.

Syntax

public PropertyPermission();

Remarks

The new instance does not allow access to any of the system properties. To add property names to the allowed set, you can use the allowUnrestrictedAccess, addAllowedSuffix, and the includeProperties methods.


Methods (PropertyPermission Class)

 Microsoft SDK for Java

PropertyPermission Class Methods

The PropertyPermission Class contains the following methods:

addAllowedSuffix adds an allowed property suffix to the permission object.
allowsUnrestrictedAccess determines whether this permission object allows unrestricted access to system properties.
allowUnrestrictedAccess turns unrestricted property access on or off, depending on the value of the flag.
check determines whether the permission allows the system property access specified by the PropertyAccessRequest parameter.
combine creates and returns a new PropertyPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the PropertyPermission instance with a specified permission object.
copy retrieves a copy of the PropertyPermission object.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
excludeProperties explicitly excludes system properties from the set of properties that this permission allows access to.
getAllowedSuffixes retrieves the list of property suffixes that the permission object allows access to.
getExcludedProperties retrieves a wildcard expression that represents all the properties that this permission object explicitly denies access to.
getIncludedProperties retrieves a wildcard expression that represents all the properties that this permission object allows access to.
includeProperties adds specific properties to the set of properties that the permission allows access to.
mapFormat retrieves a permission-specific tag when given an encoding format.
reset resets the permission object to a state in which it allows access to no system properties.
supportedFormats retrieves the encoding formats that the permission type supports.
toString retrieves a textual representation of the permission object.


addAllowedSuffix (PropertyPermission Class)

 Microsoft SDK for Java

addAllowedSuffix

This method of the PropertyPermission Class adds an allowed property suffix to the permission object.

Syntax

public void addAllowedSuffix(String suffix);

Parameters

suffix The property suffix to be added.

Remarks

Property suffixes work as follows: If you have access to a suffix "X", you have access to any system property "Y" if and only if a second system property named "Y.X" exists that is set to "true."


allowsUnrestrictedAccess (PropertyPermission Class)

 Microsoft SDK for Java

allowsUnrestrictedAccess

This method of the PropertyPermission Class determines whether this permission object allows unrestricted access to system properties.

Syntax

public boolean allowsUnrestrictedAccess();

Return Value

Returns true if this permission object allows unrestricted access to system properties.


allowUnrestrictedAccess (PropertyPermission Class)

 Microsoft SDK for Java

allowUnrestrictedAccess

This method of the PropertyPermission Class turns unrestricted property access on or off, depending on the value of the flag. Unrestricted property access allows you to read all system properties, and to obtain the system properties object and manipulate it.

Syntax

public void allowUnrestrictedAccess(boolean flag);

Parameters

flag The flag that indicates whether access to unrestricted properties should be turned on or off.


check (PropertyPermission Class)

 Microsoft SDK for Java

check

This method of the PropertyPermission Class determines whether the permission allows the system property access specified by the PropertyAccessRequest parameter.

Syntax

public void check(Object param);

Parameters

param The security request parameter. It must be an instance of PropertyAccessRequest.

Remarks

If the PropertyAccessRequest is requesting ALL access, this check will only succeed if this permission object has unrestricted access to the system properties. Otherwise, the PropertyAccessRequest parameter indicates a request for access to a specific system property by name. In this case, the following rules are used to determine whether the check passes or fails.

  1. If the permission object allows unrestricted access, the check passes.

  2. If the specified property is within the set of explicitly denied properties, the check fails.

  3. If the specified property is within the set of explicitly allowed properties, the check succeeds. Otherwise, the check fails.

Exceptions

SecurityException if this permission does not allow access to the specified system property.


combine (PropertyPermission Class)

 Microsoft SDK for Java

combine

This method of the PropertyPermission Class creates and returns a new PropertyPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission other);

Return Value

Returns the resulting PropertyPermission.

Parameters

other The PropertyPermission to combine with.

Exceptions

IllegalArgumentException if the specified object to combine with is not an instance of PropertyPermission.


compareSet (PropertyPermission Class)

 Microsoft SDK for Java

compareSet

This method of the PropertyPermission Class compares the PropertyPermission instance with a specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the PropertyPermission instance is compared with.


copy (PropertyPermission Class)

 Microsoft SDK for Java

copy

This method of the PropertyPermission Class retrieves a copy of the PropertyPermission object.

Syntax

public IPermission copy();

Return Value

Returns the PropertyPermission object that is a copy of the current PropertyPermission object.


decode (PropertyPermission Class)

 Microsoft SDK for Java

decode

This method of the PropertyPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (PropertyPermission Class)

 Microsoft SDK for Java

encode

This method of the PropertyPermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


excludeProperties (PropertyPermission Class)

 Microsoft SDK for Java

excludeProperties

This method of the PropertyPermission Class explicitly excludes system properties from the set of properties that this permission allows access to.

Syntax

public void excludeProperties(String pattern);

Parameters

pattern The pattern that specifies the system properties that are explicitly prohibited. This pattern can contain wildcard expressions.

Remarks

Because access to all system properties is prohibited by default, this method is only useful to remove properties from those explicitly included by a wildcard expression. For example, the following code allows access to all properties beginning with 'java.' except for the property named "java.class.path":

   ...
   PropertyPermission perm = new PropertyPermission()
   eperm.includeProperties("java.*");
   eperm.excludeProperties("java.class.path");
   ...

Note This method does nothing if the permission object already specifies unrestricted access.

See Also

com.ms.util.WildcardExpression


getAllowedSuffixes (PropertyPermission Class)

 Microsoft SDK for Java

getAllowedSuffixes

This method of the PropertyPermission Class retrieves the list of property suffixes that the permission object allows access to.

Syntax

public String[] getAllowedSuffixes();

Return Value

Returns the list of property suffixes that the permission object allows access to.


getExcludedProperties (PropertyPermission Class)

 Microsoft SDK for Java

getExcludedProperties

This method of the PropertyPermission Class retrieves a wildcard expression that represents all the properties that this permission object explicitly denies access to.

Syntax

public WildcardExpression getExcludedProperties();

Return Value

Returns the wildcard expression that represents all the properties that this permission object explicitly denies access to.

See Also

com.ms.util.WildcardExpression


getIncludedProperties (PropertyPermission Class)

 Microsoft SDK for Java

getIncludedProperties

This method of the PropertyPermission Class retrieves a wildcard expression that represents all the properties that this permission object allows access to.

Syntax

public WildcardExpression getIncludedProperties();

Return Value

Returns the wildcard expression that represents all the properties that this permission object allows access to.

See Also

com.ms.util.WildcardExpression


includeProperties (PropertyPermission Class)

 Microsoft SDK for Java

includeProperties

This method of the PropertyPermission Class adds specific properties to the set of properties that the permission allows access to. The properties are specified by a pattern string that can contain wildcard expressions.

Syntax

public void includeProperties(String pattern);

Examples

includeProperties("java.class.path");

includeProperties("java.*");

Note This method does nothing if the permission object already specifies unrestricted access.

Parameters

pattern The pattern that specifies the system properties that can be accessed. This pattern can contain wildcard expressions.

See Also

com.ms.util.WildcardExpression


mapFormat (PropertyPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the PropertyPermission Class retrieves a permission-specific tag when given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


reset (PropertyPermission Class)

 Microsoft SDK for Java

reset

This method of the PropertyPermission Class resets the permission object to a state in which it allows access to no system properties.

Syntax

public void reset();


supportedFormats (PropertyPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the PropertyPermission Class retrieves the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (PropertyPermission Class)

 Microsoft SDK for Java

toString

This method of the PropertyPermission Class retrieves a textual representation of the permission object.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


ReflectionPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

ReflectionPermission Class

The ReflectionPermission Class of the com.ms.security.permissions package represents a permission that controls the ability to perform reflection operations. The StandardSecurityManager checks for this permission type when performing the checkMemberAccess operation.

public class ReflectionPermission implements IPermission,
            IEncodablePermission, IAdjustablePermission
{
  // Fields
  public static int ALL;
  public static int DIFFERENTLOADER;
  public static int NONE;
  public static int SAMELOADER;
  public static int SYSTEMLOADER;

  // Constructors
  public ReflectionPermission();

  // Methods
  public void adjustPermission(String tag, Object adjustment);
  public void check(Object param);
  public IPermission combine(IPermission source2);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public int getAllowedAccess(int accessType);
  public int getAllowedDeclaredAccess();
  public int getAllowedPublicAccess();
  public ClassLoader getAssociatedLoader();
  public String mapFormat(String format);
  public void reset();
  public void setAllowedDeclaredAccess(int loadertypes);
  public void setAllowedPublicAccess(int loadertypes);
  public void setAssociatedLoader(ClassLoader ldr);
  public String[] supportedFormats();
  public String toString();
}

A ReflectionPermission distinguishes between two different types of reflection operations:

Public

Reflective access to a public member of some class. This type of access is specified by the constant java.lang.reflect.Member.PUBLIC.

Declared

Reflective access to any member of a given class. This type of access is specified by the constant java.lang.reflect.Member.DECLARED.

A ReflectionPermission object further distinguishes between types of reflection operations, depending on the type of class being reflected. The types of classes that can be reflected are as follows:

SAMELOADER

A class from the same loader as the class initiating the reflection operation.

DIFFERENTLOADER

A non-system class from a loader other than that of the class that is initiating the reflection operation.

SYSTEMLOADER

A System class.

See Also

com.ms.security.permissions.ReflectionRequest


Constructors (ReflectionPermission Class)

 Microsoft SDK for Java

ReflectionPermission Class Constructors

The ReflectionPermission Class contains the following constructor:

ReflectionPermission()

Creates a new ReflectionPermission instance. The new instance does not allow reflective access to any classes.

Syntax

public ReflectionPermission();


Methods (ReflectionPermission Class)

 Microsoft SDK for Java

ReflectionPermission Class Methods

The ReflectionPermission Class contains the following methods:

adjustPermission adjusts the permission object with some run-time state.
check determines whether the permission object allows the specified action.
combine creates and returns a new ReflectionPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the ReflectionPermission instance with a specified permission object.
copy retrieves a copy of the ReflectionPermission instance.
decode decodes a source according to the specified tag.
encode encodes a source according to the specified tag.
getAllowedAccess retrieves the types of classes that the permission object allows access to, based on a reflective access type.
getAllowedDeclaredAccess retrieves the types of classes that the permission object allows declared access to.
getAllowedPublicAccess retrieves the types of classes that the permission object allows public access to.
getAssociatedLoader retrieves the class loader associated with this permission object.
mapFormat retrieves a permission-specific tag when given an encoding format.
reset resets the permission object to a state in which it allows no reflection access.
setAllowedDeclaredAccess sets the types of classes that the permission object allows declared reflective access to.
setAllowedPublicAccess sets the types of classes that the permission object allows public reflective access to.
setAssociatedLoader sets the class loader that this permission is associated with.
supportedFormats retrieves a list of supported formats.
toString converts the permission object to its string representation.


adjustPermission (ReflectionPermission Class)

 Microsoft SDK for Java

adjustPermission

This method of the ReflectionPermission Class adjusts the permission object with some run-time state. The ReflectionPermission only responds to the "classloader" adjustment type. This method expects the adjustment parameter to be a ClassLoader instance. All other adjustment types are ignored. The class loader instance used for the adjustment parameter is the loader that SAMELOADER will refer to after this method adjusts the class loader.

Syntax

public void adjustPermission(String tag, Object adjustment);

Note The "classloader" adjustment to this permission is equivalent to an explicit setAssociatedLoader call.

Parameters

tag | The adjustment type. Every value except "classloader" is ignored.
adjustment | This parameter must be an instance of java.lang.ClassLoader for the "classloader" tag.


check (ReflectionPermission Class)

 Microsoft SDK for Java

check

This method of the ReflectionPermission Class determines whether the permission object allows the specified action. The request parameter represents a request to perform a particular action. The type of the parameter depends on the type of the permission object.

Syntax

public void check(Object param);

Parameters

param The object that represents the action for which permission is being checked.

Exceptions

SecurityException if the state of the permission object indicates that the action is not allowed.


combine (ReflectionPermission Class)

 Microsoft SDK for Java

combine

This method of the ReflectionPermission Class creates and returns a new ReflectionPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission source2);

Return Value

Returns the resulting ReflectionPermission object.

Parameters

source2 The permission object that indicates additional resources to allow access to.


compareSet (ReflectionPermission Class)

 Microsoft SDK for Java

compareSet

This method of the ReflectionPermission Class compares the ReflectionPermission instance with a specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the ReflectionPermission instance is compared with.


copy (ReflectionPermission Class)

 Microsoft SDK for Java

copy

This method of the ReflectionPermission Class retrieves a copy of the ReflectionPermission instance.

Syntax

public IPermission copy();

Return Value

Returns the copy of the ReflectionPermission instance.


decode (ReflectionPermission Class)

 Microsoft SDK for Java

decode

This method of the ReflectionPermission Class decodes a source according to the specified tag. This method implements the IEncodablePermission.decode method.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding process is completed successfully; otherwise, returns false.

Parameters

tag | The tag used for the decoding. It is the same tag that was used to encode the data.
data | The stream that contains the encoded permission.


encode (ReflectionPermission Class)

 Microsoft SDK for Java

encode

This method of the ReflectionPermission Class encodes a source according to the specified tag. This method implements the IEncodablePermission.encode method.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding process is completed successfully; otherwise, returns false.

Parameters

tag | The string that indicates how to encode the data.
out | The stream to write the encoded data to.


getAllowedAccess (ReflectionPermission Class)

 Microsoft SDK for Java

getAllowedAccess

This method of the ReflectionPermission Class retrieves the types of classes that the permission object allows access to, based on a reflective access type.

Syntax

public int getAllowedAccess(int accessType);

Return Value

Returns the types of classes that the permission object allows access to. This will be one of the following: SAMELOADER, DIFFERENTLOADER, SYSTEMLOADER, ALL, or NONE.

Parameters

accessType The reflective access type. It must be either java.lang.reflect.Member.PUBLIC or java.lang.reflect.Member.DECLARED.

Exceptions

IllegalArgumentException if the accessType parameter is not equal to java.lang.reflect.Member.PUBLIC or java.lang.reflect.Member.DECLARED.


getAllowedDeclaredAccess (ReflectionPermission Class)

 Microsoft SDK for Java

getAllowedDeclaredAccess

This method of the ReflectionPermission Class retrieves the types of classes that the permission object allows declared access to.

Syntax

public int getAllowedDeclaredAccess();

Return Value

Returns the types of classes that the permission object allows declared access to. This will be one of the following: SAMELOADER, DIFFERENTLOADER, SYSTEMLOADER, ALL, or NONE.


getAllowedPublicAccess (ReflectionPermission Class)

 Microsoft SDK for Java

getAllowedPublicAccess

This method of the ReflectionPermission Class retrieves the types of classes that the permission object allows public access to.

Syntax

public int getAllowedPublicAccess();

Return Value

Returns the types of classes that the permission object allows public access to. This will be one of the following: SAMELOADER, DIFFERENTLOADER, SYSTEMLOADER, ALL, or NONE.


getAssociatedLoader (ReflectionPermission Class)

 Microsoft SDK for Java

getAssociatedLoader

This method of the ReflectionPermission Class retrieves the class loader associated with this permission object.

Syntax

public ClassLoader getAssociatedLoader();

Return Value

Returns the class loader associated with the permission object.


mapFormat (ReflectionPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the ReflectionPermission Class retrieves a permission-specific tag when given an encoding format. The tag can be used with the encode and decode methods to specify an encoding type. This method implements the IEncodablePermission.mapFormat method.

Syntax

public String mapFormat(String format);

Return Value

Returns the tag used to encode the data in the given format. If the specified format is not supported, null is returned.

Parameters

format The format that the tag is requested for. If format is null, the default format for the class is returned.


reset (ReflectionPermission Class)

 Microsoft SDK for Java

reset

This method of the ReflectionPermission Class resets the permission object to a state in which it allows no reflection access.

Syntax

public void reset();


setAllowedDeclaredAccess (ReflectionPermission Class)

 Microsoft SDK for Java

setAllowedDeclaredAccess

This method of the ReflectionPermission Class sets the types of classes that the permission object allows declared reflective access to. The classes are specified by the loader types. For example, the following code indicates that the permission should only allow declared reflective access to classes from the same loader:

    ...
    ReflectionPermission perm = new ReflectionPermission();
    perm.setAssociatedLoader( some loader );
    perm.setAllowedDeclaredAccess(ReflectionPermission.SAMELOADER);
    ...

Syntax

public void setAllowedDeclaredAccess(int loadertypes);

Parameters

loadertypes The types of classes that the permission object will allow declared reflective access to. This should be one of the following types: SAMELOADER, DIFFERENTLOADER, SYSTEMLOADER, ALL, or NONE.


setAllowedPublicAccess (ReflectionPermission Class)

 Microsoft SDK for Java

setAllowedPublicAccess

This method of the ReflectionPermission Class sets the types of classes that the permission object allows public reflective access to. The classes are specified by the loader types. For example, the following code indicates that the permission should allow reflective access to public members of all classes:

    ...
    ReflectionPermission perm = new ReflectionPermission();
    perm.setAllowedPublicAccess(ReflectionPermission.ALL);
    ...

Syntax

public void setAllowedPublicAccess(int loadertypes);

Parameters

loadertypes The types of classes that the permission object allows public reflective access to. This should be one of the following types: SAMELOADER, DIFFERENTLOADER, SYSTEMLOADER, ALL, or NONE.


setAssociatedLoader (ReflectionPermission Class)

 Microsoft SDK for Java

setAssociatedLoader

This method of the ReflectionPermission Class sets the class loader that this permission is associated with. The associated class loader should be the class loader that loaded the classes that this permission will be assigned to. The loader access type SAMELOADER refers to the class loader set by this method.

Syntax

public void setAssociatedLoader(ClassLoader ldr);

Parameters

ldr The class loader object.


supportedFormats (ReflectionPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the ReflectionPermission Class retrieves a list of supported formats. This method implements the IEncodablePermission.supportedFormats method.

Syntax

public String[] supportedFormats();

Return Value

Returns the supported formats.


toString (ReflectionPermission Class)

 Microsoft SDK for Java

toString

This method of the ReflectionPermission Class converts the permission object to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


Fields (ReflectionPermission Class)

 Microsoft SDK for Java

ReflectionPermission Class Fields

The ReflectionPermission Class contains the following fields.

ALL | A loader type that indicates all classes.
DIFFERENTLOADER | A loader type that refers to any loaders other than the one associated with this permission instance. If no loader has been associated with this permission, this loader type refers to all non-system classes.
NONE | A loader type that indicates no classes.
SAMELOADER | A loader type that refers to the loader that has been associated with this permission object with the setAssociatedLoader method. If no loader has been associated with this permission instance, this loader type has no meaning.
SYSTEMLOADER | A loader type that indicates system classes.


ReflectionRequest Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

ReflectionRequest Class

The ReflectionRequest Class of the com.ms.security.permissions package represents a request to use the reflection APIs to gain access to members of a specified class.

public class ReflectionRequest implements ISecurityRequest
{
  // Constructors
  public ReflectionRequest(int type, Class target);

  // Methods
  public PermissionID getPermissionID();
  public String toString();
}

The type of access can be either to public members or to declared members of the class. ReflectionRequest objects should be used as the security request objects for parameterized security checks involving the reflection permission. The ReflectionPermission.check method expects a ReflectionRequest object as its parameter.

Example

The following example shows how to use a ReflectionRequest object to perform a security check:

  ...
  // Create a ReflectionRequest object that indicates that you want to
  // access the public members of a specific class.

  Class cls = java.lang.String.class;
  ReflectionRequest sreq = new ReflectionRequest(Member.PUBLIC,cls);

  // Check to see that all of your callers have the rights to
  // access the public members of the class.

  PolicyEngine.checkPermission(sreq);
  ...

For more information about checking reflection permissions, see the PolicyEngine class and the ReflectionPermission class.


Constructors (ReflectionRequest Class)

 Microsoft SDK for Java

ReflectionRequest Class Constructors

The ReflectionRequest Class contains the following constructor:

ReflectionRequest(int type, Class target)

Creates a ReflectionRequest object based on the access type requested and the class instance to reflect.

Syntax

public ReflectionRequest(int type, Class target);

Parameters

type | The type of reflection access that is requested. This value must be either java.lang.reflect.Member.PUBLIC or java.lang.reflect.Member.DECLARED.
target | The class to examine with the reflection APIs.


Methods (ReflectionRequest Class)

 Microsoft SDK for Java

ReflectionRequest Class Methods

The ReflectionRequest Class contains the following methods:

getPermissionID retrieves the permission identifier for the ReflectionRequest object.
toString converts the ReflectionRequest object to its string representation.


getPermissionID (ReflectionRequest Class)

 Microsoft SDK for Java

getPermissionID

This method of the ReflectionRequest Class retrieves the permission identifier for the ReflectionRequest object.

Syntax

public PermissionID getPermissionID();

Return Value

Returns PermissionID.REFLECTION.

Remarks

This method satisfies the ISecurityRequest interface and returns PermissionID.REFLECTION to indicate that instances of the ReflectionRequest class are associated with the reflection permission.


toString (ReflectionRequest Class)

 Microsoft SDK for Java

toString

This method of the ReflectionRequest Class converts the ReflectionRequest object to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the ReflectionRequest object.


RegistryPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

RegistryPermission Class

The RegistryPermission Class of the com.ms.security.permissions package represents a permission that controls the ability to access the registry. The StandardSecurityManager checks for this permission type when performing the checkRegistry operation.

public class RegistryPermission implements IPermission,
            IEncodablePermission
{
  // Fields
  public static final int CREATE;
  public static final int DELETE;
  public static final int OPEN;
  public static final int READ;
  public static final int WRITE;

  // Constructors
  public RegistryPermission();

  // Methods
  public void check(Object param);
  public IPermission combine(IPermission source2);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public void excludeRule(int access, String pattern);
  public WildcardExpression getExcludedRules(int accessType);
  public WildcardExpression getIncludedRules(int accessType);
  public void includeRule(int access, String pattern);
  public String mapFormat(String format);
  public void reset();
  public String[] supportedFormats();
  public String toString();
}

The registry permission distinguishes between five different types of access to registry keys or values, shown in the following list:

OPEN

Keys can be opened (does not apply to values).

READ

Information about a key or value can be read.

WRITE

A key or value can be modified.

DELETE

A key or value can be deleted.

CREATE

A key or value can be created.

The specific key or value allowed for each operation is defined by a pair of include/exclude patterns. Keys are specified by a trailing backslash (\). Absolute registry paths must start with a root key specifier, which is one of the following strings:

"HKCR"

HKEY_CLASSES_ROOT

"HKLM"

HKEY_LOCAL_MACHINE

"HKCU"

HKEY_CURRENT_USER

"HKUR"

HKEY_USERS

For example, "HKCU\\dog\\" specifies a key named "dog" under HKEY_CURRENT_USER. But "HKCU\\dog\\Fido" specifies the value named "Fido" within the key HKEY_CURRENT_USER\dog.

Note In source code, you must type two backslashes to represent the single backslash necessary for specifying a key.

See Also

com.ms.security.permissions.RegistryRequest


Constructors (RegistryPermission Class)

 Microsoft SDK for Java

RegistryPermission Class Constructors

The RegistryPermission Class contains the following constructor:

RegistryPermission()

Creates a new RegistryPermission instance. The new instance will not allow any access to any portion of the registry. Access to specific portions of the registry must be explicitly enabled.

Syntax

public RegistryPermission();


Methods (RegistryPermission Class)

 Microsoft SDK for Java

RegistryPermission Class Methods

The RegistryPermission Class contains the following methods:

check determines whether the specified registry operation is allowed by the permission object.
combine creates and returns a new RegistryPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the RegistryPermission instance with a specified permission object.
copy retrieves a copy of the RegistryPermission object.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
excludeRule adds a rule that explicitly denies the specified access type to the registry keys or values specified by the pattern string.
getExcludedRules returns the wildcard expression representing all the keys or values that are explicitly denied for the specified access type.
getIncludedRules retrieves the wildcard expression that represents all the keys or values that are allowed for the specified access type.
includeRule adds a rule that allows the specified access types to the registry keys/values specified by the pattern string.
mapFormat retrieves a permission-specific tag, given an encoding format.
reset resets the permission state to empty.
supportedFormats retrieves the encoding formats that the permission type supports.
toString retrieves a textual representation of the permission object.


check (RegistryPermission Class)

 Microsoft SDK for Java

check

This method of the RegistryPermission Class determines whether the specified registry operation is allowed by the permission object.

Syntax

public void check(Object param);

Parameters

param The security request parameter. It must be an instance of the RegistryRequest class.

Exceptions

SecurityException if this permission does not allow the specified operation.


combine (RegistryPermission Class)

 Microsoft SDK for Java

combine

This method of the RegistryPermission Class creates and returns a new RegistryPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission source2);

Return Value

Returns the resulting RegistryPermission object.

Parameters

source2 The other RegistryPermission object to combine with.

Exceptions

IllegalArgumentException if the specified object to combine with is not an instance of RegistryPermission.


compareSet (RegistryPermission Class)

 Microsoft SDK for Java

compareSet

This method of the RegistryPermission Class compares the RegistryPermission instance with a specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the RegistryPermission instance is compared with.


copy (RegistryPermission Class)

 Microsoft SDK for Java

copy

This method of the RegistryPermission Class retrieves a copy of the RegistryPermission object.

Syntax

public IPermission copy();

Return Value

Returns the copy of the RegistryPermission object.


decode (RegistryPermission Class)

 Microsoft SDK for Java

decode

This method of the RegistryPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (RegistryPermission Class)

 Microsoft SDK for Java

encode

This method of the RegistryPermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


excludeRule (RegistryPermission Class)

 Microsoft SDK for Java

excludeRule

This method of the RegistryPermission Class adds a rule that explicitly denies the specified access type to the registry keys or values specified by the pattern string. This method is used to modify a previously allowed rule to a more restricted type of access.

Syntax

public void excludeRule(int access, String pattern);

Parameters

access | The access types being added. Must be one of OPEN, READ, WRITE, DELETE, or CREATE, or any combination of these types used with the OR operator.
pattern | The registry keys/values to which the specified access type is being added. This parameter must be of the form accepted by a WildcardExpression with the ESCAPED flag enabled.


getExcludedRules (RegistryPermission Class)

 Microsoft SDK for Java

getExcludedRules

This method of the RegistryPermission Class returns the wildcard expression representing all the keys or values that are explicitly denied for the specified access type.

Syntax

public WildcardExpression getExcludedRules(int accessType);

Return Value

Returns the wildcard expression representing all the keys/values that are explicitly denied for the specified access type.

Parameters

accessType This value must be one of the following: OPEN, READ, WRITE, DELETE, or CREATE.


getIncludedRules (RegistryPermission Class)

 Microsoft SDK for Java

getIncludedRules

This method of the RegistryPermission Class retrieves the wildcard expression that represents all the keys or values that are allowed for the specified access type.

Syntax

public WildcardExpression getIncludedRules(int accessType');

Return Value

Returns the wildcard expression representing all the keys or values that are allowed for the specified access type.

Parameters

accessType The type of access used to determine the wildcard expression. This value must be one of the following: OPEN, READ, WRITE, DELETE, or CREATE.


includeRule (RegistryPermission Class)

 Microsoft SDK for Java

includeRule

This method of the RegistryPermission Class adds a rule that allows the specified access types to the registry keys/values specified by the pattern string.

Syntax

public void includeRule(int access, String pattern);

Parameters

access | The access types being added. Must be one of the following types: OPEN, READ, WRITE, DELETE, or CREATE, or any combination of these types used with the OR operator (|).
pattern | The registry keys or values to which the specified access type is being added. This parameter must be of the form accepted by a WildcardExpression with the ESCAPED flag enabled.


mapFormat (RegistryPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the RegistryPermission Class retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


reset (RegistryPermission Class)

 Microsoft SDK for Java

reset

This method of the RegistryPermission Class resets the permission state to empty. This is a state in which the object allows no registry access.

Syntax

public void reset();


supportedFormats (RegistryPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the RegistryPermission Class retrieves the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (RegistryPermission Class)

 Microsoft SDK for Java

toString

This method of the RegistryPermission Class retrieves a textual representation of the permission object.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


Fields (RegistryPermission Class)

 Microsoft SDK for Java

RegistryPermission Class Fields

The RegistryPermission Class contains the following fields.

CREATE | An access type that indicates that a key or value can be created.
DELETE | An access type that indicates that a key or value can be deleted.
OPEN | An access type that indicates that keys can be opened.
READ | An access type that indicates that information about a key or value can be read.
WRITE | An access type that indicates that a key or value can be modified.


RegistryRequest Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

RegistryRequest Class

The RegistryRequest Class of the com.ms.security.permissions package represents a request for access to a registry key.

public class RegistryRequest implements ISecurityRequest
{
  // Fields
  public static final int CREATE;
  public static final int DELETE;
  public static final int OPEN;
  public static final int READ;
  public static final int WRITE;

  // Constructors
  public RegistryRequest(int access, String value);

  // Methods
  public PermissionID getPermissionID();
  public String toString();
}

It should be used as the security request object for a parameterized security check involving registry permissions. The RegistryPermission.check method expects a RegistryRequest object as its parameter.

Example

The following example shows how to use a RegistryRequest object to perform a security check to see if a specific registry key can be accessed:

// Create a ReqistryRequest object that indicates that you want
// to read the registry key "HKLM\Software\stuff".

RegistryRequest sreq =
   new RegistryRequest(RegistryRequest.READ,"HKLM\Software\stuff");

// Check to see that all of your callers have the rights to
// read that registry key.

PolicyEngine.checkPermission(sreq);
...

For more information about checking registry permissions, see the com.ms.security.PolicyEngine class and the RegistryPermission class.


Constructors (RegistryRequest Class)

 Microsoft SDK for Java

RegistryRequest Class Constructors

The RegistryRequest Class contains the following constructor:

RegistryRequest(int access, String value)

Creates a RegistryRequest object based on the specified access type and value.

Syntax

public RegistryRequest(int access, String value);

Parameters

access | The type of access requested. It must be one of the following: OPEN, READ, WRITE, DELETE, or CREATE.
value | The key or value for which access is requested.


Methods (RegistryRequest Class)

 Microsoft SDK for Java

RegistryRequest Class Methods

The RegistryRequest Class contains the following methods:

getPermissionID retrieves the permission identifier for the RegistryRequest object.
toString converts the RegistryRequest object to its string representation.


getPermissionID (RegistryRequest Class)

 Microsoft SDK for Java

getPermissionID

This method of the RegistryRequest Class retrieves the permission identifier for the RegistryRequest object.

Syntax

public PermissionID getPermissionID();

This method satisfies the ISecurityRequestinterface and returns PermissionID.REGISTRY to indicate that instances of the RegistryRequest class are associated with the registry permission.

Return Value

Returns PermissionID.REGISTRY.


toString (RegistryRequest Class)

 Microsoft SDK for Java

toString

This method of the RegistryRequest Class converts the RegistryRequest object to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the RegistryRequest object.


Fields (RegistryRequest Class)

 Microsoft SDK for Java

RegistryRequest Class Fields

The RegistryRequest Class contains the following fields.

CREATE | The registry access type that represents a request to create a key or value.
DELETE | The registry access type that represents a request to delete a key or value.
OPEN | The registry access type that represents an attempt to open a registry key.
READ | The registry access type that represents a request to read or obtain information about a key or value.
WRITE | The registry access type that represents a request to modify a key or value.


SecurityPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

SecurityPermission Class

The SecurityPermission Class of the com.ms.security.permissions package represents a permission that controls access to the JDK security classes (the java.lang.security package). Checks for the security permission are non-parameterized.

public class SecurityPermission implements IPermission,
            IEncodablePermission
{
  // Methods
  public void check(Object request) throws SecurityException;
  public IPermission combine(IPermission other);
  public int compareSet(Object other);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public String mapFormat(String format);
  public String[] supportedFormats();
}

This class implements the IPermission and the IEncodablePermission interfaces.


Methods (SecurityPermission Class)

 Microsoft SDK for Java

SecurityPermission Class Methods

The SecurityPermission Class contains the following methods:

check performs a check on the permission object.
combine creates and returns a new SecurityPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the SecurityPermission instance with a specified permission object.
copy retrieves a new instance of the SecurityPermission class.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
mapFormat retrieves a permission-specific tag, given an encoding format.
supportedFormats retrieves the encoding formats that the permission type supports.


check (SecurityPermission Class)

 Microsoft SDK for Java

check

This method of the SecurityPermission Class performs a check on the permission object. Because checks for the security permission are non-parameterized, this method always succeeds.

Syntax

public void check(Object request) throws SecurityException;

Parameters

request This parameter is ignored.


combine (SecurityPermission Class)

 Microsoft SDK for Java

combine

This method of the SecurityPermission Class creates and returns a new SecurityPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission other);

Return Value

Returns a new SecurityPermission instance.

Parameters

other This parameter is ignored, but it must be an instance of the SecurityPermission class.


compareSet (SecurityPermission Class)

 Microsoft SDK for Java

compareSet

This method of the SecurityPermission Class compares the SecurityPermission instance with a specified permission object.

Syntax

public int compareSet(Object other);

Return Value

Returns EQUAL if the specified object is an instance of the SecurityPermission class.

Parameters

other The permission object that the SecurityPermission instance is compared with. The specified object must be an instance of the SecurityPermission class.

Exceptions

IllegalArgumentException if the specified Object is not an instance of the SecurityPermission class.


copy (SecurityPermission Class)

 Microsoft SDK for Java

copy

This method of the SecurityPermission Class retrieves a new instance of the SecurityPermission class.

Syntax

public IPermission copy();

Return Value

Returns a new SecurityPermission instance.


decode (SecurityPermission Class)

 Microsoft SDK for Java

decode

This method of the SecurityPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (SecurityPermission Class)

 Microsoft SDK for Java

encode

This method of the SecurityPermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


mapFormat (SecurityPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the SecurityPermission Class retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


supportedFormats (SecurityPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the SecurityPermission Class retrieves the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


SystemStreamsPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

SystemStreamsPermission Class

The SystemStreamsPermission Class of the com.ms.security.permissions package represents a permission that controls the ability to change the values of the system streams java.lang.System.in, java.lang.System.out, and java.lang.System.err. The StandardSecurityManager checks for this permission type when performing a checkSystemStreams operation.

public class SystemStreamsPermission implements IPermission,
            IEncodablePermission
{
  // Constructors
  public SystemStreamsPermission();

  // Methods
  public boolean canSetSystemErr();
  public boolean canSetSystemIn();
  public boolean canSetSystemOut();
  public void check(Object param) throws SecurityException;
  public IPermission combine(IPermission source2);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public String mapFormat(String format);
  public void reset();
  public void setCanSetSystemErr(boolean allow);
  public void setCanSetSystemIn(boolean allow);
  public void setCanSetSystemOut(boolean allow);
  public String[] supportedFormats();
  public String toString();
}

This class implements the IPermission and IEncodablePermission interfaces.


Constructors (SystemStreamsPermission Class)

 Microsoft SDK for Java

SystemStreamsPermission Class Constructors

The SystemStreamsPermission Class contains the following constructor:

SystemStreamsPermission()

Creates a new SystemStreamsPermission instance.

Syntax

public SystemStreamsPermission();

Remarks

The new instance does not allow access to any of the system streams. Access to a stream must be explicitly turned on by using one of the setCanSetSystemIn, setCanSetSystemOut, and setCanSetSystemErr methods.


Methods (SystemStreamsPermission Class)

 Microsoft SDK for Java

SystemStreamsPermission Class Methods

The SystemStreamsPermission Class contains the following methods:

canSetSystemErr determines whether the permission object allows the System.err stream to be set.
canSetSystemIn determines whether the permission object allows the System.in stream to be set.
canSetSystemOut determines whether the permission object allows the System.out stream to be set.
check determines whether the permission object allows the specified system stream to be set.
combine creates and returns a new SystemStreamsPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the SystemStreamsPermission instance with a specified permission object.
copy retrieves a copy of the SystemStreamsPermission object.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
mapFormat retrieves a permission-specific tag, given an encoding format.
reset resets the permission object to a state where it does not allow access to any of the system streams.
setCanSetSystemErr sets whether this permission object allows the system stream System.err to be set by classes that possess this permission instance.
setCanSetSystemIn sets whether this permission object allows the system stream System.in to be set by classes that possess this permission instance.
setCanSetSystemOut sets whether this permission object allows the system stream System.out to be set by classes that possess this permission instance.
supportedFormats retrieves the encoding formats that the permission type supports.
toString retrieves a textual representation of the permission object.


canSetSystemErr (SystemStreamsPermission Class)

 Microsoft SDK for Java

canSetSystemErr

This method of the SystemStreamsPermission Class determines whether the permission object allows the System.err stream to be set.

Syntax

public boolean canSetSystemErr();

Return Value

Returns true if the permission object allows the System.err stream to be set; otherwise, returns false.


canSetSystemIn (SystemStreamsPermission Class)

 Microsoft SDK for Java

canSetSystemIn

This method of the SystemStreamsPermission Class determines whether the permission object allows the System.in stream to be set.

Syntax

public boolean canSetSystemIn();

Return Value

Returns true if the permission object allows the System.in stream to be set; otherwise, returns false.


canSetSystemOut (SystemStreamsPermission Class)

 Microsoft SDK for Java

canSetSystemOut

This method of the SystemStreamsPermission Class determines whether the permission object allows the System.out stream to be set.

Syntax

public boolean canSetSystemOut();

Return Value

Returns true if the permission object allows the System.out stream to be set; otherwise, returns false.


check (SystemStreamsPermission Class)

 Microsoft SDK for Java

check

This method of the SystemStreamsPermission Class determines whether the permission object allows the specified system stream to be set.

Syntax

public void check(Object param) throws SecurityException;

Parameters

param The security request parameter. This parameter must be an instance of java.lang.Integer, whose value is interpreted as follows:

0

Indicates an attempt to set System.in.

1

Indicates an attempt to set System.out.

2

Indicates an attempt to set System.err.

Exceptions

SecurityException if the permission does not allow the specified operation.


combine (SystemStreamsPermission Class)

 Microsoft SDK for Java

combine

This method of the SystemStreamsPermission Class creates and returns a new SystemStreamsPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission source2);

Return Value

Returns the resulting SystemStreamsPermission object.

Parameters

source2 The SystemStreamsPermission object to combine with.

Exceptions

IllegalArgumentException if the specified object to combine with is not an instance of SystemStreamsPermission.


compareSet (SystemStreamsPermission Class)

 Microsoft SDK for Java

compareSet

This method of the SystemStreamsPermission Class compares the SystemStreamsPermission instance with a specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the SystemStreamsPermission instance is compared with.


copy (SystemStreamsPermission Class)

 Microsoft SDK for Java

copy

This method of the SystemStreamsPermission Class retrieves a copy of the SystemStreamsPermission object.

Syntax

public IPermission copy();

Return Value

Returns the copy of the SystemStreamsPermission object.


decode (SystemStreamsPermission Class)

 Microsoft SDK for Java

decode

This method of the SystemStreamsPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (SystemStreamsPermission Class)

 Microsoft SDK for Java

encode

This method of the SystemStreamsPermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


mapFormat (SystemStreamsPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the SystemStreamsPermission Class encodes the contents of this permission object and retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


reset (SystemStreamsPermission Class)

 Microsoft SDK for Java

reset

This method of the SystemStreamsPermission Class resets the permission object to a state where it does not allow access to any of the system streams.

Syntax

public void reset();


setCanSetSystemErr (SystemStreamsPermission Class)

 Microsoft SDK for Java

setCanSetSystemErr

This method of the SystemStreamsPermission Class sets whether this permission object allows the system stream System.err to be set by classes that possess this permission instance.

Syntax

public void setCanSetSystemErr(boolean allow);

Parameters

allow The value that indicates whether the permission allows System.err to be set. This value must be set to true if this permission should allow System.err to be set; otherwise, it should be set to false.


setCanSetSystemIn (SystemStreamsPermission Class)

 Microsoft SDK for Java

setCanSetSystemIn

This method of the SystemStreamsPermission Class sets whether this permission object allows the system stream System.in to be set by classes that possess this permission instance.

Syntax

public void setCanSetSystemIn(boolean allow);

Parameters

allow The value that indicates whether the permission allows System.in to be set. This value must be true if this permission should allow System.in to be set; otherwise, it should be false.


setCanSetSystemOut (SystemStreamsPermission Class)

 Microsoft SDK for Java

setCanSetSystemOut

This method of the SystemStreamsPermission Class sets whether this permission object allows the system stream System.out to be set by classes that possess this permission instance.

Syntax

public void setCanSetSystemOut(boolean allow);

Parameters

allow The value that indicates whether the permission allows System.out to be set. This value must be true if this permission should allow System.out to be set; otherwise, it should be false.


supportedFormats (SystemStreamsPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the SystemStreamsPermission Class retrieves the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (SystemStreamsPermission Class)

 Microsoft SDK for Java

toString

This method of the SystemStreamsPermission Class retrieves a textual representation of the permission object.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


ThreadPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

ThreadPermission Class

The ThreadPermission Class of the com.ms.security.permissions package represents a permission that controls the ability to create and manipulate threads and thread groups. The StandardSecurityManager class checks for this permission type when performing its checkAccess methods.

public class ThreadPermission implements IPermission,
            IEncodablePermission, IAdjustablePermission
{
  // Constructors
  public ThreadPermission();

  // Methods
  public void adjustPermission(String tag, Object adjustment);
  public void check(Object param) throws SecurityException;
  public IPermission combine(IPermission source2);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public ThreadGroup getAllowedThreadGroup();
  public boolean isThreadAccessUnrestricted();
  public boolean isThreadGroupAccessUnrestricted();
  public String mapFormat(String format);
  public void reset();
  public void setAllowedThreadGroup(ThreadGroup tg);
  public void setUnrestrictedThreadAccess(boolean f);
  public void setUnrestrictedThreadGroupAccess(boolean flag);
  public String[] supportedFormats();
  public String toString();
}

You can use a ThreadPermission object to allow unrestricted thread or thread group access. Or, you can specify a ThreadGroup instance that defines a subset of the thread group space, within which the ThreadPermission object allows threading operations to take place.


Constructors (ThreadPermission Class)

 Microsoft SDK for Java

ThreadPermission Class Constructors

The ThreadPermission Class contains the following constructor:

ThreadPermission()

Creates a new ThreadPermission instance that does not allow any threading operations.

Syntax

public ThreadPermission();


Methods (ThreadPermission Class)

 Microsoft SDK for Java

ThreadPermission Class Methods

The ThreadPermission Class contains the following methods:

adjustPermission adjusts the ThreadPermission object with some run-time state.
check determines whether the specified threading object can be manipulated.
combine creates and returns a new ThreadPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the ThreadPermission instance with a specified permission object.
copy retrieves a copy of the ThreadPermission instance.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object and sends the encoded data to the specified stream.
getAllowedThreadGroup retrieves the ThreadGroup object that defines the domain in which classes that possess this permission are allowed to perform threading operations.
isThreadAccessUnrestricted determines whether this permission grants unlimited access to Thread objects.
isThreadGroupAccessUnrestricted determines whether this permission grants unlimited access to ThreadGroup objects.
mapFormat retrieves a permission-specific tag, given an encoding format.
reset resets the permission object to empty, which is a state in which the permission allows no threading operations.
setAllowedThreadGroup sets a ThreadGroup that defines the domain in which the permission object allows manipulation of Thread or ThreadGroup objects.
setUnrestrictedThreadAccess sets the ability to manipulate any Thread object in the system.
setUnrestrictedThreadGroupAccess sets the ability to manipulate any ThreadGroup object in the system.
supportedFormats retrieves the encoding formats that the permission type supports.
toString retrieves a textual representation of the permission object.


adjustPermission (ThreadPermission Class)

 Microsoft SDK for Java

adjustPermission

This method of the ThreadPermission Class adjusts the ThreadPermission object with some run-time state.

Syntax

public void adjustPermission(String tag, Object adjustment);

Parameters

tag | The adjustment type. Any value other than "threadgroup" is ignored.
adjustment | This parameter must be an instance of java.lang.ThreadGroup. It indicates a portion of the thread group space.

Remarks

The ThreadPermission object only responds to the "threadgroup" adjustment type, and it expects the adjustment parameter to be a ThreadGroup object (in that case). All other adjustment types are ignored.

Usually, a ThreadPermission object allows unrestricted thread and thread group access within a specific ThreadGroup. However, this method can be called to allow a loader to grant some loaded code (an applet, for example) a portion of the thread group space in which it can perform threading operations.

Note The "threadgroup" adjustment to a ThreadPermission object is equivalent to explicitly calling the setAllowedThreadGroup method.


check (ThreadPermission Class)

 Microsoft SDK for Java

check

This method of the ThreadPermission Class determines whether the specified threading object can be manipulated.

Syntax

public void check(Object param)throws SecurityException;

Parameters

param The security request parameter. It must be an instance of Thread or ThreadGroup.

Remarks

If the specified Object is a Thread, the check takes place as follows:

  1. If the permission allows unrestricted thread access, the check succeeds.

  2. If the Thread exists within the ThreadGroup object associated with this permission or within one of its children, the check succeeds. Otherwise, it fails.

If the specified Object is a ThreadGroup, the check takes place as follows:

  1. If the permission allows unrestricted thread group access, the check succeeds.

  2. If the ThreadGroup is the ThreadGroup object associated with this permission or one of its children, the check succeeds. Otherwise, it fails.

Exceptions

SecurityException if the permission does not allow access to the specified threading object.


combine (ThreadPermission Class)

 Microsoft SDK for Java

combine

This method of the ThreadPermission Class creates and returns a new ThreadPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission source2);

Return Value

Returns the ThreadPermission object that results from combining.

Parameters

source2 The other ThreadPermission object to combine with.

Exceptions

IllegalArgumentException if the specified object to combine with is not an instance of ThreadPermission.


compareSet (ThreadPermission Class)

 Microsoft SDK for Java

compareSet

This method of the ThreadPermission Class compares the ThreadPermission instance with a specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the ThreadPermission instance is compared with.


copy (ThreadPermission Class)

 Microsoft SDK for Java

copy

This method of the ThreadPermission Class retrieves a copy of the ThreadPermission instance.

Syntax

public IPermission copy();

Return Value

Returns the copy of the ThreadPermission instance.


decode (ThreadPermission Class)

 Microsoft SDK for Java

decode

This method of the ThreadPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (ThreadPermission Class)

 Microsoft SDK for Java

encode

This method of the ThreadPermission Class encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


getAllowedThreadGroup (ThreadPermission Class)

 Microsoft SDK for Java

getAllowedThreadGroup

This method of the ThreadPermission Class retrieves the ThreadGroup object that defines the domain in which classes that possess this permission are allowed to perform threading operations.

Syntax

public ThreadGroup getAllowedThreadGroup();

Return Value

Returns the thread group that can be manipulated.


isThreadAccessUnrestricted (ThreadPermission Class)

 Microsoft SDK for Java

isThreadAccessUnrestricted

This method of the ThreadPermission Class determines whether this permission grants unlimited access to Thread objects.

Syntax

public boolean isThreadAccessUnrestricted();

Return Value

Returns true if access to Thread objects is unrestricted; otherwise, returns false.


isThreadGroupAccessUnrestricted (ThreadPermission Class)

 Microsoft SDK for Java

isThreadGroupAccessUnrestricted

This method of the ThreadPermission Class determines whether this permission grants unlimited access to ThreadGroup objects.

Syntax

public boolean isThreadGroupAccessUnrestricted();

Return Value

Returns true if access to ThreadGroup objects is unrestricted; otherwise, returns false.


mapFormat (ThreadPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the ThreadPermission Class retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


reset (ThreadPermission Class)

 Microsoft SDK for Java

reset

This method of the ThreadPermission Class resets the permission object to empty, which is a state in which the permission allows no threading operations.

Syntax

public void reset();


setAllowedThreadGroup (ThreadPermission Class)

 Microsoft SDK for Java

setAllowedThreadGroup

This method of the ThreadPermission Class sets a ThreadGroup that defines the domain in which the permission object allows manipulation of Thread or ThreadGroup objects.

Syntax

public void setAllowedThreadGroup(ThreadGroup tg);

Parameters

tg The thread group that can be manipulated.

Remarks

Classes that possess this permission can manipulate any threads within this ThreadGroup or within any child ThreadGroup of this ThreadGroup. The permission also allows the manipulation of the specified ThreadGroup or any of its children.


setUnrestrictedThreadAccess (ThreadPermission Class)

 Microsoft SDK for Java

setUnrestrictedThreadAccess

This method of the ThreadPermission Class sets the ability to manipulate any Thread object in the system.

Syntax

public void setUnrestrictedThreadAccess(boolean f);

Parameters

f The flag that indicates whether to turn unrestricted Thread access on or off. If the value is true, the ability to manipulate all Thread objects is turned on; otherwise, it is turned off.


setUnrestrictedThreadGroupAccess (ThreadPermission Class)

 Microsoft SDK for Java

setUnrestrictedThreadGroupAccess

This method of the ThreadPermission Class sets the ability to manipulate any ThreadGroup object in the system.

Syntax

public void setUnrestrictedThreadGroupAccess(boolean flag);

Parameters

flag The flag that indicates whether to turn unrestricted ThreadGroup access on or off. If the value is true, the ability to manipulate all ThreadGroup objects is turned on; otherwise, it is turned off.


supportedFormats (ThreadPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the ThreadPermission Class retrieves the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (ThreadPermission Class)

 Microsoft SDK for Java

toString

This method of the ThreadPermission Class retrieves a textual representation of the permission object.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


UIAccessRequest Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

UIAccessRequest Class

The UIAccessRequest Class of the com.ms.security.permissions package represents objects that indicate a request to use an extended aspect of the user interface APIs.

public class UIAccessRequest implements ISecurityRequest
{
  // Constructors
  public UIAccessRequest(int accessType);

  // Methods
  public PermissionID getPermissionID();
  public boolean isWarningBannerNeeded();
  public String toString();
}

UIAccessRequest objects are intended to be used as the security request objects for parameterized security checks involving the user interface permission. The UIPermission.check method expects a UIAccessRequest object as its parameter.

Example

The following example shows how to use a UIAccessRequest object to check permission to create a top-level window:

  ...
  // Create a UIAccessRequest object that indicates that you
  // want to create top-level windows.

  UIAccessRequest sreq = new UIAccessRequest(UIPermission.ALLOW_TOPLEVELWINDOW);

  // Check to see that all of your callers have the rights to
  // create top-level windows.

  PolicyEngine.checkPermission(sreq);
  ...

For more information about checking user interface permissions, see the PolicyEngine class and the UIPermission class.


Constructors (UIAccessRequest Class)

 Microsoft SDK for Java

UIAccessRequest Class Constructors

The UIAccessRequest Class contains the following constructor:

UIAccessRequest(int accessType)

Creates a UIAccessRequest object based on a specified access type.

Syntax

public UIAccessRequest(int accessType);

Return Value

Returns a request object that indicates a request to access the specified UI feature.

Parameters

AccessType The type of access that is being requested. The value must be one of the following constants from the UIPermission class:

ALLOW_CLIPBOARD
ALLOW_TOPLEVELWINDOW
ALLOW_FILEDIALOG
ALLOW_EVENTQUEUEACCESS


Methods (UIAccessRequest Class)

 Microsoft SDK for Java

UIAccessRequest Class Methods

The UIAccessRequest Class contains the following methods:

getPermissionID retrieves the permission identifier for the UIAccessRequest object.
isWarningBannerNeeded determines whether top-level windows need warning banners.
toString converts the UIAccessRequest object to its string representation.


getPermissionID (UIAccessRequest Class)

 Microsoft SDK for Java

getPermissionID

This method of the UIAccessRequest Class retrieves the permission identifier for the UIAccessRequest object. This method satisfies the ISecurityRequest interface and returns PermissionID.UI to indicate that instances of the UIAccessRequest class are associated with the user interface permission.

Syntax

public PermissionID getPermissionID();

Return Value

Returns PermissionID.UI.


isWarningBannerNeeded (UIAccessRequest Class)

 Microsoft SDK for Java

isWarningBannerNeeded

This method of the UIAccessRequest Class determines whether top-level windows need warning banners.

Syntax

public boolean isWarningBannerNeeded();

Return Value

Returns true if top-level windows need warning banners; otherwise, returns false.


toString (UIAccessRequest Class)

 Microsoft SDK for Java

toString

This method of the UIAccessRequest Class converts the UIAccessRequest object to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the UIAccessRequest object.


UIPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

UIPermission Class

The UIPermission Class of the com.ms.security.permissions package represents a permission that controls the ability to use some of the enhanced functionality of the AWT.

public class UIPermission implements IPermission,
            IEncodablePermission
{
  // Fields
  public static final int ALLOW_CLIPBOARD;
  public static final int ALLOW_EVENTQUEUEACCESS;
  public static final int ALLOW_FILEDIALOG;
  public static final int ALLOW_TOPLEVELWINDOW;

  // Constructors
  public UIPermission();

  // Methods
  public void check(Object param);
  public IPermission combine(IPermission source2);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public boolean getClipboardAccess();
  public boolean getEventQueueAccessAllowed();
  public boolean getFileDialogsAllowed();
  public boolean getTopLevelWindowCreationAllowed();
  public boolean getWarningBannersRequired();
  public String mapFormat(String format);
  public void reset();
  public void setClipboardAccess(boolean flag);
  public void setEventQueueAccessAllowed(boolean flag);
  public void setFileDialogsAllowed(boolean flag);
  public void setTopLevelWindowCreationAllowed(boolean flag);
  public void setWarningBanners(boolean flag);
  public String[] supportedFormats();
  public String toString();
}

Specifically, the UI (user interface) permission controls the ability to do the following:

  • Create top-level windows

  • Access the system clipboard

  • Create file dialog boxes

  • Access the AWT event queue

You can also use this permission to determine whether top-level windows require warning banners.

The StandardSecurityManager class checks for this permission type when performing the checkFileDialog, checkSystemClipboardAccess, checkAwtEventQueueAccess, and checkTopLevelWindow operations.

This class implements the IPermission and IEncodablePermission interfaces.

See Also

com.ms.security.permissions.UIAccessRequest


Constructors (UIPermission Class)

 Microsoft SDK for Java

UIPermission Class Constructors

The UIPermission Class contains the following constructor:

UIPermission()

Creates a new UIPermission instance. The new instance will not allow access to any of the extended AWT functionality. Specific features must be explicitly turned on to enable access.

Syntax

public UIPermission();


Methods (UIPermission Class)

 Microsoft SDK for Java

UIPermission Class Methods

The UIPermission Class contains the following methods:

check determines if the permission object allows the specified UI operation.
combine creates and returns a new UIPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the UIPermission instance with the specified permission object.
copy retrieves a copy of this UIPermission object.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object, and sends the encoded data to the specified stream.
getClipboardAccess determines whether the object indicates permission to access the Clipboard.
getEventQueueAccessAllowed determines whether the permission object indicates the ability to access the AWT event queue.
getFileDialogsAllowed determines whether the permission object indicates the ability to create file dialog boxes.
getTopLevelWindowCreationAllowed determines whether the permission object indicates permission to create top-level windows.
getWarningBannersRequired determines whether the permission object indicates that top-level windows require warning banners.
mapFormat retrieves a permission-specific tag, given an encoding format.
reset resets the permission object to a state in which it allows no access to any of the special UI behaviors.
setClipboardAccess sets the ability to access the system clipboard.
setEventQueueAccessAllowed sets the ability to access the AWT event queue.
setFileDialogsAllowed sets the ability to use file dialog boxes.
setTopLevelWindowCreationAllowed sets the ability to create a top-level window.
setWarningBanners sets the ability to display warning banners.
supportedFormats retrieves the encoding formats that the permission type supports.
toString converts the permission object to a textual representation.


check (UIPermission Class)

 Microsoft SDK for Java

check

This method of the UIPermission Class determines if the permission object allows the specified UI operation.

Syntax

public void check(Object param);

Parameters

param The security request parameter. It must be an instance of UIAccessRequest.

Exceptions

SecurityException if this permission does not allow the specified operation.


combine (UIPermission Class)

 Microsoft SDK for Java

combine

This method of the UIPermission Class creates and returns a new UIPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects it was constructed from.

Syntax

public IPermission combine(IPermission source2);

Return Value

Returns the resulting UIPermission object.

Parameters

source2 The UIPermission object to combine with.

Exceptions

IllegalArgumentException if the specified object to combine with is not an instance of UIPermission.


compareSet (UIPermission Class)

 Microsoft SDK for Java

compareSet

This method of the UIPermission Class compares the UIPermission instance with the specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the UIPermission instance is compared with. This parameter must be an instance of the UIPermission class.

Exceptions

IllegalArgumentException if the specified Object is not an instance of UIPermission.


copy (UIPermission Class)

 Microsoft SDK for Java

copy

This method of the UIPermission Class retrieves a copy of this UIPermission object.

Syntax

public IPermission copy();

Return Value

Returns the copy of the UIPermission object.


decode (UIPermission Class)

 Microsoft SDK for Java

decode

This method of the UIPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (UIPermission Class)

 Microsoft SDK for Java

encode

This method of the UIPermission Class encodes the contents of this permission object, and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


getClipboardAccess (UIPermission Class)

 Microsoft SDK for Java

getClipboardAccess

This method of the UIPermission Class determines whether the object indicates permission to access the Clipboard.

Syntax

public boolean getClipboardAccess();

Return Value

Returns true if the object indicates permission to access the Clipboard; otherwise, returns false.


getEventQueueAccessAllowed (UIPermission Class)

 Microsoft SDK for Java

getEventQueueAccessAllowed

This method of the UIPermission Class determines whether the permission object indicates the ability to access the AWT event queue.

Syntax

public boolean getEventQueueAccessAllowed();

Return Value

Returns true if the permission object indicates the ability to access the AWT event queue.


getFileDialogsAllowed (UIPermission Class)

 Microsoft SDK for Java

getFileDialogsAllowed

This method of the UIPermission Class determines whether the permission object indicates the ability to create file dialog boxes.

Syntax

public boolean getFileDialogsAllowed();

Return Value

Returns true if the permission object indicates the ability to create file dialog boxes; otherwise, returns false.


getTopLevelWindowCreationAllowed (UIPermission Class)

 Microsoft SDK for Java

getTopLevelWindowCreationAllowed

This method of the UIPermission Class determines whether the permission object indicates permission to create top-level windows.

Syntax

public boolean getTopLevelWindowCreationAllowed();

Return Value

Returns true if the permission object indicates permission to create top-level windows; otherwise, returns false.


getWarningBannersRequired (UIPermission Class)

 Microsoft SDK for Java

getWarningBannersRequired

This method of the UIPermission Class determines whether the permission object indicates that top-level windows require warning banners.

Syntax

public boolean getWarningBannersRequired();

Return Value

Returns true if the permission object indicates that top-level windows require warning banners; otherwise, returns false.


mapFormat (UIPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the UIPermission Class retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


reset (UIPermission Class)

 Microsoft SDK for Java

reset

This method of the UIPermission Class resets the permission object to a state in which it allows no access to any of the special UI behaviors.

Syntax

public void reset();


setClipboardAccess (UIPermission Class)

 Microsoft SDK for Java

setClipboardAccess

This method of the UIPermission Class sets the ability to access the system clipboard. If flag is set to true, the permission object will indicate that access to the Clipboard is allowed; otherwise, it will indicate that access to the Clipboard is not allowed.

Syntax

public void setClipboardAccess(boolean flag);

Parameters

flag The flag that indicates whether access to the Clipboard should be allowed.


setEventQueueAccessAllowed (UIPermission Class)

 Microsoft SDK for Java

setEventQueueAccessAllowed

This method of the UIPermission Class sets the ability to access the AWT event queue. If flag is set to true, the permission object will indicate that access to the AWT event queue is allowed; otherwise, it will indicate that access to the AWT event queue is not allowed.

Syntax

public void setEventQueueAccessAllowed(boolean flag);

Parameters

flag The flag that indicates whether access to the AWT event queue should be allowed.


setFileDialogsAllowed (UIPermission Class)

 Microsoft SDK for Java

setFileDialogsAllowed

This method of the UIPermission Class sets the ability to use file dialog boxes. If flag is set to true, the permission object will indicate that top-level windows require warning banners; otherwise, it will indicate that top-level windows do not require warning banners.

Syntax

public void setFileDialogsAllowed(boolean flag);

Parameters

flag The flag that indicates whether top-level windows should require warning banners.


setTopLevelWindowCreationAllowed (UIPermission Class)

 Microsoft SDK for Java

setTopLevelWindowCreationAllowed

This method of the UIPermission Class sets the ability to create a top-level window. If flag is set to true, the permission object will indicate that top-level window creation is allowed; otherwise, it will indicate that top level window creation is not allowed.

Syntax

public void setTopLevelWindowCreationAllowed(boolean flag);

Parameters

flag The flag that indicates whether top-level window creation should be allowed.


setWarningBanners (UIPermission Class)

 Microsoft SDK for Java

setWarningBanners

This method of the UIPermission Class sets the ability to display warning banners. If flag is set to true, the permission object will indicate that top-level windows require warning banners; otherwise, it will indicate that top-level windows do not require warning banners.

Syntax

public void setWarningBanners(boolean flag);

Parameters

flag The flag that indicates whether top-level windows should require warning banners.


supportedFormats (UIPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the UIPermission Class retrieves the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (UIPermission Class)

 Microsoft SDK for Java

toString

This method of the UIPermission Class converts the permission object to a textual representation.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


Fields (UIPermission Class)

 Microsoft SDK for Java

UIPermission Class Fields

The UIPermission Class contains the following fields:

ALLOW_CLIPBOARD | Flag that indicates a request for access to the Clipboard.
ALLOW_EVENTQUEUEACCESS | Flag that indicates a request for access to the AWT event queue.
ALLOW_FILEDIALOG | Flag that indicates a request for access to file dialog boxes.
ALLOW_TOPLEVELWINDOW | Flag that indicates a request for the ability to create top level windows.


UserFileIOAccess Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

UserFileIOAccess Class

The UserFileIOAccess Class of the com.ms.security.permissions package represents a request to perform a user-directed file I/O operation.

public class UserFileIOAccess implements ISecurityRequest
{
  // Fields
  public static final int READ;
  public static final int READWRITE;
  public static final int WRITE;

  // Constructors
  public UserFileIOAccess(int accessType);

  // Methods
  public int getAccessFlags();
  public PermissionID getPermissionID();
  public String toString();
  public static boolean validAccessType(int acc);
}

UserFileIOAccess instances are intended to be used as the security request objects for parameterized security checks involving the user-directed file I/O permission. The UserFileIOPermission.check method expects a UserFileIOAccess object as its parameter.

Example

The following example shows how to use a UserFileIOAccess object to check permission for user-directed file I/O operations:

  ...
  // Create a UserFileIOAccess object that indicates that you
  // want to ask the user to choose a file to open for reading.

  UserFileIOAccess sreq = new UserFileIOAccess(UserFileIOAccess.READ);

  // Check to see that all of your callers have the rights to
  // initiate user-directed file operations for reading.

  PolicyEngine.checkPermission(sreq);
  ...

For more information about checking file I/O permissions, see the PolicyEngine class and the UserFileIOPermission class.


Constructors (UserFileIOAccess Class)

 Microsoft SDK for Java

UserFileIOAccess Class Constructors

The UserFileIOAccess Class contains the following constructor:

UserFileIOAccess(int accessType)

Creates a new UserFileIOAccess object that represents the specified access types.

Syntax

public UserFileIOAccess(int accessType);

Parameters

accessType The requested access type. The value must be READ, WRITE, or READWRITE.


Methods (UserFileIOAccess Class)

 Microsoft SDK for Java

UserFileIOAccess Class Methods

The UserFileIOAccess Class contains the following methods:

getAccessFlags retrieves the access flags represented by the UserFileIOAccess object.
getPermissionID retrieves the permission identifier associated with the UserFileIOAccess object.
toString converts the UserFileIOAccess object to its string representation.
validAccessType determines whether the access flags in the specified integer are valid UserFileIOAccess flags.


getAccessFlags (UserFileIOAccess Class)

 Microsoft SDK for Java

getAccessFlags

This method of the UserFileIOAccess Class retrieves the access flags represented by the UserFileIOAccess object.

Syntax

public int getAccessFlags();

Return Value

Returns the access flags represented by the UserFileIOAccess object.


getPermissionID (UserFileIOAccess Class)

 Microsoft SDK for Java

getPermissionID

This method of the UserFileIOAccess Class retrieves the permission identifier associated with the UserFileIOAccess object. This method satisfies the ISecurityRequest interface and returns PermissionID.USERFILEIO to indicate that instances of the UserFileIOAccess class are associated with the user-directed file I/O permission.

Syntax

public PermissionID getPermissionID();

Return Value

Returns PermissionID.USERFILEIO.


toString (UserFileIOAccess Class)

 Microsoft SDK for Java

toString

This method of the UserFileIOAccess Class converts the UserFileIOAccess object to its string representation.

Syntax

public String toString();

Return Value

Returns the string representation of the UserFileIOAccess object.


validAccessType (UserFileIOAccess Class)

 Microsoft SDK for Java

validAccessType

This method of the UserFileIOAccess Class determines whether the access flags in the specified integer are valid UserFileIOAccess flags.

Syntax

public static boolean validAccessType(int acc);

Return Value

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

Parameters

acc The access type that is checked for validity.


Fields (UserFileIOAccess Class)

 Microsoft SDK for Java

UserFileIOAccess Class Fields

The UserFileIOAccess Class contains the following fields.

READ | The value indicating that a file needs to be opened for reading.
READWRITE | The value indicating that a file needs to be opened for both reading and writing.
WRITE | The value indicating that a file needs to be opened for writing.


UserFileIOPermission Class (com.ms.security.permissions Package)

 Microsoft SDK for Java

UserFileIOPermission Class

The UserFileIOPermission Class of the com.ms.security.permissions package represents a permission that controls the ability to perform user-directed file I/O operations using the UserFileDialog class.

public class UserFileIOPermission implements IPermission,
            IEncodablePermission
{
  // Constructors
  public UserFileIOPermission();
  public UserFileIOPermission(int accessType);

  // Methods
  public boolean canRead();
  public boolean canWrite();
  public void check(Object request) throws SecurityException;
  public IPermission combine(IPermission source2);
  public int compareSet(Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public int getAccessFlags();
  public String mapFormat(String format);
  public void setAccessFlags(int type);
  public String[] supportedFormats();
  public String toString();
}

See Also

com.ms.security.permissions.UserFileIOAccess


Constructors (UserFileIOPermission Class)

 Microsoft SDK for Java

UserFileIOPermission Class Constructors

The UserFileIOPermission Class contains the following constructors:

UserFileIOPermission()
UserFileIOPermission(int accessType)

UserFileIOPermission()

Creates a new UserFileIOPermission object that represents the specified access types.

Syntax

public UserFileIOPermission();

UserFileIOPermission(int accessType)

Creates a new UserFileIOPermission instance that allows the user to have access to specific types of file I/O.

Syntax

public UserFileIOPermission(int accessType);

Parameters

accessType The access flag. This value must be READ, WRITE, or READWRITE.


Methods (UserFileIOPermission Class)

 Microsoft SDK for Java

UserFileIOPermission Class Methods

The UserFileIOPermission Class contains the following methods:

canRead determines whether the object allows user-directed file I/O for reading files.
canWrite determines whether the object allows user-directed file I/O for writing files.
check determines whether the permission object allows the specified user-directed file I/O operation.
combine creates and returns a new UserFileIOPermission object that is a combination of the current permission object and the specified permission object.
compareSet compares the UserFileIOPermission instance with a specified permission object.
copy retrieves a copy of the UserFileIOPermission object.
decode decodes the contents of the specified data stream into this permission object.
encode encodes the contents of this permission object, and sends the encoded data to the specified stream.
getAccessFlags retrieves the access types allowed by the permission object.
mapFormat retrieves a permission-specific tag, given an encoding format.
setAccessFlags sets the types of user-directed file I/O access that the permission object should allow.
supportedFormats retrieves the encoding formats that the permission type supports.
toString retrieves a textual representation of the permission object.


canRead (UserFileIOPermission Class)

 Microsoft SDK for Java

canRead

This method of the UserFileIOPermission Class determines whether the object allows user-directed file I/O for reading files.

Syntax

public boolean canRead();

Return Value

Returns true if the object has permission to read; otherwise, returns false.


canWrite (UserFileIOPermission Class)

 Microsoft SDK for Java

canWrite

This method of the UserFileIOPermission Class determines whether the object allows user-directed file I/O for writing files.

Syntax

public boolean canWrite();

Return Value

Returns true if the object has permission to write; otherwise, returns false.


check (UserFileIOPermission Class)

 Microsoft SDK for Java

check

This method of the UserFileIOPermission Class determines whether the permission object allows the specified user-directed file I/O operation.

Syntax

public void check(Object request) throws SecurityException;

Parameters

request The security request parameter. It must be an instance of the UserFileIOAccess class.

Exceptions

SecurityException if this permission does not allow the specified operation.


combine (UserFileIOPermission Class)

 Microsoft SDK for Java

combine

This method of the UserFileIOPermission Class creates and returns a new UserFileIOPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Syntax

public IPermission combine(IPermission source2);

Return Value

Returns the resulting UserFileIOPermission object.

Parameters

source2 The UserFileIOPermission object to combine with the current one.

Exceptions

IllegalArgumentException if the specified object to combine with is not an instance of UserFileIOPermission.


compareSet (UserFileIOPermission Class)

 Microsoft SDK for Java

compareSet

This method of the UserFileIOPermission Class compares the UserFileIOPermission instance with a specified permission object.

Syntax

public int compareSet(Object target);

Return Value

Returns one of the following constants:

DISJOINT
EMPTY
OVERLAP
EQUAL
SUBSET
SUPERSET
EMPTY_SUBSET
EMPTY_SUPERSET

Parameters

target The permission object that the UserFileIOPermission instance is compared with.


copy (UserFileIOPermission Class)

 Microsoft SDK for Java

copy

This method of the UserFileIOPermission Class retrieves a copy of the UserFileIOPermission object.

Syntax

public IPermission copy();

Return Value

Returns the copy of the UserFileIOPermission object.


decode (UserFileIOPermission Class)

 Microsoft SDK for Java

decode

This method of the UserFileIOPermission Class decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Syntax

public boolean decode(String tag, InputStream data);

Return Value

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
data | The raw data to construct the object from. The type of data is specified by the tag parameter.


encode (UserFileIOPermission Class)

 Microsoft SDK for Java

encode

This method of the UserFileIOPermission Class encodes the contents of this permission object, and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Syntax

public boolean encode(String tag, OutputStream out);

Return Value

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameters

tag | The encoding type identifier.
out | The output stream to send the encoded data to.


getAccessFlags (UserFileIOPermission Class)

 Microsoft SDK for Java

getAccessFlags

This method of the UserFileIOPermission Class retrieves the access types allowed by the permission object.

Syntax

public int getAccessFlags();

Return Value

Returns the access flag represented by the permission object, which will be READ, WRITE, or READWRITE.


mapFormat (UserFileIOPermission Class)

 Microsoft SDK for Java

mapFormat

This method of the UserFileIOPermission Class retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Syntax

public String mapFormat(String format);

Return Value

Returns the permission-specific tag that corresponds to the specified format.

Parameters

format The encoding format to retrieve the tag for.


setAccessFlags (UserFileIOPermission Class)

 Microsoft SDK for Java

setAccessFlags

This method of the UserFileIOPermission Class sets the types of user-directed file I/O access that the permission object should allow.

Syntax

public void setAccessFlags(int type);

Parameters

type The access flag. This value must be READ, WRITE, or READWRITE.


supportedFormats (UserFileIOPermission Class)

 Microsoft SDK for Java

supportedFormats

This method of the UserFileIOPermission Class retrieves the encoding formats that the permission type supports.

Syntax

public String[] supportedFormats();

Return Value

Returns an array of the supported format identifiers.


toString (UserFileIOPermission Class)

 Microsoft SDK for Java

toString

This method of the UserFileIOPermission Class retrieves a textual representation of the permission object.

Syntax

public String toString();

Return Value

Returns the string representation of the permission object.


com.ms.service Package Overview

Microsoft Packages Overview

The com.ms.service package enables you to write a Microsoft® Windows NT® system service in Java. (System services do not work under Microsoft® Windows® 98.) For more information about Windows NT system services, refer to the MSDN™ Library.

This package contains the following:

Classes

Hierarchy

To create and use a Windows NT service using this package, you must perform the following steps:

  1. Create your own service class by deriving it from the Service class.

  2. Implement either a default constructor with no parameters or a constructor with a single String[] parameter. This constructor will be used to instantiate the service, and it should perform initialization during ServiceMain.

  3. Implement your own versions of service callback methods (the methods that start with handle) to handle the various system service requests.

  4. Use the query methods (the methods that begin with can) to determine which controls are accepted by a service (instead of testing the flags returned from getControlsAccepted).

  5. Use a built-in assassin to terminate a service that exceeds a time-out period specified by the wait hint value in status updates.

  6. Use the jntsvc tool to generate a self-contained, self-installing and uninstalling, redistributable executable for the service.

  7. After generating the executable, install and run the service.

For instructions on generating a service executable using the jntsvc tool, and on installing, uninstalling, and running the executable, see the jntsvc section of the Tools Reference.


Classes (com.ms.service Package)

 Microsoft SDK for Java

com.ms.service Package Classes

The com.ms.service package contains the following classes:

Service Class is a base class for creating Microsoft® Windows NT® system services in Java. (System services do not work under Microsoft® Windows® 98.)

ServiceStatus Class contains information about the state of a service.


Hierarchy (com.ms.service Package)

 Microsoft SDK for Java

com.ms.service Package Hierarchy

The com.ms.service package has the following hierarchy:

Object
  |
  +--Service
  |
  +--ServiceStatus (Cloneable)


Service Class (com.ms.service Package)

 Microsoft SDK for Java

Service Class

The Service Class of the com.ms.service package is a base class for creating Microsoft® Windows NT® system services in Java.

public abstract class Service
{
  // Fields
  public static final int ACCEPT_PAUSE_CONTINUE;
  public static final int ACCEPT_SHUTDOWN;
  public static final int ACCEPT_STOP;
  public static final int CONTINUE_PENDING;
  protected static boolean disableassassin;
  public PrintStream err;
  protected static final int ERROR_SERVICE_SPECIFIC_ERROR;
  protected static final int NO_ERROR;
  public PrintStream out;
  public static final int PAUSE_PENDING;
  public static final int PAUSED;
  public static final int RUNNING;
  public static final int START_PENDING;
  public static final int STOP_PENDING;
  public static final int STOPPED;

  // Constructors
  protected Service();

  // Methods
  public synchronized boolean canPause();
  public synchronized boolean canShutdown();
  public synchronized boolean canStop();
  protected synchronized void CheckPoint();
  protected synchronized void CheckPoint(int waithint);
  protected static void disableAllAssassins();
  protected void disableAssassin();
  protected static void enableAllAssassins();
  protected void enableAssassin();
  protected void getAssassinTimeout(long ms);
  public synchronized int getCheckPoint();
  public synchronized int getControlsAccepted();
  public synchronized int getCurrentState();
  public synchronized final ServiceStatus getServiceStatus();
  public final ServiceStatus getServiceStatusDirect();
  public synchronized int getWaitHint();
  protected boolean handleContinue();
  protected boolean handleInterrogate();
  protected boolean handlePause();
  protected boolean handleShutdown();
  protected boolean handleStop();
  protected boolean handleUnrecognizedEvent(int event);
  protected boolean isAssassinActive();
  protected static void preventAssassins();
  protected void setAssassinTimeout( long ms );
  public static boolean setAutoDumpErr( boolean autodump );
  public static boolean setAutoDumpOut( boolean autodump );
  protected synchronized void setContinuing( int waithint );
  protected synchronized void setPaused( );
  protected synchronized void setPausing( int waithint );
  protected synchronized void setRunning( int controls );
  protected synchronized void setRunning( );
  public boolean setServiceAutoDumpErr(boolean autodump);
  public boolean setServiceAutoDumpOut(boolean autodump);
  protected synchronized final boolean setServiceStatus(
        ServiceStatus newstatus);
  protected final boolean setServiceStatusDirect(
        ServiceStatus newstatus);
  protected synchronized void setStopped();
  protected synchronized void setStopping(int waithint);
  protected void StopServiceEventHandler(int waithint);
}

CAUTION By default, the service assassin is turned on for services. It must be turned off by using the disableAssassin method. For more information, see the enableAssassin method.


Constructors (Service Class)

 Microsoft SDK for Java

Service Class Constructors

The Service Class contains the following constructor:

Service()

Constructs a new service.

Syntax

protected Service();

CAUTION The service being created must send a status update within 30 seconds or disable the assassin; otherwise, the assassin will kill the service.


Methods (Service Class)

 Microsoft SDK for Java

Service Class Methods

The Service Class contains the following methods:

canPause indicates whether the service can be paused.
canShutdown indicates whether the service should be notified when the system shuts down.
canStop indicates whether the service can be stopped.
CheckPoint increments the current checkpoint value.
disableAllAssassins disables the assassins for each service in the process.
disableAssassin disables the service assassin.
enableAllAssassins restores the assassins for each service in the process to their normal state.
enableAssassin enables the assassin.
getAssassinTimeout obtains the default time for which the assassin will wait for any state change before terminating a service.
getCheckPoint determines the service checkpoint.
getControlsAccepted indicates the control codes that the service will accept and process.
getCurrentState determines the service state.
getServiceStatus determines the service status.
getServiceStatusDirect determines the service status.
getWaitHint specifies the number of milliseconds the service is likely to remain in the current pending state.
handleContinue handles the continue request.
handleInterrogate handles the interrogate request.
handlePause handles the pause request.
handleShutdown handles the shutdown request.
handleStop handles the stop request.
handleUnrecognizedEvent handles an unrecognized event code from the service control manager.
isAssassinActive indicates whether the assassin is currently active.
preventAssassins prevents assassins from being created.
setAssassinTimeout sets the time for which the assassin will wait for any state change before terminating a service.
setAutoDumpErr determines whether each line written to system.err is automatically written to the event log or whether the service will manually flush the stream to log events.
setAutoDumpOut determines whether each line written to system.out is automatically written to the event log or whether the service will manually flush the stream to log events.
setContinuing sets the service to CONTINUE_PENDING.
setPaused sets the service to the PAUSED state.
setPausing sets the service to PAUSE_PENDING and sets the wait hint to waithint.
setRunning sets the service to RUNNING and sets the ControlsAccepted field in the ServiceStatus object to a specified value indicating the control capabilities of the service.
setServiceAutoDumpErr determines whether each line written to err is automatically written to the event log or whether the service will manually flush the stream to log events.
setServiceAutoDumpOut determines whether each line written to out is automatically written to the event log or whether the service will manually flush the stream to log events.
setServiceStatus changes the value of the service, based on a ServiceStatus object.
setServiceStatusDirect changes the value of the service, based on a ServiceStatus object.
setStopped sets the service to STOPPED.
setStopping sets the service to STOP_PENDING and the wait hint to waithint.
StopServiceEventHandler internally stops the service.


canPause (Service Class)

 Microsoft SDK for Java

canPause

This method of the Service Class indicates whether the service can be paused.

Syntax

public synchronized boolean canPause();

Return Value

Returns true if the service can be paused (that is, if getControlsAccepted returns ACCEPT_PAUSE_CONTINUE); otherwise, returns false.


canShutdown (Service Class)

 Microsoft SDK for Java

canShutdown

This method of the Service Class indicates whether indicates whether the service should be notified when the system shuts down.

Syntax

public synchronized boolean canShutdown();

Return Value

Returns true if the service can accept shutdown requests (that is, if getControlsAccepted returns ACCEPT_SHUTDOWN); otherwise, returns false.


canStop (Service Class)

 Microsoft SDK for Java

canStop

This method of the Service Class indicates whether the service can be stopped.

Syntax

public synchronized boolean canStop();

Return Value

Returns true if the service can be stopped (that is, if getControlsAccepted returns ACCEPT_STOP); otherwise, returns false.


CheckPoint (Service Class)

 Microsoft SDK for Java

CheckPoint

The CheckPoint method of the Service Class contains the following signatures:

CheckPoint()
CheckPoint(int waithint)

CheckPoint()

Increments the current checkpoint value.

Syntax

protected synchronized void CheckPoint();

Remarks

During a pending operation, the service should call the CheckPoint method to indicate that the service has progressed toward changing the state from pending to start, stop, continue, or pause.

CheckPoint(int waithint)

Sets the checkpoint to a specified value.

Syntax

protected synchronized void CheckPoint(int waithint);

Parameters

waithint The estimated number of milliseconds until the next state.


disableAllAssassins (Service Class)

 Microsoft SDK for Java

disableAllAssassins

This method of the Service Class indicates whether disables the assassins for each service in the process.

Syntax

protected static void disableAllAssassins();


disableAssassin (Service Class)

 Microsoft SDK for Java

disableAssassin

This method of the Service Class disables the service assassin. If the assassin is disabled, the service must always be able to respond to stop and shutdown requests, because a service cannot be shut down through the task manager.

Syntax

protected void disableAssassin();

If it is unknown whether the service will always be able to do so, it is best advised to leave the assassin enabled. If the assassin is killing the service too soon, use the setAssassinTimeout to set its default timeout.

See Also

enableAssassin, isAssassinActive


enableAllAssassins (Service Class)

 Microsoft SDK for Java

enableAllAssassins

This method of the Service Class restores the assassins for each service in the process to their normal state. This method globally re-enables assassins, regardless of their individual settings.

Syntax

protected static void enableAllAssassins();


enableAssassin (Service Class)

 Microsoft SDK for Java

enableAssassin

This method of the Service Class enables the assassin.

Syntax

protected void enableAssassin();

The assassin will observe the state of the service and will terminate it in the following cases:

  • A control request is received and the service does not respond within the default time-out.

  • A call to setServiceStatus changes the state of the service to a state unrelated to a previous state change request. This means that if a stop request is received and the service proceeds to set the state to RUNNING, the service is terminated. However, if the service sets its state to STOPPED or STOP_PENDING, the service will terminate in the first case, or it will re-start its time-out in the second case.

  • A setServiceStatus call changes the state of the service to any PENDING state and the service does not make a setServiceStatus call to the corresponding state within the WaitHint (or if WaitHint is not specified), within the assassin's default time-out.

See Also

disableAssassin, isAssassinActive, setAssassinTimeout, STOPPED, START_PENDING, STOP_PENDING, RUNNING, CONTINUE_PENDING, PAUSE_PENDING, PAUSED


getAssassinTimeout (Service Class)

 Microsoft SDK for Java

getAssassinTimeout

This method of the Service Class obtains the default time for which the assassin will wait for any state change before terminating a service. The time-out initially defaults to 30 seconds.

Syntax

protected void getAssassinTimeout(long ms);

Return Value

Returns the time, in milliseconds, that the assassin will wait for a state change before terminating the service.


getCheckPoint (Service Class)

 Microsoft SDK for Java

getCheckPoint

This method of the Service Class determines the service checkpoint.

Syntax

public synchronized int getCheckPoint();

Return Value

Returns the current checkpoint value.


getControlsAccepted (Service Class)

 Microsoft SDK for Java

getControlsAccepted

This method of the Service Class indicates the control codes that the service will accept and process.

Syntax

public synchronized int getControlsAccepted();

Return Value

Returns flags that indicate which controls the service will accept.


getCurrentState (Service Class)

 Microsoft SDK for Java

getCurrentState

This method of the Service Class determines the service state.

Syntax

public synchronized int getCurrentState();

Return Value

Returns the system's current state.


getServiceStatus (Service Class)

 Microsoft SDK for Java

getServiceStatus

This method of the Service Class determines the service status.

Syntax

public synchronized final ServiceStatus getServiceStatus();

Return Value

Returns a copy of the service status, which is a ServiceStatus object.


getServiceStatusDirect (Service Class)

 Microsoft SDK for Java

getServiceStatusDirect

This method of the Service Class determines the service status. This operation is not synchronized with other status-changing operations.

Syntax

public final ServiceStatus getServiceStatusDirect();

Return Value

Returns a copy of the service status, which is a ServiceStatus object.


getWaitHint (Service Class)

 Microsoft SDK for Java

getWaitHint

This method of the Service Class determines the wait hint.

Syntax

public synchronized int getWaitHint();

Return Value

Returns the service wait hint.

Remarks

The wait hint value specifies the number of milliseconds the service is likely to remain in the current pending state. If the service exceeds this value, the service will be terminated if the assassin is enabled.


handleContinue (Service Class)

 Microsoft SDK for Java

handleContinue

This method of the Service Class handles the continue request.

Syntax

protected boolean handleContinue();

Return Value

Returns false.

Remarks

Override this method in your derived service class if you want your service to handle continue events.


handleInterrogate (Service Class)

 Microsoft SDK for Java

handleInterrogate

This method of the Service Class handles the interrogate request.

Syntax

protected boolean handleInterrogate();

Return Value

Returns false.

Remarks

Override this method in your derived service class if you want your service to handle interrogate events.


handlePause (Service Class)

 Microsoft SDK for Java

handlePause

This method of the Service Class handles the pause request.

Syntax

protected boolean handlePause();

Return Value

Returns false.

Remarks

Override this method in your derived service class if you want your service to handle pause events.


handleShutdown (Service Class)

 Microsoft SDK for Java

handleShutdown

This method of the Service Class handles the shutdown request.

Syntax

protected boolean handleShutdown();

Return Value

Returns false.

Remarks

Override this method in your derived service class if you want your service to handle shutdown events. By default, this method makes a call to handleStop.


handleStop (Service Class)

 Microsoft SDK for Java

handleStop

This method of the Service Class handles the stop request.

Syntax

protected boolean handleStop();

Return Value

Returns false.

Remarks

Override this method in your derived service class if you want your service to handle stop events. By default, if stop control requests are accepted, it will call the setStopped method and return false.


handleUnrecognizedEvent (Service Class)

 Microsoft SDK for Java

handleUnrecognizedEvent

This method of the Service Class handles an unrecognized event code from the service control manager. Future versions of Windows NT might define additional events; this method provides a way for services to respond to these events.

Syntax

protected boolean handleUnrecognizedEvent(int event);

Return Value

Returns false.


isAssassinActive (Service Class)

 Microsoft SDK for Java

isAssassinActive

This method of the Service Class indicates whether the assassin is currently active.

Syntax

protected boolean isAssassinActive();

Return Value

Returns true if the assassin is active; otherwise, returns false.

See Also

enableAssassin, disableAssassin


preventAssassins (Service Class)

 Microsoft SDK for Java

preventAssassins

This method of the Service Class prevents assassins from being created. For this method to be effective, each service should call this method from its static initializer.

Syntax

protected static void preventAssassins();


setAssassinTimeout (Service Class)

 Microsoft SDK for Java

setAssassinTimeout

This method of the Service Class sets the time for which the assassin will wait for any state change before terminating a service.

Syntax

protected void setAssassinTimeout(long ms);

Parameters

ms The time, in milliseconds, for the assassin to wait for a state change before terminating the service.


setAutoDumpErr (Service Class)

 Microsoft SDK for Java

setAutoDumpErr

This method of the Service Class determines whether each line written to system.err is automatically written to the event log or whether the service will manually flush the stream to log events.

Syntax

public static boolean setAutoDumpErr(boolean autodump);

Note As of SDK for Java version 2.02, this method changes the state of System.err if it has not been changed since the first service was instantiated. The status of err, the output stream for each service, can be changed with setServiceAutoDumpErr.

Return Value

Returns the previous auto-flush state.

Parameters

autodump Set to true to automatically flush to the Windows NT event log whenever a new line is written. Set to false to enable writing to the error log. In this case, the stream can be manually flushed by calling System.err.flush, which will write any text printed to the stream since the last flush to the event log as a single event.


setAutoDumpOut (Service Class)

 Microsoft SDK for Java

setAutoDumpOut

This method of the Service Class determines whether each line written to system.out is automatically written to the event log or whether the service will manually flush the stream to log events.

Syntax

public static boolean setAutoDumpOut(boolean autodump);

Note As of SDK for Java version 2.02, this method changes the state of System.out if it has not been changed since the first service was instantiated. The status of out, the output stream for each service, can be changed by using setServiceAutoDumpOut.

Return Value

Returns the previous auto-flush state.

Parameters

autodump Set to true to automatically flush to the Windows NT event log whenever a new line is written. Set to false to enable the writing of multiline error messages to the information log. In this case, the stream can be manually flushed by calling System.out.flush, which will write any text printed to the stream since the last flush to the event log as a single event.


setContinuing (Service Class)

 Microsoft SDK for Java

setContinuing

This method of the Service Class sets the service to CONTINUE_PENDING.

Syntax

protected synchronized void setContinuing(int waithint);

Parameters

waithint The estimated number of milliseconds it takes for the service to reach the RUNNING state.


setPaused (Service Class)

 Microsoft SDK for Java

setPaused

This method of the Service Class sets the service to the PAUSED state.

Syntax

protected synchronized void setPaused();


setPausing (Service Class)

 Microsoft SDK for Java

setPausing

This method of the Service Class sets the service to PAUSE_PENDING and sets the wait hint to waithint.

Syntax

protected synchronized void setPausing(int waithint);

Parameters

waithint The estimated number of milliseconds it takes for the service to reach the PAUSED state.


setRunning (Service Class)

 Microsoft SDK for Java

setRunning

The setRunning method of the Service Class contains the following signatures:

setRunning(int controls)
setRunning()

setRunning(int controls)

Sets the service to RUNNING and sets the ControlsAccepted field in the ServiceStatus object to a specified value indicating the control capabilities of the service.

Syntax

protected synchronized void setRunning(int controls);

Parameters

controls The control capabilities that ControlsAccepted is set to.

See Also

com.ms.service.ServiceStatus.ControlsAccepted

setRunning()

Sets the service to RUNNING.

Syntax

protected synchronized void setRunning();


setServiceAutoDumpErr (Service Class)

 Microsoft SDK for Java

setServiceAutoDumpErr

This method of the Service Class determines whether each line written to err is automatically written to the event log or whether the service will manually flush the stream to log events.

Syntax

public boolean setServiceAutoDumpErr(boolean autodump);

Return Value

Returns the previous auto-flush state.

Parameters

autodump Set to true to automatically flush to the Windows NT event log whenever a new line is written. Set to false to enable the writing of multiline error messages. In this case, the stream can be manually flushed by calling err.flush, which will write any text printed to the stream since the last flush to the event log as a single event.


setServiceAutoDumpOut (Service Class)

 Microsoft SDK for Java

setServiceAutoDumpOut

This method of the Service Class determines whether each line written to out is automatically written to the event log or whether the service will manually flush the stream to log events.

Syntax

public boolean setServiceAutoDumpOut(boolean autodump);

Return Value

Returns the previous auto-flush state.

Parameters

autodump Set to true to automatically flush to the Windows NT event log whenever a new line is written. Set to false to enable the writing of multiline error messages. In this case, the stream can be manually flushed by calling out.flush, which will write any text printed to the stream since the last flush to the event log as a single event.


setServiceStatus (Service Class)

 Microsoft SDK for Java

setServiceStatus

This method of the Service Class changes the value of the service, based on a ServiceStatus object.

Syntax

protected synchronized final boolean setServiceStatus(ServiceStatus newstatus);

Return Value

Returns true if the status was updated; returns false if the newstatus parameter is not correct or the status could not be updated.

Parameters

newstatus The value that the service status is set to. The state in newstatus is copied to the current status.


setServiceStatusDirect (Service Class)

 Microsoft SDK for Java

setServiceStatusDirect

This method of the Service Class changes the value of the service, based on a ServiceStatus object. This method should be externally synchronized with other status-changing operations, if necessary.

Syntax

protected final boolean setServiceStatusDirect(ServiceStatus newstatus);

CAUTION This method is not synchronized with the other status get/set methods. This method provides the service with a direct way to internally update the assassin. It allows the assassin to identify deadlock conditions on internally-initiated state changes. External state changes through Service Control Manager events will always update the assassin. Use getServiceStatusDirect to obtain the status without synchronizing.

Return Value

Returns true if the status was updated; returns false if the newstatus parameter is not correct or the status could not be updated.

Parameters

newstatus The value that the service status is set to. The state in newstatus is copied to the current status.


setStopped (Service Class)

 Microsoft SDK for Java

setStopped

This method of the Service Class sets the service to STOPPED.

Syntax

protected synchronized void setStopped();


setStopping (Service Class)

 Microsoft SDK for Java

setStopping

This method of the Service Class sets the sets the service to STOP_PENDING and the wait hint to waithint.

Syntax

protected synchronized void setStopping(int waithint);

Parameters

waithint The estimated number of milliseconds it takes for the service to reach the STOPPED state.


StopServiceEventHandler (Service Class)

 Microsoft SDK for Java

StopServiceEventHandler

This method of the Service Class internally stops the service. Sets the service to STOPPED. No more control commands will be dispatched after this method is called.

Syntax

protected void StopServiceEventHandler(int waithint);

Note This method is provided only for backward compatibility with services developed using the Microsoft SDK for Java version 1.5.1. The preferred way to indicate a stopped service is by using setStopped. Version 1.5.1 reported a STOP_PENDING status and activated the assassin with the given waithint; a STOPPED status would automatically be reported when all non-daemon threads terminated. Because multiple services are supported, this version simply reports a STOPPED status and does not activate the assassin.

Parameters

waithint This parameter is not used.


Fields (Service Class)

 Microsoft SDK for Java

Service Class Fields

The Service Class contains the following fields.

ACCEPT_PAUSE_CONTINUE | Indicates that the service accepts pause and continue requests.
ACCEPT_SHUTDOWN | Indicates that the service accepts shutdown requests.
ACCEPT_STOP | Indicates that the service accepts stop requests.
CONTINUE_PENDING | Indicates that the service is changing its state from pause to run.
disableassassin When true, prevents the assassin from being activated. The assassin ensures that the service actually stops when instructed to do so. This deactivates the assassins for each service in the process.

Note As of SDK for Java version 2.02, each service has its own assassin, which can be disabled by calling disableAssassin. All assassins can be globally disabled by calling disableAllAssassins.
err An error output stream for the service. Data written to the stream is automatically redirected to the event log as error events using the event source specified to jntsvc. Each line printed to the stream results in a new event. Multiple lines can be written by synchronizing on this object and using setServiceAutoDumpErr to temporarily turn off auto-logging, as shown in the following example:

Example

synchronized (err)
{
boolean oldautodump =
setServiceAutoDumpErr(false);
err.println("Line 1");
err.println("Line 2");
setServiceAutoDumpErr(oldautodump);
err.flush();
}
ERROR_SERVICE_SPECIFIC_ERROR | Service-specific error reported. This is set in ServiceStatus.Win32ExitCode to indicate that an error has occurred.
NO_ERROR | No error reported. This is set in ServiceStatus.Win32ExitCode to indicate that the service terminated correctly.
out A standard output stream for the service. Data written to the stream is automatically redirected to the event log using the event source specified to the jntsvc tool. Each line printed to the stream results in a new event. Multiple lines can be written by synchronizing on this object and using setServiceAutoDumpOut to temporarily turn off auto-logging, as shown in the following example:

Example

     synchronized (out)
     {
       boolean oldautodump = setServiceAutoDumpOut(false);
       out.println("Line 1");
       out.println("Line 2");
       setServiceAutoDumpOut(oldautodump);
       out.flush();
     }
PAUSE_PENDING | Indicates that the service is changing its state from run to pause.
PAUSED | Indicates that the service is paused.
RUNNING | Indicates that the service is running.
START_PENDING | Indicates that the service is starting.
STOP_PENDING | Indicates that the service is stopping.
STOPPED | Indicates that the service has stopped.


ServiceStatus Class (com.ms.service Package)

 Microsoft SDK for Java

ServiceStatus Class

The ServiceStatus Class of the com.ms.service package contains information about the state of a service. For more information about this class, see the Microsoft® Win32® SERVICE_STATUS documentation.

public final class ServiceStatus implements Cloneable
{
  // Fields
  public int CheckPoint;
  public int ControlsAccepted;
  public int CurrentState;
  public int ServiceSpecificExitCode;
  public int WaitHint;
  public int Win32ExitCode;
}


Fields (ServiceStatus Class)

 Microsoft SDK for Java

ServiceStatus Class Fields

The ServiceStatus Class contains the following fields.

CheckPoint | A value that the service increments periodically to report its progress during a lengthy start, stop, or continue operation. For example, the service should increment this value as it completes each step of its initialization when it is starting up. The user interface program that invoked the operation on the service uses this value to track the progress of the service during a lengthy operation. This value is not valid and should be zero when the service does not have a start, stop, or continue operation pending.
ControlsAccepted | The control codes that the service will accept and process. This can be a combination of ACCEPT_STOP, ACCEPT_PAUSE_CONTINUE, or ACCEPT_SHUTDOWN.
CurrentState | The current state of the service. This can be one of the following values:
 | Value | Meaning
 | STOPPED | The service is not running.
 | START_PENDING | The service is starting.
 | STOP_PENDING | The service is stopping.
 | RUNNING | The service is running.
 | CONTINUE_PENDING | The service continue is pending.
 | PAUSE_PENDING | The service pause is pending.
 | PAUSED | The service is paused.
ServiceSpecificExitCode | A service-specific error code that the service returns when an error occurs while the service is starting or stopping. This value is ignored unless the Win32ExitCode field is set to ERROR_SERVICE_SPECIFIC_ERROR.
WaitHint | An estimate of the amount of time, in milliseconds, that the service expects a pending start, stop, or continue operation to take before the service makes its next call to the Service.setServiceStatus method with either an incremented CheckPoint value or a change in CurrentState. If the amount of time specified by WaitHint passes, and CheckPoint has not been incremented or CurrentState has not changed, the service control manager or service control program can assume that an error has occurred.
Win32ExitCode | A Win32 error code that the service uses to report an error that occurs when it is starting or stopping. To return an error code specific to the service, the service must set this value to ERROR_SERVICE_SPECIFIC_ERROR to indicate that the ServiceSpecificExitCode field contains the error code. The service should set this value to NO_ERROR when it is running and on normal termination.


com.ms.util Package Overview

Microsoft Packages Overview

The com.ms.util package includes a variety of classes and interfaces for utilities such as version management, sorting, wildcard expression parsing, maintaining integer ranges, event logging, and timer services.

This package contains the following:

Classes

Interfaces

Hierarchy


Classes (com.ms.util Package)

 Microsoft SDK for Java

com.ms.util Package Classes

The com.ms.util package contains the following classes:.

ArraySort Class sorts an Object array using a Comparison object.

EventLog Class implements an event log.

FileVersionInformation Class creates file version information for a given file.

HTMLTokenizer Class parses an HTML 3.2 document.

IncludeExcludeIntRanges Class maintains a set of integers specified by a pair of IntRanges objects.

IncludeExcludeWildcards Class maintains a set of strings specified by a pair of WildcardExpression objects.

IntRanges Class maintains a list of integer ranges.

MultiComparison Class provides a comparison based on an array of other comparisons.

Queue Class provides a queue, implemented in an array.

SetComparer Class compares sets that cannot be subtracted or otherwise have no "inverse" operator.

Sort Class implements an abstract sorting engine.

StringComparison Class provides a simple comparison, similar to that done by String.compareTo.

SystemVersionManager Class provides methods that set and retrieve system version properties.

Task Class schedules and manages the execution of runnable objects in the global task manager.

TaskManager Class schedules or manages the execution of runnable objects.

ThreadLocalStorage Class allows applications to store a per-thread reference to a Java object; added as of versions 2437 through 2925 of the Microsoft virtual machine.

Timer Class implements a timer event source.

TimerEvent Class identifies the expiration of a Timer.

UnsignedIntRanges Class shifts unsigned numbers to the range of signed numbers.

VectorSort Class sorts the specified Vector object using the specified Comparison.

WildcardExpression Class matches simple wildcard expressions, such as txt or report?.doc, commonly recognized by users on most platforms.


Interfaces (com.ms.util Package)

 Microsoft SDK for Java

com.ms.util Package Interfaces

The com.ms.util package contains the following interfaces:

Comparison Interface is designed for implementing comparisons of two objects (usually used in conjunction with a VectorSort or ArraySort object).

IIntRangeComparator Interface supplies a hook for sorting auxiliary data associated with elements of an IntRanges object.

IWildcardExpressionComparator Interface is used to compare subexpressions in WildcardExpression.compare.

ProvideSetComparisonInfo Interface provides set rules for comparisons.

SetComparison Interface compares two sets.

TimerListener Interface enables TIMER event notifications to be received.


Hierarchy (com.ms.util Package)

 Microsoft SDK for Java

com.ms.util Package Hierarchy

The com.ms.util package has the following hierarchy:

Object
  |
  +--Sort
  |  |
  |  +--ArraySort
  |  |
  |  +--VectorSort
  |
  +--EventLog
  |
  +--HTMLTokenizer
  |
  +--IncludeExcludeIntRanges, (SetComparison, ProvideSetComparisonInfo)
  |
  +--IncludeExcludeWildcards, (ProvideSetComparisonInfo, SetComparison)
  |
  +--IntRanges(Cloneable, SetComparison)
  |  |
  |  +--UnsignedIntRanges
  |
  +--MultiComparison (Comparison)
  |
  +--Queue (java.util.Enumeration, Cloneable)
  |
  +--SetComparer
  |
  +--StringComparison (Comparison)
  |
  +--SystemVersionManager (Runnable)
  |
  +--Task
  |
  +--TaskManager (Runnable)
  |
  +--ThreadLocalStorage
  |
  +--Timer
  |
  +--TimerEvent
  |
  +--WildcardExpression(java.io.FilenameFilter, Cloneable, SetComparison)

Properties
  |
  +--FileVersionInformation

Comparison
IIntRangeComparator
IwildcardExpressionComparator
ProvideSetComparisonInfo
SetComparison
TimerListener


ArraySort Class (com.ms.util Package)

 Microsoft SDK for Java

ArraySort Class

The ArraySort Class of the com.ms.util package sorts an Object array using a Comparison object.

public class ArraySort extends Sort
{
  // Methods
  protected int compare(int p, int q);
  static public void sort(Object array[], Comparison comparison);
  static public void sort(Object array[], Comparison comparison,
        int first, int size);
  protected void swap(int p, int q);
}

Hierarchy

Sort
  |
  +--ArraySort


Methods (ArraySort Class)

 Microsoft SDK for Java

ArraySort Class Methods

The ArraySort Class contains the following methods:

compare compares two elements in the array using the Comparison object.
sort sorts the specified Object array using a Comparison object.
swap swaps two elements in the array.


compare (ArraySort Class)

 Microsoft SDK for Java

compare

This method of the ArraySort Class compares two elements in the array using the Comparison object.

Syntax

protected int compare(int p, int q);

Return Value

Returns the result of the comparison.

Parameters

p | The index of the first operand of the comparison.
q | The index of the second operand of the comparison.

Overrides

compare(int,int) in.Sort


sort (ArraySort Class)

 Microsoft SDK for Java

sort

The sort method of the ArraySort Class contains the following signatures:

sort(Object array[], Comparison comparison)
sort(Object array[], Comparison comparison, int first, int size)

sort(Object array[], Comparison comparison)

Sorts the specified Object array using a Comparison object.

Syntax

static public void sort(Object array[], Comparison comparison);

Parameters

array | The Object array to sort.
comparison | The Comparison object to use.

sort(Object array[], Comparison comparison, int first, int size)

Sorts a subrange of the specified Object array using a Comparison object.

Syntax

static public void sort(Object array[], Comparison comparison, int first,int size);

Parameters

array | The Object array to sort.
comparison | The Comparison to use.
first | The beginning element of the subrange.
size | The number of elements in the subrange.


swap (ArraySort Class)

 Microsoft SDK for Java

swap

This method of the ArraySort Class swaps two elements in the array.

Syntax

protected void swap(int p, int q);

Parameters

p | The index of the first operand of the swap operation.
q | The index of the second operand of the swap operation.

Overrides

swap(int,int) in Sort


EventLog Class (com.ms.util Package)

 Microsoft SDK for Java

EventLog Class

The EventLog Class of the com.ms.util package implements an event log. It is based directly upon the Microsoft® Win32® event log APIs, RegisterEventSource, ReportEvent, and DeregisterEventSource.

public class EventLog
{
  // Fields
  public static final short AUDIT_FAILURE;
  public static final short AUDIT_SUCCESS;
  public static final short ERROR;
  public static final short INFORMATION;
  public static final short SUCCESS;
  public static final short WARNING;

  // Constructors
  public EventLog(String source);
  public EventLog(String server, String source);

  // Methods
  protected void finalize();
  public void reportEvent(short type, short cat, int id,
        String[] msg, byte[] data);
  public void reportEvent(short type, short cat, int id,
        String msg, byte[] data);
  public void reportEvent(short type, short cat, int id,
        String[] msgs);
  public void reportEvent(short type, short cat, int id,
        String msg);
  public void reportEvent(short type, short cat, int id);
}

For more information on implementing and using event logs, see the Win32 documentation.


Constructors (EventLog Class)

 Microsoft SDK for Java

EventLog Class Constructors

The EventLog Class contains the following constructors:

EventLog(String source)
EventLog(String server, String source)

EventLog(String source)

Creates an EventLog object given the name of the source. This constructor calls the Win32 RegisterEventSource API.

Syntax

public EventLog(String source);

Parameters

source The name of the source referenced by the EventLog object. The source name must be a subkey of a logfile entry under the EventLog key in the registry. Its value can be null.

EventLog(String server, String source)

Creates an EventLog object given the name of the source and the name of the server. This constructor calls the Win32 RegisterEventSource API.

Syntax

public EventLog(String server, String source);

Parameters

server | The Universal Naming Convention (UNC) name of the server that this operation is to be performed on.
source | The name of the source referenced by the EventLog object. The source name must be a subkey of a logfile entry under the Eventlog key in the registry. Its value can be null.


Methods (EventLog Class)

 Microsoft SDK for Java

EventLog Class Methods

The EventLog Class contains the following methods:

finalize de-registers the event source when the garbage collector detects there are no more references to this object.
reportEvent writes an entry at the end of the event log, providing associated strings and binary data.


finalize (EventLog Class)

 Microsoft SDK for Java

finalize

This method of the EventLog Class de-registers the event source when the garbage collector detects there are no more references to this object. This method calls the Win32 DeregisterEventSource function.

Syntax

protected void finalize();


reportEvent (EventLog Class)

 Microsoft SDK for Java

reportEvent

The reportEvent method of the EventLog Class contains the following signatures:

reportEvent(short type, short cat, int id, String[] msg,byte[] data)
reportEvent(short type, short cat, int id, String msg, byte[] data)
reportEvent(short type, short cat, int id, String[] msgs)
reportEvent(short type, short cat, int id, String msg)
reportEvent(short type, short cat, int id)

reportEvent(short type, short cat, int id, String[] msg,byte[] data)

Writes an entry at the end of the event log, providing associated strings and binary data.

Syntax

public void reportEvent(short type, short cat, int id, String[] msg, byte[] data);

Parameters

type | The type of event being logged. The parameter can be one of the following types: ERROR WARNING INFORMATION AUDIT_SUCCESS AUDIT_FAILURE
cat | The event category. This is source-specific information; the category can have any value.
id | The event identifier, which specifies the message that goes with this event as an entry in the message file associated with the event source.
msgs | An array of strings that are merged into the message before the message is displayed to the user.
data | The binary data associated with the report.

reportEvent(short type, short cat, int id, String msg, byte[] data)

Writes an entry at the end of the event log, providing an associated string and binary data.

Syntax

public void reportEvent (short type, short cat, int id, String msg, byte[] data);

Parameters

type | The type of event being logged. The parameter can be one of the following types: ERROR WARNING INFORMATION AUDIT_SUCCESS AUDIT_FAILURE
cat | The event category. This is source-specific information; the category can have any value.
id | The event identifier, specifies the message that goes with this event as an entry in the message file associated with the event source.
msg | A string that is merged into the message before the message is displayed to the user.
data | The binary data associated with the report.

reportEvent(short type, short cat, int id, String[] msgs)

Writes an entry at the end of the event log, providing associated strings.

Syntax

public void reportEvent(short type, short cat, int id, String[] msgs);

Parameters

type | The type of event being logged. The parameter can be one of the following types: ERROR WARNING INFORMATION AUDIT_SUCCESS AUDIT_FAILURE
cat | The event category. This is source-specific information; the category can have any value.
id | The event identifier, which specifies the message that goes with this event as an entry in the message file associated with the event source.
msgs | An array of strings that are merged into the message before the message is displayed to the user.

reportEvent(short type, short cat, int id, String msg)

Writes an entry at the end of the event log, providing an associated string.

Syntax

public void reportEvent(short type, short cat, int id, String msg);

Parameters

type | The type of event being logged. The parameter can be one of the following types: ERROR WARNING INFORMATION AUDIT_SUCCESS AUDIT_FAILURE
cat | The event category. This is source-specific information; the category can have any value.
id | The event identifier, which specifies the message that goes with this event as an entry in the message file associated with the event source.
msgs | A string that is merged into the message before the message is displayed to the user.

reportEvent(short type, short cat, int id);

Writes an entry at the end of the event log.

Syntax

public void reportEvent(short type, short cat, int id);

Parameters

type | The type of event being logged. The parameter can be one of the following types: ERROR WARNING INFORMATION AUDIT_SUCCESS AUDIT_FAILURE
cat | The event category. This is source-specific information; the category can have any value.
id | The event identifier, which specifies the message that goes with this event as an entry in the message file associated with the event source.


Fields (EventLog Class)

 Microsoft SDK for Java

EventLog Class Fields

The EventLog Class contains the following fields.

AUDIT_FAILURE | Indicates a failure audit event.
AUDIT_SUCCESS | Indicates a success audit event.
ERROR | Indicates an error event.
INFORMATION | Indicates an information event.
SUCCESS | Indicates a success event.
WARNING | Indicates a warning event.


FileVersionInformation Class (com.ms.util Package)

 Microsoft SDK for Java

FileVersionInformation Class

The FileVersionInformation Class of the com.ms.util package creates file version information for a given file.

public class FileVersionInformation extends Properties
{
  // Constructors
  public FileVersionInformation(Sring filename);
  public FileVersionInformation(File file);
}

Hierarchy

Properties
  |
  +--FileVersionInformation


Constructors (FileVersionInformation Class)

 Microsoft SDK for Java

FileVersionInformation Class Constructors

The FileVersionInformation Class contains the following constructors:

FileVersionInformation(Sring filename)
FileVersionInformation(File file)

FileVersionInformation(String filename)

Creates a Properties object that contains file version information.

Syntax

public FileVersionInformation(String filename);

Parameters

filename

The name of the file to retrieve file version information from. The file name does not need to be absolute.

FileVersionInformation(File file)

Creates a Properties object that contains file version information.

Syntax

public FileVersionInformation(File file);

Parameters

file The File object that represents the file name.


HTMLTokenizer Class (com.ms.util Package)

 Microsoft SDK for Java

HTMLTokenizer Class

The HTMLTokenizer Class of the com.ms.util package parses an HTML version 3.2 document. The parser does not interpret any HTML tags, except for comments and the <PRE> tag.

public class HTMLTokenizer
{
  // Fields
  public Hashtable attrs;
  public String tag;
  public String text;
  public static final int TT_BEGIN_TAG;
  public static final int TT_COMMENT;
  public static final int TT_END_TAG;
  public static final int TT_TEXT;
  public int type;

  // Constructors
  public HTMLTokenizer(InputStream isin);

  // Methods
  public boolean hasMoreTokens();
  public void mark(int readLimit) throws Ioexception;
  public int nextToken()throws ParseException, IOException;
  public void reset() throws IOException;
  public String toString();
}


Constructors (HTMLTokenizer Class)

 Microsoft SDK for Java

HTMLTokenizer Class Constructors

The HTMLTokenizer Class contains the following constructor:

HTMLTokenizer(InputStream isin)

Creates an HTMLTokenizer object when passed to an input stream.

Syntax

public HTMLTokenizer(InputStream isin);

Parameters

isin The input stream to tokenize.


Methods (HTMLTokenizer Class)

 Microsoft SDK for Java

HTMLTokenizer Class Methods

The HTMLTokenizer Class contains the following methods:

hasMoreTokens indicates if the HTMLTokenizer object contains more tokens.
mark marks the parser's current position in the input stream.
nextToken parses the next token from the input stream.
reset resets the input to the last marked position.
toString retrieves a string representation of the HTMLTokenizer object.


hasMoreTokens (HTMLTokenizer Class)

 Microsoft SDK for Java

hasMoreTokens

This method of the HTMLTokenizer Class indicates if the HTMLTokenizer object contains more tokens.

Syntax

public boolean hasMoreTokens();

Return Value

Returns true if there are more tokens; otherwise, returns false.


mark (HTMLTokenizer Class)

 Microsoft SDK for Java

mark

This method of the HTMLTokenizer Class marks the parser's current position in the input stream.

Syntax

public void mark(int readLimit) throws IOException;

Parameters

readLimit The number of bytes that can be read before this mark is invalidated.

Exceptions

IOException if the tokenized input stream cannot set the requested mark.

See Also

java.lang.InputStream.mark


nextToken (HTMLTokenizer Class)

 Microsoft SDK for Java

nextToken

This method of the HTMLTokenizer Class parses the next token from the input stream. The white space that follows the token and the first character of the next token is consumed.

Syntax

public int nextToken() throws ParseException, IOException;

Return Value

Returns one the following token types:

TT_TEXT
TT_BEGIN_TAG
TT_END_TAG
TT_COMMENT

Exceptions

java.util.NoSuchElementException if a null token is received.

java.text.ParseException if no tag is found after a less than (<) symbol or a tag does not have a matching greater than (>) symbol.


reset (HTMLTokenizer Class)

 Microsoft SDK for Java

reset

This method of the HTMLTokenizer Class resets the input to the last marked position.

Syntax

public void reset() throws IOException;

Exceptions

IOException if the tokenized input stream cannot set the requested mark.

See Also

java.lang.InputStream.reset


toString (HTMLTokenizer Class)

 Microsoft SDK for Java

toString

This method of the HTMLTokenizer Class retrieves a string representation of the HTMLTokenizer object.

Syntax

public String toString();

Return Value

Returns a string containing the tag types, tags, attributes, and text of the current token in the HTML file.


Fields (HTMLTokenizer Class)

 Microsoft SDK for Java

HTMLTokenizer Class Fields

The HTMLTokenizer Class contains the following fields.

attrs | The attributes of a tag. They are valid for these token types: TT_BEGIN_TAG and TT_END_TAG.
tag | The tag. Comments: If this is the closing end of a tag, it will not have the leading slash (/) character. This tag is valid for these token types: TT_BEGIN_TAG and TT_END_TAG.
text | Plain text. They are valid for these token types: TT_TEXT and TT_COMMENT.
TT_BEGIN_TAG | A token type representing a beginning tag (for example, <H1>).
TT_COMMENT | A token type representing a comment.
TT_END_TAG | A token type representing an ending tag (for example, </H1>).
TT_TEXT | A token type representing the token text.
type | The last token type read. It can be one of the following: TT_TEXT TT_BEGIN_TAG TT_END_TAG TT_COMMENT


IncludeExcludeIntRanges Class (com.ms.util Package)

 Microsoft SDK for Java

IncludeExcludeIntRanges Class

The IncludeExcludeIntRanges Class of the com.ms.util package maintains a set of integers specified by a pair of IntRanges objects. The First IntRanges object specifies a set of integers that are included in the set, and the second specifies integers that are excluded from the set.

public class IncludeExcludeIntRanges implements SetComparison
            ProvideSetComparisonInfo
{
  // Constructors
  public IncludeExcludeIntRanges(InitRanges Include,
        IntRanges exclude);
  public IncludeExcludeIntRanges();

  // Methods
  public Object combineSetRules(Object o1, Object o2);
  public int compareSet(Object other)
  public int compareSetRules(Object o1, Object o2);
  public boolean contains(int n);
  public void excludeRange(int s, int e);
  public void excludeRanges(IntRanges ranges);
  public IntRanges getExcludedRanges();
  public IntRanges getIncludedRanges();
  public Object getSetRule(int rule);
  public String getStringForSetRule(object o);
  public void includeRange(int s, int e);
  public void includeRanges(IntRanges ranges);
  public Object intersectSetRules(Object o1, Object o2);
  public void invalidate();
  public boolean isEmptySetRule(object o);
  public String toString();
  public void validate();
}


Constructors (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

IncludeExcludeIntRanges Class Constructors

The IncludeExcludeIntRanges Class contains the following constructors:

IncludeExcludeIntRanges(InitRanges Include, IntRanges exclude)
IncludeExcludeIntRanges()

IncludeExcludeIntRanges(IntRanges include, IntRanges exclude)

Constructs a new IncludeExcludeIntRanges given an IntRanges object matching the included integers and an IntRanges object matching the excluded integers.

Syntax

public IncludeExcludeIntRanges(IntRanges include, IntRanges exclude);

Parameters

include | The integers that are included in the set.
exclude | The integers that are excluded from the set.

IncludeExcludeIntRanges()

Constructs an empty IncludeExcludeIntRanges object.

Syntax

public IncludeExcludeIntRanges();


Methods (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

IncludeExcludeIntRanges Class Methods

The IncludeExcludeIntRanges Class contains the following methods:

combineSetRules combines two set rule objects.
compareSet compares the current IncludeExcludeIntRanges object with another.
compareSetRules compares two objects retrieved from getRule.
contains determines if n is a member of the set.
excludeRange excludes a range of integers in the set.
excludeRanges excludes a set of integers in the set.
getExcludedRanges retrieves the set of all excluded ranges.
getIncludedRanges retrieves the set of all included ranges.
getSetRule obtains an object representing the specified rule that can be used internally by SetComparer.
getStringForSetRule retrieves a String representation of a given set rule.
includeRange includes a range of integers in the set.
includeRanges includes a set of integers in the set.
intersectSetRules determines the intersection of two set rule objects.
invalidate ensures that the set is in a valid state.
isEmptySetRule determines if the set rule is empty or not.
toString retrieves a string representation of the object.
validate forces the next operation that requires the set to be valid to validate the set.


combineSetRules (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

combineSetRules

This method of the IncludeExcludeIntRanges Class combines two set rule objects.

Syntax

public Object combineSetRules(Object o1, Object o2);

Return Value

Returns an object containing the combined set rules.

o1 | The object containing the first set rule.
o2 | The object containing the second set rule.


compareSet (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

compareSet

This method of the IncludeExcludeIntRanges Class compares the current IncludeExcludeIntRanges object with another.

Syntax

public int compareSet(Object other);

Return Value

Returns a SetComparison.compareSet result code.

Parameters

other The object with which to compare this object.


compareSetRules (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

compareSetRules

This method of the IncludeExcludeIntRanges Class compares two objects retrieved from getRule.

Syntax

public int compareSetRules(Object o1, Object o2);

Return Value

Returns a SetComparison.compareSet result code.

Parameters

o1 | The object containing the first set rule.
o2 | The object containing the second set rule.


contains (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

contains

This method of the IncludeExcludeIntRanges Class determines if n is a member of the set.

Syntax

public boolean contains(int n);

Return Value

Returns true if n is in the set.

n The integer to test for membership.


excludeRange (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

excludeRange

This method of the IncludeExcludeIntRanges Class excludes a range of integers in the set.

Syntax

public void excludeRange(int s, int e);

Parameters

s | The lower limit of the range.
e | The upper limit of the range.


excludeRanges (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

excludeRanges

This method of the IncludeExcludeIntRanges Class excludes a set of integers in the set.

Syntax

public void excludeRanges(IntRanges ranges);

Parameters

ranges An IntRanges object specifying integers to exclude.


getExcludedRanges (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

getExcludedRanges

This method of the IncludeExcludeIntRanges Class retrieves the set of all excluded ranges.

Syntax

public IntRanges getExcludedRanges();

Return Value

Returns a set of ranges.


getIncludedRanges (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

getIncludedRanges

This method of the IncludeExcludeIntRanges Class retrieves the set of all included ranges.

Syntax

public IntRanges getIncludedRanges();

Return Value

Returns a set of ranges.


getSetRule (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

getSetRule

This method of the IncludeExcludeIntRanges Class obtains an object representing the specified rule that can be used internally by SetComparer.

Syntax

public Object getSetRule(int rule);

Return Value

Returns the set rule object.

Parameters

rule The rule that specifies the object to return.


getStringForSetRule (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

getStringForSetRule

This method of the IncludeExcludeIntRanges Class retrieves a String representation of a given set rule.

Syntax

public String getStringForSetRule(Object o);

Return Value

Returns the set rule String.

Parameters

o The object containing the set rule.


includeRange (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

includeRange

This method of the IncludeExcludeIntRanges Class includes a range of integers in the set.

Syntax

public void includeRange(int s, int e);

Parameters

s | The lower limit of the range.
e | The upper limit of the range.


includeRanges (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

includeRanges

This method of the IncludeExcludeIntRanges Class includes a set of integers in the set.

Syntax

public void includeRanges(IntRanges ranges);

Parameters

ranges An IntRanges object specifying the integers to include.


intersectSetRules (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

intersectSetRules

This method of the IncludeExcludeIntRanges Class determines the intersection of two set rule objects.

Syntax

public Object intersectSetRules(Object o1, Object o2);

Return Value

Returns an object containing the intersection of the set rules.

Parameters

o1 | The object containing the first set rule.
o2 | The object containing the second set rule.


invalidate (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

invalidate

This method of the IncludeExcludeIntRanges Class ensures that the set is in a valid state.

Syntax

public void invalidate();

Remarks

The set is automatically invalidated when additional expressions are included or excluded, and is automatically validated by other operators when necessary. If the set is already known to be in a valid state, this method does nothing. Validation is relatively expensive, so invoking this method in advance can speed up other operations that require validations.


isEmptySetRule (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

isEmptySetRule

This method of the IncludeExcludeIntRanges Class determines if the set rule is empty or not.

Syntax

public boolean isEmptySetRule(Object o);

Return Value

Returns true if the set rule is empty; otherwise, returns false.

Parameters

o The object containing the set rule.


toString (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

toString

This method of the IncludeExcludeIntRanges Class retrieves a string representation of the object.

Syntax

public String toString();

Return Value

Returns a String showing the IntRanges object’s included and excluded sets.


validate (IncludeExcludeIntRanges Class)

 Microsoft SDK for Java

validate

This method of the IncludeExcludeIntRanges Class forces the next operation that requires the set to be valid to validate the set. The set can be manually placed in a valid state by invoking validate.

Syntax

public void validate();


IncludeExcludeWildcards Class (com.ms.util Package)

 Microsoft SDK for Java

IncludeExcludeWildcards Class

The IncludeExcludeWildcards Class of the com.ms.util package maintains a set of strings specified by a pair of WildcardExpression objects. The first expression specifies a set of strings that are included in the set, the second specifies strings that are excluded from the set. Because WildcardExpression cannot be subtracted, this class provides a way of emulating subtraction.

public class IncludeExcludeWildcards implements
            ProvideSetComparisonInfo, SetComparison
{
  // Constructors
  public IncludeExcludeWildcards(WildcardExpression include,
        WildcardExpression exclude);

  // Methods
  public Object combineSetRules(Object o1, Object o2);
  public int compareSet(Object other);
  public int compareSetRules(Object o1, Object o2);
  public synchronized void exclude(WildcardExpression expr);
  public WildcardExpression getExcludeExpression();
  public WildcardExpression getIncludeExpression();
  public Object getSetRule(int rule);
  public String getStringForSetRule(Object o);
  public synchronized void include(WildcardExpression expr);
  public Object intersectSetRules(Object o1, Object o2)
  public synchronized void invalidate();
  public boolean isEmptySetRule(Object o);
  public boolean match(String s);
  public String toString();
  public synchronized void validate();
}


Constructors (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

IncludeExcludeWildcards Class Constructors

The IncludeExcludeWildcards Class contains the following constructor:

IncludeExcludeWildcards(WildcardExpression include, WildcardExpression exclude)

Constructs a new IncludeExcludeWildcards object given a WildcardExpression matching the included strings and a WildcardExpression matching the excluded strings.

Syntax

public IncludeExcludeWildcards(WildcardExpression include, WildcardExpression exclude);

Parameters

include | The expression strings that are included in the set.
exclude | The expression strings that are excluded from the set.


Methods (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

IncludeExcludeWildcards Class Methods

The IncludeExcludeWildcards Class contains the following methods:

combineSetRules combines two set rule objects.
compareSet compares this IncludeExcludeWildcards object against another IncludeExcludeWildCards object.
compareSetRules compares two objects retrieved from getRule.
exclude adds an expression matching the strings that should be excluded in the set.
getExcludeExpression retrieves the WildcardExpression object that specifies the strings that are excluded from the set.
getIncludeExpression retrieves the WildcardExpression object that specifies the strings that are included in the set.
getSetRule obtains an object representing the specified rule that can be used internally by SetComparer.
getStringForSetRule retrieves a String representation of a given set rule.
include adds an expression matching the strings that should be included in the set.
intersectSetRules determines the intersection of two set rule objects.
invalidate forces the next operation that requires the set to be valid to validate the set.
isEmptySetRule determines if the set rule is empty or not.
match determines if s is a member of the set.
toString retrieves a string representation of the IncludeExcludeWildcards object.
validate ensures that the set is in a valid state.


combineSetRules (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

combineSetRules

This method of the IncludeExcludeWildcards Class combines two set rule objects

Syntax

public Object combineSetRules(Object o1, Object o2);

Return Value

Returns an object containing the combined set rules.

o1 | The object containing the first set rule.
o2 | The object containing the second set rule.


compareSet (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

compareSet

This method of the IncludeExcludeWildcards Class compares this IncludeExcludeWildcards object against another IncludeExcludeWildCards object.

Syntax

public int compareSet(Object other);

Return Value

Returns a SetComparison.compareSet result code.

Parameters

other The object with which to compare this object.


compareSetRules (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

compareSetRules

This method of the IncludeExcludeWildcards Class compares two objects retrieved from getRule.

Syntax

public int compareSetRules(Object o1, Object o2);

Return Value

Returns a SetComparison.compareSet result code.

Parameters

o1 | The object containing the first set rule.
o2 | The object containing the second set rule.


exclude (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

exclude

This method of the IncludeExcludeWildcards Class adds an expression matching the strings that should be excluded in the set.

Syntax

public synchronized void exclude(WildcardExpression expr);

Parameters

expr A WildcardExpression specifying strings that should be excluded.


getExcludeExpression (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

getExcludeExpression

This method of the IncludeExcludeWildcards Class retrieves the WildcardExpression object that specifies the strings that are excluded from the set.

Syntax

public WildcardExpression getExcludeExpression();

Return Value

Returns the WildcardExpression object that specifies the strings that are excluded from the set. If the IncludeExcludeWildcards object was created with a null exclude parameter and the exclude method has not been called, the method returns null.

See Also

exclude


getIncludeExpression (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

getIncludeExpression

This method of the IncludeExcludeWildcards Class retrieves the WildcardExpression object that specifies the strings that are included in the set.

Syntax

public WildcardExpression getIncludeExpression();

Return Value

Returns the WildcardExpression object that specifies the strings that are included in the set. If the IncludeExcludeWildcards object was created with a null include parameter and the include method has not been called, the method returns null.

See Also

include


getSetRule (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

getSetRule

This method of the IncludeExcludeWildcards Class obtains an object representing the specified rule that can be used internally by SetComparer.

Syntax

public Object getSetRule(int rule);

Return Value

Returns the set rule object.

Parameters

rule The rule that specifies the object to return.


getStringForSetRule (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

getStringForSetRule

This method of the IncludeExcludeWildcards Class retrieves a String representation of a given set rule.

Syntax

public String getStringForSetRule(Object o);

Return Value

Returns the set rule String.

Parameters

o The object containing the set rule.


include (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

include

This method of the IncludeExcludeWildcards Class adds an expression matching the strings that should be included in the set.

Syntax

public synchronized void include(WildcardExpression expr);

Parameters

expr A WildcardExpression specifying strings that should be included.


intersectSetRules (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

intersectSetRules

This method of the IncludeExcludeWildcards Class determines the intersection of two set rule objects.

Syntax

public Object intersectSetRules(Object o1, Object o2);

Return Value

Returns an object containing the intersection of the set rules.

Parameters

o1 | The object containing the first set rule.
o2 | The object containing the second set rule.


invalidate (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

invalidate

This method of the IncludeExcludeWildcards Class forces the next operation that requires the set to be valid to validate the set. The set can be manually placed in a valid state by invoking validate.

Syntax

public synchronized void invalidate();


isEmptySetRule (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

isEmptySetRule

This method of the IncludeExcludeWildcards Class determines if the set rule is empty or not.

Syntax

public boolean isEmptySetRule(Object o);

Return Value

Returns true if the set rule is empty; otherwise, returns false.

Parameters

o The object containing the set rule.


match (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

match

This method of the IncludeExcludeWildcards Class determines if String s is a member of the set.

Syntax

public boolean match(String s);

Return Value

Returns true if s is in the set.

Parameters

s The String to test for membership.


toString (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

toString

This method of the IncludeExcludeWildcards Class retrieves a string representation of the IncludeExcludeWildcards object.

Syntax

public String toString();

Return Value

Returns a string containing both the include and exclude WildcardExpression objects.


validate (IncludeExcludeWildcards Class)

 Microsoft SDK for Java

validate

This method of the IncludeExcludeWildcards Class ensures that the set is in a valid state.

Syntax

public synchronized void validate();

Remarks

The set is automatically invalidated when additional expressions are included or excluded, and is automatically validated by other operators when necessary. If the set is already known to be in a valid state, this method does nothing. Validation is relatively expensive, so invoking this method in advance can speed up other operations that require validations.


IntRanges Class (com.ms.util Package)

 Microsoft SDK for Java

IntRanges Class

The IntRanges Class of the com.ms.util package maintains a list of integer ranges. Readers and writers of this list should be externally synchronized.

public class IntRanges implements Cloneable, SetComparison
{
  // Constructors
  public IntRanges();
  public IntRanges(String str);
  public IntRanges(String str, String delims);

  // Methods
  public synchronized void addRange(int s, int e);
  public synchronized void addRanges(IntRanges r);
  public synchronized void addSingleton(int n);
  public StringBuffer appendToStringBuffer(StringBuffer sb);
  protected Object clone();
  public int compare(IntRanges other);
  public int compare(IntRanges other);
  public int compareSet(Object other);
  public static String ComparisonResulttoString(int cmp);
  public synchronized void condense(IIntRangeComparator judge);
  public void condense();
  public boolean contains(int find);
  public synchronized boolean contains(int s, int e);
  public synchronized IntRanges copy();
  public int getRangeEnd(int idx);
  public synchronized int[] getRanges();
  public int getRangeStart(int idx);
  public int synchronized indexOf(int find, int fromRange);
  public int indexOf(int find);
  public IntRanges intersect(IntRanges other
        IIntRangeComparator judge);
  public IntRanges intersect(IntRanges other);
  public static int invertComparisonResult(int cmp);
  public boolean isEmpty();
  public synchronized boolean lock(Object key);
  public synchronized void parse(String str, String delims);
  public void parse(String str);
  public boolean removeRange(int re, int re);
  public void removeRange(int i, IIntRangeComparator hook);
  public void removeRange(int i);
  public synchronized boolean removeRange(int s, int e,
        IIntRangeComparator hook);
  public synchronized void removeRanges(int i, int count,
        IIntRangeComparator hook);
  public void removeRanges(int i, int count);
  public boolean removeSingleton(int n);
  public boolean removeSingleton(int n, IIntRangeComparator hook);
  public synchronized void setRanges(int[] array);
  public int size();
  public synchronized void sort(IIntComparator judge);
  public void sort();
  public String toString();
  public synchronized boolean unlock(Object key);
}


Constructors (IntRanges Class)

 Microsoft SDK for Java

IntRanges Class Constructors

The IntRanges Class contains the following constructors:

IntRanges()
IntRanges(String str)
IntRanges(String str, String delims)

IntRanges()

Constructs an empty set of ranges as an IntArrayOutputStream object.

Syntax

public IntRanges();

IntRanges(String str)

Constructs a set of ranges from the given string.

Syntax

public IntRanges(String str);

Exceptions

Throws IllegalArgumentException if the string to be parsed is invalid.

Parameters

str A string containing ranges of integers, where the bounds of each range are separated by a hyphen (-), and separate ranges are delimited by commas. A range of a single integer can be entered by including just the single integer, separated by delimiters. For example: 1-5,9-11,44,13-120.

IntRanges(String str, String delims)

Constructs a set of ranges from the given string with specified delimiters.

Syntax

public IntRanges(String str, String delims);

Exceptions

Throws IllegalArgumentException if the string to be parsed is invalid.

Parameters

str | A string containing ranges of integers, where the bounds of each range are separated by a hyphen (-). A range of a single integer can be entered by including just the single integer, separated by delimiters.
delims | The character or characters that separate the ranges.


Methods (IntRanges Class)

 Microsoft SDK for Java

IntRanges Class Methods

The IntRanges Class contains the following methods:

addRange adds a range to the IntRange object.
addRanges adds another set of ranges to this object's set of ranges.
addSingleton adds a range of a single integer to the IntRange object.
appendToStringBuffer appends a string representation of the integer ranges to a given string buffer.
clone creates a copy of the set of ranges.
compare compares this set of ranges to another.
compareSet compares this set of ranges to another.
ComparisonResulttoString converts comparison result flags to a string format.
condense merges overlapping ranges.
contains searches from the beginning of a range for a given number.
copy creates a copy of the set of ranges.
getRangeEnd retrieves the end of a range at a specified index.
getRanges retrieves the integer range pairs as an integer array.
getRangeStart retrieves the start of a range at a specified index.
indexOf searches from a starting index for a range pair containing a given a number.
intersect constructs a new IntRanges object with the set of integers that are common to both this object and another object.
invertComparisonResult inverts comparison results.
isEmpty determines if the IntRanges object is empty.
lock assigns a key and locks the IntRanges object.
parse parses the ranges in the string, separated with specified delimiters.
removeRange removes a range of integers from the IntRange object.
removeRanges removes ranges specified by index from the IntRange object.
removeSingleton removes a single integer from the IntRange object.
setRanges sets the integer ranges from an existing integer array.
size retrieves the size of the IntRanges object.
sort sorts the ranges by the first element in each range pair.
toString retrieves a string representation of the IntRanges.
unlock unlocks the IntRanges.


addRange (IntRanges Class)

 Microsoft SDK for Java

addRange

This method of the IntRanges Class adds a range to the IntRange object.

Syntax

public synchronized void addRange(int s, int e);

Exceptions

Throws SecurityException if there is an immutable key.

Throws IllegalArgumentException if the lower limit of the range is greater than the upper limit of the range.

Parameters

s | The lower limit of the range.
e | The upper limit of the range.


addRanges (IntRanges Class)

 Microsoft SDK for Java

addRanges

This method of the IntRanges Class adds another set of ranges to this object's set of ranges.

Syntax

public synchronized void addRanges(IntRanges r);

Parameters

r Another IntRangesIntRanges object.


addSingleton (IntRanges Class)

 Microsoft SDK for Java

addSingleton

This method of the IntRanges Class adds a range of a single integer to the IntRange object.

Syntax

public synchronized void addSingleton(int n);

Exceptions

Throws SecurityException if there is an immutable key.

Parameters

n The integer range. For example, if n is 43, a range of 43-43 is added.


appendToStringBuffer (IntRanges Class)

 Microsoft SDK for Java

appendToStringBuffer

This method of the IntRanges Class appends a string representation of the integer ranges to a given string buffer. Used by toString.

Syntax

public StringBuffer appendToStringBuffer(StringBuffer sb);

Return Value

Returns a string buffer containing the concatenated strings.

Parameters

sb The string buffer to append the set of integer range pairs to.


clone (IntRanges Class)

 Microsoft SDK for Java

clone

This method of the IntRanges Class creates a copy of the set of ranges.

Syntax

protected Object clone();

Return Value

Returns an identical object to this object.


compare (IntRanges Class)

 Microsoft SDK for Java

compare

The compare method of the IntRanges Class contains the following signatures:

compare(IntRanges other)
compare(IntRanges other, IIntRangeComparator judge)

compare(IntRanges other)

Compares this set of ranges to another.

Syntax

public int compare(IntRanges other);

Return Value

Returns the ranges shown in the following table.

OVERLAP | If the sets of integers are not equal, but have a common set of integers.
DISJOINT | If the sets of integers have no integers in common.
SUBSET | If the second set of integers includes all the integers in the first set, plus some integers that are not in the first set.
EQUAL | If the sets of integers are identical.
SUPERSET | If the first set of integers includes all the integers in the second set, plus some integers that are not in the second set.
EMPTY | If both sets of integers are empty.
EMPTY_SUBSET | If pairs1 is empty and pairs2 is not empty.
EMPTY_SUPERSET | If pairs2 is empty and pairs1 is not empty.

Parameters

other The set of ranges to compare with.

compare(IntRanges other, IIntRangeComparator judge)

Compares this set of ranges to another.

Syntax

public int compare(IntRanges other, IIntRangeComparator judge);

Return Value

Returns ranges shown in the following table.

OVERLAP | If the sets of integers are not equal, but have a common set of integers.
DISJOINT | If the sets of integers have no integers in common.
SUBSET | If the second set of integers includes all the integers in the first set, plus some integers that are not in the first set.
EQUAL | If the sets of integers are identical.
SUPERSET | If the first set of integers includes all the integers in the second set, plus some integers that are not in the second set.
EMPTY | If both sets of integers are empty.
EMPTY_SUBSET | If pairs1 is empty and pairs2 is not empty.
EMPTY_SUPERSET | If pairs2 is empty and pairs1 is not empty.

Parameters

other | The set of ranges to compare with.
judge | A helper interface for the comparison.


compareSet (IntRanges Class)

 Microsoft SDK for Java

compareSet

This method of the IntRanges Class compares this set of ranges to another.

Syntax

public int compareSet(Object other);

Return Value

Returns SetComparison.DISJOINT if other is not an instance of IntRanges, or else a SetComparison.compareSet result:

SetComparison.OVERLAP | The sets of integers are not equal but have a common set of integers.
SetComparison.DISJOINT | The sets of integers have no integers in common.
SetComparison.SUBSET | other includes all the integers in this set, plus some integers that are not in this set.
SetComparison.EQUAL | The sets of integers are identical.
SetComparison.SUPERSET | This set of integers includes all the integers in other, plus some integers that are not in other.
SetComparison.EMPTY | Both sets of integers are empty.
SetComparison.EMPTY_SUBSET | This set is empty and other is not empty.
SetComparison.EMPTY_SUPERSET | This set is not empty and other is empty.

Parameters

other The set of ranges to compare with.


ComparisonResulttoString (IntRanges Class)

 Microsoft SDK for Java

ComparisonResulttoString

This method of the IntRanges Class converts comparison result flags to a string format.

Syntax

public static String ComparisonResulttoString(int cmp);

Return Values

Returns the result string as follows:

  1. "empty" (EMPTY)

  2. "equal" (EQUAL)

  3. "disjoint" (DISJOINT)

  4. "overlap" (OVERLAP)

  5. "inclusive subset" (SUBSET)

  6. "inclusive superset" (SUPERSET)

  7. "empty subset" (EMPTY_SUBSET)

  8. "empty superset" (EMPTY_SUPERSET)

  9. When an interger that is out of range is used, the return string is in the form (unknown xx), where xx is the integer it recieved.

Parameters

cmp A comparison result from the compare method.


condense (IntRanges Class)

 Microsoft SDK for Java

condense

The condense method of the IntRanges Class contains the following signatures:

condense(IIntRangeComparator judge)
condense()

condense(IIntRangeComparator judge)

Merges overlapping ranges. This method assumes the ranges have already been sorted.

Syntax

public synchronized void condense(IIntRangeComparator judge);

Exceptions

Throws SecurityException if there is an immutable key.

Parameters

judge The interface to help compare equal integer ranges while sorting. This parameter value can be null.

condense()

Merges overlapping ranges. This method assumes the ranges have already been sorted.

Syntax

public void condense();

Exceptions

Throws SecurityException if there is an immutable key.


contains (IntRanges Class)

 Microsoft SDK for Java

contains

The contains method of the IntRanges Class contains the following signatures:

contains(int find)
contains(int s, int e)

contains(int find)

Searches from the beginning of a range for a given number.

Syntax

public boolean contains(int find);

Exceptions

Throws IllegalArgumentException if the parameter is invalid.

Return Value

Returns true if the number was found; otherwise, returns false.

Parameters

find The number to search for.

contains(int s, int e)

Searches from the beginning of a range for a given range of numbers.

Syntax

public synchronized boolean contains(int s, int e);

Exceptions

Throws IllegalArgumentException if the parameter is invalid.

Return Value

Returns true if the entire search range was found; otherwise, returns false.

Parameters

s | The lower limit of the range.
e | The upper limit of the range.


copy (IntRanges Class)

 Microsoft SDK for Java

copy

This method of the IntRanges Class creates a copy of the set of ranges.

Syntax

public synchronized IntRanges copy();

Return Value

Returns an identical object to this object.


getRangeEnd (IntRanges Class)

 Microsoft SDK for Java

getRangeEnd

This method of the IntRanges Class retrieves the end of a range at a specified index.

Syntax

public int getRangeEnd(int idx);

Exceptions

Throws ArrayIndexOutOfBoundsException if the index is less than zero or equal to or greater than the array size.

Return Value

Returns the last integer of the range pair.

Parameters

idx The index of the range pair.


getRanges (IntRanges Class)

 Microsoft SDK for Java

getRanges

This method of the IntRanges Class retrieves the integer range pairs as an integer array.

Syntax

public synchronized int[] getRanges();

Return Value

Returns the integer ranges.


getRangeStart (IntRanges Class)

 Microsoft SDK for Java

getRangeStart

This method of the IntRanges Class retrieves the start of a range at a specified index.

Syntax

public int getRangeStart(int idx);

Exceptions

Throws ArrayIndexOutOfBoundsException if the index is less than zero or equal to or greater than the array size.

Return Value

Returns the first integer of the range pair.

Parameters

idx The index of the range pair.


indexOf (IntRanges Class)

 Microsoft SDK for Java

indexOf

The indexOf method of the IntRanges Class contains the following signatures:

indexOf(int find, int fromRange)
indexOf(int find)

indexOf(int find, int fromRange)

Searches from a starting index for a range pair containing a given a number. This method sorts but does not condense the ranges.

Syntax

public synchronized int indexOf(int find, int fromRange);

Exceptions

Throws ArrayIndexOutOfBoundsException if the index is less than zero or equal to or greater than the array size.

Return Value

Returns the index of the range pair that includes the number if found; otherwise, returns -1.

Parameters

find | The number to search for.
fromRange | The index of the range pair to start the search from.

indexOf(int find)

Searches from the beginning for a range pair containing a given number. This method sorts but does not condense the ranges.

Syntax

public int indexOf(int find);

Return Value

Retuens the index of the range pair that includes the number (if found); otherwise, returns -1.

Parameters

find The number to search for.


intersect (IntRanges Class)

 Microsoft SDK for Java

intersect

The intersect method of the IntRanges Class contains the following signatures:

intersect(IntRanges other, IIntRangeComparator judge)
intersect(IntRanges other)

intersect(IntRanges other, IIntRangeComparator judge)

Constructs a new IntRanges object with the set of integers that are common to both this object and another object.

Syntax

public IntRanges intersect(IntRanges other, IIntRangeComparator judge);

Return Value

Returns an IntRanges object for the intersection of this object and other. Returns NULL if the ranges are DISJOINT.

Parameters

other | The other IntRanges object to find an intersection with.
judge | The hook interface to notify using IIntRangeComparator.intersectRanges of intersecting ranges that will be added to the new IntRanges object.

intersect(IntRanges other)

Constructs a new IntRanges object with the set of integers that are common to both this object and another object.

Syntax

public IntRanges intersect(IntRanges other);

Return Value

Returns an IntRanges object for the intersection of this object and other. Returns NULL if the ranges are DISJOINT.

Parameters

other The other IntRanges object to find an intersection with.


invertComparisonResult (IntRanges Class)

 Microsoft SDK for Java

invertComparisonResult

This method of the IntRanges Class inverts comparison results.

Syntax

public static int invertComparisonResult(int cmp);

Return Value

Returns the inverted comparison result. If cmp is a valid SetComparison result, and is not one of the four results that are inverted, the result is simply returned.

Exceptions

Throws InternalError if cmp is not a valid SetComparison result.

Parameters

cmp Any comparison result of the compare method, which is inverted as follows:
  1. SUBSET returns SUPERSET.

  2. SUPERSET returns SUBSET.

  3. EMPTY_SUBSET returns EMPTY_SUPERSET.

  4. EMPTY_SUPERSET returns EMPTY_SUBSET

  5. Any other result is not affected and is simply returned. Note that EQUAL and DISJOINT are not inverted by this function.


isEmpty (IntRanges Class)

 Microsoft SDK for Java

isEmpty

This method of the IntRanges Class determines if the IntRanges object is empty.

Syntax

public boolean isEmpty();

Return Value

Returns true if the object contains no ranges; otherwise, returns false.


lock (IntRanges Class)

 Microsoft SDK for Java

lock

This method of the IntRanges Class assigns a key and locks the IntRanges object.

Syntax

public synchronized boolean lock(Object key);

Return Value

Returns true if successful; returns false if the object is already locked.

Parameters

key The key object to be used for unlocking the object.

Exceptions

NullPointerException if the key is null.


parse (IntRanges Class)

 Microsoft SDK for Java

parse

The parse method of the IntRanges Class contains the following signatures:

parse(String str, String delims)
parse(String str)

parse(String str, String delims)

Parses the ranges in the string, separated with specified delimiters. This method tokenizes using StringTokenizer.

Syntax

public synchronized void parse(String str, String delims);

Parameters

str | The string to be parsed.
delims | The delimiters.

parse(String str)

Parses comma-delimited ranges in the string.

Syntax

public void parse(String str);

Parameters

str A string containing ranges of integers, where the bounds of each range are separated by a hyphen (-). A range of a single integer can be entered by including just the single integer, separated by delimiters.


removeRange (IntRanges Class)

 Microsoft SDK for Java

removeRange

The removeRange of the IntRanges Class contains the following signatures:

removeRange(int re, int re)
removeRange(int i, IIntRangeComparator hook)
removeRange(int i)
removeRange(int s, int e, IIntRangeComparator hook)

removeRange(int rs, int re)

Removes a range of integers from the IntRange object.

Syntax

public boolean removeRange(int rs, int re);

Return Value

Returns true if any integers in the range were removed; returns false if the set contains no integers in the range.

Parameters

rs | The lower limit of the range.
re | The upper limit of the range.

removeRange(int i, IIntRangeComparator hook)

Removes a single range specified by index from the IntRange object.

Syntax

public void removeRange(int i, IIntRangeComparator hook);

Parameters

i | The index of the range to remove.
hook | The interface to notify through IIntRangeComparator.shiftRanges that the ranges were deleted.

removeRange(int i)

Removes a single range specified by index from the IntRange object.

Syntax

public void removeRange(int i);

Parameters

i The index of the range to remove.

removeRange(int s, int e, IIntRangeComparator hook)

Removes a range of integers from the IntRange object.

Syntax

public synchronized boolean removeRange(int s, int e, IIntRangeComparator hook);

Return Value

Returns true if any integers in the range were removed; returns false if the set contains no integers in the range.

Parameters

rs | The lower limit of the range.
re | The upper limit of the range.
hook | The interface to notify through IIntRangeComparator.shiftRanges that the ranges were deleted or IIntRangeComparator.splitRange that a range was split.


removeRanges (IntRanges Class)

 Microsoft SDK for Java

removeRanges

The removeRanges method of the IntRanges Class contains the following signatures:

removeRanges(int i, int count, IIntRangeComparator hook)
removeRanges(int i, int count)

removeRanges(int i, int count, IIntRangeComparator hook)

Removes ranges specified by index from the IntRange object.

Syntax

public synchronized void removeRanges(int i, int count, IIntRangeComparator hook);

Parameters

i | The index of the range to remove.
count | The number ranges to remove.
hook | The interface to notify through IIntRangeComparator.shiftRanges that the ranges were deleted.

removeRanges(int i, int count)

Removes ranges specified by index from the IntRange object.

Syntax

public void removeRanges(int i, int count);

Parameters

i | The index of the range to remove.
count | The number ranges to remove.


removeSingleton (IntRanges Class)

 Microsoft SDK for Java

removeSingleton

The removeSingleton method of the IntRanges Class contains the following signatures:

removeSingleton(int n)
removeSingleton(int n, IIntRangeComparator hook)

removeSingleton(int n)

Removes a single integer from the IntRange object.

Syntax

public boolean removeSingleton(int n);

Return Value

Returns true if the integer was removed returns false if the integer was not found in the set.

Parameters

n The integer to remove.

removeSingleton(int n, IIntRangeComparator hook)

Removes a single integer from the IntRange object.

Syntax

public boolean removeSingleton(int n, IIntRangeComparator hook);

Return Value

Returns true if the integer was removed. This method returns false if the integer was not found in the set.

Parameters

n | The integer to remove.
hook | The interface to notify through IIntRangeComparator.shiftRanges that ranges were deleted or IIntRangeComparator.splitRange that a range was split.


setRanges (IntRanges Class)

 Microsoft SDK for Java

setRanges

This method of the IntRanges Class sets the integer ranges from an existing integer array.

Syntax

public synchronized void setRanges(int[] array);

Parameters

array The array of integer ranges. Each range is specified by two adjacent integers in this array.


size (IntRanges Class)

 Microsoft SDK for Java

size

This method of the IntRanges Class retrieves the size of the IntRanges

Syntax

public int size();

Return Value

Returns the number of elements in the object.


sort (IntRanges Class)

 Microsoft SDK for Java

sort

The sort method of the IntRanges Class contains the following signatures:

sort(IIntRangeComparator judge)
sort()

sort(IIntRangeComparator judge)

Sorts the ranges by the first element in each range pair.

Syntax

public synchronized void sort(IIntRangeComparator judge);

Exceptions

Throws SecurityException if the key is immutable.

Parameters

judge The interface to help compare equal ranges while sorting. This parameter value can be null.

sort()

Sorts the ranges by left endpoints.

Syntax

public void sort();


toString (IntRanges Class)

 Microsoft SDK for Java

toString

This method of the IntRanges Class retrieves a string representation of the IntRanges object.

Syntax

public String toString();

Return Value

Returns a string containing "{" followed by the set of integer range pairs, followed by "}".


unlock (IntRanges Class)

 Microsoft SDK for Java

unlock

This method of the IntRanges Class unlocks the IntRanges using a previously-assigned key.

Syntax

public synchronized boolean unlock(Object key);

Return Value

Returns true if the object is successfully unlocked; otherwise, returns false.

Parameters

key The key object previously assigned to lock the object.

Exceptions

NullPointerException if the key is null.


MultiComparison Class (com.ms.util Package)

 Microsoft SDK for Java

MultiComparison Class

The MultiComparison Class of the com.ms.util package provides a comparison based on an array of other comparisons. It enables you to specify a group of comparisons to be applied in priority order.

public final class MultiComparison implements Comparison
{
  // Constructors
  public MultiComparison(Comparison comparisons[]);
  public MultiComparison(Comparison comparisonA,
        Comparison comparisonB);

  // Methods
  public int compare(Object p, Object q)
}

The constructor takes an array of Comparison objects. When requested to preform a comparison of two objects through the compare method, the first comparison in the array is applied; if that comparison finds they are equal, the next comparison is called. This continues until either a comparison finds the objects to be different, or all comparisons have been called.


Constructors (MultiComparison Class)

 Microsoft SDK for Java

MultiComparison Class Constructors

The MultiComparison Class contains the following constructors:

MultiComparison(Comparison conparisons[])
MultiComparison(Comparison comparisonA, Comparison comparisonB)

MultiComparison(Comparison comparisons[])

Constructs a new MultiComparison object with the specified comparison array.

Syntax

public MultiComparison(Comparison comparisons[]);

Parameters

comparisons An array of Comparison objects.

MultiComparison(Comparison comparisonA, Comparison comparisonB)

Constructs a new MultiComparison with the specified comparisons.

Syntax

public MultiComparison(Comparison comparisonA, Comparison comparisonB);

Parameters

comparisonA | The first Comparison object in the comparison array.
comparisonB | The second Comparison object in the comparison array.


Methods (MultiComparison Class)

 Microsoft SDK for Java

MultiComparison Class Methods

The MultiComparison Class contains the following method:

compare compares the two objects according to the comparison array.


compare (MultiComparison Class)

 Microsoft SDK for Java

compare

This method of the MultiComparison Class compares the two objects according to the comparison array. The comparison terminates when one of the comparisons in the array determines that the objects are different.

Syntax

public int compare(Object p, Object q);

Return Value

Returns the result of the comparison.

Parameters

p | The first object to compare.
q | The second object to compare.


Queue Class (com.ms.util Package)

 Microsoft SDK for Java

Queue Class

The Queue Class of the com.ms.util package provides a queue, implemented in an array.

public class Queue implements java.util.Enumeration, Cloneable
{
  // Constructors
  public Queue();
  public Queue(int intialcapacity);
  public Queue(int intialcapacity, init growthfactor);

  // Methods
  public synchronized void addElement(Object newelt);
  public int capacity();
  protected Object clone() throws CloneNotSupportedEception;
  public synchronized Queue copy();
  public synchronized Object elementFromHead(int idx);
  public synchronized Object elementFromTail(int idx);
  public synchronized boolean hasMoreElements();
  public synchronized Object nextElement();
  public synchronized Object pop();
  public synchronized void removeAllElements();
  public synchronized int setCapacity(int newcapacity);
  public synchronized int size();
  public String toString();
}


Constructors (Queue Class)

 Microsoft SDK for Java

Queue Class Constructors

The Queue Class contains the following constructors:

Queue()
Queue(int initialcapacity)
Queue(int initialcapacity, int growthfactor)

Queue()

Constructs a queue with an initial capacity of 32 elements. When the queue is full, its size doubles.

Syntax

public Queue();

Queue(int initialcapacity)

Constructs a queue with the given initial capacity. When the queue is full, the capacity doubles in size.

Syntax

public Queue(int initialcapacity);

Parameters

initialcapacity The size of the queue to construct (the number of elements it will hold).

Queue(int initialcapacity, int growthfactor)

Constructs a queue with the given initial capacity and growth factor.

Syntax

public Queue(int initialcapacity, int growthfactor);

Parameters

initialcapacity | The initial size of the queue.
growthfactor | The factor to grow by when the queue is full. If the growth factor is 1, the queue will drop elements at its head as needed.


Methods (Queue Class)

 Microsoft SDK for Java

Queue Class Methods

The Queue Class contains the following methods:

addElement adds an element to the tail of the queue.
capacity obtains the maximum number of objects that the queue can contain without resizing.
clone creates a copy of the object.
copy duplicates the queue.
elementFromHead retrieves an element relative to the head of the queue.
elementFromTail retrieves an element relative to the tail of the queue.
hasMoreElements determines if the queue is empty.
nextElement removes an object from the head of the queue.
pop retrieves the element last added to the queue.
removeAllElements empties the queue.
setCapacity changes the queue's capacity.
size obtains the number of elements in the queue.
toString retrieves a string representation of the Queue object.


addElement (Queue Class)

 Microsoft SDK for Java

addElement

This method of the Queue Class adds an element to the tail of the queue.

Syntax

public synchronized void addElement(Object newelt);

Parameters

newelt The new element to add to the queue.

Remarks

The queue will grow, as necessary, by the factor provided when the queue was constructed. Null is a valid element to add.


capacity (Queue Class)

 Microsoft SDK for Java

capacity

This method of the Queue Class obtains the maximum number of objects that the queue can contain without resizing.

Syntax

public int capacity();

Return Value

Returns the maximum capacity (in objects) of the queue.


clone (Queue Class)

 Microsoft SDK for Java

clone

This method of the Queue Class creates a copy of the object.

Syntax

protected Object clone() throws CloneNotSupportedException;

Return Value

Returns a copy of the Queue object.

Exceptions

CloneNotSupportedException if the object cannot be copied.


copy (Queue Class)

 Microsoft SDK for Java

copy

This method of the Queue Class duplicates the queue.

Syntax

public synchronized Queue copy();

Return Value

Returns a copy of the Queue object.


elementFromHead (Queue Class)

 Microsoft SDK for Java

elementFromHead

This method of the Queue Class retrieves an element relative to the head of the queue.

Syntax

public synchronized Object elementFromHead(int idx);

Return Value

Returns the requested object.

Parameters

idx The offset from the first item in the queue.


elementFromTail (Queue Class)

 Microsoft SDK for Java

elementFromTail

This method of the Queue Class retrieves an element relative to the tail of the queue.

Syntax

public synchronized Object elementFromTail(int idx);

Return Value

Returns the requested object.

Parameters

idx The offset from the last item in the queue.


hasMoreElements (Queue Class)

 Microsoft SDK for Java

hasMoreElements

This method of the Queue Class determines if the queue is empty.

Syntax

public synchronized boolean hasMoreElements();

Return Value

Returns true if there are more elements in the queue; otherwise, returns false.


nextElement (Queue Class)

 Microsoft SDK for Java

nextElement

This method of the Queue Class removes an object from the head of the queue.

Syntax

public synchronized Object nextElement();

Return Value

Returns true if the object was successfully removed; otherwise, returns false.

Exceptions

NoSuchElementException if the queue is empty.


pop (Queue Class)

 Microsoft SDK for Java

pop

This method of the Queue Class retrieves the element last added to the queue.

Syntax

public synchronized Object pop();

Return Value

Returns the requested object.


removeAllElements (Queue Class)

 Microsoft SDK for Java

removeAllElements

This method of the Queue Class empties the queue.

Syntax

public synchronized void removeAllElements();


setCapacity (Queue Class)

 Microsoft SDK for Java

setCapacity

This method of the Queue Class changes the queue's capacity.

Syntax

public synchronized int setCapacity(int newcapacity);

Return Value

Returns the actual final capacity assigned to the queue.

Parameters

newcapacity The new number of elements in the queue.


size (Queue Class)

 Microsoft SDK for Java

size

This method of the Queue Class obtains the number of elements in the queue.

Syntax

public synchronized int size();

Return Value

Returns the size of the queue (in elements).


toString (Queue Class)

 Microsoft SDK for Java

toString

This method of the Queue Class retrieves a string representation of the Queue object.

Syntax

public String toString();

Return Value

Returns a string.


SetComparer Class (com.ms.util Package)

 Microsoft SDK for Java

SetComparer Class

The SetComparer Class of the com.ms.util package compares sets that cannot be subtracted or otherwise have no "inverse" operator.

public final class SetComparer
{
  // Methods
  public static int compareSets(ProvideSetComparisonInfo set1
        ProvideSetComparisonInfo set2);
}

The pseudo-set implements ProvideSetComparisonInfo and consists of two sets that together dictate membership.

The include set defines an enclosing set for all possible members of the set, and the exclude set defines members of the enclosing set that are removed.

Three basic operations are supported on the two sets using this class.

  1. intersection: Produces a set with only the common members of two sets.

  2. union: Produces a set with all the members of two sets.

  3. comparison: Compares two sets and returns a SetComparison result.

The compareSets operator method makes the assumption that is relatively inexpensive to compute and an intersection is relatively expensive. The include set is assumed to be an inclusive superset of the exclude set (otherwise, incorrect results might be returned). Because comparison is typically expensive, the invariant is not checked.


Methods (SetComparer Class)

 Microsoft SDK for Java

SetComparer Class Methods

The SetComparer Class contains the following method:

compareSets compares two set rules.


compareSets (SetComparer Class)

 Microsoft SDK for Java

compareSets

This method of the SetComparer Class compares two set rules.

Syntax

public static int compareSets(ProvideSetComparisonInfo set1, ProvideSetComparisonInfo set2);

Return Value

Returns a SetComparison.compareSet return code.

Parameters

set1 | A set rule.
set2 | A set rule.


Sort Class (com.ms.util Package)

 Microsoft SDK for Java

Sort Class

The Sort Class of the com.ms.util package implements an abstract sorting engine.

public abstract class Sort
{
  // Constructors
  protected Sort();
  protected void doSort(int lo, int size);

  // Methods
  protected int compare(int p, int q);
  protected void swap(int p, int q);
}

The Sort class is a base class for implementing container-specific sorts. For examples of subclasses of Sort, see com.ms.util.VectorSort or com.ms.util.Arraysort.


Constructors (Sort Class)

 Microsoft SDK for Java

Sort Class Constructors

The Sort Class contains the following constructors:

Sort()
doSort(int lo, int size)

Sort()

Constructs an instance of Sort.

Syntax

protected Sort();

doSort(int lo, int size)

Sorts a range of elements.

Syntax

protected void doSort(int lo, int size);

Parameters

lo | The index of the first element to be sorted.
size | The number of elements to be sorted.


Methods (Sort Class)

 Microsoft SDK for Java

Sort Class Methods

The Sort Class contains the following methods:

compare is called when the sorting engine must compare two elements.
swap is called when the sorting engine must swap two elements.


compare (Sort Class)

 Microsoft SDK for Java

compare

This method of the Sort Class is called when the sorting engine must compare two elements. Subclasses override this method in a container-specific manner.

Syntax

protected int compare(int p, int q);

Return Value

Returns an integer describing the relationship of the elements.

If Sort returns less than a 0, place element p before element q in the sort.

If Sort returns greater than 0, place element p after element q.

If Sort returns 0, elements p and q are equivelent.

Parameters

p | The index of the first operand of the comparison.
q | The index of the second operand of the comparison.


swap (Sort Class)

 Microsoft SDK for Java

swap

This method of the Sort Class is called when the sorting engine must swap two elements. Subclasses override this method in a container-specific manner.

Syntax

protected void swap(int p, int q);

Parameters

p | The index of the first operand of the swap operation.
q | The index of the second operand of the swap operation.


StringComparison Class (com.ms.util Package)

 Microsoft SDK for Java

StringComparison Class

The StringComparison Class of the com.ms.util package provides a simple comparison, similar to that done by String.compareTo.

public final class StringComparison implements Comparison
{
  // Constructors
  public static final Comparison ascending = new StringComparison(
        1);
  public static final Comparison descending = new StringComparison(
        -1);

  // Methods
  public int compare(Object p, Object q);
}

Example

Given an array of strings like the following:

  String strings[] = new String[4];
  strings[0]="my";
  strings[1]="dog";
  strings[2]="has";
  strings[3]="fleas";

A sort could be performed with the following code:

ArraySort.sort(strings, StringComparison.ascending);


Constructors (StringComparison Class)

 Microsoft SDK for Java

StringComparison Class Constructors

The StringComparison Class contains the following constructors:

StringComparison(1)
StringComparison(-1)

StringComparison(1)

Specifies an ascending string comparison. This compares according to String.compareTo.

Syntax

public static final Comparison ascending = new StringComparison(1);

StringComparison(-1)

Specifies a descending string comparison. This compares according to the inverse of String.compareTo.

Syntax

public static final Comparison descending = new StringComparison(-1);


Methods (StringComparison Class)

 Microsoft SDK for Java

StringComparison Class Methods

The StringComparison Class contains the following method:

compare compares the two objects.


compare (StringComparison Class)

 Microsoft SDK for Java

compare

This method of the StringComparison Class compares the two objects.

Syntax

public int compare(Object p, Object q);

Return Value

Returns the result of the comparison.

Parameters

p | The first operand of the comparison.
q | The second operand of the comparison.

Remarks

If both objects are instances of the String class, String.compareTo is called. If neither object is a String object, zero is returned. If one of the objects is a String, it is treated as lexicographically preceding the non-String object. This method must be addressed as ascend.compare or decend.compare.


SystemVersionManager Class (com.ms.util Package)

 Microsoft SDK for Java

SystemVersionManager Class

The SystemVersionManager Class of the com.ms.util package provides methods that set and retrieve system version properties.

public class SystemVersionManager implements Runnable
{
  // Methods
  public static Properties createVersion(int major, int minor, int
        buildnum, int buildinc, String description);
  public static Enumeration enumerate();
  public static Properties getPackageVersion(String pkgname);
  public static Properties getSystemComponentVersion(
        String compname);
  public static Properties getVMVersion();
  public void run();
}

Typically, this class is not called directly. Rather, it is used by implementing a VersionManager class that is derived from it. For a standard implementation of a VersionManager class, see AFCVersionManager in the Samples\Afc\AFCDetect directory of the Microsoft SDK for Java. This class can be added, without editing, directly to your distributed packages, which allows applications to check the version information of your distributed classes.

You can request a package by name by using the getPackageVersion method. This method searches for the information in a Version (*.Version) class in the requested package or a superpackage. The version information is in a Properties object. All version objects have the following keys:

  1. MajorVersion

  2. MinorVersion

  3. BuildNumber

  4. BuildIncrement

  5. Description

All values are stored as instances of Strings. You can also use getSystemComponentVersion to request information about the following components:

  1. VM

  2. Classes

  3. TrustedClasses


Methods (SystemVersionManager Class)

 Microsoft SDK for Java

SystemVersionManager Class Methods

The SystemVersionManager Class contains the following methods:

createVersion creates a version object.
enumerate retrieves the default system components that are provided with the version information.
getPackageVersion retrieves the version information for the specified package.
getSystemComponentVersion retrieves the component version information.
getVMVersion retrieves version data for the virtual machine (VM).
run runs when the thread originating in SystemVersionManager getSystemComponentVersion is started.


createVersion (SystemVersionManager Class)

 Microsoft SDK for Java

createVersion

This method of the SystemVersionManager Class creates a version object.

Syntax

public static Properties createVersion(int major, int minor, int buildnum, int buildinc, String description);

Return Value

Returns a Property object that contains the version properties.

Parameters

major | The major version number.
minor | The minor version number.
buildnum | The build number.
buildinc | The incremental build number.
description | The string description of the version.


enumerate (SystemVersionManager Class)

 Microsoft SDK for Java

enumerate

This method of the SystemVersionManager Class retrieves the default system components that are provided with the version information.

Syntax

public static Enumeration enumerate();

Return Value

Returns an Enumeration object that contains the following String objects.

VM | The VM version.
Classes | The version of the system classes.
TrustedClasses | The version of the classes in the TrustedLib path.


getPackageVersion (SystemVersionManager Class)

 Microsoft SDK for Java

getPackageVersion

This method of the SystemVersionManager Class retrieves the version information for the specified package.

Syntax

public static Properties getPackageVersion(String pkgname);

Return Value

Returns a Properties object that contains the package version data.

Parameters

pkgname The name of the package.


getSystemComponentVersion (SystemVersionManager Class)

 Microsoft SDK for Java

getSystemComponentVersion

This method of the SystemVersionManager Class retrieves the component version information.

Syntax

public static Properties getSystemComponentVersion(String compname);

Return Value

Returns a Properties object that contains the version information.

Parameters

compname The system component name, which can be one of the components returned by the enumerate method.


getVMVersion (SystemVersionManager Class)

 Microsoft SDK for Java

getVMVersion

This method of the SystemVersionManager Class retrieves version data for the virtual machine (VM).

Syntax

public static Properties getVMVersion();

Return Value

Returns a Properties object that contains the VM version data.


run (SystemVersionManager Class)

 Microsoft SDK for Java

run

This method of the SystemVersionManager Class runs when the thread originating in SystemVersionManager getSystemComponentVersion is started.

Syntax

public void run();

Remarks

This method retrieves the value of the ClassesBuild string in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Java VM registry key.


Task Class (com.ms.util Package)

 Microsoft SDK for Java

Task Class

The Task Class of the com.ms.util package schedules and manages the execution of runnable objects in the global task manager.

public class Task
{
  // Methods
  public static boolean cancel(int id);
  public static int schedule(Runnable runnable);
  public static int schedule(Runnable runnable, long when);
  public static int schedule(Runnable runnable, long when
        boolean lightweight);
}


Methods (Task Class)

 Microsoft SDK for Java

Task Class Methods

The Task Class contains the following methods:

cancel cancels a pending runnable object.
schedule schedules a runnable object to run immediately in the global task manager as a lightweight task.


cancel (Task Class)

 Microsoft SDK for Java

cancel

This method of the Task Class cancels a pending runnable object.

Syntax

public static boolean cancel(int id);

Return Value

Returns true if the runnable object was cancelled successfully; returns false if the task was already run or had never been scheduled.

Parameters

id An integer that identifies the task.


schedule (Task Class)

 Microsoft SDK for Java

schedule

The schedule method of the Task Class contains the following signatures:

schedule(Runnable runnable)
schedule(Runnable runnable, long when)
schedule(Runnable runnable, long when boolean lightweight)

schedule(Runnable runnable)

Schedules a runnable object to run immediately in the global task manager as a lightweight task.

Syntax

public static int schedule(Runnable runnable);

Return Value

Returns a non-zero integer that identifies the task.

Parameters

runnable The object scheduled to run.

schedule(Runnable runnable, long when)

Schedules a runnable object to run in the global task manager at the specified time as a lightweight task.

Syntax

public static int schedule(Runnable runnable, long when);

Return Value

Returns a non-zero integer that identifies the task.

Parameters

runnable | The object that is run.
when | The time at which the object is run.

schedule(Runnable runnable, long when, boolean lightweight)

Schedules a runnable object to run in the global task manager at the specified time, and optionally as a lightweight task or not.

Syntax

Public static int schedule(Runnable runnable, long when, boolean lightweight);

Return Value

Returns a non-zero integer that identifies the task.

Parameters

runnable | The object that runs.
when | The time at which the object runs.
lightweight | Set to true to run the task as a lightweight task; false, otherwise.


TaskManager Class (com.ms.util Package)

 Microsoft SDK for Java

TaskManager Class

The TaskManager Class of the com.ms.util package schedules or manages the execution of runnable objects.

public class TaskManager implements Runnable
{
  // Constructors
  public TaskManager(ThreadGroup threadGroup);
  public TaskManager(ThreadGroup threadGroup
        boolean runTasksAsDaemons);

  // Methods
  public synchronized boolean cancel(int id);
  public static TaskManager global();
  public void run();
  public int schedule(Runnable runnable);
  public int schedule(Runnable runnable, long when);
  public synchronized int schedule(Runnable runnable, long when,
        boolean lightweight);
}


Constructors (TaskManager Class)

 Microsoft SDK for Java

TaskManager Class Constructors

The TaskManager Class contains the following constructors:

TaskManager(ThreadGroup threadGroup)
TaskManager(ThreadGroup threadGroup, boolean runTasksAsDaemons)

TaskManager(ThreadGroup threadGroup)

Constructs a new TaskManager object.

Syntax

public TaskManager(ThreadGroup threadGroup);

Parameters

threadGroup The thread group that the task manager creates threads in.

TaskManager(ThreadGroup threadGroup, boolean runTasksAsDaemons)

Constructs a new TaskManager object.

Syntax

public TaskManager(ThreadGroup threadGroup, boolean runTasksAsDaemons);

Parameters

threadGroup | The thread group that the task manager creates threads in.
runTasksAsDaemons | Set to true if the tasks in this task manager are to run on daemon threads; otherwise, set to false.


Methods (TaskManager Class)

 Microsoft SDK for Java

TaskManager Class Methods

The TaskManager Class contains the following methods:

cancel cancels a pending runnable object.
global retrieves the global task manager.
run is called when the thread is started.
schedule schedules a runnable object to run immediately.


cancel (TaskManager Class)

 Microsoft SDK for Java

cancel

This method of the TaskManager Class cancels a pending runnable object.

Syntax

public synchronized boolean cancel(int id);

Return Value

Returns true if the runnable object was cancelled successfully; returns false if the task was already run or had never been scheduled.

Parameters

id An integer that identifies the task.


global (TaskManager Class)

 Microsoft SDK for Java

global

This method of the TaskManager Class retrieves the global task manager.

Syntax

public static TaskManager global();

Return Value

Returns the global TaskManager object.


run (TaskManager Class)

 Microsoft SDK for Java

run

This method of the TaskManager Class is called when the thread is started.

Syntax

public void run();


schedule (TaskManager Class)

 Microsoft SDK for Java

schedule

The schedule method of the TaskManager Class contains the following signatures:

schedule(Runnable runnable)
schedule(Runnable runnable, long when)
schedule(Runnable runnable, long when, boolean lightweight)

schedule(Runnable runnable)

Schedules a runnable object to run immediately.

Syntax

public int schedule(Runnable runnable);

Return Value

Returns a non-zero integer that identifies the task.

Parameters

runnable The object that is run.

schedule(Runnable runnable, long when)

Schedules a runnable object to run at a specified time.

Syntax

public int schedule(Runnable runnable, long when);

Return Value

Returns a non-zero integer that identifies the task.

Parameters

runnable | The object that is run.
long | The time at which the object is to start.

schedule(Runnable runnable, long when, boolean lightweight)

Schedules a runnable object to run at a specified time.

Syntax

public synchronized int schedule(Runnable runnable, long when, boolean lightweight);

Return Value

Returns a non-zero integer that identifies the task.

Parameters

runnable | The object that is run.
when | The time at which the object is run.
lightweight | Set to true to run the task as a lightweight task.


ThreadLocalStorage Class (com.ms.util Package)

 Microsoft SDK for Java

ThreadLocalStorage Class

The ThreadLocalStorage Class of the com.ms.util package allows applications to store a per-thread reference to a Java object.

public class ThreadLocalStorage
{
  // Constructors
  public ThreadLocalStorage();

  // Methods
  protected void finalize();
  public Object get();
  public void release();
  public void set(Object obj);
}

Remarks

The ThreadLocalStorage class was added as of versions 2437 through 2925 of the Microsoft virtual machine.


Constructors (ThreadLocalStorage Class)

 Microsoft SDK for Java

ThreadLocalStorage Class Constructors

The ThreadLocalStorage Class contains the following constructor:

ThreadLocalStorage()

Creates a new per-thread storage object for application use.

Syntax

public ThreadLocalStorage();


Methods (ThreadLocalStorage Class)

 Microsoft SDK for Java

ThreadLocalStorage Class Methods

The ThreadLocalStorage Class contains the following methods:

finalize performs cleanup tasks before garbage collection.
get retrieves the per-thread object stored in this storage object.
release destroys the storage object.
set stores a specified per-thread object in the storage object.


finalize (ThreadLocalStorage Class)

 Microsoft SDK for Java

finalize

This method of the ThreadLocalStorage Class performs cleanup tasks before garbage collection.

Syntax

protected void finalize();


get (ThreadLocalStorage Class)

 Microsoft SDK for Java

get

This method of the ThreadLocalStorage Class retrieves the per-thread object stored in this storage object.

Syntax

public Object get();

Return Value

Returns the per-thread object stored in this storage object.


release (ThreadLocalStorage Class)

 Microsoft SDK for Java

release

This method of the ThreadLocalStorage Class destroys the storage object. The finalize method will perform this task for you, but because storage objects are scarce resources, you should use this method to release them in a timely manner.

Syntax

public void release();


set (ThreadLocalStorage Class)

 Microsoft SDK for Java

set

This method of the ThreadLocalStorage Class stores a specified per-thread object in the storage object.

Syntax

public void set(Object obj);

Parameters

obj The new object to store.


Timer Class (com.ms.util Package)

 Microsoft SDK for Java

Timer Class

The Timer Class of the com.ms.util package implements a timer event source.

public class Timer
{
  // Constructors
  public Timer(long p);
  public Timer(long p, int id);
  public Timer(long p, boolean r);
  public Timer(long p, int id boolean r);
  public Timer(TimerListener defaultListener, long p);
  public Timer(TimerListener defaultListener, long p, int id);
  public Timer(TimerListener defaultListener, long p, boolean r);
  public Timer(TimerListener defaultListener, long p, int id,
        boolean r);
  public Timer(TaskManager tm, long p);
  public Timer(TaskManager tm, long p, int id);
  public Timer(TaskManager tm, long p, boolean r);
  public Timer(TaskManager tm, long pint id, boolean r);
  public Timer(TaskManager tm, TimeListener defaultListener,
        long p);
  public Timer(TaskManager tm, TimeListener defaultListener
        long p, int id);
  public Timer(TaskManager tm, TimeListener defaultListener
        long p, boolean r);
  public Timer(TaskManager tm, TimeListener defaultListener
        long p, int id, boolean r);

  // Methods
  public void addTimerListener(TimerListener listener);
  public long getPeriod();
  public boolean getRepeat();
  public int getUserID();
  public boolean isRunning();
  public void removeTimerListener(TimerListener listener);
  public void start();
  public void stop();
}


Constructors (Timer Class)

 Microsoft SDK for Java

Timer Class Constructors

The Timer Class contains the following constructors:

Timer(long p)
Timer(long p, int id)
Timer(long p, boolean r)
Timer(long p, int id, boolean r)
Timer(TimerListener defaultListener, long p)
Timer(TimerListener defaultListener, long p, int id)
Timer(TimerListener defaultListener, long p, boolean r)
Timer(TimerListener defaultListener, long p, int id, boolean r)
Timer(TaskManager tm, long p)
Timer(TaskManager tm, long p, int id)
Timer(TaskManager tm, long p, boolean r)
Timer(TaskManager tm, long p, int id, boolean r)
Timer(TaskManager tm, TimerListener defaultListener, long p)
Timer(TaskManager tm, TimerListener defaultListener, long p, int id)
Timer(TaskManager tm, TimerListener defaultListener, long p, boolean r)
Timer(TaskManager tm, TimerListener defaultListener, long p, int id, boolean r)

Timer(long p)

Constructs a one-shot timer with the specified period (in milliseconds).

Syntax

public Timer(long p);

Parameters

p The initial period of the timer.

Timer(long p, int id)

Constructs a one-shot timer with a specific period (in milliseconds) and that includes a user-defined identifier.

Syntax

public Timer(long p, int id);

Parameters

p | The initial period of the timer.
id | The user-defined identifier of the timer.

Timer(long p, boolean r)

Constructs a one-shot or repeating timer with the specified period (in milliseconds).

Syntax

public Timer(long p, boolean r);

Parameters

p | The initial period of the timer.
r | Set to true if the timer is a repeating timer or false if it is a one-shot timer.

Timer(long p, int id, boolean r)

Constructs a one-shot or repeating timer with the specified period (in milliseconds).

Syntax

public Timer(long p, int id, boolean r);

Parameters

p | The initial period of the timer.
id | The user-defined identifier for the timer.
r | Set to true if the timer is a repeating timer; set to false if it is a one-shot timer.

Timer(TimerListener defaultListener, long p)

Constructs a one-shot timer with the specified period (in milliseconds) and that includes a default listener.

Syntax

public Timer(TimerListener defaultListener, long p);

Parameters

defaultListener | The initial listener to add to the timer.
p | The initial period of the timer.

Timer(TimerListener defaultListener, long p, int id)

Constructs a one-shot timer with the specified period (in milliseconds) and listener.

Syntax

public Timer(TimerListener defaultListener, long p, int id);

Parameters

defaultListener | The initial listener to add to the timer.
p | The initial period of the timer.
id | The user-defined identifier of the timer.

Timer(TimerListener defaultListener, long p, boolean r)

Constructs a one-shot or repeating timer with the specified period (in milliseconds) and that includes a default listener.

Syntax

public Timer(TimerListener defaultListener, long p, boolean r);

Parameters

defaultListener | The initial listener to add to the timer.
p | The initial period of the timer.
r | Set to true if the timer is a repeating timer; set to false if it is a one-shot timer.

Timer(TimerListener defaultListener, long p, int id, boolean r)

Constructs a one-shot or repeating timer with the specified period (in milliseconds) and a default listener.

Syntax

public Timer(TimerListener defaultListener, long p, int id, boolean r);

Parameters

defaultListener | An initial listener to add to the timer.
id | A user-defined identifier for the listener.
p | The initial period of the timer.
r | Set to true if the timer is a repeating timer; set to false if it is a one-shot timer.

Timer(TaskManager tm, long p)

Constructs a one-shot timer with the specified period.

Syntax

public Timer(TaskManager tm, long p);

Parameters

tm | The TaskManager that is to service this Timer.
p | The initial period of the timer (in milliseconds).

Timer(TaskManager tm, long p, int id)

Constructs a one-shot timer with a specific period and that includes a user-defined identifier.

Syntax

public Timer(TaskManager tm, long p, int id);

Parameters

tm | The TaskManager that is to service this Timer.
p | The initial period of the timer (in milliseconds).
id | The user-defined identifier of the timer.

Timer(TaskManager tm, long p, boolean r)

Constructs a one-shot or repeating timer with the specified period.

Syntax

public Timer(TaskManager tm, long p, boolean r);

Parameters

tm | The task manager that is to service this timer.
p | The initial period of the timer (in milliseconds).
r | Set to true if the timer is a repeating timer or false if it is a one-shot timer.

Timer(TaskManager tm, long p, int id, boolean r)

Constructs a one-shot or repeating timer with the specified period.

Syntax

public Timer(TaskManager tm, long p, int id, boolean r);

Parameters

tm | The task manager that is to service this timer.
p | The initial period of the timer (in milliseconds).
id | The user-defined identifier for the timer.
r | Set to true if the timer is a repeating timer; set to false if it is a one-shot timer.

Timer(TaskManager tm, TimerListener defaultListener, long p)

Constructs a one-shot timer with the specified period and that includes a default listener.

Syntax

public Timer(TaskManager tm, TimerListener defaultListener, long p);

Parameters

tm | The task manager that is to service this timer.
defaultListener | The initial listener to add to the timer.
p | The initial period of the timer.

Timer(TaskManager tm, TimerListener defaultListener, long p, int id)

Constructs a one-shot timer with the specified period and listener.

Syntax

public Timer(TaskManager tm, TimerListener defaultListener, long p, int id);

Parameters

tm | The task manager that is to service this timer.
defaultListener | The initial listener to add to the timer.
p | The initial period of the timer.
id | The user-defined identifier of the timer.

Timer(TaskManager tm, TimerListener defaultListener, long p, boolean r)

Constructs a one-shot or repeating timer with the specified period and that includes a default listener.

Syntax

public Timer(TaskManager tm, TimerListener defaultListener, long p, boolean r);

Parameters

tm | The task manager that is to service this timer.
defaultListener | The initial listener to add to the timer.
p | The initial period of the timer.
r | Set to true if the timer is a repeating timer; set to false if it is a one-shot timer.

Timer(TaskManager tm, TimerListener defaultListener, long p, int id, boolean r)

Constructs a one-shot or repeating timer with the specified period and a default listener.

Syntax

public Timer(TaskManager tm, TimerListener defaultListener, long p, int id, boolean r);

Parameters

tm | The task manager that is to service this timer.
defaultListener | An initial listener to add to the timer.
id | A user-defined identifier for the listener.
p | The initial period of the timer.
r | Set to true if the timer is a repeating timer; set to false if it is a one-shot timer.


Methods (Timer Class)

 Microsoft SDK for Java

Timer Class Methods

The Timer Class contains the following methods:

addTimerListener adds a listener to the timer.
getPeriod retrieves the timer period.
getRepeat retrieves the timer repeat flag.
getUserID retrieves the timer's user-defined identifier.
isRunning queries the Timer to see if it is running.
removeTimerListener removes a listener from the timer.
start starts the timer.
stop stops the timer.


addTimerListener (Timer Class)

 Microsoft SDK for Java

addTimerListener

This method of the Timer Class adds a listener to the timer.

Syntax

public void addTimerListener(TimerListener listener);

Parameters

listener The listener that is added to the timer.


getPeriod (Timer Class)

 Microsoft SDK for Java

getPeriod

This method of the Timer Class retrieves the timer period.

Syntax

public long getPeriod();

Return Value

Returns the number of milliseconds that must elapse before the timer fires.


getRepeat (Timer Class)

 Microsoft SDK for Java

getRepeat

This method of the Timer Class retrieves the timer repeat flag.

Syntax

public boolean getRepeat();

Return Value

Returns true if the timer is a repeating timer; otherwise, returns false.


getUserID (Timer Class)

 Microsoft SDK for Java

getUserID

This method of the Timer Class retrieves the timer's user-defined identifier.

Syntax

public int getUserID();

Return Value

Returns the integer identifier of the timer.


isRunning (Timer Class)

 Microsoft SDK for Java

isRunning

This method of the Timer Class queries the Timer to see if it is running.

Syntax

public boolean isRunning();

Return Value

Returns true if the timer is running; otherwise, returns false.


removeTimerListener (Timer Class)

 Microsoft SDK for Java

removeTimerListener

This method of the Timer Class removes a listener from the timer.

Syntax

public void removeTimerListener(TimerListener listener);

Parameters

listener The listener that is removed.

Remarks

This method prevents future listener timer events from being generated. However, timer events that have already been generated can be delivered to listeners.


start (Timer Class)

 Microsoft SDK for Java

start

This method of the Timer Class starts the timer. If the timer is already running, calls to this method are ignored.

Syntax

public void start();


stop (Timer Class)

 Microsoft SDK for Java

stop

This method of the Timer Class stops the timer. If the timer is not running, calls to this method are ignored.

Syntax

public void stop();

Remarks

This method prevents future listener timer events from being generated. However, timer events that have already been generated can be delivered to listeners.


TimerEvent Class (com.ms.util Package)

 Microsoft SDK for Java

TimerEvent Class

The TimerEvent Class of the com.ms.util package identifies the expiration of a Timer.

public class TimerEvent
{
  // Methods
  public Object getSource();
  public long getTime();
  public int getUserID();
  public String toString();
}


Methods (TimerEvent Class)

 Microsoft SDK for Java

TimerEvent Class Methods

The TimerEvent Class contains the following methods:

getSource retrieves the event source.
getTime retrieves the time at which the timer expires.
getUserID retrieves the timer's user-defined identifier.
toString retrieves a string object that describes the timer event.


getSource (TimerEvent Class)

 Microsoft SDK for Java

getSource

This method of the TimerEvent Class retrieves the event source.

Syntax

public Object getSource();

Return Value

Returns the source object for the event.


getTime (TimerEvent Class)

 Microsoft SDK for Java

getTime

This method of the TimerEvent Class retrieves the time at which the timer expires.

Syntax

public long getTime();

Return Value

Returns the time at which the timer expires.


getUserID (TimerEvent Class)

 Microsoft SDK for Java

getUserID

This method of the TimerEvent Class retrieves the timer's user-defined identifier.

Syntax

public int getUserID();

Return Value

Returns the integer identifier of the timer.


toString (TimerEvent Class)

 Microsoft SDK for Java

toString

This method of the TimerEvent Class retrieves a string object that describes the timer event.

Syntax

public String toString();

Return Value

Returns a string object that describes the timer event.


UnsignedIntRanges Class (com.ms.util Package)

 Microsoft SDK for Java

UnsignedIntRanges Class

The UnsignedIntRanges Class of the com.ms.util package shifts unsigned numbers to the range of signed numbers.

public class UnsignedIntRanges extends IntRanges
{
  // Constructors
  public UnsignedIntRanges();
  public UnsignedIntRanges(String str);
  public UnsignedIntRanges(String str, String delims);

  // Methods
  public synchronized void addRange(int s, int e);
  public synchronized void addRanges(IntRanges r);
  public synchronized void addSingleton(int n);
  public StringBuffer appendToStringBuffer(StringBuffer sb);
  public boolean contains(int find);
  public int getRangeEnd(int idx);
  public int getRangeStart(int idx);
  public int indexOf(inf find, int fromRange);
  public int indexOf(int find);
  public UnsignedIntRanges intersect(UnsignedIntRanges other,
        IIntRangeComparator judge);
  public IntRanges intersect(IntRanges other, IntRangesComparator judge);
  public UnsignedIntRanges intersect(UnsignedIntRanges other);
  public boolean removeRange(int s, int e
        IIntRangeComparator hook);
}

Those familiar with the IntRanges class should be aware that IntRanges.getRanges and IntRanges.setRanges are not converted by this derived class.

Hierarchy

IntRanges
  |
  +--UnsignedIntRanges


Constructors (UnsignedIntRanges Class)

 Microsoft SDK for Java

UnsignedIntRanges Class Constructors

The UnsignedIntRanges Class contains the following constructors:

UnsignedIntRanges()
UnsignedIntRanges(String str)
UnsignedIntRanges(String str, String delims)

UnsignedIntRanges()

Creates an UnsignedIntRanges object.

Syntax

public UnsignedIntRanges();

UnsignedIntRanges(String str)

Constructs a set of ranges from the given string. This method simply calls the superclass.

Syntax

public UnsignedIntRanges(String str);

Parameters

str A string containing ranges of unsigned integers (in hexadecimal), where the bounds of each range are separated by a hyphen (-), and separate ranges are delimited by commas.

A range of a single unsigned integer can be entered by including just the single unsigned integer, separated by delimiters.

UnsignedIntRanges(String str, String delims)

Constructs a set of ranges from the given string with specified delimiters. This method simply calls the superclass.

Syntax

public UnsignedIntRanges(String str, String delims)

Parameters

str | A string containing ranges of unsigned integers (in hexadecimal), where the bounds of each range are separated by a hyphen (-). A range of a single unsigned integer can be entered by including just the single unsigned integer, separated by delimiters.
delims | The character or characters separating ranges.


Methods (UnsignedIntRanges Class)

 Microsoft SDK for Java

UnsignedIntRanges Class Methods

The UnsignedIntRanges Class contains the following methods:

addRange adds a range of unsigned integers to the UnsignedIntRanges object.
addRanges adds a set of ranges to this set of ranges.
addSingleton adds a range of a single, unsigned integer to the UnsignedIntRanges object.
appendToStringBuffer appends a string representation of the unsigned integer ranges to a given string buffer.
contains searches from the beginning for a given number.
getRangeEnd retrieves the end of a range at a specified index.
getRangeStart retrieves the start of a range at a specified index.
indexOf searches from a starting index for a range pair containing a given a number.
intersect constructs a new IntRanges object with the set of integers that are common to both this object and another object.
removeRange removes a range of integers from the UnsignedIntRanges object.


addRange (UnsignedIntRanges Class)

 Microsoft SDK for Java

addRange

This method of the UnsignedIntRanges Class adds a range of unsigned integers to the UnsignedIntRanges object.

Syntax

public synchronized void addRange(int s, int e);

Parameters

s | The lower limit of the range.
e | The upper limit of the range.

Overrides

addRange(int,int) in IntRanges.


addRanges (UnsignedIntRanges Class)

 Microsoft SDK for Java

addRanges

This method of the UnsignedIntRanges Class adds a set of ranges to this set of ranges.

Syntax

public synchronized void addRanges(IntRanges r);

Parameters

r An IntRanges object to add to this UnsignedIntRanges object.

Overrides

addRanges(IntRanges) in IntRanges.


addSingleton (UnsignedIntRanges Class)

 Microsoft SDK for Java

addSingleton

This method of the UnsignedIntRanges Class adds a range of a single, unsigned integer to the UnsignedIntRanges object.

Syntax

public synchronized void addSingleton(int n);

Parameters

n The integer range.

Overrides

addSingleton(int) in IntRanges.


appendToStringBuffer (UnsignedIntRanges Class)

 Microsoft SDK for Java

appendToStringBuffer

This method of the UnsignedIntRanges Class appends a string representation of the unsigned integer ranges to a given string buffer. The unsigned integers are represented in hexadecimal.

Syntax

public StringBuffer appendToStringBuffer(StringBuffer sb);

Return Value

Returns a string buffer containing the concatenated strings.

Parameters

sb The StringBuffer to append the set of unsigned integer range pairs to.

Overrides

appendToStringBuffer(StringBuffer) in IntRanges.


contains (UnsignedIntRanges Class)

 Microsoft SDK for Java

contains

This method of the UnsignedIntRanges Class searches from the beginning for a given number.

Syntax

public boolean contains(int find);

Return Value

Returns true if the number was found; otherwise, returns false.

Parameters

find The number to search for.

Overrides

contains(int) in IntRanges.


getRangeEnd (UnsignedIntRanges Class)

 Microsoft SDK for Java

getRangeEnd

This method of the UnsignedIntRanges Class retrieves the end of a range at a specified index.

Syntax

public int getRangeEnd(int idx);

Return Value

Returns the last integer of the range pair.

Parameters

idx The index of the range pair.

Overrides

getRangeEnd(int) in IntRanges.


getRangeStart (UnsignedIntRanges Class)

 Microsoft SDK for Java

getRangeStart

This method of the UnsignedIntRanges Class retrieves the start of a range at a specified index.

Syntax

public int getRangeStart(int idx);

Return Value

Returns the first integer of the range pair.

Parameters

idx The index of the range pair.

Overrides

getRangeStart(int) in IntRanges.


indexOf (UnsignedIntRanges Class)

 Microsoft SDK for Java

indexOf

The indexOf method of the UnsignedIntRanges Class contains the following signatures:

indexOf(int find, int fromRange)
indexOf(int find)

indexOf(int find, int fromRange)

Searches from a starting index for a range pair containing a given a number.

Syntax

public int indexOf(int find, int fromRange);

Return Value

Returns the index of the range pair that includes the number, if found; otherwise, returns -1.

Parameters

find | The number to search for.
fromRange | The index of the range pair to start the search from.

Overrides

indexOf(int,int) in IntRanges.

indexOf(int find)

Searches from the beginning for a range pair containing a given a number.

Syntax

public int indexOf(int find);

Return Value

Returns the index of the range pair that includes the number, if found; otherwise, returns -1.

Parameters

find The number to search for.

Overrides

indexOf(int) in IntRanges.


intersect (UnsignedIntRanges Class)

 Microsoft SDK for Java

intersect

The intersect method of the UnsignedIntRanges Class contains the following signatures:

intersect(IntRanges other, IIntRangeComparator judge)
intersect(UnsignedIntRanges other, IIntRangeComparator judge)
intersect(UnsignedIntRanges other)

intersect(UnsignedIntRanges other, IIntRangeComparator judge)

Constructs a new UnsignedIntRanges object with the set of unsigned integers that are common to both this object and another object.

Syntax

public UnsignedIntRanges intersect(UnsignedIntRanges other, IIntRangeComparator judge);

Return Value

Returns an UnsignedIntRanges object for the intersection of this object and other.

Parameters

other | The other UnsignedIntRanges object to find intersection with.
judge | The hook interface to notify through IIntRangeComparator.intersectRanges of intersecting ranges that will be added to the new UnsignedIntRanges object.

intersect(IntRanges other, IIntRangeComparator judge)

Constructs a new IntRanges object with the set of integers that are common to both this object and another object.

Syntax

public IntRanges intersect(IntRanges other, IIntRangeComparator judge);

Return Value

Returns an IntRanges object for the intersection of this object and the IntRanges object contained in the other parameter.

Parameters

other | The other IntRanges object to find an intersection with.
judge | The hook interface to notify through IIntRangeComparator.intersectRanges of intersecting ranges that will be added to the new IntRanges object.

intersect(UnsignedIntRanges other)

Retrieves the intersection of this set of unsigned integer ranges with another.

Syntax

public UnsignedIntRanges intersect(UnsignedIntRanges other);

Return Value

Returns the intersection as a set of unsigned integer ranges.

Parameters

other The set of unsigned integer ranges to compare.


removeRange (UnsignedIntRanges Class)

 Microsoft SDK for Java

removeRange

This method of the UnsignedIntRanges Class removes a range of integers from the UnsignedIntRanges object.

Syntax

public boolean removeRange(int s, int e, IIntRangeComparator hook);

Return Value

Returns true if any integers in the range were removed; otherwise, false if the set contains no integers in the range.

Parameters

s | The lower limit of the range.
e | The upper limit of the range.
hook | The interface to notify through IIntRangeComparator.shiftRanges that the ranges were deleted or IIntRangeComparator that a range was split.


VectorSort Class (com.ms.util Package)

 Microsoft SDK for Java

VectorSort Class

The VectorSort Class of the com.ms.util package sorts the specified Vector object using the specified Comparison.

public class VectorSort extends Sort
{
  // Methods
  protected int compare(int p, int q);
  static public void sort(Vector vector,Comparison comparison);
  static public void sort(Vector vector,Comparison comparison, int
        first, int size);
  protected void swap(int p, int q);
}

Hierarchy

Sort
  |
  +--VectorSort


Methods (VectorSort Class)

 Microsoft SDK for Java

VectorSort Class Methods

The VectorSort Class contains the following methods:

compare compares two elements in the vector using the Comparison object.
sort sorts the specified Vector object using the specified Comparison object.
swap swaps two elements in the vector.


compare (VectorSort Class)

 Microsoft SDK for Java

compare

This method of the VectorSort Class compares two elements in the vector using the Comparison object.

Syntax

protected int compare(int p, int q);

Return Value

Returns the result of the comparison.

Parameters

p | The index of the first operand of the comparison.
q | The index of the second operand of the comparison.

Overrides

compare(int,int) in Sort.


sort (VectorSort Class)

 Microsoft SDK for Java

sort

The sort method of the VectorSort Class contains the following signatures:

sort(Vector vector,Comparison comparison)
sort(Vector vector,Comparison comparison, int first, int size)

sort(Vector vector, Comparison comparison)

Sorts the specified Vector object using the specified Comparison object.

Syntax

static public void sort(Vector vector, Comparison comparison);

Parameters

vector | The Vector object to be sorted.
comparison | The Comparison object to use.

sort(Vector vector, Comparison comparison, int first, int size)

Sorts a subrange of the specified Vector object using the specified Comparison object.

Syntax

static public void sort(Vector vector, Comparison comparison, int first, int size);

Parameters

vector | The Vector object to be sorted.
comparison | The Comparison object to use.
first | The index of the beginning element of the subrange to sort.
size | The number of elements of the subrange to sort.


swap (VectorSort Class)

 Microsoft SDK for Java

swap

This method of the VectorSort Class swaps two elements in the vector.

Syntax

protected void swap(int p, int q);

Parameters

p | The index of the first operand of the swap operation.
q | The index of the second operand of the swap operation.

Overrides

swap(int,int) in Sort


WildcardExpression Class (com.ms.util Package)

 Microsoft SDK for Java

WildcardExpression Class

The WildcardExpression class of the com.ms.util package matches simple wildcard expressions, such as *.txt or report?.doc commonly recognized by users on most platforms.

public class WildcardExpression implements
            java.io.FilenameFilter, Cloneable, SetComparison
{
  // Fields
  public static int CASE_SENSITIVE;
  public static final int COMPARE_FL_ALL;
  public static final int COMPARE_FL_REJECT;
  public static final int COMPARE_FL_STOP1;
  public static final int COMPARE_FL_STOP2;
  public static int ESCAPED;
  public static int EXACT;
  public static int NO_DELIMITERS;
  public static int NO_WILDCARDS;

  // Constructors
  public WildcardExpression();
  public WildcardExpression(String expr);
  public WildcardExpression(String expr, int flags);

  // Methods
  public boolean accept(java.io.file dir, Sring name);
  public synchronized void append(WildcardExpression other);
  public synchronized void append(WildcardExpression[] list);
  public synchronized void append(String expr, int flags);
  public void append(String expr);
  protected Object clone();
  public int compare(WildcardExpression other,
        IWildcardExpressionComparator judge,
        boolean requireEquality);
  public int compare(WildcardExpression other)
  public int compare(WildcardExpression other,
        IWildcardExpressionComparator judge);
  public int compareSet(Object other);
  public static String ComparisonResulttoString(int cmp);
  public synchronized void compile(String expr, int flags)
  public void compile(String expr)
  public WildcardExpression condense();
  public synchronized WildcardExpression); condense(
        IWildcardExpressionComparator judge);
  public WildcardExpression copy();
  public boolean equals(Object obj);
  public WildcardExpression[] getSubexpressions();
  public WildcardExpression intersect(WildcardExpression other,
        IWildcardExpressionComparator judge);
  public WildcardExpression intersect(WildcardExpression other);
  public static int InvertComparisonResult(int cmp);
  public boolean isCaseSensitive();
  public boolean isEmpty();
  public boolean match(String s);
  public int matchex(String s);
  public static int matchOne(WildcardExpression[] exprs, int ofs
        int len, String s);
  public static int matchOne(WildcardExpression[] exprs, Sting s);
  public int resume(String s);
  public WildcardExpression selectSubexpressions(
        WildcardExpression other, int[] criteria,
        IWildcardExpressionComparator judge);
  public WildcardExpression selectSubexpressions(
        WildcardExpression other, int[] criteria);
  public void setCaseInsensitive();
  public String toString();
  public String toString(boolean escaped);
}

The nonterminals "*" and "?" can be combined any number of times in any conceivable manner. Multiple expressions can be matched by separating the expressions with a semicolon; for example, "*.txt;*.doc" will match Strings ending with .txt or .doc. The special expression tokens can be matched by escaping them with '\'; for example, "clear\*sky" will match the string "clear*sky", but not "clearbluesky". Expressions can be case-sensitive or case-insensitive; this is selected when the expression is constructed.

This is very similar to Microsoft® MS-DOS® wildcards, but is in no way confined to file names. The expression '*' will match a path in any subdirectory, and "*.*" does not match a file with no extension. For example, unlike MS-DOS, "c:\\windows\\*" will match "c:\\windows\\system\\blue.vxd" and "*.*" will not match "notes."

WildcardExpression implements FilenameFilter, so it can readily be used with FileDialog, ClientStoreFile.list or ClientStore.listFiles.

The equals method has been overridden to special case-equality with strings. When invoked with a string, it will perform a match instead of comparing the pattern string. This allows it to be more easily used in a container, such as Vector, to find an expression matching a string. To find a matching expression in a string array, use the matchOne method.

The preferred method of matching a string against a series of expressions is to combine the expressions into a single expression using the append operator. The matchtex function will return the sub-expression number of the first matching expression, and the resume function will continue to search for matching expressions.

Example

The use of matchex, or resume can be used on the same expression simultaneously from another thread, as shown in the following example:

 WildcardExpression expr = new WildcardExpression();
 expr.append("*.java");
 expr.append("*.txt");
 expr.append("*.doc");
 expr.append("c:\\docs\\*");
 // Resulting expression: "*.java;*.txt;*.doc;c:\\docs\\*"

 String filename = "c:\\docs\\MyText.txt";
 synchronized (expr)
 {
     int exprnum;
     exprnum = expr.matchex(filename);   // returns 1
     exprnum = expr.resume(filename);    // returns 3
     exprnum = expr.resume(filename);    // returns -1
 }

Case-sensitive and case-insensitive expressions cannot be combined.

To construct expressions

  1. Use one of the constructors to create a set of subexpressions from a string delimited by ';'.

  2. Use the append methods to add subexpressions to an existing expression (which can be an empty expression). The new pattern string can optionally have ';' delimiters ignored. Both single WildcardExpression objects and arrays of WildcardExpression objects can be appended to existing expressions.

  3. Use the compile methods, which replace an existing expression with a new one using the same semantics as the constructors.

To improve performance, nothing in this class is synchronized. The typical use is that an expression is compiled once by the constructor. The compile and append methods are the only operators that change the state of the expression. Callers are responsible for synchronizing these operations with callers of the other methods. Note that matchex and resume also change state of the expression but not the expression itself. These operations also might need to be synchronized, but not with the others.

WildcardExpressions are not immutable, so security-critical code should be careful to pass copies of the expression to less-trusted code using the copy method. Some of the contents of the copy will be shared with the original until one of them changes.


Constructors (WildcardExpression Class)

 Microsoft SDK for Java

WildcardExpression Class Constructors

The WildcardExpression Class contains the following constructors:

WildcardExpression()
WildcardExpression(String expr)
WildcardExpression(String expr, int flags)

WildcardExpression()

Creates an empty expression. (An expression must be compiled before matches can be made.)

Syntax

public WildcardExpression();

See Also

compile

WildcardExpression(String expr)

Creates an expression that follows the typical wildcard convention.

Syntax

public WildcardExpression(String expr);

Parameters

expr The expression to evaluate.

WildcardExpression(String expr, int flags)

Creates a case-sensitive expression from a string and allows for escaped wildcards.

Syntax

public WildcardExpression (String expr, int flags);

Parameters

expr | The expression to compile.
flags | Combination of one or more of the following flags: CASE_SENSITIVE NO_DELIMITERS ESCAPED

See Also

compile


Methods (WildcardExpression Class)

 Microsoft SDK for Java

WildcardExpression Class Methods

The WildcardExpression Class contains the following methods:

accept determines if a file name is valid.
append appends another expression to this expression.
clone creates a copy of the this object.
compare compares the set of strings matched by this expression to the set matched by another.
compareSet compares the set of strings matched by this expression to the set matched by another.
ComparisonResulttoString converts comparison result flags to a string format.
compile compiles the expression for faster evaluation.
condense removes redundant subexpressions.
copy retrieves a copy of the currently compiled expression.
equals determines if this object is equivalent to another object.
getSubexpressions splits the expression into its subexpressions.
intersect constructs an expression that matches any strings that this and another expression both match.
InvertComparisonResult inverts comparison results.
isCaseSensitive determines if the expression is case-sensitive.
isEmpty determines if the expression has an expression compiled into it.
match evaluates the expression on a string.
matchex evaluates the expression on a string.
matchOne evaluates a list of expressions on a string.
resume resumes a previous match that stopped at a subexpression.
selectSubexpressions constructs a new expression containing expressions from this expression that have any of the specified comparison results against any subexpressions of the target expression.
setCaseInsensitive destructively changes the expression to perform case-insensitive matching.
toString reconstructs the original expression in extended, non-escaped form.


accept (WildcardExpression Class)

 Microsoft SDK for Java

accept

This method of the WildcardExpression Class determines if a file name is valid.

Syntax

public boolean accept(java.io.File dir, String name);

Return Value

Returns true if name matches a real path; otherwise, returns false.

Parameters

dir | The directory that contains the file.
name | The name of the file.


append (WildcardExpression Class)

 Microsoft SDK for Java

append

The append method of the WildcardExpression Class contains the following signatures:

append(WildcardExpression other)
append(WildcardExpression[] list)
append(String expr, int flags)
append(String expr)

append(WildcardExpression other)

Appends another expression to this expression.

Syntax

public synchronized void append(WildcardExpression other);

Parameters

other The expression to append.

Exceptions

IllegalArgumentException if the expressions are incompatible.

append(WildcardExpression[] list)

Adds a list of expressions to the expression. If any expressions fail to be added, the original expression is not affected.

Syntax

public synchronized void append(WildcardExpression[] list);

Parameters

list The list of expressions to add.

append(String expr, int flags)

Appends another expression to this expression.

Syntax

public synchronized void append(String expr, int flags);

Parameters

expr | The expression to append.
flags | Combination of one or more of the following flags for controlling constructing of the expression: NO_WILDCARDS NO_DELIMITERS ESCAPED Note that CASE_SENSITIVE is not valid. The case-sensitivity of matching the new pattern is controlled by the existing case-sensitivity of the expression.

Exceptions

IllegalArgumentException if the expression is invalid.

append(String expr)

Appends another expression to this expression.

Syntax

public void append(String expr);

Parameters

expr The expression to append.

Exceptions

IllegalArgumentException if the expression is invalid.


clone (WildcardExpression Class)

 Microsoft SDK for Java

clone

This method of the WildcardExpression Class creates a copy of the this object.

Syntax

protected Object clone();

Return Value

Returns the cloned copy.


compare (WildcardExpression Class)

 Microsoft SDK for Java

compare

The compare method of the WildcardExpression Class contains the following signatures:

compare(WildcardExpression other, IWildcardExpressionComparator judge, boolean requireEquality)
compare(WildcardExpression other)
compare(WildcardExpression other, IWildcardExpressionComparator judge)

compare(WildcardExpression other, IWildcardExpressionComparator judge, boolean requireEquality)

Compares the set of strings matched by this expression to the set matched by another. This variant of this method should be used for continued expressions.

Syntax

public int compare(WildcardExpression other, IWildcardExpressionComparator judge, boolean requireEquality);

Return Value

Returns one of the SetComparison field values to indicate the relationship between the sets.

Parameters

Other | The object containing the other set of strings.
Judge | Used for deciding what to do with two expressions.
RequireEquality | Set to true if the comparator should time-out if it becomes impossible for an EQUAL result to be returned.

Exceptions

IllegalArgumentException if the expressions cannot be compared.

compare(WildcardExpression other)

Compares the set of strings matched by this expression to the set matched by another.

Syntax

public int compare(WildcardExpression other);

Return Value

Returns one of the SetComparison field to indicate the relationship between the sets. The result reflects the action of matching non-continuable expressions.

Parameters

other The object containing the other set of strings.

Exceptions

IllegalArgumentException if the expressions cannot be compared.

compare(WildcardExpression other, IWildcardExpressionComparator judge)

Compares the set of strings matched by this expression to the set matched by another. This variant of this method should be used for continued expressions.

Syntax

public int compare(WildcardExpression other, IWildcardExpressionComparator judge);

Return Value

Returns one of the SetComparison field values to indicate the relationship between the sets.

Parameters

other | The object containing the other set of strings.
judge | Used for deciding what to do with two expressions.

Exceptions

IllegalArgumentException if the expressions cannot be compared.


compareSet (WildcardExpression Class)

 Microsoft SDK for Java

compareSet

This method of the WildcardExpression Class compares the set of strings matched by this expression to the set matched by another.

Syntax

public int compareSet(Object other);

Return Value

Returns one of the SetComparison field values to indicate the relationship between the sets. If other is not a WildcardExpression object, returns DISJOINT. The result reflects the action of matching non-continuable expressions.

Parameters

other The object containing the other set of strings.

Exceptions

IllegalArgumentException if the expressions cannot be compared.


ComparisonResulttoString (WildcardExpression Class)

 Microsoft SDK for Java

ComparisonResulttoString

This method of the WildcardExpression Class converts comparison result flags to a string format.

Syntax

public static String ComparisonResulttoString(int cmp);

Return Value

Returns the result string as follows:

"equal" (SetComparison.EQUAL)
"notequal" (SetComparison.DISJOINT)
"overlap" (SetComparison.OVERLAP)
"subset" (SetComparison.SUBSET)
"superset" (SetComparison.SUPERSET)

Parameters

cmp A comparison result from the compare method.


compile (WildcardExpression Class)

 Microsoft SDK for Java

compile

The compile method of the WildcardExpression Class contains the following signatures:

compile(String expr, int flags)
compile(String expr)

compile(String expr, int flags)

Compiles the expression for faster evaluation. The previously compiled expression is lost when this method is called.

Syntax

public synchronized void compile(String expr, int flags);

Parameters

expr | The expression to compile.
flags | Combination of one or more of the following flags: NO_WILDCARDS CASE_SENSITIVE NO_DELIMITERS ESCAPED

See Also

match

compile(String expr)

Compiles the expression for faster evaluation with default values.

Syntax

public void compile(String expr);

Parameters

expr The expression to compile.

Remarks

The previously compiled expression is lost when this method is called. Case-sensitive matching and the evaluation of escaped wildcards are disabled for the compilation.

See Also

match


condense (WildcardExpression Class)

 Microsoft SDK for Java

condense

The condense method of the WildcardExpression Class contains the following signatures:

condense()
condense(IWildcardExpressionComparator judge)

condense()

Removes redundant subexpressions. The new subexpressions might match overlapping sets of strings, but will not be equal or entirely match the set of strings of any other subexpressions.

Syntax

public WildcardExpression condense();

Return Value

Returns a new WildcardExpression object containig unique expressions of the expression. If there are no redundant expressions, the original expression is returned.

condense(IWildcardExpressionComparator judge)

Removes redundant subexpressions. The new subexpressions might match overlapping sets of strings, but will not be equal or entirely match the set of strings of any other subexpressions.

Syntax

public synchronized WildcardExpression condense( IWildcardExpressionComparator judge);

Return Value

Returns a new WildcardExpression object containig unique expressions of the expression. If there are no redundant expressions, the original expression is returned.

Parameters

judge Used for comparing any auxiliary data that might be associated with each subexpression.


copy (WildcardExpression Class)

 Microsoft SDK for Java

copy

This method of the WildcardExpression Class retrieves a copy of the currently compiled expression.

Syntax

public WildcardExpression copy();

Return Value

Returns a copy of the expression.


equals (WildcardExpression Class)

 Microsoft SDK for Java

equals

This method of the WildcardExpression Class determines if this object is equivalent to another object.

Syntax

public boolean equals(Object obj);

Return Value

Returns true if obj is equivalent or matched by this object; otherwise, returns false.

Parameters

obj A String to match against this expression or a WildcardExpression to compare for equivalence.


getSubexpressions (WildcardExpression Class)

 Microsoft SDK for Java

getSubexpressions

This method of the WildcardExpression Class splits the expression into its subexpressions.

Syntax

public WildcardExpression[] getSubexpressions();

Return Value

Returns an array of expressions that make up the subexpressions.


intersect (WildcardExpression Class)

 Microsoft SDK for Java

intersect

The intersect method of the WildcardExpression Class contains the following signatures:

intersect(WildcardExpression other, IWildcardExpressionComparator judge)
intersect(WildcardExpression other)

intersect(WildcardExpression other, IWildcardExpressionComparator judge)

Constructs an expression that matches any strings that this and another expression both match.

Syntax

public WildcardExpression intersect(WildcardExpression other, IWildcardExpressionComparator judge);

Return Value

Returns an expression that is the intersection of the two expressions.

Parameters

Other | The other expression.
Judge | A helper interface.

Remarks

If either expression contains redundant subexpressions, the resulting expression will also contain redundant intersections. Calling condense beforehand on both expressions might improve the efficiency of this operaration. Redundant expressions might be returned even if the source expressions contain no redundant expressions.

intersect(WildcardExpression other)

Constructs an expression that matches any strings that this and another expression both match.

Syntax

public WildcardExpression intersect(WildcardExpression other);

Return Value

Returns an expression that is the intersection of the two expressions.

Parameters

other The other expression.

‘


InvertComparisonResult (WildcardExpression Class)

 Microsoft SDK for Java

InvertComparisonResult

This method of the WildcardExpression Class inverts comparison results.

Syntax

public static int InvertComparisonResult(int cmp);

Return Value

Returns the inverted comparison result.

Parameters

cmp Any comparison result of the compare method, which is inverted as follows:
  1. SUBSET returns SUPERSET.

  2. SUPERSET returns a SUBSET.

  3. any other result is not affected and is simply returned. Note that EQUAL and DISJOINT are not inverted by this function.


isCaseSensitive (WildcardExpression Class)

 Microsoft SDK for Java

isCaseSensitive

This method of the WildcardExpression Class determines if the expression is case-sensitive.

Syntax

public boolean isCaseSensitive();


isEmpty (WildcardExpression Class)

 Microsoft SDK for Java

isEmpty

This method of the WildcardExpression Class determines if the expression has an expression compiled into it. An empty expression cannot be used for matching.

Syntax

public boolean isEmpty();

Return Value

Returns true if the expression does not contain a compiled expression; otherwise, returns false.


match (WildcardExpression Class)

 Microsoft SDK for Java

match

This method of the WildcardExpression Class evaluates the expression on a string.

Syntax

public boolean match(String s);

Return Value

Returns true if the expression accepts the string.

Parameters

s The string to evaluate the expression on.


matchex (WildcardExpression Class)

 Microsoft SDK for Java

matchex

This method of the WildcardExpression Class evaluates the expression on a string.

Syntax

public int matchex(String s);

Return Value

Returns the subexpression number if the expression accepts the string; returns -1 if the string was not accepted.

Parameters

s The string to evaluate the expression on.


matchOne (WildcardExpression Class)

 Microsoft SDK for Java

matchOne

The matchOne method of the WildcardExpression Class contains the following signatures:

matchOne(WildcardExpression[] exprs, int ofs int len, String s)
matchOne(WildcardExpression[] exprs, Sting s)

matchOne(WildcardExpression[] exprs, int ofs, int len, String s)

Evaluates a list of expressions on a string.

Syntax

public static int matchOne(WildcardExpression[] exprs, int ofs, int len, String s);

Return Value

Returns the index of the expression that matched; returns -1 if no match occurred.

Parameters

exprs | A list of expressions.
ofs | The offset into the list to begin matching.
len | The number of elements to match against.
s | The string to evaluate the expressions on.

matchOne(WildcardExpression[] exprs, String s)

Evaluates a list of expressions on a string.

Syntax

public static int matchOne(WildcardExpression[] exprs, String s);

Return Value

Returns the index of the expression that matched; returns -1 if no match occurred.

Parameters

exprs | A list of expressions.
s | The string to evaluate the expressions on.


resume (WildcardExpression Class)

 Microsoft SDK for Java

resume

This method of the WildcardExpression Class resumes a previous match that stopped at a subexpression.

Syntax

public int resume(String s);

Return Value

Returns the subexpression number if the expression accepts the string; returns -1 if the string was not accepted.

Parameters

s The string to evaluate the expression on.


selectSubexpressions (WildcardExpression Class)

 Microsoft SDK for Java

selectSubexpressions

The selectSubexpression method of the WildcardExpression Class contains the following signatures:

selectSubexpressions(WildcardExpression other, int[] criteria, IWildcardExpressionComparator judge)
selectSubexpressions(WildcardExpression other, int[] criteria)

selectSubexpressions(WildcardExpression other, int[] criteria, IWildcardExpressionComparator judge)

Constructs a new expression containing expressions from this expression that have any of the specified comparison results against any subexpressions of the target expression.

Syntax

public WildcardExpression selectSubexpressions(WildcardExpression other, int[] criteria, IWildcardExpressionComparator judge);

Return Value

Returns the original expression if all are selected; returns a new expression containing only the subexpressions of this expression that meet the selection criteria.

Parameters

other | The target expression to compare against.
criteria | The selection criteria determining inclusion in the returned expression.
judge | An IWildcardExpressionComparator hook interface to compare any extra data associated with the subexpressions.

selectSubexpressions(WildcardExpression other, int[] criteria)

Constructs a new expression containing expressions from this expression that have any of the specified comparison results against any subexpressions of the target expression.

Syntax

public WildcardExpression selectSubexpressions(WildcardExpression other, int[] criteria);

Return Value

Returns the original expression if all are selected; returns a new expression containing only the subexpressions of this expression that meet the selection criteria.

Parameters

other | The other target expression to compare against.
criteria | The Selection criteria determining inclusion in the returned expression.


setCaseInsensitive (WildcardExpression Class)

 Microsoft SDK for Java

setCaseInsensitive

This method of the WildcardExpression Class destructively changes the expression to perform case-insensitive matching. This change cannot be reversed.

Syntax

public void setCaseInsensitive();


toString (WildcardExpression Class)

 Microsoft SDK for Java

toString

The toString method of the WildcardExpression Class contains the following signatures:

toString()
toString(boolean escaped)

toString()

Reconstructs the original expression in extended, non-escaped form. Case-insensitive expressions are reconstructed in lowercase.

Syntax

public String toString();

Return Value

Returns the original expression.

toString(boolean escaped)

Reconstructs the original expression, optionally in escaped form. Case-insensitive expressions are reconstructed in lowercase.

Syntax

public String toString(boolean escaped);

Return Value

Returns the original expression.

Parameters

escaped True if string is to include escape characters; false, otherwise.


Fields (WildcardExpression Class)

 Microsoft SDK for Java

WildcardExpression Class Fields

The WildcardExpression Class contains the following fields.

CASE_SENSITIVE | Specifies that the resulting expression should perform case-sensitive matching.
COMPARE_FL_ALL | An IWildCardExpressionComparator result flag, used in conjunction with COMPARE_XXX, by IWildcardExpressionComparator.compareSubexpressions. Combines flags COMPARE_FL_REJECT, COMPARE_FL_STOP1, and COMPARE_FL_STOP2.
COMPARE_FL_REJECT | Is a Comparison result flag, used by IWildcardExpressionComparator.compareSubexpressions to stop the comparison.
COMPARE_FL_STOP1 | Is a SetComparison result flag, used by IWildcardExpressionComparator.compareSubexpressions to disregard further elements of the first expression because they will not be considered during matching.
COMPARE_FL_STOP2 | Is a SetComparison result flag, used in conjunction with COMPARE_XXX, by IWildcardExpressionComparator.compareSubexpressions to disregard further elements of the second expression because they will not be considered during matching.
ESCAPED | Specifies that the added string contains escaped expression characters. For example, "\*" will match a '*'.
EXACT | Specifies that the added string will be matched "as is," with no interpretation of delimiters or wildcards.
NO_DELIMITERS | Specifies that the string being added or compiled into the expression should be added as a single subexpression. Subexpression delimiters within the added string will be ignored.
NO_WILDCARDS | Specifies that wildcard characters in the added string will be ignored.


Comparison Interface (com.ms.util Package)

 Microsoft SDK for Java

Comparison Interface

The Comparison Interface of the com.ms.util package is designed for implementing comparisons of two objects (usually used in conjunction with a VectorSort or ArraySort object).

public interface Comparison
{
  // Methods
  public int compare(Object p, Object q);
}


Methods (Comparison Interface)

 Microsoft SDK for Java

Comparison Interface Methods

The Comparison Interface contains the following method:

compare compares two Objects.


compare (Comparison Interface)

 Microsoft SDK for Java

compare

This method of the Comparison Interface compares two Objects.

Syntax

public int compare(Object p, Object q);

Return Value

Returns less than 0 if p is less than or comes before q, 0 if p equals q, or greater than 0 if p is greater than or comes after q.

Parameters

p | The Object to compare with q.
q | The Object to compare with p.


IIntRangeComparator Interface (com.ms.util Package)

 Microsoft SDK for Java

IIntRangeComparator Interface

The IIntRangeComparator Interface of the com.ms.util package supplies a hook for sorting auxiliary data associated with elements of an IntRanges object. The hook is used to help compare equal ranges during a condensing operation, while sorting and merging ranges.

public interface IIntRangeComparator
{
  // Fields
  static final int ORDER_AFTER;
  static final int ORDER_BEFORE;
  static final int ORDER_EQUAL;

  // Methods
  int compareRanges(IntRanges ranges1, int i1, IntRanges ranges2,
        int i2);
  void intersectRanges(IntRanges ranges1, int i1
        IntRanges ranges2, int i2, int isectexprnum);
  boolean mergeRanges(IntRanges ranges, int i1 inti2);
  int orderRanges(IntRnages ranges, int i1, int i2);
  void shiftRanges(IntRanges ranges, int start, int count,
        int shiftcount);
  void splitRange(IntRanges ranges, int i);
  void swapRanges(IntRanges ranges, int i1, int i2);
}


Methods (IIntRangeComparator Interface)

 Microsoft SDK for Java

IIntRangeComparator Interface Methods

The IIntRangeComparator Interface contains the following methods:

compareRanges compares ranges.
intersectRanges is called by IntRanges.intersect to intersect any extra data associated with two ranges.
mergeRanges determines if two overlapping ranges can be merged into a single range.
orderRanges compares equal ranges.
shiftRanges moves the ranges backward.
splitRange splits a range.
swapRanges swaps ranges.


compareRanges (IIntRangeComparator Interface)

 Microsoft SDK for Java

compareRanges

This method of the IIntRangeComparator Interface compares ranges. It is called by IntRanges.compare.

Syntax

int compareRanges(IntRanges ranges1, int i1, IntRanges ranges2, int i2);

Return Value

Returns one of the values shown in the following table.

OVERLAP | The sets of integers are not equal but have a common set of integers.
DISJOINT | The sets of integers have no integers in common.
SUBSET | The second set of integers includes all the integers in the first set, plus some integers that are not in the first set.
EQUAL | The sets of integers are identical.
SUPERSET | The first set of integers includes all the integers in the second set, plus some integers that are not in the second set.

Parameters

ranges1 | The first set of ranges to compare.
i1 | The index in ranges1 of the first range to compare.
ranges2 | The second set of ranges to compare.
i2 | The index in ranges2 of the second range to compare.


intersectRanges (IIntRangeComparator Interface)

 Microsoft SDK for Java

intersectRanges

This method of the IIntRangeComparator Interface is called by IntRanges.intersect to intersect any extra data associated with two ranges.

Syntax

void intersectRanges(IntRanges ranges1, int i1, IntRanges ranges2, int i2, int isectexprnum);

Parameters

ranges1 | The first set of ranges to intersect.
i1 | The index into the first set of ranges.
ranges2 | The second set of ranges to intersect.
i2 | The index into the second set of ranges.
isectexprnum | The intersection expression.


mergeRanges (IIntRangeComparator Interface)

 Microsoft SDK for Java

mergeRanges

This method of the IIntRangeComparator Interface determines if two overlapping ranges can be merged into a single range. This method is called by IntRanges.condense. If the ranges can be merged, they should be merged into the ranges and true should be returned.

Syntax

boolean mergeRanges(IntRanges ranges, int i1, int i2);

Return Value

Returns true if the ranges can be merged; otherwise, returns false.

Parameters

ranges | The IntRanges object to merge to.
i1 | The index of first range to merge.
i2 | The index of second range to merge into the first range.


orderRanges (IIntRangeComparator Interface)

 Microsoft SDK for Java

orderRanges

This method of the IIntRangeComparator Interface compares equal ranges. This method is called by IntRanges.sort.

Syntax

int orderRanges(IntRanges ranges, int i1, int i2);

Return Value

Returns an integer indicating how to interpret two equal ranges. This can be one of the values shown in the following table.

ORDER_BEFORE | i1 should be placed before i2.
ORDER_EQUAL | i1 and i2 are equal.
ORDER_AFTER | i1 should be placed after i2.

Parameters

ranges | The set of integer ranges to order.
i1 | The index of first range.
i2 | The index of second range.


shiftRanges (IIntRangeComparator Interface)

 Microsoft SDK for Java

shiftRanges

This method of the IIntRangeComparator Interface moves the ranges backward.

Syntax

void shiftRanges(IntRanges ranges, int start, int count, int shiftcount);

Parameters

ranges | The IntRanges object containing the ranges to shift.
start | The starting index of the ranges to move.
count | The number of ranges to move.
shiftcount | The number of ranges to shift backward; if -1, the ranges should be discarded.


splitRange (IIntRangeComparator Interface)

 Microsoft SDK for Java

splitRange

This method of the IIntRangeComparator Interface splits a range. This method is called by IntRanges.removeRanges when a range needs to be split to remove elements in the middle of a range. During removal this will be called at most, one time.

Syntax

void splitRange(IntRanges ranges, int i);

Parameters

ranges | The range to be split.
i | The index at which to split.


swapRanges (IIntRangeComparator Interface)

 Microsoft SDK for Java

swapRanges

This method of the IIntRangeComparator Interface swaps ranges. This method is called by IntRanges.sort.

Syntax

void swapRanges(IntRanges ranges, int i1, int i2);

Parameters

ranges | The IntRanges object in which to swap.
i1 | The index of the first range to swap.
i2 | The index of the second range to swap.


Fields (IIntRangeComparator Interface)

 Microsoft SDK for Java

IIntRangeComparator Interface Fields

The IIntRangeComparator Interface contains the following fields.

ORDER_AFTER | Is returned by orderRanges to indicate that the one set of ranges is to be ordered after another set of ranges.
ORDER_BEFORE | Is returned by orderRanges to indicate that the one set of ranges is to be ordered before another set of ranges.
ORDER_EQUAL | Is returned by orderRanges to indicate that the one set of ranges is equal to another set of ranges.


IWildcardExpressionComparator Interface (com.ms.util Package)

 Microsoft SDK for Java

IWildcardExpressionComparator Interface

The IWildcardExpressionComparator Interface of the com.ms.util package is used to compare subexpressions in WildcardExpression.compare.

public interface IWildcardExpressionComparator
{
  // Methods
  int compareSubexpressions(WildcardExpression expr1,
        int exprnum1, WildcardExpression expr2, int exprnum2, int
        cmpresult);
  void deleteSubexpression(WildcardExpression expr, int exprnum);
  void intersectSubexpressions(WildcardExpression expr1,
        int exprnum1, WildcardExpression expr2, int exprnum2, int
        cmpresult);
}


Methods (IWildcardExpressionComparator Interface)

 Microsoft SDK for Java

IWildcardExpressionComparator Interface Methods

The IWildcardExpressionComparator Interface contains the following methods:

compareSubexpressions compares two subexpressions of different expressions.
deleteSubexpression is called by condense when redundant expressions need to be deleted.
intersectSubexpressions is called by WildcardExpression.intersect to find the intersection of any data associated with two subexpressions.


compareSubexpressions (IWildcardExpressionComparator Interface)

 Microsoft SDK for Java

compareSubexpressions

This method of the IWildcardExpressionComparator Interface compares two subexpressions of different expressions.

Syntax

int compareSubexpressions(WildcardExpression expr1, int exprnum1, WildcardExpression expr2, int exprnum2, int cmpresult);

Return Value

Returns a SetComparison result code that is valid with WildcardExpression. This can be one of the following:

EQUAL
DISJOINT
SUBSET
OVERLAP
SUPERSET

Parameters

expr1 | The first expression operand.
exprnum1 | The subexpression of expr1 to compare.
expr2 | The second expression operand.
exprnum2 | The subexpression of expr2 to compare.
cmpresult | The result of comparing the given subexpressions (a SetComparison result code). The cmpresult value must be computed before calling this function. The subexpressions are compared, and passed to this method as cmpresult. The return value of compareSubexpressions is possibly completely independent of cmpresult. The return value is the result of comparing any extra elements that clients of WildcardExpression might have associated with each subexpression.


deleteSubexpression (IWildcardExpressionComparator Interface)

 Microsoft SDK for Java

deleteSubexpression

This method of the IWildcardExpressionComparator Interface is called by condense when redundant expressions need to be deleted.

Syntax

void deleteSubexpression(WildcardExpression expr, int exprnum);

Parameters

expr | The expression from which to delete the subexpression.
exprnum | The expression number, which is the original expression index, before any deletions have occurred. The new expression numbers will take effect after condense has completed.


intersectSubexpressions (IWildcardExpressionComparator Interface)

 Microsoft SDK for Java

intersectSubexpressions

This method of the IWildcardExpressionComparator Interface is called by WildcardExpression.intersect to find the intersection of any data associated with two subexpressions. The resulting data should be retained for the final intersection.

Syntax

void intersectSubexpressions(WildcardExpression expr1, int exprnum1, WildcardExpression expr2, int exprnum2, int cmpresult);

Parameters

expr1 | The first expression operand.
exprnum1 | The subexpression of expr1 to compare.
expr2 | The second expression operand.
exprnum2 | The subexpression of expr2 to compare.
cmpresult | The result of comparing the given subexpressions.


ProvideSetComparisonInfo Interface (com.ms.util Package)

 Microsoft SDK for Java

ProvideSetComparisonInfo Interface

The ProvideSetComparisonInfo Interface of the com.ms.util package provides set rules for comparisons.

public interface ProvideSetComparisonInfo
{
  // Fields
  static final int EXCLUDE;
  static final int INCLUDE;

  // Methods
  Object combineSetRules(Object o1, Object o2);
  int compareSetRules(Object o1, Object o2);
  Object getSetRule(int rule);
  String getStringForSetRule(Object o);
  Object intersectSetRules(Object o1, Object o2);
  boolean isEmptySetRule(Object o);
}

A set rule is an opaque value that defines a group of members from one or more sets. The rules can be manipulated using the operators on this interface. Rules are manipulated as Objects. Clients of this interface should not attempt to interpret the value of any objects returned from the methods.


Methods (ProvideSetComparisonInfo Interface)

 Microsoft SDK for Java

ProvideSetComparisonInfo Interface Methods

The ProvideSetComparisonInfo Interface contains the following methods:

combineSetRules computes the union of two objects retrieved from getSetRule or objects derived through other methods in this interface.
compareSetRules compares two objects retrieved from getSetRule or objects derived through other methods on this interface.
getSetRule obtains an object representing the specified rule that can be used internally by SetComparer.
getStringForSetRule retrieves a string representation of a given rule.
intersectSetRules computes the intersection of two objects retrieved from getSetRule or objects or objects derived through other methods on this interface.
isEmptySetRule determines if the given set rule is empty.


combineSetRules (ProvideSetComparisonInfo Interface)

 Microsoft SDK for Java

combineSetRules

This method of the ProvideSetComparisonInfo Interface computes the union of two objects retrieved from getSetRule or objects derived through other metods in this interface.

Syntax

Object combineSetRules(Object o1, Object o2);

Return Value

Returns a new set rule representing the union of the two rules, o1 and o2.

Parameters

o1 | The first set rule.
o2 | The second set rule.


compareSetRules (ProvideSetComparisonInfo Interface)

 Microsoft SDK for Java

compareSetRules

This method of the ProvideSetComparisonInfo Interface compares two objects retrieved from getSetRule or objects derived through other methods on this interface.

Syntax

int compareSetRules(Object o1, Object o2);

Return Value

Returns a SetComparison.compareSet return code.

Parameters

o1 | The first set rule to compare.
o2 | The second set rule to compare.


getSetRule (ProvideSetComparisonInfo Interface)

 Microsoft SDK for Java

getSetRule

This method of the ProvideSetComparisonInfo Interface obtains an object representing the specified rule that can be used internally by SetComparer.

Syntax

Object getSetRule(int rule);

Return Value

Returns the object specifying the rule. The object is treated as an opaque value and is provided to the other operators on this interface to obtain further information.

Parameters

rule The rule, which can be either INCLUDE or EXCLUDE.


getStringForSetRule (ProvideSetComparisonInfo Interface)

 Microsoft SDK for Java

getStringForSetRule

This method of the ProvideSetComparisonInfo Interface retrieves a string representation of a given rule.

Syntax

String getStringForSetRule(Object o);

Return Value

Returns the String representing the rule.

Parameters

o The given rule.


intersectSetRules (ProvideSetComparisonInfo Interface)

 Microsoft SDK for Java

intersectSetRules

This method of the ProvideSetComparisonInfo Interface computes the intersection of two objects retrieved from getSetRule or objects or objects derived through other methods on this interface.

Syntax

Object intersectSetRules(Object o1, Object o2);

Return Value

Returns a new set rule representing the intersection of the two rules, o1 and o2.

Parameters

o1 | The first set rule.
o2 | The second set rule.


isEmptySetRule (ProvideSetComparisonInfo Interface)

 Microsoft SDK for Java

isEmptySetRule

This method of theProvideSetComparisonInfo Interface determines if the given set rule is empty.

Syntax

boolean isEmptySetRule(Object o);

Return Value

Returns true if the object is empty; otherwise, returns false.

Parameters

o The given set rule.


Fields (ProvideSetComparisonInfo Interface)

 Microsoft SDK for Java

ProvideSetComparisonInfo Interface Fields

The ProvideSetComparisonInfo Interface contains the following fields.

EXCLUDE | Indicates the set rule specifying members that are excluded from the set.
INCLUDE | Indicates the set rule specifying members that are included in the set.


SetComparison Interface (com.ms.util Package)

 Microsoft SDK for Java

SetComparison Interface

The SetComparison Interface of the com.ms.util package compares two sets. It has only one method, which compares the sets, and a number of fields that are used to report the result of the set comparison.

public interface SetComparison
{
  // Fields
  static final int DISJOINT;
  static final int EMPTY;
  static final int EMPTY_SUBSET;
  static final int EMPTY_SUPERSET;
  static final int EQUAL;
  static final int OVERLAP;
  static final int SUBSET;
  static final int SUPERSET;

  // Methods
  int compareSet(Object other);
}


Methods (SetComparison Interface)

 Microsoft SDK for Java

SetComparison Interface Methods

The SetComparison Interface contains the following method:

compareSet compares this set against another, and returns one of the previous results.


compareSet (SetComparison Interface)

 Microsoft SDK for Java

compareSet

This method of the SetComparison Interface compares this set against another, and returns one of the previous results.

Syntax

int compareSet(Object other);

Return Value

Returns one of the field values of this interface.

Parameters

other The set to compare this set against.


Fields (SetComparison Interface)

 Microsoft SDK for Java

SetComparison Interface Fields

The SetComparison Interface contains the following fields.

DISJOINT | The sets are disjoint.
EMPTY | Both sets are empty sets.
EMPTY_SUBSET | This set is empty, and the other set is not empty.
EMPTY_SUPERSET | This set is not empty, and the other set is empty.
EQUAL | The sets are identical.
OVERLAP | The sets overlap.
SUBSET | This set is a subset of the other set, and is not equal to the other set.
SUPERSET | This set is a superset of the other set, and is not equal to the other set.


TimerListener Interface (com.ms.util Package)

 Microsoft SDK for Java

TimerListener Interface

The TimerListener Interface of the com.ms.util package enables timer event notifications to be received.

public interface TimerListener
{
  // Methods
  public void timeTriggered(TimerEvent te);
}


Methods (TimerListener Interface)

 Microsoft SDK for Java

TimerListener Interface Methods

The TimerListener Interface contains the following method:

timeTriggered is called when a timer event has expired.


timeTriggered (TimerListener Interface)

 Microsoft SDK for Java

timeTriggered

This method of the TimerListener Interface is called when a timer event has expired.

Syntax

public void timeTriggered(TimerEvent te);

Parameters

te A TimerEvent that describes the event.


com.ms.util.InputMethod Package Overview

Microsoft Packages Overview

The com.ms.util.InputMethod package provides Java classes and interfaces that support Input Method messaging and access to native system Input Method Editors (IMEs).

The Microsoft® Input Method Editor for Java APIs are designed to work with both Java and native system IMEs on any system where the Microsoft VM is installed.

This package contains the following:

Classes

Interfaces

Hierarchy

Level 2 IME Support

Currently, only level 2 IME support, where the user can type in text via a composition window, is provided for AFC components (components derived from com.ms.ui.UIComponent, or that implement the IUIComponent interface).

Level 3 IME Support

Level 3 IME support, where an IME is completely managed by an application, exists for components derived from java.awt.Component. The architecture of the com.ms.util.InputMethod package allows IMEs to work with components that are originally not IME-aware.

Input Method Editors generate InputMethodMessage-derived messages (such as IMECompositionMessage and IMENotifyMessage) when states change in the IME. These messages are passed to the InputMethodCallback.handleIMEMessage method. If the currently focused (AWT-derived) component implements the InputMethodMessageListener interface, these IME messages are passed to that component. The component can render its own custom IME user interface (handleIMEMessage returns true), or pass the message on to the InputMethodListener (handleIMEMessage returns false), which can then draw a default IME user interface.

The JavaIME accelerator key switching behavior is as follows: Ctrl+Alt will switch from JavaIME1, JavaIME2, ..., no IME, and back to JavaIME1, IME2, and so on.


Classes (com.ms.util.InputMethod Package)

 Microsoft SDK for Java

com.ms.util.InputMethod Package Classes

The com.ms.util.InputMethod package contains the following classes:

IMECompositionMessage Class implements Input Method (IME) Composition messages.

IMENotifyMessage Class provides message objects that notify an Input Method Editor (IME) object to perform an action with one of the various windows associated with it.

InputMethodMessage Class provides a base from which input method editor (IME) message classes can be derived.


Interfaces (com.ms.util.InputMethod Package)

 Microsoft SDK for Java

com.ms.util.InputMethod Package Interfaces

The com.ms.util.InputMethod package contains the following interfaces:

InputManagerListener Interface receives messages from a system input and distributes those messages to designated Input Method Editors (IMEs) and other Components.

InputMethodCallback Interface enables InputMethodListener objects to return composed characters and Input Method Editor (IME) messages.

InputMethodListener Interface must be implemented by Input Method Editors (IMEs) to be used with Java applications.

InputMethodMessageListener Interface is implemented by classes derived from java.awt.Component to handle Input Method Editor (IME) messages.


Hierarchy (com.ms.util.InputMethod Package)

 Microsoft SDK for Java

com.ms.util.InputMethod Package Hierarchy

The com.ms.util.InputMethod package has the following hierarchy:

Object
  |
  +--InputMethodMessage
     |
     +--IMECompositionMessage
     |
     +--IMENotifyMessage

InputManagerListener
InputMethodCallback
InputMethodListener
InputMethodMessageListener


IMECompositionMessage Class (com.ms.util.InputMethod Package)

 Microsoft SDK for Java

IMECompositionMessage Class

The IMECompositionMessage Class of the com.ms.util.InputMethod package implements Input Method (IME) Composition messages.

public class IMECompositionMessage extends InputMethodMessage
{
  // Fields
  public final static int CHANGE_COMPOSITION;
  public final static int END_COMPOSITION;
  public final static int START_COMPOSITION;
  public final static int UNKNOWN;

  // Constructors
  public IMECompositionMessage(int id);
  public IMECompositionMessage(int id, int keyCode, int keyChar,
        String compStr);

  // Methods
  public String getComposition();
  public int getID();
  public int getKeyChar();
  public int getkeyCode();
  public void setComposition(String compStr);
  public void setKeyChar(int keyChar);
  public void setKeyCode(int keyCode);
  public String toString();
}

Hierarchy

InputMethodMessage
  |
  +--IMECompositionMessage


Constructors (IMECompositionMessage Class)

 Microsoft SDK for Java

IMECompositionMessage Class Constructors

The IMECompositionMessage Class contains the following constructors:

IMECompositionMessage(int id)
IMECompositionMessage(int id, int keyCode, int keyChar, String compStr)

IMECompositionMessage(int id)

Creates an Input Method Composition message.

Syntax

public IMECompositionMessage(int id);

Parameters

id The message identifier, which can be one of the following:

START_COMPOSITION
END_COMPOSITION
CHANGE_COMPOSITION
UNKNOWN

IMECompositionMessage(int id, int keyCode, int keyChar, String compStr)

Creates an Input Method Composition message that has a specific key code, key character, and composition string.

Syntax

public IMECompositionMessage(int id, int keyCode, int keyChar, String compStr);

Parameters

id | The message identifier, which can be one of the following: START_COMPOSITION END_COMPOSITION CHANGE_COMPOSITION UNKNOWN
keyCode | The message key code.
keyChar | The message key character.
compStr | The message composition string.


Methods (IMECompositionMessage Class)

 Microsoft SDK for Java

IMECompositionMessage Class Methods

The IMECompositionMessage Class contains the following methods:

getComposition retrieves the composition string from an IMECompositionMessage object.
getID retrieves the message identifier from an IMECompositionMessage object.
getKeyChar retrieves the key character from an IMECompositionMessage object.
getkeyCode retrieves the key code from an IMECompositionMessage object.
setComposition sets the IMECompositionMessage object composition string.
setKeyChar sets the IMECompositionMessage key character.
setKeyCode sets the IMECompositionMessage key code.
toString translates the IMECompositionMessage object to text form.


getComposition (IMECompositionMessage Class)

 Microsoft SDK for Java

getComposition

This method of the IMECompositionMessage Class retrieves the composition string from an IMECompositionMessage object.

Syntax

public String getComposition();

Return Value

Returns the message composition string (which can be null if a string hasn't been specified for the object).


getID (IMECompositionMessage Class)

 Microsoft SDK for Java

getID

This method of the IMECompositionMessage Class retrieves the message identifier from an IMECompositionMessage object.

Syntax

public int getID();

Return Value

Returns the message identifier, which can be one of the following.

START_COMPOSITION END_COMPOSITION CHANGE_COMPOSITION UNKNOWN

or 0 if id hasn't been specified for the message.


getKeyChar (IMECompositionMessage Class)

 Microsoft SDK for Java

getKeyChar

This method of the IMECompositionMessage Class retrieves the key character from an IMECompositionMessage object.

Syntax

public int getKeyChar();

Return Value

Returns the message key character (which can be 0 if keyChar hasn't been specified for the message).

See Also

setKeyChar


getkeyCode (IMECompositionMessage Class)

 Microsoft SDK for Java

getkeyCode

This method of the IMECompositionMessage Class retrieves the key code from an IMECompositionMessage object.

Syntax

public int getkeyCode();

Return Value

Returns the message key code (which can be 0 if keyCode hasn't been specified for the message).

See Also

setKeyCode


setComposition (IMECompositionMessage Class)

 Microsoft SDK for Java

setComposition

This method of the IMECompositionMessage Class sets the IMECompositionMessage object composition string.

Syntax

public void setComposition(String compStr);

Parameters

compStr The message composition string.


setKeyChar (IMECompositionMessage Class)

 Microsoft SDK for Java

setKeyChar

This method of the IMECompositionMessage Class sets the IMECompositionMessage key character.

Syntax

public void setKeyChar(int keyChar);

Parameters

keyChar The character that is set.


setKeyCode (IMECompositionMessage Class)

 Microsoft SDK for Java

setKeyCode

This method of the IMECompositionMessage Class sets the IMECompositionMessage key code.

Syntax

public void setKeyCode(int keyCode);

Parameters

keyCode The char that is set.


toString (IMECompositionMessage Class)

 Microsoft SDK for Java

toString

This method of the IMECompositionMessage Class translates the IMECompositionMessage object to text form.

Syntax

public String toString();

Return Value

Returns a description of the IMECompositionMessage. For example, if the IMECompositionMessage is a START_COMPOSITION message, the text "IMECompositionMessage, START_COMPOSITION keyCode=keyCode keyChar=keyChar composition=compositionString" is returned.


Fields (IMECompositionMessage Class)

 Microsoft SDK for Java

IMECompositionMessage Class Fields

The IMECompositionMessage Class contains the following fields.

CHANGE_COMPOSITION | A message used to alert a Component that a composition has changed.
END_COMPOSITION | A message used to alert a Component object that a composition is finished.
START_COMPOSITION | A message used to alert a Component object that a composition has started.
UNKNOWN | An unknown composition message.


IMENotifyMessage Class (com.ms.util.InputMethod Package)

 Microsoft SDK for Java

IMENotifyMessage Class

The IMENotifyMessage Class of the com.ms.util.InputMethod package provides message objects that notify an Input Method Editor (IME) object to perform an action with one of the various windows associated with it.

public class IMENotifyMessage extends InputMethodMessage
{
  // Fields
  public final static int CHANGE_CANDIDATE;
  public final static int CLOSE_CANDIDATE;
  public final static int CLOSE_STATUS_WINDOW;
  public final static int OPEN_CANDIDATE;
  public final static int OPEN_STATUS_WINDOW;
  public final static int UNKNOWN;

  // Constructors
  public IMENotifyMessage(int id);

  // Methods
  public String[] getCandidateList();
  public int getID ();
  public String toString();
}

Hierarchy

InputMethodMessage
  |
  +--IMENotifyMessage


Constructors (IMENotifyMessage Class)

 Microsoft SDK for Java

IMENotifyMessage Class Constructors

The IMENotifyMessage Class contains the following constructor:

IMENotifyMessage(int id)

Creates an Input Method Notify Message that includes a specific flag.

Syntax

public IMENotifyMessage(int id);

Parameters

id | The flag used to create the message. This flag can be one of the following:
 | CLOSE_STATUS_WINDOW | CLOSE_CANDIDATE | UNKNOWN
 | OPEN_STATUS_WINDOW | OPEN_CANDIDATE |
 | CHANGE_CANDIDATE |


Methods (IMENotifyMessage Class)

 Microsoft SDK for Java

IMENotifyMessage Class Methods

The IMENotifyMessage Class contains the following methods:

getCandidateList retrieves a list of candidate windows.
getID retrieves the IMENotifyMessage message identifier.
toString Translates the IMENotifyMessage object to text form.


getCandidateList (IMENotifyMessage Class)

 Microsoft SDK for Java

getCandidateList

This method of the IMENotifyMessage Class retrieves a list of candidate windows.

Syntax

public String[] getCandidateList();

Return Value

Returns an array of strings that list the associated candidates.


getID (IMENotifyMessage Class)

 Microsoft SDK for Java

getID

This method of the IMENotifyMessage Class retrieves the IMENotifyMessage message identifier.

Syntax

public int getID();

Return Value

Returns the message identifier. This can be one of the following.

CLOSE_STATUS_WINDOW | CLOSE_CANDIDATE | UNKNOWN
OPEN_STATUS_WINDOW | OPEN_CANDIDATE |
CHANGE_CANDIDATE |


toString (IMENotifyMessage Class)

 Microsoft SDK for Java

toString

This method of the IMENotifyMessage Class translates the IMENotifyMessage object to text form.

Syntax

public String toString();

Return Value

Returns a description of the IMENotifyMessage. For example, if the IMENotifyMessage is a CLOSE_CANDIDATE message, the text "IMENotifyMessage, CLOSE_CANDIDATE" is returned.


Fields (IMENotifyMessage Class)

 Microsoft SDK for Java

IMENotifyMessage Class Fields

The IMENotifyMessage Class contains the following fields.

CHANGE_CANDIDATE | An IME message used to change the IME Candidate window.
CLOSE_CANDIDATE | An IME message used to close the Candidate window associated with an IME.
CLOSE_STATUS_WINDOW | An IME message used to close an IME Status window.
OPEN_CANDIDATE | An IME message used to open a Candidate window associated with an IME.
OPEN_STATUS_WINDOW | An IME message used to open a Status window associated with the IME.
UNKNOWN | An unknown IME message.


InputMethodMessage Class (com.ms.util.InputMethod Package)

 Microsoft SDK for Java

InputMethodMessage Class

The InputMethodMessage Class of the com.ms.util.InputMethod package provides a base from which input method editor (IME) message classes can be derived.

public abstract class InputMethodMessage
{
  // Constructors
  public InputMethodMessage();
}


Constructors (InputMethodMessage Class)

 Microsoft SDK for Java

InputMethodMessage Class Constructors

The InputMethodMessage Class contains the following constructor:

InputMethodMessage()

Creates an input method message.

Syntax

public InputMethodMessage();

See Also

com.ms.util.InputMethod.IMENotifyMessage, com.ms.util.InputMethod.IMECompositionMessage


InputManagerListener Interface (com.ms.util.InputMethod Package)

 Microsoft SDK for Java

InputManagerListener Interface

The InputManagerListener Interface of the com.ms.util.InputMethod package receives messages from a system input and distributes those messages to designated Input Method Editors (IMEs) and other Components. This interface must be implemented by any object designated as the system Input Method Manager (IMM).

public interface InputManagerListener
{
  // Fields
  public static final int ALT;
  public static final int CONTROL;
  public static final int DOWN;
  public static final int LBUTTON;
  public static final int MBUTTON;
  public static final int RBUTTON;
  public static final int SHIFT;
  public static final int UP;
  public static final int UPDOWN;

  // Methods
  public InputMethodListener getCurrentInputMethod();
  public InputMethodListener getCurrentInputMethod();
  public InputMethodListener getInputMethod(int idx);
  public int getNumberInputMethods();
  public boolean handledKey(InputMethodCallback imeCallback,
        long when, int keyCode, int keyChar, int state);
  public void removeInputMethod(InputMethodListener ime);
  public void setInputMethod(InputMethodListener ime);
}

See Also

com.ms.util.InputMethod.InputMethodListener, com.ms.util.InputMethod.InputMethodCallback


Methods (InputManagerListener Interface)

 Microsoft SDK for Java

InputManagerListener Interface Methods

The InputManagerListener Interface contains the following methods:

getCurrentInputMethod retrieves the current IME from an Input Method Manager-maintained list.
getInputMethod retrieves an IME from an Input Method Manager-maintained list.
getNumberInputMethods retrieves the current number of registered Input Methods in an Input Method Manager-maintained list.
handledKey is called by an IME class that handles the keystrokes from the native system.
removeInputMethod removes a registered IME from the IMM-maintained list.
setInputMethod sets the given InputMethodListener object as the current IME.


getCurrentInputMethod (InputManagerListener Interface)

 Microsoft SDK for Java

getCurrentInputMethod

The getCurrentInputMethod of the InputManagerListener Interface contains the following signatures:

getCurrentInputMethod()
getCurrentInputMethod()

getCurrentInputMethod()

Retrieves the current IME from an Input Method Manager-maintained list.

Syntax

public InputMethodListener getCurrentInputMethod();

Return Value

Returns the current InputMethodListener.

getCurrentInputMethod()

Retrieves the current IME from an Input Method Manager-maintained list.

Syntax

public InputMethodListener getCurrentInputMethod();

Return Value

Returns the InputMethodListener at a specific index interface.


getInputMethod (InputManagerListener Interface)

 Microsoft SDK for Java

getInputMethod

This method of the InputManagerListener Interface retrieves an IME from an Input Method Manager-maintained list.

Syntax

public InputMethodListener getInputMethod(int idx);

Return Value

Returns the InputMethodListener at a specific index interface.

Parameters

idx An index of an IME on the list.


getNumberInputMethods (InputManagerListener Interface)

 Microsoft SDK for Java

getNumberInputMethods

This method of the InputManagerListener Interface retrieves the current number of registered Input Methods in an Input Method Manager-maintained list.

Syntax

public int getNumberInputMethods();

Return Value

Returns the number of input methods on the list.


handledKey (InputManagerListener Interface)

 Microsoft SDK for Java

handledKey

This method of the InputManagerListener Interface is called by an IME class that handles the keystrokes from the native system.

Syntax

public boolean handledKey(InputMethodCallback imeCallback, long when, int keyCode, int keyChar, int state);

Return Value

Returns true if InputManagerListener processes the keystroke; otherwise, returns false.

Parameters

imeCallback | The InputMethodCallback object that receives keystrokes from the native system.
when | The time that the composed character is generated at.
keyCode | The ASCII key code of the character.
keyChar | The key character of the composed character.
state | The state when the event occurred.


removeInputMethod (InputManagerListener Interface)

 Microsoft SDK for Java

removeInputMethod

This method of the InputManagerListener Interface removes a registered IME from the IMM-maintained list.

Syntax

public void removeInputMethod(InputMethodListener ime);

Parameters

ime The IME removed from the list.


setInputMethod (InputManagerListener Interface)

 Microsoft SDK for Java

setInputMethod

This method of the InputManagerListener Interface sets the given InputMethodListener object as the current IME.

Syntax

public void setInputMethod(InputMethodListener ime);

Parameters

ime The IME object to set the current input method as. If ime is null, all IMEs are deactivated, and the standard system keyboard input is used.


Fields (InputManagerListener Interface)

 Microsoft SDK for Java

InputManagerListener Interface Fields

The InputManagerListener Interface contains the following fields.

ALT | Indicates that the Alt key was depressed when this message was generated.
CONTROL | Indicates that the CTRL key was depressed when this message was generated.
DOWN | Indicates that either a key or mouse button was depressed.
LBUTTON | Indicates that the left mouse button was depressed when this message was generated.
MBUTTON | Indicates that the third mouse button was depressed when this message was generated.
RBUTTON | Indicates that the second (right) mouse button was depressed when this message was generated.
SHIFT | Indicates that the Shift key was depressed when this message was generated.
UP | Indicates that either a key or mouse button was released.
UPDOWN | Indicates that either a key or mouse button was depressed and released.


InputMethodCallback Interface (com.ms.util.InputMethod Package)

 Microsoft SDK for Java

InputMethodCallback Interface

The InputMethodCallback Interface of the com.ms.util.InputMethod package enables InputMethodListener objects to return composed characters and Input Method Editor (IME) messages. This interface is used by both Java IMEs and native system IMEs.

public interface InputMethodCallback
{
  // Methods
  public void handleIMEChar(long when, char keyChar, int state);
  public void handleIMEMessage(InputMethodMessage IMEMessage);
}


Methods (InputMethodCallback Interface)

 Microsoft SDK for Java

InputMethodCallback Interface Methods

The InputMethodCallback Interface contains the following methods:

handleIMEChar enables any class that implements InputMethodListener to return a composed character.
handleIMEMessage enables any class that implements InputMethodListener to handle IME-related messages.


handleIMEChar (InputMethodCallback Interface)

 Microsoft SDK for Java

handleIMEChar

This method of the InputMethodCallback Interface enables any class that implements InputMethodListener to return a composed character. The character is added to the internal input queue as if this is a character that the user typed. This method allows an InputMethodListener to pass back a composed character that is generated by a series of keystrokes.

Syntax

public void handleIMEChar(long when, char keyChar, int state);

For example, in a Japanese IME, you can type "ka" to send a Katakana character that doesn't exist in a standard English keyboard.

Parameters

when | The time that the composed character is generated.
keyChar | The key character of the composed character.
state | The state when the event occurred.


handleIMEMessage (InputMethodCallback Interface)

 Microsoft SDK for Java

handleIMEMessage

This method of the InputMethodCallback Interface enables any class that implements InputMethodListener to handle IME-related messages.

Syntax

public void handleIMEMessage(InputMethodMessage IMEMessage);

Parameters

IMEMessage The IME-related message (extended from InputMethodMessage). Two examples are IMENotifyMessage and IMECompositionMessage.


InputMethodListener Interface (com.ms.util.InputMethod Package)

 Microsoft SDK for Java

InputMethodListener Interface

The InputMethodListener Interface of the com.ms.util.InputMethod package must be implemented by Input Method Editors (IMEs) to be used with Java applications.

public interface InputMethodListener
{
  // Methods
  public void activate();
  public void deactivate();
  public String getName();
  public boolean handledKey(InputMethodCallback imeCallback,
        long when, int keyCode, int keyChar, int state);
  public void handleIMEMessage(InputMethodMessage IMEMessage);
  public void paint(Graphics g);
  public void setFont(Font font);
  public void setPos(int x, int y);
  public void setVisibleComponent(Component c);
  public void setVisibleComponent(IUIComponent c);
  public Dimension size(Graphics g);
}


Methods (InputMethodListener Interface)

 Microsoft SDK for Java

InputMethodListener Interface Methods

The InputMethodListener Interface contains the following methods:

activate activates the IME.
deactivate deactivates the IME.
getName retrieves the localized name of the IME.
handledKey is called by the InputManagerListener.
handleIMEMessage handles an IME Message.
paint paints the object on a specific graphic object.
setFont sets the font used in composition window.
setPos displays the IME composition window on the visible canvas in terms of (x,y) coordinates.
setVisibleComponent sets the component c as the component where the IME is seen on the screen.
size retrieves the current size of the area required to draw the IME, using the given graphics object.


activate (InputMethodListener Interface)

 Microsoft SDK for Java

activate

This method of the InputMethodListener Interface activates the IME. You must call this method to activate the IME because the IME will never receive focus and be activated by using focus methods.

Syntax

public void activate();

Remarks

Currently, this method is not implemented.


deactivate (InputMethodListener Interface)

 Microsoft SDK for Java

deactivate

This method of the InputMethodListener Interface deactivates the IME. You must call this method to deactivate the IME because the IME will never receive or lose focus and be deactivated by using focus methods.

Syntax

public void deactivate();

Remarks

Currently, this method is not implemented.


getName (InputMethodListener Interface)

 Microsoft SDK for Java

getName

This method of the InputMethodListener Interface retrieves the localized name of the IME. The IME should call Locale.getDefault() to determine the current locale, and return the localized name according to the locale. However, if the IME does not have a name corresponding to the current locale, it should return a language-netural name of the IME, generally in English.

Syntax

public String getName();

Return Value

Returns the localized name of the IME.


handledKey (InputMethodListener Interface)

 Microsoft SDK for Java

handledKey

This method of the InputMethodListener Interface is called by the InputManagerListener. The InputManagerListener passes the keystroke to the InputMethodListener object by calling this method.

Syntax

public boolean handledKey(InputMethodCallback imeCallback, long when, int keyCode, int keyChar, int state);

If the InputMethodListener object accepts the keystroke, it returns true and the keystroke never returns to the internal input queue. If the return value is false, this keystroke is returned to the internal input queue.

Return Value

Returns true if InputMethodListener processes the keystroke; otherwise, returns false.

Parameters

imeCallback | The InputMethodCallback object that receives keystrokes from the native system.
when | The time that the composed character is generated.
keyCode | The ASCII key code of the character.
keyChar | The key character of the composed character.
state | The state when the event occurred.


handleIMEMessage (InputMethodListener Interface)

 Microsoft SDK for Java

handleIMEMessage

This method of the InputMethodListener Interface handles an IME Message. The IME will first send any IME messages generated by itself to InputMethodCallback. handleIMEMessage. This gives the application a chance to handle IME messages (to reposition the IME windows, for example). However, if the handleIMEMessage method in the application which implements the InputMethodMessageListener returns false, the InputMethodCallback will forward these IME messages back into this method. In this way the InputMethodListener can listen to these messages and repaint the default IME user interface.

Syntax

public void handleIMEMessage(InputMethodMessage IMEMessage);

Parameters

IMEMessage The InputMethodMessage that is processed.


paint (InputMethodListener Interface)

 Microsoft SDK for Java

paint

This method of the InputMethodListener Interface paints the object on a specific graphic object.

Syntax

public void paint(Graphics g);

Parameters

g The Graphics object used to paint.

Remarks

Currently, this method is not implemented.


setFont (InputMethodListener Interface)

 Microsoft SDK for Java

setFont

This method of the InputMethodListener Interface sets the font used in composition window.

Syntax

public void setFont(Font font);

Parameters

font The Font used in the composition window.


setPos (InputMethodListener Interface)

 Microsoft SDK for Java

setPos

This method of the InputMethodListener Interface displays the IME composition window on the visible canvas in terms of (x,y) coordinates. When the IME is attached to a component, the position of the composition window will be set in the client area of the component.

Syntax

public void setPos(int x, int y);

Parameters

x | The x-coordinate of the position of the IME composition window.
y | The y-coordinate of the position of the IME composition window.

Remarks

Currently, this method is not implemented.


setVisibleComponent (InputMethodListener Interface)

 Microsoft SDK for Java

setVisibleComponent

The setVisibleComponent method of the InputMethodListener Interface contains the following signatures:

setVisibleComponent(Component c)
setVisibleComponent(IUIComponent c)

setVisibleComponent(Component c)

Sets the component c as the component where the IME is seen on the screen. This component does not have to be an independent window, but it can be attached to the input window.

Syntax

public void setVisibleComponent(Component c);

Parameters

c The component that displays the IME on the screen.

setVisibleComponent(IUIComponent c)

Sets the component c as the component where the IME is seen on the screen. This component does not have to be an independent window, but it can be attached to the input window.

Syntax

public void setVisibleComponent(IUIComponent c);

Parameters

c The component that displays the IME on the screen.


size (InputMethodListener Interface)

 Microsoft SDK for Java

size

This method of the InputMethodListener Interface retrieves the current size of the area required to draw the IME, using the given graphics object. This method enables the caller to set text fonts and colors.

Syntax

public Dimension size(Graphics g);

Return Value

Returns null, by default.

Parameters

g The Graphics object used to determine the size of the IME.

Remarks

Currently, this method is not implemented.


InputMethodMessageListener Interface (com.ms.util.InputMethod Package)

 Microsoft SDK for Java

InputMethodMessageListener Interface

The InputMethodMessageListener Interface of the com.ms.util.InputMethod package is implemented by classes derived from java.awt.Component to handle Input Method Editor (IME) messages.

public interface InputMethodMessageListener
{
  // Methods
  public boolean handleIMEMessage(InputMethodMessage IMEMessage);
}


Methods (InputMethodMessageListener Interface)

 Microsoft SDK for Java

InputMethodMessageListener Interface Methods

The InputMethodMessageListener Interface contains the following method:

handleIMEMessage handles IME-related messages.


handleIMEMessage (InputMethodMessageListener Interface)

 Microsoft SDK for Java

handleIMEMessage

This method of the InputMethodMessageListener Interface handles IME-related messages. The class that implements the InputMethodMessageListener interface needs to have current focus for IME messages to be successfully handled.

Syntax

public boolean handleIMEMessage(InputMethodMessage IMEMessage);

Return Value

Returns true if the class that implements the interface draws its own custom IME user interface. If the implementation method returns false, IME messages are directed to the InputMethodListener, which draws the IME user interface.

Parameters

IMEMessage The IME-related message (which is extended from InputMethodMessage). Two examples are IMENotifyMessage and IMECompositionMessage.


com.ms.vm Package Overview

Microsoft Packages Overview

The com.ms.vm package provides a class that implements a weak reference to an object. A weak reference tracks an object without preventing it from being garbage-collected.

This package contains the following:

Classes

Hierarchy


Classes (com.ms.vm Package)

 Microsoft SDK for Java

com.ms.vm Package Classes

The com.ms.vm package contains the following classes:

WeakReference Class implements a weak reference to an object.


Hierarchy (com.ms.vm Package)

 Microsoft SDK for Java

com.ms.vm Package Hierarchy

The com.ms.vm package has the following hierarchy:

Object
  |
  +--WeakReference


WeakReference Class (com.ms.vm Package)

 Microsoft SDK for Java

WeakReference Class

The WeakReference Class of the com.ms.vm package implements a weak reference to an object. A weak reference tracks an object without preventing it from being garbage-collected.

public class WeakReference
{
  // Constructors
  public WeakReference(Object referent);

  // Methods
  public void finalize();
  public Object getReferent();
  public void setReferent(Object object);
}


Constructors (WeakReference Class)

 Microsoft SDK for Java

WeakReference Class Constructors

The WeakReference Class contains the following constructor:

WeakReference(Object referent)

Constructs a weak reference to a specified object.

Syntax

public WeakReference(Object referent);

Parameters

referent The object to track.


Methods (WeakReference Class)

 Microsoft SDK for Java

WeakReference Class Methods

The WeakReference Class contains the following methods:

finalize finalizes the weak reference instance.
getReferent retrieves the current object being tracked.
setReferent sets the current object being tracked.


finalize (WeakReference Class)

 Microsoft SDK for Java

finalize

This method of the WeakReference Class finalizes the weak reference instance. The referent is no longer tracked.

Syntax

public void finalize();


getReferent (WeakReference Class)

 Microsoft SDK for Java

getReferent

This method of the WeakReference Class retrieves the current object being tracked.

The returned referent might be in the queue to have its finalizer called. In this case, it is possible to get an object and have that object's finalizer executed. This is possible even though there is a strong reference to that object in a live thread.

Syntax

public Object getReferent();

Return Value

Returns the object being tracked; returns null if the object was collected.


setReferent (WeakReference Class)

 Microsoft SDK for Java

setReferent

This method of the WeakReference Class sets the current object being tracked.

Syntax

public void setReferent(Object object);

Parameters

object The object being tracked, or null if the object was collected.


Package com.ms.wfc.app

Microsoft Packages Overview

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 using an .exe file, this method returns the path to the .exe file.


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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

Syntax

public static final int ANSI;


CharacterSet.ARABIC

Specifies the Arabic character set.

Syntax

public static final int ARABIC;


CharacterSet.BALTIC

Specifies the Baltic character set.

Syntax

public static final int BALTIC;


CharacterSet.CHINESEBIG5

Specifies the Chinese BIG 5 character set.

Syntax

public static final int CHINESEBIG5;


CharacterSet.DEFAULT

Specifies the default character set.

Syntax

public static final int DEFAULT;

Remarks

Uses the default character set for the thread.


CharacterSet.EASTEUROPE

Specifies the Eastern Europe character set.

Syntax

public static final int EASTEUROPE;


CharacterSet.GB2312

Specifies the Great Britain 2312 character set.

Syntax

public static final int GB2312;


CharacterSet.GREEK

Specifies the Greek character set.

Syntax

public static final int GREEK;


CharacterSet.HANGEUL

Specifies the Korean Hangeul character set.

Syntax

public static final int HANGEUL;


CharacterSet.HEBREW

Specifies the Hebrew character set.

Syntax

public static final int HEBREW;


CharacterSet.JOHAB

Specifies the Johab character set.

Syntax

public static final int JOHAB;


CharacterSet.MAC

Specifies the Macintosh character set.

Syntax

public static final int MAC;


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

Specifies the Russian character set.

Syntax

public static final int RUSSIAN;


CharacterSet.SHIFTJIS

Specifies the Shift JIS character set.

Syntax

public static final int SHIFTJIS;


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

Specifies the Thai character set.

Syntax

public static final int THAI;


CharacterSet.TURKISH

Specifies the Turkish character set.

Syntax

public static final int TURKISH;


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

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


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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Method | Description
Format | Creates a Format object.


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

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

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

Specifies the name of the format.

Syntax

public final String name;


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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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 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

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

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

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

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

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

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

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

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 Taiwan
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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves an array of Locale objects for all 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 Taiwan
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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 Taiwan
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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Fields | Description
ERA_EMPEROR | Specifies the Era: Year of the Emperor (Japan) 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

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

Syntax

public static final int ERA_EMPEROR;


Locale.CalendarType.ERA_TANGUN

Specifies the Tangun Era (Korea) calendar.

Syntax

public static final int ERA_TANGUN;


Locale.CalendarType.GREGORIAN_ENGLISH

Specifies the Gregorian (using English strings) calendar.

Syntax

public static final int GREGORIAN_ENGLISH;


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

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

Specifies the day-month-year calendar ordering.

Syntax

public static final int DAY_MONTH_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

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

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

Represents the Albanian language.

Syntax

public static final int ALBANIAN;


Locale.Languages.ARABIC

Represents the Arabic language.

Syntax

public static final int ARABIC;


Locale.Languages.BAHASA

Represents the Bahasa language.

Syntax

public static final int BAHASA;


Locale.Languages.BULGARIAN

Represents the Bulgarian language

Syntax

public static final int BULGARIAN;


Locale.Languages.CATALAN

Represents the Catalan language.

Syntax

public static final int CATALAN;


Locale.Languages.CHINESE

Represents the Chinese language.

Syntax

public static final int CHINESE;


Locale.Languages.CZECH

Represents the Czech language.

Syntax

public static final int CZECH;


Locale.Languages.DANISH

Represents the Danish language.

Syntax

public static final int DANISH;


Locale.Languages.DUTCH

Represents the Dutch language.

Syntax

public static final int DUTCH;


Locale.Languages.ENGLISH

Represents the English language.

Syntax

public static final int ENGLISH;


Locale.Languages.FINNISH

Represents the Finnish language.

Syntax

public static final int FINNISH;


Locale.Languages.FRENCH

Represents the French language.

Syntax

public static final int FRENCH;


Locale.Languages.GERMAN

Represents the German language.

Syntax

public static final int GERMAN;


Locale.Languages.GREEK

Represents the Greek language.

Syntax

public static final int GREEK;


Locale.Languages.HEBREW

Represents the Hebrew language.

Syntax

public static final int HEBREW;


Locale.Languages.HUNGARIAN

Represents the Hungarian language.

Syntax

public static final int HUNGARIAN;


Locale.Languages.ICELANDIC

Represents the Icelandic language.

Syntax

public static final int ICELANDIC;


Locale.Languages.ITALIAN

Represents the Italian language.

Syntax

public static final int ITALIAN;


Locale.Languages.JAPANESE

Represents the Japanese language.

Syntax

public static final int JAPANESE;


Locale.Languages.KOREAN

Represents the Korean language.

Syntax

public static final int KOREAN;


Locale.Languages.NEUTRAL

Represents a neutral language.

Syntax

public static final int NEUTRAL;


Locale.Languages.NORWEGIAN

Represents the Norwegian language.

Syntax

public static final int NORWEGIAN;


Locale.Languages.POLISH

Represents the Polish language.

Syntax

public static final int POLISH;


Locale.Languages.PORTUGUESE

Represents the Portuguese language.

Syntax

public static final int PORTUGUESE;


Locale.Languages.RHAETO_ROMAN

Represents the Rhaeto-Romance language.

Syntax

public static final int RHAETO_ROMAN;


Locale.Languages.ROMANIAN

Represents the Romanian language.

Syntax

public static final int ROMANIAN;


Locale.Languages.RUSSIAN

Represents the Russian language.

Syntax

public static final int RUSSIAN;


Locale.Languages.SERBO_CROATIAN

Represents the Serbo-Croatian language.

Syntax

public static final int SERBO_CROATIAN;


Locale.Languages.SLOVAK

Represents the Slovakian language.

Syntax

public static final int SLOVAK;


Locale.Languages.SPANISH

Represents the Spanish language.

Syntax

public static final int SPANISH;


Locale.Languages.SWEDISH

Represents the Swedish language.

Syntax

public static final int SWEDISH;


Locale.Languages.THAI

Represents the Thai language.

Syntax

public static final int THAI;


Locale.Languages.TURKISH

Represents the Turkish language.

Syntax

public static final int TURKISH;


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

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


Locale.LeadingZeros.LEADING

Specifies that leading zeros are used.

Syntax

public static final int LEADING;


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

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


Locale.MeasurementSystem.METRIC

Represents the metric measurement system.

Syntax

public static final int METRIC;


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

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

Specifies that negative numbers are displayed in parentheses.

Syntax

public static final int PARENS;


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

Specifies that negative numbers are displayed with a separator prefix.

Syntax

public static final int PREFIX_SEP;


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

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

Fields | Description
NO_ADDITIONAL_TYPES_VALID | Specifies that no additional calendar types are 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

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

Specifies that positive currency is displayed without a prefix separator.

Syntax

public static final int PREFIX_NOSEP;


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

Specifies that positive currency is displayed without a suffix separator.

Syntax

public static final int SUFFIX_NOSEP;


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

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

Specifies the Chinese BIG5 sort order.

Syntax

public static final int CHINESE_BIG5;


Locale.Sort.CHINESE_PRC

Specifies the PRC Chinese Stroke Count sort order.

Syntax

public static final int CHINESE_PRC;


Locale.Sort.CHINESE_PRCP

Specifies the PRC Chinese Phonetic sort order.

Syntax

public static final int CHINESE_PRCP;


Locale.Sort.CHINESE_UNICODE

Specifies the Chinese Unicode sort order.

Syntax

public static final int CHINESE_UNICODE;


Locale.Sort.DEFAULT

Specifies the default sort order.

Syntax

public static final int DEFAULT;


Locale.Sort.GERMAN_PHONE_BOOK

Specifies the German Phone Book sort order.

Syntax

public static final int GERMAN_PHONE_BOOK;


Locale.Sort.JAPANESE_UNICODE

Specifies the Japanese Unicode sort order.

Syntax

public static final int JAPANESE_UNICODE;


Locale.Sort.JAPANESE_XJIS

Specifies the Japanese XJIS sort order.

Syntax

public static final int JAPANESE_XJIS;


Locale.Sort.KOREAN_KSC

Specifies the Korean KSC sort order.

Syntax

public static final int KOREAN_KSC;


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

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

Specifies the Chinese (Simplified) sublanguage.

Syntax

public static final int CHINESE_SIMPLIFIED;


Locale.SubLanguages.CHINESE_TRADITIONAL

Specifies the Chinese (Traditional) sublanguage.

Syntax

public static final int CHINESE_TRADITIONAL;


Locale.SubLanguages.DEFAULT

Specifies the user default sublanguage.

Syntax

public static final int DEFAULT;


Locale.SubLanguages.DUTCH

Specifies the Dutch sublanguage.

Syntax

public static final int DUTCH;


Locale.SubLanguages.DUTCH_BELGIAN

Specifies the Dutch (Belgian) sublanguage.

Syntax

public static final int DUTCH_BELGIAN;


Locale.SubLanguages.ENGLISH_AUS

Specifies the English (Australian) sublanguage.

Syntax

public static final int ENGLISH_AUS;


Locale.SubLanguages.ENGLISH_CAN

Specifies the English (Canadian) sublanguage.

Syntax

public static final int ENGLISH_CAN;


Locale.SubLanguages.ENGLISH_EIRE

Specifies the English (Irish) sublanguage.

Syntax

public static final int ENGLISH_EIRE;


Locale.SubLanguages.ENGLISH_NZ

Specifies the English (New Zealand) sublanguage.

Syntax

public static final int ENGLISH_NZ;


Locale.SubLanguages.ENGLISH_UK

Specifies the English (United Kingdom) sublanguage.

Syntax

public static final int ENGLISH_UK;


Locale.SubLanguages.ENGLISH_US

Specifies the English (United States) sublanguage.

Syntax

public static final int ENGLISH_US;


Locale.SubLanguages.FRENCH

Specifies the French sublanguage.

Syntax

public static final int FRENCH;


Locale.SubLanguages.FRENCH_BELGIAN

Specifies the French (Belgian) sublanguage.

Syntax

public static final int FRENCH_BELGIAN;


Locale.SubLanguages.FRENCH_CANADIAN

Specifies the French (Canadian) sublanguage.

Syntax

public static final int FRENCH_CANADIAN;


Locale.SubLanguages.FRENCH_SWISS

Specifies the French (Swiss) sublanguage.

Syntax

public static final int FRENCH_SWISS;


Locale.SubLanguages.GERMAN

Specifies the German sublanguage.

Syntax

public static final int GERMAN;


Locale.SubLanguages.GERMAN_AUSTRIAN

Specifies the German (Austrian) sublanguage.

Syntax

public static final int GERMAN_AUSTRIAN;


Locale.SubLanguages.GERMAN_SWISS

Specifies the German (Swiss) sublanguage.

Syntax

public static final int GERMAN_SWISS;


Locale.SubLanguages.ITALIAN

Specifies the Italian sublanguage.

Syntax

public static final int ITALIAN;


Locale.SubLanguages.ITALIAN_SWISS

Specifies the Italian (Swiss) sublanguage.

Syntax

public static final int ITALIAN_SWISS;


Locale.SubLanguages.NEUTRAL

Specifies the neutral sublanguage.

Syntax

public static final int NEUTRAL;


Locale.SubLanguages.NORWEGIAN_BOKMAL

Specifies the Norwegian (Bokmal) sublanguage.

Syntax

public static final int NORWEGIAN_BOKMAL;


Locale.SubLanguages.NORWEGIAN_NYNORSK

Specifies the Norwegian (Nynorsk) sublanguage.

Syntax

public static final int NORWEGIAN_NYNORSK;


Locale.SubLanguages.PORTUGUESE

Specifies the Portuguese sublanguage.

Syntax

public static final int PORTUGUESE;


Locale.SubLanguages.PORTUGUESE_BRAZILIAN

Specifies the Portuguese (Brazilian) sublanguage.

Syntax

public static final int PORTUGUESE_BRAZILIAN;


Locale.SubLanguages.SERBO_CROATIAN_CYRILLIC

Specifies the Serbo-Croatian (Cyrillic) sublanguage.

Syntax

public static final int SERBO_CROATIAN_CYRILLIC;


Locale.SubLanguages.SERBO_CROATIAN_LATIN

Specifies the Serbo-Croatian (Latin) sublanguage.

Syntax

public static final int SERBO_CROATIAN_LATIN;


Locale.SubLanguages.SPANISH

Specifies the Spanish sublanguage.

Syntax

public static final int SPANISH;


Locale.SubLanguages.SPANISH_MEXICAN

Specifies the Spanish (Mexican) sublanguage.

Syntax

public static final int SPANISH_MEXICAN;


Locale.SubLanguages.SPANISH_MODERN

Specifies the Spanish (modern) sublanguage.

Syntax

public static final int SPANISH_MODERN;


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

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

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

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

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

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

Specifies the window handle of the message.

Syntax

public int hWnd;


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

Specifies the message identifier.

Syntax

public int msg;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

Syntax

public static final int APPLICATION_DATA;


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

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

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

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

Syntax

public static final int HISTORY;


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

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

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

Syntax

public static final int RECENT;


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

Specifies the file system directory containing Start menu items.

Syntax

public static final int START_MENU;


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

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

Syntax

public static final int TEMPLATES;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 taskbar or by application desktop toolbars.

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

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

Arranges minimized windows vertically from top to bottom.

Syntax

public static final int DOWN;


SystemInformation.ArrangeDirection.LEFT

Arranges minimized windows horizontally from left to right.

Syntax

public static final int LEFT;


SystemInformation.ArrangeDirection.RIGHT

Arranges minimized windows horizontally from right to left.

Syntax

public static final int RIGHT;


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

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

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

Syntax

public static final int BOTTOMLEFT;


SystemInformation.ArrangeStartingPosition.BOTTOMRIGHT

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

Syntax

public static final int BOTTOMRIGHT;


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

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

Syntax

public static final int TOPLEFT;


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

Constructors | Description
ThreadExceptionDialog | Creates a new ThreadExceptionDialog object.


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

Constructors | Description
ThreadExceptionEvent | Creates a new ThreadExceptionEvent object.


ThreadExceptionEvent.ThreadExceptionEvent

Creates a new ThreadExceptionEvent object.

Syntax

public ThreadExceptionEvent( Throwable t )

Parameters

t

The exception that has occurred.


ThreadExceptionEvent Fields

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Specifies the number of time units (100 nanoseconds) per day.

Syntax

public static final long UNITS_PER_DAY;


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

Specifies the number of time units (100 nanoseconds) per millisecond.

Syntax

public static final long UNITS_PER_MILLISECOND;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
getVersion | Retrieves the version information for the operating system.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Microsoft Packages Overview

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 Classesjsdk_ref_wfc_core_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

Constructors | Description
CancelEvent | Creates a CancelEvent object.


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

Fields | Description
cancel | Indicates whether the event will be canceled.


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.

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, &quot;autoSize&quot;, Boolean.TYPE,
         CategoryAttribute.Behavior,
         DefaultValueAttribute.TRUE,
         new DescriptionAttribute(&quot;Enables automatic
         resizing.&quot;));

      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,&quot;textChanged&quot;, EventHandler.class,
         CategoryAttribute.Behavior,
// Occurs when the text property of this control changes
         new DescriptionAttribute);

      // Specify the default event.
      public String getDefaultEventName() {
         return &quot;textChanged&quot;;

      }

      // 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

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

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

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

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

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

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

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

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

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

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

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

Creates a Component object.

Syntax

public Component()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves the class type of the component.

Syntax

public Class getComponentClass()

Return Value

Returns the component's type.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a Container object.

Syntax

public Container()


Container.dispose

Removes and disposes of all components in the container.

Syntax

public synchronized void dispose()

See Also remove


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

If your development tool has a Properties window, 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 &lt; 0 || value &gt; 3) return false;
        return true;
   }
}

// Set the alignment property of an object.
myObject.setAlignment(Alignment.LEFT);


Enum Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

Constructors | Description
Event | Creates an Event object.


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

Fields | Description
EMPTY | Specifies an Event object with no associated information.
extendedInfo | Specifies additional information for com.ms.wfc.html events.


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

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

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

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

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

Retrieves the addOn<EventName> method of the component class.

Syntax

public Method getAddMethod()

Return Value

Returns the addOn<EventName> method.


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

Retrieves the removeOn<EventName> method of the component class.

Syntax

public Method getRemoveMethod()

Return Value

Returns the removeOn<EventName> method.


EventInfo.getType

Retrieves the type of the delegate for the event.

Syntax

public Class getType()

Return Value

Returns the delegate type.


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

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

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

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

Retrieves the type of the object receiving the extender property.

Syntax

public Class getExtendeeType()

Return Value

Returns the extendee object's type.


ExtenderInfo.getGetMethod

Retrieves the get<ExtenderName> method of the extender component.

Syntax

public Method getGetMethod()

Return Value

Returns the get<ExtenderName> method.


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

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

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

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

Retrieves the type of the extender property.

Syntax

public Class getType()

Return Value

Returns the extender type.


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

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

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

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

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

Methods | Description
add | Adds an attribute to the associated component class.


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

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

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

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

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.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
getConstructorArgs | Retrieves the constructor arguments that are needed to instantiate the class.


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

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

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

Removes and disposes of all components in the container.

Syntax

public synchronized void dispose()

See Also remove


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

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

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

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

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

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

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

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

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

Indicates that the control inside a drop-down window has finished editing the value.

Syntax

public void dropDownDone()

See Also dropDownControl


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

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

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

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

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

Retrieves the type of the value being edited.

Syntax

public Class getType()

Return Value

Returns the value type.


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

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

Methods | Description
add | Adds an event to the associated component class.


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

Methods | Description
canExtend | Determines whether an object can receive the extender properties.


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

Methods | Description
add | Adds an extender property to the associated component class.


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

Methods | Description
getExtension | Retrieves the extension for the file name of the stream.
save | Persists the object to a stream.


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

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

Methods | Description
add | Adds a property to the associated component class.


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

Methods | Description
begin | Signals the component that all peer components are loaded and the property sets are complete.


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

Methods | Description
getResource | Retrieves a data stream for the specified resource.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
depersistProperties | Reads all resource data from the specified stream.


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

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

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

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

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

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

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

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

Methods | Description
persistProperties | Writes the specified set of resources to a file.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Specifies that arrays should not be expanded in a property browser.

Syntax

public static final int STYLE_NOARRAYEXPANSION;

See Also getStyle


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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves the name of the member.

Syntax

public String getName()

Return Value

Returns the member's name.


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

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

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

Retrieves the get<PropertyName> method of the component class.

Syntax

public Method getGetMethod()

Return Value

Returns the get<PropertyName> method.


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

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

Retrieves the set<PropertyName> method of the component class.

Syntax

public Method getSetMethod()

Return Value

Returns the set<PropertyName> method.


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

Retrieves the type of the property.

Syntax

public Class getType()

Return Value

Returns the property type.


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

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

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

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

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

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

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

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

Releases any cached resource data.

Syntax

public void flush()


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

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

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

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

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

Retrieves the extension for resource file names.

Syntax

public String getExtension()

Return Value

Returns the value of the EXTENSION field.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Fields | Description
EXTENSION | Specifies the extension of all resource files.


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

Methods | Description
depersistProperties | Reads all resource data from the specified stream.


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

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

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

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

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

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

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

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

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

Methods | Description
persistProperties | Writes the specified set of resources to a file.


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

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

Retrieves the name of the subproperty.

Syntax

public String getName()

Return Value

Returns the subproperty name.


SubProperty.getType

Retrieves the class type of the subproperty.

Syntax

public Class getType()

Return Value

Returns the property type.


SubProperty.getValue

Retrieves the value of the subproperty.

Syntax

public Object getValue()

Return Value

Returns an object that represents the value.


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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
VerbExecuteEvent | Creates a VerbExecuteEvent object.


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

Fields | Description
data | Specifies the user-defined data associated with the verb that was executed.


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

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

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

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

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

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

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

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

Fields | Description
innerException | The inner exception associated with the WFCException object.


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

Constructors | Description
WFCInvalidArgumentException | Creates a WFCInvalidArgumentException object.


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

Constructors | Description
WFCInvalidEnumException | Creates a WFCInvalidEnumException object.


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

Constructors | Description
WFCInvalidPropertyValue | Creates a WFCInvalidPropertyException object.


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

Constructors | Description
WFCInvalidStateException | Creates a WFCInvalidStateException object.


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

Constructors | Description
WFCSystemException | Creates a WFCSystemException object.


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

Constructors | Description
WFCWarning | Creates a WFCWarning object.


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

Fields | Description
helpTopic | The help topic associated with the warning.
helpURL | The help file associated with the warning.


WFCWarning.helpTopic

The help topic associated with the warning.

Syntax

public final String helpTopic;


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

Constructors | Description
WFCWin32Exception | Creates a WFCWin32Exception object.


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

Fields | Description
errorCode | The Win32 error code associated with this exception.


WFCWin32Exception.errorCode

The Win32 error code associated with this exception.

Syntax

public final int errorCode;


com.ms.wfc.data Package Overview

Microsoft Packages Overview

The com.ms.wfc.data package provides basic data access using the Microsoft® ActiveX® Data Objects (ADO) object model. This package also provides classes that support data formatting.

The package contains the following:

Classes
Interfaces
Hierarchy


Classes (com.ms.wfc.data package)

 Microsoft SDK for Java

com.ms.wfc.data Package Classes

The com.ms.wfc.data package contains the following classes:

AdoEnums.AdcPropAsyncThreadPriority specifies the execution priority of the asynchronous thread that fetches data for a Remote Data Service (RDS) Recordset object.

AdoEnums.AdcPropUpdateCriteria specifies which fields can be used to detect conflicts during an optimistic update of a row of the data source with a Remote Data Service (RDS) Recordset object.

AdoEnums.Affect specifies which records are affected by an operation.

AdoEnums.Bookmark specifies a bookmark indicating where the operation should begin.

AdoEnums.CommandType specifies how a command argument should be interpreted.

AdoEnums.Compare specifies the relative position of two records represented by their bookmarks.

AdoEnums.ConnectMode specifies the available permissions for modifying data in a Connection, opening a Record, or specifying values for the Mode property of the Record and Stream objects.

AdoEnums.ConnectOption specifies whether the Open method of a Connection object should return after (synchronously) or before (asynchronously) the connection is established.

AdoEnums.ConnectPrompt specifies whether a dialog box should be displayed to prompt for missing parameters when opening a connection to a data source.

AdoEnums.CursorLocation specifies the location of the cursor engine.

AdoEnums.CursorOption specifies what functionality the com.ms.wfc.data.Recordset.supports method should test for.

AdoEnums.CursorType specifies the type of cursor used in a com.ms.wfc.data.Recordset object.

AdoEnums.DataType specifies the data type of a field, parameter, or object.

AdoEnums.EditMode specifies the editing status of a record.

AdoEnums.ErrorValue specifies the type of ADO (Microsoft® ActiveX Data Objects) runtime error.

AdoEnums.EventReason specifies the reason that caused an event to occur.

AdoEnums.EventStatus specifies the current status of the execution of an event.

AdoEnums.ExecuteOption specifies how a provider should execute a command.

AdoEnums.FieldAttribute specifies one or more attributes, or characteristics, of a Field object.

AdoEnums.FilterGroup specifies the group of records to be filtered from a Recordset.

AdoEnums.GetRowsOption specifies how many records to retrieve from a Recordset.

AdoEnums.IsolationLevel specifies the level of transaction isolation for a Connection object.

AdoEnums.LockType specifies the type of lock placed on records during editing.

AdoEnums.MarshalOptions specifies which records should be returned to the server.

AdoEnums.ObjectState specifies whether an object is open or closed, connecting to a data source, executing a command, or fetching data.

AdoEnums.ParameterAttributes specifies the attributes of a Parameter object.

AdoEnums.ParameterDirection specifies whether the Parameter represents an input parameter, an output parameter, or both, or if the parameter is the return value from a stored procedure.

AdoEnums.PersistFormat specifies the format in which to save a Recordset.

AdoEnums.Position specifies the current position of the record pointer within a Recordset.

AdoEnums.PropertyAttributes specifies the attributes of an AdoProperties object.

AdoEnums.RecordStatus specifies the status of a record with regard to batch updates and other bulk operations.

AdoEnums.Resync specifies whether underlying values are overwritten by a call to Resync.

AdoEnums.Schema specifies the type of schema Recordset to be retrieved by the OpenSchema method.

AdoEnums.SearchDirection specifies the direction of a record search within a Recordset.

AdoEnums.StringFormat specifies the format when retrieving a Recordset as a string.

AdoEnums.XactAttribute specifies the transaction attributes of a Connection object.

AdoEvent is the basis of ADO event handlers.

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.

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.


Interfaces (com.ms.wfc.data package)

 Microsoft SDK for Java

com.ms.wfc.data Package Interfaces

The com.ms.wfc.data package contains the following interfaces:

IDataFormat defines the data formatting interface.

IDataSource

IDataSourceListener

IMarshal

IPersist

IPersistStream


Hierarchy (com.ms.wfc.data package)

 Microsoft SDK for Java

com.ms.wfc.data Package Hierarchy

The com.ms.wfc.data package has the following hierarchy:

java.lang.Object
  |
  +--AdoProperties
  |
  +--AdoProperty
  |
  +--AdoEvent
  |  |
  |  +--RecordsetEvent
  |
  +--java.lang.Throwable
  |  |
  |  +--java.lang.Exception
  |  |  |
  |  |  +--java.lang.RuntimeException
  |  |  |  |
  |  |  |  +--com.ms.com.ComException
  |  |  |  |  |
  |  |  |  |  +--com.ms.com.ComFailException
  |  |  |  |  |  |
  |  |  |  |  |  +--AdoException
  |
  +--Command
  |
  +--Connection
  |
  +--DataFormat (IOleDataFormat, IDataFormat)
  |  |
  |  +--BooleanDataFormat
  |  |
  |  +--DateDataFormat (IConstructable)
  |  |
  |  +--NumberDataFormat (IConstructable)
  |
  +--DataSpace
  |
  +--Error
  |
  +--Errors
  |
  +--com.ms.wfc.core.Enum
  |  |
  |  +--DateFormat
  |  |
  |  +--AdoEnums.AdcPropAsyncThreadPriority
  |  |
  |  +--AdoEnums.AdcPropUpdateCriteria
  |  |
  |  +--AdoEnums.Affect
  |  |
  |  +--AdoEnums.Bookmark
  |  |
  |  +--AdoEnums.CommandType
  |  |
  |  +--AdoEnums.Compare
  |  |
  |  +--AdoEnums.ConnectMode
  |  |
  |  +--AdoEnums.ConnectOption
  |  |
  |  +--AdoEnums.ConnectPrompt
  |  |
  |  +--AdoEnums.CursorLocation
  |  |
  |  +--AdoEnums.CursorOption
  |  |
  |  +--AdoEnums.CursorType
  |  |
  |  +--AdoEnums.DataType
  |  |
  |  +--AdoEnums.EditMode
  |  |
  |  +--AdoEnums.ErrorValue
  |  |
  |  +--AdoEnums.EventReason
  |  |
  |  +--AdoEnums.EventStatus
  |  |
  |  +--AdoEnums.ExecuteOption
  |  |
  |  +--AdoEnums.FieldAttribute
  |  |
  |  +--AdoEnums.FilterGroup
  |  |
  |  +--AdoEnums.GetRowsOption
  |  |
  |  +--AdoEnums.IsolationLevel
  |  |
  |  +--AdoEnums.LockType
  |  |
  |  +--AdoEnums.MarshalOptions
  |  |
  |  +--AdoEnums.ObjectState
  |  |
  |  +--AdoEnums.ParameterAttributes
  |  |
  |  +--AdoEnums.ParameterDirection
  |  |
  |  +--AdoEnums.PersistFormat
  |  |
  |  +--AdoEnums.Position
  |  |
  |  +--AdoEnums.PropertyAttributes
  |  |
  |  +--AdoEnums.RecordStatus
  |  |
  |  +--AdoEnums.Resync
  |  |
  |  +--AdoEnums.Schema
  |  |
  |  +--AdoEnums.SearchDirection
  |  |
  |  +--AdoEnums.StringFormat
  |  |
  |  +--AdoEnums.XactAttribute
  |
  |  +--Field
  |
  |  +--Fields
  |
  |  +--ObjectProxy
  |
  |  +--Parameter
  |
  |  +--Parameters
  |
  |  +--Recordset

Interfaces
IDataFormat
IDataSource
IDataSourceListener
IMarshal
IPersist
IPersistStream


AdoEnums.AdcPropAsyncThreadPriority Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.AdcPropAsyncThreadPriority Class

The AdcPropAsyncThreadPriority class of the com.ms.wfc.data package specifies the execution priority of the asynchronous thread that fetches data for a Remote Data Service (RDS) Recordset object.

class AdoEnums.AdcPropAsyncThreadPriority extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ABOVENORMAL;
  public static final int BELOWNORMAL;
  public static final int HIGHEST;
  public static final int LOWEST;
  public static final int NORMAL;
}


Fields (AdoEnums.AdcPropAsyncThreadPriority Class)

 Microsoft SDK for Java

AdoEnums.AdcPropAsyncThreadPriority Class Fields

The AdcPropAsyncThreadPriority class contains the fields shown in the following table.

Constant | Value | Description
LOWEST | 1 | Sets priority to the lowest possible.
BELOWNORMAL | 2 | Sets priority between lowest and normal.
NORMAL | 3 | Sets priority to normal.
ABOVENORMAL | 4 | Sets priority between normal and highest.
HIGHEST | 5 | Sets priority to the highest possible.


AdoEnums.AdcPropUpdateCriteria Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.AdcPropUpdateCriteria Class

The AdoEnums.AdcPropUpdateCriteria class of the com.ms.wfc.data package specifies which fields can be used to detect conflicts during an optimistic update of a row of the data source with a Remote Data Service (RDS) Recordset object. The constants specify that collisions should be detected if there is a change to the key field (that is, the data source row has been deleted), a change to any column in the data source row, a change to the same column of the data source row as the updated column of the recordset, or if the data source row has merely been accessed.

class AdoEnums.AdcPropUpdateCriteria extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ALLCOLS;
  public static final int KEY;
  public static final int TIMESTAMP;
  public static final int UPDCOLS;
}


Fields (AdoEnums.AdcPropUpdateCriteria Class)

 Microsoft SDK for Java

AdoEnums.AdcPropUpdateCriteria Class Fields

The AdcPropUpdateCriteria class contains the fields shown in the following table.

Constant | Value | Description
KEY | 0 | Uses changes to the key field.
ALLCOLS | 1 | Uses changes to any field.
UPDCOLS | 2 | Uses changes to the updated field.
TIMESTAMP | 3 | Uses changes timestamp.


AdoEnums.Affect Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.Affect Class

The AdoEnums.Affect class of the com.ms.wfc.data package specifies which records are affected by an operation.

class AdoEnums.Affect extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ALL;
  public static final int ALLCHAPTERS;
  public static final int CURRENT;
  public static final int GROUP;
}


Fields (AdoEnums.Affect Class)

 Microsoft SDK for Java

AdoEnums.Affect Class Fields

The Affect class contains the fields shown in the following table.

Constant | Value | Description
CURRENT | 1 | Affects only the current record.
GROUP | 2 | Affects only records that satisfy the current Filter property setting. You must set the Filter property to one of the valid predefined constants to use this option.
ALL | 3 | Affects all records in the Recordset.
ALLCHAPTERS | 4 | Affects records in all chapters of the Recordset.


AdoEnums.Bookmark Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.Bookmark Class

The AdoEnums.Bookmark class of the com.ms.wfc.data package specifies a bookmark indicating where the operation should begin.

class AdoEnums.Bookmark extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int CURRENT;
  public static final int FIRST;
  public static final int LAST;
}


Fields (AdoEnums.Bookmark Class)

 Microsoft SDK for Java

AdoEnums.Bookmark Class Fields

The Bookmark class contains the fields shown in the following table.

Constant | Value | Description
CURRENT | 0 | Starts at the current record.
FIRST | 1 | Starts at the first record.
LAST | 2 | Starts at the last record.


AdoEnums.CommandType Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.CommandType Class

The AdoEnums.CommandType class of the com.ms.wfc.data package specifies how a command argument should be interpreted.

class AdoEnums.CommandType extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int FILE;
  public static final int STOREDPROC;
  public static final int TABLE;
  public static final int TABLEDIRECT;
  public static final int TEXT;
  public static final int UNKNOWN;
  public static final int UNSPECIFIED;
}


Fields (AdoEnums.CommandType Class)

 Microsoft SDK for Java

AdoEnums.CommandType Class Fields

The CommandType class contains the fields shown in the following table.

Constant | Value | Description
UNSPECIFIED | -1 | Does not specify the command type argument.
UNKNOWN | 8 | Default. Indicates that the type of command in the CommandText property is not known.
TEXT | 1 | Evaluates CommandText as a textual definition of a command or stored procedure call.
TABLE | 2 | Evaluates CommandText as a table name whose columns are all returned by an internally generated SQL query.
STOREDPROC | 4 | Evaluates CommandText as a stored procedure name.
FILE | 256 | Evaluates CommandText as the file name of a persisted Recordset.
TABLEDIRECT | 512 | Evaluates CommandText as a table name whose columns are all returned.


AdoEnums.Compare Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.Compare Class

The AdoEnums.Compare class of the com.ms.wfc.data package specifies the relative position of two records represented by their bookmarks.

class AdoEnums.Compare extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int EQUAL;
  public static final int GREATERTHAN;
  public static final int LESSTHAN;
  public static final int NOTCOMPARABLE;
  public static final int NOTEQUAL;
}


Fields (AdoEnums.Compare Class)

 Microsoft SDK for Java

AdoEnums.Compare Class Fields

The Compare class contains the fields shown in the following table.

Constant | Value | Description
LESSTHAN | 0 | Indicates that the first bookmark is before the second.
EQUAL | 1 | Indicates that the bookmarks are equal.
GREATERTHAN | 2 | Indicates that the first bookmark is after the second.
NOTEQUAL | 3 | Indicates that the bookmarks are not equal and not ordered.
NOTCOMPARABLE | 4 | Indicates that the bookmarks cannot be compared.


AdoEnums.ConnectMode Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.ConnectMode Class

The AdoEnums.ConnectMode class of the com.ms.wfc.data package specifies the available permissions for modifying data in a Connection, opening a Record, or specifying values for the Mode property of the Record and Stream objects.

class AdoEnums.ConnectMode extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int READ;
  public static final int READWRITE;
  public static final int SHAREDENYNONE;
  public static final int SHAREDENYREAD;
  public static final int SHAREDENYWRITE;
  public static final int SHAREEXCLUSIVE;
  public static final int UNKNOWN;
  public static final int WRITE;
}


Fields (AdoEnums.ConnectMode Class)

 Microsoft SDK for Java

AdoEnums.ConnectMode Class Fields

The ConnectMode class contains the fields shown in the following table.

Constant | Value | Description
UNKNOWN | 0 | Default. Indicates that the permissions have not yet been set or cannot be determined.
READ | 1 | Indicates read-only permissions.
WRITE | 2 | Indicates write-only permissions.
READWRITE | 3 | Indicates read/write permissions.
SHAREDENYREAD | 4 | Prevents others from opening a connection with read permissions.
SHAREDENYWRITE | 8 | Prevents others from opening a connection with write permissions.
SHAREEXCLUSIVE | 12 | Prevents others from opening a connection.
SHAREDENYNONE | 16 | Allows others to open a connection with any permissions. Neither read nor write access can be denied to others.


AdoEnums.ConnectOption Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.ConnectOption Class

The AdoEnums.ConnectOption class of the com.ms.wfc.data package specifies whether the Open method of a Connection object should return after (synchronously) or before (asynchronously) the connection is established.

class AdoEnums.ConnectOption extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ASYNCCONNECT;
}


Fields (AdoEnums.ConnectOption Class)

 Microsoft SDK for Java

AdoEnums.ConnectOption Class Fields

The ConnectOption class contains the field shown in the following table.

Constant | Value | Description
ASYNCCONNECT | 16 | Opens the connection asynchronously. The ConnectComplete event may be used to determine when the connection is available.


AdoEnums.ConnectPrompt Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.ConnectPrompt Class

The AdoEnums.ConnectPrompt class of the com.ms.wfc.data package specifies whether a dialog box should be displayed to prompt for missing parameters when opening a connection to a data source.

class AdoEnums.ConnectPrompt extends com.ms.wfc.core.Enum
{
  // Fields
public static final int ALWAYS;
public static final int COMPLETE;
public static final int COMPLETEREQUIRED;
public static final int NEVER;
}


Fields (AdoEnums.ConnectPrompt Class)

 Microsoft SDK for Java

AdoEnums.ConnectPrompt Class Fields

The ConnectPrompt class contains the fields shown in the following table.

Constant | Value | Description
ALWAYS | 1 | Prompts always.
COMPLETE | 2 | Prompts if more information is required.
COMPLETEREQUIRED | 3 | Prompts if more information is required but optional parameters are not allowed.
NEVER | 4 | Never prompts.


AdoEnums.CursorLocation Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.CursorLocation Class

The AdoEnums.CursorLocation class of the com.ms.wfc.data package specifies the location of the cursor engine (a database element that controls record navigation), updatability of data, and the visibility of changes made to the database by other users.

class AdoEnums.CursorLocation extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int CLIENT;
  public static final int NONE;
  public static final int SERVER;
}


Fields (AdoEnums.CursorLocation Class)

 Microsoft SDK for Java

AdoEnums.CursorLocation Class Fields

The CursorLocation class contains the fields shown in the following table.

Constant | Value | Description
NONE | 1 | Does not use cursor services. (This constant is obsolete and appears solely for the sake of backward compatibility.)
CLIENT | 2 | Uses client-side cursors supplied by a local cursor library. Local cursor services often will allow many features that driver-supplied cursors may not, so using this setting may provide an advantage with respect to features that will be enabled. For backward compatibility, the synonym adUseClientBatch is also supported.
SERVER | 3 | Default. Uses data-provider or driver-supplied cursors. These cursors are sometimes very flexible and allow for additional sensitivity to changes others make to the data source. However, some features of the Microsoft Client Cursor Provider (such as disassociated Recordset objects) cannot be simulated with server-side cursors and these features will be unavailable with this setting.


AdoEnums.CursorOption Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.CursorOption Class

The AdoEnums.CursorOption class of the com.ms.wfc.data package specifies what functionality the com.ms.wfc.data.Recordset.supports method should test for.

class AdoEnums.CursorOption extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ADDNEW;
  public static final int APPROXPOSITION;
  public static final int BOOKMARK;
  public static final int DELETE;
  public static final int FIND;
  public static final int HOLDRECORDS;
  public static final int MOVEPREVIOUS;
  public static final int NOTIFY;
  public static final int RESYNC;
  public static final int UPDATE;
  public static final int UPDATEBATCH;
}


Fields (AdoEnums.CursorOption Class)

 Microsoft SDK for Java

AdoEnums.CursorOption Class Fields

The CursorOption class contains the fields shown in the following table.

Constant | Value | Description
HOLDRECORDS | 0x100 | Retrieves more records or changes the next retrieve position without committing all pending changes.
UPDATEBATCH | 0x10000 | Uses batch updating (updateBatch and cancelBatch methods) to transmit groups of changes to the provider.
ADDNEW | 0x1000400 | Uses the addNew method to add new records.
DELETE | 0x1000800 | Uses the delete method to delete records.
UPDATE | 0x1008000 | Uses the update method to modify existing data.
MOVEPREVIOUS | 0x200 | Uses the moveFirst and movePrevious, move, and getRows methods to move the current record position backward without requiring bookmarks.
BOOKMARK | 0x2000 | Uses the getBookmark property to gain access to specific records.
RESYNC | 0x20000 | Updates the cursor with the data that is visible in the underlying database using the resync method.
APPROXPOSITION | 0x4000 | Reads and sets the getAbsolutePosition and getAbsolutePage properties.
NOTIFY | 0x40000 | Indicates that the underlying data provider supports notifications (which determines whether Recordset events are supported).
FIND | 0x80000 | Uses the find method to locate a row in a Recordset.


AdoEnums.CursorType Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.CursorType Class

The AdoEnums.CursorType class of the com.ms.wfc.data package specifies the type of cursor used in a com.ms.wfc.data.Recordset object.

class AdoEnums.CursorType extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int DYNAMIC;
  public static final int FORWARDONLY;
  public static final int KEYSET;
  public static final int STATIC;
  public static final int UNSPECIFIED;
}


AdoEnums.CursorType class;

 Microsoft SDK for Java

AdoEnums.CursorType Class Fields

The CursorType class contains the fields shown in the following table.

Constant | Value | Description
UNSPECIFIED | -1 | Does not specify the type of cursor.
FORWARDONLY | 0 | Default. Uses a forward-only cursor. Identical to a static cursor, except that you can only scroll forward through records. This improves performance in situations when you need to make only a single pass through a Recordset.
KEYSET | 1 | Uses a keyset cursor. Like a dynamic cursor, except that you can't see records that other users add, although records that other users delete are inaccessible from your recordset. Data changes by other users are still visible.
DYNAMIC | 2 | Uses a dynamic cursor. Additions, changes, and deletions by other users are visible, and all types of movement through the recordset are allowed, except for bookmarks, if the provider doesn't support them.
STATIC | 3 | Uses a static cursor. A static copy of a set of records that you can use to find data or generate reports. Additions, changes, or deletions by other users are not visible.


AdoEnums.DataType Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.DataType Class

The AdoEnums.DataType class of the com.ms.wfc.data package specifies the data type of a field, parameter, or object. The corresponding OLE DB type indicator is shown in parentheses in the DataType Class Fields table.

class AdoEnums.DataType extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int BIGINT;
  public static final int BINARY;
  public static final int BOOLEAN;
  public static final int BSTR;
  public static final int CHAPTER;
  public static final int CHAR;
  public static final int CURRENCY;
  public static final int DATE;
  public static final int DBDATE;
  public static final int DBTIME;
  public static final int DBTIMESTAMP;
  public static final int DECIMAL;
  public static final int DOUBLE;
  public static final int EMPTY;
  public static final int ERROR;
  public static final int FILETIME;
  public static final int GUID;
  public static final int IDISPATCH;
  public static final int INTEGER;
  public static final int IUNKNOWN;
  public static final int LONGVARBINARY;
  public static final int LONGVARCHAR;
  public static final int LONGVARWCHAR;
  public static final int NUMERIC;
  public static final int PROPVARIANT;
  public static final int SINGLE;
  public static final int SMALLINT;
  public static final int TINYINT;
  public static final int UNSIGNEDBIGINT;
  public static final int UNSIGNEDINT;
  public static final int UNSIGNEDSMALLINT;
  public static final int UNSIGNEDTINYINT;
  public static final int USERDEFINED;
  public static final int VARBINARY;
  public static final int VARCHAR;
  public static final int VARIANT;
  public static final int VARNUMERIC;
  public static final int VARWCHAR;
  public static final int WCHAR;
}


Fields (AdoEnums.DataType Class)

 Microsoft SDK for Java

AdoEnums.DataType Class Fields

The DataType class contains the fields shown in the following table.

Constant | Value | Description
EMPTY | 0 | Specifies no value was specified (DBTYPE_EMPTY).
SMALLINT | 2 | Indicates a 2-byte signed integer (DBTYPE_I2).
INTEGER | 3 | Indicates a 4-byte signed integer (DBTYPE_I4).
SINGLE | 4 | Indicates a single-precision floating-point value (DBTYPE_R4).
DOUBLE | 5 | Indicates a double-precision floating-point value (DBTYPE_R8).
CURRENCY | 6 | Indicates a currency value (DBTYPE_CY). Currency is a fixed-point number with four digits to the right of the decimal point. It is stored in an 8-byte signed integer scaled by 10,000.
DATE | 7 | Indicates a date value (DBTYPE_DATE). A date is stored as a Double, the whole part of which is the number of days since December 30, 1899, and the fractional part of which is the fraction of a day.
BSTR | 8 | Indicates a null-terminated character string (Unicode) (DBTYPE_BSTR).
IDISPATCH | 9 | Indicates a pointer to an IDispatch interface on an OLE object (DBTYPE_IDISPATCH). Note This data type is currently not supported by ADO (Microsoft® ActiveX Data Objects). Usage may cause unpredictable results.
ERROR | 10 | Indicates a 32-bit error code (DBTYPE_ERROR).
BOOLEAN | 11 | Indicates a boolean value (DBTYPE_BOOL).
VARIANT | 12 | Indicates an Automation Variant (DBTYPE_VARIANT). Note This data type is currently not supported by ADO. Usage may cause unpredictable results.
IUNKNOWN | 13 | Indicates a pointer to an IUnknown interface on an OLE object (DBTYPE_IUNKNOWN). Note This data type is currently not supported by ADO. Usage may cause unpredictable results.
DECIMAL | 14 | Indicates an exact numeric value with a fixed precision and scale (DBTYPE_DECIMAL).
TINYINT | 16 | Indicates a 1-byte signed integer (DBTYPE_I1).
UNSIGNEDTINYINT | 17 | Indicates a 1-byte unsigned integer (DBTYPE_UI1).
UNSIGNEDSMALLINT | 18 | Indicates a 2-byte unsigned integer (DBTYPE_UI2).
UNSIGNEDINT | 19 | Indicates a 4-byte unsigned integer (DBTYPE_UI4).
BIGINT | 20 | Indicates an 8-byte signed integer (DBTYPE_I8).
UNSIGNEDBIGINT | 21 | Indicates an 8-byte unsigned integer (DBTYPE_UI8).
FILETIME | 64 | Indicates a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (DBTYPE_FILETIME).
GUID | 72 | Indicates a globally unique identifier (GUID) (DBTYPE_GUID).
BINARY | 128 | Indicates a binary value (DBTYPE_BYTES).
CHAR | 129 | Indicates a String value (DBTYPE_STR).
WCHAR | 130 | Indicates a null-terminated Unicode character string (DBTYPE_WSTR).
NUMERIC | 131 | Indicates an exact numeric value with a fixed precision and scale (DBTYPE_NUMERIC).
USERDEFINED | 132 | Indicates a user-defined variable (DBTYPE_UDT).
DBDATE | 133 | Indicates a date value (yyyymmdd) (DBTYPE_DBDATE).
DBTIME | 134 | Indicates a time value (hhmmss) (DBTYPE_DBTIME).
DBTIMESTAMP | 135 | Indicates a date-time stamp (yyyymmddhhmmss plus a fraction in billionths) (DBTYPE_DBTIMESTAMP).
CHAPTER | 136 | Indicates a four-byte chapter value used to identify rows in a child rowset (DBTYPE_HCHAPTER).
PROPVARIANT | 138 | Indicates an Automation PROPVARIANT (DBTYPE_PROP_VARIANT).
VARNUMERIC | 139 | Indicates a numeric value (Parameter object only).
VARCHAR | 200 | Indicates a String value (Parameter object only).
LONGVARCHAR | 201 | Indicates a long String value (Parameter object only).
VARWCHAR | 202 | Indicates a null-terminated Unicode character string (Parameter object only).
LONGVARWCHAR | 203 | Indicates a long null-terminated string value (Parameter object only).
VARBINARY | 204 | Indicates a binary value (Parameter object only).
LONGVARBINARY | 205 | Indicates a long binary value (Parameter object only).


AdoEnums.EditMode Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.EditMode Class

The AdoEnums.EditMode class of the com.ms.wfc.data package specifies the editing status of a record.

class AdoEnums.EditMode extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ADD;
  public static final int DELETE;
  public static final int INPROGRESS;
  public static final int NONE;
}


AdoEnums.EditMode class;

 Microsoft SDK for Java

AdoEnums.EditMode Class Fields

The EditMode class contains the fields shown in the following table.

Constant | Value | Description
NONE | 0 | Indicates that no editing operation is in progress.
INPROGRESS | 1 | Indicates that data in the current record has been modified but not saved.
ADD | 2 | Indicates that the addNew method has been called, and the current record in the copy buffer is a new record that hasn't been saved in the database.
DELETE | 4 | Indicates that the current record has been deleted.


AdoEnums.ErrorValue Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.ErrorValue Class

The AdoEnums.ErrorValue class of the com.ms.wfc.data package specifies the type of ADO runtime error.

class AdoEnums.ErrorValue extends com.ms.wfc.core.Enum
{
  // Fields
public static final int BOUNDTOCOMMAND;
public static final int DATACONVERSION;
public static final int FEATURENOTAVAILABLE;
public static final int ILLEGALOPERATION;
public static final int INTRANSACTION;
public static final int INVALIDARGUMENT;
public static final int INVALIDCONNECTION;
public static final int INVALIDPARAMINFO;
public static final int ITEMNOTFOUND;
public static final int NOCURRENTRECORD;
public static final int NOTEXECUTING;
public static final int NOTREENTRANT;
public static final int OBJECTCLOSED;
public static final int OBJECTINCOLLECTION;
public static final int OBJECTNOTSET;
public static final int OBJECTOPEN;
public static final int OPERATIONCANCELLED;
public static final int PROVIDERNOTFOUND;
public static final int STILLCONNECTING;
public static final int STILLEXECUTING;
}


Fields (AdoEnums.ErrorValue Class)

 Microsoft SDK for Java

AdoEnums.ErrorValue Class Fields

The ErrorValue class contains the fields shown in the following table.

Constant | Value | Description
INVALIDARGUMENT | 3001 | Indicates that the application is using arguments that are of the wrong type, are out of acceptable range, or are in conflict with one another.
NOCURRENTRECORD | 3021 | Indicates that either BOF or EOF is True, or the current record has been deleted. The operation requested by the application requires a current record.
ILLEGALOPERATION | 3219 | Indicates that the operation requested by the application is not allowed in this context.
INTRANSACTION | 3246 | Indicates that the application cannot explicitly close a Connection object while in the middle of a transaction.
FEATURENOTAVAILABLE | 3251 | Indicates that the operation requested by the application is not supported by the provider.
ITEMNOTFOUND | 3265 | Indicates that ADO could not find the object in the collection corresponding to the name or ordinal reference requested by the application.
OBJECTINCOLLECTION | 3367 | Indicates that the object is already in the collection and cannot be appended.
OBJECTNOTSET | 3420 | Indicates that the object referenced by the application no longer points to a valid object.
DATACONVERSION | 3421 | Indicates that the application is using a value of the wrong type for the current operation.
OBJECTCLOSED | 3704 | Indicates that the operation requested by the application is not allowed if the object is closed.
OBJECTOPEN | 3705 | Indicates that the operation requested by the application is not allowed if the object is open.
PROVIDERNOTFOUND | 3706 | Indicates that ADO could not find the specified provider.
BOUNDTOCOMMAND | 3707 | Indicates that the application cannot change the ActiveConnection property of a Recordset object with a Command object as its source.
INVALIDPARAMINFO | 3708 | Indicates that the application has improperly defined a Parameter object.
INVALIDCONNECTION | 3709 | Indicates that the application requested an operation on an object with a reference to a closed or invalid Connection object.
NOTREENTRANT | 3710 | Indicates that code that would cause an event to reoccur cannot be executed within that event.
STILLEXECUTING | 3711 | Indicates that ADO was still executing a command when another operation was requested.
OPERATIONCANCELLED | 3712 | Occurs when an ADO operation has been canceled.
STILLCONNECTING | 3713 | Indicates that ADO was still connecting to the data source when another operation was requested.
NOTEXECUTING | 3715 | Indicates that an ADO operation that was not executed was requested to be canceled.


AdoEnums.EventReason Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.EventReason Class

The AdoEnums.EventReason class of the com.ms.wfc.data package specifies the reason that caused an event to occur.

class AdoEnums.EventReason extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ADDNEW;
  public static final int CLOSE;
  public static final int DELETE;
  public static final int FIRSTCHANGE;
  public static final int MOVE;
  public static final int MOVEFIRST;
  public static final int MOVELAST;
  public static final int MOVENEXT;
  public static final int MOVEPREVIOUS;
  public static final int REQUERY;
  public static final int RESYNCH;
  public static final int UNDOADDNEW;
  public static final int UNDODELETE;
  public static final int UNDOUPDATE;
  public static final int UPDATE;
}


Fields (AdoEnums.EventReason Class)

 Microsoft SDK for Java

AdoEnums.EventReason Class Fields

The EventReason class contains the fields shown in the following table.

Constant | Value | Description
ADDNEW | 1 | Added a new record.
DELETE | 2 | Deleted a record.
UPDATE | 3 | Updated an existing record.
UNDOUPDATE | 4 | Reversed an update to an existing record.
UNDOADDNEW | 5 | Reversed the adding of a new record.
UNDODELETE | 6 | Reversed the deletion of a record.
REQUERY | 7 | Requeried the Recordset.
RESYNCH | 8 | Resynchronized the Recordset with the database.
CLOSE | 9 | Closed the Recordset.
MOVE | 10 | Moved the record pointer within the Recordset.
FIRSTCHANGE | 11 | Made the first change to a record.
MOVEFIRST | 12 | Moved the record pointer to the first record in the Recordset.
MOVENEXT | 13 | Moved the record pointer to the next record in the Recordset.
MOVEPREVIOUS | 14 | Moved the record pointer to the previous record in the Recordset.
MOVELAST | 15 | Moved the record pointer to the last record in the Recordset.


AdoEnums.EventStatus Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.EventStatus Class

The AdoEnums.EventStatus class of the com.ms.wfc.data package specifies the current status of the execution of an event.

class AdoEnums.EventStatus extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int CANCEL;
  public static final int CANTDENY;
  public static final int ERRORSOCCURRED;
  public static final int OK;
  public static final int UNWANTEDEVENT;
}


Fields (AdoEnums.EventStatus Class)

 Microsoft SDK for Java

AdoEnums.EventStatus Class Fields

The EventStatus class contains the fields shown in the following table.

Constant | Value | Description
OK | 1 | Indicates that the operation that caused the event was successful.
ERRORSOCCURRED | 2 | Indicates that the operation that caused the event failed due to an error or errors.
CANTDENY | 3 | Indicates that the operation cannot request cancellation of the pending operation.
CANCEL | 4 | Requests cancellation of the operation that caused the event to occur.
UNWANTEDEVENT | 5 | Prevents subsequent notifications before the event method has finished executing.


AdoEnums.ExecuteOption Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.ExecuteOption Class

The AdoEnums.ExecuteOption class of the com.ms.wfc.data package specifies how a provider should execute a command.

class AdoEnums.ExecuteOption extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ASYNCEXECUTE;
  public static final int ASYNCFETCH;
  public static final int ASYNCFETCHNONBLOCKING;
  public static final int NORECORDS;
  public static final int UNSPECIFIED;
}


Fields (AdoEnums.ExecuteOption Class)

 Microsoft SDK for Java

AdoEnums.ExecuteOption Class Fields

The ExecuteOption class contains the fields shown in the following table.

Constant | Value | Description
UNSPECIFIED | -1 | Indicates that the command is unspecified.
ASYNCEXECUTE | 0x10 | Indicates that the command should execute asynchronously.
ASYNCFETCH | 0x20 | Indicates that the remaining rows after the initial quantity specified in getCacheSize should be fetched asynchronously.
ASYNCFETCHNONBLOCKING | 0x40 | Indicates that the main thread never blocks while fetching. If the requested row has not been fetched, the current row automatically moves to the end of the file. If you open a Recordset from a Stream containing a persisted Recordset, ASYNCFETCHNONBLOCKING will not have an effect; the fetch will be synchronous and blocking.
NORECORDS | 0x80 | Indicates that the command text is a command or stored procedure that does not return rows (for example, a command that only inserts data). If any rows are retrieved, they are discarded and not returned. Always combined with CommandType values TEXT or STOREDPROC.


AdoEnums.FieldAttribute Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.FieldAttribute Class

The AdoEnums.FieldAttribute class of the com.ms.wfc.data package specifies one or more attributes, or characteristics, of a Field object.

class AdoEnums.FieldAttribute extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int CACHEDEFERRED;
  public static final int FIXED;
  public static final int ISNULLABLE;
  public static final int KEYCOLUMN;
  public static final int LONG;
  public static final int MAYBENULL;
  public static final int MAYDEFER;
  public static final int NEGATIVESCALE;
  public static final int ROWID;
  public static final int ROWVERSION;
  public static final int UNKNOWNUPDATABLE;
  public static final int UNSPECIFIED;
  public static final int UPDATABLE;
}


Fields (AdoEnums.FieldAttribute Class)

 Microsoft SDK for Java

AdoEnums.FieldAttribute Class Fields

The FieldAttribute class contains the fields shown in the following table.

Constant | Value | Description
UNSPECIFIED | -1 | Does not specify the field attributes.
MAYDEFER | 0x2 | Indicates that the field is deferred; that is, the field values are not retrieved from the data source with the whole record, but only when you explicitly access them.
UPDATABLE | 0x4 | Indicates that you can write to the field.
UNKNOWNUPDATABLE | 0x8 | Indicates that the provider cannot determine if you can write to the field.
FIXED | 0x10 | Indicates that the field contains fixed-length data.
ISNULLABLE | 0x20 | Indicates that the field accepts Null values.
MAYBENULL | 0x40 | Indicates that you can read Null values from the field.
LONG | 0x80 | Indicates that the field is a long binary field. Also indicates that you can use the com.ms.wfc.data.Field.appendChunk, com.ms.wfc.data.Field.getByteChunk, com.ms.wfc.data.Field.getCharChunk, and com.ms.wfc.data.Field.getStringChunk methods.
ROWID | 0x100 | Indicates that the field contains a persistent row identifier that cannot be written to and has no meaningful value except to identify the row (such as a record number, unique identifier, and so forth).
ROWVERSION | 0x200 | Indicates that the field contains some kind of time or date stamp used to track updates.
CACHEDEFERRED | 0x1000 | Indicates that the provider caches field values and that subsequent reads are done from the cache.
NEGATIVESCALE | 0x4000 | Indicates that the field represents numeric value from a column that supports negative scale values. The scale is specified by the com.ms.wfc.data.Field.setNumericScale property.
KEYCOLUMN | 0x8000 | Indicates that the field is the primary key of the underlying rowset. Also can indicate that the field is part of a compound primary key.


AdoEnums.FilterGroup Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.FilterGroup Class

The AdoEnums.FilterGroup class of the com.ms.wfc.data package specifies the group of records to be filtered from a Recordset.

class AdoEnums.FilterGroup extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int AFFECTEDRECORDS;
  public static final int CONFLICTINGRECORDS;
  public static final int FETCHEDRECORDS;
  public static final int NONE;
  public static final int PENDINGRECORDS;
}


Fields (AdoEnums.FilterGroup Class)

 Microsoft SDK for Java

AdoEnums.FilterGroup Class Fields

The FilterGroup class contains the fields shown in the following table.

Constant | Value | Description
NONE | 0 | Removes the current filter and restores all records to view.
PENDINGRECORDS | 1 | Allows you to view only records that have changed but have not yet been sent to the server. Applicable only for batch update mode.
AFFECTEDRECORDS | 2 | Allows you to view only records affected by the last com.ms.wfc.data.Recordset.delete, resync, updateBatch, or cancelBatch call.
FETCHEDRECORDS | 3 | Allows you to view records in the current cache; that is, the results of the last call to retrieve records from the database.
CONFLICTINGRECORDS | 5 | Allows you to view the records that failed the last batch update attempt.


AdoEnums.GetRowsOption Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.GetRowsOption Class

The AdoEnums.GetRowsOption class of the com.ms.wfc.data package specifies how many records to retrieve from a Recordset.

class AdoEnums.GetRowsOption extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int REST;
}


Fields (AdoEnums.GetRowsOption Class)

 Microsoft SDK for Java

AdoEnums.GetRowsOption Class Fields

The GetRowsOption class contains the following field.

Constant | Value | Description
REST | -1 | Retrieves the rest of the records in the Recordset, from either the current position or a bookmark specified by the bmkStart parameter of the Recordset.getRows method.


AdoEnums.IsolationLevel Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.IsolationLevel Class

The AdoEnums.IsolationLevel class of the com.ms.wfc.data package specifies the level of transaction isolation for a Connection object.

class AdoEnums.IsolationLevel extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int BROWSE;
  public static final int CHAOS;
  public static final int CURSORSTABILITY;
  public static final int ISOLATED;
  public static final int READCOMMITTED;
  public static final int READUNCOMMITTED;
  public static final int REPEATABLEREAD;
  public static final int SERIALIZABLE;
  public static final int UNSPECIFIED;
}


Fields (AdoEnums.IsolationLevel Class)

 Microsoft SDK for Java

AdoEnums.IsolationLevel Class Fields

The IsolationLevel class contains the fields shown in the following table.

Constant | Value | Description
UNSPECIFIED | -1 | Indicates that the provider is using a different isolation level than specified, but that the level cannot be determined.
CHAOS | 16 | Indicates that you cannot overwrite pending changes from more highly isolated transactions.
BROWSE | 256 | Indicates that from one transaction you can view uncommitted changes in other transactions.
READUNCOMMITTED | 256 | Same as BROWSE.
CURSORSTABILITY | 4096 | Indicates that from one transaction you can view changes in other transactions only after they've been committed.
READCOMMITTED | 4096 | Same as CURSORSTABILITY.
REPEATABLEREAD | 65536 | Indicates that from one transaction you cannot see changes made in other transactions, but that requerying can bring new recordsets.
ISOLATED | 1048576 | Indicates that transactions are conducted in isolation of other transactions.
SERIALIZABLE | 1048576 | Same as ISOLATED.


AdoEnums.LockType Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.LockType Class

The AdoEnums.LockType class of the com.ms.wfc.data package specifies the type of lock placed on records during editing.

class AdoEnums.LockType extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int BATCHOPTIMISTIC;
  public static final int OPTIMISTIC;
  public static final int PESSIMISTIC;
  public static final int READONLY;
  public static final int UNSPECIFIED;
}


Fields (AdoEnums.LockType Class)

 Microsoft SDK for Java

AdoEnums.LockType Class Fields

The LockType class contains the fields shown in the following table.

Constant | Value | Description
UNSPECIFIED | -1 | Does not specify a type of lock. For clones, the clone is created with the same lock type as the original.
READONLY | 1 | Indicates read-only. You cannot alter the data.
PESSIMISTIC | 2 | Indicates pessimistic locking, record by record—the provider does what is necessary to ensure successful editing of the records, usually by locking records at the data source immediately upon editing.
OPTIMISTIC | 3 | Indicates optimistic locking, record by record. The provider uses optimistic locking, locking records only when you call the Recordset.update method.
BATCHOPTIMISTIC | 4 | Indicates optimistic batch updates. Required for batch update mode as opposed to immediate update mode.


AdoEnums.MarshalOptions Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.MarshalOptions Class

The AdoEnums.MarshalOptions class of the com.ms.wfc.data package specifies which records should be returned to the server.

class AdoEnums.MarshalOptions extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ALL;
  public static final int MODIFIEDONLY;
}


Fields (AdoEnums.MarshalOptions Class)

 Microsoft SDK for Java

AdoEnums.MarshalOptions Class Fields

The MarshalOptions class contains the fields shown in the following table.

Constant | Value | Description
ALL | 0 | Default. Returns all rows to the server.
MODIFIEDONLY | 1 | Returns only modified rows to the server.


AdoEnums.ObjectState Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.ObjectState Class

The AdoEnums.ObjectState class of the com.ms.wfc.data package specifies whether an object is open or closed, connecting to a data source, executing a command, or fetching data.

class AdoEnums.ObjectState extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int CLOSED;
  public static final int CONNECTING;
  public static final int EXECUTING;
  public static final int FETCHING;
  public static final int OPEN;
}


Fields (AdoEnums.ObjectState Class)

 Microsoft SDK for Java

AdoEnums.ObjectState Class Fields

The ObjectState class contains the fields shown in the following table.

Constant | Value | Description
CLOSED | 0 | Indicates that the object is closed.
OPEN | 1 | Indicates that the object is open.
CONNECTING | 2 | Indicates that the object is connecting.
EXECUTING | 4 | Indicates that the object is executing.
FETCHING | 8 | Indicates that the rows of the object are being fetched.


AdoEnums.ParameterAttributes Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.ParameterAttributes Class

The AdoEnums.ParameterAttributes class of the com.ms.wfc.data package specifies the attributes of a Parameter object.

class AdoEnums.ParameterAttributes extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int LONG;
  public static final int NULLABLE;
  public static final int SIGNED;
}


Fields (AdoEnums.ParameterAttributes Class)

 Microsoft SDK for Java

AdoEnums.ParameterAttributes Class Fields

The ParameterAttributes class contains the fields shown in the following table.

Constant | Value | Description
SIGNED | 16 | Indicates that the parameter accepts signed values.
NULLABLE | 64 | Indicates that the parameter accepts Null values.
LONG | 128 | Indicates that the parameter accepts long binary data.


AdoEnums.ParameterDirection Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.ParameterDirection Class

The AdoEnums.ParameterDirection class of the com.ms.wfc.data package specifies whether the Parameter represents an input parameter, an output parameter, or both, or if the parameter is the return value from a stored procedure.

class AdoEnums.ParameterDirection extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int INPUT;
  public static final int INPUTOUTPUT;
  public static final int OUTPUT;
  public static final int RETURNVALUE;
  public static final int UNKNOWN;
}


Fields (AdoEnums.ParameterDirection Class)

 Microsoft SDK for Java

AdoEnums.ParameterDirection Class Fields

The ParameterDirection class contains the fields shown in the following table.

Constant | Value | Description
UNKNOWN | 0 | Indicates parameter direction is unknown.
INPUT | 1 | Default. Indicates an input parameter.
OUTPUT | 2 | Indicates an output parameter.
INPUTOUTPUT | 3 | Indicates both an input and output parameter.
RETURNVALUE | 4 | Indicates a return value.


AdoEnums.PersistFormat Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.PersistFormat Class

The AdoEnums.PersistFormat class of the com.ms.wfc.data package specifies the format in which to save a Recordset.

class AdoEnums.PersistFormat extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ADTG;
  public static final int XML;
}


Fields (AdoEnums.PersistFormat Class)

 Microsoft SDK for Java

AdoEnums.PersistFormat Class Fields

The PersistFormat class contains the fields shown in the following table.

Constant | Value | Description
ADTG | 0 | Indicates Microsoft Advanced Data TableGram format.
XML | 1 | Indicates Extended Markup Language format.


AdoEnums.Position Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.Position Class

The AdoEnums.Position class of the com.ms.wfc.data package specifies the current position of the record pointer within a Recordset.

class AdoEnums.Position extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int BOF;
  public static final int EOF;
  public static final int UNKNOWN;
}


Fields (AdoEnums.Position Class)

 Microsoft SDK for Java

AdoEnums.Position Class Fields

The Position class contains the fields shown in the following table.

Constant | Value | Description
UNKNOWN | -1 | Indicates that the Recordset is empty, the current position is unknown, or the provider does not support getAbsolutePage or getAbsolutePosition.
BOF | -2 | Indicates that the current record pointer is at BOF (that is, getBOF is True).
EOF | -3 | Indicates that the current record pointer is at EOF (that is, getEOF is True).


AdoEnums.PropertyAttributes Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.PropertyAttributes Class

The AdoEnums.PropertyAttributes class of the com.ms.wfc.data package specifies the attributes of an AdoProperties object.

class AdoEnums.PropertyAttributes extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int NOTSUPPORTED;
  public static final int OPTIONAL;
  public static final int READ;
  public static final int REQUIRED;
  public static final int WRITE;
}


Fields (AdoEnums.PropertyAttributes Class)

 Microsoft SDK for Java

AdoEnums.PropertyAttributes Class Fields

The PropertyAttributes class contains the fields shown in the following table.

Constant | Value | Description
NOTSUPPORTED | 0 | Indicates that the property is not supported by the provider.
REQUIRED | 1 | Indicates that the user must specify a value for this property before the data source is initialized.
OPTIONAL | 2 | Indicates that the user does not need to specify a value for this property before the data source is initialized.
READ | 512 | Indicates that the user can read the property.
WRITE | 1024 | Indicates that the user can set the property.


AdoEnums.RecordStatus Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.RecordStatus Class

The AdoEnums.RecordStatus class of the com.ms.wfc.data package specifies the status of a record with regard to batch updates and other bulk operations.

class AdoEnums.RecordStatus extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int CANCELED;
  public static final int CANTRELEASE;
  public static final int CONCURRENCYVIOLATION;
  public static final int DBDELETED;
  public static final int DELETED;
  public static final int INTEGRITYVIOLATION;
  public static final int INVALID;
  public static final int MAXCHANGESEXCEEDED;
  public static final int MODIFIED;
  public static final int MULTIPLECHANGES;
  public static final int NEW;
  public static final int OBJECTOPEN;
  public static final int OK;
  public static final int OUTOFMEMORY;
  public static final int PENDINGCHANGES;
  public static final int PERMISSIONDENIED;
  public static final int SCHEMAVIOLATION;
  public static final int UNMODIFIED;
}


Fields (AdoEnums.RecordStatus Class)

 Microsoft SDK for Java

AdoEnums.RecordStatus Class Fields

The RecordStatus class contains the fields shown in the following table.

Constant | Value | Description
OK | 0 | Indicates that the record was successfully updated.
NEW | 0x1 | Indicates that the record is new.
MODIFIED | 0x2 | Indicates that the record was modified.
DELETED | 0x4 | Indicates that the record was deleted.
UNMODIFIED | 0x8 | Indicates that the record was not modified.
INVALID | 0x10 | Indicates that the record was not saved because its bookmark is invalid.
MULTIPLECHANGES | 0x40 | Indicates that the record was not saved because it would have affected multiple records.
PENDINGCHANGES | 0x80 | Indicates that the record was not saved because it refers to a pending insert.
CANCELED | 0x100 | Indicates that the record was not saved because the operation was canceled.
CANTRELEASE | 0x400 | Indicates that the new record was not saved because of existing record locks.
CONCURRENCYVIOLATION | 0x800 | Indicates that the record was not saved because optimistic concurrency was in use.
INTEGRITYVIOLATION | 0x1000 | Indicates that the record was not saved because the user violated integrity constraints.
MAXCHANGESEXCEEDED | 0x2000 | Indicates that the record was not saved because there were too many pending changes.
OBJECTOPEN | 0x4000 | Indicates that the record was not saved because of a conflict with an open storage object.
OUTOFMEMORY | 0x8000 | Indicates that the record was not saved because the computer has run out of memory.
PERMISSIONDENIED | 0x10000 | Indicates that the record was not saved because the user has insufficient permissions.
SCHEMAVIOLATION | 0x20000 | Indicates that the record was not saved because it violates the structure of the underlying database.
DBDELETED | 0x40000 | Indicates that the record has already been deleted from the data source.


AdoEnums.Resync Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.Resync Class

The AdoEnums.Resync class of the com.ms.wfc.data package specifies whether underlying values are overwritten by a call to Resync.

class AdoEnums.Resync extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ALLVALUES;
  public static final int UNDERLYINGVALUES;
}


Fields (AdoEnums.Resync Class)

 Microsoft SDK for Java

AdoEnums.Resync Class Fields

The Resync class contains the fields shown in the following table.

Constant | Value | Description
ALLVALUES | 2 | Default. Overwrites data, and pending updates are canceled.
UNDERLYINGVALUES | 1 | Does not overwrite data, and pending updates are not canceled.


AdoEnums.Schema Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.Schema Class

The AdoEnums.Schema class of the com.ms.wfc.data package specifies the type of schema Recordset to be retrieved by the OpenSchema method.

Additional information about the function and columns returned for each ADO constant can be found in topics of the OLE DB Programmer's Reference that deal with schema rowsets.

Additional information about the function and columns returned for each ADOMD constant can be found in topics of the OLE DB for OLAP Programmer's Reference.

Translate the data types of columns in the OLE DB documentation to ADO data types by referring to the Description section of the ADO DataType topic. For example, an OLE DB data type of DBTYPE_WSTR is equivalent to an ADO data type of WCHAR.

ADO generates schema-like results for the constants DBINFOKEYWORDS and DBINFOLITERALS. ADO creates a Recordset, then fills each row with the values returned respectively by the IDBInfo::GetKeywords and IDBInfo::GetLiteralInfo methods. Additional information about these methods can be found in the OLE DB Programmer's Reference.

class AdoEnums.Schema extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ASSERTS;
  public static final int CATALOGS;
  public static final int CHARACTERSETS;
  public static final int CHECKCONSTRAINTS;
  public static final int COLLATIONS;
  public static final int COLUMNPRIVILEGES;
  public static final int COLUMNS;
  public static final int COLUMNSDOMAINUSAGE;
  public static final int CONSTRAINTCOLUMNUSAGE;
  public static final int CONSTRAINTTABLEUSAGE;
  public static final int CUBES;
  public static final int DBINFOKEYWORDS;
  public static final int DBINFOLITERALS;
  public static final int DIMENSIONS;
  public static final int FOREIGNKEYS;
  public static final int HIERARCHIES;
  public static final int INDEXES;
  public static final int KEYCOLUMNUSAGE;
  public static final int LEVELS;
  public static final int MEASURES;
  public static final int MEMBERS;
  public static final int PRIMARYKEYS;
  public static final int PROCEDURECOLUMNS;
  public static final int PROCEDUREPARAMETERS;
  public static final int PROCEDURES;
  public static final int PROPERTIES;
  public static final int PROVIDERSPECIFIC;
  public static final int PROVIDERTYPES;
  public static final int REFERENTIALCONSTRAINTS;
  public static final int SCHEMATA;
  public static final int SQLLANGUAGES;
  public static final int STATISTICS;
  public static final int TABLECONSTRAINTS;
  public static final int TABLEPRIVILEGES;
  public static final int TABLES;
  public static final int TRANSLATIONS;
  public static final int TRUSTEES;
  public static final int USAGEPRIVILEGES;
  public static final int VIEWCOLUMNUSAGE;
  public static final int VIEWS;
  public static final int VIEWTABLEUSAGE;
}


Fields (AdoEnums.Schema Class)

 Microsoft SDK for Java

AdoEnums.Schema Class Fields

The Schema class contains the fields shown in the following table.

Constant | Value | Description
PROVIDERSPECIFIC | -1 | Used if the provider defines its own nonstandard schema queries outside those listed below.
ASSERTS | 0 | Returns the assertions defined in the catalog that are owned by a given user.
CATALOGS | 1 | Returns the physical attributes associated with catalogs accessible from the DBMS.
CHARACTERSETS | 2 | Returns the character sets defined in the catalog that are accessible to a given user.
COLLATIONS | 3 | Returns the character collations defined in the catalog that are accessible to a given user.
COLUMNS | 4 | Returns the columns of tables (including views) defined in the catalog that are accessible to a given user.
CHECKCONSTRAINTS | 5 | Returns the check constraints defined in the catalog that are owned by a given user.
CONSTRAINTCOLUMNUSAGE | 6 | Returns the columns used by referential constraints, unique constraints, check constraints, and assertions, defined in the catalog and owned by a given user.
CONSTRAINTTABLEUSAGE | 7 | Returns the tables that are used by referential constraints, unique constraints, check constraints, and assertions defined in the catalog and owned by a given user.
KEYCOLUMNUSAGE | 8 | Returns the columns defined in the catalog that are constrained as keys by a given user.
REFERENTIALCONSTRAINTS | 9 | Returns the referential constraints defined in the catalog that are owned by a given user.
TABLECONSTRAINTS | 10 | Returns the table constraints defined in the catalog that are owned by a given user.
COLUMNSDOMAINUSAGE | 11 | Returns the columns defined in the catalog that are dependent on a domain defined in the catalog and owned by a given user.
INDEXES | 12 | Returns the indexes defined in the catalog that are owned by a given user.
COLUMNPRIVILEGES | 13 | Returns the privileges on columns of tables defined in the catalog that are available to, or granted by, a given user.
TABLEPRIVILEGES | 14 | Returns the privileges on tables defined in the catalog that are available to, or granted by, a given user.
USAGEPRIVILEGES | 15 | Returns the USAGE privileges on objects defined in the catalog that are available to, or granted by, a given user.
PROCEDURES | 16 | Returns the procedures defined in the catalog that are owned by a given user.
SCHEMATA | 17 | Returns the schemas (database objects) that are owned by a given user.
SQLLANGUAGES | 18 | Returns the conformance levels, options, and dialects supported by the SQL-implementation processing data defined in the catalog.
STATISTICS | 19 | Returns the statistics defined in the catalog that are owned by a given user.
TABLES | 20 | Returns the tables (including views) defined in the catalog that are accessible to a given user.
TRANSLATIONS | 21 | Returns the character translations defined in the catalog that are accessible to a given user.
PROVIDERTYPES | 22 | Returns the (base) data types supported by the data provider.
VIEWS | 23 | Returns the views defined in the catalog that are accessible to a given user.
VIEWCOLUMNUSAGE | 24 | Returns the columns on which viewed tables, defined in the catalog and owned by a given user, are dependent.
VIEWTABLEUSAGE | 25 | Returns the tables on which viewed tables, defined in the catalog and owned by a given user, are dependent.
PROCEDUREPARAMETERS | 26 | Returns information about the parameters and return codes of procedures.
FOREIGNKEYS | 27 | Returns the foreign key columns defined in the catalog by a given user.
PRIMARYKEYS | 28 | Returns the primary key columns defined in the catalog by a given user.
PROCEDURECOLUMNS | 29 | Returns information about the columns of rowsets returned by procedures.
DBINFOKEYWORDS | 30 | Returns a list of provider-specific keywords.
DBINFOLITERALS | 31 | Returns a list of provider-specific literals used in text commands.
CUBES | 32 | Returns information about the available cubes in a schema (or the catalog, if the provider does not support schemas).
DIMENSIONS | 33 | Returns information about the dimensions in a given cube. It has one row for each dimension.
HIERARCHIES | 34 | Returns information about the hierarchies available in a dimension.
LEVELS | 35 | Returns information about the levels available in a dimension.
MEASURES | 36 | Returns information about the available measures.
PROPERTIES | 37 | Returns information about the available properties for each level of the dimension.
MEMBERS | 38 | Returns information about the available members.
TRUSTEES | 39 | Returns information about trustees.


AdoEnums.SearchDirection Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.SearchDirection Class

The AdoEnums.SearchDirection class of the com.ms.wfc.data package specifies the direction of a record search within a Recordset.

class AdoEnums.SearchDirection extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int BACKWARD;
  public static final int FORWARD;
}


Fields (AdoEnums.SearchDirection Class)

 Microsoft SDK for Java

AdoEnums.SearchDirection Class Fields

The SearchDirection class contains the fields shown in the following table.

Constant | Value | Description
BACKWARD | -1 | Searches backward. Search stops at beginning of recordset. If a match is not found, the record pointer is positioned at BOF.
FORWARD | 1 | Searches forward. Search stops at end of recordset. If a match is not found, the record pointer is positioned at EOF.


AdoEnums.StringFormat Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.StringFormat Class

The AdoEnums.StringFormat class of the com.ms.wfc.data package specifies the format when retrieving a Recordset as a string.

class AdoEnums.StringFormat extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int CLIPSTRING;
}


Fields (AdoEnums.StringFormat Class)

 Microsoft SDK for Java

AdoEnums.StringFormat Class Fields

The StringFormat class contains the following field.

Constant | Value | Description
CLIPSTRING | 2 | Delimits rows by RowDelimiter, columns by ColumnDelimiter, and NULL values by NullExpr. These three parameters of the getString method are valid only with a StringFormat of CLIPSTRING.


AdoEnums.XactAttribute Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEnums.XactAttribute Class

The AdoEnums.XactAttribute class of the com.ms.wfc.data package specifies the transaction attributes of a Connection object.

class AdoEnums.XactAttribute extends com.ms.wfc.core.Enum
{
  // Fields
  public static final int ABORTRETAINING;
  public static final int ASYNCPHASEONE;
  public static final int COMMITRETAINING;
  public static final int SYNCPHASEONE;
}


Fields (AdoEnums.XactAttribute Class)

 Microsoft SDK for Java

AdoEnums.XactAttribute Class Fields

The XactAttribute class contains the fields shown in the following table.

Constant | Value | Description
COMMITRETAINING | 131072 | Performs retaining commits—that is, calling CommitTrans automatically starts a new transaction. Not all providers support this.
ABORTRETAINING | 262144 | Performs retaining aborts—that is, calling RollbackTrans automatically starts a new transaction. Not all providers support this.
ASYNCPHASEONE | 524288 | When this flag is specified, an asynchronous commit is performed.
SYNCPHASEONE | 1048576 | When this flag is specified, the call to ITransaction::Commit returns after phase one of the two-phase commit protocol.


AdoEvent class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoEvent Class

The AdoEvent class of the com.ms.wfc.data package is the basis of ADO event handlers. It is the superclass that is extended by ConnectionEvent and RecordsetEvent.

class AdoEvent
{
  // Constructors
  public AdoEvent(java.lang.Object p1);

  // Fields
  public java.lang.Object sender;
}


AdoEvent Constructors

 Microsoft SDK for Java

AdoEvent Class Constructors

The AdoEvent class contains the AdoEvent(java.lang.Object p1) constructor.

AdoEvent(java.lang.Object p1)

Creates an AdoEvent object with one event provider.

Syntax

public AdoEvent(java.lang.Object p1);

Parameters

p1 The event provider.


Fields (AdoEvent Class)

 Microsoft SDK for Java

AdoEvent Class Fields

The AdoEvent class contains the following field.

Field | Description
sender | A value representing the event provider.


AdoException Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoException Class

The AdoException class of the com.ms.wfc.data package represents an ADO exception.

public class AdoException extends com.ms.com.ComFailException
{
  // Constructors
  public AdoException(int id);
  public AdoException(int hr, String s);
  public AdoException(String s);

  // Methods
  public int getErrorNumber();

  // Fields

}

Remarks

Exceptions of this type are thrown only by methods internal to WFC.


Constructors (AdoException class)

 Microsoft SDK for Java

AdoException Class Constructors

The AdoException class contains the following constructors:

AdoException(int id)
AdoException(int hr, String s)
AdoException(String s)

AdoException(int id)

Creates an AdoException object that includes a specific error number.

Syntax

public AdoException(int id);

Parameters

id An integer specifying an error number. Specify one of the constants defined in the AdoEnums.ErrorValue class.

AdoException(int hr, String s)

Creates an AdoException object that includes an HRESULT and an associated exception message.

Syntax

public AdoException(int hr, String s);

Parameters

hr | An integer specifying an HRESULT returned by COM. This value is converted to a compatible error number.
s | The message associated with the exception.

AdoException(String s)

Creates an AdoException object including an associated exception message.

Syntax

public AdoException(String s);

Parameters

s The message associated with the exception.


Methods (AdoException class)

 Microsoft SDK for Java

AdoException Class Methods

The AdoException class has the following methods:

getErrorNumber retrieves the error number associated with the exception.


getErrorNumber (AdoException class)

 Microsoft SDK for Java

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.


Fields (AdoException class)

 Microsoft SDK for Java

AdoException Class Fields

The AdoException class contains the fields shown in the following table.

Constant | Value | Description
adErrInvalidArgument | 3001 | Indicates that the application is using arguments that are of the wrong type, are out of acceptable range, or are in conflict with one another.
adErrNoCurrentRecord | 3021 | Indicates that either BOF or EOF is True, or the current record has been deleted. The operation requested by the application requires a current record.
adErrIllegalOperation | 3219 | Indicates that the operation requested by the application is not allowed in this context.
adErrInTransaction | 3246 | Indicates that the application cannot explicitly close a Connection object while in the middle of a transaction.
adErrFeatureNotAvailable | 3251 | Indicates that the operation requested by the application is not supported by the provider.
adErrItemNotFound | 3265 | Indicates that ADO could not find the object in the collection corresponding to the name or ordinal reference requested by the application.
adErrObjectInCollection | 3367 | Indicates that the object is already in the collection and cannot be appended.
adErrObjectNotSet | 3420 | Indicates that the object referenced by the application no longer points to a valid object.
adErrDataConversion | 3421 | Indicates that the application is using a value of the wrong type for the current operation.
adErrObjectClosed | 3704 | Indicates that the operation requested by the application is not allowed if the object is closed.
adErrObjectOpen | 3705 | Indicates that the operation requested by the application is not allowed if the object is open.
adErrProviderNotFound | 3706 | Indicates that ADO could not find the specified provider.
adErrBoundToCommand | 3707 | Indicates that the application cannot change the getActiveConnection property of a Recordset object with a Command object as its source.
adErrInvalidParamInfo | 3708 | Indicates that the application has improperly defined a Parameter object.
adErrInvalidConnection | 3709 | Indicates that the application requested an operation on an object with a reference to a closed or invalid Connection object.
adErrNotReentrant | 3710 | Indicates that code that would cause an event to reoccur cannot be executed within that event.
adErrStillExecuting | 3711 | Indicates that ADO was still executing a command when another operation was requested.
adErrOperationCancelled | 3712 | Occurs when an ADO operation has been canceled.
adErrStillConnecting | 3713 | Indicates that ADO was still connecting to the data source when another operation was requested.
adErrNotExecuting | 3715 | Indicates that an ADO operation that was not execute was requested to be canceled.
adErrUnsafeOperation | 3716 | Indicates that the requested operation is not allowed by the security of the environment under which ADO is running.


AdoProperties class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoProperties Class

The AdoProperties class of the com.ms.wfc.data package encapsulates the ADO Properties collection, which contains all Property objects for an instance of an ADO object.

public class AdoProperties
{
  // Methods
  public int getCount();
  public com.ms.wfc.data.AdoProperty getItem(int n);
  public com.ms.wfc.data.AdoProperty getItem(java.lang.String s);
  public void refresh();
}

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.


Methods (AdoProperties Class)

 Microsoft SDK for Java

AdoProperties Class Methods

The AdoProperties class contains the following methods, which encapsulate the properties and methods of the ADO Properties collection:

getCount retrieves the number of objects in a collection.
getItem retrieves a specific member of a collection by ordinal number or name.
refresh updates the objects in a collection to reflect objects available from and specific to the provider.


getCount (AdoProperties class)

 Microsoft SDK for Java

getCount

This method of the AdoProperties class retrieves the number of objects in a collection.

Syntax

public int getCount();


getItem (AdoProperties class)

 Microsoft SDK for Java

getItem

This method of the AdoProperties class contains the following signatures:

getItem(int n)

Retrieves a specific member of a collection by ordinal number.

Syntax

public com.ms.wfc.data.AdoProperty getItem(int n);

Parameters

n An integer representing the ordinal number of the collection member.

getItem(java.lang.String s)

Retrieves a specific member of a collection by name.

Syntax

public com.ms.wfc.data.AdoProperty getItem(java.lang.String s);

Parameters

s A string representing the name of the collection member.


refresh (AdoProperties class)

 Microsoft SDK for Java

refresh

This method of the AdoProperties class updates the objects in a collection to reflect objects available from and specific to the provider.

Syntax

public void refresh();


AdoProperty Class (com.ms.wfc.data package)

 Microsoft SDK for Java

AdoProperty Class

The AdoProperty class of the com.ms.wfc.data package encapsulates the ADO Property object, which represents a property for an ADO object, and uses Java primitive data types to retrieve and set the value of the AdoProperty object.

public class AdoProperty
{
  // Methods
  public int getAttributes();
  public boolean getBoolean();
  public byte getByte();
  public byte[] getBytes();
  public double getDouble();
  public float getFloat();
  public int getInt();
  public long getLong();
  public String getName();
  public Object getObject();
  public short getShort();
  public String getString();
  public int getType();
  public Variant getValue();
  public boolean isNull();
  public void setAttributes(int attr);
  public void setBoolean(boolean v);
  public void setByte(byte v);
  public void setBytes(byte[] v);
  public void setDouble(double v);
  public void setFloat(float v);
  public void setInt(int v);
  public void setLong(long v);
  public void setNull();
  public void setObject(Object v);
  public void setShort(short v);
  public void setString(String v);
  public void setValue(Variant v);
}

Note The isNull method returns a boolean value indicating whether the property is null. There is no getNull method.

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 associated getxxx 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. For convenience, ADO/WFC also provides accessor methods that retrieve and assign values not specified as variants, but as standard Java data types.


Methods (AdoProperty Class)

 Microsoft SDK for Java

AdoProperty Class Methods

The AdoProperty class contains the following methods:

getAttributes retrieves one or more characteristics of an object.
getBoolean uses the Java boolean data type to retrieve the value of the AdoProperty object.
getByte uses the Java byte primitive data type to retrieve the value of the AdoProperty object.
getBytes uses the Java byte primitive data type to retrieve the byte array values of the AdoProperty object.
getDouble uses the Java double primitive data type to retrieve the value of the AdoProperty object.
getFloat uses the Java float primitive data type to retrieve the value of the AdoProperty object.
getInt uses the Java int primitive data type to retrieve the value of the AdoProperty object.
getLong uses the Java long primitive data type to retrieve the value of the AdoProperty object.
getName retrieves the name of an object.
getObject uses the Java object primitive data type to retrieve the value of the AdoProperty object.
getShort uses the Java short primitive data type to retrieve the value of the AdoProperty object.
getString uses the Java string primitive data type to retrieve the value of the AdoProperty object.
getType retrieves the operational type or data type of a Parameter, Field, or Property object.
getValue retrieves the value assigned to a Field, Parameter, or Property object.
isNull returns a boolean value indicating whether the property is null.
setAttributes sets one or more characteristics of an object.
setBoolean uses the Java boolean primitive data type to set the value of the AdoProperty object.
setByte uses the Java byte primitive data type to set the value of the AdoProperty object.
setBytes uses the Java byte primitive data type to set the byte array values of the AdoProperty object.
setDouble uses the Java double primitive data type to set the value of the AdoProperty object.
setFloat uses the Java float primitive data type to set the value of the AdoProperty object.
setInt uses the Java int primitive data type to set the value of the AdoProperty object.
setLong uses the Java long primitive data type to set the value of the AdoProperty object.
setNull sets the property to null.
setObject uses the Java object primitive data type to set the value of the AdoProperty object.
setShort uses the Java short primitive data type to set the value of the AdoProperty object.
setString uses the Java string primitive data type to set the value of the AdoProperty object.
setValue sets the value assigned to a Field, Parameter, or Property object.


getAttributes (AdoProperty class)

 Microsoft SDK for Java

getAttributes

This method of the AdoProperty class retrieves one or more characteristics of an object.

For a Connection object, the retrieved attribute is read/write, and its value can be the sum of one or more XactAttribute values. The default is zero (0).

For a Parameter object, the retrieved attribute is read/write, and its value can be the sum of any one or more ParameterAttributes values. The default is SIGNED.

For a Field object, the retrieved attribute is read-only, and its value can be the sum of one or more FieldAttribute values.

For a Property object, the retrieved attribute is read-only, and its value can be the sum of any one or more PropertyAttributes values.

Syntax

public int getAttributes();


getBoolean (AdoProperty class)

 Microsoft SDK for Java

getBoolean

This method of the AdoProperty class uses the Java boolean data type to retrieve the value of the AdoProperty object.

Syntax

public boolean getBoolean();


getByte (AdoProperty class)

 Microsoft SDK for Java

getByte

This method of the AdoProperty class uses the Java byte primitive data type to retrieve the value of the AdoProperty object.

Syntax

public byte getByte();


getBytes (AdoProperty class)

 Microsoft SDK for Java

getBytes

This method of the AdoProperty class uses the Java byte primitive data type to retrieve a byte array of values from the AdoProperty object.

Syntax

public byte[] getBytes();


getDouble (AdoProperty class)

 Microsoft SDK for Java

getDouble

This method of the AdoProperty class uses the Java double primitive data type to retrieve the value of the AdoProperty object.

Syntax

public double getDouble();


getFloat (AdoProperty class)

 Microsoft SDK for Java

getFloat

This method of the AdoProperty class uses the Java float primitive data type to retrieve the value of the AdoProperty object.

Syntax

public float getFloat();


getInt (AdoProperty class)

 Microsoft SDK for Java

getInt

This method of the AdoProperty class uses the Java int primitive data type to retrieve the value of the AdoProperty object.

Syntax

public int getInt();


getLong (AdoProperty class)

 Microsoft SDK for Java

getLong

This method of the AdoProperty class uses the Java long primitive data type to retrieve the value of the AdoProperty object.

Syntax

public long getLong();


getName (AdoProperty class)

 Microsoft SDK for Java

getName

This method of the AdoProperty class retrieves the name of an object.

The value is read/write on a Command or Parameter object and read-only on an AdoProperty or Field object.

For Parameter objects not yet appended to the Parameters collection, the name is read/write. For appended Parameter objects and all other objects, the name is read-only. Names do not have to be unique within a collection.

You can retrieve the name of an object by an ordinal reference, after which you can refer to the object directly by name.

Syntax

public String getName();


getObject (AdoProperty class)

 Microsoft SDK for Java

getObject

This method of the AdoProperty class uses the Java object primitive data type to retrieve the value of the AdoProperty object.

Syntax

public Object getObject();


getShort (AdoProperty class)

 Microsoft SDK for Java

getShort

This method of the AdoProperty class uses the Java short primitive data type to retrieve the value of the AdoProperty object.

Syntax

public short getShort();


getString (AdoProperty class)

 Microsoft SDK for Java

getString

This method of the AdoProperty class uses the Java string primitive data type to retrieve the value of the AdoProperty object.

Syntax

public String getString();


getType (AdoProperty class)

 Microsoft SDK for Java

getType

This method of the AdoProperty class retrieves the operational type or data type of a Parameter, Field, or AdoProperty object.

For Parameter objects, the Type property is read/write. For all other objects, the Type property is read-only.

Syntax

public int getType();
public void setType(int t);

Return Value

Returns one of the DataType values.

Parameters

t One of the DataType values.


getValue (AdoProperty class)

 Microsoft SDK for Java

getValue

This method of the AdoProperty class retrieves the value assigned to a Field, Parameter, or AdoProperty object.

Syntax

public Variant getValue();

Return Value

Returns a VARIANT value whose default value depends on the data type.

Use getValue and setValue to set or return data from Field objects, to set or return parameter values with Parameter objects, or to set or return property settings with Property objects. Whether the value is read/write or read-only depends upon numerous factors. See the respective object topics for more information.

ADO allows setting and returning long binary data with getValue and setValue.

Note For Parameter objects, ADO reads the Value property only once from the provider. If a command contains a Parameter whose Value property is empty and you create a Recordset from the command, ensure that you first close the Recordset before retrieving the Value property. Otherwise, for some providers the Value property may be empty, and won't contain the correct value.


isNull (AdoProperty class)

 Microsoft SDK for Java

isNull

This method of the AdoProperty class returns a boolean value indicating whether the property is null.

Syntax

public boolean isNull();

Note The isNull method returns a boolean value indicating whether the property is null. There is no getNull method.


setAttributes (AdoProperty class)

 Microsoft SDK for Java

setAttributes

This method of the AdoProperty class sets one or more attributes of an object.

Syntax

public void setAttributes(int attr);

Parameters

attr An integer representing the object attribute to set.


setBoolean (AdoProperty class)

 Microsoft SDK for Java

setBoolean

This method of the AdoProperty class uses the Java boolean primitive data type to set the value of the AdoProperty object.

Syntax

public void setBoolean(boolean v);

Parameters

v A boolean TRUE or FALSE.


setByte (AdoProperty class)

 Microsoft SDK for Java

setByte

This method of the AdoProperty class uses the Java byte primitive data type to set the value of the AdoProperty object.

Syntax

public void setByte(byte v);

Parameters

v A byte.


setBytes (AdoProperty class)

 Microsoft SDK for Java

setBytes

This method of the AdoProperty class uses the Java byte primitive data type to set the byte array values of the AdoProperty object.

Syntax

public void setBytes (byte[] v);

Parameters

v An array of bytes.


setDouble (AdoProperty class)

 Microsoft SDK for Java

setDouble

This method of the AdoProperty class uses the Java double primitive data type to set the value of the AdoProperty object.

Syntax

public void setDouble(double v);

Parameters

v A double floating-point number.


setFloat (AdoProperty class)

 Microsoft SDK for Java

setFloat

This method of the AdoProperty class uses the Java float primitive data type to set the value of the AdoProperty object.

Syntax

public void setFloat(float v);

Parameters

v A floating-point number.


setInt (AdoProperty class)

 Microsoft SDK for Java

setInt

This method of the AdoProperty class uses the Java int primitive data type to set the value of the AdoProperty object.

Syntax

public void setInt(int v);

Parameters

v An integer.


setLong (AdoProperty class)

 Microsoft SDK for Java

setLong

This method of the AdoProperty class uses the Java long primitive data type to set the value of the AdoProperty object.

Syntax

public void setLong(long v);

Parameters

v A long integer.


setNull (AdoProperty class)

 Microsoft SDK for Java

setNull

This method of the AdoProperty class sets the property to null.

Syntax

public void setNull();


setObject (AdoProperty class)

 Microsoft SDK for Java

setObject

This method of the AdoProperty class uses the Java object primitive data type to set the value of the AdoProperty object.

Syntax

public void setObject(Object v);

Parameters

v The object name.


setShort (AdoProperty class)

 Microsoft SDK for Java

setShort

This method of the AdoProperty class uses the Java byte primitive data type to set the value of the AdoProperty object.

Syntax

public void setShort(short v);

Parameters

v A short integer.


setString (AdoProperty class)

 Microsoft SDK for Java

setString

This method of the AdoProperty class uses the Java byte primitive data type to set the value of the AdoProperty object.

Syntax

public void setString(String v);

Parameters

v A string.


setValue (AdoProperty class)

 Microsoft SDK for Java

setValue

This method of the AdoProperty class sets the value assigned to a Field, Parameter, or AdoProperty object.

Syntax

public void setValue(Variant v);

Parameters

v A com.ms.com.Variant value.


BooleanDataFormat Class (com.ms.wfc.data package)

 Microsoft SDK for Java

BooleanDataFormat Class

The BooleanDataFormat class of the com.ms.wfc.data package represents a data format object for formatting boolean data types.

public class BooleanDataFormat extends DataFormat implements IConstructable

{

// Constructors

public BooleanDataFormat(String falsevalue, String truevalue);

public BooleanDataFormat(String falseValue, String trueValue,

String nullValue);

// Methods

public String getFalseValue();

public String getNullValue();

public String getTrueValue();

public void setFalseValue(String value);

public void setNullValue(String value);

public void setTrueValue(String value);

}

Remarks

The com.ms.wfc.data.ui.Column and com.ms.wfc.data.ui.DataBinding classes provide a setDataFormat method that 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 data format to a BooleanDataFormat object shown as follows:

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 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);

See Also DateDataFormat, NumberDataFormat


Constructors (BooleanDataFormat class)

 Microsoft SDK for Java

BooleanDataFormat Class Constructors

The BooleanDataFormat class contains the following constructors:

BooleanDataFormat(String falsevalue, String truevalue)
BooleanDataFormat(String falseValue, String trueValue, String nullValue)

BooleanDataFormat(String falsevalue, String truevalue)

Creates a BooleanDataFormat object for formatting false and true values.

Syntax

public BooleanDataFormat(String falsevalue, String truevalue);

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".

BooleanDataFormat(String falseValue, String trueValue, String nullValue)

Creates a BooleanDataFormat object for formatting false, true, and null values.

Syntax

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 explicitly use a default string, pass null for the parameter.


Methods (BooleanDataFormat class)

 Microsoft SDK for Java

BooleanDataFormat Class Methods

The BooleanDataFormat class contains the following methods:

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.


getFalseValue (BooleanDataFormat class)

 Microsoft SDK for Java

getFalseValue

This method of the BooleanDataFormat class 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


getNullValue (BooleanDataFormat class)

 Microsoft SDK for Java

getNullValue

This method of the BooleanDataFormat class 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


getTrueValue (BooleanDataFormat class)

 Microsoft SDK for Java

getTrueValue

This method of the BooleanDataFormat class 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


setFalseValue (BooleanDataFormat class)

 Microsoft SDK for Java

setFalseValue

This method of the BooleanDataFormat class 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


setNullValue (BooleanDataFormat class)

 Microsoft SDK for Java

setNullValue

This method of the BooleanDataFormat class 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


setTrueValue (BooleanDataFormat class)

 Microsoft SDK for Java

setTrueValue

This method of the BooleanDataFormat class 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


Command Class (com.ms.wfc.data package)

 Microsoft SDK for Java

Command Class

The Command class of the com.ms.wfc.data package defines a specific command that you intend to execute against a data source.

Use a Command object to query a database and return records in a Recordset object, to execute a bulk operation, or to manipulate the structure of a database. Depending on the functionality of the provider, some Command methods may generate an error when referenced.

With the methods of a Command object, you can do the following:

  • Define the executable text of the command (for example, an SQL statement) with the setCommandText method.

  • Define parameterized queries or stored-procedure arguments with Parameter and Parameters objects.

  • Execute a command and return a Recordset object if appropriate with the execute method.

  • Specify the type of command with the setCommandType property prior to execution to optimize performance.

  • Control whether the provider saves a prepared (or compiled) version of the command prior to execution with the setPrepared method.

  • Set the number of seconds a provider will wait for a command to execute with setCommandTimeout.

  • Associate an open connection with a Command object by setting setActiveConnection.

  • Identify the Command object as a method on the associated Connection object by using the setName method.

  • Pass a Command object to Recordset.setSource to obtain data.

Note To execute a query without using a Command object, pass a query string to Connection.execute or Recordset.open. A Command object is required, however, when you want to persist the command text and re-execute it, or use query parameters.

To create a Command object independently of a previously defined Connection object, pass setActiveConnection a valid connection string. ADO still creates a Connection object, but it doesn't assign that object to an object variable. However, if you are associating multiple Command objects with the same connection, you should explicitly create and open a Connection object; this assigns the Connection object to an object variable. If you do not set the Command object's setActiveConnection property to this object variable, ADO creates a new Connection object for each Command object, even if you use the same connection string.

To execute a Command, simply call it by its Name on the associated Connection object. The Command must have setActiveConnection set to the Connection object. If the Command has parameters, pass their values as arguments to the method.

If two or more Command objects are executed on the same connection and either Command object is a stored procedure with output parameters, an error occurs. To execute each Command object, use separate connections or disconnect all other Command objects from the connection.

public class Command
{
  // Methods
  public void cancel();
  public com.ms.wfc.data.Parameter createParameter(String Name,
    int Type, int Direction, int Size, Object Value);
  public Recordset execute();
  public Recordset execute(Object[] parameters);
  public Recordset execute(Object[] parameters, int options);
  public int executeUpdate();
  public int executeUpdate(Object[] parameters);
  public int executeUpdate(Object[] parameters, int options);
  public com.ms.wfc.data.Connection getActiveConnection();
  public String getCommandText();
  public int getCommandTimeout();
  public int getCommandType();
  public String getName();
  public com.ms.wfc.data.Parameter getParameter(int n);
  public com.ms.wfc.data.Parameter getParameter(String n);
  public com.ms.wfc.data.Parameters getParameters();
  public boolean getPrepared();
  public AdoProperties getProperties();
  public int getState();
  public void setActiveConnection(com.ms.wfc.data.Connection con);
  public void setActiveConnection(String conString);
  public void setCommandText(String command);
  public void setCommandTimeout(int timeout);
  public void setCommandType(int type);
  public void setName(String name);
  public void setPrepared(boolean prepared);
}


Methods (Command Class)

 Microsoft SDK for Java

Command Class Methods

The Command class has the following methods:

cancel cancels execution of a pending asynchronous execute method call.
createParameter creates a new Parameter object with the specified properties.
execute executes the query, SQL statement, or stored procedure specified in the CommandText property.
executeUpdate calls the underlying ADO execute method with certain parameters.
getActiveConnection retrieves a string containing a definition for a connection if the connection is closed, or a Variant containing the current Connection object if the connection is open.
getCommandText retrieves a string containing a provider command, such as an SQL statement, a table name, a relative URL, or a stored procedure call. Default is "" (zero-length string).
getCommandTimeout retrieves a value that indicates, in seconds, how long to wait for a command to execute.
getCommandType retrieves one or more CommandType values.
getName retrieves the name of a Command object.
getParameter retrieves a parameter of a Command object.
getParameters retrieves all parameters of a Command object.
getPrepared retrieves a boolean value that indicates whether to save a compiled version of a command before execution.
getProperties retrieves the Property objects for a specific instance of an object.
getState retrieves a value that indicates for all applicable objects whether the state of the object is open or closed.
setActiveConnection sets a string containing a definition for a connection if the connection is closed, or a Variant containing the current Connection object if the connection is open.
setCommandText sets a string containing a provider command, such as an SQL statement, a table name, a relative URL, or a stored procedure call. Default is "" (zero-length string).
setCommandTimeout sets a value that indicates, in seconds, how long to wait for a command to execute.
setCommandType sets one or more CommandType values.
setName assigns the name of a Command object.
setPrepared sets a boolean value that indicates whether to save a compiled version of a command before execution.


cancel (Command Class)

 Microsoft SDK for Java

cancel

This method of the Command class cancels execution of a pending asynchronous execute method call.

Syntax

public void cancel();


createParameter (Command Class)

 Microsoft SDK for Java

createParameter

This method of the Command class creates a new Parameter object with the specified properties.

Syntax

public com.ms.wfc.data.Parameter createParameter(String Name, int Type, int Direction, int Size, Object Value);

Return Value

A Parameter object.

Parameters

Name | Optional. A String that contains the name of the Parameter object.
Type | Optional. A DataType value that specifies the data type of the Parameter object.
Direction | Optional. A ParameterDirectionEnum value that specifies the type of Parameter object.
Size | Optional. A Long value that specifies the maximum length for the parameter value in characters or bytes.
Value | Optional. A Variant that specifies the value for the Parameter object.


execute (Command Class)

 Microsoft SDK for Java

execute

This method of the Command class has the following signatures:

execute()
execute(Object[] parameters)
execute(Object[] parameters, int options)

execute()

Executes the query, SQL statement, or stored procedure specified in the CommandText property.

Syntax

public Recordset execute();

Return Value

Returns a Recordset object reference.

execute(Object[] parameters)

Syntax

public Recordset execute(Object[] parameters);

Return Value

Returns a Recordset object reference.

Parameters

parameters Optional. A VARIANT array of parameter values passed with an SQL statement. (Output parameters will not return correct values when passed in this argument.)

execute(Object[] parameters, int options)

Syntax

public Recordset execute(Object[] parameters, int options);

Return Value

Returns a Recordset object reference.

Parameters

parameters | Optional. A VARIANT array of parameter values passed with an SQL statement. (Output parameters will not return correct values when passed in this argument.)
options | Optional. A Long value that indicates how the provider should evaluate the CommandText property of the Command object. Can be one or more CommandType or ExecuteOption values.


executeUpdate (Command Class)

 Microsoft SDK for Java

executeUpdate

This method of the Command class is a special-case method that calls the underlying ADO execute method with certain parameters. The executeUpdate method does not support the return of a Recordset object, so the execute method's options parameter is modified with AdoEnums.ExecuteOption.NORECORDS. After the execute method completes, its updated RecordsAffected parameter is passed back to the executeUpdate method, which is finally returned as an integer.

The executeUpdate method has the following signatures:

executeUpdate()
executeUpdate(Object[] parameters)
executeUpdate(Object[] parameters, int options)

executeUpdate()

Syntax

public int executeUpdate();

Return Value

Returns an integer designating the affected records.

executeUpdate(Object[] parameters)

Syntax

public int executeUpdate(Object[] parameters);

Return Value

Returns an integer designating the affected records.

Parameters

parameters Optional. A VARIANT array of parameter values passed with an SQL statement. (Output parameters will not return correct values when passed in this argument.)

executeUpdate(Object[] parameters, int options)

Syntax

public int executeUpdate(Object[] parameters, int options);

Return Value

Returns an integer designating the affected records.

Parameters

parameters | Optional. A VARIANT array of parameter values passed with an SQL statement. (Output parameters will not return correct values when passed in this argument.)
options | Optional. A Long value that indicates how the provider should evaluate the CommandText property of the Command object. Can be one or more CommandType or ExecuteOption values.


getActiveConnection (Command Class)

 Microsoft SDK for Java

getActiveConnection

This method of the Command class determines whether the connection is closed or open.

Syntax

public com.ms.wfc.data.Connection getActiveConnection();

Return Value

Returns a string containing a definition for a connection if the connection is closed, or a VARIANT containing the current Connection object if the connection is open.


getCommandText (Command Class)

 Microsoft SDK for Java

getCommandText

This method of the Command class retrieves a string containing a provider command, such as an SQL statement, a table name, a relative URL, or a stored procedure call. Default is "" (zero-length string).

Syntax

public String getCommandText();

Return Value

Returns a string containing a provider command.


getCommandTimeout (Command Class)

 Microsoft SDK for Java

getCommandTimeout

This method of the Command class indicates, in seconds, how long to wait for a command to execute.

Syntax

public int getCommandTimeout();

Return Value

Returns an integer value that indicates, in seconds, how long to wait for a command to execute.


getCommandType (Command Class)

 Microsoft SDK for Java

getCommandType

This method of the Command class retrieves one or more CommandType values.

Syntax

public int getCommandType();

Return Value

Returns an integer representing the CommandType.


getName (Command Class)

 Microsoft SDK for Java

getName

This method of the Command class retrieves the name of a Command object.

Syntax

public String getName();

Return Value

Returns a string.


getParameter (Command Class)

 Microsoft SDK for Java

getParameter

This method of the Command class has the following signatures:

getParameter(int n)
getParameter(String n)

getParameter(int n)

Retrieves a parameter of a Command object.

Syntax

public com.ms.wfc.data.Parameter getParameter(int n);

Return Value

Returns a Parameter object.

Parameters

n An integer representing the Command object parameter.

getParameter(String n)

Syntax

public com.ms.wfc.data.Parameter getParameter(String n);

Return Value

Returns a Parameter object.

Parameters

n A string representing the Command object parameter.


getParameters (Command Class)

 Microsoft SDK for Java

getParameters

This method of the Command class retrieves all parameters of a Command object.

Syntax

public com.ms.wfc.data.Parameters getParameters();

Return Value

Returns a Parameters object.


getPrepared (Command Class)

 Microsoft SDK for Java

getPrepared

This method of the Command class indicates whether to save a compiled version of a command before execution.

Syntax

public boolean getPrepared();

Return Value

Returns a boolean TRUE or FALSE.


getProperties (Command Class)

 Microsoft SDK for Java

getProperties

This method of the Command class retrieves the Property objects for a specific instance of an object.

Syntax

public AdoProperties getProperties();

Return Value

Returns the Property objects for an object instance.


getState (Command Class)

 Microsoft SDK for Java

getState

This method of the Command class retrieves a value that indicates for all applicable objects whether the state of the object is open or closed.

Syntax

public int getState();

Return Value

Returns an integer that indicates the object's state.


setActiveConnection (Command Class)

 Microsoft SDK for Java

setActiveConnection

This method of the Command class has the following signatures:

setActiveConnection(com.ms.wfc.data.Connection con)
setActiveConnection(String conString)

setActiveConnection(com.ms.wfc.data.Connection con)

Sets a VARIANT containing the current Connection object if the connection is open.

Syntax

public void setActiveConnection(com.ms.wfc.data.Connection con);

Return Value

Returns a Connection object.

Parameters

con A VARIANT containing the current Connection object.

setActiveConnection(String conString)

Sets a string containing a definition for a connection if the connection is closed.

Syntax

public void setActiveConnection(String conString);

Parameters

conString A string containing a connection definition.


setCommandText (Command Class)

 Microsoft SDK for Java

setCommandText

This method of the Command class sets a string containing a provider command, such as an SQL statement, a table name, a relative URL, or a stored procedure call. Default is "" (zero-length string).

Syntax

public void setCommandText(String command);

Parameters

command A string containing a provider command.


setCommandTimeout (Command Class)

 Microsoft SDK for Java

setCommandTimeout

This method of the Command class sets a value that indicates, in seconds, how long to wait for a command to execute.

Syntax

public void setCommandTimeout(int timeout);

Parameters

timeout An integer value.


setCommandType (Command Class)

 Microsoft SDK for Java

setCommandType

This method of the Command class sets one or more CommandType values.

Syntax

public void setCommandType(int type);

Parameters

type One of the CommandType values.


setName (Command Class)

 Microsoft SDK for Java

setName

This method of the Command class assigns the name of a Command object.

Syntax

public void setName(String name);

Parameters

name The Command object name.


setPrepared (Command Class)

 Microsoft SDK for Java

setPrepared

This method of the Command class sets a boolean value that indicates whether to save a compiled version of a command before execution.

Syntax

public void setPrepared(boolean prepared);

Parameters

prepared A boolean TRUE or FALSE.


Connection Class (com.ms.wfc.data package)

 Microsoft SDK for Java

Connection Class

The Connection class of the com.ms.wfc.data package represents a unique session with a data source. In the case of a client/server database system, it may be equivalent to an actual network connection to the server. Depending on the functionality supported by the provider, some collections, methods, or properties of a Connection object may not be available.

public class Connection
{
  // Methods
  public void addOnBeginTransComplete(ConnectionEventHandler handler);
  public void addOnCommitTransComplete(ConnectionEventHandler handler);
  public void addOnConnectComplete(ConnectionEventHandler handler);
  public void addOnDisconnect(ConnectionEventHandler handler);
  public void addOnExecuteComplete(ConnectionEventHandler handler);
  public void addOnInfoMessage(ConnectionEventHandler handler);
  public void addOnRollbackTransComplete(ConnectionEventHandler handler);
  public void addOnWillConnect(ConnectionEventHandler handler);
  public void addOnWillExecute(ConnectionEventHandler handler);
  public int beginTrans();
  public void cancel();
  public void close();
  public void commitTrans();
  public com.ms.wfc.data.Recordset execute(String commandText);
  public com.ms.wfc.data.Recordset execute(String commandText, int options);
  public int executeUpdate(String commandText);
  public int executeUpdate(String commandText, int options);
  public int getAttributes();
  public int getCommandTimeout();
  public String getConnectionString();
  public int getConnectionTimeout();
  public int getCursorLocation();
  public String getDefaultDatabase();
  public com.ms.wfc.data.Errors getErrors();
  public int getIsolationLevel();
  public int getMode();
  public AdoProperties getProperties();
  public String getProvider();
  public int getState();
  public String getVersion();
  public void open();
  public void open(String connectionString);
  public void open(String connectionString, String userID);
  public void open(String connectionString, String userID, String password);
  public void open(String connectionString, String userID, String password, int options);
  public Recordset openSchema(int schema);
  public Recordset openSchema(int schema, Object[] restrictions);
  public Recordset openSchema(int schema, Object[] restrictions, String schemaID);
  public void rollbackTrans();
  public void setAttributes(int attr);
  public void setCommandTimeout(int timeout);
  public void setConnectionString(String con);
  public void setConnectionTimeout(int timeout);
  public void setCursorLocation(int cursorLoc);
  public void setDefaultDatabase(String db);
  public void setIsolationLevel(int level);
  public void setMode(int mode);
  public void setProvider(String provider);
}

Using the methods of a Connection object, you can do the following:

  • Configure the connection before opening it with the setConnectionString, setConnectionTimeout, and setMode methods.

  • Invoke the Client Cursor Provider, which supports batch updates, with the setCursorLocation method.

  • Set the default database for the connection with the setDefaultDatabase method.

  • Set the level of isolation for the transactions opened on the connection with the setIsolationLevel method.

  • Specify an OLE DB provider with setProvider.

  • Establish, and later break, the physical connection to the data source with the open and close methods.

  • Execute a command on the connection with the execute method and configure the execution with the setCommandTimeout method.

  • Manage transactions on the open connection, including nested transactions if the provider supports them, with the addOnBeginTransComplete, addOnCommitTransComplete, addOnRollbackTransComplete, getAttributes, and setAttributes methods.

  • Examine errors returned from the data source with the getErrors method.

  • Read the version from the ADO implementation in use with the getVersion method.

  • Obtain schema information about your database with the openSchema method.

Note To execute a query without using a Command object, pass a query string to Connection.execute. However, a Command object is required when you want to persist the command text and re-execute it, or use query parameters.

You can create Connection objects independently of any other previously defined object.

Note You can execute commands or stored procedures as if they were native methods on the Connection object.

To execute a command, give the command a name using the Command object setName property. Pass the Command object's setActiveConnection value to the connection. Then issue a statement where the command name is used as if it were a method on the Connection object, followed by any parameters, followed by a Recordset object if any rows are returned. Set the Recordset properties to customize the resulting Recordset.

To execute a stored procedure, issue a statement where the stored procedure name is used as if it were a method on the Connection object, followed by any parameters. ADO will make a "best guess" of parameter types.


Methods (Connection Class)

 Microsoft SDK for Java

Connection Class Methods

The Connection class has the following methods:

addOnBeginTransComplete is called after the beginTrans operation.
addOnCommitTransComplete is called after the commitTrans operation.
addOnConnectComplete is called after a connection starts.
addOnDisconnect is called after a connection ends.
addOnExecuteComplete is called after a command has finished executing.
addOnInfoMessage is called whenever a warning occurs during a ConnectionEvent operation.
addOnRollbackTransComplete is called after the rollbackTrans operation.
addOnWillConnect is called before a connection starts.
addOnWillExecute is called just before a pending command executes on this connection.
beginTrans begins a new transaction.
cancel cancels execution of a pending, asynchronous execute or open method call.
close closes an open object and any dependent objects.
commitTrans saves any changes and ends the current transaction. It may also start a new transaction.
execute executes the specified query, SQL statement, stored procedure, or provider-specific text.
executeUpdate calls the underlying ADO execute method with certain parameters.
getAttributes retrieves a read/write value that can be the sum of one or more XactAttribute values.
getCommandTimeout indicates, in seconds, how long to wait for a command to execute.
getConnectionString retrieves a connection to a data source.
getConnectionTimeout indicates how long to wait while establishing a connection before terminating the attempt and generating an error.
getCursorLocation returns the location of the cursor service.
getDefaultDatabase retrieves the name of the default database for a Connection object.
getErrors retrieves all the error objects created in response to a single failure involving the provider.
getIsolationLevel retrieves the level of isolation for the transactions opened on the connection.
getMode retrieves the available permissions for modifying data in a Connection.
getProperties retrieves the Property objects for a specific instance of an object.
getProvider retrieves the name of the provider for a Connection object.
getState indicates whether the state of the object is open, closed, connecting, executing, or fetching.
getVersion retrieves the ADO version number.
open opens a connection to a data source.
openSchema obtains database schema information from the provider.
rollbackTrans cancels any changes made during the current transaction and ends the transaction. It may also start a new transaction.
setAttributes assigns a read/write value that can be the sum of one or more XactAttribute values.
setCommandTimeout assigns how long to wait for a command to execute.
setConnectionString establishes a connection to a data source.
setConnectionTimeout defines how long to wait while establishing a connection before terminating the attempt and generating an error.
setCursorLocation assigns the location of the cursor service.
setDefaultDatabase assigns the name of the default database for a Connection object.
setIsolationLevel assigns the level of isolation for the transactions opened on the connection.
setMode assigns the available permissions for modifying data in a Connection.
setProvider assigns the name of the provider for a Connection object.


addOnBeginTransComplete (Connection Class)

 Microsoft SDK for Java

addOnBeginTransComplete

This method of the Connection class is called after the beginTrans operation.

Syntax

public void addOnBeginTransComplete(ConnectionEventHandler handler);

Parameters

handler The event handler.


addOnCommitTransComplete (Connection Class)

 Microsoft SDK for Java

addOnCommitTransComplete

This method of the Connection class is called after the commitTrans operation.

Syntax

public void addOnCommitTransComplete(ConnectionEventHandler handler);

Parameters

handler The event handler.


addOnConnectComplete (Connection Class)

 Microsoft SDK for Java

addOnConnectComplete

This method of the Connection class is called after a connection starts.

Syntax

public void addOnConnectComplete(ConnectionEventHandler handler);

Parameters

handler The event handler.


addOnDisconnect (Connection Class)

 Microsoft SDK for Java

addOnDisconnect

This method of the Connection class is called after a connection ends.

Syntax

public void addOnDisconnect(ConnectionEventHandler handler);

Parameters

handler The event handler.


addOnExecuteComplete (Connection Class)

 Microsoft SDK for Java

addOnExecuteComplete

This method of the Connection class is called after a command has finished executing.

Syntax

public void addOnExecuteComplete(ConnectionEventHandler handler);

Parameters

handler The event handler.


addOnInfoMessage (Connection Class)

 Microsoft SDK for Java

addOnInfoMessage

This method of the Connection class is called whenever a warning occurs during a ConnectionEvent operation.

Syntax

public void addOnInfoMessage(ConnectionEventHandler handler);

Parameters

handler The event handler.


addOnRollbackTransComplete (Connection Class)

 Microsoft SDK for Java

addOnRollbackTransComplete

This method of the Connection class is called after the rollbackTrans operation.

Syntax

public void addOnRollbackTransComplete(ConnectionEventHandler handler);

Parameters

handler The event handler.


addOnWillConnect (Connection Class)

 Microsoft SDK for Java

addOnWillConnect

This method of the Connection class is called before a connection starts. The parameters to be used in the pending connection are supplied as input parameters and can be changed before the method returns. This method may return a request that the pending connection be canceled.

Syntax

public void addOnWillConnect(ConnectionEventHandler handler);

Parameters

handler The event handler.


addOnWillExecute (Connection Class)

 Microsoft SDK for Java

addOnWillExecute

This method of the Connection class is called just before a pending command executes on this connection and affords the user an opportunity to examine and modify the pending execution parameters. This method may return a request that the pending command be canceled.

Syntax

public void addOnWillExecute(ConnectionEventHandler handler);

Parameters

handler The event handler.


beginTrans (Connection Class)

 Microsoft SDK for Java

beginTrans

This method of the Connection class begins a new transaction.

Syntax

public int beginTrans();

Return Value

Returns the nesting level of the transaction.


cancel (Connection Class)

 Microsoft SDK for Java

cancel

This method of the Connection and Recordset classes cancels execution of a pending, asynchronous execute or open method call.

Syntax

public void cancel();


close (Connection Class)

 Microsoft SDK for Java

close

This method of the Connection and Recordset classes closes an open object and any dependent objects.

Syntax

public void close();


commitTrans (Connection Class)

 Microsoft SDK for Java

commitTrans

This method of the Connection class saves any changes and ends the current transaction. It may also start a new transaction.

Syntax

public void commitTrans();


execute (Connection Class)

 Microsoft SDK for Java

execute

This method of the Connection class has the following signatures:

execute(String commandText)
execute(String commandText, int recordsaffected)

execute(String commandText)

Executes the query, SQL statement, or stored procedure specified in the commandText parameter.

Syntax

public com.ms.wfc.data.Recordset execute(String commandText);

Return Value

Returns a Recordset object reference.

Parameters

commandText A String that contains the SQL statement, table name, stored procedure, a URL, or provider-specific text to execute.

execute(String commandText, int recordsaffected)

Executes the query, SQL statement, or stored procedure specified in the commandText parameter and returns the number of records affected by the procedure.

Syntax

public com.ms.wfc.data.Recordset execute(String commandText, int recordsaffected);

Return Value

Returns a Recordset object reference.

Parameters

commandText | A String that contains the SQL statement, table name, stored procedure, a URL, or provider-specific text to execute.
recordsaffected | Optional. A variable to which the provider returns the number of records that the operation affected.


executeUpdate (Connection Class)

 Microsoft SDK for Java

executeUpdate

This method of the Connection class has the following signatures:

executeUpdate(String commandText)
executeUpdate(String commandText, int options)

executeUpdate(String commandText)

Syntax

public int executeUpdate(String commandText);

Return Value

Returns an integer designating the affected records.

Parameters

commandText A String that contains the SQL statement, table name, stored procedure, a URL, or provider-specific text to execute.

executeUpdate(String commandText, int options)

Syntax

public int executeUpdate(String commandText, int options);

Return Value

Returns an integer designating the affected records.

Parameters

commandText | A String that contains the SQL statement, table name, stored procedure, a URL, or provider-specific text to execute.
options | Optional. A Long value that indicates how the provider should evaluate the CommandText property of the Command object. Can be one or more CommandType or ExecuteOption values.


getAttributes (Connection Class)

 Microsoft SDK for Java

getAttributes

This method of the Connection class retrieves the sum of one or more XactAttribute values.

Syntax

public int getAttributes();

Return Value

Returns a read/write value that can be the sum of one or more XactAttribute values. The default is zero (0).


getCommandTimeout (Connection Class)

 Microsoft SDK for Java

getCommandTimeout

This method of the Connection class indicates, in seconds, how long to wait for a command to execute.

Syntax

public int getCommandTimeout();

Return Value

Returns an integer representing seconds.


getConnectionString (Connection Class)

 Microsoft SDK for Java

getConnectionString

This method of the Connection class retrieves a connection to a data source.

Syntax

public String getConnectionString();

Return Value

Returns a string representing the connection.


getConnectionTimeout (Connection Class)

 Microsoft SDK for Java

getConnectionTimeout

This method of the Connection class indicates how long to wait while establishing a connection before terminating the attempt and generating an error.

Syntax

public int getConnectionTimeout();

Return Value

Returns an integer representing the timeout in seconds.


getCursorLocation (Connection Class)

 Microsoft SDK for Java

getCursorLocation

This method of the Connection class returns the location of the cursor service.

Syntax

public int getCursorLocation();

Return Value

Returns an integer representing cursor service location.

Remarks

This method allows you to choose between various cursor libraries accessible to the provider. Usually, you can choose between using a client-side cursor library or one that is located on the server.

This CursorLocation value affects connections established only after the property has been set. Changing the CursorLocation value has no effect on existing connections.

This property is read/write on a Connection or a closed Recordset, and read-only on an open Recordset.

Cursors returned by the execute method inherit this setting. Recordsets will automatically inherit this setting from their associated connections.

Remote Data Service Usage When used on a client-side Recordset or Connection object, CursorLocation can only be set to CLIENT.


getDefaultDatabase (Connection Class)

 Microsoft SDK for Java

getDefaultDatabase

This method of the Connection class retrieves the name of the default database for a Connection object.

Syntax

public String getDefaultDatabase();

Return Value

Returns a string that is the name of the default database.


getErrors (Connection Class)

 Microsoft SDK for Java

getErrors

This method of the Connection class retrieves all the error objects created in response to a single failure involving the provider.

Syntax

public com.ms.wfc.data.Errors getErrors();

Return Value

Returns a collection of error objects.


getIsolationLevel (Connection Class)

 Microsoft SDK for Java

getIsolationLevel

This method of the Connection class retrieves the level of isolation for the transactions opened on the connection.

Syntax

public int getIsolationLevel();

Return Value

Returns an IsolationLevel value. The default is CHAOS.


getMode (Connection Class)

 Microsoft SDK for Java

getMode

This method of the Connection class retrieves the available permissions for modifying data in a Connection.

Syntax

public int getMode();

Return Value

Returns a ConnectMode value. The default is UNKNOWN.


getProperties (Connection Class)

 Microsoft SDK for Java

getProperties

This method of the Connection class retrieves the Property objects for a specific instance of an object.

Syntax

public AdoProperties getProperties();

Return Value

Returns an AdoProperties object.


getProvider (Connection Class)

 Microsoft SDK for Java

getProvider

This method of the Connection class retrieves the name of the provider for a Connection object.

Syntax

public String getProvider();

Return Value

Returns the provider name.


getState (Connection Class)

 Microsoft SDK for Java

getState

This method of the Connection class indicates whether the state of the object is open or closed or, for objects executing an asynchronous method, whether the current state of the object is connecting, executing, or fetching.

Syntax

public int getState();

Return Value

Returns an ObjectState value. The default is CLOSED.


getVersion (Connection Class)

 Microsoft SDK for Java

getVersion

This method of the Connection class retrieves the ADO version number.

Syntax

public String getVersion();

Return Value

Returns the version number.


open (Connection Class)

 Microsoft SDK for Java

open

This method of the Connection class has the following signatures:

open()
open(String connectionString)
open(String connectionString, String userID)
open(String connectionString, String userID, String password)
open(String connectionString, String userID, String password, int options)

open()

Opens a connection to a data source.

Syntax

public void open();

open(String connectionString)

Syntax

public void open(String connectionString);

Parameters

connectionString Optional. A String that contains connection information.

open(String connectionString, String userID)

Syntax

public void open(String connectionString, String userID);

Parameters

connectionString | Optional. A String that contains connection information.
userID | Optional. A String that contains a user name to use when establishing the connection.

open(String connectionString, String userID, String password)

Syntax

public void open(String connectionString, String userID, String password);

Parameters

connectionString | Optional. A string that contains connection information.
userID | Optional. A string that contains a user name to use when establishing the connection.
password | Optional. A string that contains a password to use when establishing the connection.

open(String connectionString, String userID, String password, int options)

Syntax

public void open(String connectionString, String userID, String password, int options);

Parameters

connectionString | Optional. A string that contains connection information.
userID | Optional. A string that contains a user name to use when establishing the connection.
password | Optional. A string that contains a password to use when establishing the connection.
options | Optional. A ConnectOption value that determines whether this method should return after (synchronously) or before (asynchronously) the connection is established.


openSchema (Connection Class)

 Microsoft SDK for Java

openSchema

This method of the Connection class returns a Recordset object that contains schema information. The Recordset will be opened as a read-only, static cursor. The schema parameter determines what columns appear in the Recordset. The openSchema method has the following signatures:

openSchema(int schema)
openSchema(int schema, Object[] restrictions)
openSchema(int schema, Object[] restrictions, String schemaID)

openSchema(int schema)

Syntax

public Recordset openSchema(int schema);

Return Value

Returns a Recordset object.

Parameters

schema Any Schema value that represents the type of schema query to run.

openSchema(int schema, Object[] restrictions)

Syntax

public Recordset openSchema(int schema, Object[] restrictions);

Return Value

Returns a Recordset object.

Parameters

schema | Any Schema value that represents the type of schema query to run.
restrictions | Optional. An array of query constraints for each schema option, as listed in Schema.

openSchema(int schema, Object[] restrictions, String schemaID)

Syntax

public Recordset openSchema(int schema, Object[] restrictions, String schemaID);

Return Value

Returns a Recordset object.

Parameters

schema | Any Schema value that represents the type of schema query to run.
restrictions | Optional. An array of query constraints for each schema option, as listed in Schema.
schemaID | The GUID for a provider-schema query not defined by the OLE DB specification. This parameter is required if schema is set to PROVIDERSPECIFIC; otherwise, it is not used.


rollbackTrans (Connection Class)

 Microsoft SDK for Java

rollbackTrans

This method of the Connection class cancels any changes made during the current transaction and ends the transaction. It may also start a new transaction.

Syntax

public void rollbackTrans();


setAttributes (Connection Class)

 Microsoft SDK for Java

setAttributes

This method of the Connection class assigns a read/write value that can be the sum of one or more XactAttribute values. The default is zero (0).

Syntax

public void setAttributes(int attr);

Parameters

attr The integer sum of one or more XactAttribute values.


setCommandTimeout (Connection Class)

 Microsoft SDK for Java

setCommandTimeout

This method of the Connection class assigns how long to wait for a command to execute.

Syntax

public void setCommandTimeout(int timeout);

Parameters

timeout An integer representing seconds.


setConnectionString (Connection Class)

 Microsoft SDK for Java

setConnectionString

This method of the Connection class establishes a connection to a data source.

Syntax

public void setConnectionString(String con);

Parameters

con The name of the connection.


setConnectionTimeout (Connection Class)

 Microsoft SDK for Java

setConnectionTimeout

This method of the Connection class assigns how long to wait for a command to execute.

Syntax

public void setConnectionTimeout(int timeout);

Parameters

timeout An integer representing seconds.


setCursorLocation (Connection Class)

 Microsoft SDK for Java

setCursorLocation

This method of the Connection class assigns the location of the cursor service.

Syntax

public void setCursorLocation(int cursorLoc);

Parameters

cursorLoc Cursor location.


setDefaultDatabase (Connection Class)

 Microsoft SDK for Java

setDefaultDatabase

This method of the Connection class assigns the name of the default database for a Connection object.

Syntax

public void setDefaultDatabase(String db);

Parameters

Db The database name.


setIsolationLevel (Connection Class)

 Microsoft SDK for Java

setIsolationLevel

This method of the Connection class assigns the level of isolation for the transactions opened on the connection.

Syntax

public void setIsolationLevel(int level);

Parameters

level The nesting level.


setMode (Connection Class)

 Microsoft SDK for Java

setMode

This method of the Connection class assigns the available permissions for modifying data in a Connection.

Syntax

public void setMode(int mode);

Parameters

mode A ConnectMode value.


setProvider (Connection Class)

 Microsoft SDK for Java

setProvider

This method of the Connection class assigns the name of the provider for a Connection object.

Syntax

public void setProvider(String provider);

Parameters

provider The provider name.


DataFormat Class (com.ms.wfc.data package)

 Microsoft SDK for Java

DataFormat Class

The DataFormat class of the com.ms.wfc.data package represents the abstract implementation of the IDataFormat interface. This class also converts between the OLE interface IOleDataFormat and the WFC IDataFormat interface.

public abstract class DataFormat
implements IOleDataFormat, IDataFormat
{
  // Constructors
  public DataFormat(IDataFormat format);

  // Methods
  public void addOnFormatChanged(EventHandler handler);
  protected boolean getUseVariant();

protected void onFormatChanged(Event event);

  public void performFormatChanged();
  public void removeOnFormatChanged(EventHandler handler);
}

See Also BooleanDataFormat, DateDataFormat, NumberDataFormat


Constructors (DataFormat Class)

 Microsoft SDK for Java

DataFormat Class Constructors

The DataFormat class has the following constructor:

DataFormat(IDataFormat format)

DataFormat(IDataFormat format)

Creates a DataFormat object.

Syntax

public DataFormat(IDataFormat format);

Parameters

format An object implementing the IDataFormat interface to be wrapped by this object.


Methods (DataFormat class)

 Microsoft SDK for Java

DataFormat Class Methods

The DataFormat class has the following methods:

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.


addOnFormatChanged (DataFormat class)

 Microsoft SDK for Java

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


getUseVariant (DataFormat class)

 Microsoft SDK for Java

getUseVariant

Determines whether the data format object can receive com.ms.com.Variant objects.

Syntax

protected boolean getUseVariant();

Return Value

Returns true if the IDataFormat.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.


onFormatChanged (DataFormat class)

 Microsoft SDK for Java

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


performFormatChanged (DataFormat class)

 Microsoft SDK for Java

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


removeOnFormatChanged (DataFormat class)

 Microsoft SDK for Java

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


DataSpace Class (com.ms.wfc.data package)

 Microsoft SDK for Java

DataSpace Class

The DataSpace class of the com.ms.wfc.data package encapsulates the ADO DataSpace object, which creates client-side proxies to business objects located on the middle tier.

public class DataSpace
{
  // Methods
  public static ObjectProxy DataSpace createObject(String progid, String connection);
  public static int getInternetTimeout();
  public static void setInternetTimeout(int plInetTimeout);
}


Methods (DataSpace Class)

 Microsoft SDK for Java

DataSpace Class Methods

The DataSpace class has the following methods:

createObject specifies a server and communication protocol.
getInternetTimeout retrieves the number of milliseconds to wait before a request times out.
setInternetTimeout assigns the number of milliseconds to wait before a request times out.


createObject (DataSpace Class)

 Microsoft SDK for Java

createObject

This method of the DataSpace class specifies a server and communication protocol.

Syntax

public static ObjectProxy DataSpace createObject(String progid, String connection);

Return Value

Returns a server object.

Parameters

progid | The server name.
connection | The communication protocol.


getInternetTimeout(DataSpace Class)

 Microsoft SDK for Java

getInternetTimeout

This method of the DataSpace class retrieves the number of milliseconds to wait before a request times out.

Syntax

public static int getInternetTimeout();

Return Value

Returns an integer representing timeout in milliseconds.


setInternetTimeout(DataSpace Class)

 Microsoft SDK for Java

setInternetTimeout

This method of the DataSpace class assigns the number of milliseconds to wait before a request times out.

Syntax

public static void setInternetTimeout(int plInetTimeout);

Parameters

plInetTimeout An integer representing timeout in milliseconds.


DateDataFormat Class (com.ms.wfc.data package)

 Microsoft SDK for Java

DateDataFormat Class

The DateDataFormat class of the com.ms.wfc.data package represents a data format object for formatting date data types.

public class DateDataFormat extends DataFormat implements IConstructable
{
  // Constructors

public DateDataFormat(int format);

public DateDataFormat(String customFormat);

public DateDataFormat(int format, String customFormat);

  // Methods
  public String getCustomFormat();
  public int getFormat();
  public void setCustomFormat(String value);
  public void setFormat(int value);
}

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 fields to format date and time values as shown in the following table.

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


Constructors (DateDataFormat Class)

 Microsoft SDK for Java

DateDataFormat Class Constructors

The DateDataFormat class has the following constructors:

DateDataFormat(int format)
DateDataFormat(String customFormat)
DateDataFormat(int format, String customFormat)

DateDataFormat(int format)

Creates a DateDataFormat object.

Syntax

public DateDataFormat(int format);

Parameters

format The type of format. Specify one of the constants defined by the DateFormat class.

DateDataFormat(String customFormat)

Creates a DateDataFormat object.

Syntax

public DateDataFormat(String customFormat);

Parameters

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.

DateDataFormat(int format, String customFormat)

Creates a DateDataFormat object.

Syntax

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.


Methods (DateDataFormat class)

 Microsoft SDK for Java

DateDataFormat Class Methods

The DateDataFormat class has the following methods:

getCustomFormat retrieves the custom format string.
getFormat retrieves the format type.
setCustomFormat sets the custom format string.
setFormat sets the format type.


getCustomFormat (DateDataFormat class)

 Microsoft SDK for Java

getCustomFormat

This method of the DateDataFormat class 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.


getFormat (DateDataFormat class)

 Microsoft SDK for Java

getFormat

This method of the DateDataFormat class retrieves the format type.

Syntax

public int getFormat();

Return Value

Returns one of the constants defined by the DateFormat class.

See Also setFormat


setCustomFormat (DateDataFormat class)

 Microsoft SDK for Java

setCustomFormat

This method of the DateDataFormat class 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, 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 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


setFormat (DateDataFormat class)

 Microsoft SDK for Java

setFormat

This method of the DateDataFormat class 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 (com.ms.wfc.data package)

 Microsoft SDK for Java

DateFormat Class

The DateFormat class of the com.ms.wfc.data package 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.

public final class DateFormat extends Enum
{
  // Methods
  public static boolean valid(int value);

  // Fields
  public static final int CUSTOM;
  public static final int LONG;
  public static final int SHORT;
  public static final int TIME;
}


Methods (DateFormat class)

 Microsoft SDK for Java

DateFormat Class Methods

The DateFormat class has the following method:

valid determines whether the specified value is one of the constants defined in this class.


valid (DateFormat class)

 Microsoft SDK for Java

valid

This method of the DateFormat class determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid(int value);

Return Value

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

Parameters

value The value to check.


Fields (DateFormat)

 Microsoft SDK for Java

DateFormat Class Fields

The DateFormat class has the fields shown in the following table.

Fields | Description
CUSTOM | Specifies a custom date or time format. When a DateDataFormat object's format property is set to CUSTOM, you can define the custom format string through the customFormat property.
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.


Error Class (com.ms.wfc.data package)

 Microsoft SDK for Java

Error Class

The Error class of the com.ms.wfc.data package encapsulates the ADO Error object, which represents a provider error.

public class Error
{
  // Methods
  public String getDescription();
  public int getNativeError();
  public int getNumber();
  public String getSource();
  public String getSQLState();
}


Methods (Error Class)

 Microsoft SDK for Java

Error Class Methods

The Error class has the following methods:

getDescription retrieves the description of an Error object.
getNativeError indicates the provider-specific error code for a given Error object.
getNumber indicates the number that uniquely identifies an Error object.
getSource indicates the name of the object or application that originally generated an error.
getSQLState indicates the SQL state for a given Error object.


getDescription (Error Class)

 Microsoft SDK for Java

getDescription

This method of the Error class retrieves the description of an Error object.

Syntax

public String getDescription();

Return Value

Returns a string value.


getNativeError (Error Class)

 Microsoft SDK for Java

getNativeError

This method of the Error class indicates the provider-specific error code for a given Error object.

Syntax

public int getNativeError();

Return Value

Returns a Long value.


getNumber (Error Class)

 Microsoft SDK for Java

getNumber

This method of the Error class indicates the number that uniquely identifies an Error object.

Syntax

public int getNumber();

Return Value

Returns a Long value that may correspond to one of the ErrorValue constants.


getSource (Error Class)

 Microsoft SDK for Java

getSource

This method of the Error class indicates the name of the object or application that originally generated an error.

Syntax

public String getSource();

Return Value

Returns a String value.


getSQLState (Error Class)

 Microsoft SDK for Java

getSQLState

This method of the Error class indicates the SQL state for a given Error object.

Syntax

public String getSQLState();

Return Value

Returns a five-character String that follows the ANSI SQL standard.


Errors Class (com.ms.wfc.data package)

 Microsoft SDK for Java

Errors Class

The Errors class of the com.ms.wfc.data package encapsulates the ADO Errors collection, which contains all Error objects created in response to provider errors.

public class Errors
{
  // Methods
  public void clear();
  public int getCount();
  public com.ms.wfc.data.Error getItem(int n);
  public com.ms.wfc.data.Error getItem(java.lang.String s);
  public void refresh();
}


Methods (Errors Class)

 Microsoft SDK for Java

Errors Class Methods

The Errors class contains the following methods:

clear removes all the objects in a collection.
getCount retrieves the number of objects in a collection.
getItem retrieves a specific member of a collection by ordinal number or name.
refresh updates the objects in a collection to reflect objects available from and specific to the provider.


clear (Errors Class)

 Microsoft SDK for Java

clear

This method of the Errors class removes all the objects in a collection.

Syntax

public void clear();

Use the clear method on the Errors collection to remove all existing Error objects from the collection. When an error occurs, ADO automatically clears the Errors collection and fills it with Error objects based on the new error.

Some properties and methods return warnings that appear as Error objects in the Errors collection but do not halt a program's execution. Before you call Recordset.resync, Recordset.updateBatch, Recordset.cancelBatch, Connection.open, or Recordset.setFilter, call the clear method on the Errors collection. That way, you can read the count of the Errors collection to test for returned warnings.


getCount (Errors class)

 Microsoft SDK for Java

getCount

This method of the Errors class retrieves the number of objects in a collection.

Syntax

public int getCount();


getItem (Errors class)

 Microsoft SDK for Java

getItem

This method of the Errors class contains the following signatures:

getItem(int n)
getItem(java.lang.String s)

getItem(int n)

Retrieves a specific member of an Errors, Fields, Parameters, or Properties collection by ordinal number.

Syntax

public com.ms.wfc.data.Error getItem(int n);

Parameters

n An integer representing the ordinal number of the collection member.

getItem(java.lang.String s)

Retrieves a specific member of an Errors, Fields, Parameters, or Properties collection by name.

Syntax

public com.ms.wfc.data.Error getItem(java.lang.String s);

Parameters

s A string representing the name of the collection member.


refresh (Errors class)

 Microsoft SDK for Java

refresh

This method of the Errors class updates the objects in a collection to reflect objects available from and specific to the provider.

Syntax

public void refresh();

The refresh method accomplishes different tasks depending on the object from which you call it.

Parameters

Using the refresh method on Command object parameters retrieves provider-side parameter information for the stored procedure or parameterized query specified in the Command object. The collection will be empty for providers that do not support stored procedure calls or parameterized queries.

Pass Command.setActiveConnection a valid Connection object, pass Command.setCommandText a valid command, and set CommandType to STOREDPROC before calling the refresh method.

If you access the Parameters object before calling the refresh method, ADO will automatically call the method and populate the collection for you.

Note If you use the refresh method to obtain parameter information from the provider and it returns one or more variable-length data type Parameter objects, ADO may allocate memory for the parameters based on their maximum potential size, which will cause an error during execution. You should call setSize for these parameters before calling Command.execute to prevent errors.

Fields

Using the refresh method on the Fields collection has no visible effect. To retrieve changes from the underlying database structure, you must use either the Recordset.requery method or, if the Recordset object does not support bookmarks, the moveFirst method.

Properties

Using the refresh method on a Properties collection of some objects populates the collection with the dynamic properties the provider exposes. These properties provide information about functionality specific to the provider, beyond the built-in properties ADO supports.


Field Class (com.ms.wfc.data package)

 Microsoft SDK for Java

Field Class

The Field class of the com.ms.wfc.data package encapsulates the ADO Field object, which represents a column of data with a data type.

  public class Field
{
  // Methods
  public void appendChunk(byte[] bytes);
  public void appendChunk(char[] chars);
  public void appendChunk(String chars);
  public int getActualSize();
  public int getAttributes();
  public void setAttributes(int attr);
  public boolean getBoolean();
  public byte getByte();
  public byte[] getByteChunk(int len);
  public byte[] getBytes();
  public char[] getCharChunk(int len);
  public int getDefinedSize();
  public double getDouble();
  public float getFloat();
  public int getInt();
  public long getLong();
  public String getName();
  public int getNumericScale();
  public Object getObject();
  public Variant getOriginalValue();
  public int getPrecision();
  public AdoProperties getProperties();
  public short getShort();
  public String getString();
  public String getStringChunk(int len);
  public int getType();
  public Variant getUnderlyingValue();
  public Variant getValue();
  public boolean isNull();
  public void setAttributes(int attr);
  public void setBoolean(boolean v);
  public void setByte(byte v);
  public void setBytes(byte[] v);
  public void setDefinedSize(int pl);
  public void setDouble(double v);
  public void setFloat(float v);
  public void setInt(int v);
  public void setLong(long v);
  public void setNull();
  public void setNumericScale(byte pbNumericScale);
  public void setObject(Object v);
  public void setPrecision(byte pbPrecision);
  public void setShort(short v);
  public void setString(String v);
  public void setType(int t);
  public void setValue(Variant v);
}

Field Accessor Methods

The Value property of a Field object gets or sets the content of that object. The content is represented as a VARIANT, a type of object that can be assigned a value and any of several data types.

ADO/WFC implements the Value property with the getValue method, which returns a VARIANT object; and the setValue method, which takes a VARIANT as an argument. VARIANTs are highly efficient in certain languages; however, you can get better performance in Microsoft® Visual J++® by using native Java data types.

In addition to the Value property, ADO/WFC provides accessor methods that use Java data types to get and set the content of Field objects. Most of these methods have names of the form getDataType and setDataType. These are documented in the AdoProperty class.

There are two noteworthy exceptions: One of the getObject methods returns an object coerced to a specified class. There is no getNull method; instead, there is an isNull method that returns a boolean value indicating whether the field is null.


Methods (Field Class)

 Microsoft SDK for Java

Field Class Methods

The Field class has the following methods:

appendChunk appends data to a large text or binary data Field object.
getActualSize returns the actual length of a Field object's value.
getByteChunk retrieves all or part of a Field object's binary data.
getCharChunk retrieves all or part of a Field object's character data.
getDefinedSize and setDefinedSize retrieve or set the data capacity of a Field object, respectively.
getNumericScale and setNumericScale retrieve or set a Byte value that indicates the number of decimal places to which numeric values will be resolved, respectively.
getOriginalValue retrieves the value of a Field that existed in the record before any changes were made.
getPrecision and setPrecision retrieve or set the degree of precision for numeric Field objects, respectively.
getProperties retrieves properties of a Field object.
getStringChunk retrieves all or part of a Field object's string data.
getUnderlyingValue retrieves the current field value from the database.


appendChunk (Field Class)

 Microsoft SDK for Java

appendChunk

This method of the Field class appends data to a large text or binary data Field or Parameter object. The appendChunk method has the following signatures:

appendChunk(byte[] bytes)
appendChunk(char[] chars)
appendChunk(String chars)

In situations where system memory is limited, you can use the appendChunk method to manipulate long values in portions rather than in their entirety.

Implementation in Field Objects

If FieldAttributes.LONG is specified for a Field object, you can use the appendChunk method for that field.

The first appendChunk call on a Field object writes data to the field, overwriting any existing data. Subsequent appendChunk calls add to existing data. If you are appending data to one field and then you set or read the value of another field in the current record, ADO assumes that you are done appending data to the first field. If you call the appendChunk method on the first field again, ADO interprets the call as a new appendChunk operation and overwrites the existing data. Accessing fields in other Recordset objects that are not clones of the first Recordset object will not disrupt appendChunk operations.

If there is no current record when you call appendChunk on a Field object, an error occurs.

Implementation in Parameter Objects

If ParameterAttributes.LONG is specified for a Parameter object, you can use the appendChunk method for that parameter.

The first appendChunk call on a Parameter object writes data to the parameter, overwriting any existing data. Subsequent appendChunk calls on a Parameter object add to existing parameter data. An appendChunk call that passes a null value discards all the parameter data.

appendChunk(byte[] bytes)

Syntax

public void appendChunk(byte[] bytes);

Parameters

bytes The binary data to append.

appendChunk(char[] chars)

Syntax

public void appendChunk(char[] chars);

Parameters

chars The characters to append.

appendChunk(String chars)

Syntax

public void appendChunk(String chars);

Parameters

chars The string to append.


getActualSize (Field Class)

 Microsoft SDK for Java

getActualSize

This method of the Field class returns the actual length of a Field object's value.

For all fields, the value is read-only.

The getActualSize and getDefinedSize methods are different. A Field object of data type char and a maximum length of 50 characters returns a getDefinedSize value of 50, but the getActualSize value it returns is the length of the data stored in the field for the current record.

Syntax

public int getActualSize();

Return Value

Returns the actual length of a Field object's value.


getByteChunk (Field Class)

 Microsoft SDK for Java

getByteChunk

This method of the Field class retrieves all or part of a Field object's binary data.

Syntax

public byte[] getByteChunk(int len);

Parameters

len A number that equals the number of bytes you want to retrieve.


getCharChunk (Field Class)

 Microsoft SDK for Java

getCharChunk

This method of the Field class retrieves all or part of a Field object's character data.

Syntax

public char[] getCharChunk(int len);

Parameters

len A number that equals the number of characters you want to retrieve.


getDefinedSize (Field Class)

 Microsoft SDK for Java

getDefinedSize

The getDefinedSize and setDefinedSize methods of the Field class retrieve or set the data capacity of a Field object, respectively.

The getDefinedSize and getActualSize methods are different. For example, consider a Field object of data type char and a getDefinedSize property value of 50, containing a single character. The getActualSize property value it returns is the length in bytes of the single character.

Syntax

public int getDefinedSize();
public void setDefinedSize(int pl);

Parameters

p1 An integer that sets the data capacity of the field.


getNumericScale (Field Class)

 Microsoft SDK for Java

getNumericScale

The getNumericScale and setNumericScale methods of the Field class retrieve or set, respectively, a Byte value that indicates the number of decimal places to which numeric values will be resolved for a Field or Parameter object.

For Parameter objects, the value is read/write. For Field objects, the value is read-only.

Syntax

public int getNumericScale();
public void setNumericScale(byte pbNumericScale);

Parameters

pbNumericScale A Byte value indicating the number of decimal places to which numeric values will be resolved.


getOriginalValue (Field Class)

 Microsoft SDK for Java

getOriginalValue

This method of the Field class retrieves the value of a Field that existed in the record before any changes were made.

Syntax

public Variant getOriginalValue();

Return Value

Returns a Variant value.


getPrecision (Field Class)

 Microsoft SDK for Java

getPrecision

The getPrecision and setPrecision methods of the Field class retrieve or set, respectively, the degree of precision for numeric values in a Parameter object or for numeric Field objects.

The value is read/write on a Parameter object and read-only on a Field object.

Syntax

public int getPrecision();
public void setPrecision(byte pbPrecision);

Return Value

Returns a Byte value indicating the maximum total number of digits used to represent values.

Parameters

pbPrecision A Byte value indicating the maximum total number of digits used to represent values.


getProperties (Field Class)

 Microsoft SDK for Java

getProperties

This method of the Field class retrieves properties of a Field object.

Syntax

public AdoProperties getProperties();


getStringChunk (Field Class)

 Microsoft SDK for Java

getStringChunk

This method of the Field class retrieves all or part of a Field object's string data.

Syntax

public String getStringChunk(int len);

Parameters

len The length of the string.


getUnderlyingValue (Field Class)

 Microsoft SDK for Java

getUnderlyingValue

This method of the Field class retrieves the current field value from the database.

Syntax

public Variant getUnderlyingValue();


Fields Class (com.ms.wfc.data package)

 Microsoft SDK for Java

Fields Class

The Fields class of the com.ms.wfc.data package encapsulates the ADO Fields collection, which contains all Field objects of a Recordset object.

public class Fields
{
  // Methods
  public void append(String name, int type);
  public void append(String name, int type, int definedSize);
  public void append(String name, int type, int definedSize, int attrib);
  public void clear();
  public void delete(int n);
  public void delete(String s);
  public int getCount();
  public com.ms.wfc.data.Fields getItem(int n);
  public com.ms.wfc.data.Fields getItem(String s);
  public void refresh();
}

See Also

Errors


Methods (Fields Class)

 Microsoft SDK for Java

Fields Class Methods

The Fields class has the following methods that are unique to it (its other methods are documented under the Errors class):

append appends an object to a Fields or Parameters collection.
delete deletes an object from a Fields collection.


append (Fields Class)

 Microsoft SDK for Java

append

The append method appends an object to a Fields or Parameters collection. append has the following signatures:

append(String name, int type)
append(String name, int type, int definedSize)
append(String name, int type, int definedSize, int attrib)

Parameter Types

You must set the type of a Parameter object before appending it to the Parameters collection. If you select a variable-length data type, you must also set the size to a value greater than zero.

Describing parameters yourself minimizes calls to the provider and consequently improves performance when using stored procedures or parameterized queries. However, you must know the properties of the parameters associated with the stored procedure or parameterized query you want to call.

Use the createParameter method to create Parameter objects with the appropriate property settings and use the append method to add them to the Parameters collection. This lets you set and return parameter values without having to call the provider for the parameter information. If you are writing to a provider that does not supply parameter information, you must manually populate the Parameters collection using this method to be able to use parameters at all.

Fields

If the collection is Fields, a new Field object may be created before it is appended to the collection.

The FieldValue parameter is only valid when adding a Field object to a Record object; not to a Recordset object. With a Record object, you may append fields and provide values at the same time. With a Recordset object, you must create fields while the Recordset is closed, then open the Recordset and assign values to the fields.

Recordset

If you do not set the CursorLocation value before calling the append method, CursorLocation will be set to CLIENT automatically when the Recordset object's open method is called.

A runtime error will occur if the append method is called on the Fields collection of an open Recordset, or a Recordset where activeConnection has been set. You can only append fields to a Recordset that is not open and has not yet been connected to a data source. This is typically the case when a Recordset object is fabricated with the createParameter method or assigned to an object variable.

append(String name, int type)

Appends an object to a Fields or Parameters collection.

Syntax

public void append(String name, int type);

Parameters

name | A String that contains the name of the new Field object, and must not be the same name as any other object in fields.
type | A DataType value, whose default value is EMPTY, that specifies the data type of the new field. The following data types are not supported by ADO, and should not be used when appending new fields to a Recordset: IDispatch, IUnknown, and Variant.

append(String name, int type, int definedSize)

Appends an object to a Fields or Parameters collection.

Syntax

public void append(String name, int type, int definedSize);

Parameters

name | A String that contains the name of the new Field object, and must not be the same name as any other object in fields.
type | A DataType value, whose default value is EMPTY, that specifies the data type of the new field. The following data types are not supported by ADO, and should not be used when appending new fields to a Recordset: IDispatch, IUnknown, and Variant.
definedSize | Optional. A Long value that represents the defined size, in characters or bytes, of the new field. The default value for this parameter is derived from getType. (The default DefinedSize is unspecified.)

append(String name, int type, int definedSize, int attrib)

Appends an object to a Fields or Parameters collection.

Syntax

public void append(String name, int type, int definedSize, int attrib);

Parameters

name | A String that contains the name of the new Field object, and must not be the same name as any other object in fields.
type | A DataType value, whose default value is EMPTY, that specifies the data type of the new field. The following data types are not supported by ADO, and should not be used when appending new fields to a Recordset: IDispatch, IUnknown, and Variant.
definedSize | Optional. A value that represents the defined size, in characters or bytes, of the new field. The default value for this parameter is derived from getType. (The default DefinedSize is unspecified.)
attrib | Optional. A FieldAttribute value, whose default value is DEFAULT, that specifies attributes for the new field. If this value is not specified, the field will contain attributes derived from Type.


delete (Fields Class)

 Microsoft SDK for Java

delete

The delete method of the Fields class deletes an object from a Fields collection. delete has the following signatures:

delete(int n)
delete(String s)

delete(int n)

Deletes an object from a Fields collection.

Syntax

public void delete(int n);

Parameters

n Designates the ordinal position of the Field object to delete.

delete(String s)

Deletes an object from a Fields collection.

Syntax

public void delete(String s);

Parameters

s Designates the name of the Field object to delete.


IDataFormat Interface (com.ms.wfc.data package)

 Microsoft SDK for Java

IDataFormat Interface

This interface of the com.ms.wfc.data package defines the data formatting interface.

public interface IDataFormat
{
  // Methods
  public void addOnFormatChanged(EventHandler handler);
  public Object format(Locale locale, Object data);
  public void removeOnFormatChanged(EventHandler handler);
  public Object unformat(Locale locale, Object data);
}

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.


Methods (IDataFormat interface)

 Microsoft SDK for Java

IDataFormat Interface Methods

The IDataFormat interface has the following methods:

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.


addOnFormatChanged (IDataFormat interface)

 Microsoft SDK for Java

addOnFormatChanged

This method of the IDataFormat interface 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


format (IDataFormat interface)

 Microsoft SDK for Java

format

This method of the IDataFormat interface 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


removeOnFormatChanged (IDataFormat interface)

 Microsoft SDK for Java

removeOnFormatChanged

This method of the IDataFormat interface 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


unformat (IDataFormat interface)

 Microsoft SDK for Java

unformat

This method of the IDataFormat interface 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 (com.ms.wfc.data package)

 Microsoft SDK for Java

NumberDataFormat Class

The NumberDataFormat class of the com.ms.wfc.data package represents a data format object for formatting numeric data types.

public class NumberDataFormat extends DataFormat implements IConstructable
{
  // Constructors
  public NumberDataFormat(String format);

  // Methods
  public String getFormat();
  public void setFormat(String value);
}

Remarks

The Column and DataBinding classes provide a dataFormat field, 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");

See Also

BooleanDataFormat
DateDataFormat


Constructors (NumberDataFormat Class)

 Microsoft SDK for Java

NumberDataFormat Class Constructors

The NumberDataFormat class has the following constructor:

NumberDataFormat(String format)

NumberDataFormat(String format)

Creates a NumberDataFormat object.

Syntax

public NumberDataFormat(String format);

Parameters

format The string to be used to format numbers.


Methods (NumberDataFormat class)

 Microsoft SDK for Java

NumberDataFormat Class Methods

The NumberDataFormat class has the following methods:

getFormat retrieves the format string.
setFormat sets the format string.


getFormat (NumberDataFormat class)

 Microsoft SDK for Java

getFormat

This method of the NumberDataFormat class retrieves the format string.

Syntax

public String getFormat();

Return Value

Returns the current format string. For information about possible format strings, see setFormat.


setFormat (NumberDataFormat class)

 Microsoft SDK for Java

setFormat

This method of the NumberDataFormat class 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


ObjectProxy Class (com.ms.wfc.data package)

 Microsoft SDK for Java

ObjectProxy Class

This class of the com.ms.wfc.data package represents a server. An ObjectProxy object is returned by DataSpace.createObject.

public class ObjectProxy
{
  // Methods
  public Object ObjectProxy.call(String method);
  public Object ObjectProxy.call(String method, Object[] args);
}


Methods (ObjectProxy Class)

 Microsoft SDK for Java

ObjectProxy Class Methods

The ObjectProxy class has the following method:

call invokes a method on the server represented by the ObjectProxy.


call (ObjectProxy Class)

 Microsoft SDK for Java

call

This method of the ObjectProxy class invokes a method on the server represented by the ObjectProxy. Optionally, method arguments may be passed as an array of objects. The call method has the following signatures:

ObjectProxy.call(String method)
ObjectProxy.call(String method, Object[] args)

call(String method)

Invokes a method on the server represented by the ObjectProxy.

Syntax

public Object ObjectProxy.call(String method);

Return Value

An object resulting from invoking the method.

Parameters

method A String containing the name of the method to invoke on the server.

call(String method, Object[] args)

Invokes a method on the server represented by the ObjectProxy, passing arguments as an array of objects.

Syntax

public Object ObjectProxy.call(String method, Object[] args);

Return Value

An object resulting from invoking the method.

Parameters

method | A String containing the name of the method to invoke on the server.
args | An array of objects that are arguments to the method on the server. Java data types are automatically converted to data types suitable for use on the server.


Parameter Class (com.ms.wfc.data package)

 Microsoft SDK for Java

Parameter Class

The Parameter class of the com.ms.wfc.data package encapsulates the ADO Parameter object, which represents a parameter or argument associated with a Command object based on a parameterized query or stored procedure.

public class Parameter
{
  // Methods
  public void appendChunk(byte[] bytes);
  public void appendChunk(char[] chars);
  public void appendChunk(String chars);
  public int getAttributes();
  public boolean getBoolean();
  public byte getByte();
  public int getDirection();
  public double getDouble();
  public float getFloat();
  public int getInt();
  public long getLong();
  public String getName();
  public int getNumericScale();
  public int getPrecision();
  public AdoProperties getProperties();
  public short getShort();
  public int getSize();
  public String getString();
  public int getType();
  public boolean isNull();
  public void setAttributes(int attr);
  public void setBoolean(boolean v);
  public void setByte(byte v);
  public void setDirection(int dir);
  public void setDouble(double v);
  public void setFloat(float v);
  public void setInt(int v);
  public void setLong(long v);
  public void setNull();
  public void setNumericScale(byte pbNumericScale);
  public void setPrecision(byte pbPrecision);
  public void setShort(short v);
  public void setSize(int s);
  public void setString(String v);
  public void setType(int t);
  public void setValue(Variant v);
}

Remarks

Many providers support parameterized commands. These are commands where the desired action is defined once, but variables (or parameters) are used to alter some details of the command. For example, an SQL SELECT statement could use a parameter to define the matching criteria of a WHERE clause, and another to define the column name for a SORT BY clause.

Parameter objects represent parameters associated with parameterized queries, or the in/out arguments and the return values of stored procedures. Depending on the functionality of the provider, some collections, methods, or properties of a Parameter object may not be available.

With the collections, methods, and properties of a Parameter object, you can do the following:

  • Set or return the name of a parameter.

  • Set or return the value of a parameter.

  • Set or return parameter characteristics, such as whether it is in, out, or both.

  • Pass long binary or character data to a parameter.

If you know the names and properties of the parameters associated with the stored procedure or parameterized query you wish to call, you can use Command.createParameter to create Parameter objects with the appropriate property settings and use the append method to add them to the Parameters collection. This lets you set and return parameter values without having to call the refresh method on the Parameters collection to retrieve the parameter information from the provider, a potentially resource-intensive operation.


Methods (Parameter Class)

 Microsoft SDK for Java

Parameter Class Methods

The Parameter class has the following methods that are unique to it (its other methods are documented under the Field and AdoProperty classes):

getDirection and setDirection indicate or specify, respectively, whether the Parameter represents an input parameter, an output parameter, or both, or if the parameter is the return value from a stored procedure.
getSize and setSize indicate or set, respectively, the maximum size, in bytes or characters, of a Parameter object.


getDirection (Parameter Class)

 Microsoft SDK for Java

getDirection

This method of the Parameter class indicates whether the Parameter represents an input parameter, an output parameter, or both, or if the parameter is the return value from a stored procedure.

The associated setDirection method specifies how a parameter is passed to or from a procedure. The ParameterDirection field is read/write, which allows you to work with providers that don't return this information. ParameterDirection being read/write also allows you to set parameter information when you don't want ADO to make an extra call to the provider to retrieve parameter information.

Not all providers can determine the direction of parameters in their stored procedures. In these cases, you must use setDirection before you execute the query.

Syntax

public int getDirection();
public void setDirection(int dir);

Return Value

Sets or returns a ParameterDirection value.

Parameters

dir One of the ParameterDirection values.


getSize (Parameter Class)

 Microsoft SDK for Java

getSize

The getSize and setSize methods of the Parameter class indicate or set, respectively, the maximum size, in bytes or characters, of a Parameter object.

Syntax

public int getSize();
public void setSize(int s);

Return Value

Sets or returns a value that indicates the maximum size in bytes or characters of a value in a Parameter object.

Parameters

s A value that indicates the maximum size in bytes or characters of a value in a Parameter object.

Remarks

Use getSize to determine the maximum size for values written to or read from the Parameter object. The size value is read/write.

If you specify a variable-length data type for a Parameter object (for example, any String type), you must set the object's size before appending it to the Parameters collection; otherwise an error occurs.

If you have already appended the Parameter object to the Parameters collection of a Command object and you change its type to a variable-length data type, you must set the Parameter object's size before executing the Command object; otherwise an error occurs.

If you use the refresh method to obtain parameter information from the provider and it returns one or more variable-length data type Parameter objects, ADO may allocate memory for the parameters based on their maximum potential size, which could cause an error during execution. To prevent an error, you should explicitly set the size for these parameters before executing the command.


Parameters Class (com.ms.wfc.data package)

 Microsoft SDK for Java

Parameters Class

The Parameters class of the com.ms.wfc.data package encapsulates the ADO Parameters collection, which contains all Parameter objects of a Command object.

public class Parameters
{
  // Methods
  public void append(com.ms.wfc.data.Parameter p1);
  public void delete(int n);
  public void delete(String s);
  public int getCount();
  public com.ms.wfc.data.Parameter getItem(int n);
  public com.ms.wfc.data.Parameter getItem(java.lang.String s);
  public void refresh();
}

A Command object has a Parameters collection made up of Parameter objects.

Using the Refresh method on a Command object's Parameters collection retrieves provider parameter information for the stored procedure or parameterized query specified in the Command object. Some providers do not support stored procedure calls or parameterized queries; calling the refresh method on the Parameters collection when using such a provider will return an error.

If you have not defined your own Parameter objects and you access the Parameters collection before calling the refresh method, ADO will automatically call the method and populate the collection for you.

You can minimize calls to the provider to improve performance if you know the properties of the parameters associated with the stored procedure or parameterized query you wish to call. Use the createParameter method to create Parameter objects with the appropriate property settings and use the append method to add them to the Parameters collection. This lets you set and return parameter values without having to call the provider for the parameter information. If you are writing to a provider that does not supply parameter information, you must manually populate the Parameters collection using this method to be able to use parameters at all. Use the delete method to remove Parameter objects from the Parameters collection if necessary.


Recordset Class (com.ms.wfc.data package)

 Microsoft SDK for Java

Recordset Class

The Recordset class of the com.ms.wfc.data package encapsulates the ADO Recordset object, which represents the set of records from a base table or from the results of an executed command.

public class Recordset implements Cloneable, IDataSource, IMarshal, IPersistStream
{
  // Methods
  public void addDataSourceListener(IDataSourceListener dsl);
  public void addNew();
  public void addNew(Object[] valueList);
  public void addNew(Object[] fieldList, Object[] valueList);
  public void addOnEndOfRecordset(RecordsetEventHandler handler);
  public void addOnFetchComplete(RecordsetEventHandler handler);
  public void addOnFetchProgress(RecordsetEventHandler handler);
  public void addOnFieldChangeComplete(RecordsetEventHandler handler);
  public void addOnMoveComplete(RecordsetEventHandler handler);
  public void addOnRecordChangeComplete(RecordsetEventHandler handler);
  public void addOnRecordsetChangeComplete(RecordsetEventHandler
    handler);
  public void addOnWillChangeField(RecordsetEventHandler handler);
  public void addOnWillChangeRecord(RecordsetEventHandler handler);
  public void addOnWillChangeRecordset(RecordsetEventHandler handler);
  public void addOnWillMove(RecordsetEventHandler handler);
  public void cancel();
  public void cancelBatch();
  public void cancelBatch(int affectRecords);
  public void cancelUpdate();
  public Object clone();
  public Object clone(int lockType);
  public void close();
  public int compareBookmarks(Object bookmark1, Object bookmark2);
  public void delete();
  public void delete(int affectRecords);
  public void find(String criteria);
  public void find(String criteria, int SkipRecords);
  public void find(String criteria, int SkipRecords,
    int searchDirection);
  public void find(String criteria, int SkipRecords, int searchDirection,
    Object bmkStart);
  public int getAbsolutePage();
  public int getAbsolutePosition();
  public Command getActiveCommand();
  public com.ms.wfc.data.Connection getActiveConnection();
  public boolean getBOF();
  public Object getBookmark();
  public int getCacheSize();
  public int getCursorLocation();
  public int getCursorType();
  public String getDataMember();
  public com.ms.com.IUnknown getDataMember(String s,
    com.ms.com._Guid guid);
  public IUnknown getDataSource();
  public int getEditMode();
  public boolean getEOF();
  public com.ms.wfc.data.Field getField(int n);
  public com.ms.wfc.data.Field getField(String n);
  public Object getFilter();
  public int getLockType();
  public int getMarshalOptions();
  public int getMaxRecords();
  public int getPageCount();
  public int getPageSize();
  public AdoProperties getProperties();
  public int getRecordCount();
  public static com.ms.wfc.data.Recordset
    getRecordset(com.ms.wfc.data.IDataSource p1, java.lang.String p2);
  public com.ms.com.Variant getRows();
  public com.ms.com.Variant getRows(int Rows);
  public com.ms.com.Variant getRows(int Rows, java.lang.Object bmkStart);
  public Object[][] getRows(int Rows, Object bmkStart,
    Object[] fieldList);
  public String getSort();
  public String getSource();
  public int getState();
  public int getStatus();
  public boolean getStayInSync();
  public String getString(int StringFormat);
  public String getString(int StringFormat, int NumRows);
  public String getString(int StringFormat, int NumRows,
    String ColumnDelimiter, String RowDelimiter);
  public String getString(int StringFormat, int NumRows,
    String ColumnDelimiter, String RowDelimiter, String NullExpr);
  public void move(int numRecords);
  public void move(int numRecords, Object bmkStart);
  public void moveFirst();
  public void moveLast();
  public void moveNext();
  public void movePrevious();
  public Recordset nextRecordset();
  public Recordset nextRecordset(int[] recordsAffected);
  public void open();
  public void open(Object source);
  public void open(Object source, Object activeConnection);
  public void open(Object source, Object activeConnection,
    int cursorType);
  public void open(Object source, Object activeConnection,
    int cursorType, int lockType);
  public void open(Object source, Object activeConnection,
    int cursorType, int lockType, int options);
  public void removeOnEndOfRecordset(RecordsetEventHandler handler);
  public void removeOnFetchComplete(RecordsetEventHandler handler);
  public void removeOnFetchProgress(RecordsetEventHandler handler);
  public void removeOnFieldChangeComplete(RecordsetEventHandler handler);
  public void removeOnMoveComplete(RecordsetEventHandler handler);
  public void removeOnRecordChangeComplete
    (RecordsetEventHandler handler);
  public void removeOnRecordsetChangeComplete
    (RecordsetEventHandler handler);
  public void removeOnWillChangeField(RecordsetEventHandler handler);
  public void removeOnWillChangeRecord(RecordsetEventHandler handler);
  public void removeOnWillChangeRecordset(RecordsetEventHandler handler);
  public void removeOnWillMove(RecordsetEventHandler handler);
  public void requery();
  public void requery(int options);
  public void resync();
  public void resync(int affectRecords, int resyncValues);
  public void save(String fileName);
  public void save(String fileName, int persistFormat);
  public void setAbsolutePage(int page);
  public void setAbsolutePosition(int pos);
  public void setActiveConnection(com.ms.wfc.data.Connection con);
  public void setActiveConnection(String conString);
  public void setBookmark(Object bmk);
  public void setCacheSize(int size);
  public void setCursorLocation(int cursorLoc);
  public void setCursorType(int cursorType);
  public void setDataMember(String pbstrDataMember);
  public void setDataSource(IUnknown dataSource);
  public void setFilter(Object filter);
  public void setLockType(int lockType);
  public void setMarshalOptions(int options);
  public void setMaxRecords(int maxRecords);
  public void setPageSize(int pageSize);
  public void setSort(String criteria);
  public void setSource(Command command);
  public void setSource(String query);
  public void setStayInSync(boolean pbStayInSync);
  public boolean supports(int cursorOptions);
  public void update();
  public void update(Object[] valueList);
  public void update(Object[] fieldList, Object[] valueList);
  public void updateBatch();
  public void updateBatch(int affectRecords);
}


Methods (Recordset Class)

 Microsoft SDK for Java

Recordset Class Methods

The Recordset class has the following methods:

addDataSourceListener adds a listener to the notification list.
addNew creates a new record for an updatable Recordset object.
addOnEndOfRecordset and removeOnEndOfRecordset add or remove a notification that the end of the recordset has been reached, respectively.
addOnFetchComplete and removeOnFetchComplete add or remove a notification that the retrieval operation has completed, respectively.
addOnFetchProgress and removeOnFetchProgress add or remove a notification of the progress of a data retrieval operation, respectively.
addOnFieldChangeComplete and removeOnFieldChangeComplete add or remove a notification that the value of the current field has changed, respectively.
addOnMoveComplete and removeOnMoveComplete add or remove a notification that the current row position in a Recordset has changed, respectively.
addOnRecordChangeComplete and removeOnRecordChangeComplete add or remove a notification that something in the current row of the Recordset has changed, respectively.
addOnRecordsetChangeComplete and removeOnRecordsetChangeComplete add or remove a notification that something in the current Recordset has changed, respectively.
addOnWillChangeField and removeOnWillChangeField add or remove a notification that the value of the current field will change, respectively.
addOnWillChangeRecord and removeOnWillChangeRecord add or remove a notification that something in the current row of the Recordset will change, respectively.
addOnWillChangeRecordset and removeOnWillChangeRecordset add or remove a notification that something in the current Recordset will change, respectively.
addOnWillMove and removeOnWillMove add or remove a notification that the current row position in a Recordset will change, respectively.
cancelBatch cancels a pending batch update.
cancelUpdate cancels any changes made to the current record or to a new record prior to calling the update method.
clone creates a duplicate Recordset object from an existing Recordset object.
compareBookmarks compares two bookmarks and returns an indication of their relative values.
delete deletes the current record or a group of records.
find searches a Recordset for the row that satisfies the specified criteria.
getAbsolutePage and setAbsolutePage identify or set the page number on which the current record is located, respectively.
getAbsolutePosition and setAbsolutePosition move to a record based on its ordinal position in the Recordset object, or set the ordinal position of the current record, respectively.
getActiveCommand finds the associated Command object when you are given only the resulting Recordset object.
getBOF indicates whether the current record position is before the first record in a Recordset object.
getBookmark and setBookmark return to a bookmarked record at any time or save the position of the current record, respectively.
getCacheSize and setCacheSize indicate how many records to retrieve at one time into local memory, or control how many records the provider keeps in its buffer, respectively.
getCursorType and setCursorType retrieve or specify the type of cursor that should be used when opening the Recordset object, respectively.
getDataMember and setDataMember determine or set which object specified by getDataSource will be represented as a Recordset object, respectively.
getDataSource and setDataSource retrieve or specify an object containing data to be represented as a Recordset object, respectively.
getEditMode indicates the editing status of the current record.
getEOF indicates whether the current record position is after the last record in a Recordset object.
getField retrieves the value of a field in a Recordset.
getFilter and setFilter retrieve or specify a filter for data in a Recordset, respectively.
getLockType and setLockType indicate or set the type of locks placed on records during editing, respectively.
getMarshalOptions and setMarshalOptions indicate or set which records are to be marshaled back to the server, respectively.
getMaxRecords and setMaxRecords indicate or set the maximum number of records to return to a Recordset from a query, respectively.
getPageCount indicates how many pages of data the Recordset object contains.
getPageSize and setPageSize indicate or set how many records constitute one page in the Recordset, respectively.
getRecordCount indicates the current number of records in a Recordset object.
getRecordset indicates the Recordset object that is returned from a custom business object.
getRows retrieves multiple records of a Recordset object into an array.
getSort and setSort indicate or specify one or more field names on which the Recordset is sorted, and whether each field is sorted in ascending or descending order, respectively.
getSource and setSource indicate or set the source for the data in a Recordset object, respectively.
getStatus indicates the status of the current record with respect to batch updates or other bulk operations.
getStayInSync and setStayInSync indicate or set, in a hierarchical Recordset object, whether the reference to the underlying child records changes when the parent row position changes, respectively.
getString returns the Recordset as a string.
move moves the position of the current record in a Recordset object.
moveFirst moves to the first record in a specified Recordset object and makes that record the current record.
moveLast moves to the last record in a specified Recordset object and makes that record the current record.
moveNext moves to the next record in a specified Recordset object and makes that record the current record.
movePrevious moves to the previous record in a specified Recordset object and makes that record the current record.
nextRecordset clears the current Recordset object and returns the next Recordset by advancing through a series of commands.
open opens a cursor.
requery updates the data in a Recordset object by re-executing the query on which the object is based.
resync refreshes the data in the current Recordset object from the underlying database.
save saves (persists) the Recordset in a file or Stream object.
supports determines whether a specified Recordset object supports a particular type of functionality.
update saves any changes you make to the current record of a Recordset object.
updateBatch writes all pending batch updates to disk.


addDataSourceListener (Recordset Class)

 Microsoft SDK for Java

addDataSourceListener

This method of the Recordset class adds a listener to the notification list.

Syntax

public void addDataSourceListener(IDataSourceListener dsl);

Parameters

dsl The listener to add to the list.


addNew (Recordset Class)

 Microsoft SDK for Java

addNew

The addNew method of the Recordset class creates a new record for an updatable Recordset object. addNew has the following signatures:

addNew()
addNew(Object[] valueList)
addNew(Object[] fieldList, Object[] valueList)

The behavior of addNew depends on the updating mode of the Recordset object and whether you pass the fieldList and valueList arguments.

In immediate update mode (the provider writes changes to the underlying data source once you call update), calling addNew without arguments sets EditMode to ADD. The provider caches any field value changes locally. Calling update posts the new record to the database and resets EditMode to NONE. If you pass the fieldList and valueList arguments, ADO immediately posts the new record to the database (no update call is necessary); EditMode does not change (NONE).

In batch update mode (the provider caches multiple changes and writes them to the underlying data source only when you call updateBatch), calling addNew without arguments sets EditMode to ADD. The provider caches any field value changes locally. Calling update adds the new record to the current recordset and resets EditMode to NONE, but the provider does not post the changes to the underlying database until you call updateBatch. If you pass the fieldList and valueList arguments, ADO sends the new record to the provider for storage in a cache; you need to call updateBatch to post the new record to the underlying database.

addNew()

Creates and initializes a new record, and sets AdoEnums.EditMode to ADD.

Syntax

public void addNew();

addNew(Object[] valueList)

Creates and initializes a new record from an object array.

Syntax

public void addNew(Object[] valueList);

Parameters

valueList An array of values for the fields in the new record. If fieldList is an array, valueList must also be an array with the same number of members; otherwise, an error occurs. The order of field names must match the order of field values in each array.

addNew(Object[] fieldList, Object[] valueList)

In immediate update mode, immediately posts the new record to the database. In batch update mode, causes the new record to be sent to the provider for storage in a cache. A call to updateBatch is required to post the new record to the underlying database.

Syntax

public void addNew(Object[] fieldList, Object[] valueList);

Parameters

fieldList | A single name, or an array of names or ordinal positions of the fields in the new record.
valueList | A single value, or an array of values for the fields in the new record. If fieldList is an array, valueList must also be an array with the same number of members; otherwise, an error occurs. The order of field names must match the order of field values in each array.


addOnEndOfRecordset (Recordset Class)

 Microsoft SDK for Java

addOnEndOfRecordset

The addOnEndOfRecordset and removeOnEndOfRecordset methods of the Recordset class add or remove a notification that the end of the recordset has been reached, respectively.

Syntax

public void addOnEndOfRecordset(RecordsetEventHandler handler);
public void removeOnEndOfRecordset(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


addOnFetchComplete (Recordset Class)

 Microsoft SDK for Java

addOnFetchComplete

The addOnFetchComplete and removeOnFetchComplete methods of the Recordset class add or remove a notification that the retrieval operation has been completed, respectively.

Syntax

public void addOnFetchComplete(RecordsetEventHandler handler);
public void removeOnFetchComplete(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


addOnFetchProgress (Recordset Class)

 Microsoft SDK for Java

addOnFetchProgress

The addOnFetchProgress and removeOnFetchProgress methods of the Recordset class add or remove a notification of the progress of a data retrieval operation, respectively.

Syntax

public void addOnFetchProgress(RecordsetEventHandler handler);
public void removeOnFetchProgress(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


addOnFieldChangeComplete (Recordset Class)

 Microsoft SDK for Java

addOnFieldChangeComplete

The addOnFieldChangeComplete and removeOnFieldChangeComplete methods of the Recordset class add or remove a notification that the value of the current field has changed, respectively.

Syntax

public void addOnFieldChangeComplete(RecordsetEventHandler handler);
public void removeOnFieldChangeComplete(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


addOnMoveComplete (Recordset Class)

 Microsoft SDK for Java

addOnMoveComplete

The addOnMoveComplete and removeOnMoveComplete methods of the Recordset class add or remove a notification that the current row position in a Recordset has changed, respectively.

Syntax

public void addOnMoveComplete(RecordsetEventHandler handler);
public void removeOnMoveComplete(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


addOnRecordChangeComplete (Recordset Class)

 Microsoft SDK for Java

addOnRecordChangeComplete

The addOnRecordChangeComplete and removeOnRecordChangeComplete methods of the Recordset class add or remove a notification that something in the current row of the Recordset has changed, respectively.

Syntax

public void addOnRecordChangeComplete(RecordsetEventHandler handler);
public void removeOnRecordChangeComplete(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


addOnRecordsetChangeComplete (Recordset Class)

 Microsoft SDK for Java

addOnRecordsetChangeComplete

The addOnRecordsetChangeComplete and removeOnRecordsetChangeComplete methods of the Recordset class add or remove a notification that something in the current Recordset has changed, respectively.

Syntax

public void addOnRecordsetChangeComplete(RecordsetEventHandler handler);
public void removeOnRecordsetChangeComplete(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


addOnWillChangeField (Recordset Class)

 Microsoft SDK for Java

addOnWillChangeField

The addOnWillChangeField and removeOnWillChangeField methods of the Recordset class add or remove a notification that the value of the current field will change, respectively.

Syntax

public void addOnWillChangeField(RecordsetEventHandler handler);
public void removeOnWillChangeField(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


addOnWillChangeRecord (Recordset Class)

 Microsoft SDK for Java

addOnWillChangeRecord

The addOnWillChangeRecord and removeOnWillChangeRecord methods of the Recordset class add or remove a notification that something in the current row of the Recordset will change, respectively.

Syntax

public void addOnWillChangeRecord(RecordsetEventHandler handler);
public void removeOnWillChangeRecord(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


addOnWillChangeRecordset (Recordset Class)

 Microsoft SDK for Java

addOnWillChangeRecordset

The addOnWillChangeRecordset and removeOnWillChangeRecordset methods of the Recordset class add or remove a notification that something in the current Recordset will change, respectively.

Syntax

public void addOnWillChangeRecordset(RecordsetEventHandler handler);
public void removeOnWillChangeRecordset(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


addOnWillMove (Recordset Class)

 Microsoft SDK for Java

addOnWillMove

The addOnWillMove and removeOnWillMove methods of the Recordset class add or remove a notification that the current row position in a Recordset will change, respectively.

Syntax

public void addOnWillMove(RecordsetEventHandler handler);
public void removeOnWillMove(RecordsetEventHandler handler);

Parameters

handler The routine defined for this event.


cancelBatch (Recordset Class)

 Microsoft SDK for Java

cancelBatch

The cancelBatch method of the Recordset class cancels a pending batch update. cancelBatch has the following signatures:

cancelBatch()
cancelBatch(int affectRecords)

Use cancelBatch to cancel any pending updates in a recordset in batch update mode. If the Recordset is in immediate update mode, calling cancelBatch without AdoEnums.Affect.CURRENT generates an error.

If you are editing the current record or are adding a new record when you call cancelBatch, ADO first calls cancelUpdate to cancel any cached changes; after that, all pending changes in the recordset are canceled.

It's possible that the current record will be indeterminable after a cancelBatch call, especially if you were in the process of adding a new record. For this reason, it is prudent to set the current record position to a known location in the recordset after the cancelBatch call. For example, call moveFirst.

If the attempt to cancel the pending updates fails because of a conflict with the underlying data (for example, a record has been deleted by another user), the provider returns warnings to the Errors object but does not halt program execution. A runtime error occurs only if there are conflicts on all the requested records. Use AdoEnums.FilterGroup.AFFECTEDRECORDS and AdoEnums.RecordStatus to locate records with conflicts.

cancelBatch()

Cancels a pending batch update.

Syntax

public void cancelBatch();

cancelBatch(int affectRecords)

Cancels a pending batch update.

Syntax

public void cancelBatch(int affectRecords);

Parameters

affectRecords An Ado.Enums.Affect value that determines how many records the cancelBatch method will affect.


cancelUpdate (Recordset Class)

 Microsoft SDK for Java

cancelUpdate

This method of the Recordset class cancels any changes made to the current record or to a new record prior to calling the update method.

Syntax

public void cancelUpdate();

Remarks

You cannot undo changes to the current record or a new record after you call the update method unless the changes are either part of a transaction that you can roll back with the rollbackTrans method or part of a batch update that you can cancel with the cancelBatch method.

If you are adding a new record when you call the cancelUpdate method, the record that was current prior to the addNew call becomes the current record again.

If you have not changed the current record or added a new record, calling the cancelUpdate method generates an error.


clone (Recordset Class)

 Microsoft SDK for Java

clone

The clone method of the Recordset class creates a duplicate Recordset object from an existing Recordset object. Optionally, it specifies that the clone be read-only. clone has the following signatures:

clone()
clone(int lockType)

Remarks

Use the clone method to create multiple, duplicate Recordset objects, particularly if you want to be able to maintain more than one current record in a given set of records. Using the clone method is more efficient than creating and opening a new Recordset object with the same definition as the original.

The current record of a newly created clone is set to the first record.

Changes you make to one Recordset object are visible in all its clones regardless of cursor type. However, once you execute requery on the original Recordset, the clones will no longer be synchronized to the original.

Closing the original Recordset does not close its copies; nor does closing a copy close the original or any of the other copies.

You can only clone a Recordset object that supports bookmarks. Bookmark values are interchangeable; that is, a bookmark reference from one Recordset object refers to the same record in any of its clones.

clone()

Creates a duplicate Recordset object from an existing Recordset object.

Syntax

public Object clone();

Return Value

Returns a Recordset object reference.

clone(int lockType)

Creates a duplicate Recordset object from an existing Recordset object.

Syntax

public Object clone(int lockType);

Return Value

Returns a Recordset object reference.

Parameters

lockType A AdoEnums.LockType value that specifies either the lock type of the original Recordset, or a read-only Recordset. Valid values are UNSPECIFIED or READONLY.


compareBookmarks (Recordset Class)

 Microsoft SDK for Java

compareBookmarks

This method of the Recordset class compares two bookmarks and returns an indication of their relative values.

Syntax

public int compareBookmarks(Object bookmark1, Object bookmark2);

Return Value

Returns a AdoEnums.Compare value that indicates the relative row position of two records represented by their bookmarks.

Parameters

bookmark1 | The bookmark of the first row.
bookmark2 | The bookmark of the second row.

Remarks

The bookmarks must apply to the same Recordset object, or a Recordset object and its clone. You cannot reliably compare bookmarks from different Recordset objects, even if they were created from the same source or command. Nor can you compare bookmarks for a Recordset object whose underlying provider does not support comparisons.

A bookmark uniquely identifies a row in a Recordset object. Use the current row's Bookmark property to obtain its bookmark.

An invalid or incorrectly formed bookmark will cause an error.


delete (Recordset Class)

 Microsoft SDK for Java

delete

The delete method of the Recordset class deletes the current record or a group of records. delete has the following signatures:

delete()
delete(int affectRecords)

Remarks

The delete method marks the current record or a group of records in a Recordset object for deletion. If the Recordset object doesn't allow record deletion, an error occurs. If you are in immediate update mode, deletions occur in the database immediately. Otherwise, the records are marked for deletion from the cache and the actual deletion happens when you call the updateBatch method. (Use the AdoEnums.FilterGroup class to view the deleted records.)

Retrieving field values from the deleted record generates an error. After deleting the current record, the deleted record remains current until you move to a different record. Once you move away from the deleted record, it is no longer accessible.

If you nest deletions in a transaction, you can recover deleted records with the rollbackTrans method. If you are in batch update mode, you can cancel a pending deletion or group of pending deletions with the cancelBatch method.

If the attempt to delete records fails because of a conflict with the underlying data (for example, a record has already been deleted by another user), the provider returns warnings to the Errors object but does not halt program execution. A runtime error occurs only if there are conflicts on all the requested records.

delete()

Deletes the current method.

Syntax

public void delete();

delete(int affectRecords)

Deletes a group of records.

Syntax

public void delete(int affectRecords);

Parameters

affectRecords An AdoEnums.Affect value that determines how many records the delete method will affect. The default value is CURRENT.


find (Recordset Class)

 Microsoft SDK for Java

find

The find method of the Recordset class searches a Recordset for the row that satisfies the specified criteria. find has the following signatures:

find(String criteria)
find(String criteria, int SkipRecords)
find(String criteria, int SkipRecords, int searchDirection)
find(String criteria, int SkipRecords, int searchDirection, Object bmkStart)

Remarks

Only a single column name may be specified in criteria. This method does not support multi-column searches.

The comparison operator in criteria may be ">" (greater than), "<" (less than), "=" (equal), ">=" (greater than or equal), "<=" (less than or equal), "<>" (not equal), or "like" (pattern matching).

The value in criteria may be a string, floating point number, or date. String values are delimited with single quotes or "#" (number sign) marks (for example, "state = 'WA'" or "state = #WA#"). Date values are delimited with "#" (number sign) marks (for example, "start_date > #7/22/97#").

If the comparison operator is "like", the string value may contain an asterisk (*) to find one or more occurrences of any character or substring. For example, "state like 'M*'" matches Maine and Massachusetts. You can also use leading and trailing asterisks to find a substring contained within the values. For example, "state like '*as*'" matches Alaska, Arkansas, and Massachusetts.

Asterisks can be used only at the end of a criteria string, or together at both the beginning and end of a criteria string, as previously shown. Using the asterisk as a leading wildcard ('*str') or embedded wildcard ('s*r') causes an error.

Note An error will occur if a current row position is not set before calling find. Any method which sets row position, such as moveFirst, should be called before calling find.

find(String criteria)

Searches a Recordset for the row that satisfies the specified criteria.

Syntax

public void find(String criteria);

Parameters

criteria A string containing a statement that specifies the column name, comparison operator, and value to use in the search.

find(String criteria, int SkipRecords)

Searches a Recordset for the row that satisfies the specified criteria.

Syntax

public void find(String criteria, int SkipRecords);

Parameters

criteria | A string containing a statement that specifies the column name, comparison operator, and value to use in the search.
SkipRecords | A value, whose default value is zero, that specifies the row offset from the current row or start bookmark to begin the search. By default, the search will start on the current row.

find(String criteria, int SkipRecords, int searchDirection)

Searches a Recordset for the row that satisfies the specified criteria.

Syntax

public void find(String criteria, int SkipRecords, int searchDirection);

Parameters

criteria | A String containing a statement that specifies the column name, comparison operator, and value to use in the search.
SkipRecords | A value, whose default value is zero, that specifies the row offset from the current row or start bookmark to begin the search. By default, the search will start on the current row.
searchDirection | An AdoEnums.SearchDirection value that specifies whether the search should begin on the current row or the next available row in the direction of the search. An unsuccessful search stops at the end of the recordset if the value is FORWARD. An unsuccessful search stops at the start of the recordset if the value is BACKWARD.

find(String criteria, int SkipRecords, int searchDirection, Object bmkStart)

Searches a Recordset for the row that satisfies the specified criteria.

Syntax

public void find(String criteria, int SkipRecords, int searchDirection, Object bmkStart);

Parameters

criteria | A string containing a statement that specifies the column name, comparison operator, and value to use in the search.
SkipRecords | A value, whose default value is zero, that specifies the row offset from the current row or start bookmark to begin the search. By default, the search will start on the current row.
searchDirection | An AdoEnums.SearchDirection value that specifies whether the search should begin on the current row or the next available row in the direction of the search. An unsuccessful search stops at the end of the recordset if the value is FORWARD. An unsuccessful search stops at the start of the recordset if the value is BACKWARD.
bmkStart | A Variant bookmark that functions as the starting position for the search.


getAbsolutePage (Recordset Class)

 Microsoft SDK for Java

getAbsolutePage

The getAbsolutePage and setAbsolutePage methods of the Recordset class identify or set the page number on which the current record is located, respectively.

Syntax

public int getAbsolutePage();
public void setAbsolutePage(int page);

Return Value

Sets or retrieves a Long value from 1 to the number of pages in the Recordset object, or retrieves one of the AdoEnums.Position values.

Parameters

page The number of pages in the Recordset object.

Remarks

Use getAbsolutePage to identify the page number on which the current record is located. Use getPageSize to logically divide the Recordset object into a series of pages, each of which has the number of records equal to setPageSize (except for the last page, which may have fewer records). The provider must support the appropriate functionality for this property to be available.

Like getAbsolutePosition, getAbsolutePage is 1-based and equals 1 when the current record is the first record in the Recordset. Set this property to move to the first record of a particular page. Obtain the total number of pages from getPageCount.


getAbsolutePosition (Recordset Class)

 Microsoft SDK for Java

getAbsolutePosition

The getAbsolutePosition and setAbsolutePosition methods of the Recordset class move to a record based on its ordinal position in the Recordset object, or set the ordinal position of the current record, respectively.

Syntax

public int getAbsolutePosition();
public void setAbsolutePosition(int pos);

Return Value

Sets or retrieves a value from 1 to the number of records in the Recordset object, or retrieves one of the AdoEnums.Position values.

Parameters

pos The desired ordinal position of the current record.

Remarks

The provider must support the appropriate functionality for this property to be available.

Like getAbsolutePage, getAbsolutePosition is 1-based and equals 1 when the current record is the first record in the Recordset. You can obtain the total number of records in the Recordset object from getRecordCount.

When you set the absolute position, even if it is to a record in the current cache, ADO reloads the cache with a new group of records starting with the record you specified. The getCacheSize method determines the size of this group.

Note Do not use the absolute position as a surrogate record number. The position of a given record changes when you delete a preceding record. There is also no assurance that a given record will have the same absolute position if the Recordset object is requeried or reopened. Bookmarks are still the recommended way of retaining and returning to a given position and are the only way of positioning across all types of Recordset objects.


getActiveCommand (Recordset Class)

 Microsoft SDK for Java

getActiveCommand

This method of the Recordset class finds the associated Command object when you are given only the resulting Recordset object.

Syntax

public Command getActiveCommand();

Return Value

Returns a Variant containing a Command object. Default is a Null object reference.

Remarks

The getActiveCommand method returns a read-only value.

If a Command object was not used to create the current Recordset, a Null object reference is returned.

Use getActiveCommand to find the associated Command object when you are given only the resulting Recordset object.


getBOF (Recordset Class)

 Microsoft SDK for Java

getBOF

This method of the Recordset class indicates whether the current record position is before the first record in a Recordset object.

Syntax

public boolean getBOF();

Return Value

Returns True (-1) if the current record position is before the first record and False (0) if the current record position is on or after the first record.

Remarks

Use getBOF and getEOF to determine whether a Recordset object contains records or whether you've gone beyond the limits of a Recordset object when you move from record to record.

The getBOF method returns True (-1) if the current record position is before the first record; returns False (0) if the current record position is on or after the first record.

The getEOF method returns True if the current record position is after the last record; returns False if the current record position is on or before the last record.

If either getBOF or getEOF is True, there is no current record.

If you open a Recordset object containing no records, getBOF and getEOF are set to True and the Recordset object's record count is zero. When you open a Recordset object that contains at least one record, the first record is the current record and the getBOF and getEOF return values are False.

If you delete the last remaining record in the Recordset object, getBOF and getEOF may remain False until you attempt to reposition the current record.

This table shows which move methods are allowed with different combinations of getBOF and getEOF.

 | moveFirst, moveLast | movePrevious, move < 0 | move 0 | moveNext, move > 0
getBOF=True, getEOF=False | Allowed | Error | Error | Allowed
getBOF=False, getEOF=True | Allowed | Allowed | Error | Error
Both True | Error | Error | Error | Error
Both False | Allowed | Allowed | Allowed | Allowed

Allowing a move method doesn't guarantee that the method will successfully locate a record; it only means that calling the specified move method won't generate an error.

The following table shows what happens to the getBOF and getEOF settings when you call various move methods but are unable to successfully locate a record.

 | getBOF | getEOF
moveFirst, moveLast | Set to True | Set to True
move 0 | No change | No change
movePrevious, move < 0 | Set to True | No change
moveNext, move > 0 | No change | Set to True


getBookmark (Recordset Class)

 Microsoft SDK for Java

getBookmark

The getBookmark and setBookmark methods of the Recordset class return to a bookmarked record at any time or save the position of the current record, respectively.

Syntax

public Object getBookmark();
public void setBookmark(Object bmk);

Return Value

Sets or retrieves a Variant expression.

Parameters

bmk A Variant expression that evaluates to a valid bookmark.


getCacheSize (Recordset Class)

 Microsoft SDK for Java

getCacheSize

The getCacheSize and setCacheSize methods of the Recordset class indicate how many records to retrieve at one time into local memory, or control how many records the provider keeps in its buffer, respectively.

Syntax

public int getCacheSize();
public void setCacheSize(int size);

Return Value

Sets or returns a value that must be greater than 0. Default is 1.

Parameters

size An integer that sets the number of records for the provider to keep in its buffer.


getCursorType (Recordset Class)

 Microsoft SDK for Java

getCursorType

The getCursorType and setCursorType methods of the Recordset class retrieve or specify the type of cursor that should be used when opening the Recordset object, respectively.

Syntax

public int getCursorType();
public void setCursorType(int cursorType);

Return Value

Sets or retrieves a AdoEnums.CursorType value. The default value is FORWARDONLY.

Parameters

cursorType One of the AdoEnums.CursorType values.


getDataMember (Recordset Class)

 Microsoft SDK for Java

getDataMember

The getDataMember and setDataMember methods of the Recordset class determine or set which object specified by setDataSource will be represented as a Recordset object, respectively. getDataMember has the following signatures:

getDataMember()
getDataMember(String s, com.ms.com._Guid guid)
setDataMember(String pbstrDataMember)

getDataMember()

Determines which object specified by setDataSource will be represented as a Recordset object.

Syntax

public String getDataMember();
public void setDataMember(String pbstrDataMember);

Return Value

Returns a string value. The name is not case-sensitive.

Remarks

The getDataMember and getDataSource methods must be used in conjunction with each other.

getDataMember(String s, com.ms.com._Guid guid)

Determines which object specified by setDataSource will be represented as a Recordset object.

Syntax

public com.ms.com.IUnknown getDataMember(String s, com.ms.com._Guid guid);

Return Value

Returns a data member identifier.

Parameters

s | A string.
guid | A GUID.

setDataMember

Sets which object specified by setDataSource will be represented as a Recordset object.

Syntax

public void setDataMember(String pbstrDataMember);

Parameters

pbstrDataMember The DataSource object.


getDataSource (Recordset Class)

 Microsoft SDK for Java

getDataSource

The getDataSource and setDataSource methods of the Recordset class retrieve or specify an object containing data to be represented as a Recordset object, respectively.

Syntax

public IUnknown getDataSource();
public void setDataSource(IUnknown dataSource);

Return Value

Returns an object containing data to be represented as a Recordset object.

Parameters

dataSource The data source containing the data object.

Remarks

Use getDataSource to create data-bound controls with the data environment. The data environment maintains collections of data (data sources) containing named objects (data members) that will be represented as a Recordset object.

The getDataMember and getDataSource methods must be used in conjunction with each other.

The object referenced must implement the IDataSource interface.


getEditMode (Recordset Class)

 Microsoft SDK for Java

getEditMode

This method of the Recordset class indicates the editing status of the current record.

Syntax

public int getEditMode();

Return Value

Returns an AdoEnums.EditMode value.


getEOF (Recordset Class)

 Microsoft SDK for Java

getEOF

This method of the Recordset class indicates whether the current record position is after the last record in a Recordset object.

Syntax

public boolean getEOF();

Return Value

Returns True if the current record position is after the last record; returns False if the current record position is on or before the last record.

Remarks

Use getBOF and getEOF to determine whether a Recordset object contains records or whether you've gone beyond the limits of a Recordset object when you move from record to record.

The getBOF method returns True (-1) if the current record position is before the first record; returns False (0) if the current record position is on or after the first record.

The getEOF method returns True if the current record position is after the last record; returns False if the current record position is on or before the last record.

If either getBOF or getEOF is True, there is no current record.

If you open a Recordset object containing no records, getBOF and getEOF are set to True, and the Recordset object's record count is zero. When you open a Recordset object that contains at least one record, the first record is the current record and the getBOF and getEOF return values are False.

If you delete the last remaining record in the Recordset object, getBOF and getEOF may remain False until you attempt to reposition the current record.

This table shows which move methods are allowed with different combinations of getBOF and getEOF.

 | moveFirst, moveLast | movePrevious, move < 0 | move 0 | moveNext, move > 0
getBOF=True, getEOF=False | Allowed | Error | Error | Allowed
getBOF=False, getEOF=True | Allowed | Allowed | Error | Error
Both True | Error | Error | Error | Error
Both False | Allowed | Allowed | Allowed | Allowed

Allowing a move method doesn't guarantee that the method will successfully locate a record; it only means that calling the specified move method won't generate an error.

The following table shows what happens to the getBOF and getEOF settings when you call various move methods but are unable to successfully locate a record.

 | getBOF | getEOF
moveFirst, moveLast | Set to True | Set to True
move 0 | No change | No change
movePrevious, move < 0 | Set to True | No change
moveNext, move > 0 | No change | Set to True


getField (Recordset Class)

 Microsoft SDK for Java

getField

The getField method of the Recordset class retrieves the value of a field in a Recordset. getField has the following signatures:

getField(int n)
getField(String n)

getField(int n)

Retrieves the value of a field in a Recordset.

Syntax

public com.ms.wfc.data.Field getField(int n);

Return Value

Returns the value of a field.

Parameters

n The index of the field.

getField(String n)

Retrieves the value of a field in a Recordset.

Syntax

public com.ms.wfc.data.Field getField(String n);

Return Value

Returns the value of a field.

Parameters

n The name of the field.


getFilter (Recordset Class)

 Microsoft SDK for Java

getFilter

The getFilter and setFilter methods of the Recordset class retrieve or specify a filter for data in a Recordset, respectively.

Syntax

public Object getFilter();
public void setFilter(Object filter);

Return Value

Sets or returns an object that can contain one of the following:

  • A criteria string made up of one or more individual clauses concatenated with AND or OR operators.

  • An array of unique bookmark values that point to records in the Recordset object.

  • A FilterGroup value.

Parameters

filter A FilterGroup value.


getLockType (Recordset Class)

 Microsoft SDK for Java

getLockType

The getLockType and setLockType methods of the Recordset class indicate or set the type of locks placed on records during editing, respectively.

Syntax

public int getLockType();
public void setLockType(int lockType);

Return Value

Returns an AdoEnums.LockType value. The default value is READONLY.

Parameters

lockType One of the AdoEnums.LockType field values.


getMarshalOptions (Recordset Class)

 Microsoft SDK for Java

getMarshalOptions

The getMarshalOptions and setMarshalOptions methods of the Recordset class indicate or set which records are to be marshaled back to the server, respectively.

Syntax

public int getMarshalOptions();
public void setMarshalOptions(int options);

Return Value

Returns an AdoEnums.MarshalOptions value. The default value is ALL.

Parameters

options One of the AdoEnums.MarshalOptions field values.


getMaxRecords (Recordset Class)

 Microsoft SDK for Java

getMaxRecords

The getMaxRecords and setMaxRecords methods of the Recordset class indicate or set the maximum number of records to return to a Recordset from a query, respectively.

Syntax

public int getMaxRecords();
public void setMaxRecords(int maxRecords);

Return Value

Sets or returns a value whose default is zero (no limit).

Parameters

maxRecords The maximum number of records.


getPageCount (Recordset Class)

 Microsoft SDK for Java

getPageCount

This method of the Recordset class indicates how many pages of data the Recordset object contains.

Syntax

public int getPageCount();

Return Value

Returns an integer indicating the number of pages.


getPageSize (Recordset Class)

 Microsoft SDK for Java

getPageSize

The getPageSize and setPageSize methods of the Recordset class indicate or set how many records constitute one page in the Recordset, respectively.

Syntax

public int getPageSize();
public void setPageSize(int pageSize);

Return Value

Sets or returns a value indicating how many records are on a page. The default is 10.

Parameters

pageSize The desired number of records on a page.


getRecordCount (Recordset Class)

 Microsoft SDK for Java

getRecordCount

This method of the Recordset class indicates the current number of records in a Recordset object.

Syntax

public int getRecordCount();

Return Value

Returns an integer indicating the number of records.


getRecordset (Recordset Class)

 Microsoft SDK for Java

getRecordset

This method of the Recordset class indicates the Recordset object that is returned from a custom business object.

Syntax

public static com.ms.wfc.data.Recordset getRecordset(com.ms.wfc.data.IDataSource p1, java.lang.String p2);

Return Value

Returns a Recordset object.

Parameters

p1 | The source of the data.
p2 | The recordset name.


getRows (Recordset Class)

 Microsoft SDK for Java

getRows

The getRows method of the Recordset class retrieves multiple records of a Recordset object into an array. getRows has the following signatures:

getRows()
getRows(int Rows)
getRows(int Rows, java.lang.Object bmkStart)
getRows(int Rows, Object bmkStart, Object[] fieldList)

getRows()

Retrieves multiple records of a Recordset object into an array.

Syntax

public com.ms.com.Variant getRows();

Return Value

Returns a Variant whose value is a two-dimensional array.

getRows(int Rows)

Retrieves multiple records of a Recordset object into an array.

Syntax

public com.ms.com.Variant getRows(int Rows);

Return Value

Returns a Variant whose value is a two-dimensional array.

Parameters

Rows An AdoEnums.GetRowsOption value that indicates the number of records to retrieve. The default is REST.

getRows(int Rows, java.lang.Object bmkStart)

Retrieves multiple records of a Recordset object into an array.

Syntax

public com.ms.com.Variant getRows(int Rows, java.lang.Object bmkStart);

Return Value

Returns a Variant whose value is a two-dimensional array.

Parameters

Rows | An AdoEnums.GetRowsOption value that indicates the number of records to retrieve. The default is REST.
bmkStart | A string or Variant that evaluates to the bookmark for the record from which the getRows operation should begin. You can also use a AdoEnums.Bookmark value.

getRows(int Rows, Object bmkStart, Object[] fieldList)

Retrieves multiple records of a Recordset object into an array.

Syntax

public Object[][] getRows(int Rows, Object bmkStart, Object[] fieldList);

Return Value

Returns a Variant whose value is a two-dimensional array.

Parameters

Rows | An AdoEnums.GetRowsOption value that indicates the number of records to retrieve. The default is REST.
bmkStart | A string or Variant that evaluates to the bookmark for the record from which the getRows operation should begin. You can also use a AdoEnums.Bookmark value.
fieldList | A Variant that represents a single field name or ordinal position or an array of field names or ordinal position numbers. ADO returns only the data in these fields.


getSort (Recordset Class)

 Microsoft SDK for Java

getSort

The getSort and setSort methods of the Recordset class indicate or specify one or more field names on which the Recordset is sorted, and whether each field is sorted in ascending or descending order, respectively.

Syntax

public String getSort();
public void setSort(String criteria);

Return Value

Sets or returns a string of field names in the Recordset to sort on.

Parameters

criteria A string of field names. Each name is separated by a comma, and is optionally followed by a blank and the keyword, ASC, which sorts the field in ascending order, or DESC, which sorts the field in descending order. By default, if no keyword is specified, the field is sorted in ascending order.


getSource (Recordset Class)

 Microsoft SDK for Java

getSource

The getSource and setSource methods of the Recordset class indicate or set the source for the data in a Recordset object (Command object, SQL statement, table name, or stored procedure), respectively.

Syntax

public String getSource();
public void setSource(Command command);
public void setSource(String query);

Return Value

The setSource method sets a Command object reference or String value. The getSource method returns only a String value.

Parameters

command | A Command object reference.
query | A string value.


getStatus (Recordset Class)

 Microsoft SDK for Java

getStatus

This method of the Recordset class indicates the status of the current record with respect to batch updates or other bulk operations.

Syntax

public int getStatus();

Return Value

Returns a sum of one or more AdoEnums.RecordStatus values.


getStayInSync (Recordset Class)

 Microsoft SDK for Java

getStayInSync

The getStayInSync and setStayInSync methods of the Recordset class indicate or set, respectively, whether the reference to the underlying child records (the chapter) changes when the parent row position changes in a hierarchical Recordset object.

Syntax

public boolean getStayInSync();
public void setStayInSync(boolean pbStayInSync);

Return Value

Sets or returns a boolean value.

Parameters

pbStayInSync Determines whether the reference to the underlying child records changes when the parent row position changes. The default value is True. If True, the chapter will be updated if the parent Recordset object changes row position. If False, the chapter will continue to refer to data in the previous chapter although the parent Recordset object has changed row position.


getString (Recordset Class)

 Microsoft SDK for Java

getString

The getString method of the Recordset class returns the Recordset as a string. getString has the following signatures:

getString(int StringFormat)
getString(int StringFormat, int NumRows)
getString(int StringFormat, int NumRows, String ColumnDelimiter, String RowDelimiter)
getString(int StringFormat, int NumRows, String ColumnDelimiter, String RowDelimiter, String NullExpr)

getString(int StringFormat)

Returns the Recordset as a string.

Syntax

public String getString(int StringFormat);

Return Value

Returns the Recordset as a string-valued Variant (BSTR).

Parameters

StringFormat An AdoEnums.StringFormat value that specifies how the Recordset should be converted to a string. The RowDelimiter, ColumnDelimiter, and NullExpr parameters are used with only a StringFormat of CLIPSTRING.

getString(int StringFormat, int NumRows)

Returns the Recordset as a string.

Syntax

public String getString(int StringFormat, int NumRows);

Return Value

Returns the Recordset as a string-valued Variant (BSTR).

Parameters

StringFormat | An AdoEnums.StringFormat value that specifies how the Recordset should be converted to a string. The RowDelimiter, ColumnDelimiter, and NullExpr parameters are used with only a StringFormat of CLIPSTRING.
NumRows | The number of rows in the recordset to convert. If NumRows is not specified or if it is greater than the total number of rows in the recordset, all the rows in the recordset are converted.

getString(int StringFormat, int NumRows, String ColumnDelimiter, String RowDelimiter)

Returns the Recordset as a string.

Syntax

public String getString(int StringFormat, int NumRows, String ColumnDelimiter, String RowDelimiter);

Return Value

Returns the Recordset as a string-valued Variant (BSTR).

Parameters

StringFormat | An AdoEnums.StringFormat value that specifies how the Recordset should be converted to a string. The RowDelimiter, ColumnDelimiter, and NullExpr parameters are used only with a StringFormat of CLIPSTRING.
NumRows | The number of rows in the recordset to convert. If NumRows is not specified, or if it is greater than the total number of rows in the recordset, then all the rows in the recordset are converted.
ColumnDelimiter | A delimiter used between columns if specified, otherwise the TAB character.
RowDelimiter | A delimiter used between rows if specified, otherwise the CARRIAGE RETURN character.

getString(int StringFormat, int NumRows, String ColumnDelimiter, String RowDelimiter, String NullExpr)

Returns the Recordset as a string.

Syntax

public String getString(int StringFormat, int NumRows, String ColumnDelimiter, String RowDelimiter, String NullExpr);

Return Value

Returns the Recordset as a string-valued Variant (BSTR).

Parameters

StringFormat | An AdoEnums.StringFormat value that specifies how the Recordset should be converted to a string. The RowDelimiter, ColumnDelimiter, and NullExpr parameters are used only with a StringFormat of CLIPSTRING.
NumRows | The number of rows in the recordset to convert. If NumRows is not specified, or if it is greater than the total number of rows in the recordset, all the rows in the recordset are converted.
ColumnDelimiter | A delimiter used between columns if specified, otherwise the TAB character is used.
RowDelimiter | A delimiter used between rows if specified, otherwise the CARRIAGE RETURN character is used.
NullExpr | An expression used in place of a NULL value if specified, otherwise the empty string is used.


move (Recordset Class)

 Microsoft SDK for Java

move

The move method of the Recordset class moves the position of the current record in a Recordset object. move has the following signatures:

move(int numRecords)
move(int numRecords, Object bmkStart)

move(int numRecords)

Moves the position of the current record in a Recordset object.

Syntax

public void move(int numRecords);

Parameters

numRecords An integer specifying the number of records the current record position moves.

move(int numRecords, Object bmkStart)

Moves the position of the current record in a Recordset object.

Syntax

public void move(int numRecords, Object bmkStart);

Parameters

numRecords | An integer specifying the number of records the current record position moves.
bmkStart | A string or Variant that evaluates to a bookmark. You can also use an AdoEnums.Bookmark value.


moveFirst (Recordset Class)

 Microsoft SDK for Java

moveFirst

This method of the Recordset class moves to the first record in a specified Recordset object and makes that record the current record.

Syntax

public void moveFirst();


moveLast (Recordset Class)

 Microsoft SDK for Java

moveLast

This method of the Recordset class moves to the last record in a specified Recordset object and makes that record the current record.

Syntax

public void moveLast();


moveNext (Recordset Class)

 Microsoft SDK for Java

moveNext

This method of the Recordset class moves to the next record in a specified Recordset object and makes that record the current record.

Syntax

public void moveNext();


movePrevious (Recordset Class)

 Microsoft SDK for Java

movePrevious

This method of the Recordset class moves to the previous record in a specified Recordset object and makes that record the current record.

Syntax

public void movePrevious();


nextRecordset (Recordset Class)

 Microsoft SDK for Java

nextRecordset

This method of the Recordset class clears the current Recordset object and returns the next Recordset by advancing through a series of commands. nextRecordset has the following signatures:

nextRecordset()
nextRecordset(int[] recordsAffected)

nextRecordset()

Clears the current Recordset object and returns the next Recordset.

Syntax

public Recordset nextRecordset();

Return Value

Returns a Recordset object.

nextRecordset(int[] recordsAffected)

Clears the current Recordset object and returns the next Recordset.

Syntax

public Recordset nextRecordset(int[] recordsAffected);

Return Value

Returns a Recordset object.

Parameters

recordsAffected A Long variable to which the provider returns the number of records that the current operation affected.


open (Recordset Class)

 Microsoft SDK for Java

open

This method of the Recordset class opens a cursor. open has the following signatures:

open()
open(Object source)
open(Object source, Object activeConnection)
open(Object source, Object activeConnection, int cursorType)
open(Object source, Object activeConnection, int cursorType, int lockType)
open(Object source, Object activeConnection, int cursorType, int lockType, int options)

open()

Opens a cursor.

Syntax

public void open();

open(Object source)

Opens a cursor.

Syntax

public void open(Object source);

Parameters

source A Variant that evaluates to a valid Command object, an SQL statement, a table name, a stored procedure call, a URL, or the name of a file or Stream object containing a persisted Recordset.

open(Object source, Object activeConnection)

Opens a cursor.

Syntax

public void open(Object source, Object activeConnection);

Parameters

source | A Variant that evaluates to a valid Command object, an SQL statement, a table name, a stored procedure call, a URL, or the name of a file or Stream object containing a persisted Recordset.
activeConnection | Either a Variant that evaluates to a valid Connection object variable name, or a connection string.

open(Object source, Object activeConnection, int cursorType)

Opens a cursor.

Syntax

public void open(Object source, Object activeConnection, int cursorType);

Parameters

source | A Variant that evaluates to a valid Command object, an SQL statement, a table name, a stored procedure call, a URL, or the name of a file or Stream object containing a persisted Recordset.
activeConnection | Either a Variant that evaluates to a valid Connection object variable name, or a connection string.
cursorType | An AdoEnums.CursorType value that determines the type of cursor that the provider should use when opening the Recordset. The default value is FORWARDONLY.

open(Object source, Object activeConnection, int cursorType, int lockType)

Opens a cursor.

Syntax

public void open(Object source, Object activeConnection, int cursorType, int lockType);

Parameters

source | A Variant that evaluates to a valid Command object, an SQL statement, a table name, a stored procedure call, a URL, or the name of a file or Stream object containing a persisted Recordset.
activeConnection | Either a Variant that evaluates to a valid Connection object variable name, or a connection string.
cursorType | An AdoEnums.CursorType value that determines the type of cursor that the provider should use when opening the Recordset. The default value is FORWARDONLY.
lockType | An AdoEnums.LockType value that determines what type of locking (concurrency) the provider should use when opening the Recordset. The default value is READONLY.

open(Object source, Object activeConnection, int cursorType, int lockType, int options)

Opens a cursor.

Syntax

public void open(Object source, Object activeConnection, int cursorType, int lockType, int options);

Parameters

source | A Variant that evaluates to a valid Command object, an SQL statement, a table name, a stored procedure call, a URL, or the name of a file or Stream object containing a persisted Recordset.
activeConnection | Either a Variant that evaluates to a valid Connection object variable name, or a connection string.
cursorType | An AdoEnums.CursorType value that determines the type of cursor that the provider should use when opening the Recordset. The default value is FORWARDONLY.
lockType | An AdoEnums.LockType value that determines what type of locking (concurrency) the provider should use when opening the Recordset. The default value is READONLY.
options | An integer value that indicates how the provider should evaluate the source argument if it represents something other than a Command object, or that the Recordset should be restored from a file where it was previously saved. Can be one or more AdoEnums.CommandType or AdoEnums.ExecuteOption values.


requery (Recordset Class)

 Microsoft SDK for Java

requery

This method of the Recordset class updates the data in a Recordset object by re-executing the query on which the object is based. requery has the following signatures:

requery()
requery(int options)

requery()

Updates the data in a Recordset object.

Syntax

public void requery();

requery(int options)

Updates the data in a Recordset object.

Syntax

public void requery(int options);

Parameters

options A bitmask that contains an AdoEnums.ExecuteOption value affecting this operation. If this parameter is set to ASYNCEXECUTE, this operation will execute asynchronously and an addOnRecordsetChangeComplete event will be issued when it concludes.


resync (Recordset Class)

 Microsoft SDK for Java

resync

This method of the Recordset class refreshes the data in the current Recordset object from the underlying database. resync has the following signatures:

resync()
resync(int affectRecords, int resyncValues)

resync()

Refreshes the data in the current Recordset object from the underlying database.

Syntax

public void resync();

resync(int affectRecords, int resyncValues)

Refreshes the data in the current Recordset object from the underlying database.

Syntax

public void resync(int affectRecords, int resyncValues);

Parameters

affectRecords | An AdoEnums.Affect value that determines how many records the resync method will affect.
resyncValues | An AdoEnums.Resync value that specifies whether underlying values are overwritten.


save (Recordset Class)

 Microsoft SDK for Java

save

This method of the Recordset class saves (persists) the Recordset in a file or Stream object. save has the following signatures:

save(String fileName)
save(String fileName, int persistFormat)

save(String fileName)

Saves (persists) the Recordset in a file or Stream object.

Syntax

public void save(String fileName);

Parameters

fileName A string that represents the complete path name of the file where the Recordset is to be saved, or a reference to a Stream object.

save(String fileName, int persistFormat)

Saves (persists) the Recordset in a file or Stream object.

Syntax

public void save(String fileName, int persistFormat);

Parameters

fileName | A string that represents the complete path name of the file where the Recordset is to be saved, or a reference to a Stream object.
persistFormat | An AdoEnums.PersistFormat value that specifies the format in which the Recordset is to be saved (XML or ADTG). The default value is ADTG.


supports (Recordset Class)

 Microsoft SDK for Java

supports

This method of the Recordset class determines whether a specified Recordset object supports a particular type of functionality.

Syntax

public boolean supports(int cursorOptions);

Return Value

Returns a boolean value that indicates whether all the features identified by the cursorOptions argument are supported by the provider.

Parameters

cursorOptions An integer that consists of one or more AdoEnums.CursorOption values.


update (Recordset Class)

 Microsoft SDK for Java

update

This method of the Recordset class saves any changes you make to the current record of a Recordset object. update has the following signatures:

update()
update(Object[] valueList)
update(Object[] fieldList, Object[] valueList)

update()

Saves changes to the current record of a Recordset object.

Syntax

public void update();

update(Object[] valueList)

Saves changes to the current record of a Recordset object.

Syntax

public void update(Object[] valueList);

Parameters

valueList Represents a single value or a Variant array that represents values for the field or fields in the new record.

update(Object[] fieldList, Object[] valueList)

Saves changes to the current record of a Recordset object.

Syntax

public void update(Object[] fieldList, Object[] valueList);

Parameters

fieldList | Represents a single name or a Variant array that represents names or ordinal positions of the field or fields you wish to modify.
valueList | Represents a single value or a Variant array that represents values for the field or fields in the new record.


updateBatch (Recordset Class)

 Microsoft SDK for Java

updateBatch

This method of the Recordset class writes all pending batch updates to disk. updateBatch has the following signatures:

updateBatch()
updateBatch(int affectRecords)

updateBatch()

Writes all pending batch updates to disk.

Syntax

public void updateBatch();

updateBatch(int affectRecords)

Writes all pending batch updates to disk.

Syntax

public void updateBatch(int affectRecords);

Parameters

affectRecords An AdoEnums.Affect value that determines how many records the updateBatch method will affect.


RecordsetEvent Class (com.ms.wfc.data package)

 Microsoft SDK for Java

RecordsetEvent Class

The RecordsetEvent class of the com.ms.wfc.data package provides data for events that result from an operation performed with a Recordset object.

public class RecordsetEvent extends AdoEvent
{
  //Fields
  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;
}


Fields (RecordsetEvent Class)

 Microsoft SDK for Java

RecordsetEvent Class Fields

The RecordsetEvent class has the fields shown in the following table.

Field | Description
adReason | An AdoEnums.EventReason value that specifies the reason for this event.
adStatus | An AdoEnums.EventStatus value.
cFields | The number of Field objects in fields.
cRecords | The number of records affected.
error | An Error object that describes the error that occurred if the value of AdoEnums.EventStatus is ERRORSOCCURRED; otherwise it is not set.
fields | An array of Variants containing Field objects with pending changes.
fMoreData | A boolean flag. It is possible to append new records while processing this event. Before addOnEndOfRecordset returns, add your data, then set this parameter to True to indicate that there is a new end to the Recordset.
maxProgress | The maximum number of records expected to be retrieved.
progress | The number of records that have currently been retrieved by the fetch operation.


Package com.ms.wfc.data.ui

Microsoft Packages Overview

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
ColumnEditingEvent | Creates a ColumnEditingEvent object.


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

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

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

Specifies the zero-based index of the column that is being edited.

Syntax

public final int column;


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

Constructors | Description
ColumnEvent | Creates a ColumnEvent object.


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

Fields | Description
column | Specifies the zero-based index of the column that the event applies to.


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

Constructors | Description
ColumnResizeEvent | Creates a columnResizeEvent object.


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

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

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

Specifies the zero-based index of the column that is being resized.

Syntax

public int column;


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

Constructors | Description
ColumnUpdatingEvent | Creates a ColumnUpdatingEvent object.


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

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

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

Specifies the zero-based index of the column that is being updated.

Syntax

public int column;


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

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

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

Removes all current bindings.

Syntax

public void clearBindings()

See Also addBinding , removeBinding


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

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

Retrieves an array of all current bindings.

Syntax

public DataBinding[] getBindings()

Return Value

Returns an array of DataBinding objects.

See Also setBindings


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

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

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

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

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

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

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

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

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

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

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

Retrieves the data source underlying the DataBinding control.

Syntax

public Recordset getDataSource()

Return Value

Returns the underlying Recordset object.

See Also setDataSource


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

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

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

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

Updates the property of the bound component with data from the data source.

Syntax

public void refreshPropertyValue()

See Also setPropertyValue


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

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

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

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

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

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, Binding Data with the DataGrid Control.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Removes any selection in the grid.

Syntax

public void clearSelection()

See Also setSelectedColumns , setSelectedRows


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Closes the connection to the data source.

Syntax

public void close()

See Also begin


DataSource.DataSource

Creates a DataSource control.

Syntax

public DataSource()


DataSource.dispose

Disposes of this component.

Syntax

public void dispose()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

See Also setLockType


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
ErrorEvent | Creates a ErrorEvent object.


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

Fields | Description
displayDialog | Indicates whether an unhandled exception dialog box should be displayed.
error | Specifies the ADO exception that was generated.


ErrorEvent.displayDialog

Indicates whether an unhandled exception dialog box should be displayed.

Syntax

public boolean displayDialog;


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

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

Specifies that the control has no gridlines between cells.

Syntax

public static final int NONE;

See Also DataGrid.getGridLineStyle, DataGrid.setGridLineStyle


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

Specifies that the control's gridlines are single lines.

Syntax

public static final int SINGLELINE;

See Also DataGrid.getGridLineStyle, DataGrid.setGridLineStyle


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

Constructors | Description
PositionChangeEvent | Creates a PositionChangeEvent object.


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

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

Specifies the zero-based index of the column that was current before the position changed.

Syntax

public int lastColumn;


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

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

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

Specifies that only the horizontal scroll bar is displayed.

Syntax

public static final int HORIZONTAL;

See Also DataGrid.getScrollbars , DataGrid.setScrollbars


Scrollbars.NONE

Specifies that no scroll bars are displayed.

Syntax

public static final int NONE;

See Also DataGrid.getScrollbars , DataGrid.setScrollbars


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

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

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

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

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

Microsoft Packages Overview

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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

Specifies vertical bottom alignment.

Syntax

public static final int ABSBOTTOM;


DhAlignment.ABSMIDDLE

Specifies vertical middle alignment.

Syntax

public static final int ABSMIDDLE;


DhAlignment.BASELINE

Specifies alignment at the baseline of the current line's text.

Syntax

public static final int BASELINE;


DhAlignment.BOTTOM

Specifies bottom alignment.

Syntax

public static final int BOTTOM;


DhAlignment.CENTER

Specifies center alignment.

Syntax

public static final int CENTER;


DhAlignment.JUSTIFY

Specifies justified alignment.

Syntax

public static final int JUSTIFY;


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

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

Specifies a subscript attribute.

Syntax

public static final int SUBSCRIPT;


DhAlignment.SUPERSCRIPT

Specifies a superscript attribute.

Syntax

public static final int SUPERSCRIPT;


DhAlignment.TEXTTOP

Specifies alignment with the top of the current line's text.

Syntax

public static final int TEXTTOP;


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

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

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

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

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

Recursively retrieves all child elements and their children.

Syntax

public DhElement[] getAllElements()

Return Value

Returns an array of all child elements.


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

Retrieves the direct child elements of this container.

Syntax

public DhElement[] getElements()

Return Value

Returns an array of direct child elements.


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

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

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

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

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

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

Sets the document that is associated with this container.

Syntax

public void setDocument( DhDocument document )

Parameters

document

The document to be set.


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

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

Constructors | Description
DhBorderInfo | Creates a DhBorderInfo object.

Methods | Description
clone | Retrieves an identical copy of this DhBorderInfo object.
copy | Copies another DhBorderInfo object's internal data to this one.


DhBorderInfo.clone

Retrieves an identical copy of this DhBorderInfo object.

Syntax

public DhBorderInfo clone()

Return Value

Returns a new DhBorderInfo object.


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

Creates a DhBorderInfo object.

Syntax

public DhBorderInfo()

public DhBorderInfo( DhBorderInfo biInit )

Parameters

biInit

An existing DhBorderInfo object used to initialize this DhBorderInfo.


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

Specifies the bottom border color.

Syntax

public Color bottomColor;


DhBorderInfo.bottomStyle

Specifies the current bottom border style as one of the DhBorderStyle constants.

Syntax

public int bottomStyle;


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

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

Specifies the left border color.

Syntax

public Color leftColor;


DhBorderInfo.leftStyle

Specifies the current left border style as one of the DhBorderStyle constants.

Syntax

public String leftStyle;


DhBorderInfo.leftWidth

Specifies the current left border width as an integer in the unit specified by leftWidthUnit.

Syntax

public int leftWidth;


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

Specifies the right border color.

Syntax

public Color rightColor;


DhBorderInfo.rightStyle

Specifies the current right border style as one of the DhBorderStyle constants.

Syntax

public String rightStyle;


DhBorderInfo.rightWidth

Specifies the current right border width.

Syntax

public int rightWidth;


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

Specifies the top border color.

Syntax

public Color topColor;


DhBorderInfo.topStyle

Specifies the current top border style as one of the DhBorderStyle constants.

Syntax

public String topStyle;


DhBorderInfo.topWidth

Specifies the current top border width in the unit specified by topWidthUnit.

Syntax

public int topWidth;


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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

Specifies the combination of all border side items. This is equivalent to (TOP | RIGHT | BOTTOM | LEFT)

Syntax

public static final int ALL;


DhBorders.BOTTOM

Specifies the bottom border.

Syntax

public static final int BOTTOM;


DhBorders.LEFT

Specifies the left border.

Syntax

public static final int LEFT;


DhBorders.RIGHT

Specifies the right border.

Syntax

public static final int RIGHT;


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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

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

Specifies that a three-dimensional groove is drawn in colors based on the value.

Syntax

public static final int GROOVE;


DhBorderStyle.INSET

Specifies that a three-dimensional inset is drawn in colors based on the value.

Syntax

public static final int INSET;


DhBorderStyle.NONE

Specifies that no border is drawn (regardless of any border width).

Syntax

public static final int NONE;


DhBorderStyle.OUTSET

Specifies that a three-dimensional outset is drawn in colors based on the value.

Syntax

public static final int OUTSET;


DhBorderStyle.RIDGE

Specifies that a three-dimensional ridge is drawn in colors based on the value.

Syntax

public static final int RIDGE;


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

Constructors | Description
DhBreak | Creates a DhBreak object.

Methods | Description
getClearFlag | Retrieves the current clear flag.
setClearFlag | Sets the current clear flag.


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

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

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

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

Inserts vertical space so that the next text displayed is past all floating images.

Syntax

public static final int CLEAR_ALL;


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

Inserts a standard line break (the default).

Syntax

public static final int CLEAR_NONE;


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
    (&quot;AppCodeName = &quot; + browser.getAppCodeName()));
    this.newLine();
    this.add(t2 = new DhText(&quot;MinorVersion = &quot;
    + browser.getAppMinorVersion()));
    this.newLine();
    this.add(t3 = new DhText(&quot;AppName = &quot;
    + browser.getAppName()));
    this.newLine();
    this.add(t4 = new DhText(&quot;AppVersion = &quot;
    + browser.getAppVersion()));
    this.newLine();
    this.add(t5 = new DhText(&quot;BrowserLanguage = &quot;
    + browser.getBrowserLanguage()));
    this.newLine();
    this.add(t6 = new DhText(&quot;CpuClass = &quot;
    + browser.getCpuClass()));
    this.newLine();
    this.add(t7 = new DhText(&quot;Platform = &quot;
    + browser.getPlatform()));
    this.newLine();
    this.add(t8 = new DhText(&quot;SystemLanguage = &quot;
    + browser.getSystemLanguage()));
    this.newLine();
    this.add(t9 = new DhText(&quot;UserAgent = &quot;
    + browser.getUserAgent()));
    this.newLine();
    this.add(t10 = new DhText(&quot;UserLanguage = &quot;
    + browser.getUserLanguage()));
  }


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

Retrieves the browser's code name.

Syntax

public String getAppCodeName()

Return Value

Returns the code name of the browser (for example, "Mozilla").


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

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

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

Retrieves the browser language setting.

Syntax

public String getBrowserLanguage()

Return Value

Returns a string containing the browser language.


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

Retrieves the CPU class string.

Syntax

public String getCpuClass()

Return Value

Returns the CPU type, such as "x86", "Alpha", or "Other".


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

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

Retrieves the platform setting.

Syntax

public String getPlatform()

Return Value

Returns the platform string (for example, "Win32").


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

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

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

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

Adds the specified element to the end of the list.

Syntax

public void addItem( DhElement e )

Parameters

e

The element to add.


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

Recursively retrieves all child elements and their children.

Syntax

public DhElement[ ] getAllElements( )

Returns

Returns an array of all child elements.


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

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

Retrieves an array of elements in the list.

Syntax

public DhElement[ ] getItems( )

Returns

Returns an array of elements in the list.


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

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

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

Removes all the elements from the list.

Syntax

public void removeAll()


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

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

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

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

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

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

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

Retrieves the label from the button.

Syntax

public String getText()

Return Value

Returns the current label string.

See Also setText


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

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

Constructors | Description
DhCantAddElementException | Creates a DhCantAddElementException object.


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

Constructors | Description
DhCantModifyElementException | Creates a DhCantModifyElementException object.


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

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

Adds an element to the cell.

Syntax

public void add( DhElement e )

Parameters

e

The DhElement element to add.

See Also remove


DhCell.DhCell

Creates an empty cell.

Syntax

public DhCell()

public DhCell( String text )

Parameters

text

The text contents of the cell.


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

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

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

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

Retrieves the text of the cell.

Syntax

public String getText()

Return Value

Returns the cell text.

See Also setText


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

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

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

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

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

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

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

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

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

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

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

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

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

Sets the input focus to this control.

Syntax

public void focus()


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

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

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

Retrieves the submit value for this check box.

Syntax

public String getSubmitValue( )

Return Value

Returns the current submit value.

See Also setSubmitValue


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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
DhComboBox | Creates an empty DhComboBox object.


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

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

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

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

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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

Specifies that the browser determines the cursor to display based on the current context.

Syntax

public static final int AUTO;


DhCursor.CROSSHAIR

Specifies a simple cross-hair cursor.

Syntax

public static final int CROSSHAIR;


DhCursor.DEFAULT

Specifies a platform-dependent default cursor (usually an arrow).

Syntax

public static final int DEFAULT;


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

Specifies a hand pointer cursor.

Syntax

public static final int HAND;


DhCursor.HELP

Specifies an arrow cursor with a question mark indicating Help.

Syntax

public static final int HELP;


DhCursor.MOVE

Specifies a cursor with crossed arrows indicating something is to be moved.

Syntax

public static final int MOVE;


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

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

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

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

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

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

Specifies an editable text cursor (usually an I-bar).

Syntax

public static final int TEXT;


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

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

Constructors | Description
DhDialogInfo | Creates a DhDialogInfo object.

Methods | Description
toString | Retrieves a string representation of this object.


DhDialogInfo.DhDialogInfo

Creates a DhDialogInfo object.

Syntax

public DhDialogInfo()


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

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

Displays the dialog box centered on the desktop.

Syntax

public boolean showCentered;

Remarks

© 1999 Microsoft Corporation. All rights reserved. Terms of use.


DhDialogInfo.showHelpButton

Adds or removes a Help button on the dialog box's title bar.

Syntax

public boolean showHelpButton;


DhDialogInfo.showMaximizeButton

Adds or removes a Maximize button on the dialog box's title bar.

Syntax

public boolean showMaximizeButton;


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

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

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

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

Appends a text string to the current document.

Syntax

public void addText( String text )

Parameters

text

The text string.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves the DhModule associated with this document.

Syntax

public DhModule getModule()

Return Value

Returns the DhModule associated with this document.


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

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

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

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

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

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

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

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

Retrieves the Window object of this document.

Syntax

final public DhWindow getWindow()

Return Value

Returns the Window object of the document.


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

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

Displays a modal user message box.

Syntax

final public void messageBox( String s )

Parameters

s

The message string to display.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Clears the text from the edit box.

Syntax

public void clear()


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

Sets the input focus to this edit box.

Syntax

public void focus()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves the number of elements contained by this element.

Syntax

public int getElementCount()

Return Value

This implementation returns 0.


DhElement.getElements

Retrieves an array of all elements contained by this element.

Syntax

public DhElement[] getElements()

Return Value

This implementation returns null.


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

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

Retrieves the current HTML generator for this element.

Syntax

public DhHTMLGenerator getHTMLGenerator()

Return Value

Returns the current DhHTMLGenerator object.

See Also setHTMLGenerator


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

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

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

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

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

Retrieves the size of the element.

Syntax

public Point getSize()

Return Value

Returns the element size.

Overrides DhStyleBase.getSize

See Also setSize


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Clears any align property.

Syntax

public final void resetAlign()

See Also getAlign


DhElement.resetID

Creates a new default ID for this element.

Syntax

public final void resetID()

See Also getID


DhElement.resetStyle

Clears any class set with setStyle.

Syntax

public final void resetStyle()

See Also getStyle


DhElement.resetToolTip

Resets the ToolTip to the default (usually blank).

Syntax

public final void resetToolTip()

See Also getToolTip


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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
DhElementExistsInDocumentException | Creates an ElementExistsinDocumentException object.


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

Constructors | Description
DhElementNotFoundException | Creates a DhElementNotFoundException object.


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

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

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

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

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

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

Resets the enumerator to the beginning.

Syntax

public void reset()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Tests for the ALT key.

Syntax

final public boolean isAltKey()

Return Value

Returns true if the ALT key is pressed.


DhEventInfo.isCtrlKey

Tests for the CTRL key.

Syntax

final public boolean isCtrlKey()

Return Value

Returns true if the CTRL key is pressed.


DhEventInfo.isShiftKey

Tests for the SHIFT key.

Syntax

final public boolean isShiftKey()

Return Value

Returns true if the SHIFT key is pressed.


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

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

Converts this event object to a string.

Syntax

public String toString()

Remarks

Use this method when performing diagnostics on your code.


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

Indicates that the left mouse button has been pressed.

Syntax

public static final int EVT_LEFTBUTTON;


DhEventInfo.EVT_MIDDLEBUTTON

Indicates that the middle mouse button has been pressed.

Syntax

public static final int EVT_MIDDLEBUTTON;


DhEventInfo.EVT_NOBUTTON

Indicates that no mouse button has been pressed.

Syntax

public static final int EVT_NOBUTTON;


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

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

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

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

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

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

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

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

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

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

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

Appends a text string to the current section.

Syntax

public void addText( String text )

Parameters

text

The text string to append.


DhForm.DhForm

Creates a DhForm section container.

Syntax

public DhForm()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
DhHorizontalRule | Creates a DhHorizontalRule object (a horizontal rule element).


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

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

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

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

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

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

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

Retrieves the current coordinate string.

Syntax

public String getCoordsString()

Return Value

Returns a string containing the current coordinates.

See Also setCoords


DhHotSpot.getShape

Retrieves the current shape constant.

Syntax

public int getShape()

Return Value

Returns the shape.

See Also setShape, DhHotSpotShapes


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

Retrieves the URL to navigate to if the user selects this hotspot.

Syntax

public String getURL()

Return Value

Returns the current URL.


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

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

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

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

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

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

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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Fields | Description
UNKNOWN_KEY | This value is returned by getNameKey if the name is not registered.


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

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

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

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

Returns the local target of the jump.

Syntax

public final DhElement getJumpPoint()

See Also setJumpPoint


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

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

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

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

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

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

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

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 frames page.

See Also setStockTargetWindow, getTargetWindow


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

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

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

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

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

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

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

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

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

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

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

Retrieves an array of the DhHotSpot objects contained in this image.

Syntax

public DhHotSpot[] getHotSpots()

Return Value

Returns the DhHotSpot array.


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

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

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

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

Removes the specified DhHotSpot from the image.

Syntax

final public void removeHotSpot( DhHotSpot hs )

Parameters

hs

The DhHotSpot to remove.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

Specifies that the item is inserted after the designated item in the list.

Syntax

public static final int AFTER;


DhInsertOptions.BEFORE

Specifies that the item is inserted before the designated item in the list.

Syntax

public static final int BEFORE;


DhInsertOptions.BEGINNING

Specifies that the item is inserted at the beginning of the current list.

Syntax

public static final int BEGINNING;


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

Constructors | Description
DhJumpPoint | Creates a DhJumpPoint object.

Methods | Description
getName | Retrieves the current jump point name.
setName | Sets the jump point name.


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

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

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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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 frames page.
TOP_FRAME | Instructs the browser to put the document into the top-most window, replacing the current frames page.


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

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

Instructs the browser to put the document into the current frame of the frames page.

Syntax

public static final int THIS_FRAME;


DhLinkTarget.TOP_FRAME

Instructs the browser to put the document into the top-most window, replacing the current frames page.

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

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

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

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

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

Retrieves the number of currently visible rows.

Syntax

public int getVisibleRows( )

Return Value

Returns the number of rows.

See Also setVisibleRows


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

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

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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

Represents a list in which each item has a small bullet.

Syntax

public final static int BULLETED;


DhListType.DIR

Represents a list in which each item has a large bullet.

Syntax

public final static int DIR;


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

Represents a list in which each item has an assigned uppercase roman numeral.

Syntax

public final static int LARGE_ROMAN;


DhListType.MENU

Represents a list in which each item has a large bullet.

Syntax

public final static int MENU;


DhListType.NUMBERED

Represents a list in which each item has an assigned number.

Syntax

public final static int NUMBERED;


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

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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

Specifies the combination of all constants. This is equivalent to (TOP | RIGHT | BOTTOM | LEFT).

Syntax

public static final int ALL;


DhMargins.BOTTOM

Specifies a bottom margin.

Syntax

public static final int BOTTOM;


DhMargins.LEFT

Specifies a left margin.

Syntax

public static final int LEFT;


DhMargins.RIGHT

Specifies a right margin.

Syntax

public static final int RIGHT;


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

Constructors | Description
DhMarginWidthInfo | Constructs a DhMarginWidthInfo object.


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

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

Specifies the bottom margin width unit as one of the DhUnits constants.

Syntax

public int bottomUnit;


DhMarginWidthInfo.bottomWidth

Specifies the bottom margin width in units specified by bottomUnit.

Syntax

public int bottomWidth;


DhMarginWidthInfo.leftUnit

Specifies the left margin width unit as one of the DhUnits constants.

Syntax

public int leftUnit;


DhMarginWidthInfo.leftWidth

Specifies the left margin width in units specified by leftUnit.

Syntax

public int leftWidth;


DhMarginWidthInfo.rightUnit

Specifies the right margin width unit as one of the DhUnits constants.

Syntax

public int rightUnit;


DhMarginWidthInfo.rightWidth

Specifies the right margin width in units specified by rightUnit.

Syntax

public int rightWidth;


DhMarginWidthInfo.topUnit

Specifies the top margin width unit as one of the DhUnits constants.

Syntax

public int topUnit;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 Java moniker name (for example "java:myapplet") as the CLASSID parameter value.

See Also com.ms.com._Guid


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

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

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

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

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

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

Retrieves the object representing the HTML OBJECT instantiated.

Syntax

public Object getObjectPeer()

Return Value

Returns the object representing the HTML OBJECT instantiated.


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

Retrieves the value of the parameter.

Syntax

public String getValue( String param )

Parameters

param

The name of the parameter.


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

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

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

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

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

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

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

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

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.

com.ms.wfc.core.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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

Specifies a combination of all padding constants.

Syntax

public static final int ALL;

Remarks

This is equivalent to (TOP | RIGHT | BOTTOM | LEFT).


DhPaddings.BOTTOM

Specifies bottom padding.

Syntax

public static final int BOTTOM;


DhPaddings.LEFT

Specifies left padding.

Syntax

public static final int LEFT;


DhPaddings.RIGHT

Specifies right padding.

Syntax

public static final int RIGHT;


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

Constructors | Description
DhPaddingWidthInfo | Creates a DhPaddingWidthInfo object.


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

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

Specifies the bottom padding width unit as one of the DhUnits constants.

Syntax

public int bottomUnit;


DhPaddingWidthInfo.bottomWidth

Specifies the bottom padding width in units specified by bottomUnit.

Syntax

public int bottomWidth;


DhPaddingWidthInfo.leftUnit

Specifies the left padding width unit as one of the DhUnits constants.

Syntax

public int leftUnit;


DhPaddingWidthInfo.leftWidth

Specifies the left padding width in units specified by leftUnit.

Syntax

public int leftWidth;


DhPaddingWidthInfo.rightUnit

Specifies the right padding width unit as one of the DhUnits constants.

Syntax

public int rightUnit;


DhPaddingWidthInfo.rightWidth

Specifies the right padding width in units specified by rightUnit.

Syntax

public int rightWidth;


DhPaddingWidthInfo.topUnit

Specifies the top padding width unit as one of the DhUnits constants.

Syntax

public int topUnit;


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

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

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

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

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

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

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

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

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

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

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

Sets the input focus to this control.

Syntax

public void focus()


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

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

Retrieves the name of the button.

Syntax

public String getName()

Return Value

Returns the button name.

See Also setName


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

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

Retrieves the current text label for the radio button.

Syntax

public String getText()

Return Value

Returns the text label.

See Also setText


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

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

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

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

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

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

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

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

Sets the name of the button.

Syntax

public void setName( String n )

Parameters

n

The name of the button.

See Also getName


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

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

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

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

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

Creates a DhRawHTML object.

Syntax

public DhRawHTML()

public DhRawHTML( String html )

Parameters

html

The initial HTML string.

See Also setHTML


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

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

Constructors | Description
DhResetButton | Creates a DhResetButton object.

Methods | Description
getText | Retrieves the button's current text caption.
setText | Sets the button caption.


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

Retrieves the button's current text caption.

Syntax

public String getText()

Return Value

Returns the button caption.

See Also 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

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

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

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

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

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

Creates a DhRow object.

Syntax

public DhRow()

Remarks

This constructor creates an empty row.


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

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

Returns the number of columns in this row.

Syntax

public int getColumnCount()

Return Value

Returns the number of columns.


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

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

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

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

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

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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

Indicates that the browser will add scroll bars as needed.

Syntax

public static final int AUTO;


DhScrollBars.NO

Indicates that scrolling is disabled.

Syntax

public static final int NO;


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

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

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

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

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

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

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

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

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

Sets the input focus to this control.

Syntax

public void focus()


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

Retrieves the number of items currently in the list.

Syntax

public int getItemCount()

Return Value

Returns the number of items.


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

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

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

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

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

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

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

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

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

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

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

Removes all items from the control.

Syntax

public void removeAll()


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

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

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


DhSelectBox.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

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

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

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

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

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

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

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

Sets the current selected index.

Syntax

public void setSelectedIndex( int index )

Parameters

index

The zero-based index of the item to select.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves the current font.

Syntax

public Font getFont()

Return Value

Returns a Font object with the current font.

See Also setFont


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Resets the background color to the default inherited setting.

Syntax

final public void resetBackColor()

See Also getBackColor


DhStyleBase.resetBorder

Clears the current border settings.

Syntax

public void resetBorder()


DhStyleBase.resetClip

Resets the clipping region to the default inherited setting.

Syntax

public void resetClip()


DhStyleBase.resetCursor

Resets the current cursor style to the default.

Syntax

public void resetCursor()

See Also getCursor


DhStyleBase.resetFont

Clears any font settings from the element and allows them to be inherited.

Syntax

public void resetFont()

See Also getFont


DhStyleBase.resetForeColor

Resets the foreground color to the default inherited setting.

Syntax

final public void resetForeColor()

See Also getForeColor


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

Clears the current margin settings.

Syntax

public void resetMargin()


DhStyleBase.resetPadding

Clears the current padding settings.

Syntax

public void resetPadding()


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

Clears any existing text alignment property.

Syntax

public void resetTextAlign()

See Also getTextAlign


DhStyleBase.resetTextVerticalAlign

Clears any existing vertical text alignment property.

Syntax

public void resetTextVerticalAlign()

See Also getTextVerticalAlign


DhStyleBase.resetZIndex

Clears any z-index setting.

Syntax

public void resetZIndex()

See Also getZIndex


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sets the margins widths.

Syntax

public void setMarginWidthInfo( DhMarginWidthInfo mwi )

Parameters

mni

The DhMarginWidthInfo margin width settings.

See Also getMarginWidthInfo


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Fields | Description
UNINITIALIZED | Indicates that the style has not been set.


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

Constructors | Description
DhSubmitButton | Creates a DhSubmitButton object.

Methods | Description
getText | Retrieves the button's current text caption.
setText | Sets the button caption.


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

Retrieves the button's current text caption.

Syntax

public String getText()

Return Value

Returns the button caption.

See Also 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

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

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

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

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

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

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

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

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

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

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

Retrieves the table CELLPADDING attribute.

Syntax

final public int getCellPadding()

Return Value

Returns the integer padding value.

See Also setCellPadding


DhTable.getCellSpacing

Retrieves the table CELLSPACING attribute.

Syntax

final public int getCellSpacing()

Return Value

Returns the integer padding value.

See Also setCellSpacing


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

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

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

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

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

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

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

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

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

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

Refreshes the table's data if it is bound to the document.

Syntax

public void refresh()


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

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

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

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

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

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

Set the table's CELLPADDING attribute.

Syntax

final public void setCellPadding( int padding )

Parameters

padding

The integer padding value.

See Also getCellPadding


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

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

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

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

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

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

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

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

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

Displays the next page of data in the table.

Syntax

public void showNextPage()

See Also setPageSize


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

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

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

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

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

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

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

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

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

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

Retrieves the text this element currently displays when rendered.

Syntax

public String getText()

Return Value

Returns the text this element displays.


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

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

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

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

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

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

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

Sets (or resets) the text to display in this element.

Syntax

public void setText( String s )

Parameters

s

The text to display.


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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

Specifies that the text contents will behave with normal HTML flow.

Syntax

public final static int FLOW;


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

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

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


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

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

Represents the auto type.

Syntax

public static final int AUTO;


DhUnits.CM

Represents the centimeter (cm) type.

Syntax

public static final int CM;


DhUnits.COLOR

Represents the color type.

Syntax

public static final int COLOR;


DhUnits.EM

Represents the relative height of the element's font (em).

Syntax

public static final int EM;


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

Represents an inches (in) type.

Syntax

public static final int INCH;


DhUnits.MM

Represents a millimeter (mm) type.

Syntax

public static final int MM;


DhUnits.NULL

Represents an unspecified or absent type.

Syntax

public static final int NULL;


DhUnits.PC

Represents a pica (pc) type.

Syntax

public static final int PC;


DhUnits.PERCENT

Represents the percentage (%) type.

Syntax

public static final int PERCENT;


DhUnits.PIXEL

Represents a pixel (px) type.

Syntax

public static final int PIXEL;


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

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

Closes the window, and resets its document and window peers to null.

Syntax

public void close()

See Also getClosed


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

Retrieves a representation of the browser.

Syntax

final public DhBrowser getBrowser()

Return Value

Returns an object representing the browser.


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

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

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

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

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

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

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

Retrieves the number of entries in the window's history.

Syntax

final public int getHistoryLength()

Return Value

Returns the history length.


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

Retrieves the parent of this window.

Syntax

public DhWindow getParent()

Return Value

Returns the parent window of this window.


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

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

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

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

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

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

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

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

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

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

Displays a modal user message box.

Syntax

final public void MessageBox( String s )

Parameters

s

The message to display.


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

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

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

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

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

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

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

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

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

Creates a DhWindowInfo object.

Syntax

public DhWindowInfo()

public DhWindowInfo( Rectangle size )

Parameters

size

A Rectangle object describing the size of the window.


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

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

Retrieves a string representation of the DhWindowInfo object.

Syntax

public String toString()


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

Informs the browser to open a new window and make it resizable using resize handles.

Syntax

public boolean isResizable;


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

Informs the browser to open a new window and add directory buttons.

Syntax

public boolean showDirectoryButtons;


DhWindowInfo.showFullScreen

Informs the browser to open a new window using the full screen as size.

Syntax

public boolean showFullScreen;


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

Informs the browser to open a new window with the menu bar showing.

Syntax

public boolean showMenubar;


DhWindowInfo.showScrollbars

Informs the browser to open a new window with the scroll bars showing.

Syntax

public boolean showScrollbars;


DhWindowInfo.showStatusbar

Informs the browser to open a new window with the status bar showing.

Syntax

public boolean showStatusbar;


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

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

Microsoft Packages Overview

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

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

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

Closes the buffer.

Syntax

public void close()


BufferedStream.flush

Forces any data remaining in the buffer to be written to the file.

Syntax

public void flush()


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

Retrieves the position of this stream.

Syntax

public long getPosition()

Return Value

Returns the current position of the stream.


BufferedStream.getStream

Retrieves the current buffered stream.

Syntax

public IByteStream getStream()

Return Value

Returns the current buffered stream.


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

Reads a byte from this stream.

Syntax

public byte readByte()

Return Value

Returns a byte of data from this stream.


BufferedStream.readChar

Reads a character from this stream.

Syntax

public char readChar()

Return Value

Returns a character of data from this stream.


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

Reads an integer from this stream.

Syntax

public int readInt()

Return Value

Returns an integer from this stream.


BufferedStream.readShort

Reads a short value from this stream.

Syntax

public short readShort()

Return Value

Returns the short value read.


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

Reads a null-terminated Unicode string from this stream.

Syntax

public String readStringNull()


BufferedStream.readStringNullAnsi

Reads a null-terminated ANSI string from this stream.

Syntax

public String readStringNullAnsi()

Return Value

Returns the string value read.


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

Sets the position of this stream.

Syntax

public void setPosition( long position )

Parameters

position

The position in the data stream to set.


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

Writes a byte to this stream.

Syntax

public void writeByte( byte value )

Parameters

value

The value to write.


BufferedStream.writeChar

Writes a character to this stream.

Syntax

public void writeChar( char value )

Parameters

value

The value to write.


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

Writes an integer to this stream.

Syntax

public void writeInt( int value )

Parameters

value

The value to write.


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

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

Specifies an American National Standards Institute (ANSI) code page.

Syntax

public static final int ANSI;


CodePage.MAC

Specifies a code page for the Apple Macintosh operating system.

Syntax

public static final int MAC;


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

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

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

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

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

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

Creates a DataStream object.

Syntax

protected DataStream()

Remarks

This constructor is protected to prevent instantiation of this class.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
EOFException | Creates an EOFException object.


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

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

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

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

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

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

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

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

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

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

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

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

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

Finalizes this File object by ensuring that the close method is called.

Syntax

protected void finalize() throws Throwable


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

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

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

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

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

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

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

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

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

Retrieves the specification for the logical drives.

Syntax

public static String[] getLogicalDrives()

Return Value

Returns the specification for the logical drives.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

Specifies that the file or directory is compressed.

Syntax

public static final int COMPRESSED;

Remarks

For a file, this means that all 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

Specifies that the file is a directory.

Syntax

public static final int DIRECTORY;


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

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

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

Specifies that the file is part of or is used exclusively by the operating system.

Syntax

public static final int SYSTEM;


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() &amp; 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

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

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

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

Ensures that the close method has been called for this file enumerator.

Syntax

protected void finalize()


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

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

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

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

Retrieves the name of the current file.

Syntax

public String getName()

Return Value

Returns the name of the file.


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

Retrieves the size in bytes of the current file.

Syntax

public long getSize()

Return Value

Returns the size of the file.


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
IOException | Creates an IOException object.


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

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

Closes this Reader object and releases any system resources associated with the reader.

Syntax

public void close()


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

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

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

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

Closes this Writer object and releases any system resources associated with the writer.

Syntax

public void close()


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

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

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

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

Retrieves the current size of the stream.

Syntax

public int getCapacity()

Return Value

Returns the current size of the stream.


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

Retrieves the position of this stream.

Syntax

public long getPosition()

Return Value

Returns the current position of the stream.


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

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

Reads a byte from this stream.

Syntax

public byte readByte()

Return Value

Returns a byte of data from the stream.


MemoryStream.readChar

Reads a character from this stream.

Syntax

public char readChar()

Return Value

Returns a character of data from this stream.


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

Reads an integer from this stream.

Syntax

public int readInt()

Return Value

Returns an integer from this stream.


MemoryStream.readShort

Reads a short value from this stream.

Syntax

public short readShort()

Return Value

Returns the short value that was read.


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

Reads a null-terminated Unicode string from this stream.

Syntax

public String readStringNull()

Return Value

Returns the string value that was read.


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

Flushes the stream buffer.

Syntax

public void reset()


MemoryStream.setLength

Sets the length of this stream.

Syntax

public void setLength( long length )

Parameters

length

The new length of the stream.


MemoryStream.setPosition

Sets the position of this stream.

Syntax

public void setPosition( long value )

Parameters

value

The new position of the stream.


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

Writes a single byte of data to this stream.

Syntax

public void write( int value )

Parameters

value

The value to write.


MemoryStream.writeByte

Writes a byte to this stream.

Syntax

public void writeByte( byte value )

Parameters

value

The value to write.


MemoryStream.writeChar

Writes a character to this stream.

Syntax

public void writeChar( char value )

Parameters

value

The value to write.


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

Writes an integer to this stream.

Syntax

public void writeInt( int value )

Parameters

value

The value to write.


MemoryStream.writeShort

Writes a short value to this stream.

Syntax

public void writeShort( short value )

Parameters

value

The value to write.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Fields | Description
err | Specifies the standard error.
in | Specifies the standard input.
out | Specifies the standard output.


Text.err

Specifies the standard error.

Syntax

public static final TextWriter err;


Text.in

Specifies the standard input.

Syntax

public static final TextReader in;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Microsoft Packages Overview

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 effects of a drag-and-drop operation.

DragEvent

Provides data for 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 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(&quot;D:\\WINNT\\clock.avi&quot;); //sets the file to play
   animation1.start(3,4,-1); //plays from frame 4 to the end of the movie 3 times
}


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

Constructors | Description
AutoSizeEvent | Creates a AutoSizeEvent object.


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

Fields | Description
newRectangle | Specifies the Rectangle object that represents the bounding rectangle for the resized control.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Frees the resources allocated by the Bitmap object.

Syntax

protected void finalize()


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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Draws a three-dimensional border on the lower side of a rectangle.

Syntax

public static final int BOTTOM;


Border3DSide.LEFT

Draws a three-dimensional border on the left side of a rectangle.

Syntax

public static final int LEFT;


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

Draws a three-dimensional border on the right side of a rectangle.

Syntax

public static final int RIGHT;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

Specifies a raised outer edge and a sunken inner edge.

Syntax

public static final int BUMP;


Border3DStyle.ETCHED

Specifies a sunken inner edge and a raised outer edge.

Syntax

public static final int ETCHED;


Border3DStyle.FLAT

Specifies a border with no three-dimensional effects.

Syntax

public static final int FLAT;


Border3DStyle.RAISED

Specifies raised inner and outer edges.

Syntax

public static final int RAISED;


Border3DStyle.RAISEDINNER

Specifies a raised inner edge and no outer edge.

Syntax

public static final int RAISEDINNER;


Border3DStyle.RAISEDOUTER

Specifies a raised outer edge and no inner edge.

Syntax

public static final int RAISEDOUTER;


Border3DStyle.SUNKEN

Specifies sunken inner and outer edges.

Syntax

public static final int SUNKEN;


Border3DStyle.SUNKENINNER

Specifies a sunken inner edge and no outer edge.

Syntax

public static final int SUNKENINNER;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies a three-dimensional line border.

Syntax

public static final int FIXED_3D;


BorderStyle.FIXED_SINGLE

Specifies a single-line border.

Syntax

public static final int FIXED_SINGLE;


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

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

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

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

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

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

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

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

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

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

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

Computes and returns the hash code for this Brush object.

Syntax

public int hashCode()

Return Value

Returns an integer hash code value.


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

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

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

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

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

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

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

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

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

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

Represents a Brush object that is the color of a standard halftone brush.

Syntax

public static final Brush HALFTONE;


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

Represents a hollow brush.

Syntax

public static final Brush HOLLOW;

Remarks

A hollow brush paints nothing.


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

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

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

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

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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


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

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

Specifies a hatched brush consisting of backward diagonal lines.

Syntax

public static final int BACKWARDDIAGONAL;


BrushStyle.CROSS

Specifies a hatched brush consisting of horizontal and vertical crossing lines.

Syntax

public static final int CROSS;


BrushStyle.DIAGONALCROSS

Specifies a hatched brush consisting of diagonal crossing lines.

Syntax

public static final int DIAGONALCROSS;


BrushStyle.FORWARDDIAGONAL

Specifies a hatched brush consisting of forward diagonal lines.

Syntax

public static final int FORWARDDIAGONAL;


BrushStyle.HOLLOW

Specifies a "hollow" brush. A hollow brush does not paint.

Syntax

public static final int HOLLOW;


BrushStyle.HORIZONTAL

Specifies a hatched brush consisting of horizontal lines.

Syntax

public static final int HORIZONTAL;


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

Specifies a solid-colored brush.

Syntax

public static final int SOLID;


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

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

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

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

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

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

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

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

Generates a click event for the button, simulating a click by a user.

Syntax

public final void performClick()


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

Specifies that the button is flat.

Syntax

public static final int FLAT;


ButtonState.INACTIVE

Specifies that the button is disabled.

Syntax

public static final int INACTIVE;


ButtonState.NORMAL

Specifies that the button is three-dimensional and not pressed.

Syntax

public static final int NORMAL;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies a Close button.

Syntax

public static final int CLOSE;


CaptionButton.HELP

Specifies a Help button.

Syntax

public static final int HELP;


CaptionButton.MAXIMIZE

Specifies a Maximize button.

Syntax

public static final int MAXIMIZE;


CaptionButton.MINIMIZE

Specifies a Minimize button.

Syntax

public static final int MINIMIZE;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that all characters should be converted to lowercase.

Syntax

public static final int LOWER;


CharacterCasing.NORMAL

Specifies that the case of characters should be left unchanged.

Syntax

public static final int NORMAL;


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.

com.ms.wfc.core.Component.html">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

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

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

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

Creates a CheckBox control.

Syntax

public CheckBox()

Remarks

By default, a check box is unchecked.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a CheckedListBox control.

Syntax

public CheckedListBox()


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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the control is checked.

Syntax

public static final int CHECKED;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves a string description of the Color object.

Syntax

public String toString()

Return Value

Returns a string describing the Color object.


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

Represents the color of an active window border.

Syntax

public static final Color ACTIVEBORDER;


Color.ACTIVECAPTION

Represents the color of the background of an active title bar caption.

Syntax

public static final Color ACTIVECAPTION;


Color.ACTIVECAPTIONTEXT

Represents the text color of an active title bar caption.

Syntax

public static final Color ACTIVECAPTIONTEXT;


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

Represents the color aqua.

Syntax

public static final Color AQUA;


Color.BLACK

Represents the color black.

Syntax

public static final Color BLACK;


Color.BLUE

Represents the color blue.

Syntax

public static final Color BLUE;


Color.BROWN

Represents the color brown.

Syntax

public static final Color BROWN;


Color.CONTROL

Represents the color for controls.

Syntax

public static final Color CONTROL;


Color.CONTROLDARK

Represents the shadow part of a 3D element.

Syntax

public static final Color CONTROLDARK;


Color.CONTROLDARKDARK

Represents the darkest part of a 3D element.

Syntax

public static final Color CONTROLDARKDARK;


Color.CONTROLLIGHT

Represents the highlight part of a 3D element.

Syntax

public static final Color CONTROLLIGHT;


Color.CONTROLLIGHTLIGHT

Represents the lightest part of a 3D element.

Syntax

public static final Color CONTROLLIGHTLIGHT;


Color.CONTROLTEXT

Represents the color of control text.

Syntax

public static final Color CONTROLTEXT;


Color.CYAN

Represents the color cyan.

Syntax

public static final Color CYAN;


Color.DARKGRAY

Represents the color dark gray.

Syntax

public static final Color DARKGRAY;


Color.DESKTOP

Represents the current desktop color.

Syntax

public static final Color DESKTOP;


Color.GRAY

Represents the color gray.

Syntax

public static final Color GRAY;


Color.GRAYTEXT

Represents the color of gray disabled text.

Syntax

public static final Color GRAYTEXT;


Color.GREEN

Represents the color green.

Syntax

public static final Color GREEN;


Color.HIGHLIGHT

Represents the color of highlighted objects.

Syntax

public static final Color HIGHLIGHT;


Color.HIGHLIGHTTEXT

Represents the color of highlighted text.

Syntax

public static final Color HIGHLIGHTTEXT;


Color.HOTTRACK

Represents the hottrack color.

Syntax

public static final Color HOTTRACK;


Color.INACTIVEBORDER

Represents the color of an inactive window's border.

Syntax

public static final Color INACTIVEBORDER;


Color.INACTIVECAPTION

Represents the color of the background of an inactive title bar caption.

Syntax

public static final Color INACTIVECAPTION;


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

Represents the background color of an information ToolTip.

Syntax

public static final Color INFO;


Color.INFOTEXT

Represents the color of information ToolTip text.

Syntax

public static final Color INFOTEXT;


Color.LIGHTGRAY

Represents the color light gray.

Syntax

public static final Color LIGHTGRAY;


Color.MAGENTA

Represents the color magenta.

Syntax

public static final Color MAGENTA;


Color.MENU

The color for menus.

Syntax

public static final Color MENU;


Color.MENUTEXT

The color for menu text.

Syntax

public static final Color MENUTEXT;


Color.ORANGE

Represents the color orange.

Syntax

public static final Color ORANGE;


Color.PURPLE

Represents the color purple.

Syntax

public static final Color PURPLE;


Color.RED

Represents the color red.

Syntax

public static final Color RED;


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

Represents the color white.

Syntax

public static final Color WHITE;


Color.WINDOW

Represents the color of a window.

Syntax

public static final Color WINDOW;


Color.WINDOWFRAME

Represents the color of a window frame.

Syntax

public static final Color WINDOWFRAME;


Color.WINDOWTEXT

Represents the color of window text.

Syntax

public static final Color WINDOWTEXT;


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

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

Creates a ColorDialog control.

Syntax

public ColorDialog()


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

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

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

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

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

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

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

Resets all dialog box options, the last selected color, and the custom colors to their default values.

Syntax

public final void reset()


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

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

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

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

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

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

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.

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

Constructors | Description
ColumnClickEvent | Creates a ColumnClickEvent object.


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

Fields | Description
column | Specifies the zero-based index of the column header that was clicked.


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

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

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

Creates a ColumnHeader object.

Syntax

public ColumnHeader()


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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

Specifies that the column headers do not work like buttons.

Syntax

public static final int NONCLICKABLE;


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

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 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

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

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

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

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

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

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

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

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

Resumes painting the ListBox control after painting is suspended by the beginUpdate method.

Syntax

public final void endUpdate()


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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves the currently selected item in 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

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

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

Creates a CommonDialog control.

Syntax

public CommonDialog()


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

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

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

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

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

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

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

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

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

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

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

Specifies that the item is vertically aligned to the bottom.

Syntax

public static final int BOTTOM;


ContentAlignment.BOTTOMCENTER

Specifies that the item is vertically aligned to the bottom and horizontally centered.

Syntax

public static final int BOTTOMCENTER;


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

Specifies that the item is vertically aligned to the bottom and horizontally aligned to the right.

Syntax

public static final int BOTTOMRIGHT;


ContentAlignment.CENTER

Specifies that the item is horizontally centered.

Syntax

public static final int CENTER;


ContentAlignment.LEFT

Specifies that the item is horizontally aligned to the left.

Syntax

public static final int LEFT;


ContentAlignment.MIDDLE

Specifies that the item is vertically centered.

Syntax

public static final int MIDDLE;


ContentAlignment.MIDDLECENTER

Specifies that the item is vertically and horizontally centered.

Syntax

public static final int MIDDLECENTER;


ContentAlignment.MIDDLELEFT

Specifies that the item is vertically centered and horizontally aligned to the left.

Syntax

public static final int MIDDLELEFT;


ContentAlignment.MIDDLERIGHT

Specifies that the item is vertically centered and horizontally aligned to the right.

Syntax

public static final int MIDDLERIGHT;


ContentAlignment.RIGHT

Specifies that the item is horizontally aligned to the right.

Syntax

public static final int RIGHT;


ContentAlignment.TOP

Specifies that the item is vertically aligned to the top.

Syntax

public static final int TOP;


ContentAlignment.TOPCENTER

Specifies that the item is vertically aligned to the top and horizontally centered.

Syntax

public static final int TOPCENTER;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Brings this control to the front of the z-order.

Syntax

public final void bringToFront()


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

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

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

Creates a Control object.

Syntax

public Control()

Remarks

This constructor is typically called from a constructor of a derived class.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 control. The Point.x field holds the control width; the Point.y field holds the height.

See Also setSize


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

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

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

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

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

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

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

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

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

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

Hides the control by setting the visible property to false.

Syntax

public final void hide()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Triggers the keyPress event.

Syntax

protected void onKeyPress( KeyPressEvent e )

Parameters

e

An KeyPressEvent object that provides the event data.

Remarks

When overriding this method, call super.onKeyPress.

See Also addOnKeyPress


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Resets the background color of the control to the parent's background color.

Syntax

public void resetBackColor()

See Also getBackColor


Control.resetFont

Resets the font for the control to the parent's font.

Syntax

public void resetFont()

See Also getFont


Control.resetForeColor

Resets the foreground color of the control to the parent's foreground color.

Syntax

public void resetForeColor()

See Also getForeColor


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

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

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

Activates this control.

Syntax

public final void select()


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

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

Sends this control to the back of the z-order.

Syntax

public final void sendToBack()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 control. The Point.x field holds the control width; the Point.y field holds the height.

See Also getSize


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

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

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

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

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

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

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

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

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

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

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

Displays the control by setting the visible property to true.

Syntax

public final void show()


Control.suspendLayout

Suspends the layout logic for the control.

Syntax

public final void suspendLayout()


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

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

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

Updates this control's position within its parent's z-order.

Syntax

protected final void updateZOrder()


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

Specifies that the default brush for the control is the brush defined in Brush.CONTROL.

Syntax

protected static final Brush defaultBrush;


Control.PROP_BACKCOLOR

Specifies that the value of the backColor property has changed.

Syntax

protected static final int PROP_BACKCOLOR;


Control.PROP_CURSOR

Specifies that the value of the cursor property has changed.

Syntax

protected static final int PROP_CURSOR;


Control.PROP_ENABLED

Specifies that the value of the enabled property has changed.

Syntax

protected static final int PROP_ENABLED;


Control.PROP_FONT

Specifies that the value of the font property has changed.

Syntax

protected static final int PROP_FONT;


Control.PROP_FORECOLOR

Specifies that the value of the foreColor property has changed.

Syntax

protected static final int PROP_FORECOLOR;


Control.PROP_LOCATION

Specifies that the value of the location property has changed.

Syntax

protected static final int PROP_LOCATION;


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

Specifies that the value of the parent's font property has changed.

Syntax

protected static final int PROP_PARENTFONT;


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

Specifies that the value of the size property has changed.

Syntax

protected static final int PROP_SIZE;


Control.PROP_TABSTOP

Specifies that the value of the tabStop property has changed.

Syntax

protected static final int PROP_TABSTOP;


Control.PROP_TEXT

Specifies that the value of the text property has changed.

Syntax

protected static final int PROP_TEXT;


Control.PROP_VISIBLE

Specifies that the value of the visible property has changed.

Syntax

protected static final int PROP_VISIBLE;


Control.STYLE_ACCEPTSCHILDREN

Specifies that the control accepts children.

Syntax

protected static final int STYLE_ACCEPTSCHILDREN;


Control.STYLE_FIXED_HEIGHT

Specifies that the control has a fixed height.

Syntax

protected static final int STYLE_FIXED_HEIGHT;


Control.STYLE_FIXED_WIDTH

Specifies that the control has a fixed width.

Syntax

protected static final int STYLE_FIXED_WIDTH;


Control.STYLE_FORM

Specifies that the control is a container for other controls.

Syntax

protected static final int STYLE_FORM;


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

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

Specifies that the control redraws when it is resized.

Syntax

protected static final int STYLE_RESIZE_REDRAW;


Control.STYLE_STDCLICK

Specifies that the control receives standard click events.

Syntax

protected static final int STYLE_STDCLICK;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the control is anchored to all edges of its container.

Syntax

public static final int ALL;


ControlAnchor.BOTTOM

Specifies that the control is anchored to the bottom edge of its container.

Syntax

public static final int BOTTOM;


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

Specifies that the control is anchored to the left, bottom, and right edges of its container.

Syntax

public static final int BOTTOMLEFTRIGHT;


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

Specifies that the control is anchored to the left edge of its container.

Syntax

public static final int LEFT;


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

Specifies that the control not anchored to any of the edges of its container.

Syntax

public static final int NONE;


ControlAnchor.RIGHT

Specifies that the control is anchored to the right edge of its container.

Syntax

public static final int RIGHT;


ControlAnchor.TOP

Specifies that the control is anchored to the top edge of its container.

Syntax

public static final int TOP;


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

Specifies that the control is anchored to the top, left, and bottom edges of its container.

Syntax

public static final int TOPBOTTOMLEFT;


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

Specifies that the control is anchored to the top and left edges of its container.

Syntax

public static final int TOPLEFT;


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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

Specifies that the control is not docked.

Syntax

public static final int NONE;


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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


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

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

Specifies that logical units are converted to arbitrary units with arbitrarily scaled axes.

Syntax

public static final int ANISOTROPIC;


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

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

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

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

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

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

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

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

Specifies the initial caption for the control.

Syntax

public String caption;


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

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

Contains extended window style bits.

Syntax

public int exStyle;

Remarks

This value must be a combination of WS_EX_XXX style flags.


CreateParams.height

Specifies the proposed initial height.

Syntax

public int height;


CreateParams.param

Specifies additional information to provide to the underlying handle.

Syntax

public Object param;


CreateParams.parent

Specifies the handle to the parent of the control.

Syntax

public int parent;


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

Specifies the proposed initial width.

Syntax

public int width;


CreateParams.x

Specifies the x-coordinate of the initial proposed location.

Syntax

public int x;


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

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

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

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

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

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

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

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

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

Frees the resources allocated by the Cursor object.

Syntax

protected void finalize()


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

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

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

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

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

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

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

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

Sets the current system cursor as the cursor for this object.

Syntax

public final void setCurrent()


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

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

Retrieves a string representation of this Cursor object.

Syntax

public String toString()

Return Value

Returns a String object that describes this object.


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

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

Specifies an arrow cursor.

Syntax

public static final Cursor ARROW;


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

Specifies the default cursor, which is usually an arrow cursor.

Syntax

public static final Cursor DEFAULT;


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

Specifies the cursor that appears when the mouse is positioned over a horizontal splitter bar.

Syntax

public static final Cursor HSPLIT;


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

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

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

Specifies a two-headed northeast/southwest sizing cursor.

Syntax

public static final Cursor SIZENESW;


Cursor.SIZENS

Specifies a two-headed north/south sizing cursor.

Syntax

public static final Cursor SIZENS;


Cursor.SIZENWSE

Specifies a two-headed northwest/southeast sizing cursor.

Syntax

public static final Cursor SIZENWSE;


Cursor.SIZEWE

Specifies a two-headed west/east sizing cursor.

Syntax

public static final Cursor SIZEWE;


Cursor.UPARROW

Specifies an up arrow, typically used to identify an insertion point.

Syntax

public static final Cursor UPARROW;


Cursor.VSPLIT

Specifies a vertical splitter bar cursor.

Syntax

public static final Cursor VSPLIT;


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

Constructors | Description
DateRangeEvent | Creates a DateRangeEvent object.


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

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

Specifies the last date in the date range the user has selected.

Syntax

public final Time end;


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

Constructors | Description
DateTimeFormatEvent | Creates a DateTimeFormatEvent object.


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

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

Specifies the date and time string to display to the user.

Syntax

public String display;


DateTimeFormatEvent.format

Specifies the custom format string the DateTimePicker control is using.

Syntax

public final String format;


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

Constructors | Description
DateTimeFormatQueryEvent | Creates a DateTimeFormatQueryEvent object.


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

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

Specifies the custom format string the DateTimePicker control is using.

Syntax

public final String format;


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

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

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

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

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

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

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

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

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

Creates a DateTimePicker control.

Syntax

public DateTimePicker()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Resets the date and time display format of the calendar to DateTimePickerFormat.LONG.

Syntax

public void resetFormat()

See Also setFormat


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

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

Resets the value of the date and time picker control to the current time.

Syntax

public void resetValue()

See Also getValue


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

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

Constructors | Description
DateTimeUserStringEvent | Creates a DateTimeUserStringEvent object.


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

Fields | Description
time | Specifies the time that the DateTimePicker control should be set to.
userString | Specifies the string the user entered.


DateTimeUserStringEvent.time

Specifies the time that the DateTimePicker control should be set to.

Syntax

public long time;


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

Constructors | Description
DateTimeWmKeyDownEvent | Creates a DateTimeWmKeyDownEvent object.


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

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

Specifies the custom format string the DateTimePicker control is using.

Syntax

public final String format;


DateTimeWmKeyDownEvent.time

Specifies the time that the DateTimePicker control should be set to.

Syntax

public long time;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Represents a default day of the week specified by the application.

Syntax

public static final int DEFAULT;


Days.FRIDAY

Represents Friday.

Syntax

public static final int FRIDAY;


Days.MONDAY

Represents Monday.

Syntax

public static final int MONDAY;


Days.SATURDAY

Represents Saturday.

Syntax

public static final int SATURDAY;


Days.SUNDAY

Represents Sunday.

Syntax

public static final int SUNDAY;


Days.THURSDAY

Represents Thursday.

Syntax

public static final int THURSDAY;


Days.TUESDAY

Represents Tuesday.

Syntax

public static final int TUESDAY;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves a human-readable string representation of this object.

Syntax

public String toString()

Return Value

Returns a string representation of this object.


Dimensions Fields

Fields | Description
columns | Specifies the number of columns.
rows | Specifies the number of rows.


Dimensions.columns

Specifies the number of columns.

Syntax

public int columns;


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

Constructors | Description
DocumentReadyEvent | Creates a DocumentReadyEvent object.


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the operation should be canceled and no drop message should be sent.

Syntax

public static final int CANCEL;


DragAction.CONTINUE

Specifies that the operation should continue.

Syntax

public static final int CONTINUE;


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 effects of a drag-and-drop operation.

Enum
  |
  +--DragDropEffect

package com.ms.wfc.ui

public class DragDropEffect
extends Enum


DragDropEffect Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

Specifies that the drop target cannot accept the data.

Syntax

public static final int NONE;


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 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

Constructors | Description
DragEvent | Creates a DragEvent object.


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

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

Specifies the IDataObject that contains the data associated with this event.

Syntax

public final IDataObject data;


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

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

Specifies the x-coordinate of the mouse pointer.

Syntax

public final int x;


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

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

Draws the background for the rectangle in which the item is drawn with default Windows control colors.

Syntax

public void drawBackground()


DrawItemEvent.drawFocusRect

Draws a focus rectangle around the item if the item is selected.

Syntax

public void drawFocusRect()


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

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

Specifies the Graphics object used to draw the item.

Syntax

public final Graphics graphics;


DrawItemEvent.index

Specifies the zero-based index of the item.

Syntax

public final int index;


DrawItemEvent.rect

Specifies the Rectangle object that represents the rectangle in which the item will be drawn.

Syntax

public final Rectangle rect;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the drawing takes place in the edit control of an owner-drawn combo box.

Syntax

public static final int COMBOBOXEDIT;


DrawItemState.FOCUS

Specifies that the item being drawn has the focus.

Syntax

public static final int FOCUS;


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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid DrawMode constant.


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

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

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

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

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

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

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

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

Clears the edit control.

Syntax

public final void clear()


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

Copies the current selection in the edit control to the Clipboard.

Syntax

public final void copy()


Edit.cut

Removes the current selection from the edit control and moves it to the Clipboard.

Syntax

public final void cut()


Edit.Edit

Creates an Edit control.

Syntax

public Edit()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Replaces the current selection in the edit control with the contents of the Clipboard.

Syntax

public final void paste()


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

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

Selects all the text in the edit control.

Syntax

public final void selectAll()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
EraseBackgroundEvent | Creates an EraseBackgroundEvent object.


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

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

Specifies the Graphics object that represents the device context that displays the control.

Syntax

public final Graphics graphics;


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

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

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

Creates a FileDialog control.

Syntax

protected FileDialog()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Resets all dialog box options to their default values.

Syntax

public void reset()

Overrides

CommonDialog.reset.


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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


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

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

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

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

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

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

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

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 the handles associated with the Font object should be destroyed.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves a hash code value for this font.

Syntax

public int hashCode()

Return Value

Returns a hash code value for this font.


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

Retrieves a human-readable string representation of this object.

Syntax

public String toString()

Return Value

Returns a string representation of this object.


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

Represents a standard ANSI fixed-width font.

Syntax

public static final Font ANSI_FIXED;


Font.ANSI_VAR

Represents a standard ANSI variable-width font.

Syntax

public static final Font ANSI_VAR;


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

Represents the standard font for the current graphics device.

Syntax

public static final Font DEVICE_DEFAULT;


Font.OEM_FIXED

Represents the standard original equipment manufacturer (OEM) fixed font.

Syntax

public static final Font OEM_FIXED;


Font.SYSTEM

Represents the standard Windows variable-width system font.

Syntax

public static final Font SYSTEM;


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

Constructors | Description
FontDescriptor | Creates a FontDescriptor object for the specified font as it will be rendered to a specified Graphics object.


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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Indicates that the font is designed to be used both with screens and printers.

Syntax

public static final int BOTH;


FontDevice.PRINTER

Indicates that the font is designed primarily for printer use.

Syntax

public static final int PRINTER;


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

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

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

Creates a FontDialog control.

Syntax

protected FontDialog()


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

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

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

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

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

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

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

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

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

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 maximum point size a user can select; returns zero (0) if there is no size limit.

See Also setMaxSize


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 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

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

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

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

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

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

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

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

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

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

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

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

Resets all dialog box options to their default values.

Syntax

public final void reset()


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

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

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

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

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

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

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

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

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

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

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 maximum point size a user can select. Set to zero (0) if there is no size limit.

See Also getMaxSize


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 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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid FontFamily constant.


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

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

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

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

Represents the default font family (identical to DEFAULT).

Syntax

public static final int DONTCARE;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

Specifies the value of the character that will be used to define word breaks for text justification.

Syntax

public int breakChar;


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

Specifies the value of the character to be substituted for characters not found in the font.

Syntax

public char defaultChar;


FontMetrics.descent

Specifies the descent (units below the base line) of characters.

Syntax

public int descent;


FontMetrics.digitizedAspectX

Specifies the horizontal aspect of the device for which the font was designed.

Syntax

public int digitizedAspectX;


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

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

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

Specifies the value of the first character defined in the font.

Syntax

public char firstChar;


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

Represents the height (ascent + descent) of characters.

Syntax

public int height;


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

Specifies whether the font is italicized.

Syntax

public boolean italic;


FontMetrics.lastChar

Specifies the value of the last character defined in the font.

Syntax

public char lastChar;


FontMetrics.maxWidth

Specifies the width of the widest character in the font.

Syntax

public int maxWidth;


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

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

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

Specifies whether the font is a strikeout font.

Syntax

public boolean strikeOut;


FontMetrics.underline

Specifies whether the font is underlined.

Syntax

public boolean underline;


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

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid FontFamily value.


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

Fields | Description
DEFAULT | Represents a default pitch.
FIXED | Represents a fixed-pitch font.
VARIABLE | Represents a variable-pitch font.


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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid FontSize constant.


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

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

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

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

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

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

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

Represents the size of the font in inches.

Syntax

public static final int INCHES;

Remarks

This unit remains constant across coordinate systems.


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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


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

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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


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

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

Represents a bold font.

Syntax

public static final int BOLD;


FontWeight.EXTRABOLD

Represents an extra bold font.

Syntax

public static final int EXTRABOLD;


FontWeight.EXTRALIGHT

Represents an extra light font.

Syntax

public static final int EXTRALIGHT;


FontWeight.HEAVY

Represents a heavy font.

Syntax

public static final int HEAVY;


FontWeight.LIGHT

Represents a light font.

Syntax

public static final int LIGHT;


FontWeight.MEDIUM

Represents a medium font weight.

Syntax

public static final int MEDIUM;


FontWeight.NORMAL

Represents a normal font weight.

Syntax

public static final int NORMAL;


FontWeight.SEMIBOLD

Represents a weight between medium and bold.

Syntax

public static final int SEMIBOLD;


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

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 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

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

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

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

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

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

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

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

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

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

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

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

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

Closes the form.

Syntax

public final void close()


Form.createHandle

Creates the handle for the form.

Syntax

protected void createHandle()

Remarks

When overriding createHandle, be sure to call super.createHandle.


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

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

Creates a Form object.

Syntax

public Form()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Removes the delegate that is assigned to the activate event.

Syntax

public final void removeOnActivate( EventHandler value )

Parameters

value

The EoventHandler delegate to be removed.

See Also addOnActivate, onActivate


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

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

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

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

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

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

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

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

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

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

Sets 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Specifies whether this form is visible.

Syntax

public void setVisible( boolean value )

Parameters

value

Set top true to make the form visible; otherwise, set to false.

Remarks

By default, Form objects are visible.


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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid FormBorderStyle constant.


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

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

Represents a thick, fixed dialog-style border.

Syntax

public static final int FIXED_DIALOG;


FormBorderStyle.FIXED_TOOLWINDOW

Represents a nonresizable tool window border.

Syntax

public static final int FIXED_TOOLWINDOW;


FormBorderStyle.SIZABLE

Represents a fully resizable border.

Syntax

public static final int SIZABLE;


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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid FormPaletteMode constant.


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

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

Indicates that a halftone palette should be used as the form's palette.

Syntax

public static final int HALFTONE;


FormPaletteMode.NONE

Indicates that no palette should be used.

Syntax

public static final int NONE;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

Specifies that the location and size of the form will determine the starting position.

Syntax

public static final int MANUAL;


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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid FormWindowState constant.


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

Fields | Description
MAXIMIZED | Represents a maximized window.
MINIMIZED | Represents a minimized window.
NORMAL | Represents a normally sized window.


FormWindowState.MAXIMIZED

Represents a maximized window.

Syntax

public static final int MAXIMIZED;


FormWindowState.MINIMIZED

Represents a minimized window.

Syntax

public static final int MINIMIZED;


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

Constructors | Description
GiveFeedbackEvent | Creates a GiveFeedbackEvent object.


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

Fields | Description
effect | Specifies the type of drag-and-drop operation.
useDefaultCursors | Specifies whether default cursors are used.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 point at which the first radial and the curve intersect to the point at which the second radial and curve intersect.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
GroupBox | Creates a GroupBox control.


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

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

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

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

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

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

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

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

Specifies that the index of the specified URL should be displayed.

Syntax

public static final int COMMAND_INDEX;

See Also showHelp


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

Constructors | Description
HelpEvent | Creates a HelpEvent object.


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

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

Specifies the control or menu item that the user wants Help on.

Syntax

public final IComponent component;


HelpEvent.contextId

Specifies the Help context identifier of the control.

Syntax

public final int contextId;


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

Specifies the identifier of the control or menu item.

Syntax

public final int controlId;


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

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

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

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

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

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

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

Creates a HelpProvider object.

Syntax

public HelpProvider()


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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies the calendar's background.

Syntax

public static final int CALENDAR_BACKGROUND;


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

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

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

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

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

Specifies the button at the top left corner of the control.

Syntax

public static final int PREV_MONTH_BUTTON;


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

Specifies the background of a month's title.

Syntax

public static final int TITLE_BACKGROUND;


HitArea.TITLE_MONTH

Specifies a month's title bar, over a month name.

Syntax

public static final int TITLE_MONTH;


HitArea.TITLE_YEAR

Specifies a month's title bar, over the year value.

Syntax

public static final int TITLE_YEAR;


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

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

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

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

Specifies a Point object that represents the point that was hit-tested.

Syntax

public Point point;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the object or text is aligned in the center of the control element.

Syntax

public static final int CENTER;


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

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

Constructors | Description
HScrollBar | Creates an HScrollBar control.


HScrollBar.HScrollBar

Creates an HScrollBar control.

Syntax

public HScrollBar()


HTMLControl Class

Encapsulates the HTML control.

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:

The following example sets the URL and posts arguments to that URL:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Frees the resources allocated by the Icon object.

Syntax

protected void finalize()


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

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

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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid IconArrange constant.


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

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

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

Specifies that icons are arranged along the left of the parent control or window.

Syntax

public static final int LEFT;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 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

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 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

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

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

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

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

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

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

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

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

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

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

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

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

Removes all images and masks from the image list.

Syntax

public void removeAll()


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

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

Adds images to 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

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

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

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

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

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

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

Creates an ImageListStreamer object.

Syntax

public ImageListStreamer( IDataStream stream )

Parameters

stream

An IDataStream object to save the image list to.


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

Constructors | Description
InputLangChangeEvent | Creates an InputLangChangeEvent object.


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

Fields | Description
charSet | Specifies the character set associated with the new language.
locale | Specifies the locale of the new language.


InputLangChangeEvent.charSet

Specifies the character set associated with the new language.

Syntax

public final byte charSet;


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 in WFC.


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

Constructors | Description
InputLangChangeRequestEvent | Creates an InputLangChangeRequestEvent object.


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

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

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

Specifies the locale of the requested input language.

Syntax

public final Locale locale;


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.


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 in WFC.


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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

Specifies that the bounding rectangle of the icon or small icon should be retrieved.

Syntax

public static final int ICON;


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

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

Constructors | Description
ItemCheckEvent | Creates a ItemCheckEvent object.


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 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

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 check box for the item to be checked, unchecked, or indeterminate.


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

Specifies the zero-based index of the item to change.

Syntax

public final int index;


ItemCheckEvent.newValue

Specifies whether to set 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

Constructors | Description
ItemDragEvent | Creates an ItemDragEvent object.


ItemDragEvent.ItemDragEvent

Creates an ItemDragEvent object.

Syntax

public ItemDragEvent( int button )

Parameters

button

An integer that indicates which mouse button was pressed.


ItemDragEvent Fields

Fields | Description
button | Specifies which mouse button was pressed.


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

Methods | Description
getHandle | Retrieves the handle to the window represented by the implementor.


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

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 bitmask 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 bitmask 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

Specifies the A key.

Syntax

public static final int A;


Key.ADD

Specifies the Add key.

Syntax

public static final int ADD;


Key.ALT

Specifies the ALT modifier key.

Syntax

public static final int ALT;


Key.APPS

Specifies the Application key (Microsoft Natural Keyboard).

Syntax

public static final int APPS;


Key.ATTN

Specifies the ATTN key.

Syntax

public static final int ATTN;


Key.B

Specifies the B key.

Syntax

public static final int B;


Key.BACK

Specifies the BACKSPACE key.

Syntax

public static final int BACK;


Key.C

Specifies the C key.

Syntax

public static final int C;


Key.CANCEL

Specifies the CANCEL key.

Syntax

public static final int CANCEL;


Key.CAPITAL

Specifies the CAPS LOCK key.

Syntax

public static final int CAPITAL;


Key.CLEAR

Specifies the CLEAR key.

Syntax

public static final int CLEAR;


Key.CONTROL

Specifies the CTRL modifier key.

Syntax

public static final int CONTROL;


Key.CONTROL_KEY

Specifies the CTRL key.

Syntax

public static final int CONTROL_KEY;


Key.CRSEL

Specifies the CRSEL key.

Syntax

public static final int CRSEL;


Key.D

Specifies the D key.

Syntax

public static final int D;


Key.D0

Specifies the 0 key.

Syntax

public static final int D0;


Key.D1

Specifies the 1 key.

Syntax

public static final int D1;


Key.D2

Specifies the 2 key.

Syntax

public static final int D2;


Key.D3

Specifies the 3 key.

Syntax

public static final int D3;


Key.D4

Specifies the 4 key.

Syntax

public static final int D4;


Key.D5

Specifies the 5 key.

Syntax

public static final int D5;


Key.D6

Specifies the 6 key.

Syntax

public static final int D6;


Key.D7

Specifies the 7 key.

Syntax

public static final int D7;


Key.D8

Specifies the 8 key.

Syntax

public static final int D8;


Key.D9

Specifies the 9 key.

Syntax

public static final int D9;


Key.DECIMAL

Specifies the Decimal key.

Syntax

public static final int DECIMAL;


Key.DELETE

Specifies the DEL key.

Syntax

public static final int DELETE;


Key.DIVIDE

Specifies the Divide key.

Syntax

public static final int DIVIDE;


Key.DOWN

Specifies the DOWN ARROW key.

Syntax

public static final int DOWN;


Key.E

Specifies the E key.

Syntax

public static final int E;


Key.END

Specifies the END key.

Syntax

public static final int END;


Key.EREOF

Specifies the ERASE EOF key.

Syntax

public static final int EREOF;


Key.ESCAPE

Specifies the ESC key.

Syntax

public static final int ESCAPE;


Key.EXECUTE

Specifies the EXECUTE key.

Syntax

public static final int EXECUTE;


Key.EXSEL

Specifies the EXSEL key.

Syntax

public static final int EXSEL;


Key.F

Specifies the F key.

Syntax

public static final int F;


Key.F1

Specifies the F1 key.

Syntax

public static final int F1;


Key.F10

Specifies the F10 key.

Syntax

public static final int F10;


Key.F11

Specifies the F11 key.

Syntax

public static final int F11;


Key.F12

Specifies the F12 key.

Syntax

public static final int F12;


Key.F13

Specifies the F13 key.

Syntax

public static final int F13;


Key.F14

Specifies the F14 key.

Syntax

public static final int F14;


Key.F15

Specifies the F15 key.

Syntax

public static final int F15;


Key.F16

Specifies the F16 key.

Syntax

public static final int F16;


Key.F17

Specifies the F17 key.

Syntax

public static final int F17;


Key.F18

Specifies the F18 key.

Syntax

public static final int F18;


Key.F19

Specifies the F19 key.

Syntax

public static final int F19;


Key.F2

Specifies the F2 key.

Syntax

public static final int F2;


Key.F20

Specifies the F20 key.

Syntax

public static final int F20;


Key.F21

Specifies the F21 key.

Syntax

public static final int F21;


Key.F22

Specifies the F22 key.

Syntax

public static final int F22;


Key.F23

Specifies the F23 key.

Syntax

public static final int F23;


Key.F24

Specifies the F24 key.

Syntax

public static final int F24;


Key.F3

Specifies the F3 key.

Syntax

public static final int F3;


Key.F4

Specifies the F4 key.

Syntax

public static final int F4;


Key.F5

Specifies the F5 key.

Syntax

public static final int F5;


Key.F6

Specifies the F6 key.

Syntax

public static final int F6;


Key.F7

Specifies the F7 key.

Syntax

public static final int F7;


Key.F8

Specifies the F8 key.

Syntax

public static final int F8;


Key.F9

Specifies the F9 key.

Syntax

public static final int F9;


Key.G

Specifies the G key.

Syntax

public static final int G;


Key.H

Specifies the H key.

Syntax

public static final int H;


Key.HELP

Specifies the HELP key.

Syntax

public static final int HELP;


Key.HOME

Specifies the HOME key.

Syntax

public static final int HOME;


Key.I

Specifies the I key.

Syntax

public static final int I;


Key.INSERT

Specifies the INS key.

Syntax

public static final int INSERT;


Key.J

Specifies the J key.

Syntax

public static final int J;


Key.K

Specifies the K key.

Syntax

public static final int K;


Key.KEYCODE

Specifies the bitmask to extract the key code for the key that was pressed from a key value.

Syntax

public static final int KEYCODE;


Key.L

Specifies the L key.

Syntax

public static final int L;


Key.LBUTTON

Specifies the left mouse button.

Syntax

public static final int LBUTTON;


Key.LCONTROL_KEY

Specifies the left CTRL key.

Syntax

public static final int LCONTROL_KEY;


Key.LEFT

Specifies the LEFT ARROW key.

Syntax

public static final int LEFT;


Key.LMENU

Specifies the left ALT key.

Syntax

public static final int LMENU;


Key.LSHIFT_KEY

Specifies the left SHIFT key.

Syntax

public static final int LSHIFT_KEY;


Key.LWIN

Specifies the left Windows logo key (Microsoft Natural Keyboard).

Syntax

public static final int LWIN;


Key.M

Specifies the M key.

Syntax

public static final int M;


Key.MBUTTON

Specifies the middle mouse button (three-button mouse).

Syntax

public static final int MBUTTON;


Key.MENU

Specifies the ALT key.

Syntax

public static final int MENU;


Key.MODIFIERS

Specifies the bitmask to extract information about which modifier keys were pressed from a key value.

Syntax

public static final int MODIFIERS;


Key.MULTIPLY

Specifies the Multiply key.

Syntax

public static final int MULTIPLY;


Key.N

Specifies the N key.

Syntax

public static final int N;


Key.NEXT

Specifies the PAGE DOWN key.

Syntax

public static final int NEXT;


Key.NONAME

Specifies a constant reserved for future use.

Syntax

public static final int NONAME;


Key.NUMLOCK

Specifies the NUM LOCK key.

Syntax

public static final int NUMLOCK;


Key.NUMPAD0

Specifies the numeric keypad 0 key.

Syntax

public static final int NUMPAD0;


Key.NUMPAD1

Specifies the numeric keypad 1 key.

Syntax

public static final int NUMPAD1;


Key.NUMPAD2

Specifies the numeric keypad 2 key.

Syntax

public static final int NUMPAD2;


Key.NUMPAD3

Specifies the numeric keypad 3 key.

Syntax

public static final int NUMPAD3;


Key.NUMPAD4

Specifies the numeric keypad 4 key.

Syntax

public static final int NUMPAD4;


Key.NUMPAD5

Specifies the numeric keypad 5 key.

Syntax

public static final int NUMPAD5;


Key.NUMPAD6

Specifies the numeric keypad 6 key.

Syntax

public static final int NUMPAD6;


Key.NUMPAD7

Specifies the numeric keypad 7 key.

Syntax

public static final int NUMPAD7;


Key.NUMPAD8

Specifies the numeric keypad 8 key.

Syntax

public static final int NUMPAD8;


Key.NUMPAD9

Specifies the numeric keypad 9 key.

Syntax

public static final int NUMPAD9;


Key.O

Specifies the O key.

Syntax

public static final int O;


Key.OEM_CLEAR

Specifies the CLEAR key.

Syntax

public static final int OEM_CLEAR;


Key.P

Specifies the P key.

Syntax

public static final int P;


Key.PA1

Specifies the PA1 key.

Syntax

public static final int PA1;


Key.PAUSE

Specifies the PAUSE key.

Syntax

public static final int PAUSE;


Key.PLAY

Specifies the PLAY key.

Syntax

public static final int PLAY;


Key.PRINT

Specifies the PRINT key.

Syntax

public static final int PRINT;


Key.PRIOR

Specifies the PAGE UP key.

Syntax

public static final int PRIOR;


Key.PROCESSKEY

Specifies the PROCESS KEY key.

Syntax

public static final int PROCESSKEY;


Key.Q

Specifies the Q key.

Syntax

public static final int Q;


Key.R

Specifies the R key.

Syntax

public static final int R;


Key.RBUTTON

Specifies the right mouse button.

Syntax

public static final int RBUTTON;


Key.RCONTROL_KEY

Specifies the right CTRL key.

Syntax

public static final int RCONTROL_KEY;


Key.RETURN

Specifies the RETURN key.

Syntax

public static final int RETURN;


Key.RIGHT

Specifies the RIGHT ARROW key.

Syntax

public static final int RIGHT;


Key.RMENU

Specifies the right ALT key.

Syntax

public static final int RMENU;


Key.RSHIFT_KEY

Specifies the right SHIFT key.

Syntax

public static final int RSHIFT_KEY;


Key.RWIN

Specifies the right Windows logo key (Microsoft Natural Keyboard).

Syntax

public static final int RWIN;


Key.S

Specifies the S key.

Syntax

public static final int S;


Key.SCROLL

Specifies the SCROLL LOCK key.

Syntax

public static final int SCROLL;


Key.SELECT

Specifies the SELECT key.

Syntax

public static final int SELECT;


Key.SEPARATOR

Specifies the Separator key.

Syntax

public static final int SEPARATOR;


Key.SHIFT

Specifies the SHIFT modifier key.

Syntax

public static final int SHIFT;


Key.SHIFT_KEY

Specifies the SHIFT key.

Syntax

public static final int SHIFT_KEY;


Key.SNAPSHOT

Specifies the PRINT SCREEN key.

Syntax

public static final int SNAPSHOT;


Key.SPACE

Specifies the SPACEBAR key.

Syntax

public static final int SPACE;


Key.SUBTRACT

Specifies the Subtract key.

Syntax

public static final int SUBTRACT;


Key.T

Specifies the T key.

Syntax

public static final int T;


Key.TAB

Specifies the TAB key.

Syntax

public static final int TAB;


Key.U

Specifies the U key.

Syntax

public static final int U;


Key.UP

Specifies the UP ARROW key.

Syntax

public static final int UP;


Key.V

Specifies the V key.

Syntax

public static final int V;


Key.W

Specifies the W key.

Syntax

public static final int W;


Key.X

Specifies the X key.

Syntax

public static final int X;


Key.Y

Specifies the Y key.

Syntax

public static final int Y;


Key.Z

Specifies the Z key.

Syntax

public static final int Z;


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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
KeyPressEvent | Creates KeyPressEvent object.

Methods | Description
getKeyChar | Retrieves the character the user composed.


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

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

Fields | Description
handled | Specifies whether the event is handled.
keyChar | Specifies the character the user composed.


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

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

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

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

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

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

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

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

Creates a Label control.

Syntax

public Label()


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

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

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

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

Constructors | Description
LabelEditEvent | Creates a LabelEditEvent object.

Methods | Description
cancelEdit | Cancels the edit operation on the text of the list view item.


LabelEditEvent.cancelEdit

Cancels the edit operation on the text of the list view item.

Syntax

public void cancelEdit()


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

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

Specifies the zero-based index of the list view item containing the text to edit.

Syntax

public final int item;


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

Constructors | Description
LayoutEvent | Creates a LayoutEvent object.


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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the object or text is aligned to the left of the reference point.

Syntax

public static final int LEFT;


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

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

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

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

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

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

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

Resumes painting the ListBox control after painting is suspended by the beginUpdate method.

Syntax

public final void endUpdate()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Fields | Description
NOMATCHES | Specifies that no matches are found during a search.


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

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

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

Ensures that the list item is visible, scrolling the list view control if necessary.

Syntax

public void ensureVisible()


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

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

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

Retrieves an array of ConstructorArg objects that describe the data types and values needed to persist this object.

Syntax

public ConstructorArg[] getConstructorArgs()


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

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

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

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

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

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

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

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

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

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

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

Removes this item from the list view control.

Syntax

public void remove()


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

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

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

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

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

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

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

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

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

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

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 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

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

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

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

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

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

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

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

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

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

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

Removes all items and columns from the list view control.

Syntax

public void clear()


ListView.endUpdate

Resumes painting the ListView control after painting is suspended by the beginUpdate method.

Syntax

public final void endUpdate()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a ListView control.

Syntax

public ListView()


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

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

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

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

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

Removes all columns from the list view control.

Syntax

public void removeAllColumns()


ListView.removeAllItems

Removes all items from the list view control.

Syntax

public void removeAllItems()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that items are aligned to the left of the list view control.

Syntax

public static final int LEFT;


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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


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

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

Specifies that all minimized MDI child icons should be arranged within the parent window.

Syntax

public static final int ARRANGE_ICONS;


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

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

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

Constructors | Description
MeasureItemEvent | Creates a MeasureItemEvent object.


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

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

Specifies the zero-based index of the item whose height must be determined.

Syntax

public final int index;


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

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 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

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

Removes all existing items from this menu.

Syntax

public void clear()

See Also add


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

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

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

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

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

Retrieves 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

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

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

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

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

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

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

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

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 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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Indicates that a submenu arrow should be drawn.

Syntax

public static final int ARROW;


MenuGlyph.BULLET

Indicates that a menu bullet should be drawn.

Syntax

public static final int BULLET;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Selects this menu item.

Syntax

public void performSelect()

Remarks

A call to this method triggers the select event.

See Also onSelect


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the menu item should be added alongside an existing item in the merged menu.

Syntax

public static final int ADD;


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

Specifies that the menu item should not be included in the merged menu.

Syntax

public static final int REMOVE;


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

Methods | Description
show | Displays a message box with the specified text, caption, and style.


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

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

Indicates that the message box should display Abort, Retry, and Ignore buttons.

Syntax

public static final int ABORTRETRYIGNORE;


MessageBox.DEFBUTTON1

Indicates that the first button on the message box should be the default button.

Syntax

public static final int DEFBUTTON1;


MessageBox.DEFBUTTON2

Indicates that the second button on the message box should be the default button.

Syntax

public static final int DEFBUTTON2;


MessageBox.DEFBUTTON3

Indicates that the third button on the message box should be the default button.

Syntax

public static final int DEFBUTTON3;


MessageBox.ICONASTERISK

Indicates that the message box should display an asterisk icon.

Syntax

public static final int ICONASTERISK;


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

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

Indicates that a hand icon should be displayed on the message box.

Syntax

public static final int ICONHAND;


MessageBox.ICONINFORMATION

Indicates that the message box should display a question mark.

Syntax

public static final int ICONINFORMATION;


MessageBox.ICONQUESTION

Indicates that the message box should display a question mark.

Syntax

public static final int ICONQUESTION;


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

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

Indicates that the message box should display an OK button.

Syntax

public static final int OK;


MessageBox.OKCANCEL

Indicates that the message box should display OK and Cancel buttons.

Syntax

public static final int OKCANCEL;


MessageBox.RETRYCANCEL

Indicates that the message box should display Retry and Cancel buttons.

Syntax

public static final int RETRYCANCEL;


MessageBox.YESNO

Indicates that the message box should display Yes and No buttons.

Syntax

public static final int YESNO;


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.

IPersistable
  |
  +--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

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

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

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

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

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

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

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

Frees the resources allocated by the Metafile object.

Syntax

protected void finalize()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a MonthCalendar control.

Syntax

public MonthCalendar()


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

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

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

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

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

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

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

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

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

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

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

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

Resets the selected range of the control to the current date.

Syntax

public void resetSelectionRange()

See Also getSelectionRange


MonthCalendar.resetTodayDate

Resets the "today" date to the current date.

Syntax

public void resetTodayDate()

See Also getTodayDate


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the left mouse button was pressed.

Syntax

public static final int LEFT;


MouseButton.MIDDLE

Specifies that the middle mouse button was pressed.

Syntax

public static final int MIDDLE;


MouseButton.NONE

Specifies that no mouse button was pressed.

Syntax

public static final int NONE;


MouseButton.RIGHT

Specifies that the right mouse button was pressed.

Syntax

public static final int RIGHT;


MouseEvent Class

Provides data for 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

Constructors | Description
MouseEvent | Creates a MouseEvent object.


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

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

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

Specifies how many times the mouse button was pressed.

Syntax

public final int clicks;


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

Specifies the x-coordinate of the mouse click (in client coordinates).

Syntax

public final int x;


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

Constructors | Description
NodeLabelEditEvent | Creates a NodeLabelEditEvent object.

Methods | Description
cancelEdit | Cancels the edit operation on the text of the tree node.


NodeLabelEditEvent.cancelEdit

Cancels the edit operation on the text of the tree node.

Syntax

public void cancelEdit()


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

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

Specifies the new text to associate with the tree node.

Syntax

public final String label;


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(&quot;java&quot;);   //sets the default extension
   ofd.setFilter(&quot;Java files (*.java)|*.java|All files
    (*.*)|*.*&quot;); //sets the file filter
//Sets the filter that will be initially selected.
   ofd.setFilterIndex(1);
//Sets the initial directory.
   ofd.setInitialDir(&quot;c:\\program files&quot;);
   int dlgResult = ofd.showDialog();
   if (dlgResult == DialogResult.OK) {
//Gets the names of the files the user chose
      String[] fnames = ofd.getFileNames();
   }


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

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

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

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

Resets all dialog box options to their default values.

Syntax

public final void reset()


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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid Orientation constant.


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

Fields | Description
HORIZONTAL | Indicates that the control is oriented horizontally.
VERTICAL | Indicates that the control is oriented vertically.


Orientation.HORIZONTAL

Indicates that the control is oriented horizontally.

Syntax

public static final int HORIZONTAL;


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

Constructors | Description
PaintEvent | Creates a PaintEvent object.


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

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

Specifies the Rectangle object that represents the rectangle in which to paint.

Syntax

public final Rectangle clipRect;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a Panel control.

Syntax

public Panel()


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

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

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

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

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

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

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

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

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

Retrieves the Win32 handle for this pen.

Syntax

public int getHandle()

Return Value

Returns a Win32 pen handle (HPEN).


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

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

Computes the hash code for this object.

Syntax

public int hashCode()

Return Value

Returns an integer hash code value.


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

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

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

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

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

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

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

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

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

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

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

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.


PenStyle Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid PenStyle constant.


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

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

Represents a pen style that consists of a series of dashed lines.

Syntax

public static final int DASH;


PenStyle.DASHDOT

Represents a pen style that consists of a dash, followed by a dot.

Syntax

public static final int DASHDOT;


PenStyle.DASHDOTDOT

Represents a pen style that consists of a dash, followed by two dots.

Syntax

public static final int DASHDOTDOT;


PenStyle.DOT

Represents a pen style that consists of a dotted line.

Syntax

public static final int DOT;


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

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

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

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

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

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

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

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

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

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

Associates an image with the PictureBox control.

Syntax

public final void setImage( Image v alue )

Parameters

value

An Image object that specifies the image to display in this control.

See Also getImage


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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


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

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

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

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

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

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

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

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

Retrieves the ConstructorArgs needed to persist this object.

Syntax

public ConstructorArg[] getConstructorArgs()

Return Value

Returns an array of ConstructorArg objects.


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

Retrieves an integer hash code for this object.

Syntax

public int hashCode()

Return Value

Returns an integer hash code for this object.


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

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

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

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

Retrieves a string representation of this object.

Syntax

public String toString()

Return Value

Returns a String that contains this object's settings.


Point Fields

Fields | Description
x | Specifies the horizontal position of the coordinate.
y | Specifies the vertical position of the coordinate.


Point.x

Specifies the horizontal position of the coordinate.

Syntax

public int x;


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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of the PolyFillMode class.


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

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

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;


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

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

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

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

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

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

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

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.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

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

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

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

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

onstructors | Description
QueryContinueDragEvent | Creates a QueryContinueDragEvent object.


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

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

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

Set to true if the user has pressed the ESC key.

Syntax

public final boolean escapePressed;


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

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

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

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

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

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

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

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

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

Generates a click event for the button, simulating a click by a user.

Syntax

public final void performClick()


RadioButton.RadioButton

Creates a RadioButton control.

Syntax

public RadioButton()


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

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

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

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 radio button off. The default value is false.

See Also getChecked


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

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

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

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

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

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

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

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

Represents a raster operation in which the resulting pixels will be black.

Syntax

public static final RasterOp BLACK;


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

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

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

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

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

Constructors | Description
ReadyStateEvent | Creates a new ReadyStateEvent object.


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

Fields | Description
state | Specifies the state of the object triggering the event.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a Rebar control.

Syntax

public Rebar()


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

Removes all bands from the rebar control.

Syntax

public void removeAllBands()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

© 1999 Microsoft Corporation. All rights reserved. Terms of use.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a RebarBand object.

Syntax

public RebarBand()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves the ConstructorArgs needed to persist this object.

Syntax

public ConstructorArg[] getConstructorArgs()

Return Value

Returns a ConstructorArg array.


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

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

Retrieves a hash code value for this object.

Syntax

public int hashCode()

Return Value

Returns a hash code value for this object.


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

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

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

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

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

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

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

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

Retrieves a String representation of this object.

Syntax

public String toString()

Return Value

Returns a String representation of this Rectangle object.


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

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

Specifies the height of the rectangle.

Syntax

public int height;


Rectangle.width

Specifies the width of the rectangle.

Syntax

public int width;


Rectangle.x

Specifies the x-position (or horizontal origin) of the rectangle.

Syntax

public int x;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves a hash code for this object.

Syntax

public int hashCode()

Return Value

Returns the object's hash code.


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

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 the elements contained either in the specified region or this one.

See Also andWith, xorWith


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

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

Constructors | Description
RequestResizeEvent | Creates a RequestResizeEvent object.


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

Fields | Description
newRectangle | Specifies the requested size of the RichEdit control.


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

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

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

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

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

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

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

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

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


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.


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.


RichEdit.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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 the characters in the selection have the bulleted style; otherwise, returns false.

See Also setSelBullet


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

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

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

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

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

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

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

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

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

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 the characters in the selection are struck through.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a RichEdit control.

Syntax

public RichEdit()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


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

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

Indicates that the search is case-sensitive.

Syntax

public static final int MATCHCASE;


RichEditFind.NOHIGHLIGHT

Indicates that the text, if found, should not be highlighted.

Syntax

public static final int NOHIGHLIGHT;


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

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

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

Creates a RichEditIMEColor object.

Syntax

public RichEditIMEColor()


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

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

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

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

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

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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


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

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

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

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

Specifies that the (IME) should be disabled when the control receives the input focus.

Syntax

static public final int FORCEDISABLE;


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

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

Specifies that input method editor (IME) handling should be disabled.

Syntax

static public final int FORCENONE;


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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


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

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

Indicates that the vertical and horizontal scroll bars should always be displayed.

Syntax

public static final int FORCED_BOTH;


RichEditScrollBars.FORCED_HORIZONTAL

Indicates that the horizontal scroll bar should always be displayed.

Syntax

public static final int FORCED_HORIZONTAL;


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

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


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

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

Indicates that no text is selected.

Syntax

public static final int EMPTY;


RichEditSelType.MULTICHAR

Indicates that multiple characters are selected.

Syntax

public static final int MULTICHAR;


RichEditSelType.MULTIOBJECT

Indicates that multiple objects are selected.

Syntax

public static final int MULTIOBJECT;


RichEditSelType.OBJECT

Indicates that a single object is selected.

Syntax

public static final int OBJECT;


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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


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

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

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

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

Indicates that the stream is a Rich Text Format (RTF) stream.

Syntax

public static final int RICHTEXT;


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

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


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

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

Indicates that the control should use a custom-defined punctuation table.

Syntax

public static final int CUSTOM;


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

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(&quot;java&quot;);   //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(&quot;c:\\program files&quot;);  //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

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

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

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

Resets all dialog box options to their default values.

Syntax

public void reset()

Overrides FileDialog.reset


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

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

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.


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

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

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

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

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

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

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

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

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

Computes and returns a hash code for this object.

Syntax

public int hashCode()

Return Value

Returns the object's hash code.


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

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

Specifies the name of the device.

Syntax

public final String deviceName;


Screen.primary

Specifies whether this Screen object represents the primary monitor.

Syntax

public final boolean primary;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that both horizontal and vertical scroll bars appear with the control.

Syntax

public static final int BOTH;


ScrollBars.HORIZONTAL

Specifies that only a horizontal scroll bar appears with the control.

Syntax

public static final int HORIZONTAL;


ScrollBars.NONE

Specifies that no scroll bars appear with the control.

Syntax

public static final int NONE;


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

Methods | Description
valid | Determines whether the specified value is valid for this class.


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

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

Specifies that a down arrow scroll bar button will be drawn.

Syntax

public static final int DOWN;


ScrollButton.LEFT

Specifies that a left arrow scroll bar button will be drawn.

Syntax

public static final int LEFT;


ScrollButton.RIGHT

Specifies that a right arrow scroll bar button will be drawn.

Syntax

public static final int RIGHT;


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

Constructors | Description
ScrollEvent | Creates a ScrollEvent object.


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

Fields | Description
newValue | Specifies the new value of the scroll bar.
type | Specifies the type of scroll event that occurred.


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

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

Methods | Description
valid | Determines whether the specified value is valid for this class.


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

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

Specifies that the control has finished scrolling.

Syntax

public static final int ENDSCROLL;


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

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

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

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

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

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

Specifies that the user has dragged and released the scroll thumb.

Syntax

public static final int THUMB_POSITION;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

Specifies that more than one item at a time can be selected.

Syntax

public static final int MULTI_SIMPLE;


SelectionMode.NONE

Specifies that no items can be selected.

Syntax

public static final int NONE;


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

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

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

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

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

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

Specifies a Time object that represents the end of the selection range.

Syntax

public Time end;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

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

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

Specifies the shortcut keys ALT+BACKSPACE.

Syntax

public static final int ALT_BKSP;


Shortcut.CTRL_A

Specifies the shortcut keys CTRL+A.

Syntax

public static final int CTRL_A;


Shortcut.CTRL_B

Specifies the shortcut keys CTRL+B.

Syntax

public static final int CTRL_B;


Shortcut.CTRL_C

Specifies the shortcut keys CTRL+C.

Syntax

public static final int CTRL_C;


Shortcut.CTRL_D

Specifies the shortcut keys CTRL+D.

Syntax

public static final int CTRL_D;


Shortcut.CTRL_DEL

Specifies the shortcut keys CTRL+DELETE.

Syntax

public static final int CTRL_DEL;


Shortcut.CTRL_E

Specifies the shortcut keys CTRL+E.

Syntax

public static final int CTRL_E;


Shortcut.CTRL_F

Specifies the shortcut keys CTRL+F.

Syntax

public static final int CTRL_F;


Shortcut.CTRL_F1

Specifies the shortcut keys CTRL+F1.

Syntax

public static final int CTRL_F1;


Shortcut.CTRL_F11

Specifies the shortcut keys CTRL+F11.

Syntax

public static final int CTRL_F11;


Shortcut.CTRL_F12

Specifies the shortcut keys CTRL+F12.

Syntax

public static final int CTRL_F12;


Shortcut.CTRL_F2

Specifies the shortcut keys CTRL+F2.

Syntax

public static final int CTRL_F2;


Shortcut.CTRL_F3

Specifies the shortcut keys CTRL+F3.

Syntax

public static final int CTRL_F3;


Shortcut.CTRL_F4

Specifies the shortcut keys CTRL+F4.

Syntax

public static final int CTRL_F4;


Shortcut.CTRL_F5

Specifies the shortcut keys CTRL+F5.

Syntax

public static final int CTRL_F5;


Shortcut.CTRL_F6

Specifies the shortcut keys CTRL+F6.

Syntax

public static final int CTRL_F6;


Shortcut.CTRL_F7

Specifies the shortcut keys CTRL+F7.

Syntax

public static final int CTRL_F7;


Shortcut.CTRL_F8

Specifies the shortcut keys CTRL+F8.

Syntax

public static final int CTRL_F8;


Shortcut.CTRL_F9

Specifies the shortcut keys CTRL+F9.

Syntax

public static final int CTRL_F9;


Shortcut.CTRL_G

Specifies the shortcut keys CTRL+G.

Syntax

public static final int CTRL_G;


Shortcut.CTRL_H

Specifies the shortcut keys CTRL+H.

Syntax

public static final int CTRL_H;


Shortcut.CTRL_I

Specifies the shortcut keys CTRL+I.

Syntax

public static final int CTRL_I;


Shortcut.CTRL_INS

Specifies the shortcut keys CTRL+INS.

Syntax

public static final int CTRL_INS;


Shortcut.CTRL_J

Specifies the shortcut keys CTRL+J.

Syntax

public static final int CTRL_J;


Shortcut.CTRL_K

Specifies the shortcut keys CTRL+K.

Syntax

public static final int CTRL_K;


Shortcut.CTRL_L

Specifies the shortcut keys CTRL+L.

Syntax

public static final int CTRL_L;


Shortcut.CTRL_M

Specifies the shortcut keys CTRL+M.

Syntax

public static final int CTRL_M;


Shortcut.CTRL_N

Specifies the shortcut keys CTRL+N.

Syntax

public static final int CTRL_N;


Shortcut.CTRL_O

Specifies the shortcut keys CTRL+O.

Syntax

public static final int CTRL_O;


Shortcut.CTRL_P

Specifies the shortcut keys CTRL+P.

Syntax

public static final int CTRL_P;


Shortcut.CTRL_Q

Specifies the shortcut keys CTRL+Q.

Syntax

public static final int CTRL_Q;


Shortcut.CTRL_R

Specifies the shortcut keys CTRL+R.

Syntax

public static final int CTRL_R;


Shortcut.CTRL_S

Specifies the shortcut keys CTRL+S.

Syntax

public static final int CTRL_S;


Shortcut.CTRL_SHIFT_A

Specifies the shortcut keys CTRL+SHIFT+A.

Syntax

public static final int CTRL_SHIFT_A;


Shortcut.CTRL_SHIFT_B

Specifies the shortcut keys CTRL+SHIFT+B.

Syntax

public static final int CTRL_SHIFT_B;


Shortcut.CTRL_SHIFT_C

Specifies the shortcut keys CTRL+SHIFT+C.

Syntax

public static final int CTRL_SHIFT_C;


Shortcut.CTRL_SHIFT_D

Specifies the shortcut keys CTRL+SHIFT+D.

Syntax

public static final int CTRL_SHIFT_D;


Shortcut.CTRL_SHIFT_E

Specifies the shortcut keys CTRL+SHIFT+E.

Syntax

public static final int CTRL_SHIFT_E;


Shortcut.CTRL_SHIFT_F

Specifies the shortcut keys CTRL+SHIFT+F.

Syntax

public static final int CTRL_SHIFT_F;


Shortcut.CTRL_SHIFT_F1

Specifies the shortcut keys CTRL+SHIFT+F1.

Syntax

public static final int CTRL_SHIFT_F1;


Shortcut.CTRL_SHIFT_F11

Specifies the shortcut keys CTRL+SHIFT+F11.

Syntax

public static final int CTRL_SHIFT_F11;


Shortcut.CTRL_SHIFT_F12

Specifies the shortcut keys CTRL+SHIFT+F12.

Syntax

public static final int CTRL_SHIFT_F12;


Shortcut.CTRL_SHIFT_F2

Specifies the shortcut keys CTRL+SHIFT+F2.

Syntax

public static final int CTRL_SHIFT_F2;


Shortcut.CTRL_SHIFT_F3

Specifies the shortcut keys CTRL+SHIFT+F3.

Syntax

public static final int CTRL_SHIFT_F3;


Shortcut.CTRL_SHIFT_F4

Specifies the shortcut keys CTRL+SHIFT+F4.

Syntax

public static final int CTRL_SHIFT_F4;


Shortcut.CTRL_SHIFT_F5

Specifies the shortcut keys CTRL+SHIFT+F5.

Syntax

public static final int CTRL_SHIFT_F5;


Shortcut.CTRL_SHIFT_F6

Specifies the shortcut keys CTRL+SHIFT+F6.

Syntax

public static final int CTRL_SHIFT_F6;


Shortcut.CTRL_SHIFT_F7

Specifies the shortcut keys CTRL+SHIFT+F7.

Syntax

public static final int CTRL_SHIFT_F7;


Shortcut.CTRL_SHIFT_F8

Specifies the shortcut keys CTRL+SHIFT+F8.

Syntax

public static final int CTRL_SHIFT_F8;


Shortcut.CTRL_SHIFT_F9

Specifies the shortcut keys CTRL+SHIFT+F9.

Syntax

public static final int CTRL_SHIFT_F9;


Shortcut.CTRL_SHIFT_G

Specifies the shortcut keys CTRL+SHIFT+G.

Syntax

public static final int CTRL_SHIFT_G;


Shortcut.CTRL_SHIFT_H

Specifies the shortcut keys CTRL+SHIFT+H.

Syntax

public static final int CTRL_SHIFT_H;


Shortcut.CTRL_SHIFT_I

Specifies the shortcut keys CTRL+SHIFT+I.

Syntax

public static final int CTRL_SHIFT_I;


Shortcut.CTRL_SHIFT_J

Specifies the shortcut keys CTRL+SHIFT+J.

Syntax

public static final int CTRL_SHIFT_J;


Shortcut.CTRL_SHIFT_K

Specifies the shortcut keys CTRL+SHIFT+K.

Syntax

public static final int CTRL_SHIFT_K;


Shortcut.CTRL_SHIFT_L

Specifies the shortcut keys CTRL+SHIFT+L.

Syntax

public static final int CTRL_SHIFT_L;


Shortcut.CTRL_SHIFT_M

Specifies the shortcut keys CTRL+SHIFT+M.

Syntax

public static final int CTRL_SHIFT_M;


Shortcut.CTRL_SHIFT_N

Specifies the shortcut keys CTRL+SHIFT+N.

Syntax

public static final int CTRL_SHIFT_N;


Shortcut.CTRL_SHIFT_O

Specifies the shortcut keys CTRL+SHIFT+O.

Syntax

public static final int CTRL_SHIFT_O;


Shortcut.CTRL_SHIFT_P

Specifies the shortcut keys CTRL+SHIFT+P.

Syntax

public static final int CTRL_SHIFT_P;


Shortcut.CTRL_SHIFT_Q

Specifies the shortcut keys CTRL+SHIFT+Q.

Syntax

public static final int CTRL_SHIFT_Q;


Shortcut.CTRL_SHIFT_R

Specifies the shortcut keys CTRL+SHIFT+R.

Syntax

public static final int CTRL_SHIFT_R;


Shortcut.CTRL_SHIFT_S

Specifies the shortcut keys CTRL+SHIFT+S.

Syntax

public static final int CTRL_SHIFT_S;


Shortcut.CTRL_SHIFT_T

Specifies the shortcut keys CTRL+SHIFT+T.

Syntax

public static final int CTRL_SHIFT_T;


Shortcut.CTRL_SHIFT_U

Specifies the shortcut keys CTRL+SHIFT+U.

Syntax

public static final int CTRL_SHIFT_U;


Shortcut.CTRL_SHIFT_V

Specifies the shortcut keys CTRL+SHIFT+V.

Syntax

public static final int CTRL_SHIFT_V;


Shortcut.CTRL_SHIFT_W

Specifies the shortcut keys CTRL+SHIFT+W.

Syntax

public static final int CTRL_SHIFT_W;


Shortcut.CTRL_SHIFT_X

Specifies the shortcut keys CTRL+SHIFT+X.

Syntax

public static final int CTRL_SHIFT_X;


Shortcut.CTRL_SHIFT_Y

Specifies the shortcut keys CTRL+SHIFT+Y.

Syntax

public static final int CTRL_SHIFT_Y;


Shortcut.CTRL_SHIFT_Z

Specifies the shortcut keys CTRL+SHIFT+Z.

Syntax

public static final int CTRL_SHIFT_Z;


Shortcut.CTRL_T

Specifies the shortcut keys CTRL+T.

Syntax

public static final int CTRL_T;


Shortcut.CTRL_U

Specifies the shortcut keys CTRL+U.

Syntax

public static final int CTRL_U;


Shortcut.CTRL_V

Specifies the shortcut keys CTRL+V.

Syntax

public static final int CTRL_V;


Shortcut.CTRL_W

Specifies the shortcut keys CTRL+W.

Syntax

public static final int CTRL_W;


Shortcut.CTRL_X

Specifies the shortcut keys CTRL+X.

Syntax

public static final int CTRL_X;


Shortcut.CTRL_Y

Specifies the shortcut keys CTRL+Y.

Syntax

public static final int CTRL_Y;


Shortcut.CTRL_Z

Specifies the shortcut keys CTRL+Z.

Syntax

public static final int CTRL_Z;


Shortcut.DEL

Specifies the shortcut key DELETE.

Syntax

public static final int DEL;


Shortcut.F1

Specifies the shortcut key F1.

Syntax

public static final int F1;


Shortcut.F11

Specifies the shortcut key F11.

Syntax

public static final int F11;


Shortcut.F12

Specifies the shortcut key F12.

Syntax

public static final int F12;


Shortcut.F2

Specifies the shortcut key F2.

Syntax

public static final int F2;


Shortcut.F3

Specifies the shortcut key F3.

Syntax

public static final int F3;


Shortcut.F4

Specifies the shortcut key F4.

Syntax

public static final int F4;


Shortcut.F5

Specifies the shortcut key F5.

Syntax

public static final int F5;


Shortcut.F6

Specifies the shortcut key F6.

Syntax

public static final int F6;


Shortcut.F7

Specifies the shortcut key F7.

Syntax

public static final int F7;


Shortcut.F8

Specifies the shortcut key F8.

Syntax

public static final int F8;


Shortcut.F9

Specifies the shortcut key F9.

Syntax

public static final int F9;


Shortcut.INS

Specifies the shortcut key INS.

Syntax

public static final int INS;


Shortcut.NONE

Specifies that there is no shortcut key associated with the menu item.

Syntax

public static final int NONE;


Shortcut.SHIFT_DEL

Specifies the shortcut keys SHIFT+DELETE.

Syntax

public static final int SHIFT_DEL;


Shortcut.SHIFT_F1

Specifies the shortcut keys SHIFT+F1.

Syntax

public static final int SHIFT_F1;


Shortcut.SHIFT_F11

Specifies the shortcut keys SHIFT+F11.

Syntax

public static final int SHIFT_F11;


Shortcut.SHIFT_F12

Specifies the shortcut keys SHIFT+F12.

Syntax

public static final int SHIFT_F12;


Shortcut.SHIFT_F2

Specifies the shortcut keys SHIFT+F2.

Syntax

public static final int SHIFT_F2;


Shortcut.SHIFT_F3

Specifies the shortcut keys SHIFT+F3.

Syntax

public static final int SHIFT_F3;


Shortcut.SHIFT_F4

Specifies the shortcut keys SHIFT+F4.

Syntax

public static final int SHIFT_F4;


Shortcut.SHIFT_F5

Specifies the shortcut keys SHIFT+F5.

Syntax

public static final int SHIFT_F5;


Shortcut.SHIFT_F6

Specifies the shortcut keys SHIFT+F6.

Syntax

public static final int SHIFT_F6;


Shortcut.SHIFT_F7

Specifies the shortcut keys SHIFT+F7.

Syntax

public static final int SHIFT_F7;


Shortcut.SHIFT_F8

Specifies the shortcut keys SHIFT+F8.

Syntax

public static final int SHIFT_F8;


Shortcut.SHIFT_F9

Specifies the shortcut keys SHIFT+F9.

Syntax

public static final int SHIFT_F9;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the items are sorted in ascending order.

Syntax

public static final int ASCENDING;


SortOrder.DESCENDING

Specifies that the items are sorted in descending order.

Syntax

public static final int DESCENDING;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
SplitterEvent | Creates a SplitterEvent object.


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

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

Specifies the x-coordinate of the upper-left corner of the splitter (in client coordinates).

Syntax

public int splitX;


SplitterEvent.splitY

Specifies the y-coordinate of the upper-left corner of the splitter (in client coordinates).

Syntax

public int splitY;


SplitterEvent.x

Specifies the x-coordinate of the mouse pointer (in client coordinates).

Syntax

public final int x;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
StatusBarDrawItemEvent | Creates a StatusBarDrawItemEvent object.


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

Fields | Description
panel | Specifies the status bar panel to draw.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a StatusBarPanel object.

Syntax

public StatusBarPanel()


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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 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

Specifies that the width of the panel is determined by its contents.

Syntax

public static final int CONTENTS;


StatusBarPanelAutoSize.NONE

Specifies that the width of the panel cannot be changed.

Syntax

public static final int NONE;


StatusBarPanelAutoSize.SPRING

Specifies that the panel shares 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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the status bar panel has no border.

Syntax

public static final int NONE;


StatusBarPanelBorderStyle.RAISED

Specifies that the status bar panel has a three-dimensional raised border.

Syntax

public static final int RAISED;


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

Constructors | Description
StatusBarPanelClickEvent | Creates a StatusBarPanelClickEvent object.


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

Fields | Description
statusBarPanel | Specifies the StatusBarPanel object that represents the clicked panel.


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

Fields | Description
OWNERDRAW | Specifies that the panel is owner-drawn.
TEXT | Specifies that the panel is drawn by the system.


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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the tabs are located at the bottom of the control.

Syntax

public static final int BOTTOM;


TabAlignment.LEFT

Specifies that the tabs are located at the left edge of the control.

Syntax

public static final int LEFT;


TabAlignment.RIGHT

Specifies that the tabs are located at the right edge of the control.

Syntax

public static final int RIGHT;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

Specifies that the tabs have the appearance of flat buttons.

Syntax

public static final int FLAT_BUTTONS;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that the system draws the tabs in the control.

Syntax

public static final int NORMAL;


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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 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

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

Specifies that all tabs in a control are the same width.

Syntax

public static final int FIXED;


TabSizeMode.NORMAL

Specifies that the size of each tab is determined by 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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of the TextFormat class.


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

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

Specifies that the text should be formatted along the bottom of a rectangle.

Syntax

public static final int BOTTOM;


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

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

Specifies that the tabs in the text should be expanded.

Syntax

public static final int EXPANDTABS;


TextFormat.HORIZONTALCENTER

Specifies that the text should be centered horizontally.

Syntax

public static final int HORIZONTALCENTER;


TextFormat.LEFT

Specifies that the text should be aligned to the left.

Syntax

public static final int LEFT;


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

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

Specifies that the text should be aligned to the right.

Syntax

public static final int RIGHT;


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

Specifies that carriage returns and line feed characters do not cause line breaks.

Syntax

public static final int SINGLELINE;


TextFormat.TOP

Specifies that the text should be aligned along the top of the rectangle.

Syntax

public static final int TOP;


TextFormat.VERTICALCENTER

Specifies that the text should be aligned vertically.

Syntax

public static final int VERTICALCENTER;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that tick marks appear on both sides of the control.

Syntax

public static final int BOTH;


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

Specifies that no tick marks are visible in the control.

Syntax

public static final int NONE;


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

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 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Removes all the buttons from the ToolBar control.

Syntax

public final void removeAll()

See Also addButton , insertButton, 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a ToolBarButton object.

Syntax

public ToolBarButton()


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

Constructors | Description
ToolBarButtonClickEvent | Creates a ToolBarButtonClickEvent object.


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

Fields | Description
toolBarButton | Specifies the toolbar button that was clicked.


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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


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

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

Specifies that the button, when pressed, can display other menus or windows.

Syntax

public static final int DROPDOWN;


ToolBarButtonStyle.PUSHBUTTON

Specifies that the button behaves like a standard Windows pushbutton.

Syntax

public static final PUSHBUTTON;


ToolBarButtonStyle.SEPARATOR

Specifies that the button acts as a separator.

Syntax

public static final int SEPARATOR;


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

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


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

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

Specifies that the text appears to the right of the image.

Syntax

public static final int RIGHT;


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

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

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

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

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

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

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

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

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

Removes all the tooltips currently associated with the ToolTip control.

Syntax

public void removeAll()

See Also setToolTip


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Collapses the node.

Syntax

public void collapse()

See Also expand


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

Ensures that the node is visible, expanding the parent node or scrolling the tree view control, if necessary.

Syntax

public void ensureVisible()


TreeNode.expand

Expands the node.

Syntax

public void expand()

See Also collapse


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.setcheckBoxes property of the tree view control that contains this node is set to false, this method has no effect.

See Also getChecked


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

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

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

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

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

Expands the node if it is collapsed; collapses the node if it is expanded.

Syntax

public void toggle()


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

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

Constructors | Description
TreeNodesEditDialog | Creates a TreeNodesEditDialog object.

Methods | Description
getNodes | Retrieves the nodes in the tree view control.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Resumes painting the TreeView control after painting is suspended by the beginUpdate method.

Syntax

public void endUpdate()


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Remove all nodes from the tree view control.

Syntax

public void removeAll()


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

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

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

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

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

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

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

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

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

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

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

Resets the indentation to the system default.

Syntax

public void resetIndent()

See Also getIndent , setIndent


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 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

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

Constructors | Description
TreeViewCancelEvent | Creates a TreeViewCancelEvent object.


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

Fields | Description
cancel | Specifies whether to cancel the operation.


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

Constructors | Description
TreeViewEvent | Creates a TreeViewEvent object.


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

Fields | Description
node | Specifies the tree node that has been expanded, collapsed, or selected.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
UpDownAcceleration | Creates an UpDownAcceleration object.


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

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

Specifies the amount that the value of the up-down control changes.

Syntax

public int increment;


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

Specifies that the position of the up-down control is determined by the programmer.

Syntax

public static final int MANUAL;


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

Constructors | Description
UpDownChangedEvent | Creates an UpDownChangedEvent object.


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

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

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

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

Constructors | Description
UserControl | Creates a UserControl object.


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

Specifies that each item appears as a full-sized icon with a label below it.

Syntax

public static final int LARGEICON;


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

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

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

Constructors | Description
VScrollBar | Creates a VScrollBar control.


VScrollBar.VScrollBar

Creates a VScrollBar control.

Syntax

public VScrollBar()


Package com.ms.wfc.util

Microsoft Packages Overview

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

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

Creates an ArrayEnumerator object.

Syntax

public ArrayEnumerator( Object[] items )

Parameters

items

The Object array to enumerate.


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

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

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

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

Methods | Description
sort | Sorts an object array using the IComparer interface to compare elements.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Constructors | Description
EmptyEnumeratorException | Creates an EmptyEnumeratorException object.


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

Constructors | Description
EmptyQueueException | Creates an EmptyQueueException object.


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

Constructors | Description
EmptyStackException | Creates an EmptyStackException object.


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

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

Creates an identical copy of this HashTable object.

Syntax

public Object clone()

Return Value

Returns an identical copy of this HashTable object.


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

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

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

Determines whether the hash table contains any items.

Syntax

public boolean getEmpty()

Return Value

Returns true if the hash table contains no items; otherwise, returns false.


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

Retrieves an enumerator for the list of keys.

Syntax

public IEnumerator getKeyEnumerator()

Return Value

Returns an IEnumerator object.


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

Retrieves the current number of items stored.

Syntax

public int getSize()

Return Value

Returns the item count.


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

Retrieves an enumerator for the list of values.

Syntax

public IEnumerator getValueEnumerator()

Return Value

Returns an IEnumerator object.


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

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

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

Rehashes the entire hash table, placing all items in the correct place.

Syntax

public void rehash()


HashTable.removeAllValues

Removes all items from the hash table.

Syntax

public void removeAllValues()


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

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

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

Methods | Description
compare | Compares two objects.


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

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

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

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

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

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

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

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

Creates an identical copy of this list.

Syntax

public Object clone()

Return Value

Returns an identical copy of this list.


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

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

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

Adds an item to the end of the list.

Syntax

public void enqueueItem( Object item )

Parameters

item

The item to add.


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

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

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

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

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

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

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

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

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

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

Retrieves the current number of items stored in the list.

Syntax

public int getSize()

Return Value

Returns the item count.


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

Computes the hash code for this object.

Syntax

public int hashCode()

Return Value

Returns the hash code.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creates a string representation of this list.

Syntax

public String toString()

Return Value

Returns the string representation of this list.


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

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


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

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

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

Specifies that a leading digit should be used.

Syntax

public static final int LEADING_DIGIT;


NumberFormat.NEGATIVE_PARENS

Specifies that negative values should be placed inside parentheses.

Syntax

public static final int NEGATIVE_PARENS;


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

Specifies that a leading digit should not be used.

Syntax

public static final int NO_LEADING_DIGIT;


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

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

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

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

Frees a root that has been allocated.

Syntax

public synchronized static void free( int root )

Parameters

root

The root reference to free.


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

Methods | Description
compare | Compares two strings.
sort | Sorts the elements in an object array.


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.


com.ms.win32 Package Overview

Microsoft Packages Overview

The com.ms.win32 package provides direct, low-overhead access to commonly used Microsoft® Windows® APIs. These classes use the Microsoft® J/Direct™ feature.

You need not declare the entire Win32 API yourself. The com.ms.win32 package provides classes that contain these declarations. Simply import the correct class or classes.

The available APIs are declared in a set of classes, one for each Windows DLL, are shown in the following table.

Import | DLL name | Contains
Kernel32.class | KERNEL32.DLL | Base API
Gdi32.class | GDI32.DLL | Graphics
Ole32.class | OLE32.DLL | J/Direct methods
User32.class | USER32.DLL | User interface
Advapi32.class | ADVAPI32.DLL | Crypto API, event logging
Shell32.class | SHELL32.DLL | Interface to the Windows Explorer
Winmm.class | WINMM.DLL | Multimedia
Spoolss.class | SPOOLSS.DLL | Spooling

For instance, MessageBox is contained in USER32.DLL and therefore declared in User32.class; just import this class (or the whole package) and you can call MessageBox directly.

Windows constants are in the com.ms.win32.wina-winz classes. To access these, just import com.ms.win32.win and use win.<CONSTANT_NAME>, shown as follows. Don't try to take a shortcut by extending or implementing com.ms.win32.win in your class; doing so will require that the entire class be loaded each time you load your class. Instead, write out win.xxx.

System.out.println("MAX_PATH = " + win.MAX_PATH);

Finally, the supported Windows structures are declared in a set of class files that have the structure name as the class name, such as com.ms.win32.RECT.class. Just import these and you can use the Windows structures as though they were Java classes.

Again, you get all these classes when you import com.ms.win32. And note that the classes are an optional part of the Microsoft SDK for Java, so if you don't have them, just install again. The Java sources are in the \Src\Win32API subdirectory of the Microsoft SDK for Java.

Because the classes contain only declarations, your users won't need to have them installed on their computers, but you'll need them to compile.


com.ms.xml.dso Package Overview

Microsoft Packages Overview

The com.ms.xml.dso package provides a Data Source Object (DSO) applet class that can be used to provide data for data binding by using XML files.

This package contains the following:

Classes

Hierarchy


Classes (com.ms.xml.dso Package)

 Microsoft SDK for Java

com.ms.xml.dso Package Classes

The com.ms.xml.dso package contains the following classes:

The XMLDSO class can be used with an <APPLET> tag to load XML files and provide the data that is contained in them for data binding.


Hierarchy (com.ms.xml.dso Package)

 Microsoft SDK for Java

com.ms.xml.dso Package Hierarchy

The com.ms.xml.dso package has the following hierarchy:

java.lang.object
  |
  +--java.awt.Component
  |  |
  |  +--java.awt.Container
  |  |  |
  |  |  +--java.awt.Panel
  |  |  |  |
  |  |  |  +--java.applet.Applet
  |  |  |  |  |
  |  |  |  |  +--XMLDSO


XMLDSO Class (com.ms.xml.dso Package)

 Microsoft SDK for Java

XMLDSO Class

The XMLDSO class of the com.ms.xml.dso package can be used with an <APPLET> tag to load XML files and provide the data contained in them for data binding.

public class XMLDSO extends Applet
{
  // Constructors
  public XMLDSO();

  // Methods
  public void addDataSourceListener(DataSourceListener listener)
        throws java.util.TooManyListenersException;
  public void asyncLoad(String arg, String callback);
  public void clear();
  public Object getDocument();
  public String getError();
  public Object getSchema(int style);
  public Object getXML(int style);
  public void handleUpdate(Element root);
  public void handleUpdateString(String xml);
  public void init();
  public void load(String arg);
  public OLEDBSimpleProvider msDataSourceObject(String qualifier);
  public void notifyListeners();
  public void paint(Graphics g);
  public Document parseXML(String xml);
  public void removeDataSourceListener(DataSourceListener listener);
  public void save(String filename);
  public void saveSchema(String filename);
  public void setRoot(Element e);
  public void updateSchema();
}

See Also

Document, Element


Constructors (XMLDSO Class)

 Microsoft SDK for Java

XMLDSO Class Constructors

The XMLDSO Class contains the following constructor:

XMLDSO()

Constructs an XMLDSO object with an empty document.

Syntax

public XMLDSO();


Methods (XMLDSO Class)

 Microsoft SDK for Java

XMLDSO Class Methods

The XMLDSO Class contains the following methods:

addDataSourceListener adds a DataSourceListener object to the XMLDSO object.
asyncLoad loads a document asynchronously.
clear replaces the currently loaded document with a new, empty document.
getDocument retrieves the loaded document.
getError retrieves a string containing the last error encountered by the XMLDSO object.
getSchema returns the schema as a string.
getXML retrieves the XML data as a large string for the loaded document.
handleUpdate processes the given piece of XML data that is to be sent to the server.
handleUpdateString parses and processes the given piece of XML data that is to be sent to the server.
init searches for a PARAM with a URL and loads this URL, if found.
load reloads the document using the specified URL.
msDataSourceObject provides the OLE DB simple provider interface to callers.
notifyListeners notifies current DataSourceListener objects associated with the XMLDSO object that data has changed.
paint displays diagnostic information that helps the page author debug the page if the applet that contains the XMLDSO object is given bounds that are non-zero.
parseXML reads a string of XML data and processes it.
removeDataSourceListener removes a DataSourceListener object from the XMLDSO object.
save saves the XML document to a file.
saveSchema saves the schema to the given file.
setRoot sets the root of the document for this XMLDSO object.
updateSchema updates the SCHEMA whenever the document is changed.


addDataSourceListener (XMLDSO Class)

 Microsoft SDK for Java

addDataSourceListener

This method of the XMLDSO class adds a DataSourceListener object to the XMLDSO object.

Syntax

public void addDataSourceListener(DataSourceListener listener) throws java.util.TooManyListenersException;

Parameters

listener The listener to add to the DSO.

Exceptions

TooManyListenersException if too many listeners are associated with the Data Source Object (DSO).


asyncLoad (XMLDSO Class)

 Microsoft SDK for Java

asyncLoad

This method of the XMLDSO class loads a Web page asynchronously. Asynchronous loading means that some parts of the page load more quickly (and are displayed first) while the browser finishes loading and displaying other portions of the page.

Syntax

public void asyncLoad(String arg, String callback);

Parameters

arg | The document name.
callback | The callback string.


clear (XMLDSO Class)

 Microsoft SDK for Java

clear

This method of the XMLDSO class replaces the currently loaded document with a new, empty document.

Syntax

public void clear();


getDocument (XMLDSO Class)

 Microsoft SDK for Java

getDocument

This method of the XMLDSO class retrieves the loaded document.

Syntax

public Object getDocument();

Return Value

Returns the loaded document.


getError (XMLDSO Class)

 Microsoft SDK for Java

getError

This method of the XMLDSO Class retrieves a string containing last error encountered by the XMLDSO object.

Syntax

public String getError();

Return Value

Returns a string that describes the last error that was encountered.


getSchema (XMLDSO Class)

 Microsoft SDK for Java

getSchema

This method of the XMLDSO class retrieves the schema as a string.

Syntax

public Object getSchema(int style);

Parameters

style The formatting style. 0=default, 1=pretty, 2=compact.


getXML (XMLDSO Class)

 Microsoft SDK for Java

getXML

This method of the XMLDSO class retrieves the XML data as a large string for the loaded document.

Syntax

public Object getXML(int style);

Return Value

Returns a string object that contains the XML contents of the loaded document.

Parameters

style The formatting style. 0=default, 1=pretty, 2=compact.


handleUpdate (XMLDSO Class)

 Microsoft SDK for Java

handleUpdate

This method of the XMLDSO class processes the given piece of XML data that is to be sent to the server.

Syntax

public void handleUpdate(Element root);

Parameters

root The root node of the XML parse tree.


handleUpdateString (XMLDSO Class)

 Microsoft SDK for Java

handleUpdateString

This method of the XMLDSO class parses and processes the given piece of XML data that is to be sent to the server.

Syntax

public void handleUpdateString(String xml);

Parameters

xml The XML string to be parsed and processed.


init (XMLDSO Class)

 Microsoft SDK for Java

init

This method of the XMLDSO class searches for a PARAM with a URL and loads this URL, if found. Otherwise, it looks for inline XML data inside the <APPLET> tag that created the current XMLDSO object.

Syntax

public void init();

Remarks

If no URL or inline XML exists, the method performs no action.


load (XMLDSO Class)

 Microsoft SDK for Java

load

This method of the XMLDSO class reloads the document using the specified URL. Relative URLs are resolved using the HTML document as a base for the URL.

Syntax

public void load(String arg);

Parameters

arg A String that contains the URL used to reload the document.


msDataSourceObject (XMLDSO Class)

 Microsoft SDK for Java

msDataSourceObject

This method of the XMLDSO class provides the OLE DB simple provider interface to callers.

Syntax

public OLEDBSimpleProvider msDataSourceObject(String qualifier);

Return Value

Returns an OLEDBSimpleProvider object.

Parameters

qualifier This parameter is currently ignored, but is available to enable the applet to serve more than one data set.


notifyListeners (XMLDSO Class)

 Microsoft SDK for Java

notifyListeners

This method of the XMLDSO class notifies current DataSourceListener objects associated with the XMLDSO class that data has changed.

Syntax

public void notifyListener();


paint (XMLDSO Class)

 Microsoft SDK for Java

paint

This method of the XMLDSO class displays diagnostic information that helps the page author debug the page if the applet that contains the XMLDSO class is given bounds that are non-zero.

Syntax

public void paint(Graphics g);

Parameters

g The graphics context to use to paint the applet.


parseXML (XMLDSO Class)

 Microsoft SDK for Java

parseXML

This method of the XMLDSO class reads a string of XML data and processes it.

Syntax

public Document parseXML(String xml);

Return Value

Returns the processed string.

Parameters

xml The XML string.


removeDataSourceListener (XMLDSO Class)

 Microsoft SDK for Java

removeDataSourceListener

This method of the XMLDSO class removes a DataSourceListener object from the XMLDSO object.

Syntax

public void removeDataSourceListener(DataSourceListener listener);

Parameters

listener The listener to remove from the DSO.


save (XMLDSO Class)

 Microsoft SDK for Java

save

This method of the XMLDSO class saves the XML document to a file.

Syntax

public void save(String filename);

Parameters

filename The name of the file to save the XML document to.


saveSchema (XMLDSO Class)

 Microsoft SDK for Java

saveSchema

This method of the XMLDSO class saves the schema to the given file.

Syntax

public void saveSchema(String filename);

Parameters

filename The filename for the saved schema.


setRoot (XMLDSO Class)

 Microsoft SDK for Java

setRoot

This method of the XMLDSO class sets the root of the document for this XMLDSO object. This is useful when you want to link together multiple DSOs.

Syntax

public void setRoot(Element e);

Parameters

e The Element to set as the root of the document.


updateSchema (XMLDSO Class)

 Microsoft SDK for Java

updateSchema

This method of the XMLDSO class updates the SCHEMA whenever the document is changed. The method is called from the clear, load, and setRoot methods. You can also call this method if you have manually changed the document or the SCHEMA <PARAM>.

Syntax

public void updateSchema();

Remarks

The SCHEMA <PARAM> is used to define a subset of data that is visible through the DSO.


com.ms.xml.om Package Overview

Microsoft Packages Overview

The com.ms.xml.om package provides classes that implement the Microsoft® XML Object Model in Java. These classes provide a way of loading XML documents, manipulating the resulting XML tree, and then writing the modified XML back out, thereby enabling applications based on XML.

This package contains the following:

Classes

Interfaces

Hierarchy


Classes (com.ms.xml.om Package)

 Microsoft SDK for Java

com.ms.xml.om Package Classes

The com.ms.xml.om package contains the following classes:

Document class implements an XML document, which can be thought of as the root of a tree.

DocumentBeanInfo class provides specialized JavaBeans support for the Document class to resolve which overloaded functions are accessible through scripting.

ElementCollection class provides an element collection interface similar to that in the Internet Explorer 4.0 Dynamic HTML object model.

ElementDeclEnumeration class is a simple enumeration for iterating over element declarations.

ElementEnumeration class is a simple Enumeration for iterating over the immediate children of a given node in the XML tree.

ElementFactoryImpl class represents the default implementation for the element factory.

ElementImpl class represents the default implementation of the Element interface.

ElementImplBeanInfo class provides specialized JavaBeans support for the ElementImpl class to resolve which overloaded functions are accessible through scripting.


Interfaces (com.ms.xml.om Package)

 Microsoft SDK for Java

com.ms.xml.om Package Interfaces

The com.ms.xml.om package contains the following interfaces:

Element interface implements an Element object.

ElementFactory interface specifies a method to create elements for an XML element tree.


Hierarchy (com.ms.xml.om Package)

 Microsoft SDK for Java

com.ms.xml.om Package Hierarchy

The com.ms.xml.om package has the following hierarchy:

Object
  |
  +--ElementImpl (Element)
  |  |
  |  +--Document (ElementFactory)
  |
  +--ElementCollection
  |
  +--ElementDeclEnumeration (Enumeration)
  |
  +--ElementEnumeration (Enumeration)
  |
  +--ElementFactoryImpl (ElementFactory)

SimpleBeanInfo
  |
  +--DocumentBeanInfo
  |
  +--ElementImplBeanInfo

Element
ElementFactory


Document Class (com.ms.xml.om Package)

 Microsoft SDK for Java

Document Class

The Document class of the com.ms.xml.om package implements an XML document, which can be thought of as the root of a tree.

public class Document extends ElementImpl implements ElementFactory
{
  // Fields
  protected DTD dtd;
  protected ElementFactory factory;

  // Constructors
  public Document();
  public Document(ElementFactory f);

  // Methods
  public void addChild(Element elem, Element after);
  public void clear();
  public final Element createElement(Element parent,
    int type, Name tag, String text);
  public final Element createElement(int type, String tag);
  public final Element createElement(int type);
  public XMLOutputStream createOutputStream(OutputStream out)
    throws IOException;
  public final Enumeration elementDeclarations();
  public Element findEntity(Name name);
  public final String getCharset();
  public final String getDocType();
  public DTD getDTD();
  public final String getDTDURL();
  public Element getElementDecl(Name name);
  public final String getEncoding();
  public long getFileModifiedDate();
  public final String getId();
  public int getOutputStyle();
  public Element getParent();
  public final Element getRoot();
  public final String getStandalone();
  public String getText();
  public int getType();
  public final String getURL();
  public final String getVersion();
  public boolean isCaseInsensitive();
  public void load(String urlstr) throws ParseException;
  public void load(URL url) throws ParseException;
  public void load(InputStream in) throws ParseException;
  public boolean loadExternal();
  public void parsed(Element e);
  public void parsedAttribute(Element e, Name name, Object value);
  public void removeChild(Element elem);
  public void reportError(ParseException e, OutputStream out);
  public void save(XMLOutputStream o) throws IOException;
  public void setCaseInsensitive(boolean yes);
  public final void setCharset(String encoding);
  public final void setEncoding(String encoding);
  public void setLoadExternal(boolean yes);
  public void setOutputStyle(int style);
  public void setShortEndTags(boolean yes);
  public final void setStandalone( String value );
  public void setText(String text);
  public void setURL(String urlstr) throws ParseException;
  public final void setVersion(String version);
  public void setShortEndTags(boolean yes);
  public boolean shortEndTags();
}

Each XML tag can either represent a node or a leaf of this tree. The Document class allows you to load an XML document, manipulate it, and then save it back out again. The document can be loaded by specifying a URL or an input stream.

According to the XML specification, the root of the tree consists of any combination of comments and processing instructions, but only one root element. A helper method, getRoot, is provided as a shortcut to finding the root element.

See Also

com.ms.xml.om.Element

Hierarchy

ElementImpl
  |
  +--Document (Element)


Constructors (Document Class)

 Microsoft SDK for Java

Document Class Constructors

The Document class contains the following constructors:

Document()
Document(ElementFactory f)

Document()

Constructs a new, empty document using the default element factory.

Syntax

public Document();

Document(ElementFactory f)

Constructs a new, empty document using the given ElementFactory object when building the XML element hierarchy.

Syntax

public Document(ElementFactory f);

Parameters

f The ElementFactory to use.


Methods (Document Class)

 Microsoft SDK for Java

Document Class Methods

The Document class contains the following methods:

addChild adds a child Element to the document.
clear sets the Document back to its initial empty state retaining only the ElementFactory association.
createElement creates a new element for the given element type and tag name using the ElementFactory for this Document object.
createOutputStream creates an XML output stream matching the format found on load().
elementDeclarations retrieves an enumeration of the element declarations from the Document Type Definition (DTD).
findEntity retrieves the XML-DATA specification for the named entity.
getCharset retrieves the character set.
getDocType retrieves the document type.
getDTD retrieves the Document's Type Definition (DTD).
getDTDURL retrieves the document type's URL.
getElementDecl returns the XML-DATA specification for the named element.
getEncoding retrieves the character encoding information.
getFileModifiedDate retrieves the last modified date on the source of the URL.
getId retrieves the external identifier.
getOutputStyle retrieves the current output style.
getParent retrieves the parent element.
getRoot retrieves the root node of the XML parse tree.
getStandalone retrieves the standalone information.
getText retrieves the document text.
getType retrieves the document type.
getURL retrieves the URL.
getVersion retrieves the version information.
isCaseInsensitive determines whether the load XML is case insensitive.
load loads the document from the given URL string.
loadexternal determines whether to load external DTDs or entities.
parsed is called when the given element is completely parsed.
parsedAttribute is a delegate to the contained element factory.
removeChild removes the specified child element from the Document.
reportError returns information about the given parse exception that was generated during the load.
save saves the document to the given output stream.
setCaseInsensitive determines whether the next XML loaded will be treated as case sensitive.
setCharset sets the character set.
setEncoding sets the character encoding for output.
setLoadExternal determines whether to load external DTDs or entities.
setOutputStyle sets the style for writing to an output stream.
setShortEndTags determines whether to allow short end tags.
setStandalone sets the RequiredMarkupDeclaration (RMD) stored in the <?XML ...?> tag.
setText passes the text through to the root node, if there is a root node.
setURL is an alias for load and is here only for compatibility reasons.
setVersion sets the version number stored in the <?XML ...?> tag.
shortEndTags returns whether short end tags are allowed.


addChild (Document Class)

 Microsoft SDK for Java

addChild

This method of the Document class adds a child Element to the document. This is an override of the Element.addChild method that stores the new child and stores the last element of type Element.ELEMENT, so that getRoot can be used as a shortcut to find a particular element.

Syntax

public void addChild(Element elem, Element after);

Parameters

elem | The child element to add.
after | The element after which to add the elem element.

Overrides

addChild(Element,Element) in ElementImpl.


clear (Document Class)

 Microsoft SDK for Java

clear

This method of the Document class sets the Document back to its initial empty state retaining only the ElementFactory association.

Syntax

public void clear();


createElement (Document Class)

 Microsoft SDK for Java

createElement

The createElement method of the Document class contains the following signatures:

createElement(Element parent, int type, Name tag, String text)
createElement(int type, String tag)
createElement(int type)

createElement(Element parent, int type, Name tag, String text)

Creates a new element for the given element type and tag name using the ElementFactory for this Document. This method allows the Document class to be used as an ElementFactory itself.

Syntax

public final Element createElement(Element parent, int type, Name tag, String text);

Parameters

parent | The parent element.
type | The element type.
tag | The element tag name.
text | The element text.

createElement(int type, String tag)

Creates a new element for the given element type and tag name.

Syntax

public final Element createElement(int type, String tag);

Parameters

type | The element type.
tag | The element tag name.

createElement(int type)

Creates a new element for a given element type with a null tag name.

Syntax

public final Element createElement(int type);

Return Value

Returns the element created.

Parameters

type The element type.


createOutputStream (Document Class)

 Microsoft SDK for Java

createOutputStream

This method of the Document class creates an XML output stream matching the format found on load().

Syntax

public XMLOutputStream createOutputStream(OutputStream out) throws IOException;

Return Value

Returns the XML output stream.

Parameters

out The output stream.

Exceptions

IOException if the output stream cannot be created.


elementDeclarations (Document Class)

 Microsoft SDK for Java

elementDeclarations

This method of the Document class retrieves an enumeration of the element declarations from the DTD. These are returned as ElementDecl objects.

Syntax

public final Enumeration elementDeclarations();

Return Value

Returns the element declarations enumeration object.


findEntity (Document Class)

 Microsoft SDK for Java

findEntity

This method of the Document class retrieves the XML-DATA specification for the named entity. This is DTD information represented in an XML Object Model.

Syntax

public Element findEntity(Name name);

Return Value

Returns the XML-DATA specification for the named entity.

Parameters

name The entity name.


getCharset (Document Class)

 Microsoft SDK for Java

getCharset

This method of the Document class retrieves the character set. This is an alias for the setEncoding method and exists for compatibility reasons only.

Syntax

public final String getCharset();

Return Value

Returns the character set.


getDocType (Document Class)

 Microsoft SDK for Java

getDocType

This method of the Document class retrieves the document type.

Syntax

public final String getDocType();

Return Value

Returns the name specified in the <!DOCTYPE> tag.


getDTD (Document Class)

 Microsoft SDK for Java

getDTD

This method of the Document class retrieves the document's DTD.

Syntax

public DTD getDTD();

Return Value

Returns the DTD.


getDTDURL (Document Class)

 Microsoft SDK for Java

getDTDURL

This method of the Document class retrieves the document type URL.

Syntax

public final String getDTDURL();

Return Value

Returns the URL specified in the <!DOCTYPE> tag or null if an internal DTD was specified.


getElementDecl (Document class)

 Microsoft SDK for Java

getElementDecl

This method of the Document class retrieves the XML-DATA specification for the named element. This is DTD information represented in an XML Object Model.

Syntax

public Element getElementDecl(Name name);

Return Value

Returns the XML-DATA specification for the named element.

Parameters

name The element name.


getEncoding (Document Class)

 Microsoft SDK for Java

getEncoding

This method of the Document class retrieves the character encoding information.

Syntax

public final String getEncoding();

Return Value

Returns the encoding information stored in the <?XML ...?> tag or the user-defined output encoding if it has been more recently set.


getFileModifiedDate (Document Class)

 Microsoft SDK for Java

getFileModifiedDate

This method of the Document class retrieves the last modified date on the source of the URL.

Syntax

public long getFileModifiedDate();

Return Value

Returns the modified date.


getId (Document Class)

 Microsoft SDK for Java

getId

This method of the Document class retrieves the external identifier.

Syntax

public final String getId();

Return Value

Returns the external identifier specified in the <!DOCTYPE> tag or null if no <!DOCTYPE> tag was specified.


getOutputStyle (Document Class)

 Microsoft SDK for Java

getOutputStyle

This method of the Document class retrieves the current output style.

Syntax

public int getOutputStyle();

Return Value

Returns the output style. The default style is XMLOutputStream.PRETTY.


getParent (Document Class)

 Microsoft SDK for Java

getParent

This method of the Document class retrieves the parent element. There is no parent element for the Document class, so this method always returns null.

Syntax

public Element getParent();

Return Value

Returns null.

Overrides

getParent() in ElementImpl.


getRoot (Document Class)

 Microsoft SDK for Java

getRoot

This method of the Document class retrieves the root node of the XML parse tree. This is guaranteed to be of type Element.ELEMENT.

Syntax

public final Element getRoot();

Return Value

Returns the root node.


getStandalone (Document class)

 Microsoft SDK for Java

getStandalone

This method of the Document class retrieves the standalone information.

Syntax

public final String getStandalone();

Return Value

Returns the standalone attribute stored in the <XML...?> tag.


getText (Document Class)

 Microsoft SDK for Java

getText

This method of the Document class retrieves the document text.

Syntax

public String getText();

Return Value

Returns a plain text (that is, not marked-up) representation of the entire document.

Overrides

getText() in ElementImpl.


getType (Document Class)

 Microsoft SDK for Java

getType

This method of the Document class retrieves the document type.

Syntax

public int getType();

Return Value

Returns the value defined by Element.DOCUMENT.

Overrides

getType() in ElementImpl.


getURL (Document Class)

 Microsoft SDK for Java

getURL

This method of the Document class retrieves the URL.

Syntax

public final String getURL();

Return Value

Returns the last URL sent to the load() method or null if an input stream was used.


getVersion (Document Class)

 Microsoft SDK for Java

getVersion

This method of the Document class retrieves the version information.

Syntax

public final String getVersion();

Return Value

Returns the version number stored in the <?XML ...?> tag.


isCaseInsensitive (Document Class)

 Microsoft SDK for Java

isCaseInsensitive

This method of the Document class determines whether the loaded XML is case-insensitive.

Syntax

public boolean isCaseInsensitive();

Return Value

Returns whether the loaded XML is case-insensitive. The default is yes.


load (Document Class)

 Microsoft SDK for Java

load

This method of the Document class contains the following signatures:

load(String urlstr)
load(URL url)
load(InputStream in)

load(String urlstr)

Loads the document from the given URL string.

Syntax

public void load(String urlstr) throws ParseException;

Parameters

urlstr The URL specifying the address of the document.

Exceptions

ParseException if the file contains errors.

load(URL url)

Loads the document from the given URL.

Syntax

public void load(URL url) throws ParseException;

Parameters

url The URL string.

Exceptions

ParseException if a syntax error is found.

load(InputStream in)

Loads the document using the given input stream. This is useful if you have the XML data already in memory.

Syntax

public void load(InputStream in) throws ParseException;

Parameters

in The input stream.

Exceptions

ParseException when a syntax error is found.


loadExternal (Document Class)

 Microsoft SDK for Java

loadExternal

This method of the Document class retrieves the status of the loadExternal field.

Syntax

public boolean loadExternal();

Return Value

Returns whether to load external DTDs or entities.


parsed (Document Class)

 Microsoft SDK for Java

parsed

This method of the Document class is called when the given element is completely parsed.

Syntax

public void parsed(Element e);

Parameters

e The Element that has been parsed.


parsedAttribute (Document Class)

 Microsoft SDK for Java

parsedAttribute

This method of the Document class is a delegate to the contained element factory.

Syntax

public void parsedAttribute(Element e, Name name, Object value);

Parameters

e | The attribute that has been parsed.
name | The attribute name.
value | The attribute value.


removeChild (Document Class)

 Microsoft SDK for Java

removeChild

This method of the Document class removes the specified child Element from the Document class.

Syntax

public void removeChild(Element elem);

Parameters

elem The child element to remove.

Overrides

removeChild(Element) in ElementImpl.


reportError (Document Class)

 Microsoft SDK for Java

reportError

This method of the Document class returns information about the given parse exception that was generated during the load.

Syntax

public void reportError(ParseException e, OutputStream out);

Parameters

e | The exception to report on.
out | The output stream to report to.


save (Document Class)

 Microsoft SDK for Java

save

This method of the Document class saves the document to the given output stream.

Syntax

public void save(XMLOutputStream o) throws IOException;

Parameters

o The output stream.

Overrides

save(XMLOutputStream) in ElementImpl.

Exceptions

IOException if there is a problem saving the output.


setCaseInsensitive (Document Class)

 Microsoft SDK for Java

setCaseInsensitive

This method of the Document class is a Boolean switch that determines whether the next XML loaded will be treated as case-insensitive. If not, names are folded to uppercase.

Syntax

public void setCaseInsensitive(boolean yes);

Parameters

yes Specifies that the next loaded XML will be treated as case-sensitive.


setCharset (Document Class)

 Microsoft SDK for Java

setCharset

This method of the Document class sets the character set. This is an alias for the getEncoding method and exists only for compatibility reasons.

Syntax

public final void setCharset(String encoding);

Parameters

encoding The encoding information.


setEncoding (Document Class)

 Microsoft SDK for Java

setEncoding

This method of the Document class sets the character encoding for output. Eventually it sets the ENCODING stored in the <?XML ...?> tag, but not until the document is saved. You should not call this method until the Document has been loaded.

Syntax

public final void setEncoding(String encoding);


setLoadExternal (Document class)

 Microsoft SDK for Java

setLoadExternal

This method of the Document class is a boolean switch that determines whether to load external DTDs or entities.

Syntax

public void setLoadExternal(boolean yes);

Parameters

yes Enables external loading of DTDs or entities.


setOutputStyle (Document Class)

 Microsoft SDK for Java

setOutputStyle

This method of the Document class sets the style for writing to an output stream. Use XMLOutputStream.PRETTY or XMLOutputStream.COMPACT.

Syntax

public void setOutputStyle(int style);

Parameters

int The style to set.

See Also

XMLOutputStream


setShortEndTags (Document Class)

 Microsoft SDK for Java

setShortEndTags

This method of the Document class determines whether to allow short end tags.

XML allows you to end a tag with a "/>". This signals that the element has no contents, and does not have an end tag. For example,

<title/>

is equivalent to

<title></title>

setShortEndTags turns this feature on or off.

Syntax

public void setShortEndTags(boolean yes);

Parameters

yes Enables short end tags.


setStandalone (Document Class)

 Microsoft SDK for Java

setStandalone

This method of the Document class sets the RequiredMarkupDeclaration (RMD) stored in the <?XML ...?> tag. The RMD indicates whether the browser needs to read the document type declarations in the prolog before it can parse the markup data.

Syntax

public final void setStandalone(String value);

Parameters

value The attribute value ("yes" or "no").


setText (Document Class)

 Microsoft SDK for Java

setText

This method of the Document class passes the text through to the root node, if there is a root node.

Syntax

public void setText(String text);

Parameters

text The text to be set.

Overrides

setText(String) in ElementImpl.


setURL (Document Class)

 Microsoft SDK for Java

setURL

This method of the Document class is an alias for load and is here only for compatibility reasons.

Syntax

public void setURL( String urlstr ) throws ParseException;

Parameters

urlstr The URL string.

Exceptions

ParseException if an error occurs while parsing the URL string.


setVersion (Document Class)

 Microsoft SDK for Java

setVersion

This method of the Document class sets the version number stored in the <?XML ...?> tag.

Syntax

public final void setVersion( String version );

Parameters

version The version information to set.


shortEndTags (Document Class)

 Microsoft SDK for Java

shortEndTags

This method of the Document class retrieves whether short end tags are allowed.

Syntax

public boolean shortEndTags();

Return Value

Returns whether short end tags are allowed.


Fields (Document Class)

 Microsoft SDK for Java

Document Class Fields

The Document class contains the following fields.

dtd | The Document Type Definition (DTD).
factory | The factory used to create the elements in the document.


DocumentBeanInfo Class (com.ms.xml.om Package)

 Microsoft SDK for Java

DocumentBeanInfo Class

The DocumentBeanInfo class of the com.ms.xml.om package provides specialized JavaBeans support for the Document class to resolve which overloaded functions are accessible through scripting.

public class DocumentBeanInfo extends SimpleBeanInfo
{
  // Methods
  public MethodDescriptor[] getMethodDescriptors();
}

Hierarchy

SimpleBeanInfo
  |
  +--DocumentBeanInfo


Methods (DocumentBeanInfo Class)

 Microsoft SDK for Java

DocumentBeanInfo Class Methods

The DocumentBeanInfo class contains the following method:

getMethodDescriptors returns the method descriptions for the methods that are to be made available through scripting.


getMethodDescriptors (DocumentBeanInfo Class)

 Microsoft SDK for Java

getMethodDescriptors

This method of the DocumentBeanInfo class retrieves the method descriptions for the methods that are to be made available through scripting.

Syntax

public MethodDescriptor[] getMethodDescriptors();

Return Value

Returns an array of MethodDescriptor objects.


ElementCollection Class (com.ms.xml.om Package)

 Microsoft SDK for Java

ElementCollection Class

The ElementCollection class of the com.ms.xml.om package provides a collection interface to elements similar to the element collections found in the Microsoft® Internet Explorer 4.0 Dynamic HTML (DHTML) object model.

public class ElementCollection
{
  // Constructors
  public ElementCollection(Element root);
  public ElementCollection(Element root, Name tag, int type);

  // Methods
  public Element getChild(int index);
  public int getLength();
  public Object item(String name);
  public Element item(String name, int index);
}


Constructors (ElementCollection Class)

 Microsoft SDK for Java

ElementCollection Class Constructors

The ElementCollection class contains the following constructors:

ElementCollection(Element root)
ElementCollection(Element root, Name tag, int type)

ElementCollection(Element root)

Creates new collection object for given element.

Syntax

public ElementCollection(Element root);

ElementCollection(Element root, Name tag, int type)

Creates a new collection for iterating over the immediate children of the given root node that have matching tag names, element types, or both.

Syntax

public ElementCollection(Element root, Name tag, int type);

Parameters

root | The root to form the collection around.
tag | The name of the tag; this parameter can be null if the name is not important.
type | The element type. Element.ELEMENT is the most common. If the element type is not important, pass -1.


Methods (ElementCollection Class)

 Microsoft SDK for Java

ElementCollection Class Methods

The ElementCollection class contains the following methods:

getChild retrieves a specified item from the collection by index.
getLength retrieves the number of items in the collection.
item retrieves a named item or a collection of matching items.


getChild (ElementCollection Class)

 Microsoft SDK for Java

getChild

This method of the ElementCollection class retrieves a specified item from the collection, given the item’s index.

Syntax

public Element getChild(int index);

Return Value

Returns the requested child node; returns null if not found.

Parameters

index The index of the item in the element collection.


getLength (ElementCollection Class)

 Microsoft SDK for Java

getLength

This method of the ElementCollection class retrieves the number of items in the collection.

Syntax

public int getLength();

Return Value

Returns the item count.


item (ElementCollection Class)

 Microsoft SDK for Java

item

This method of the ElementCollection class contains the following signatures:

item(String name)
item(String name, int index)

item(String name)

Retrieves a named item or a collection of matching items.

Syntax

public Object item(String name);

Return Value

Returns the requested item. Possible types of objects returned are Element, ElementCollection, or null.

Parameters

name The name of the item or collection of matching items.

item(String name, int index)

Retrieves a specified item from the collection of matching items.

Syntax

public Element item(String name, int index);

Return Value

Returns the requested item if it is found; returns null if it is not found.

Parameters

name | The name of the matching items.
index | The index of the specific matching item to return.


ElementDeclEnumeration Class (com.ms.xml.om Package)

 Microsoft SDK for Java

ElementDeclEnumeration Class

The ElementDeclEnumeration class of the com.ms.xml.om package is a simple enumeration for iterating over element declarations.

public class ElementDeclEnumeration implements Enumeration
{
  // Constructors
  public ElementDeclEnumeration(Enumeration elemDecls);
  public ElementDeclEnumeration(Element e);

  // Methods
  public boolean hasMoreElements();
  public Object nextElement();
}


Constructors (ElementDeclEnumeration Class)

 Microsoft SDK for Java

ElementDeclEnumeration Class Constructors

The ElementDeclEnumeration class contains the following constructors:

ElementDeclEnumeration(Enumeration elemDecls)
ElementDeclEnumeration(Element e)

ElementDeclEnumeration(Enumeration elemDecls)

This constructor enumerates over all children of the given root node.

Syntax

public ElementDeclEnumeration(Enumeration elemDecls);

Parameters

elemDecls The element root node.

ElementDeclEnumeration(Element e)

This constructor enumerates all children of the given element.

Syntax

public ElementDeclEnumeration(Element e);

Parameters

e The element to enumerate.


Methods (ElementDeclEnumeration Class)

 Microsoft SDK for Java

ElementDeclEnumeration Class Methods

The ElementDeclEnumeration class contains the following methods:

hasMoreElements determines if there are any more matching elements.
nextElement retrieves the next matching element.


hasMoreElements (ElementDeclEnumeration Class)

 Microsoft SDK for Java

hasMoreElements

This method of the ElementDeclEnumeration class determines if there are any more matching elements.

Syntax

public boolean hasMoreElements();

Return Value

Returns true if the next call to nextElement returns a non-null result.


nextElement (ElementDeclEnumeration Class)

 Microsoft SDK for Java

nextElement

This method of the ElementDeclEnumeration class retrieves the next matching element.

Syntax

public Object nextElement();

Return Value

Returns Element or null if there are no more matching elements.


ElementEnumeration Class (com.ms.xml.om Package)

 Microsoft SDK for Java

ElementEnumeration Class

The ElementEnumeration class of the com.ms.xml.om package is a simple Enumeration for iterating over the immediate children of a given node in the XML tree. This is not a hierarchical iterator. It does not traverse the entire tree.

public class ElementEnumeration implements Enumeration
{
  // Constructors
  public ElementEnumeration(Element root);
  public ElementEnumeration(Element root, Name tag, int type);

  // Methods
  public boolean hasMoreElements();
  public Object nextElement();
  public void reset();
}

See Also

com.ms.xml.om.Element


Constructors (ElementEnumeration Class)

 Microsoft SDK for Java

ElementEnumeration Class Constructors

The ElementEnumeration class contains the following constructors:

ElementEnumeration(Element root)
ElementEnumeration(Element root, Name tag, int type)

ElementEnumeration(Element root)

Creates a new enumerator for enumerating over all the children of the given root node.

Syntax

public ElementEnumeration(Element root);

Parameters

root The element whose children are going to be enumerated.

ElementEnumeration(Element root, Name tag, int type)

Creates a new enumerator for enumerating over the immediate children of the given root node that have matching tag names, types, or both.

Syntax

public ElementEnumeration(Element root, Name tag, int type);

Parameters

root | The element whose children are going to be enumerated.
tag | The name of the tag; this parameter can be null if the name is not important.
type | The element type. Element.ELEMENT is the most common. If the element type is not important, pass -1.


Methods (ElementEnumeration Class)

 Microsoft SDK for Java

ElementEnumeration Class Methods

The ElementEnumeration class contains the following methods:

hasMoreElements determines if there are any more matching elements.
nextElement retrieves the next matching element.
reset resets the iterator so that you can again iterate through the elements.


hasMoreElements (ElementEnumeration Class)

 Microsoft SDK for Java

hasMoreElements

This method of the ElementEnumeration class determines if there are any more matching elements.

Syntax

public boolean hasMoreElements();

Return Value

Returns true if the next call to nextElement will return a non-null result.


nextElement (ElementEnumeration Class)

 Microsoft SDK for Java

nextElement

This method of the ElementEnumeration class retrieves the next matching element.

Syntax

public Object nextElement();

Return Value

Returns Element or null if there are no more matching elements.


reset (ElementEnumeration Class)

 Microsoft SDK for Java

reset

This method of the ElementEnumeration class resets the iterator so that you can again iterate through the elements.

Syntax

public void reset();


ElementFactoryImpl Class (com.ms.xml.om Package)

 Microsoft SDK for Java

ElementFactoryImpl Class

The ElementFactoryImpl class of the com.ms.xml.om package represents the default implementation for the element factory. This is what the XML parser uses if no other factory is specified.

public class ElementFactoryImpl implements ElementFactory
{
  // Constructors
  public ElementFactoryImpl();

  // Methods
  public Element createElement(Element parent, int type, Name tag, String text);
  public void parsed(Element elem);
  public void parsedAttribute(Element e, Name name, Object value);
}


Constructors (ElementFactoryImpl Class)

 Microsoft SDK for Java

ElementFactoryImpl Class Constructors

The ElementFactoryImpl class contains the following constructor:

ElementFactoryImpl()

Constructs the factory object.

Syntax

public ElementFactoryImpl();


Methods (ElementFactoryImpl Class)

 Microsoft SDK for Java

ElementFactoryImpl Class Methods

The ElementFactoryImpl class contains the following methods:

createElement retrieves a new element for the specified tag and type.
parsed is called when the element is fully parsed.
parsedAttribute is called when a new attribute is parsed for the given element.


createElement (ElementFactoryImpl Class)

 Microsoft SDK for Java

createElement

This method of the ElementFactoryImpl class retrieves a new element for the specified tag and type.

Syntax

public Element createElement(Element parent, int type, Name tag, String text);

Return Value

Returns the newly created element.

Parameters

parent | The parent element.
type | One of the predefined Element types that can be returned from Element.getType.
tag | The name of the element.
text | The element text.


parsed (ElementFactoryImpl Class)

 Microsoft SDK for Java

parsed

This method of the ElementFactoryImpl class is called when the element is fully parsed.

Syntax

public void parsed(Element elem);

Parameters

elem The element parsed.

See Also

com.ms.xml.om.Element


parsedAttribute (ElementFactoryImpl Interface)

 Microsoft SDK for Java

parsedAttribute

This method of the ElementFactoryImpl class is called when a new attribute is parsed for the given element.

Syntax

public void parsedAttribute(Element e, Name name, Object value);

Parameters

e | The element containing the attribute.
name | The attribute name.
value | May be a string, name or vector of names.


ElementImpl Class (com.ms.xml.om Package)

 Microsoft SDK for Java

ElementImpl Class

The ElementImpl class of the com.ms.xml.om package represents the default implementation of the Element interface. These are created by the XML parser when using the default element factory.

public class ElementImpl implements Element
{
  // Fields
  protected Attributes attrlist;

  // Constructors
  public ElementImpl();
  public ElementImpl(Name tag, int type);

  // Methods
  public void addChild(Element elem, Element after);
  public void addChild(Element elem, int pos, int reserved);
  public Object getAttribute(String name);
  public Object getAttribute(Name attrName);
  public Enumeration getAttributes();
  public Element getChild(int index);
  public ElementCollection getChildren();
  public Enumeration getElements();
  public Element getParent();
  public Name getTagName();
  public String getText();
  public int getType();
  public boolean isAttributeQualified(Name attr, DTD dtd);
  public int numAttributes();
  public int numElements();
  public Name qualifyName(String string);
  public void removeAttribute(String name);
  public void removeAttribute(Name attrName);
  public void removeChild(Element elem);
  public void save(XMLOutputStream o) throws IOException;
  public void saveAttributes(Atom ns, XMLOutputStream o)
        throws IOException;
  public void setAttribute(String name, Object value);
  public void setAttribute(Name attrName, Object value);
  public void setParent(Element parent);
  public void setText(String text);
  public Element toSchema();
  public String toString();
}

See Also

com.ms.xml.om.Element, Parser, com.ms.xml.om.ElementFactory, com.ms.xml.om.ElementFactoryImpl


Constructors (ElementImpl Class)

 Microsoft SDK for Java

ElementImpl Class Constructors

The ElementImpl class contains the following constructors:

ElementImpl() is the default constructor.
ElementImpl(Name tag, int type) creates an instance of ElementImpl given the element tag name and the element type.

ElementImpl()

The default constructor.

Syntax

public ElementImpl();

ElementImpl(Name tag, int type)

Creates an instance of ElementImpl given the element tag name and the element type.

Syntax

public ElementImpl(Name tag, int type);

Parameters

tag | The element tag name.
type | The element type.


Methods (ElementImpl Class)

 Microsoft SDK for Java

ElementImpl Class Methods

The ElementImpl class contains the following methods:

addChild adds a child to this element.
getAttribute returns the value of the attribute; returns null if the attribute is not found.
getAttributes retrieves an enumeration for the element attributes.
getChild retrieves the child element by index.
getChildren returns an element collection of the children of this element.
getElements returns an enumeration of the children of this element.
getParent retrieves the parent of this element.
getTagName retrieves the name of the tag as a string.
getText returns the non—marked-up text contained by this element.
getType retrieves the type of the element.
isAttributeQualified determines if the attribute is qualified.
numAttributes retrieves the number of attributes.
numElements retrieves the number of child elements.
qualifyName creates a qualified Name object from the given string.
removeAttribute deletes an attribute from an element.
removeChild removes a child element from the tree.
save saves the element in XML format.
saveAttributes saves the element attributes in XML format.
setAttribute sets the attribute of this element.
setParent sets the parent of this element.
setText sets the text for this element.
toSchema returns the XML-DATA specification for the DTD element.
toString retrieves the string representation of this element.


addChild (ElementImpl Class)

 Microsoft SDK for Java

addChild

This method of the ElementImpl class contains the following signatures:

addChild(Element elem, Element after)
addChild(Element elem, int pos, int reserved)

addChild(Element elem, Element after)

Adds a child to this element. Any element can only have one parent element, so the previous parent will lose this child from its subtree.

Syntax

public void addChild(Element elem, Element after);

Parameters

elem | The element to add. The child element becomes the last element if after is null. The child is added to the beginning of the list if after is this object.
after | The element after which to add it.

addChild(Element elem, int pos, int reserved)

Adds a child to this element.

Syntax

public void addChild(Element elem, int pos, int reserved);

Parameters

elem | The element to add.
pos | The position to add this element (calling getChild(pos) will return this element). If pos is less than 0 (zero), elem becomes the new last element.
reserved | The reserved parameter.


getAttribute (ElementImpl Class)

 Microsoft SDK for Java

getAttribute

This method of the ElementImpl class contains the following signatures:

getAttribute(String name)
getAttribute(Name attrName)

getAttribute(String name)

Retrieves a named attribute's value.

Syntax

public Object getAttribute(String name);

Return Value

Returns the value of the attribute; returns null if the attribute is not found.

Parameters

name The name of the attribute.

getAttribute(Name attrName)

Retrieves a named attribute's value.

Syntax

public Object getAttribute(Name attrName);

Return Value

Returns the value of the attribute; returns null if the attribute is not found.

Parameters

name The name of the attribute.


getAttributes (ElementImpl Class)

 Microsoft SDK for Java

getAttributes

This method of the ElementImpl class retrieves an enumeration for the element attributes. The enumeration returns Attribute objects.

Syntax

public Enumeration getAttributes();

Return Value

Returns the enumeration. This method must not return null (see EnumWrapper for returning empty enumerations).

See Also

Attribute


getChild (ElementImpl Class)

 Microsoft SDK for Java

getChild

This method of the ElementImpl class retrieves the child element by index.

Syntax

public Element getChild(int index);

Return Value

Returns null if there is no child by that index.

Parameters

index The index of the child element.


getChildren (ElementImpl Class)

 Microsoft SDK for Java

getChildren

This method of the ElementImpl class retrieves an element collection of the children of this element. This method must not return null. For an empty enumeration, see EnumWrapper.

Syntax

public ElementCollection getChildren();

Return Value

Returns element collection of child objects.


getElements (ElementImpl Class)

 Microsoft SDK for Java

getElements

This method of the ElementImpl class retrieves an enumeration of the children of this element. Enumeration.nextElement returns Element objects.

Syntax

public Enumeration getElements();

Return Value

Returns an enumeration of child objects. It must not return null. See EnumWrapper for an easy way to return an empty enumeration.


getParent (ElementImpl Class)

 Microsoft SDK for Java

getParent

This method of the ElementImpl class retrieves the parent of this element. Every element in the tree except the Document object itself has a parent.

Syntax

public Element getParent();

Return Value

Returns the parent element or null if the element is at the root of the tree.


getTagName (ElementImpl Class)

 Microsoft SDK for Java

getTagName

This method of the ElementImpl class retrieves the name of the tag as a string. The string will be in uppercase.

Syntax

public Name getTagName();

Return Value

Returns the tag name or null for DATA and PCDATA elements.


getText (ElementImpl Class)

 Microsoft SDK for Java

getText

This method of the ElementImpl class retrieves the non—marked-up text contained by this element. For text elements, the non—marked-up text is the raw data. For elements with child nodes, this method traverses the entire subtree and appends the text for each terminal text element, effectively removing the XML markup for the subtree. For example, if the XML document contains the following:

<xmp> <AUTHOR> <FIRST>William</FIRST> <LAST>Shakespeare</LAST> </AUTHOR> </xmp>

Document.getText returns "William Shakespeare".

Syntax

public String getText();


getType (ElementImpl Class)

 Microsoft SDK for Java

getType

This method of the ElementImpl class retrieves the type of the element. This is always one of the following values: DOCUMENT, ELEMENT, PCDATA, PI, META, COMMENT, or CDATA.

Syntax

public int getType();

Return Value

Returns the element type.


isAttributeQualified (ElementImpl Class)

 Microsoft SDK for Java

isAttributeQualified

This method of the ElementImpl class determines if the attribute is qualified.

Syntax

public boolean isAttributeQualified(Name attr, DTD dtd);

Return Value

Returns true if the attribute is qualified; otherwise, returns false.

Parameters

attr | The name of the attribute.
dtd | The Document Definition Type (DTD) that the attribute is found in.


numAttributes (ElementImpl Class)

 Microsoft SDK for Java

numAttributes

This method of the ElementImpl class retrieves the number of attributes.

Syntax

public int numAttributes();

Return Value

Returns the number of attributes.


numElements (ElementImpl Class)

 Microsoft SDK for Java

numElements

This method of the ElementImpl class retrieves the number of child elements.

Syntax

public int numElements();

Return Value

Returns the number of child elements.


qualifyName (ElementImpl class)

 Microsoft SDK for Java

qualifyName

This method of the ElementImpl class creates a qualified Name object from the given string. It parses the string, looks up the specified namespace, and creates the fully qualified name. If no namespace is given, qualifyName inherits the namespace from the current element.

Syntax

public Name qualifyName(String string);

Return Value

Returns the fully qualified name.

Parameters

string A namespace name.


removeAttribute (ElementImpl Class)

 Microsoft SDK for Java

removeAttribute

The removeAttribute method of the ElementImpl class contains the following signatures:

removeAttribute(String name)
removeAttribute(Name attrName)

removeAttribute(String name)

Deletes an attribute from an element.

Syntax

public void removeAttribute(String name);

Parameters

name The attribute to delete.

removeAttribute(Name attrName)

Deletes an attribute from an element.

Syntax

public void removeAttribute(Name attrName);

Parameters

attrName The attribute name to delete.


removeChild (ElementImpl Class)

 Microsoft SDK for Java

removeChild

This method of the ElementImpl class removes a child element from the tree.

Syntax

public void removeChild(Element elem);

Parameters

elem The element to remove.


save (ElementImpl Class)

 Microsoft SDK for Java

save

This method of the ElementImpl class saves the element in XML format.

Syntax

public void save(XMLOutputStream o) throws IOException;

Parameters

o The output stream to save to.

Exceptions

IOException if an error occurs when writing to the output stream.


saveAttributes (ElementImpl Class)

 Microsoft SDK for Java

saveAttributes

This method of the ElementImpl class saves the element attributes in XML format.

Syntax

public void saveAttributes(Atom ns, XMLOutputStream o) throws IOException;

Parameters

ns | The name of the element attribute.
o | The output stream to save to.

Exceptions

IOException if an error occurs when writing to the output stream.


setAttribute (ElementImpl Class)

 Microsoft SDK for Java

setAttribute

This method of the ElementImpl class contains the following signatures:

setAttribute(String name, Object value)
setAttribute(Name attrName, Object value)

setAttribute(String name, Object value)

Sets the attribute of this element.

Syntax

public void setAttribute(String name, Object value);

Return Value

Returns the previous value, if any.

Parameters

name | The attribute name.
value | The attribute value.

setAttribute(Name attrName, Object value)

Sets the attribute of this element.

Syntax

public void setAttribute(Name attrName, Object value);

Parameters

attrName | The attribute name.
value | The attribute value.


setParent (ElementImpl Class)

 Microsoft SDK for Java

setParent

This method of the ElementImpl class sets the parent of this element.

Syntax

public void setParent(Element parent);

Parameters

parent The element to set as the parent.


setText (ElementImpl Class)

 Microsoft SDK for Java

setText

This method of the ElementImpl class sets the text for this element. This text is meaningful in only CDATA, PCDATA, and COMMENT nodes.

Syntax

public void setText(String text);

Parameters

text The text to set.


toSchema (ElementImpl class)

 Microsoft SDK for Java

toSchema

This method of the ElementImpl retrieves the XML-DATA specification for the DTD element. This applies to only ElementDecl and Entity nodes. This is DTD information represented in an XML Object Model.

Syntax

public Element toSchema();

Return Value

Returns the XML-DATA specification for the DTD element.


toString (ElementImpl Class)

 Microsoft SDK for Java

toString

This method of the ElementImpl class retrieves the string representation of this element.

Syntax

public String toString();

Return Value

Returns a string representing the element.


Fields (ElementImpl Class)

 Microsoft SDK for Java

ElementImpl Class Fields

The ElementImpl class contains the following fields.

attrlist The attribute list.


ElementImplBeanInfo Class (com.ms.xml.om Package)

 Microsoft SDK for Java

ElementImplBeanInfo Class

The ElementImplBeanInfo class of the com.ms.xml.om package provides specialized JavaBeans support for the ElementImpl class to resolve which overloaded functions are accessible through scripting.

public class ElementImplBeanInfo extends SimpleBeanInfo
{
  // Methods
  public MethodDescriptor[] getMethodDescriptors();
}

Hierarchy

SimpleBeanInfo
  |
  +--ElementImplBeanInfo


Methods (ElementImplBeanInfo Class)

 Microsoft SDK for Java

ElementImplBeanInfo Class Methods

The ElementImplBeanInfo class contains the following method:

getMethodDescriptors retrieves the method descriptions for the methods that are to be made available through scripting.


getMethodDescriptors (ElementImplBeanInfo Class)

 Microsoft SDK for Java

getMethodDescriptors

This method of the ElementImplBeanInfo class retrieves the method descriptions for the methods that are to be made available through scripting.

Syntax

public MethodDescriptor[] getMethodDescriptors();

Return Value

Returns an array of MethodDescriptor objects.


Element Interface (com.ms.xml.om Package)

 Microsoft SDK for Java

Element Interface

The Element interface of the com.ms.xml.om package implements an Element object. The elements are named with a string, have attributes, and can contain child nodes. Each XML tag in a document is represented by an Element object in the XML parse tree.

The element types are DOCUMENT, ELEMENT, PCDATA, PI, META, COMMENT, and CDATA.

public interface Element
{
  // Fields
  static public final int CDATA;
  static public final int COMMENT;
  static public final int DOCUMENT;
  static public final int DTD;
  static public final int ELEMENT;
  static public final int ELEMENTDECL;
  static public final int ENTITY;
  static public final int ENTITYREF;
  static public final int NAMESPACE;
  static public final int NOTATION;
  static public final int PCDATA;
  static public final int PI;
  static public final int WHITESPACE;
  static public final int INCLUDESECTION;
  static public final int IGNORESECTION;

  // Methods
  public void addChild(Element elem, Element after);
  public void addChild(Element elem, int pos, int reserved);
  public Object getAttribute(String name);
  public Object getAttribute(Name n);
  public Enumeration getAttributes();
  public Element getChild(int index);
  public ElementCollection getChildren();
  public Enumeration getElements();
  public Element getParent();
  public Name getTagName();
  public String getText();
  public int getType();
  public int numAttributes();
  public int numElements();
  public void removeAttribute(String name);
  public void removeAttribute(Name name);
  public void removeChild(Element elem);
  public void save(XMLOutputStream o) throws IOException;
  public void setAttribute(String name, Object value);
  public void setAttribute(Name name, Object value);
  public void setParent(Element parent);
  public void setText(String text);
  public abstract Element toSchema();
}


Methods (Element Interface)

 Microsoft SDK for Java

Element Interface Methods

The Element interface contains the following methods:

addChild adds a child to this element.
getAttribute retrieves an attribute's value given its name.
getAttributes retrieves an enumeration for the element attributes.
getChild retrieves the child element by index.
getChildren returns an element collection of the children of this element.
getElements returns an enumeration of the children of this element.
getParent retrieves the parent of this element.
getTagName retrieves the name of the tag as a string.
getText returns the non—marked-up text contained by this element.
getType retrieves the type of the element.
numAttributes retrieves the number of attributes.
numElements retrieves the number of child elements.
removeAttribute deletes an attribute from an element.
removeChild removes a child element from the tree.
save saves this element.
setAttribute sets the attribute of this element.
setParent sets the parent of this element.
setText sets the text for this element.
toSchema returns the XML-DATA specification for the DTD element.


addChild (Element Interface)

 Microsoft SDK for Java

addChild

This method of the Element interface contains the following signatures:

addChild(Element elem, Element after)
addChild(Element elem, int pos, int reserved)

addChild(Element elem, Element after)

Adds a child to this element. Any element can only have one parent element. As a result, the previous parent will lose this child from its subtree.

Syntax

public void addChild(Element elem, Element after);

Parameters

elem | The element to add. The child element becomes the last element if after is null. The child is added to the beginning of the list if after is this object.
after | The element after which to add elem.

addChild(Element elem, int pos, int reserved)

Adds a child to this element.

Syntax

public void addChild(Element elem, int pos, int reserved);

Parameters

elem | The element to add.
pos | The position to add this element (calling getChild(pos) will return this element). If pos is less than 0, elem becomes the new last element.
reserved | The reserved parameter.


getAttribute (Element Interface)

 Microsoft SDK for Java

getAttribute

This method of the Element interface contains the following signatures:

getAttribute(String name)
getAttribute(Name n)

getAttribute(String name)

Retrieves an attribute's value given its name.

Syntax

public Object getAttribute(String name);

Return Value

Returns the value of the attribute or null if the attribute is not found.

Parameters

name The name of the attribute.

getAttribute(Name n)

Retrieves an attribute's value given its name.

Syntax

public Object getAttribute(Name n);

Return Value

Returns the value of the attribute or null if the attribute is not found.

Parameters

n The name of the attribute.


getAttributes (Element Interface)

 Microsoft SDK for Java

getAttributes

This method of the Element interface retrieves an enumeration for the element attributes. The enumeration returns Attribute objects.

Syntax

public Enumeration getAttributes();

Return Value

Returns the enumeration. It must not return null. For returning empty enumerations, see EnumWrapper.

See Also

Attribute


getChild (Element Interface)

 Microsoft SDK for Java

getChild

This method of the Element interface retrieves the child element by index.

Syntax

public Element getChild(int index);

Return Value

Returns null if there is no child by that index.

Parameters

index The index of the child element.


getChildren (Element Interface)

 Microsoft SDK for Java

getChildren

This method of the Element interface retrieves an element collection of the children of this element. It must not return null. For an empty enumeration, see EnumWrapper.

Syntax

public ElementCollection getChildren();

Return Value

Returns ElementCollection of child objects.


getElements (Element Interface)

 Microsoft SDK for Java

getElements

This method of the Element interface retrieves an enumeration of the children of this element. Enumeration.nextElement returns Element objects.

Syntax

public Enumeration getElements();

Return Value

Returns an enumeration of child objects. It must not return null. For an easy way to return an empty enumeration, see EnumWrapper.


getParent (Element Interface)

 Microsoft SDK for Java

getParent

This method of the Element interface retrieves the parent of this element. Every element in the tree—except the Document itself—has a parent.

Syntax

public Element getParent();

Return Value

Returns the parent element or null if at the root of the tree.


getTagName (Element Interface)

 Microsoft SDK for Java

getTagName

This method of the Element interface retrieves the name of the tag as a string. The string will be in uppercase.

Syntax

public Name getTagName();

Return Value

Returns the tag name or null for DATA and PCDATA elements.


getText (Element Interface)

 Microsoft SDK for Java

getText

This method of the Element interface returns the non—marked-up text contained by this element. For text elements, this text is the raw data. For elements with child nodes, getText traverses the entire subtree and appends the text for each terminal text element, effectively removing the XML markup for the subtree. For example, if the XML document contains

<xmp> <AUTHOR> <FIRST>William</FIRST> <LAST>Shakespeare</LAST> </AUTHOR> </xmp>

Document.getText returns "William Shakespeare".

Syntax

public String getText();


getType (Element Interface)

 Microsoft SDK for Java

getType

This method of the Element interface retrieves the type of the element. The type is always one of the following values: DOCUMENT, ELEMENT, PCDATA, PI, META, COMMENT, or CDATA.

Syntax

public int getType();

Return Value

Returns element type.


numAttributes (Element Interface)

 Microsoft SDK for Java

numAttributes

This method of the Element interface retrieves the number of attributes.

Syntax

public int numAttributes();

Return Value

Returns the number of attributes.


numElements (Element Interface)

 Microsoft SDK for Java

numElements

This method of the Element interface retrieves the number of child elements.

Syntax

public int numElements();

Return Value

Returns the number of child elements.


removeAttribute (Element Interface)

 Microsoft SDK for Java

removeAttribute

This method of the Element interface contains the following signatures:

removeAttribute(String name)
removeAttribute(Name name)

removeAttribute(String name)

Deletes an attribute from an element.

Syntax

public void removeAttribute(String name);

Parameters

name The attribute to delete.

removeAttribute(Name name)

Deletes an attribute from an element.

Syntax

public void removeAttribute(Name name);

Parameters

name The attribute to delete.


removeChild (Element Interface)

 Microsoft SDK for Java

removeChild

This method of the Element interface removes a child element from the tree.

Syntax

public void removeChild(Element elem);

Parameters

elem The element to remove.


save (Element Interface)

 Microsoft SDK for Java

save

This method of the Element interface saves this element.

Syntax

public void save(XMLOutputStream o) throws IOException;

Parameters

o The output stream to save to.

Exceptions

IOException if there is a problem saving the output.


setAttribute (Element Interface)

 Microsoft SDK for Java

setAttribute

This method of the Element interface contains the following signatures:

setAttribute(String name, Object value)
setAttribute(Name name, Object value)

setAttribute(String name, Object value)

Sets the attribute of this element.

Syntax

public void setAttribute(String name, Object value);

Parameters

name | The attribute name.
value | The attribute value.

setAttribute(Name name, Object value)

Sets the attribute of this element.

Syntax

public void setAttribute(Name name, Object value);

Parameters

name | The attribute name.
value | The attribute value.


setParent (Element Interface)

 Microsoft SDK for Java

setParent

This method of the Element interface sets the parent of this element.

Syntax

public void setParent(Element parent);

Parameters

parent The element to set as parent.


setText (Element Interface)

 Microsoft SDK for Java

setText

This method of the Element interface sets the text for this element. setText is meaningful in only CDATA, PCDATA, and COMMENT nodes.

Syntax

public void setText(String text);

Parameters

text The text to set.


toSchema (Element Interface)

 Microsoft SDK for Java

toSchema

This method of the Element interface retrieves the XML-DATA specification for the DTD element. This applies to only ElementDecl and Entity nodes. This is DTD information represented in an XML Object Model.

Implementations for this abstract method are provided in ElementImpl and AttDef.

Syntax

public abstract Element toSchema();


Fields (Element Interface)

 Microsoft SDK for Java

Element Interface Fields

The Element interface contains the fields as shown in the following table.

CDATA | Raw character data specified with special CDATA construct: <![CDATA[...]]>, where ... can be anything except ]]>, including HTML tags.
COMMENT | An XML comment (<!-- ... -->).
DOCUMENT | Reserved for use by only the Document node.
DTD | Reserved for use by only the DTD node.
ELEMENT | A general container element having optional attributes and optional child elements.
ELEMENTDECL | An element declaration node.
ENTITY | An entity node.
ENTITYREF | Entity reference nodes.
IGNORESECTION | Ignore conditional section.
INCLUDESECTION | Include conditional section.
META | A meta element containing information about the tree.
NAMESPACE | A namespace node that declares new namespaces in the element tree.
NOTATION | A notation node.
PCDATA | A text element that has no children or attributes and that contains parsed character data.
PI | A processing instruction node (<? ... ?>).
WHITESPACE | White space to ignore between elements.


ElementFactory Interface (com.ms.xml.om Package)

 Microsoft SDK for Java

ElementFactory Interface

The ElementFactory interface of the com.ms.xml.om package specifies a method to create elements for an XML element tree. This is used by the XML Document to create nodes in the tree as it parses the elements.

public interface ElementFactory
{
  // Methods
  public abstract Element createElement(Element parent, int type, Name tag, String text);
  public abstract void parsed(Element elem);
  public abstract void parsedAttribute(Element e, Name name, Object value);
}


Methods (ElementFactory Interface)

 Microsoft SDK for Java

ElementFactory Interface Methods

The ElementFactory interface contains the following methods:

createElement creates an element with the specified tag for the specified type of element.
parsed gives notification that the element is fully parsed.
parsedAttribute gives notification that an attribute has been parsed.


createElement (ElementFactory Interface)

 Microsoft SDK for Java

createElement

This method of the ElementFactory interface creates an element with the specified tag for the specified type of element.

Syntax

public abstract Element createElement(Element parent, int type, Name tag, String text);

Return Value

Returns the created element.

Parameters

parent | The parent element.
type | One of the predefined Element types that can be returned from Element.getType.
tag | The name of the element.
text | The element text.

See Also

com.ms.xml.os.Element


parsed (ElementFactory Interface)

 Microsoft SDK for Java

parsed

This method of the ElementFactory interface gives notification that the element is fully parsed.

Syntax

void parsed(Element elem);

Parameters

elem The element parsed.

See Also

com.ms.xml.os.Element


parsedAttribute (ElementFactory Interface)

 Microsoft SDK for Java

parsedAttribute

This method of the ElementFactory interface gives notification that an attribute has been parsed.

Syntax

public abstract void parsedAttribute(Element e, Name name, Object value);

Parameters

e | The element containing the attribute.
name | The attribute name.
value | May be a string, name, or vector of names.


com.ms.xml.parser Package Overview

Microsoft Packages Overview

The com.ms.xml.parser package contains the Microsoft® XML Parser, which is a validating XML parser written in Java. The parser checks for well-formed documents and, optionally, permits checking of the validity of the documents according to the Document Type Definition (DTD). This package is encapsulated by the Document class in the com.ms.xml.om package, so you shouldn't need to use this package directly.

This package contains the following:

Classes

Hierarchy


Classes (com.ms.xml.parser Package)

 Microsoft SDK for Java

com.ms.xml.parser Package Classes

The com.ms.xml.parser package contains the following classes:

AttDef Class describes an attribute type and potential values. This class encapsulates the information for one Attribute in an Attribute List.

ContentModel Class represents the content model definition for a given Microsoft® XML element.

DTD Class contains all the Document Type Definition (DTD) information for an XML document.

ElementDecl Class represents an element declaration in an XML Document Type Definition (DTD).

ElementDeclEnumeration is a simple enumeration for iterating over element declarations.

Entity Class implements an Entity object representing an XML internal or external entity as defined in the XML Document Type Definition (DTD).

Notation Class implements an entity object representing an XML notation.

ParseException Class signals that a parsing exception of some sort has occurred.

Parser Class implements an eXtensible Markup Language (XML) parser according to the latest World Wide Web Consortium (W3C) working draft of the XML specification.


Hierarchy (com.ms.xml parser Package)

 Microsoft SDK for Java

com.ms.xml.parser Package Hierarchy

The com.ms.xml.parser package has the following hierarchy:

Object
  |
  +--AttDef
  |
  +--ContentModel
  |
  +--DTD
  |
  +--Parser

ElementImpl
  |
  +--ElementDecl
  |
  +--ElementDeclEnumeration (Enumeration)
  |
  +--Entity
  |
  +--Notation

Exception
  |
  +--ParseException


AttDef Class (com.ms.xml.parser Package)

 Microsoft SDK for Java

AttDef Class

The AttDef class of the com.ms.xml.parser package describes an attribute type and potential values. This class encapsulates the information for one attribute in an attribute list in a Document Type Definition (DTD).

public class AttDef
{
// Fields
  public static final int CDATA;
  public static final int ID;
  public static final int IDREF;
  public static final int IDREFS;
  public static final int ENTITY;
  public static final int ENTITIES;
  public static final int NMTOKEN;
  public static final int NMTOKENS;
  public static final int NOTATION;
  public static final int ENUMERATION;
  public static final int DEFAULT;
  public static final int REQUIRED;
  public static final int IMPLIED;
  public static final int FIXED;

  // Constructors
  AttDef(Name name, int type);
  AttDef(Name name, int type, Vector values);
  AttDef(Name name, int type, Object def, int presence);
  AttDef(Name name, int type, Object def, int presence, Vector values);

  // Methods
  public Object getDefault();
  public Name getName();
  public int getPresence();
  public int getType();

}


Constructors (AttDef Class)

 Microsoft SDK for Java

AttDef Class Constructors

The AttDef class contains the following constructors:

AttDef(Name name, int type)
AttDef(Name name, int type, Vector values)
AttDef(Name name, int type, Object def, int presence)
AttDef(Name name, int type, Object def, int presence, Vector values)

AttDef(Name name, int type)

Constructs a new object for the given attribute type.

Syntax

AttDef(Name name, int type);

Parameters

name | The name of the attribute.
type | The attribute type.

AttDef(Name name, int type, Vector values)

Constructs a new object for the given attribute type and array of possible values.

Syntax

AttDef(Name name, int type, Vector values);

Parameters

name | The name of the attribute.
type | The attribute type.
values | The possible values.

AttDef(Name name, int type, Object def, int presence)

Constructs a new object for the given attribute type, default value, and presence flag.

Syntax

AttDef(Name name, int type, Object def, int presence);

Parameters

name | The name of the attribute.
type | The attribute type.
def | The default value of the attribute.
presence | Specifies the presence value of the attribute. Values are as follows: DEFAULT = 0 REQUIRED = 1 IMPLIED = 2 FIXED = 3

AttDef(Name name, int type, Object def, int presence, Vector values)

Constructs a new object for the given attribute type, default value, presence flag, and range of possible values.

Syntax

AttDef(Name name, int type, Object def, int presence, Vector values);

Parameters

name | The name of the attribute.
type | The attribute type.
def | The default value of the attribute.
presence | Specifies the presence type of the attribute. Values are as follows: DEFAULT = 0 REQUIRED = 1 IMPLIED = 2 FIXED = 3
values | The possible attribute values.


Methods (AttDef Class)

 Microsoft SDK for Java

AttDef Class Methods

The AttDef class contains the following methods:

getDefault returns the default value for the attribute.
getName returns the name of the attribute.
getPresence returns the presence type for the attribute.
getType returns the attribute type.


getDefault (AttDef Class)

 Microsoft SDK for Java

getDefault

This method of the AttDef class returns the default value for the attribute.

Syntax

public Object getDefault();

Return Value

Returns the default value for the attribute.


getName (AttDef Class)

 Microsoft SDK for Java

getName

This method of the AttDef class retrieves the name of the attribute.

Syntax

public Name getName();

Return Value

Returns the name of the attribute.


getPresence (AttDef Class)

 Microsoft SDK for Java

getPresence

This method of the AttDef class retrieves the presence type for the attribute.

Syntax

public int getPresence();

Return Value

Returns the presence type for the attribute.


getType (AttDef Class)

 Microsoft SDK for Java

getType

This method of the AttDef class retrieves the attribute type.

Syntax

public int getType();

Return Value

Returns the attribute type.


Fields (AttDef Class);

 Microsoft SDK for Java

AttDef Class Fields

The AttDef class contains the following fields. They are all constant integers denoting attribute types.

Field

Value
CDATA | 0
ID | 1
IDREF | 2
IDREFS | 3
ENTITY | 4
ENTITIES | 5
NMTOKEN | 6
NMTOKENS | 7
NOTATION | 8
ENUMERATION | 9

The AttDef class also contains the following fields. They are all constant integers denoting attribute presence.

Field

Value
DEFAULT | 0
REQUIRED | 1
IMPLIED | 2
FIXED | 3


ContentModel Class (com.ms.xml.parser Package)

 Microsoft SDK for Java

ContentModel Class

The ContentModel class of the com.ms.xml.parser package represents the content model definition for a given XML element.

public class ContentModel
{
// Fields
  public static final byte EMPTY;
  public static final byte ANY;
  public static final byte ELEMENTS;

  // Methods
  public byte getType();
  public void save(Atom ns, XMLOutputStream o) throws IOException;
  public Element toSchema();
  public String toString();

}

The content model is defined in the element declaration in the Document Type Definition (DTD); for example, (a,(b|c)*,d). The content model is stored in an expression tree of Node objects for use by the XML parser during validation.


Methods (ContentModel Class)

 Microsoft SDK for Java

ContentModel Class Methods

The ContentModel class contains the following methods:

getType returns the content type.
save saves the content model out to the specified stream.
toSchema retrieves the XML-DATA specification for the DTD element.
toString retrieves a string representation of the content type.


getType (ContentModel class)

 Microsoft SDK for Java

getType

This method of the ContentModel class retrieves the content type.

Syntax

public byte getType();

Return Value

The content type.


save (ContentModel Class)

 Microsoft SDK for Java

save

This method of the ContentModel class saves the content model out to the specified stream.

Syntax

public void save(Atom ns, XMLOutputStream o) throws IOException;

Parameters

ns | The current namespace context.
o | The output stream to write to.

Exceptions

IOException if there was a problem writing to the output stream.


toSchema (ContentModel Class)

 Microsoft SDK for Java

toSchema

This method of the ContentModel class retrieves the XML-DATA specification for the DTD element.

Syntax

public Element toSchema();

Return Value

Returns the element content.


toString (ContentModel Class)

 Microsoft SDK for Java

toString

This method of the ContentModel class retrieves a string representation of the content type.

Syntax

public String toString();

Return Value

Returns a String.


Fields (ContentModel Class)

 Microsoft SDK for Java

ContentModel Class Fields

The ContentModel class contains the following fields. They are byte constants that denote content type.

Field | Value
EMPTY | 1
ANY | 2
ELEMENTS | 4


DTD Class (com.ms.xml.parser Package)

 Microsoft SDK for Java

DTD Class

The DTD Class of the com.ms.xml.parser package contains all the Document Type Definition (DTD) information for an XML document.

public class DTD
{
  // Constructors
  public DTD();

  // Methods
  public final void addLoadedNameSpace(Atom url);
  public final void addNameSpace(Atom as, Atom href);
  public final void clear();
  public final Enumeration elementDeclarations();
  public final Enumeration entityDeclarations();
  public final ElementDecl findElementDecl(Name name);
  public final Entity findEntity(Name n);
  public final Name findLoadedNameSpace(Atom url);
  public final Name findLongNameSpace(Atom as);
  public final Notation findNotation(Name name);
  public final Name findShortNameSpace(Atom href);
  public final Name getDocType();
  public final Element getSchema();
  public static boolean isReservedNameSpace(Atom n);
  public final Enumeration notationDeclarations();
  public final void save(XMLOutputStream o) throws IOException;
}


Constructors (DTD Class)

 Microsoft SDK for Java

DTD Class Constructors

The DTD class contains the following constructor:

DTD()

Creates a new empty DTD.

Syntax

public DTD();


Methods (DTD Class)

 Microsoft SDK for Java

DTD Class Methods

The DTD class contains the following methods:

addLoadedNameSpace adds a specified URL to the list of loaded namespaces.
addNameSpace adds a name pair (long name, short name) to the name space hashtable.
clear resets the DTD to its initial state.
elementDeclarations retrieves an object for enumerating the element declarations.
entityDeclarations retrieves an enumeration for enumerating the entities.
findElementDecl finds an element declaration for the given tag name.
findEntity finds a named entity in the DTD.
findLoadedNameSpace determines whether the specified URL is already a loaded namespace so that the caller can decide not to load it again.
findLongNameSpace retrieves the long name of a specified namespace.
findNotation retrieves the named XML notation in the DTD.
findShortNameSpace retrieves the short name of a specified namespace.
getDocType retrieves the name specified in the DOCTYPE tag.
getSchema converts everything stored in the DTD to the schema.
isReservedNameSpace determines if the given namespace is reserved.
notationDeclarations retrieves an enumeration for enumerating the notations.
save saves the DTD information to the given XML output stream.


addLoadedNameSpace (DTD Class)

 Microsoft SDK for Java

addLoadedNameSpace

This method of the DTD class adds a specified URL to the list of loaded namespaces.

Syntax

public final void addLoadedNameSpace(Atom url);

Parameters

url The long name for the namespace.


addNameSpace (DTD Class)

 Microsoft SDK for Java

addNameSpace

This method of the DTD class adds a name pair (long name, short name) to the namespace hash table.

Syntax

public final void addNameSpace(Atom as, Atom href);

Parameters

as | The long name part of the namespace.
href | The short name part of the namespace.


clear (DTD Class)

 Microsoft SDK for Java

clear

This method of the DTD class resets the DTD to its initial state.

Syntax

public final void clear();


elementDeclarations (DTD Class)

 Microsoft SDK for Java

elementDeclarations

This method of the DTD class retrieves an object for enumerating the element declarations.

Syntax

public final Enumeration elementDeclarations();

Return Value

Returns an Enumeration object that returns ElementDecl objects when enumerated.


entityDeclarations (DTD Class)

 Microsoft SDK for Java

entityDeclarations

This method of the DTD class retrieves an enumeration for enumerating the entities. The enumeration returns entity objects.

Syntax

public final Enumeration entityDeclarations();

Return Value

Returns an enumerator for entities.


findElementDecl (DTD Class)

 Microsoft SDK for Java

findElementDecl

This method of the DTD class finds an element declaration for the given tag name.

Syntax

public final ElementDecl findElementDecl(Name name);

Return Value

Returns the element declaration object.

Parameters

name The tag name.


findEntity (DTD Class)

 Microsoft SDK for Java

findEntity

This method of the DTD class finds a named entity in the DTD.

Syntax

public final Entity findEntity(Name n);

Return Value

Returns the specified Entity object; returns null if it is not found.

Parameters

n The name of the entity.


findLoadedNameSpace (DTD Class)

 Microsoft SDK for Java

findLoadedNameSpace

This method of the DTD class determines whether the specified URL is already a loaded namespace so that the caller can decide not to load it again.

Syntax

public final Name findLoadedNameSpace(Atom url);

Return Value

Returns true if it is already loaded; otherwise, returns false.

Parameters

url The long name for the namespace.


findLongNameSpace (DTD Class)

 Microsoft SDK for Java

findLongNameSpace

This method of the DTD class retrieves the long name of a specified namespace.

Syntax

public final Name findLongNameSpace(Atom as);

Return Value

Returns the long name; returns null if it is not found.

Parameters

as The short name of the namespace.


findNotation (DTD Class)

 Microsoft SDK for Java

findNotation

This method of the DTD class retrieves the named XML notation in the DTD.

Syntax

public final Notation findNotation(Name name);

Return Value

Returns the Notation object; returns null if it is not found.

Parameters

name The name of the notation.


findShortNameSpace (DTD Class)

 Microsoft SDK for Java

findShortNameSpace

This method of the DTD class retrieves the short name of a specified namespace.

Syntax

public final Name findShortNameSpace(Atom href);

Return Value

Returns the short name; returns null if it is not found.

Parameters

href The long name of the namespace.


getDocType (DTD Class)

 Microsoft SDK for Java

getDocType

This method of the DTD class retrieves the name specified in the DOCTYPE tag.

Syntax

public final Name getDocType();

Return Value

Returns the name of the document type.


getSchema (DTD Class)

 Microsoft SDK for Java

getSchema

This method of the DTD class converts everything stored in the DTD to the schema. It does not retain the original order.

Syntax

final public Element getSchema();

Return Value

Returns a schema.


isReservedNameSpace (DTD Class)

 Microsoft SDK for Java

isReservedNameSpace

This method of the DTD class determines if the given namespace is reserved.

Syntax

public static boolean isReservedNameSpace(Atom n);

Return Value

Returns true if reserved; otherwise, returns false.

Parameters

n The namespace to verify.


notationDeclarations (DTD Class)

 Microsoft SDK for Java

notationDeclarations

This method of the DTD class retrieves an enumeration for enumerating the notations. The enumeration returns notation objects.

Syntax

public final Enumeration notationDeclarations();

Return Value

Returns a notation enumerator.


save (DTD Class)

 Microsoft SDK for Java

save

This method of the DTD class saves the DTD information to the given XML output stream.

Syntax

public final void save(XMLOutputStream o) throws IOException;

Parameters

o The output stream to write to.

Exceptions

IOException if there are problems writing to the output stream.


ElementDecl Class (com.ms.xml.parser Package)

 Microsoft SDK for Java

ElementDecl Class

The ElementDecl class of the com.ms.xml.parser package represents an element declaration in an XML Document Type Definition (DTD).

public class ElementDecl extends ElementImpl
{
  // Methods
  public final AttDef findAttDef(Name name);
  public final ContentModel getContent();
  public final Name getName();
  public void save(XMLOutputStream o) throws IOException;
  public Element toSchema();
}

Hierarchy

ElementImpl
  |
  +--ElementDecl


Methods (ElementDecl Class)

 Microsoft SDK for Java

ElementDecl Class Methods

The ElementDecl class contains the following methods:

findAttDef retrieves the attribute definition of the named attribute.
getContent retrieves the content model object for the element declaration.
getName retrieves the name of the element declaration.
save saves the element declaration in DTD syntax to the given output stream.
toSchema retrieves the XML-DATA specification for the DTD element.


findAttDef (ElementDecl Class)

 Microsoft SDK for Java

findAttDef

This method of the ElementDecl class retrieves the attribute definition of the named attribute.

Syntax

public final AttDef findAttDef(Name name);

Return Value

Returns an attribute definition object; returns null if it is not found.

Parameters

name The name of the attribute.


getContent (ElementDecl Class)

 Microsoft SDK for Java

getContent

This method of the ElementDecl class retrieves the content model object for the element declaration.

Syntax

public final ContentModel getContent();

Return Value

Returns the content model for the element.


getName (ElementDecl Class)

 Microsoft SDK for Java

getName

This method of the ElementDecl class retrieves the name of the element declaration.

Syntax

public final Name getName();

Return Value

Returns the Name object containing the element declaration name.


save (ElementDecl Class)

 Microsoft SDK for Java

save

This method of the ElementDecl class saves the element declaration in DTD syntax to the given output stream.

Syntax

public void save(XMLOutputStream o) throws IOException;

Parameters

o The output stream to write to.

Exceptions

IOException if there is a problem writing to the output stream.


toSchema (ElementDecl Class)

 Microsoft SDK for Java

toSchema

This method of the ElementDecl class retrieves the XML-DATA specification for the DTD element.

Syntax

public Element toSchema();

Return Value

Returns the element content.


ElementDeclEnumeration Class (com.ms.xml.parser Package)

 Microsoft SDK for Java

ElementDeclEnumeration Class

The ElementDeclEnumeration class of the com.ms.xml.parser package is a simple enumeration for iterating over element declarations.

public class ElementDeclEnumeration implements Enumeration
{
  // Constructors
  public ElementDeclEnumeration(Enumeration elemDecls);
  public ElementDeclEnumeration(Element e);

  // Methods
  public boolean hasMoreElements();
  public Object nextElement();
}


Entity Class (com.ms.xml.parser Package)

 Microsoft SDK for Java

Entity Class

The Entity class of the com.ms.xml.parser package implements an Entity object representing an XML internal or external entity as defined in the XML Document Type Definition (DTD).

public class Entity extends ElementImpl
{
  // Methods
  public Object getAttribute(Name attName);
  public Enumeration getAttributes();
  public Name getName();
  public Name getTagName();
  public void save(XMLOutputStream o) throws IOException;
  public void saveEntity(XMLOutputStream o) throws IOException;
  public void setText(String text);
}

Hierarchy

ElementImpl
  |
  +--Entity


Methods (Entity Class)

 Microsoft SDK for Java

Entity Class Methods

The Entity class contains the following methods:

getAttribute retrieves a specified attribute within an ElementImpl set.
getAttributes retrieves all attributes within an ElementImpl set.
getName retrieves the name of the entity.
getTagName retrieves the tag name from an external (system) or internal entity declaration.
save saves the entity to the given output stream with indenting and new lines.
saveEntity saves the entity to the given output stream.
setText changes the text of the entity.


getAttribute (Entity Class)

 Microsoft SDK for Java

getAttribute

This method of the Entity class retrieves a specified attribute within an ElementImpl set.

Syntax

public Object getAttribute(Name attName);

Return Value

Returns the specified attribute.

Parameters

attName The specified attribute.


getAttributes (Entity Class)

 Microsoft SDK for Java

getAttributes

This method of the Entity class retrieves all attributes within an ElementImpl set.

Syntax

public Enumeration getAttributes();

Return Value

Returns an enumeration of all attributes within the ElementImpl set.


getName (Entity Class)

 Microsoft SDK for Java

getName

This method of the Entity class retrieves the name of the entity.

Syntax

public Name getName();

Return Value

Returns the Name object containing the entity name.


getTagName (Entity Class)

 Microsoft SDK for Java

getTagName

This method of the Entity class retrieves the tag name from an external (system) or internal entity declaration.

Syntax

public Name getTagName();

Return Value

If the boolean sys variable is true, returns the tag name for an external entity declaration. Otherwise, returns the tag name for an internal entity declaration.


save (Entity Class)

 Microsoft SDK for Java

save

This method of the Entity class saves the entity to the given output stream with indenting and new lines.

Syntax

public void save(XMLOutputStream o) throws IOException;

Parameters

o The output stream.

Exceptions

IOException if there is a problem writing to the output stream.


saveEntity (Entity Class)

 Microsoft SDK for Java

saveEntity

This method of the Entity class saves the entity to the given output stream.

Syntax

public void saveEntity(XMLOutputStream o) throws IOException;

Parameters

o The output stream.

Exceptions

IOException if there is a problem writing to the output stream.


setText (Entity Class)

 Microsoft SDK for Java

setText

This method of the Entity class changes the text of the entity.

Syntax

public void setText(String text);

Parameters

text The new text of the entity.


Notation Class (com.ms.xml.parser Package)

 Microsoft SDK for Java

Notation Class

The Notation class of the com.ms.xml.parser package implements an entity object representing an XML notation.

public class Notation extends ElementImpl
{
  // Methods
  public void save(XMLOutputStream o) throws IOException;
  public Element toSchema();
}

Hierarchy

ElementImpl
  |
  +--Notation


Methods (Notation Class)

 Microsoft SDK for Java

Notation Class Methods

The Notation class contains the following methods:

save saves the notation to the given output stream with indenting and new lines.
toSchema retrieves the XML-DATA specification for the DTD element.


save (Notation Class)

 Microsoft SDK for Java

save

This method of the Notation class saves the notation to the given output stream with indenting and new lines.

Syntax

public void save(XMLOutputStream o) throws IOException;

Parameters

o The output stream.

Exceptions

IOException if there is a problem writing to the output stream.


toSchema (Notation Class)

 Microsoft SDK for Java

toSchema

This method of the Notation class retrieves the XML-DATA specification for the DTD element.

Syntax

public Element toSchema();

Return Value

Returns the element content.


ParseException Class (com.ms.xml.parser Package)

 Microsoft SDK for Java

ParseException Class

The ParseException class of the com.ms.xml.parser package signals that a parsing exception of some sort has occurred.

public class ParseException extends Exception
{
  // Fields
  public int column;
  public int line;
  public Object owner;

  // Constructors
  public ParseException();
  public ParseException(String s);
  public ParseException(String s, int line, int column,
        Object owner);
}

Hierarchy

Exception
  |
  +--ParseException


Constructors (ParseException Class)

 Microsoft SDK for Java

ParseException Class Constructors

The ParseException class contains the following constructors:

ParseException()
ParseException(String s)
ParseException(String s, int line, int column, Object owner)

ParseException()

Constructs a ParseException exception with no detail message.

Syntax

public ParseException();

ParseException(String s)

Constructs a ParseException exception with a specified message.

Syntax

public ParseException(String s);

Parameters

s The detail message.

ParseException(String s, int line, int column, Object owner)

Constructs a ParseException exception with detail about what occurred.

Syntax

public ParseException(String s, int line, int column, Object owner);

Parameters

s | The detail message.
line | The line number of the input where the error was found.
column | The position on the line.
owner | The context in which the error was encountered. This is either an Entity object or a Parser object.


Fields (ParseException Class)

 Microsoft SDK for Java

ParseException Class Fields

The ParseException class contains the following fields.

column | The position on the line where the error was found.
line | The line where the error was found.
owner | The parser context that the error occurred in.


Parser Class (com.ms.xml.parser Package)

 Microsoft SDK for Java

Parser Class

The Parser class of the com.ms.xml.parser package implements an eXtensible Markup Language (XML) parser according to the World Wide Web Consortium (W3C) working draft of the XML specification available at the time that Microsoft® Internet Explorer 4 was released. This Parser class is used internally by the XML document load method, so you shouldn't need to use it directly.

public class Parser
{
  // Constructors
  public Parser();

  // Methods
  public final XMLOutputStream createOutputStream(OutputStream out);
  public final void loadDTD(String urlStr, Atom nameSpace)
    throws ParseException;
  public final void parse(URL url, ElementFactory factory,
    DTD dtd, Element root, boolean caseInsensitive, boolean loadExt)
        throws ParseException;
  public final void parse(InputStream in, ElementFactory factory,
    DTD dtd, Element root, boolean caseInsensitive, boolean loadExt)
        throws ParseException;
  public final void report(ParseException e, OutputStream out);
  public void setShortEndTags(boolean shortendtags);
}


Constructors (Parser Class)

 Microsoft SDK for Java

Parser Class Constructors

The Parser class contains the following constructor:

Parser()

Creates a new parser object.

Syntax

public Parser();


Methods (Parser Class)

 Microsoft SDK for Java

Parser Class Methods

The Parser class contains the following methods:

createOutputStream creates an output stream that best matches the XML data format found during parsing.
loadDTD loads a DTD given its URL and namespace.
parse parses the XML document pointed to by the given URL and creates the corresponding XML document hierarchy.
report reports errors to the specified output stream including parsing context and stack trace where the error occurred.
setShortEndTags determines whether to allow short end tags.


createOutputStream (Parser Class)

 Microsoft SDK for Java

createOutputStream

This method of the Parser class creates an output stream that best matches the XML data format found during parsing. For example, this will match big endian or little endian XML data formats.

Syntax

public final XMLOutputStream createOutputStream(OutputStream out);

Return Value

Returns an XMLOutputStream object that uses the newline separator defined by the system property "line.separator".

Parameters

out The output stream.


loadDTD (Parser Class)

 Microsoft SDK for Java

loadDTD

This method of the Parser class loads a DTD given its URL and namespace.

Syntax

public final void loadDTD(String urlStr, Atom nameSpace) throws ParseException;

Parameters

urlStr | A string representing the URL that contains the DTD.
nameSpace | The namespace that contains the DTD.

Exceptions

ParseException if a string is incorrectly formatted and cannot be parsed.


parse (Parser Class)

 Microsoft SDK for Java

parse

The parse method of the Parser class contains the following signatures:

parse(URL url, ElementFactory factory, DTD dtd, Element root, boolean caseInsensitive, boolean loadExt)
parse(InputStream in, ElementFactory factory, DTD dtd, Element root, boolean caseInsensitive, boolean loadExt)

parse(URL url, ElementFactory factory, DTD dtd, Element root, boolean caseInsensitive, boolean loadExt)

Parses the XML document pointed to by the given URL and creates the corresponding XML document hierarchy.

Syntax

public final void parse(URL url, ElementFactory factory, DTD dtd, Element root, boolean caseInsensitive, boolean loadExt) throws ParseException;

Parameters

url | The URL address of the XML document to parse.
factory | The element factory used to create XML Element objects during parsing.
dtd | The object that the parser stores DTD information in.
root | The starting root node that children are added to during parsing.
caseInsensitive | Specifies whether the document is case-insensitive.
loadExt | Specifies whether to load external DTDs.

Exceptions

com.ms.xml.parser.ParseException if syntax or other errors are encountered.

parse(InputStream in, ElementFactory factory, DTD dtd, Element root, boolean caseInsensitive, boolean loadExt)

Parses the XML from the given input stream.

Syntax

final public void parse(InputStream in, ElementFactory factory, DTD dtd, Element root, boolean caseInsensitive, boolean loadExt) throws ParseException;

Parameters

in | The input stream containing XML data to parse.
factory | The element factory used to create XML Element objects during parsing.
dtd | The object that the parser stores DTD information in.
root | The starting root node that children are added to during parsing.
caseInsensitive | Specifies whether the document is case-insensitive.
loadExt | Specifies whether to load external DTDs.

Exceptions

com.ms.xml.parser.ParseException if syntax or other errors are encountered.


report (Parser Class)

 Microsoft SDK for Java

report

This method of the Parser class reports errors to the specified output stream, including parsing context and stack trace where the error occurred.

Syntax

final public void report(ParseException e, OutputStream out);

Parameters

e | The exception to report.
out | The output stream to write the report to.


setShortEndTags (Parser Class)

 Microsoft SDK for Java

setShortEndTags

This method of the Parser class determines whether to allow short end tags.

XML allows you to end a tag with a "/>". This signals that the element has no contents, and does not have an end tag. For example,

<title/>

is equivalent to

<title></title>

setShortEndTags turns this feature on or off.

Syntax

public void setShortEndTags(boolean shortendtags);

Parameters

shortendtags Enables short end tags.


com.ms.xml.util Package Overview

Microsoft Packages Overview

The com.ms.xml.util package provides base classes for Microsoft® XML object technology, including input and output stream objects specifically designed for XML.

This package contains the following:

Classes

Hierarchy


classes (com.ms.xml.util Package)

 Microsoft SDK for Java

com.ms.xml.util Package Classes

The com.ms.xml.util package contains the following classes:

Atom class allows efficient sharing of duplicate strings in the system.

Attribute class encapsulates a Microsoft® XML Name and value pair.

Attributes class encapsulates a list of Attribute objects.

EnumWrapper class is a simple implementation of the Enumeration interface.

Name class represents a general-purpose Name object; it is used for efficient sharing of duplicate strings in the system.

NameSpaceContext class adds or finds a namespace.

ReadOnlyAttributes class encapsulates a read-only list of Attribute objects.

StringHashtable class adds objects to the hash table and gets values from the hash table.

StringInputStream class takes input from the characters of a specified String object.

XMLInputStream class is an input stream reader, specifically designed to handle different encoding formats as well as little endian files.

XMLOutputStream class is an output stream writer specifically designed for eXtended Markup Language (XML), including XML encoding as well as little endian files, XML namespaces, and white-space handling.


com.ms.xml.util Package Interfaces

The com.ms.xml.util package contains the following interface:

XMLStreamReader interface reads XML streams and translates them into characters according to a specified character encoding.


Hierarchy (com.ms.xml.util Package)

 Microsoft SDK for Java

com.ms.xml.util Package Hierarchy

The com.ms.xml.util package has the following hierarchy:

Object
  |
  +--Attribute
  |
  +--Atom
  |
  +--EnumWrapper (Enumeration)
  |
  +--Name
  |
  +--NameSpaceContext
  |
  +--ReadOnlyAttributes
  |  |
  |  +--Attributes
  |
  +--StringHashtable

OutputStream
  |
  +--XMLOutputStream

InputStream
  |
  +--XMLInputStream
  |
  +--StringInputStream

XMLStreamReader


Atom class (com.ms.xml.util Package)

 Microsoft SDK for Java

Atom Class

The Atom class of the com.ms.xml.util package creates a global hash table of all atoms that have been constructed. This general-purpose object allows efficient sharing of duplicate strings in the system.

public class Atom
{
  // Methods
  public static Atom create(String s);
  public int hashCode();
  public String toString();
  public boolean equals(Object that);
}


Methods (Atom class)

 Microsoft SDK for Java

Atom Class Methods

The Atom class has the following methods:

create creates an atom object for the specified string.
equals specifies whether two specified atoms are equal.
hashCode converts an atom name string into a hash code.
toString returns the string represented by the atom.


create (Atom class)

 Microsoft SDK for Java

create

This method of the Atom class creates an atom object for the specified string. Atoms are case-sensitive and assume that all case folding has been done.

Syntax

public static Atom create(String s);

Parameters

s The string to create an Atom object for.


equals (Atom class)

 Microsoft SDK for Java

equals

This method of the Atom class specifies whether two specified atoms are equal.

Syntax

public boolean equals(Object that);

Return Value

Returns true if the atoms are equal; returns false if the atoms are not equal.

Parameters

that An atom object to be compared with the atom object invoking the equals( ) method.


hashCode (Atom class)

 Microsoft SDK for Java

hashCode

This method of the Atom class converts the atom name given by the String argument of the create( ) method into a hash code.

Syntax

public int hashCode();

Return Value

Returns the hash code for the atom name.


toString (Atom class)

 Microsoft SDK for Java

toString

This method of the Atom class returns the string represented by the atom.

Syntax

public String toString();

Return Value

Returns s, the string represented by the atom.


Attribute class (com.ms.xml.util Package)

 Microsoft SDK for Java

Attribute Class

The Attribute class of the com.ms.xml.util package encapsulates an XML Name and value pair.

public class Attribute
{
  // Constructors
  public Attribute();
  public Attribute(Name n, Object v);

  // Methods
  public Name getName();
  public Object getValue();
}


Constructors (Attribute class)

 Microsoft SDK for Java

Attribute Class Constructors

The Attribute class contains the following constructors:

Attribute()
Attribute(Name n, Object v)

Attribute()

Constructs an uninitialized Attribute.

Syntax

public Attribute();

Attribute(Name n, Object v)

Constructs an Attribute with given Name and associated value object.

Syntax

public Attribute(Name n, Object v);

Parameters

n | The name of the Attribute pair.
v | The value object to associate with the name.


Methods (Attribute class)

 Microsoft SDK for Java

Attribute Class Methods

The Attribute class contains the following methods:

getName retrieves the Name of the Attribute object.
getValue retrieves the value object of the Attribute.


getName (Attribute class)

 Microsoft SDK for Java

getName

This method of the Attribute class retrieves the Name of the Attribute object.

Syntax

public Name getName();

Return Value

Returns the name of the Attribute.


getValue (Attribute class)

 Microsoft SDK for Java

getValue

This method of the Attribute class retrieves the value object of the Attribute.

Syntax

public Object getValue();

Return Value

Returns the value of the Attribute.


Attributes class (com.ms.xml.util Package)

 Microsoft SDK for Java

Attributes Class

The Attributes class of the com.ms.xml.util package encapsulates a list of Attribute objects.

public class Attributes extends ReadOnlyAttributes
{
  // Constructors
  public Attributes();
  public Attributes(int elems);
  public Attributes(ReadOnlyAttributes attrs);
  public Attributes(Vector v);

  // Methods
  public Object put(Attribute v);
  public Object put(Name name, Object value);
  public void remove(Name name);
  public void removeAll();
}

Hierarchy

ReadOnlyAttributes
  |
  +--Attributes


Constructors (Attributes class)

 Microsoft SDK for Java

Attributes Class Constructors

The Attributes class contains the following constructors:

Attributes()
Attributes(int elems)
Attributes(ReadOnlyAttributes attrs)
Attributes(Vector v)

Attributes()

Constructs an empty Attribute collection.

Syntax

public Attributes();

Attributes(int elems)

Constructs an empty Attribute collection of a specified size. If you add more Attribute objects to it than the initially specified size, the collection grows automatically.

Syntax

public Attributes(int elems);

Parameters

elems The number of Attributes to initially reserve space for in the collection.

Attributes(ReadOnlyAttributes attrs)

Constructs a collection of Attribute objects from an existing collection of read-only Attribute objects.

Syntax

public Attributes(ReadOnlyAttributes attrs);

Parameters

attrs A read-only Attribute collection used to create the new Attributes object.

Attributes(Vector v)

Constructs an empty collection of Attribute objects using the specified Vector.

Syntax

public Attributes(Vector v);

Parameters

v The vector to use for the Attribute collection.


Methods (Attributes class)

 Microsoft SDK for Java

Attributes Class Methods

The Attributes class contains the following methods:

put adds an Attribute Name and value pair to the collection, or replaces the value for the named Attribute if it is already present in the collection.
remove removes the named Attribute from the collection.
removeAll removes all Attributes from the collection and sets the collection's size to 0 (zero).


put (Attributes class)

 Microsoft SDK for Java

put

This method of the Attributes class contains the following signatures:

put(Attribute v)
put(Name name, Object value)

put(Attribute v)

Adds an Attribute Name and value pair to the collection, or replaces the value for the named Attribute if it is already present in the collection.

Syntax

public Object put(Attribute v);

Return Value

Returns null if the Attribute was added to the collection; returns the previous value of the Attribute if the value was replaced.

Parameters

v The Attribute to add. If the Attribute is already present in the collection, its current value is replaced with that in the value parameter.

put(Name name, Object value)

Adds an Attribute Name and value pair to the collection, or replaces the value for the named Attribute if it is already present in the collection.

Syntax

public Object put(Name name, Object value);

Return Value

Returns null if the Attribute was added to the collection; returns the previous value of the Attribute if the value was replaced.

Parameters

name | The Name of the Attribute to add. If the Attribute is already present in the collection, its current value is replaced with that in the value parameter.
value | The object to associate with the Attribute.


remove (Attributes class)

 Microsoft SDK for Java

remove

This method of the Attributes class removes the named Attribute from the collection.

Syntax

public void remove(Name name);

Parameters

name The Name of the Attribute to remove from the collection.


removeAll (Attributes class)

 Microsoft SDK for Java

removeAll

This method of the Attributes class removes all Attributes from the collection and sets the collection's size to 0 (zero).

Syntax

public void removeAll();


EnumWrapper class (com.ms.xml.util Package)

 Microsoft SDK for Java

EnumWrapper Class

The EnumWrapper class of the com.ms.xml.util package is a simple implementation of the Enumeration interface. The EnumWrapper object generates a list of objects and accesses them through calls to the nextElement method.

public class EnumWrapper implements Enumeration
{
  // Constructors
  public EnumWrapper(Object o);

  // Methods
  public boolean hasMoreElements();
  public Object nextElement();
}


Constructors (EnumWrapper class)

 Microsoft SDK for Java

EnumWrapper Class Constructors

The EnumWrapper class contains the following constructor:

EnumWrapper(Object o)

Constructs an EnumWrapper from the specified base object.

Syntax

public EnumWrapper(Object o);

Parameters

o The object to create the EnumWrapper object from.


Methods (EnumWrapper class)

 Microsoft SDK for Java

EnumWrapper Class Methods

The EnumWrapper class contains the following methods:

hasMoreElements determines if there are elements remaining in the Enumeration.
nextElement retrieves the next object in the Enumeration.


hasMoreElements (EnumWrapper class)

 Microsoft SDK for Java

hasMoreElements

This method of the EnumWrapper class determines if there are elements remaining in the Enumeration.

Syntax

public boolean hasMoreElements();

Return Value

Returns true if the EnumWrapper contains more elements; otherwise, returns false.


nextElement (EnumWrapper class)

 Microsoft SDK for Java

nextElement

This method of the EnumWrapper class retrieves the next object in the enumeration.

Syntax

public Object nextElement();

Return Value

Returns the next object in the enumeration.


Name class (com.ms.xml.util Package)

 Microsoft SDK for Java

Name Class

The Name class of the com.ms.xml.util package allows efficient sharing of duplicate names in the system by creating a global hash table of all names. Names are different from Atoms in that they can be qualified by a separate namespace string. In effect, Names are compound Atoms.

public class Name
{
  // Methods
  public static Name create(String s);
  public static Name create(char val[], int offset, int len);
  public static Name create(String name, String ns);
  public static Name create(String name, Atom nameSpace);
  public boolean equals(Object that);
  public String getName();
  public Atom getNameSpace();
  public int hashCode();
  public String toString();
}


Methods (Name class)

 Microsoft SDK for Java

Name Class Methods

The Name class contains the following methods:

create constructs a Name object for an XML Attribute using the given string.
equals determines whether the current Name object is equal to the one passed in the that parameter.
getName retrieves a name.
getNameSpace retrieves a namespace.
hashCode retrieves the hash code for the Name.
toString retrieves a String representation of the class name of the Name object.


create (Name class)

 Microsoft SDK for Java

create

This method of the Name class contains the following signatures:

create(String s) creates an unqualified Name for an XML Attribute using the given string.
create(char val[], int offset, int len) creates an unqualified Name for an XML Attribute using the given array, offset, and length.
create(String name, String ns) creates a Name object for the given name and namespace.
create(String name, Atom nameSpace) creates a Name object for the given name and namespace where the name and Namespace are already Atoms.

create(String s)

Creates an unqualified Name object for an XML Attribute using the given string.

Syntax

public static Name create(String s);

Return Value

Returns a Name object.

Parameters

s The String object to create the Name with.

create(char val[], int offset, int len)

Creates an unqualified Name object for an XML Attribute using the given array, offset, and length.

Syntax

public static Name create(char val[], int offset, int len);

Return Value

Returns a Name object.

Parameters

val | A character array.
offset | The index of the first character of the array.
len | The array length.

create(String name, String ns)

Creates a Name object for the given name and namespace. The strings are case-sensitive.

Syntax

public static Name create(String name, String ns);

Return Value

Returns a Name object.

Parameters

name | The string representing the Name object to be added to the hash table.
ns | The namespace that defines the context in which the name was defined.

create(String name, Atom nameSpace)

Creates a Name object for the given name and namespace where the name and Namespace are already Atoms. The strings are case-sensitive.

Syntax

public static Name create(String name, Atom nameSpace);

Return Value

Returns a Name object.

Parameters

name | The string representing the Name object to be added to the hash table.
namespace | The namespace hash code.


equals (Name class)

 Microsoft SDK for Java

equals

This method of the Name class determines whether the current Name object is equal to the one passed in the that parameter.

Syntax

public boolean equals(Object that);

Return Value

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

Parameters

that The object to compare the Name object with.


getName (Name class)

 Microsoft SDK for Java

getName

This method of the Name class retrieves a name.

Syntax

public String getName();

Return Value

Returns a name string.


getNameSpace (Name class)

 Microsoft SDK for Java

getNameSpace

This method of the Name class retrieves a namespace.

Syntax

public Atom getNameSpace();

Return Value

Returns a namespace hash code.


hashCode (Name class)

 Microsoft SDK for Java

hashCode

This method of the Name class retrieves the hash code for the Name. A global hash table of all Name objects that have been constructed is used to share duplicate strings.

Syntax

public int hashCode();

Return Value

Returns the hash code for the Name.


toString (Name class)

 Microsoft SDK for Java

toString

This method of the Name class retrieves a String representation of the class name of the Name object.

Syntax

public String toString();

Return Value

Returns the class name of the Name object.


NameSpaceContext Class

The NameSpaceContext class of the com.ms.xml.util package adds or finds a namespace.

public class NameSpaceContext
{
  // Methods
  public final void addNameSpace(Atom url, Atom n);
  public final Atom findNameSpace(Atom n);
  public final void push();
  public final void pop();
}


Methods (NameSpaceContext class)

 Microsoft SDK for Java

NameSpaceContext Class Methods

The NameSpaceContext class contains the following methods:

addNameSpace adds a name space using the long name as the key.
findNameSpace finds a name space using the long name as the key.
pop retrieves the namespace last added to the stack.
push inserts a namespace onto the stack.


addNameSpace (NameSpaceContext class)

 Microsoft SDK for Java

addNameSpace

This method of the NameSpaceContext class adds a namespace using the long name as the key.

Syntax

public final void addNameSpace(Atom url, Atom n);

Parameters

url | The namespace that defines the context.
n | The name being written.


findNameSpace (NameSpaceContext class)

 Microsoft SDK for Java

findNameSpace

This method of the NameSpaceContext class finds a namespace using the prefix as the key.

Syntax

public final Atom findNameSpace(Atom n);

Return Value

Returns the namespace that contains the prefix.

Parameters

n The name to find.


pop (NameSpaceContext class)

 Microsoft SDK for Java

pop

This method of the NameSpaceContext class retrieves the namespace last added to the stack.

Syntax

public final void pop();


push (NameSpaceContext class)

 Microsoft SDK for Java

push

This method of the NameSpaceContext class inserts a namespace onto the stack.

Syntax

public final void push();


ReadOnlyAttributes class (com.ms.xml.util Package)

 Microsoft SDK for Java

ReadOnlyAttributes Class

The ReadOnlyAttributes class of the com.ms.xml.util package encapsulates a read-only list of Attribute objects.

public class ReadOnlyAttributes
{
  // Constructors
  public ReadOnlyAttributes();
  public ReadOnlyAttributes(Vector v);
  public ReadOnlyAttributes(int elems);

  // Methods
  public Enumeration attributes();
  public Object get(Name name);
  public Attribute lookup(Name name);
  public int size();
  public String toString();
}


Constructors (ReadOnlyAttributes class)

 Microsoft SDK for Java

ReadOnlyAttributes Class Constructors

The ReadOnlyAttributes class contains the following constructors:

ReadOnlyAttributes()
ReadOnlyAttributes(Vector v)
ReadOnlyAttributes(int elems)

ReadOnlyAttributes()

Constructs an empty read-only Attribute collection.

Syntax

public ReadOnlyAttributes();

ReadOnlyAttributes(Vector v)

Constructs a read-only collection of Attribute objects using the given Vector of Attributes.

Syntax

public ReadOnlyAttributes(Vector v);

Parameters

v The Vector that contains the Attribute objects.

ReadOnlyAttributes(int elems)

Constructs an empty Attribute collection of the specified size. If you add more Attribute objects to the collection than the initially specified size, it grows automatically.

Syntax

public ReadOnlyAttributes(int elems);

Parameters

elems The number of Attribute objects to initially reserve space for in the collection.


Methods (ReadOnlyAttributes class)

 Microsoft SDK for Java

ReadOnlyAttributes Class Methods

The ReadOnlyAttributes class contains the following methods:

attributes retrieves an Enumeration of the Attribute objects in the collection.
get retrieves the named Attribute object and returns its associated value.
lookup cycles through the collection of Attribute objects and retrieves the named Attribute, if it is present.
size retrieves the number of Attribute Name and value pairs that are currently in the collection.
toString retrieves a String representation of the class name of the ReadOnlyAttributes object.


attributes (ReadOnlyAttributes class)

 Microsoft SDK for Java

attributes

This method of the ReadOnlyAttributes class retrieves an Enumeration of the Attribute objects in the collection.

Syntax

public Enumeration attributes();

Return Value

Returns an Enumeration of the Attribute objects in the collection.


get (ReadOnlyAttributes class)

 Microsoft SDK for Java

get

This method of the ReadOnlyAttributes class retrieves the named Attribute object and returns its associated value.

Syntax

public Object get(Name name);

Return Value

Returns an object that is the associated value for the named Attribute.

Parameters

name A Name object that identifies the Attribute to retrieve.


lookup (ReadOnlyAttributes class)

 Microsoft SDK for Java

lookup

This method of the ReadOnlyAttributes class cycles through the collection of Attribute objects and retrieves the named Attribute, if it is present.

Syntax

public Attribute lookup(Name name);

Return Value

Returns the named Attribute; returns null if the Attribute is not currently included in the collection.

Parameters

name The Name of the Attribute to retrieve.


size (ReadOnlyAttributes class)

 Microsoft SDK for Java

size

This method of the ReadOnlyAttributes class retrieves the number of Attribute Name and value pairs that are currently in the collection.

Syntax

public int size();

Return Value

Returns the number of pairs in the collection.


toString (ReadOnlyAttributes class)

 Microsoft SDK for Java

toString

This method of the ReadOnlyAttributes class retrieves a String representation of the class name of the ReadOnlyAttributes object.

Syntax

public String toString();

Return Value

Returns the class name for the ReadOnlyAttributes object.


StringHashtable class (com.ms.xml.util package)

 Microsoft SDK for Java

StringHashtable Class

The StringHashtable class of the com.ms.xml.util package adds objects to the hash table and gets values from the hash table.

public class StringHashtable
{
  // Constructors
  public StringHashtable(int size);

  // Methods
  public Object put(String key, Object value);
  public Object get(String key);
  public Object get(char chars[], int offset, int length);
}


Constructors (StringHashtable class)

 Microsoft SDK for Java

StringHashtable Class Constructors

The StringHashtable class contains the following constructor:

StringHashtable(int size)

Constructs an empty hash table of the specified initial capacity.

Syntax

public StringHashtable(int size);

Parameters

size The initial capacity of the hash table.


Methods (StringHashtable class)

 Microsoft SDK for Java

StringHashtable Class Methods

The StringHashtable class contains the following methods:

get gets a value from the hash table.
put maps the specified key to the specified value in this hash table.


get (StringHashtable class)

 Microsoft SDK for Java

get

The get method of the StringHashtable class has the following signatures:

get(String key)
get(char chars[], int offset, int length);

get(String key)

Gets a hash table value by using the hash table key.

Syntax

public Object get(String key);

Parameters

key A hash table key.

get(char chars[], int offset, int length)

Gets a hash table value that contains characters from a subarray of the char argument.

Syntax

public Object get(char chars[], int offset, int length);

Parameters

chars[] | A subarray.
offset | The index of the first character of the subarray.
length | The subarray length.


put (StringHashtable class)

 Microsoft SDK for Java

put

This method of the StringHashtable class maps the specified key to the specified value in this hash table.

Syntax

public Object put(String key, Object value);

Parameters

key | A hash table key.
value | The value the key is mapped to.


StringInputStream class (com.ms.xml.util Package)

 Microsoft SDK for Java

StringInputStream Class

The StringInputStream class of the com.ms.xml.util package takes input from the characters of a specified String object.

public class StringInputStream extends java.io.InputStream
{
  // Constructors
  public StringInputStream(String text);

  // Methods
  public int read() throws IOException;
}


Constructors (StringInputStream class)

 Microsoft SDK for Java

StringInputStream Class Constructors

The StringInputStream class contains the following constructor:

StringInputStream(String text)

Initializes the stream with the given string object.

Syntax

public StringInputStream(String text);

Parameters

text The string that initializes the buffer contents.


Methods (StringInputStream class)

 Microsoft SDK for Java

StringInputStream Class Methods

The StringInputStream class contains the following method:

read reads the next byte of data from this input stream.


read (StringInputStream class)

 Microsoft SDK for Java

read

This method of the StringInputStream class reads the next byte of data from this input stream.

Syntax

public int read() throws IOException;

Return Value

Returns the next byte of data, or -1 if the end of the stream is reached.

Exceptions

Throws IOException if an I/O error occurs.


XMLInputStream class (com.ms.xml.util Package)

 Microsoft SDK for Java

XMLInputStream Class

The XMLInputStream class of the com.ms.xml.util package is an input stream reader, specifically designed to handle different encoding formats and little endian files.

public class XMLInputStream extends InputStream
{
  // Constructors
  public XMLInputStream(InputStream in);
  public XMLInputStream(URL url) throws IOException;

  // Methods
  public void close() throws IOException;
  public XMLOutputStream createOutputStream(OutputStream out);
  public int read() throws IOException;
  public void setEncoding(String encoding) throws IOException;

  // Fields
  public boolean caseInsensitive;
}

Hierarchy

InputStream
  |
  +--XMLInputStream


Constructors (XMLInputStream class)

 Microsoft SDK for Java

XMLInputStream Class Constructors

The XMLInputStream class contains the following constructors:

XMLInputStream(InputStream in)

Constructs an XMLInputStream object from an InputStream. The first four bytes of the InputStream are read to determine the character encoding of the file. The XMLInputStream object does not ensure that the input stream follows the XML standard, and expects any non-UTF-8 file to begin with an <?XML> tag.

Syntax

public XMLInputStream(InputStream in);

Parameters

in The input stream to base the XMLInputStream object on.

XMLInputStream(URL url)

Constructs an XMLInputStream object from a URL object. Call this constructor to speed up Microsoft® Win32® input speed. The decoding is done by IXMLStream.

This constructor relies on the CXMLStream class in xmlurlstream.dll.

Syntax

public XMLInputStream(URL url) throws IOException;

Exception

IOException if xmlurlstream.dll or xmlurlstream.tlb is not properly registered on the system, or the encoding of the input stream cannot be handled.

Parameters

url The URL object to create the XMLInputStream object from.


Methods (XMLInputStream class)

 Microsoft SDK for Java

XMLInputStream Class Methods

The XMLInputStream class contains the following methods:

close closes the stream and releases system resources.
createOutputStream constructs an XMLOutputStream with the appropriate initial state.
read retrieves the next Unicode character in the input stream.
setEncoding defines the character encoding of the input stream.


close (XMLInputStream class)

 Microsoft SDK for Java

close

This method of the XMLInputStream class closes the stream and releases system resources.

Syntax

public void close() throws IOException;

Exceptions

IOException if the stream cannot be closed.


createOutputStream (XMLInputStream class)

 Microsoft SDK for Java

createOutputStream

This method of the XMLInputStream class constructs an XMLOutputStream with the appropriate initial state. XMLOutputStream objects should always be created using this method for the output stream to mimic the input stream.

Syntax

public XMLOutputStream createOutputStream(OutputStream out);

Return Value

Returns a correctly initialized XMLOutputStream for use with the current XMLInputStream.

Parameters

out The output stream to base the XMLOutputStream object on.


read (XMLInputStream class)

 Microsoft SDK for Java

read

This method of the XMLInputStream class retrieves the next Unicode character in the input stream. The read operation performed depends on the current read state.

Syntax

public int read() throws IOException;

Return Value

Returns the next Unicode character in the stream.

Exceptions

IOException if an I/O error occurs.


setEncoding (XMLInputStream class)

 Microsoft SDK for Java

setEncoding

This method of the XMLInputStream class defines the character encoding of the input stream.

Syntax

public void setEncoding(String encoding) throws IOException;

Parameters

encoding The type of character encoding. This can be one of the following formats:
  1. UTF-8

  2. Shift_JIS

  3. ISO-8859-1

  4. ISO-10646-UCS-4 (not yet supported)

  5. ISO-10646-UCS-2 or UCS-2

The default character encoding is ASCII.

Remarks

The character encoding must agree with the encoding determined by the constructor. The setEncoding method is used to clarify encodings that cannot be fully determined by reading the first four bytes in a stream. setEncoding is not used to change the encoding of a stream. It must be called within 4096 read() operations after the XMLInputStream object's creation.

Exceptions

IOException if the encoding type is not supported by the currently installed virtual machine.


Fields (XMLInputStream class)

 Microsoft SDK for Java

XMLInputStream Class Fields

The XMLInputStream class has the following field:

caseInsensitive Specifies whether the document to be parsed is case-insensitive. If so, all names are folded to upper case. Default is false.


XMLOutputStream class (com.ms.xml.util Package)

 Microsoft SDK for Java

XMLOutputStream Class

The XMLOutputStream class of the com.ms.xml.util package is an output stream writer that is specifically designed for XML including XML encoding, little endian files, XML namespaces, and white-space handling.

public class XMLOutputStream extends OutputStream
{
  // Fields
  public static int COMPACT;
  public DTD dtd;
  public boolean mixed;
  public NameSpaceContext nameSpaceContext;
  public static int PRETTY;
  public boolean savingDTD;

  // Constructors
  public XMLOutputStream(OutputStream out);

  // Methods
  public void addIndent(int offset);
  public void close() throws IOException;
  public void flush() throws IOException;
  public int getOutputStyle();
  public void setEncoding(String encoding, boolean littleendian,
        boolean byteOrderMark) throws IOException;
  public void setOutputStyle(int style);
  public void write(int c) throws IOException;
  public void writeChars(String str) throws IOException;
  public void writeIndent() throws IOException;
  public void writeNewLine() throws IOException;
  public void writeQualifiedName(Name n, Atom ns) throws IOException;
  public void writeQuotedString(String str) throws IOException;
}

Hierarchy

OutputStream
  |
  +--XMLOutputStream


Constructors (XMLOutputStream class)

 Microsoft SDK for Java

XMLOutputStream Class Constructors

The XMLOutputStream class contains the following constructor:

XMLOutputStream(OutputStream out)

Constructs the XMLOutputStream object as a standard UTF-8 output stream. A subsequent call to the setEncoding method will specify the correct character encoding that is required. Create an XMLOutputStream by using the createOutputStream method of the XMLInputStream class.

Syntax

public XMLOutputStream(OutputStream out);

Parameters

out An output stream to use to create the XMLOutputStream.


Methods (XMLOutputStream class)

 Microsoft SDK for Java

XMLOutputStream Class Methods

The XMLOutputStream class contains the following methods:

addIndent sets the relative indentation level (for example, addIndent(+1) or addIndent(-1)).
close closes the XMLOutputStream and frees any system resources that are associated with the stream.
flush flushes the XMLOutputStream.
getOutputStyle retrieves the current output style for the output stream.
setEncoding defines the character encoding of the output stream.
setOutputStyle sets the output style for the output stream.
write writes a character to the output stream according to the current write state.
writeChars writes the given string to the output stream.
writeIndent writes the appropriate indent according to the indentation level that is specified by the addIndent method.
writeNewLine writes a new line.
writeQualifiedName writes out the fully qualified name using the appropriate short name syntax.
writeQuotedString writes out the string enclosed in quotation marks.


addIndent (XMLOutputStream class)

 Microsoft SDK for Java

addIndent

This method of the XMLOutputStream class sets the relative indentation level (for example, addIndent(+1) or addIndent(-1)). The indent level controls what the writeIndent writes.

Syntax

public void addIndent(int offset);

Parameter

offset A signed value for the indentation level.


close (XMLOutputStream class)

 Microsoft SDK for Java

close

This method of the XMLOutputStream class closes the XMLOutputStream and frees any system resources that are associated with the stream.

Syntax

public void close() throws IOException;

Exceptions

IOException if an I/O error occurs.


flush (XMLOutputStream class)

 Microsoft SDK for Java

flush

This method of the XMLOutputStream class flushes the XMLOutputStream.

Syntax

public void flush() throws IOException;

Exceptions

IOException if an I/O error occurred.


getOutputStyle (XMLOutputStream class)

 Microsoft SDK for Java

getOutputStyle

This method of the XMLOutputStream class retrieves the current output style for the output stream.

Syntax

public int getOutputStyle();

Return Value

Returns either the COMPACT or the PRETTY output style.


setEncoding (XMLOutputStream class)

 Microsoft SDK for Java

setEncoding

This method of the XMLOutputStream class defines the character encoding of the output stream.

Syntax

public void setEncoding(String encoding, boolean littleendian, boolean byteOrderMark) throws IOException;

Parameters

encoding The type of character encoding. This can be one of the following formats:
  1. UTF-8

  2. Shift_JIS

  3. ISO-8859-1

  4. ISO-10646-UCS-4 (not yet supported)

  5. UCS-2

The default character encoding is ASCII.
littleendian | Set this parameter to true to specify whether the stream is in little endian format.
byteOrderMark | This flag is only relevant if the character encoding type is UCS-2. Otherwise, it is ignored.

Exceptions

IOException if the encoding type is not supported by the currently installed virtual machine.


setOutputStyle (XMLOutputStream class)

 Microsoft SDK for Java

setOutputStyle

This method of the XMLOutputStream class sets the output style for the output stream.

Syntax

public void setOutputStyle(int style);

Parameters

style The output style. This can be either PRETTY or COMPACT.


write (XMLOutputStream class)

 Microsoft SDK for Java

write

This method of the XMLOutputStream class writes a character to the output stream according to the current write state. To avoid an extra conditional in every UCS-2 write, an extra state is used for a UCS-2 write operation that requires a ByteOrderMark. The ByteOrderMark is written only once at the beginning of the file.

Syntax

public void write(int c) throws IOException;

Parameters

c The character to write to the output stream.

Exceptions

IOException if there was an error writing to the stream.


writeChars (XMLOutputStream class)

 Microsoft SDK for Java

writeChars

This method of the XMLOutputStream class writes the given string to the output stream.

Syntax

public void writeChars(String str) throws IOException;

Parameters

str The String to write to the output stream.

Exceptions

IOException if there was an error writing to the output stream.


writeIndent (XMLOutputStream class)

 Microsoft SDK for Java

writeIndent

This method of the XMLOutputStream class writes the appropriate indent, according to the indentation level that is specified by the addIndent method. If the output style is COMPACT, the method performs no operation.

Syntax

public void writeIndent() throws IOException;

Exceptions

IOException if there was an error writing to the output stream.


writeNewLine (XMLOutputStream class)

 Microsoft SDK for Java

writeNewLine

This method of the XMLOutputStream class writes a new line. If the output style is COMPACT, the method performs no operation.

Syntax

public void writeNewLine() throws IOException;

Exceptions

IOException if there was an error writing to the output stream.


writeQualifiedName (XMLOutputStream class)

 Microsoft SDK for Java

writeQualifiedName

This method of the XMLOutputStream class writes out the fully qualified name, using the appropriate short name syntax.

Syntax

public void writeQualifiedName(Name n, Atom ns) throws IOException;

Parameters

n | The Name being written.
ns | The namespace that defines the context that the name was defined in.

Exceptions

IOException if there was an error writing to the stream.


writeQuotedString (XMLOutputStream class)

 Microsoft SDK for Java

writeQuotedString

This method of the XMLOutputStream class writes out the string enclosed in quotation marks. This method uses quotation marks that are appropriate for the string (for example, if a string contains a single quotation mark ('), the method uses a double quotation mark ("), and so on).

Syntax

public void writeQuotedString(String str) throws IOException;

Parameters

str The String to write to the output stream.

Exceptions

IOException if any exceptional condition occurs during input or output.


Fields (XMLOutputStream class)

 Microsoft SDK for Java

XMLOutputStream Class Fields

The XMLOutputStream class contains the fields shown in the following table.

COMPACT | An output style that specifies that no newline characters or tabs are used in the output stream.
dtd | Needed for saving in correct format.
mixed | Output styling.
nameSpaceContext | Needed for saving in correct format.
PRETTY | The default output style. New lines and tabs are used when writing to the output stream.
savingDTD | Specifies whether you are in the scope of saving a DTD.


XMLStreamReader Interface (com.ms.xml.util Package)

 Microsoft SDK for Java

XMLStreamReader Interface

The XMLStreamReader interface of the com.ms.xml.util package reads XML streams and translates them into characters according to a specified character encoding.

public interface XMLStreamReader
{
  // Methods
  public int open(String url);
  public int read(int[] buf, int len);
  public void setEncoding(int encoding, int offset);
  public void close();
}


Methods (XMLStreamReader interface)

 Microsoft SDK for Java

XMLStreamReader Interface Methods

The XMLStreamReader interface contains the following methods:

close closes the input stream.
open opens the input stream from a given URL.
read reads characters into a portion of an array.
setEncoding defines the character encoding of the input stream.


close (XMLStreamReader interface)

 Microsoft SDK for Java

close

This method of the XMLStreamReader interface closes the input stream.

Syntax

public void close();


open (XMLStreamReader interface)

 Microsoft SDK for Java

open

This method of the XMLStreamReader interface opens the input stream from a given URL.

Syntax

public int open(String url);

Parameters

url The URL containing the data to be read.


read (XMLStreamReader interface)

 Microsoft SDK for Java

read

This method of the XMLStreamReader interface reads characters into a portion of an array.

Syntax

public int read(int[] buf, int len);

Return Value

The number of characters read, or -1 if the end of the stream has been reached.

Parameters

buf | The destination buffer.
len | The maximum number of characters to read.


setEncoding (XMLStreamReader interface)

 Microsoft SDK for Java

setEncoding

This method of the XMLStreamReader interface defines the character encoding of the input stream.

Syntax

public void setEncoding(int encoding, int offset);

Parameters

encoding | The type of encoding.
offset | The starting offset in the input stream.


Debugger Interfaces Reference

This section describes the Java language debugger interfaces and their methods.

This reference contains the following sections:

Debugger Interfaces Hierarchy shows the inheritance of all Java language debugger interfaces.

Registration Debugger Interfaces register Java classes for debugging and to receive notification when new Java processes are created.

Notification Debugger Interfaces notify the debugger when new Java processes are created and when events occur on a specific Java process.

Static Information Debugger Interfaces represent fields that are class members, such as methods, objects, inner classes, or nested class definitions.

Dynamic Information Debugger Interfaces provide bound access to objects of different types.

Execution Control Debugger Interfaces provide access to the Java method call stacks of the threads executing in the Java process being debugged.

See Also

Debugger Interfaces Overview

Debugging and Profiling Java Applications (white paper)


Debugger Interfaces Hierarchy

The following hierarchy shows the inheritance of all Java language debugger interfaces, which all ultimately derive from IUnknown:

Registration Debugger Interfaces

IUnknown
  |
  +--IRemoteDebugManager
  |
  +--IEnumRemoteProcess
  |  |
  |  +--IJavaEnumRemoteProcess
  |
  +--IRemoteProcess
  |  |
  |  +--IRemoteProcessEx

Notification Debugger Interfaces

IUnknown
  |
  +--IRemoteDebugManagerCallback
  |  |
  |  +--IRemoteDebugManagerCallbackEx
  |
  +--IRemoteProcessCallback
  |  |
  |  +--IRemoteProcessCallbackEx
  |  |  |
  |  |  +--IRemoteProcessCallbackEx2

Static Information Debugger Interfaces

IUnknown
  |
  +--IRemoteField
  |  |
  |  +--IRemoteDataField
  |  |  |
  |  |  +--IRemoteArrayField
  |  |
  |  +--IRemoteContainerField
  |  |  |
  |  |  +--IRemoteClassField
  |  |  |  |
  |  |  |  +--IRemoteClassFieldEx
  |  |  |  |  |
  |  |  |  |  +--IRemoteInnerClassField
  |  |  |
  |  |  |  +--IRemotePrimitiveClassField
  |  |  |
  |  |  +--IRemoteMethodField
  |  |  |  |
  |  |  |  +--IRemoteMethodFieldEx
  |
  +--IEnumRemoteField
  |  |
  |  +--IJavaEnumRemoteField
  |
  +--IEnumLINEINFO
  |  |
  |  +--IJavaEnumLINEINFO

Dynamic Information Debugger Interfaces

IUnknown
  |
  +--IEnumXXXX : IUnknown
  |  |
  |  +--IJavaEnumXXXX : IEnumXXXX
  |
  +--IRemoteObject
  |  |
  |  +--IRemoteObjectEx
  |  |
  |  +--IRemoteBooleanObject
  |  |
  |  +--IRemoteByteObject
  |  |
  |  +--IRemoteCharObject
  |  |
  |  +--IRemoteContainerObject
  |  |  |
  |  |  +--IRemoteClassObject
  |  |
  |  +--IRemoteDoubleObject
  |  |
  |  +--IRemoteFloatObject
  |  |
  |  +--IRemoteIntObject
  |  |
  |  +--IRemoteLongObject
  |  |
  |  +--IRemoteShortObject
  |  |
  |  +--IRemoteXXXXObject
  |  |
  |  +--IRemoteArrayObject
  |
  +--IEnumRemoteObject
  |  |
  |  +--IJavaEnumRemoteObject
  |
  +--IEnumRemoteValue
  |  |
  |  +--IEnumRemoteBooleanValue
  |  |
  |  |  +--IJavaEnumRemoteBooleanValue
  |  |
  |  +--IEnumRemoteByteValue
  |  |
  |  |  +--IJavaEnumRemoteByteValue
  |  |
  |  +--IEnumRemoteCharValue
  |  |
  |  |  +--IJavaEnumRemoteCharValue
  |  |
  |  +--IEnumRemoteDoubleValue
  |  |
  |  |  +--IJavaEnumRemoteDoubleValue
  |  |
  |  +--IEnumRemoteFloatValue
  |  |
  |  |  +--IJavaEnumRemoteFloatValue
  |  |
  |  +--IEnumRemoteIntValue
  |  |
  |  |  +--IJavaEnumRemoteIntValue
  |  |
  |  +--IEnumRemoteLongValue
  |  |
  |  |  +--IJavaEnumRemoteLongValue
  |  |
  |  +--IEnumRemoteShortValue
  |  |
  |  |  +--IJavaEnumRemoteShortValue

Execution Control Debugger Interfaces

IUnknown
  |
  +--IEnumCodeBreakpoints
  |
  +--IEnumRemoteStackFrames
  |
  +--IEnumRemoteThread
  |  |
  |  +--IJavaEnumRemoteThread
  |
  +--IEnumRemoteThreadGroup
  |  |
  |  +--IJavaEnumRemoteThreadGroup
  |
  +--IRemoteStackFrame
  |  |
  |  +--IRemoteStackFrameEx
  |
  +--IRemoteThread
  |  |
  |  +--IRemoteThreadEx
  |  |  |
  |  |  +--IRemoteThreadEx2
  |
  +--IRemoteThreadGroup
  |  |
  |  +--IRemoteThreadGroupEx
  |
  +--IJITAttachDebugger


Registration Debugger Interfaces Overview

Debugger Interfaces Reference

Use these interfaces to register Java classes for debugging and to receive notification when new Java processes are created.

For general information, see Registering with the Debugger Manager in the Programmer's Guide.

This topic contains the following section:

Interfaces

Hierarchy


Registration Debugger Interfaces

The registration debugger interfaces are as follows:

IRemoteDebugManager obtains an enumerator for all the Java processes running on the system, and registers to debug a particular Java process.

IEnumRemoteProcess enumerates all Java processes currently running in the Microsoft VM.

IJavaEnumRemoteProcess enumerates IRemoteProcess pointers.

IRemoteProcess represents a Java process running under the Microsoft VM.

IRemoteProcessEx extends IRemoteProcess with three methods. It allows dynamically attached debuggers to get and set the debugger flags.


Registration Debugger Interfaces Hierarchy

The registration debugger interfaces have the following hierarchy:

IUnknown
  |
  +--IRemoteDebugManager
  |
  +--IEnumRemoteProcess
  |  |
  |  +--IJavaEnumRemoteProcess
  |
  +--IRemoteProcess
  |  |
  |  +--IRemoteProcessEx


IRemoteDebugManager : IUnknown

The IRemoteDebugManager interface obtains an enumerator for all the Java processes running on the system, and registers to debug a particular Java process. This interface is implemented by the Microsoft VM’s Debug Manager, which can be accessed using CLSID_RemoteJavaDebugManager.

  // Methods
  HRESULT Detach(void)
  HRESULT GetActiveProcesses(IJavaEnumRemoteProcess **ppEnum)
  HRESULT RegisterCallback(IRemoteDebugManagerCallback *pCallback)
  HRESULT RequestCreateEvent(LPCOLESTR pszProcessName,
    DWORD dwParentProcessId)


Methods (IRemoteDebugManager Interface)

 Microsoft SDK for Java

IRemoteDebugManager Interface Methods

The IRemoteDebugManager interface contains the following methods:

Detach is called by a debugger to detach its IRemoteDebugManagerCallback interface that was registered by a previous call to RegisterCallback.
GetActiveProcesses is called by a debugger to obtain an IJavaEnumRemoteProcess interface that can be used to enumerate all the running Java processes.
RegisterCallback is called by a debugger to register an IRemoteDebugManagerCallback interface for receiving notification when a requested Java process begins execution.
RequestCreateEvent is called by a debugger to notify the Microsoft VM’s Debug Manager that the debugger is interested in debugging a Java process, optionally specifying a particular Java class.


IRemoteDebugManager::Detach

 Microsoft SDK for Java

IRemoteDebugManager::
Detach

The Detach method of the IRemoteDebugManager interface detaches the IRemoteDebugManagerCallback interface that was registered by a previous call to RegisterCallback. This method should be called if the debugger exits before the Java process being debugged.

Syntax

HRESULT Detach(void)

Return Value

S_OK Success.

E_FAIL Failure.


IRemoteDebugManager::GetActiveProcesses

 Microsoft SDK for Java

IRemoteDebugManager::
GetActiveProcesses

The GetActiveProcesses method of the IRemoteDebugManager interface obtains an IJavaEnumRemoteProcess interface that can be used to enumerate all the running Java processes.

Note If you are logged on to Microsoft® Windows NT® under the system account, GetActiveProcesses may not enumerate all debuggable Java service processes. This is a DCOM security configuration issue, and is addressed in Enumerating Debuggable Service Processes.

Syntax

HRESULT GetActiveProcesses(IJavaEnumRemoteProcess **ppEnum)

Parameters

[out] ppEnum Returns an enumerator for all the running Java processes.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IRemoteDebugManager::RegisterCallback

 Microsoft SDK for Java

IRemoteDebugManager::
RegisterCallback

The RegisterCallback method of the IRemoteDebugManager interface is called by a debugger to register an IRemoteDebugManagerCallback interface for receiving notification when a requested Java process begins execution.

Syntax

HRESULT RegisterCallback(IRemoteDebugManagerCallback *pCallback)

Parameters

[in] pCallback The debugger’s callback interface that should receive notification when a requested Java process begins execution.

Return Value

S_OK Success.

E_FAIL A debugger callback is already registered.


IRemoteDebugManager::RequestCreateEvent

 Microsoft SDK for Java

IRemoteDebugManager::
RequestCreateEvent

The RequestCreateEvent method of the IRemoteDebugManager interface is called by a debugger to notify the Microsoft VM’s Debug Manager that the debugger is interested in debugging a Java process, optionally specifying a particular Java class.

Syntax

HRESULT RequestCreateEvent(LPCOLESTR pszProcessName, DWORD dwParentProcessId)

Parameters

[in] pszProcessName | The name of the Java class to debug, that is, an applet or application. The debugger can request debugging of any Java class by passing in an empty string ("").
[in] dwParentProcessId | The Win32 process ID of the Java process that the debugger wants to debug. The debugger can request debugging of the next Java process to begin execution by passing in 0xFFFFFFFF.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.

Remarks

The RequestCreateEvent method takes two parameters. The debugger can register to receive a notification when the next new Java process is created or when a specific Win32 process starts up the Microsoft VM. The debugger can also register to receive notification when the Microsoft VM in that process starts up, or to delay notification until a specific Java class is loaded in that process. There are four possible combinations of these two parameters. The debugger can pass 0xFFFFFFFF for dwParentProcessID to register to receive notifications for the next Java process that starts up. Any other value for dwParentProcessID indicates a specific Win32 process. The debugger can pass a zero-length string for pcszProcessName to register to receive notification as soon as the Microsoft VM starts up in that process. Any other value for pcszProcessName indicates a specific Java class that the debugger wants to wait for before receiving notification.


IEnumRemoteProcess : IUnknown

The IEnumRemoteProcess interface enumerates all Java processes currently running in the Microsoft VM. It is used primarily as the base class for IJavaEnumRemoteProcess.

  // Methods
  HRESULT Clone(IJavaEnumRemoteProcess **ppEnum)
  HRESULT Next(ULONG celt, IRemoteProcess *rgelt[],
    ULONG *pceltFetched)
  HRESULT Reset(void)
  HRESULT Skip(ULONG celt)


Methods (IEnumRemoteProcess Interface)

 Microsoft SDK for Java

IEnumRemoteProcess Interface Methods

The IEnumRemoteProcess interface contains the following methods:

Clone creates a copy of the enumerator, including the enumerator’s current position in its list of elements.
Next retrieves the next specified number of elements from the enumerator’s list.
Reset resets the enumerator’s current position in its list of elements to the first element in the list.
Skip moves the enumerator’s current position ahead in its list of elements by the given number of elements.


IEnumRemoteProcess::Clone

 Microsoft SDK for Java

IEnumREMOTEPROCESS::
Clone

The Clone method of the IEnumRemoteProcess interface creates a copy of the enumerator, including the enumerator’s current position in its list of elements.

Syntax

HRESULT Clone(IJavaEnumRemoteProcess **ppEnum)

Parameters

[out] ppEnum Returns a pointer to the copied enumerator.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IEnumRemoteProcess::Next

 Microsoft SDK for Java

IEnumRemoteProcess::
Next

The Next method of the IEnumRemoteProcess interface retrieves the next specified number of elements from the enumerator’s list.

Syntax

HRESULT Next(ULONG celt, IRemoteProcess rgelt[], ULONG *pceltFetched)

Parameters

[in] celt | The number of elements requested.
[length_is][size_is][out] rgelt | The array to be filled in with the elements.
[out] pceltFetched | The number of elements actually returned in rgelt. This can be less than celt if fewer than celt elements remained in the list.

Return Value

S_OK Celt elements were returned.

S_FALSE Fewer than celt elements were returned.


IEnumRemoteProcess::Reset

 Microsoft SDK for Java

IEnumRemoteProcess::
Reset

The Reset method of the IEnumRemoteProcess interface resets the enumerator’s current position in its list of elements to the first element in the list.

Syntax

HRESULT Reset(void)

Return Value

S_OK Success.


IEnumRemoteProcess::Skip

 Microsoft SDK for Java

IEnumRemoteProcess::
Skip

The Skip method of the IEnumRemoteProcess interface moves the enumerator’s current position ahead in its list of elements by the given number of elements.

Syntax

HRESULT Skip(ULONG celt)

Parameters

[in] celt The number of elements to be skipped.

Return Value

S_OK Celt elements were skipped.

S_FALSE Fewer than celt elements were skipped. Fewer than celt elements remained in the list.


IJavaEnumRemoteProcess : IEnumRemoteProcess

The IJavaEnumRemoteProcess interface enumerates IRemoteProcess pointers. It is used to enumerate Java processes running under the Microsoft virtual machine. This interface is implemented by the Microsoft VM. Note that unlike some other IJavaEnumXXXX classes, IJavaEnumRemoteProcess does not include a GetCount method.

  // Methods
  HRESULT Clone(IJavaEnumRemoteProcess **ppEnum)
  HRESULT GetNext(IRemoteProcess *ppirp)
  HRESULT Next(ULONG celt, IRemoteProcess rgelt[], ULONG *pceltFetched)
  HRESULT Reset(void)
  HRESULT Skip(ULONG celt)


Methods (IJavaEnumRemoteProcess Interface)

 Microsoft SDK for Java

IJavaEnumRemoteProcess Interface Methods

The IJavaEnumRemoteProcess interface contains the following methods:

Clone creates a copy of the enumerator, including the enumerator’s current position in its list of elements.
GetNext retrieves the next element from the enumerator’s list.
Next retrieves the next specified number of elements from the enumerator’s list.
Reset resets the enumerator’s current position in its list of elements to the first element in the list.
Skip moves the enumerator’s current position ahead in its list of elements by the given number of elements.


IJavaEnumRemoteProcess::Clone

 Microsoft SDK for Java

IJavaEnumRemoteProcess::
Clone

The Clone method of the IJavaEnumRemoteProcess interface creates a copy of the enumerator, including the enumerator’s current position in its list of elements.

Syntax

HRESULT Clone(IJavaEnumRemoteProcess **ppEnum)

Parameters

[out] ppEnum Returns a pointer to the copied enumerator.

Return Value

S_OK Success

E_OUTOFMEMORY Insufficient memory.


IJavaEnumRemoteProcess::GetNext

 Microsoft SDK for Java

IJavaEnumRemoteProcess::
GetNext

The GetNext method of the IJavaEnumRemoteProcess interface retrieves the next element from the enumerator's list.

Syntax

HRESULT GetNext(IRemoteProcess *ppirp)

Parameters

[retval] [out] ppirp Returns the next element in the enumerator’s list.

Return Value

S_OK The next element was returned.

S_FALSE No element was returned. There were no elements remaining in the enumerator’s list.


IJavaEnumRemoteProcess::Next

 Microsoft SDK for Java

IJavaEnumRemoteProcess::
Next

The Next method of the IJavaEnumRemoteProcess interface retrieves the next specified number of elements from the enumerator’s list.

Syntax

HRESULT Next(ULONG celt, IRemoteProcess rgelt[], ULONG *pceltFetched)

Parameters

[in] celt | The number of elements requested.
[length_is] [size_is] [out] rgelt | The array to be filled in with the elements.
[out] pceltFetched | The number of elements actually returned in rgelt. This can be less than celt if fewer than celt elements remained in the list.

Return Value

S_OK celt elements were returned.

S_FALSE Fewer than celt elements were returned.


IJavaEnumRemoteProcess::Reset

 Microsoft SDK for Java

IJavaEnumRemoteProcess::
Reset

The Reset method of the IJavaEnumRemoteProcess interface resets the enumerator’s current position in its list of elements to the first element in the list.

Syntax

HRESULT Reset(void)

Return Value

S_OK Success


IJavaEnumRemoteProcess::Skip

 Microsoft SDK for Java

IJavaEnumRemoteProcess::
Skip

The Skip method of the IJavaEnumRemoteProcess interface moves the enumerator’s current position ahead in its list of elements by the given number of elements.

Syntax

HRESULT Skip(ULONG celt)

Parameters

[in] celt The number of elements to be skipped.

Return Value

S_OK Celt elements were skipped.

S_FALSE Fewer than celt elements were skipped. Fewer than celt elements remained in the list.


IRemoteProcess : IUnknown

The IRemoteProcess interface represents a Java process running under the Microsoft VM. This interface is implemented by the Microsoft VM. Once a debugger has obtained an IRemoteProcess interface, either through enumeration or from receiving a ProcessCreateEvent method call, it can attach to and debug the associated Java process.

To debug a Java process, a debugger must first register its IRemoteProcessCallbackEx2 interface with the Java process to receive notifications and information from the Microsoft VM regarding that Java process.

  // Methods
  HRESULT Break(void)
  HRESULT Detach(void)
  HRESULT FindClass(LPCOLESTR pszClassName,
    IRemoteClassField **ppClassType)
  HRESULT GetGlobalContainerObject(IRemoteContainerObject
    **ppGlobalContainerObject)
  HRESULT GetThreadGroups(IJavaEnumRemoteThreadGroup **ppEnum)
  HRESULT RegisterCallback(IRemoteProcessCallback *pCallback)
  HRESULT TraceMethods(BOOL bTraceOn)


Methods (IRemoteProcess Interface)

 Microsoft SDK for Java

IRemoteProcess Interface Methods

The IRemoteProcess interface contains the following methods:

Break breaks execution on all threads in this Java process.
Detach is called by a debugger to detach its IRemoteProcessCallbackEx2 interface from this Java process.
FindClass is used to obtain the IRemoteClassField interface for a named Java class, loading the Java class as a system class first if necessary.
GetGlobalContainerObject returns the IRemoteContainerObject interface representing this Java process’s global container object.
GetThreadGroups returns an IJavaEnumRemoteThreadGroup enumerator for all the thread groups in this Java process.
RegisterCallback is called by a debugger to register a callback interface that should receive notification and information regarding this Java process.
TraceMethods is deprecated.


IRemoteProcess::Break

 Microsoft SDK for Java

IRemoteProcess::
Break

The Break method of the IRemoteProcess interface breaks execution on all threads in this Java process. This method returns immediately and Java execution is halted asynchronously, so threads won't necessarily stop immediately.

Syntax

HRESULT Break(void)

Return Value

S_OK Success.

S_FALSE A break event is already pending.

E_FAIL No debugger IRemoteProcessCallbackEx2 interface is registered.

E_OUTOFMEMORY Insufficient memory.


IRemoteProcess::Detach

 Microsoft SDK for Java

IRemoteProcess::
Detach

The Detach method of the IRemoteProcess interface detaches the IRemoteProcessCallbackEx2 interface from a Java process after the debugger attached its IRemoteProcessCallbackEx2 interface with a previous call to RegisterCallback.

Syntax

HRESULT Detach(void)

Return Value

S_OK Success.

E_FAIL No debugger IRemoteProcessCallbackEx2 interface is registered.


IRemoteProcess::FindClass

 Microsoft SDK for Java

IRemoteProcess::
FindClass

The FindClass method of the IRemoteProcess interface is used to obtain the IRemoteClassField interface for a named Java class, loading the Java class as a system class first if necessary.

Syntax

HRESULT FindClass(LPCOLESTR pszClassName, IRemoteClassField **ppClassType)

Parameters

[in] pszClassName | The name of the class to find.
[out] ppClassType | Returns the named class.

Return Value

S_OK Success.

E_FAIL Unable to find the specified system class.

E_OUTOFMEMORY Insufficient memory.

Remarks

FindClass can only be used to load a system class. It cannot be used to load a class from a Java class loader.


IRemoteProcess::GetGlobalContainerObject

 Microsoft SDK for Java

IRemoteProcess::
GetGlobalContainerObject

The GetGlobalContainerObject method of the IRemoteProcess interface returns the IRemoteContainerObject interface representing this Java process’s global container object. The global container object is the root container object in this Java process. It contains class objects that hold the static data of all loaded Java classes.

Syntax

HRESULT GetGlobalContainerObject(IRemoteContainerObject **ppGlobalContainerObject)

Parameters

[out] ppGlobalContainerObject Returns the global container object for this Java process.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IRemoteProcess::GetThreadGroups

 Microsoft SDK for Java

IRemoteProcess::
GetThreadGroups

The GetThreadGroups method of the IRemoteProcess interface returns an IJavaEnumRemoteThreadGroup enumerator for all the thread groups in this Java process.

Syntax

HRESULT GetThreadGroups(IJavaEnumRemoteThreadGroup **ppEnum)

Parameters

[out] ppEnum Returns an enumerator for the thread groups in this Java process.

Return Value

S_OK Success.

E_FAIL Failure.

E_OUTOFMEMORY Insufficient memory.


IRemoteProcess::RegisterCallback

 Microsoft SDK for Java

IRemoteProcess::
RegisterCallback

The RegisterCallback method of the IRemoteProcess interface is called by a debugger to register a callback interface that should receive notification and information regarding this Java process. The debugger passes its IRemoteProcessCallbackEx2 interface implementation. IRemoteProcessCallbackEx2 is the primary interface that the Microsoft VM uses to communicate with the debugger. The VM sends information to the debugger regarding the process by calling various methods on this callback interface.

Syntax

HRESULT RegisterCallback(IRemoteProcessCallback *pCallback)

Parameters

[in] pCallback The debugger’s callback interface that is to receive notifications for this Java process.

Return Value

S_OK Success.

E_FAIL An IRemoteProcessCallbackEx2 interface is already registered with this Java process.


IRemoteProcess::TraceMethods

 Microsoft SDK for Java

IRemoteProcess::
TraceMethods

Use of the TraceMethods method is deprecated. Tool developers should, in general, use the Java profiler interfaces instead.

The TraceMethods method of the IRemoteProcess interface enables or disables IRemoteProcessCallbackEx2::TraceEvent method callbacks from the Microsoft VM to the debugger each time a Java method is called.

Syntax

HRESULT TraceMethods(BOOL bTraceOn)

Parameters

[in] bTraceOn Set to TRUE to enable method call tracing; set to FALSE to disable method call tracing.

Return Value

S_OK -- Success.

E_FAIL -- Method tracing can only be disabled if it is enabled.

E_OUTOFMEMORY -- Insufficient memory.


IRemoteProcessEx : IRemoteProcess

IRemoteProcessEx extends IRemoteProcess with three methods. It allows dynamic attach debuggers to get and set the debugger flags.

  // Methods
  HRESULT GetDebugOptions(DWORD *pdwOptions);
  HRESULT GetPossibleDebugOptions(DWORD *pdwPossibleOptions);
  HRESULT SetDebugOptions(DWORD dwOptions);

Remarks

  1. MSJDBG_NO_HARDWARE_BREAKPOINTS and MSJDBG_NO_PAGE_BREAKPOINTS can only be changed if no data breakpoints have been set yet.

  2. MSJDBG_IGNORE_METHODS_WITHOUT_DEBUG_INFO will not have the same effect as if enabled at startup. At startup, this enables stepping optimizations. At any other time it just causes events to not be sent for these methods, which is still useful for decreasing needless debugger communication. If the fast interpreter is enabled and this flag is set at startup, the flag cannot be later cleared by SetDebugOptions.

  3. MSJDBG_DISABLE_JIT_COMPILED_CODE_DEBUGGING cannot be modified by SetDebugOptions.

  4. MSJDBG_FL_REQUIRE_BYTE_CODE_EXECUTION and MSJDBG_FL_ENABLE_PROFILING cannot be modified by SetDebugOptions and will not be returned by GetDebugOptions.

  5. All other flags can be set and cleared at will.

See Also

Java Debugger Flags


IRemoteProcessEx Interface Methods

The IRemoteProcessEx interface contains the following methods:

GetDebugOptions gives information about the current state of the debugger flags.
SetDebugOptions changes the debugger flags and indicates if any could not be changed because of the current state of the VM.
GetPossibleDebugOptions tells you which flags are supported by the VM that can be changed by SetDebugOptions.


IRemoteProcessEx::GetDebugOptions

 Microsoft SDK for Java

IRemoteProcessEx::
GetDebugOptions

The GetDebugOptions method of the IRemoteProcessEx interface gives information about the current state of the debugger flags.

Syntax

HRESULT GetDebugOptions(DWORD *pdwOptions);

Parameters

[out] *pdwOptions Pointer to the current state of the debugger flags.

Remarks

GetDebugOptions may return MSJDBG_DISABLE_JIT_COMPILED_CODE_DEBUGGING.

See Also

Java Debugger Flags


IRemoteProcessEx::GetPossibleDebugOptions

 Microsoft SDK for Java

IRemoteProcessEx::
GetPossibleDebugOptions

The GetPossibleDebugOptions method of the IRemoteProcessEx interface tells you which flags are supported by the VM that can be changed by SetDebugOptions.

Syntax

HRESULT GetPossibleDebugOptions(DWORD *pdwPossibleOptions);

Parameters

[out] *pdwPossibleOptions Pointer to changeable options.

Remarks

GetPossibleDebugOptions returns the possible debug flags that may possibly be modified by SetDebugOptions. This includes all flags except MSJDBG_DISABLE_JIT_COMPILED_CODE_DEBUGGING, MSJDBG_FL_REQUIRE_BYTE_CODE_EXECUTION, and MSJDBG_FL_ENABLE_PROFILING.

See Also

Java Debugger Flags


IRemoteProcessEx::SetDebugOptions

 Microsoft SDK for Java

IRemoteProcessEx::
SetDebugOptions

The SetDebugOptions method of the IRemoteProcessEx interface changes the debugger flags and indicates if any could not be changed because of the current state of the VM.

Syntax

HRESULT SetDebugOptions(DWORD dwOptions);

Return Values

S_OK -- all flags were modified as specified.

S_FALSE -- some flags could not be modified as specified.

E_FAIL -- no flags could be modified.

Parameters

[in] dwOptions The requested settings for the debugger flags.

See Also

Java Debugger Flags


Notification Debugger Interfaces Overview

Debugger Interfaces Reference

The notification debugger interfaces notify the debugger when new Java processes are created and when events occur on a specific Java process.

For general information, see Implementing Callback Notification Interfaces in the Programmer's Guide.

This topic contains the following section:

Interfaces

Hierarchy


Notification Debugger Interfaces

The notification debugger interfaces are as follows:

IRemoteDebugManagerCallback has been superseded by the IRemoteDebugManagerCallbackEx interface.

IRemoteDebugManagerCallbackEx provides an initial callback interface through which the Microsoft VM communicates with the debugger.

IRemoteProcessCallback has been superseded by the IRemoteProcessCallbackEx2 interface.

IRemoteProcessCallbackEx has been superseded by the IRemoteProcessCallbackEx2 interface.

IRemoteProcessCallbackEx2 is the primary callback interface through which the Microsoft VM communicates with the debugger.


Notification Debugger Interfaces Hierarchy

The notification debugger interfaces have the following hierarchy:

IUnknown
  |
  +--IRemoteDebugManagerCallback
  |  |
  |  +--IRemoteDebugManagerCallbackEx
  |
  +--IRemoteProcessCallback
  |  |
  |  +--IRemoteProcessCallbackEx
  |  |  |
  |  |  +--IRemoteProcessCallbackEx2


IRemoteDebugManagerCallback : IUnknown

The IRemoteDebugManagerCallback interface has been superseded by the IRemoteDebugManagerCallbackEx interface. New debuggers should implement the IRemoteDebugManagerCallbackEx interface, and pass that interface to RegisterCallback.


IRemoteDebugManagerCallbackEx : IRemoteDebugManagerCallback

The IRemoteDebugManagerCallbackEx interface is one initial callback interface through which the Microsoft VM communicates with the debugger. The debugger registers its IRemoteDebugManagerCallbackEx interface with the Microsoft VM's Debug Manager by calling IRemoteDebugManager::RegisterCallback.

The Microsoft VM calls the debugger's ProcessCreateEvent method when the Java process requested by the debugger's previous call to RequestCreateEvent begins execution. If the debugger specified a particular Java class to be debugged in its call to RequestCreateEvent, the Microsoft VM delays calling the debugger's ProcessCreateEvent method until the specified Java class is loaded.

  // Methods
  HRESULT ProcessCreateEvent(IRemoteProcess *pProcessNew,
    IRemoteProcess *pProcessParent)
  HRESULT StartClassEvent(LPCOLESTR pcstrStartClass)


Methods (IRemoteDebugManagerCallbackEx Interface)

 Microsoft SDK for Java

IRemoteDebugManagerCallbackEx Interface Methods

The IRemoteDebugManagerCallbackEx interface contains the following methods:

ProcessCreateEvent is called by the Microsoft VM to notify the debugger that the requested process to be debugged has started.

StartClassEvent is called by the Microsoft VM to notify the debugger that the Microsoft VM has loaded a Java application, applet, or COM object.


IRemoteDebugManagerCallbackEx::ProcessCreateEvent

 Microsoft SDK for Java

IRemoteDebugManagerCallbackEx::
ProcessCreateEvent

The ProcessCreateEvent method of the IRemoteDebugManagerCallbackEx interface is called by the Microsoft VM to notify the debugger that the requested process to be debugged has started. The Microsoft VM passes in an IRemoteProcess interface representing the running Java process.

Syntax

HRESULT ProcessCreateEvent(IRemoteProcess *pProcessNew, IRemoteProcess *pProcessParent)

Parameters

[in] pProcessNew | The new Java process.
[in] pProcessParent | Reserved.

Return Value

S_FALSE Success.

E_FAIL Failure.

Remarks

The debugger establishes a session with the new Java process by calling RegisterCallback. RegisterCallback registers the debugger's IRemoteProcessCallbackEx2 interface with the new Java process during the Microsoft VM's call to ProcessCreateEvent. The Microsoft VM responds to RegisterCallback by calling ThreadCreateEvent for each running Java thread, and by calling ClassLoadEvent for each loaded Java class.


IRemoteDebugManagerCallbackEx::StartClassEvent

 Microsoft SDK for Java

IRemoteDebugManagerCallbackEx::
StartClassEvent

The StartClassEvent method of the IRemoteDebugManagerCallbackEx is called by the Microsoft VM to notify the debugger that the Microsoft VM has loaded a Java application, applet, or COM object. For example, if the Microsoft VM was started with jview using the command line

JView Hello

the start class would be Hello. If the debugger has already registered an IRemoteProcessCallbackEx2 interface via RegisterCallback, the Microsoft VM calls IRemoteProcessCallbackEx2::StartClassEvent instead of IRemoteDebugManagerCallbackEx::StartClassEvent. IRemoteDebugManagerCallbackEx allows a debugger to receive a StartClassEvent before it has registered an IRemoteProcessCallbackEx2 interface with the Microsoft VM.

Syntax

HRESULT StartClassEvent(LPCOLESTR pcstrStartClass)

Parameters

[in] pcstrStartClass The name of the Java application, applet or COM object class that the Microsoft VM loaded.

Return Value

S_FALSE Success.

E_FAIL Failure.

Remarks

The Microsoft VM calls this method only if the MSJDBG_SEND_START_CLASS_EVENTS (0x40) flag is set in the MSJAVA_DEBUGGING_FLAGS environment variable, or if the MSJAVA_DEBUGGING_FLAGS environment variable is not set and the MSJDBG_SEND_START_CLASS_EVENTS flag is set in the appropriate registry key.


IRemoteProcessCallback : IUnknown

The IRemoteProcessCallback interface has been superseded by the IRemoteProcessCallbackEx2 interface. New debuggers should implement the IRemoteProcessCallbackEx2 interface, and pass that interface to IRemoteProcess::RegisterCallback. See the IRemoteProcessCallbackEx2 interface for details.


IRemoteProcessCallbackEx : IRemoteProcessCallback

The IRemoteProcessCallbackEx interface has been superseded by the IRemoteProcessCallbackEx2 interface. New debuggers should implement the IRemoteProcessCallbackEx2 interface, and pass that interface to IRemoteProcess::RegisterCallback. See the IRemoteProcessCallbackEx2 interface description for details.


IRemoteProcessCallbackEx2 : IRemoteProcessCallbackEx

The IRemoteProcessCallbackEx2 interface is the primary callback interface through which the Microsoft VM communicates with the debugger. The debugger registers its IRemoteProcessCallbackEx2 interface with the Microsoft VM by calling RegisterCallback. The Microsoft VM calls methods on the debugger's IRemoteProcessCallbackEx2 interface to provide notifications and information about the Java process being debugged. Debuggers should implement this latest version of the process callback interface.

Execution of the process being debugged is suspended during IRemoteProcessCallbackEx2 method calls. If the debugger returns S_OK from an IRemoteProcessCallbackEx2 method, the Java process remains suspended. Execution of the Java process is resumed when the debugger calls Go or one of the IRemoteThread stepping methods. If the debugger returns S_FALSE from an IRemoteProcessCallbackEx2 method, the Java process resumes execution immediately. The IRemoteThread interface is passed as a parameter to each IRemoteProcessCallbackEx2 method, and it represents the Java thread on which the event occurred.

  // Methods
  HRESULT BreakEvent(IRemoteThread *pThread)
  HRESULT CanStopEvent(IRemoteThread *pThread)
  HRESULT ClassLoadEvent(IRemoteThread *pThread,
    IRemoteClassField *pClassType)
  HRESULT ClassUnloadEvent(IRemoteThread *pThread,
    IRemoteClassField *pClassType)
  HRESULT CodeBreakpointEvent(IRemoteThread *pThread)
  HRESULT CodeBreakpointEventEx(IRemoteThread *pThread,
    IMethodLocation *piml)
  HRESULT DataBreakpointEvent(IRemoteThread *pThread,
    IRemoteObject *pObject)
  HRESULT DebugStringEvent(IRemoteThread *pThread,
    LPCOLESTR pcszDebugString)
  HRESULT ExceptionEvent(IRemoteThread *pThread,
    IRemoteClassField *pExceptionClass, EXCEPTIONKIND exceptionKind)
  HRESULT ExceptionEventEx(IRemoteThread *pThread,
    IRemoteClassField *pExceptionClass, EXCEPTIONKIND exceptionKind,
    IRemoteClassObject *pExceptionObject)
  HRESULT LoadCompleteEvent(IRemoteThread *pThread)
  HRESULT ProcessDestroyEvent(IRemoteThread *pThread)
  HRESULT StartClassEvent(LPCOLESTR pcstrStartClass)
  HRESULT StepEvent(IRemoteThread *pThread)
  HRESULT ThreadCreateEvent(IRemoteThread *pThread)
  HRESULT ThreadDestroyEvent(IRemoteThread *pThread)
  HRESULT ThreadGroupCreateEvent(IRemoteThread *pThread,
    IRemoteThreadGroup *pThreadGroup)
  HRESULT ThreadGroupDestroyEvent(IRemoteThread *pThread,
    IRemoteThreadGroup *pThreadGroup)
  HRESULT TraceEvent(IRemoteThread *pThread)


Methods (IRemoteProcessCallbackEx2 Interface)

 Microsoft SDK for Java

IRemoteProcessCallbackEx2 Interface Methods

The IRemoteProcessCallbackEx2 interface contains the following methods:

BreakEvent notifies the debugger when an asynchronous break occurs in response to the debugger calling IRemoteProcess::Break.
CanStopEvent notifies the debugger when a Java thread in step in mode makes a method call or returns from the stepping stack frame.
ClassLoadEvent notifies the debugger when a Java class is loaded.
ClassUnloadEvent notifies the debugger when a Java class is unloaded.
CodeBreakpointEvent notifies the debugger when a code breakpoint set by a call to IRemoteMethodField::SetBreakpoint is hit by the Java process being debugged.
CodeBreakpointEventEx notifies the debugger when a code breakpoint set by a call to IMethodLocation::SetBreakpoint is hit by the Java process being debugged.
DataBreakpointEvent notifies the debugger when a data breakpoint is hit by the Java process being debugged.
DebugStringEvent notifies the debugger when the Java process being debugged generates a string.
ExceptionEvent is deprecated.
ExceptionEventEx supersedes the ExceptionEvent method.
LoadCompleteEvent notifies the debugger when all Java classes directly required by the class being debugged have been loaded.
ProcessDestroyEvent notifies the debugger when the Java process terminates.
StartClassEvent notifies the debugger that the Microsoft VM has loaded a Java application, applet, or COM object in the Java process.
StepEvent notifies the debugger when a Java thread in step mode completes an execution step.
ThreadCreateEvent notifies the debugger when a thread is created.
ThreadDestroyEvent notifies the debugger when a thread is destroyed.
ThreadGroupCreateEvent notifies the debugger when a thread group is created.
ThreadGroupDestroyEvent notifies the debugger when a thread group is destroyed.
TraceEvent notifies the debugger when a Java method is entered while method tracing is enabled.


IRemoteProcessCallbackEx2::BreakEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
BreakEvent

The BreakEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when an asynchronous break occurs in response to the debugger calling IRemoteProcess::Break.

Syntax

HRESULT BreakEvent(IRemoteThread *pThread)

Parameters

[in] pThread The thread that generated the event.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::CanStopEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
CanStopEvent

The CanStopEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a Java thread in step in mode makes a method call or returns from the stepping stack frame. See Controlling Execution for details on thread stepping events.

Syntax

HRESULT CanStopEvent(IRemoteThread *pThread)

Parameters

[in] pThread The thread that generated the event.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::ClassLoadEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
ClassLoadEvent

The ClassLoadEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a Java class is loaded.

Syntax

HRESULT ClassLoadEvent(IRemoteThread *pThread, IRemoteClassField *pClassType)

Parameters

[in] pThread | The thread that generated the event.
[in] pClassType | The class that was loaded.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::ClassUnloadEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
ClassUnloadEvent

The ClassUnloadEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a Java class is unloaded.

Syntax

HRESULT ClassUnloadEvent(IRemoteThread *pThread, IRemoteClassField *pClassType)

Parameters

[in] pThread | The thread that generated the event.
[in] pClassType | The class that was unloaded.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::CodeBreakpointEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
CodeBreakpointEvent

The CodeBreakpointEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a code breakpoint set by a call to IRemoteMethodField::SetBreakpoint is hit by the Java process being debugged.

Syntax

HRESULT CodeBreakpointEvent(IRemoteThread *pThread)

Parameters

[in] pThread The thread that generated the event.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::CodeBreakpointEventEx

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
CodeBreakpointEventEx

The CodeBreakpointEventEx method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a code breakpoint set by a call to IMethodLocation::SetBreakpoint is hit by the Java process being debugged.

Syntax

HRESULT CodeBreakpointEventEx(IRemoteThread *pThread, IMethodLocation *piml)

Parameters

[in] pThread | The thread that generated the event.
[in] piml | The method location where the code breakpoint was triggered.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::DataBreakpointEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
DataBreakpointEvent

The DataBreakpointEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a data breakpoint is hit by the Java process being debugged.

Syntax

HRESULT DataBreakpointEvent(IRemoteThread *pThread, IRemoteObject *pObject)

Parameters

[in] pThread | The thread that generated the event.
[in] pObject | The object whose value was set, triggering the breakpoint.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::DebugStringEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
DebugStringEvent

The DebugStringEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when the Java process being debugged generates a string. A process that is being debugged can cause the Microsoft VM to call the debugger's DebugStringEvent method by calling the com.ms.debug.Debugger.out.println method.

Syntax

HRESULT DebugStringEvent(IRemoteThread *pThread, LPCOLESTR pcszDebugString)

Parameters

[in] pThread | The thread that generated the event.
[in] pcszDebugString | The string from the Java process.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::ExceptionEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
ExceptionEvent

This method is deprecated. If the debugger implements IRemoteProcessCallbackEx2, the Microsoft VM calls the debugger's ExceptionEventEx method rather than the debugger's ExceptionEvent method.

The ExceptionEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when an exception occurs in the Java process being debugged.

Syntax

HRESULT ExceptionEvent(IRemoteThread *pThread, IRemoteClassField *pExceptionClass, EXCEPTIONKIND exceptionKind)

Parameters

[in] pThread | The thread that generated the event.
[in] pExceptionClass | The class of the thrown object.
[in] exceptionKind | The kind of exception that occurred.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.

Remarks

The EXCEPTIONKIND parameter is one of the values defined in the EXCEPTIONKIND enumeration as shown below.

EXCEPTIONKIND Enumeration: EXCEPTION_KIND_FIRST_CHANCE

Value: 1

Description: A Java exception was thrown. The Microsoft VM has not yet searched for a handler for the thrown exception.

EXCEPTIONKIND Enumeration: EXCEPTION_KIND_LAST_CHANCE

Value: 2

Description: No exception handler was found for this thrown Java exception.

When a Java exception is thrown, the debugger receives an EXCEPTION_KIND_FIRST_CHANCE exception notification. If the Microsoft VM cannot find a handler for the exception, the debugger then receives an EXCEPTION_KIND_LAST_CHANCE exception notification.


IRemoteProcessCallbackEx2::ExceptionEventEx

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
ExceptionEventEx

This method of the IRemoteProcessCallbackEx2 interface supersedes the ExceptionEvent method. If the debugger implements IRemoteProcessCallbackEx2, the Microsoft VM calls the debugger's ExceptionEventEx method rather than the debugger's ExceptionEvent method.

The ExceptionEventEx method notifies the debugger when an exception occurs in the Java process being debugged.

Syntax

HRESULT ExceptionEventEx(IRemoteThread *pThread, IRemoteClassField *pExceptionClass, EXCEPTIONKIND exceptionKind, IRemoteClassObject *pExceptionObject)

Parameters

[in] pThread | The thread that generated the event.
[in] pExceptionClass | The class of the thrown object.
[in] exceptionKind | The kind of exception that occurred.
[in] pExceptionObject | The thrown object.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.

Remarks

The exceptionKind parameter is one of the values defined in the EXCEPTIONKIND enumeration as shown below.

EXCEPTIONKIND Enumeration: EXCEPTION_KIND_FIRST_CHANCE

Value: 1

Description: A Java exception was thrown. The Microsoft VM has not yet searched for a handler for the thrown exception.

EXCEPTIONKIND Enumeration: EXCEPTION_KIND_LAST_CHANCE

Value: 2

Description: No exception handler was found for this thrown Java exception.

When a Java exception is thrown, the debugger receives an EXCEPTION_KIND_FIRST_CHANCE exception notification. If the Microsoft VM cannot find a handler for the exception, the debugger then receives an EXCEPTION_KIND_LAST_CHANCE exception notification.


IRemoteProcessCallbackEx2::LoadCompleteEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
LoadCompleteEvent

The LoadCompleteEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when all Java classes directly required by the class being debugged have been loaded.

Syntax

HRESULT LoadCompleteEvent(IRemoteThread *pThread)

Parameters

[in] pThread The thread that generated the event.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::ProcessDestroyEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
ProcessDestroyEvent

The ProcessDestroyEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when the Java process terminates. No further notifications are sent to the debugger regarding the Java process after this method is called. This method is not necessarily called before the Java process terminates. A debugger should watch for the termination of the Win32 process being debugged.

Syntax

HRESULT ProcessDestroyEvent(IRemoteThread *pThread)

Parameters

[in] pThread The thread that generated the event.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::StartClassEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
StartClassEvent

The StartClassEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger that the Microsoft VM has loaded a Java application, applet, or COM object in the Java process.

Syntax

HRESULT StartClassEvent(LPCOLESTR pcstrStartClass)

Parameters

[in] pcstrStartClass The name of the application, applet, or COM object Java class.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::StepEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
StepEvent

The StepEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a Java thread in step mode completes an execution step. See Controlling Execution for details on thread stepping events.

Syntax

HRESULT StepEvent(IRemoteThread *pThread)

Parameters

[in] pThread The thread that generated the event.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::ThreadCreateEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
ThreadCreateEvent

The ThreadCreateEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a thread is created.

Syntax

HRESULT ThreadCreateEvent(IRemoteThread *pThread)

Parameters

[in] pThread The thread that generated the event.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::ThreadDestroyEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
ThreadDestroyEvent

The ThreadDestroyEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a thread is destroyed.

Syntax

HRESULT ThreadDestroyEvent(IRemoteThread *pThread)

Parameters

[in] pThread The thread that generated the event.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::ThreadGroupCreateEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
ThreadGroupCreateEvent

The ThreadGroupCreateEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a thread group is created.

Syntax

HRESULT ThreadGroupCreateEvent(IRemoteThread *pThread, IRemoteThreadGroup *pThreadGroup)

Parameters

[in] pThread | The thread that generated the event.
[in] pThreadGroup | The thread group that was created.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2::ThreadGroupDestroyEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
ThreadGroupDestroyEvent

The ThreadGroupDestroyEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a thread group is destroyed.

Syntax

HRESULT ThreadGroupDestroyEvent(IRemoteThread *pThread, IRemoteThreadGroup *pThreadGroup)

Parameters

[in] pThread | The thread that generated the event.
[in] pThreadGroup | The thread group that was destroyed.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


IRemoteProcessCallbackEx2:TraceEvent

 Microsoft SDK for Java

IRemoteProcessCallbackEx2::
TraceEvent

The TraceEvent method of the IRemoteProcessCallbackEx2 interface notifies the debugger when a Java method is entered while method tracing is enabled by IRemoteProcess::TraceMethods. Its use is deprecated. Tool developers should (in general) instead use the Java profiler interfaces.

Syntax

HRESULT TraceEvent(IRemoteThread *pThread)

Parameters

[in] pThread The thread that generated the event.

Return Value

S_OK Leave execution suspended.

S_FALSE Resume execution.


Static Information Debugger Interfaces Overview

Debugger Interfaces Reference

Static information on a Java process is available mainly through the IRemoteField hierarchy of interfaces. These interfaces represent fields that are class members, such as methods, objects, inner classes, or nested class definitions. Because all the attributes of a field are constant during its lifetime, the debugger can cache this information.

For general information, see Retrieving Static Information in the Programmer's Guide.

This topic contains the following sections:

Interfaces

Hierarchy


Static Information Debugger Interfaces

The static information interfaces are as follows:

IRemoteField and its derivatives represent classes and fields that are members of classes.

IRemoteDataField represents a Java data field.

IRemoteArrayField represents a Java array data field.

IRemoteContainerField represents a field that contain other fields.

IRemoteClassField represents a Java class.

IRemoteClassFieldEx The IRemoteClassFieldEx interface represents a Java class definition.

IRemoteInnerClassField represents a Java inner class.

IRemotePrimitiveClassField represents a Java primitive data type.

IRemoteMethodField represents a Java method.

IRemoteMethodFieldEx represents a Java method in conjunction with IMethodLocation.

IEnumRemoteField enumerates all the fields contained within a class, method, or container.

IJavaEnumRemoteField enumerates IRemoteField pointers.

IEnumLINEINFO provides access to line number information.

IJavaEnumLINEINFO provides access to line number information and adds one method to IEnumLINEINFO.


Static Information Debugger Interfaces Hierarchy

The static information debugger interfaces have the following hierarchy:

IUnknown
  |
  +--IRemoteField
  |  |
  |  +--IRemoteDataField
  |  |  |
  |  |  +--IRemoteArrayField
  |  |
  |  +--IRemoteContainerField
  |  |  |
  |  |  +--IRemoteClassField
  |  |  |  |
  |  |  |  +--IRemoteClassFieldEx
  |  |  |  |  |
  |  |  |  |  +--IRemoteInnerClassField
  |  |  |
  |  |  |  +--IRemotePrimitiveClassField
  |  |  |
  |  |  +--IRemoteMethodField
  |  |  |  |
  |  |  |  +--IRemoteMethodFieldEx
  |
  +--IEnumRemoteField
  |  |
  |  +--IJavaEnumRemoteField
  |
  +--IEnumLINEINFO
  |  |
  |  +--IJavaEnumLINEINFO


IRemoteField : IUnknown

The IRemoteField hierarchy of interfaces represents classes and fields that are members of classes. These fields can be methods, variable definitions, or inner class definitions. Global classes (classes not defined within other classes) can be thought of as fields of a global class. Because all the attributes of a field are constant during its lifetime, the debugger can cache field information until the class associated with the field is unloaded.

  // Methods
  HRESULT GetContainer(IRemoteContainerField **ppContainer)
  HRESULT GetKind(FIELDKIND *pKind)
  HRESULT GetModifiers(ULONG *pulModifiers)
  HRESULT GetName(LPOLESTR *ppszName)
  HRESULT GetType(IRemoteField **ppType)


Methods (IRemoteField Interface)

 Microsoft SDK for Java

IRemoteField Interface Methods

The IRemoteField interface contains the following methods:

GetContainer returns an IRemoteContainerField interface representing this field’s container.
GetKind returns the kind of this field as a bitmask of flags from the FIELD_KIND enumeration.
GetModifiers returns a bitmask of flags from the FIELDMODIFIERS enumeration describing the modifiers of this field.
GetName returns the identifier (the class, variable, or method name) of this field.
GetType returns an IRemoteField interface that represents the type of this field.


IRemoteField::GetContainer

 Microsoft SDK for Java

IRemoteField::
GetContainer

The GetContainer method of the IRemoteField interface returns an IRemoteContainerField interface representing this field’s container.

Syntax

HRESULT GetContainer(IRemoteContainerField **ppContainer)

Parameters

[out] ppContainer Returns the field representing the field’s container.

Return Value

S_OK Success.

Containers of Each Type of Field

Field Type | Container
Global container | None
Global class | Global container
Inner class | Global container
Class data field | Class
Method | Class
Method parameter | Method
Method local variable | Method

To obtain the IRemoteClassField of the class containing an inner class, call IRemoteInnerClassField::GetOuterClass. To obtain the IRemoteField of the global container field, call GetType on the IRemoteContainerObject interface returned from IRemoteProcess::GetGlobalContainerObject. GetContainer returns a NULL IRemoteContainerField and S_OK for the global container field.


IRemoteField::GetKind

 Microsoft SDK for Java

IRemoteField::
GetKind

The GetKind method of the IRemoteField interface returns the kind of this field as a bitmask of flags from the FIELD_KIND enumeration.

Syntax

HRESULT GetKind(FIELDKIND *pKind)

Parameters

[out] pKind Returns a bitmask of flags describing the kind of this field.

Return Value

S_OK Success.

Remarks

Field kinds are classified by the bit flags in the FIELDKIND enumeration, as shown below.

FIELDKIND enum: FIELD_KIND_DATA_OBJECT

Value: 0x0001

Description: An instance of a Java class.

FIELDKIND enum: FIELD_KIND_DATA_PRIMITIVE

Value: 0x0002

Description: An instance of a primitive Java data type.

FIELDKIND enum: FIELD_KIND_ARRAY

Value: 0x0004

Description: A Java array.

FIELDKIND enum: FIELD_KIND_CLASS

Value: 0x0008

Description: A Java class.

FIELDKIND enum: FIELD_KIND_METHOD

Value: 0x0010

Description: A Java method.

FIELDKIND enum: FIELD_KIND_LOCAL

Value: 0x1000

Description: A local variable in a Java method.

FIELDKIND enum: FIELD_KIND_PARAM

Value: 0x2000

Description: A parameter passed to a Java method

FIELDKIND enum: FIELD_KIND_THIS

Value: 0x4000

Description: A this object reference passed to a Java method.

FIELDKIND enum: FIELD_KIND_INNER_CLASS

Value: 0x8000

Description: A Java inner class.

If a field is not FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS, it might be a class field or an array element. This can be determined by getting the kind of the field’s container. For an array element, the container field’s kind is FIELD_KIND_ARRAY. For a class field, the container field’s kind is FIELD_KIND_CLASS.

The following Java code sample illustrates the FIELDKINDs for a sample Java class:

class <globals>              // FIELD_KIND_CLASS
{
  class MyClass              // FIELD_KIND_CLASS
  {
    boolean bDone;           // FIELD_KIND_DATA_PRIMITIVE
    class BarClass           // FIELD_KIND_INNER_CLASS
    {
      String username[20];   // FIELD_KIND_ARRAY
    }
      BarClass mybar;        // FIELD_KIND_DATA_OBJECT
      int BarMethod();       // FIELD_KIND_METHOD
  };
};


IRemoteField::GetModifiers

 Microsoft SDK for Java

IRemoteField::
GetModifiers

The GetModifiers method of the IRemoteField interface returns a bitmask of flags from the FIELDMODIFIERS enumeration describing the modifiers of this field.

Syntax

HRESULT GetModifiers(ULONG *pulModifiers)

Parameters

[out] pulModifiers Returns a bitmask of flags describing the modifiers of this field.

Return Value

S_OK Success.

Remarks

The modifier bit flags are the same as those used in the access_flags field of the class file header. The modifier bit flags are defined in the FIELDMODIFIERS enumeration shown as follows:

FIELDMODIFIERS enum: FIELD_ACC_PUBLIC

Value: 0x0001

Description: Accessible from outside its package. This modifier can be applied to a class, field, inner class, interface, or method.

FIELDMODIFIERS enum: FIELD_ACC_PRIVATE

Value: 0x0002

Description: Accessible only within the defining class. This modifier can be applied to a field, inner class, or method.

FIELDMODIFIERS enum: FIELD_ACC_PROTECTED

Value: 0x0004

Description: Accessible only within this class and its subclasses. This modifier can be applied to a field, inner class, or method.

FIELDMODIFIERS enum: FIELD_ACC_STATIC

Value: 0x0008

Description: Accessible without an object reference. This modifier can be applied to a field, inner class, or method.

FIELDMODIFIERS enum: FIELD_ACC_FINAL

Value: 0x0010

Description: No subclassing from or assignment to is allowed. This modifier can be applied to any class, field, inner class, or method.

FIELDMODIFIERS enum: FIELD_ACC_SYNCHRONIZED

Value: 0x0020

Description: An object monitor lock is entered during a call to this method. This modifier can be applied to a method.

FIELDMODIFIERS enum: FIELD_ACC_VOLATILE

Value: 0x0040

Description: The value of this field cannot be cached. This modifier can be applied to a field.

FIELDMODIFIERS enum: FIELD_ACC_TRANSIENT

Value: 0x0080

Description: This field cannot be read or written by a persistent object manager. This modifier can be applied to a field.

FIELDMODIFIERS enum: FIELD_ACC_NATIVE

Value: 0x0100

Description: This method is implemented using native code. This modifier can be applied to a method.

FIELDMODIFIERS enum: FIELD_ACC_INTERFACE

Value: 0x0200

Description: This is an interface, not a class. This modifier is applied to an interface.

FIELDMODIFIERS enum: FIELD_ACC_ABSTRACT

Value: 0x0400

Description: This class or interface can not be instantiated. This modifier can be applied to a class, inner class, interface, or method.

FIELDMODIFIERS enum: FIELD_ACC_SUPER

Value: 0x0800

Description: Superclass methods are treated specially by the invokespecial bytecode instruction (used for backward compatibility). This modifier can be applied to a class, inner class, or interface.

FIELDMODIFIERS enum: FIELD_ACC_SYNTHETIC

Value: 0x1000

Description: Invented by the compiler. This modifier can be applied to an inner class.


IRemoteField::GetName

 Microsoft SDK for Java

IRemoteField::
GetName

The GetName method of the IRemoteField interface returns the identifier (the class, variable, or method name) of this field.

Syntax

HRESULT GetName(LPOLESTR *ppszName)

Parameters

[out] *ppszName Returns the identifier for this field.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IRemoteField::GetType

 Microsoft SDK for Java

IRemoteField::
GetType

The GetType method of the IRemoteField interface returns an IRemoteField interface that represents the type of this field.

Syntax

HRESULT GetType(IRemoteField **ppType)

Parameters

[out] **ppType Returns an IRemoteField representing the type of this field.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.

Remarks

The relationship between a field and its type depends on FIELDKIND. The type will be an array type, a class type, or a Java primitive data type. When this method is called on the global container field, the method returns S_OK and the IRemoteField returned representing the type is NULL.

If the GetType method is called on an IRemoteField representing a primitive data field, the IRemoteField returned will be that of the primitive class corresponding to the type of the data field. For example, for a boolean variable, GetType will return the IRemoteField for the boolean primitive class. Calling GetName on the Boolean primitive class’s IRemoteField will return the Unicode string "boolean", and calling GetKind will return FIELD_KIND_CLASS.

If the GetType method is called on an IRemoteField representing an array data field, the IRemoteField returned will be that of the element type of the array. The element type can be another array, a class, or a primitive class. Calling GetKind on the returned IRemoteField will return either the FIELD_KIND_CLASS bit flag set (for an array of object references or an array of a primitive data type) or the FIELD_KIND_ARRAY bit set for an array of arrays.

The element type of an array of a primitive data type can be determined by calling QueryInterface for IID_IRemotePrimitiveClassField on the IRemoteField representing the element type of the array to obtain the IRemotePrimitiveClassField interface, if any, for the array elements. Then, the debugger can call IRemotePrimitiveClassField::GetPrimitiveType to obtain a PRIMITIVE_TYPE enumeration value representing the primitive type of the array elements.

The debugger can call IRemoteField::GetName on the IRemoteField representing the element type of the array to obtain the name of the primitive class of the array elements. The array element class name can be compared with the known primitive class names.


IRemoteDataField : IRemoteField

The IRemoteDataField interface represents a Java data field. It derives from IRemoteField and contains all its methods.


IRemoteArrayField : IRemoteDataField

The IRemoteArrayField interface represents a Java array data field. The only major difference between a data field and an array data field is that an array field has a size.

A debugger does not access the elements of an array through an IRemoteArrayField because the field is not bound to an instance of the array. The IRemoteArrayObject interface can be used to extract the elements from an instance of an array.

  // Methods
  HRESULT GetSize(ULONG *pcElements)


Methods (IRemoteArrayField Interface)

 Microsoft SDK for Java

IRemoteArrayField Interface Methods

The IRemoteDataField interface contains only the IRemoteArrayField::GetSize method, which returns the number of elements in an array, if known.


IRemoteArrayField::GetSize

 Microsoft SDK for Java

IRemoteArrayField::
GetSize

The GetSize method of the IRemoteDataField interface returns the number of elements in an array, if known. IRemoteArrayField::GetSize only succeeds if the array’s size is statically recorded in the array’s signature. IRemoteArrayObject::GetSize should always succeed for a valid array object, whether or not its signature explicitly included a size.

Syntax

HRESULT GetSize(ULONG *pcElements)

Parameters

[out] pcElements Returns the number of elements in this array.

Return Value

S_OK Success.

E_FAIL This field is not an array.

Remarks

If the array’s size is not statically known, S_OK will be returned with a 0 (zero) element count.


IRemoteContainerField : IRemoteField

The IRemoteContainerField interface represents a field that contains other fields.

  // Methods
  HRESULT GetFields(IJavaEnumRemoteField **ppEnum, FIELDKIND ulKind,
    FIELDMODIFIERS ulModifiers, LPCOLESTR lpcszName)


Methods (IRemoteContainerFields Interface)

 Microsoft SDK for Java

IRemoteContainerField Interface Methods

The IRemoteContainerField interface contains the IRemoteContainerField::GetFields method, which returns an IJavaEnumRemoteField enumerator for the fields that are contained by this field and match given characteristics.


IRemoteContainerField::GetFields

 Microsoft SDK for Java

IRemoteContainerField::
GetFields

The GetFields method of the IRemoteContainerField interface returns an IJavaEnumRemoteField enumerator for the fields that are contained by this field and match given characteristics.

Syntax

HRESULT GetFields(IJavaEnumRemoteField **ppEnum, FIELDKIND ulKind, FIELDMODIFIERS ulModifiers, LPCOLESTR lpcszName)

Parameters

[out] **ppEnum | Returns an enumerator for the fields that are contained by this field and match the given characteristics.
[in] ulKind | A bitmask of flags indicating the kinds of fields to be included in the enumeration. Use zero to include all field kinds.
[in] ulModifiers | A bitmask of flags indicating the modifiers of fields to be included in the enumeration. Use zero to include all field modifiers.
[in] lpcszName | The name of the fields to be included in the enumeration. Use NULL to include all names.

Return Value

S_OK Success.

E_NOFIELDS There are no matching fields in this container.

E_OUTOFMEMORY Insufficient memory.

Remarks

The characteristics of the fields included in the enumeration are determined by three parameters that specify the name of the field, the field modifiers bitmask of flags, and the field kind bitmask of flags. A NULL name is used to include all names. A bitmask of 0 (zero) is used to include all field modifiers. A bitmask of 0 (zero) is used to include all field kinds.

FIELDKIND enum: FIELD_KIND_DATA_OBJECT

Value: 0x0001

Description: An instance of a Java class.

FIELDKIND enum: FIELD_KIND_DATA_PRIMITIVE

Value: 0x0002

Description: An instance of a primitive Java data type.

FIELDKIND enum: FIELD_KIND_ARRAY

Value: 0x0004

Description: A Java array.

FIELDKIND enum: FIELD_KIND_CLASS

Value: 0x0008

Description: A Java class.

FIELDKIND enum: FIELD_KIND_METHOD

Value: 0x0010

Description: A Java method.

FIELDKIND enum: FIELD_KIND_LOCAL

Value: 0x1000

Description: A local variable in a Java method.

FIELDKIND enum: FIELD_KIND_PARAM

Value: 0x2000

Description: A parameter passed to a Java method

FIELDKIND enum: FIELD_KIND_THIS

Value: 0x4000

Description: A this object reference passed to a Java method.

FIELDKIND enum: FIELD_KIND_INNER_CLASS

Value: 0x8000

Description: A Java inner class.

If a field is not FIELD_KIND_LOCAL, FIELD_KIND_PARAM, or FIELD_KIND_THIS, it might be a class field or an array element. This can be determined by getting the kind of the field’s container. For an array element, the container field’s kind is FIELD_KIND_ARRAY. For a class field, the container field’s kind is FIELD_KIND_CLASS.

The following Java code sample illustrates the FIELDKINDs for a sample Java class:

class <globals>              // FIELD_KIND_CLASS
{
class MySampleClass          // FIELD_KIND_CLASS
  {
  boolean bDone;             // FIELD_KIND_DATA_PRIMITIVE
  class BarClass             // FIELD_KIND_INNER_CLASS
    {
    String username[20];     // FIELD_KIND_ARRAY
    }
    BarClass mybar;          // FIELD_KIND_DATA_OBJECT
    int BarMethod();         // FIELD_KIND_METHOD
  };
};

FIELDMODIFIERS enum: FIELD_ACC_PUBLIC

Value: 0x0001

Description: Accessible from outside its package. This modifier can be applied to a class, field, inner class, interface, or method.

FIELDMODIFIERS enum: FIELD_ACC_PRIVATE

Value: 0x0002

Description: Accessible only within the defining class. This modifier can be applied to a field, inner class, or method.

FIELDMODIFIERS enum: FIELD_ACC_PROTECTED

Value: 0x0004

Description: Accessible only within this class and its subclasses. This modifier can be applied to a field, inner class, or method.

FIELDMODIFIERS enum: FIELD_ACC_STATIC

Value: 0x0008

Description: Accessible without an object reference. This modifier can be applied to a field, inner class, or method.

FIELDMODIFIERS enum: FIELD_ACC_FINAL

Value: 0x0010

Description: No subclassing from or assignment to is allowed. This modifier can be applied to any class, field, inner class, or method.

FIELDMODIFIERS enum: FIELD_ACC_SYNCHRONIZED

Value: 0x0020

Description: An object monitor lock is entered during a call to this method. This modifier can be applied to a method.

FIELDMODIFIERS enum: FIELD_ACC_VOLATILE

Value: 0x0040

Description: The value of this field cannot be cached. This modifier can be applied to a field.

FIELDMODIFIERS enum: FIELD_ACC_TRANSIENT

Value: 0x0080

Description: This field cannot be read or written by a persistent object manager. This modifier can be applied to a field.

FIELDMODIFIERS enum: FIELD_ACC_NATIVE

Value: 0x0100

Description: This method is implemented using native code. This modifier can be applied to a method.

FIELDMODIFIERS enum: FIELD_ACC_INTERFACE

Value: 0x0200

Description: This is an interface, not a class. This modifier is applied to an interface.

FIELDMODIFIERS enum: FIELD_ACC_ABSTRACT

Value: 0x0400

Description: This class or interface might not be instantiated. This modifier can be applied to a class, inner class, interface, or method.

FIELDMODIFIERS enum: FIELD_ACC_SUPER

Value: 0x0800

Description: Superclass methods are treated specially by the invokespecial bytecode instruction (used for backward compatibility). This modifier can be applied to a class, inner class, or interface.

FIELDMODIFIERS enum: FIELD_ACC_SYNTHETIC

Value: 0x1000

Description: Invented by the compiler. This modifier can be applied to an inner class.


IRemoteClassField : IRemoteContainerField

The IRemoteClassField interface represents a Java class.

  // Methods
  HRESULT GetConstantPoolItem(ULONG indexCP, BYTE **ppCPBytes,
    ULONG *plength)
  HRESULT GetInterfaces(IJavaEnumRemoteField **ppEnum)
  HRESULT GetSourceFileName(LPOLESTR *ppszSourceFileName)
  HRESULT GetSuperclass(IRemoteClassField **ppSuperclass)


Methods (IRemoteClassField Interface)

 Microsoft SDK for Java

IRemoteClassField Interface Methods

The IRemoteClassField interface contains the following methods:

GetConstantPoolItem returns the raw contents of a constant pool item, typically for bytecode disassembly.
GetInterfaces returns an IJavaEnumRemoteField enumerator for the interfaces that this class implements.
GetSourceFileName returns the source file attribute (SourceFile) from the class file.
GetSuperClass returns the IRemoteClassField of the class from which this class is derived.


IRemoteClassField::GetConstantPoolItem

 Microsoft SDK for Java

IRemoteClassField::
GetConstantPoolItem

The GetConstantPoolItem method of the IRemoteClassField interface returns the raw contents of a constant pool item, typically for bytecode disassembly. Any indices contained within the constant pool item are converted from big-endian order to platform byte order.

Syntax

HRESULT GetConstantPoolItem(ULONG indexCP, BYTE **ppCPBytes, ULONG *plength)

Parameters

[in] indexCP | Index in the constant pool of this class of the entry to be retrieved.
[out] ppCPBytes | Returns the constant pool data of the requested entry.
[out] plength | Returns the length of the returned constant pool entry, in bytes.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.

Remarks

The constant pool items are defined by an initial tag byte that indicates the format of the item stored followed by the data for that constant pool entry.

CP_CONSTANT enum: CP_CONSTANT_UTF8

Value: 1

Description: A UCS Transformation Format (UTF-8) string used to represent a constant string value encoded in a structure with a 2-byte length preceding the string.

CP_CONSTANT enum: CP_CONSTANT_UNICODE

Value: 2

Description: A Unicode string with a two-byte length preceding the string.

CP_CONSTANT enum: CP_CONSTANT_INTEGER

Value: 3

Description: A 32-bit integer constant.

CP_CONSTANT enum: CP_CONSTANT_FLOAT

Value: 4

Description: A 32-bit single-precision floating point constant.

CP_CONSTANT enum: CP_CONSTANT_LONG

Value: 5

Description: A 64-bit long integer constant.

CP_CONSTANT enum: CP_CONSTANT_DOUBLE

Value: 6

Description: A 64-bit double precision floating-point constant.

CP_CONSTANT enum: CP_CONSTANT_CLASS

Value: 7

Description: A 16-bit index to a UTF-8 class name.

CP_CONSTANT enum: CP_CONSTANT_STRING

Value: 8

Description: A 16-bit index to a UTF-8 string.

CP_CONSTANT enum: CP_CONSTANT_FIELDREF

Value: 9

Description: A 16-bit index to a class, followed by a 16-bit index to a field name and type.

CP_CONSTANT enum: CP_CONSTANT_METHODREF

Value: 10

Description: A 16-bit index to a class, followed by a 16-bit index to a method name and type.

CP_CONSTANT enum: CP_CONSTANT_INTERFACEMETHODREF

Value: 11

Description: A 16-bit index to an interface, followed by a 16-bit index to a method name and type.

CP_CONSTANT enum: CP_CONSTANT_NAMEANDTYPE

Value: 12

Description: A 16-bit index to a UTF-8 name, followed by a 16-bit index to a UTF-8 field or method descriptor representing the type of the field or method. The field or method descriptor is a series of characters defined in The Java Virtual Machine Specification by Addison Wesley.


IRemoteClassField::GetInterfaces

 Microsoft SDK for Java

IRemoteClassField::
GetInterfaces

The GetInterfaces method of the IRemoteClassField interface returns an IJavaEnumRemoteField enumerator for the interfaces that this class implements.

Syntax

HRESULT GetInterfaces(IJavaEnumRemoteField **ppEnum)

Parameters

[out] ppEnum Returns an enumerator for the interfaces that this class implements.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.

Remarks

If the class implements no interfaces, an empty enumerator is returned.


IRemoteClassField::GetSourceFileName

 Microsoft SDK for Java

IRemoteClassField::
GetSourceFileName

The GetSourceFileName method of the IRemoteClassField interface returns the source file attribute (SourceFile) from the class file. The source file for HelloWorld.class might be HelloWorld.java, for example.

Syntax

HRESULT GetSourceFileName(LPOLESTR *ppszSourceFileName)

Parameters

[out] ppszSourceFileName Returns the name of the source file that was compiled to create this class.

Return Value

S_OK Success.

E_FAIL This class has no SourceFile attribute.

E_OUTOFMEMORY Insufficient memory.


IRemoteClassField::GetSuperClass

 Microsoft SDK for Java

IRemoteClassField::
GetSuperClass

The GetSuperClass method of the IRemoteClassField interface returns the IRemoteClassField of the class from which this class is derived.

Syntax

HRESULT GetSuperclass(IRemoteClassField **ppSuperclass)

Parameters

[out] ppSuperclass Returns the class from which this class is derived.

Return Value

S_OK Success.

Remarks

For java.lang.Object, the root of the class hierarchy, and for primitive classes (like int) this method returns NULL.


IRemoteClassFieldEx : IRemoteClassField

The IRemoteClassFieldEx interface represents a Java class definition. It extends IRemoteClassField by adding one method. A debugger typically obtains an IRemoteClassFieldEx interface by calling QueryInterface for IID_IRemoteClassFieldEx on an IRemoteClassField interface provided by the Microsoft VM.

  // Methods
  HRESULT GetSourceFileDir(LPOLESTR *ppszSourceFileDir)


Methods (IRemoteClassFieldEx Interface)

 Microsoft SDK for Java

IRemoteClassFieldEx Interface Methods

The IRemoteClassFieldEx interface contains the GetSourceFileDir method, which returns the source file directory attribute (SourceDir) from the class file.


IRemoteClassFieldEx::GetSourceFileDir

 Microsoft SDK for Java

IRemoteClassFieldEx::
GetSourceFileDir

The GetSourceFileDir method of the IRemoteClassFieldEx interface returns the source file directory attribute (SourceDir) from the class file. The source file directory for HelloWorld.class might be C:\HelloWorld, for example.

Syntax

HRESULT GetSourceFileDir(LPOLESTR *ppszSourceFileDir)

Parameters

[out] *ppszSourceFileDir Returns the name of the source file directory containing the source file that was compiled to create this class.

Return Value

S_OK Success.

E_FAIL This class has no SourceDir attribute.

E_OUTOFMEMORY Insufficient memory.


IRemotePrimitiveClassField : IRemoteClassField

The IRemotePrimitiveClassField interface represents a Java primitive data type. A debugger typically obtains an IRemotePrimitiveClassField interface by calling QueryInterface for IID_IRemotePrimitiveClassField on an IRemoteClassField interface provided by the Microsoft VM. Note that some of the methods on this interface that are inherited from IRemoteClassField will fail (GetSourceFileName and GetSourceFileDir, for example) when applied to a primitive data type.

  // Methods
  HRESULT GetPrimitiveType(PRIMITIVE_TYPE *pPrimitiveType)


Methods (IRemotePrimitiveClassField Interface)

 Microsoft SDK for Java

IRemotePrimitiveClassField Interface Methods

The IRemotePrimitiveClassField interface contains the GetPrimitiveType method, which returns the Java primitive type of a field if the field is of a Java primitive type.


IRemotePrimitiveClassField::GetPrimitiveType

 Microsoft SDK for Java

IRemotePrimitiveClassField::
GetPrimitiveType

The GetPrimitiveType method of the IRemotePrimitiveClassField interface returns the Java primitive type of a field if the field is of a Java primitive type.

Syntax

HRESULT GetPrimitiveType(PRIMITIVE_TYPE *pPrimitiveType)

Parameters

[out] pPrimitiveType Returns the type of the Java primitive field.

Return Value

S_OK Success.

E_FAIL The field is not of a Java primitive type.

Remarks

Java primitive types are defined in the PRIMITIVE_TYPE enumeration as shown in the following table.

Primitive Types Returned by GetPrimitiveType

PRIMITIVE_TYPE enum | Value | Description
PRIMITIVE_VOID | 1 | Void
PRIMITIVE_BOOLEAN | 2 | A Java boolean.
PRIMITIVE_BYTE | 3 | A Java byte.
PRIMITIVE_CHAR | 4 | A Java char.
PRIMITIVE_SHORT | 5 | A Java short.
PRIMITIVE_INT | 6 | A Java integer.
PRIMITIVE_FLOAT | 7 | A Java float.
PRIMITIVE_LONG | 8 | A Java long.
PRIMITIVE_DOUBLE | 9 | A Java double.


IRemoteInnerClassField : IRemoteClassFieldEx

The IRemoteInnerClassField interface represents a Java inner class. A debugger typically obtains an IRemoteInnerClassField interface by calling QueryInterface for IID_IRemoteInnerClassField on an IRemoteClassField interface provided by the Microsoft VM.

  // Methods
  HRESULT GetInnerClassModifiers(FIELDMODIFIERS *pulModifiers)
  HRESULT GetInnerClassName(LPOLESTR *ppszName)
  HRESULT GetOuterClass(IRemoteClassField **ppOuterClass)


Methods (IRemoteInnerClassField Interface)

 Microsoft SDK for Java

IRemoteInnerClassField Interface Methods

The IRemoteInnerClassField interface contains the following methods:

GetInnerClassModifiers returns a bitmask of flags from the FIELDMODIFIERS enumeration describing the modifiers of this inner class.
GetInnerClassName returns the original name of the inner class, not the decorated class name generated by the Java compiler.
GetOuterClass returns an IRemoteClassField interface representing the outer class of this inner class.


IRemoteInnerClassField::GetInnerClassModifiers

 Microsoft SDK for Java

IRemoteInnerClassField::
GetInnerClassModifiers

The GetInnerClassModifiers method of the IRemoteInnerClassField interface returns a bitmask of flags from the FIELDMODIFIERS enumeration describing the modifiers of this inner class.

Syntax

HRESULT GetInnerClassModifiers (FIELDMODIFIERS *pulModifiers)

Parameters

[out] pulModifiers Returns the modifiers for this inner class.

Return Value

S_OK Success.


IRemoteInnerClassField::GetInnerClassName

 Microsoft SDK for Java

IRemoteInnerClassField::
GetInnerClassName

The GetInnerClassName method of the IRemoteInnerClassField returns the original name of the inner class, not the decorated class name generated by the Java compiler.

Syntax

HRESULT GetInnerClassName(LPOLESTR *ppszName)

Parameters

[out] ppszName Returns the original name of the inner class.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IRemoteInnerClassField::GetOuterClass

 Microsoft SDK for Java

IRemoteInnerClassField::
GetOuterClass

The GetOuterClass method of the IRemoteInnerClassField returns an IRemoteClassField interface representing the outer class of this inner class.

Syntax

HRESULT GetOuterClass(IRemoteClassField **ppOuterClass)

Parameters

[out] ppOuterClass Returns the outer class of this inner class.

Return Value

S_OK Success.

S_FALSE This class has no outer class; ppOuterClass is NULL.

E_CLASSNOTFOUND Unable to load the outer class of this inner class.

E_OUTOFMEMORY Insufficient memory.


IRemoteMethodField : IRemoteContainerField

The IRemoteMethodField interface represents a Java method.

  // Methods
  HRESULT ClearBreakpoint(ULONG offPC)
  HRESULT GetBytes(ILockBytes **ppLockBytes)
  HRESULT GetIndexedField(ULONG slot, ULONG offPC,
    IRemoteField **ppField)
  HRESULT GetLineInfo(IJavaEnumLINEINFO **ppEnum)
  HRESULT GetScope(IRemoteField *pField, ULONG *poffStart,
    ULONG *pcbScope)
  HRESULT SetBreakpoint(ULONG offPC)


Methods (IRemoteMethodField Interface)

 Microsoft SDK for Java

IRemoteMethodField Interface Methods

The IRemoteMethodField interface contains the following methods:

ClearBreakpoint has been superseded by IMethodLocation::ClearBreakpoint.
GetBytes returns an ILockBytes interface that can be used to obtain the Java bytecodes of this method.
GetIndexedField returns a local variable or parameter field from this method by its local variable index at a given bytecode offset in this method.
GetLineInfo returns an IJavaEnumLINEINFO enumerator of LINEINFO structures describing the mapping between source lines and bytecode offsets within the Java bytecodes representing the method.
GetScope returns the range of bytecode offsets within which the given field is in scope in this method.
SetBreakpoint has been superseded by IMethodLocation::SetBreakpoint.


IRemoteMethodField::ClearBreakpoint

 Microsoft SDK for Java

IRemoteMethodField::
ClearBreakpoint

This method of the IRemoteMethodField interface has been superseded by IMethodLocation::ClearBreakpoint. New debuggers should call that method instead.

The ClearBreakpoint method clears a code breakpoint at a given bytecode offset from the start of this method. IRemoteMethodField::ClearBreakpoint only clears code breakpoints set by IRemoteMethodField::SetBreakpoint.

Syntax

HRESULT ClearBreakpoint(ULONG offPC)

Parameters

[in] offPC The bytecode offset within this method at which to clear a code breakpoint.

Return Value

S_OK The code breakpoint was cleared.

E_FAIL No code breakpoint was set at the given bytecode offset in this method.

Remarks

If a code breakpoint is set multiple times, it must be cleared the same number of times to completely eliminate it.


IRemoteMethodField::GetBytes

 Microsoft SDK for Java

IRemoteMethodField::
GetBytes

The GetBytes method of the IRemoteMethodField interface returns an ILockBytes interface that can be used to obtain the Java bytecodes of this method. A debugger can use this method to display a disassembly of the method's bytecodes.

Syntax

HRESULT GetBytes(ILockBytes **ppLockBytes)

Parameters

[out] ppLockBytes Returns an ILockBytes interface that can be used to access this method's bytecodes.

Return Value

S_OK Success.

E_FAIL if the method has no bytecode (as with a native method) or it is a JIT method with no source line mapping information.


IRemoteMethodField::GetIndexedField

 Microsoft SDK for Java

IRemoteMethodField::
GetIndexedField

The GetIndexedField method of the IRemoteMethodField interface can be used by debuggers that understand the local variable slot layouts of Java methods. A method's local variable slots contain the arguments to the method in addition to the local variables.

The local variable slots may be re-used in the method. Therefore, at one computer a slot may contain one local variable, while at another computer it may contain a different local variable.

To determine what the local variable slots in a method are used for, the debugger typically performs bytecode disassembly on the method. Local variable slot indexes are zero-based.

Syntax

HRESULT GetIndexedField(ULONG slot, ULONG offPC, IRemoteField **ppField)

Parameters

[in] slot | The slot in this method of the field to be retrieved.
[in] offPC | The bytecode offset within this method indicating the given slot's point of execution.
[out] ppField | Returns the field contained by the given slot at the given bytecode offset.

Return Value

S_OK Success.

E_FAIL There is no field in the given slot at the given bytecode offset.


IRemoteMethodField::GetLineInfo

 Microsoft SDK for Java

IRemoteMethodField::
GetLineInfo

The GetLineInfo method of the IRemoteMethodField interface returns an IJavaEnumLINEINFO enumerator of LINEINFO structures. These structures describe the mapping between source lines and bytecode offsets within the Java bytecodes representing the method. This mapping is in order of increasing bytecode offset. The last element in the enumeration is a "dummy" LINEINFO with a line number field set to 0 (zero) and the offset field set to a bytecode offset just past the end of the method.

Syntax

HRESULT GetLineInfo(IJavaEnumLINEINFO **ppEnum)

Parameters

[out] ppEnum Returns an enumerator of LINEINFO structures.

Return Value

S_OK Success.

E_FAIL This method cannot have bytecode source line mapping information.

E_NODEBUGINFORMATION This method does not have bytecode source line mapping information.

E_OUTOFMEMORY Insufficient memory.


IRemoteMethodField::GetScope

 Microsoft SDK for Java

IRemoteMethodField::
GetScope

The GetScope method of the IRemoteMethodField interface returns the range of bytecode offsets within which the given field is in scope in this method. If a field is in scope at the current point of execution in this method, its value can be obtained by the debugger.

Syntax

HRESULT GetScope(IRemoteField *pField, ULONG *poffStart, ULONG *pcbScope)

Parameters

[in] pField | The field whose scope within this method is to be determined.
[out] poffStart | The bytecode offset within this method where the scope of the given field begins.
[out] pcbScope | The length of the scope of the given field in this method, in bytes.

Return Value

S_OK Success.

E_FAIL The given field is not a field of this method.


IRemoteMethodField::SetBreakpoint

 Microsoft SDK for Java

IRemoteMethodField::
SetBreakpoint

This method of the IRemoteMethodField interface has been superseded by IMethodLocation::SetBreakpoint. New debuggers should call that method instead.

The SetBreakpoint method sets a code breakpoint at a given bytecode offset from the start of this method. If the code breakpoint is hit, the Microsoft VM will call the debugger’s IRemoteProcessCallbackEx2::CodeBreakpointEvent method.

Syntax

HRESULT SetBreakpoint(ULONG offPC)

Parameters

[in] offPC The bytecode offset within this method at which to set a code breakpoint.

Return Value

S_OK Success.

E_FAIL Unable to set a code breakpoint at the given bytecode offset in this method.

E_OUTOFMEMORY Insufficient memory.

Remarks

The Microsoft VM will not validate that the given offset corresponds to the beginning of a bytecode instruction. A code breakpoint can be set at any offset within the method’s bytecodes. Breakpoints are reference counted and can be set multiple times at the same bytecode offset.


IRemoteMethodFieldEx : IRemoteMethodField

The IRemoteMethodFieldEx interface represents a Java method. A debugger typically obtains an IRemoteMethodFieldEx interface by calling QueryInterface for IID_IRemoteMethodFieldEx on an IRemoteMethodField interface provided by the Microsoft VM.

  // Methods
  HRESULT GetCodeBreakpoints(IEnumCodeBreakpoints **ppiecbp)
  HRESULT GetMethodLocationForPC(ULONG ulPC, IMethodLocation **ppiml)


Methods (IRemoteMethodFieldEx Interface)

 Microsoft SDK for Java

IRemoteMethodFieldEx Interface Methods

The IRemoteMethodFieldEx interface contains the following methods:

GetCodeBreakpoints returns an IEnumCodeBreakpoints enumerator of code breakpoints that have been set in this method only through IMethodLocation::SetBreakpoint method calls.
GetMethodLocationForPC returns the IMethodLocation interface representing a given interpreted bytecode offset in this method.


IRemoteMethodFieldEx::GetCodeBreakpoints

 Microsoft SDK for Java

IRemoteMethodFieldEx::
GetCodeBreakpoints

The GetCodeBreakpoints method of the IRemoteMethodFieldEx interface returns an IEnumCodeBreakpoints enumerator of code breakpoints that have been set in this method only through IMethodLocation::SetBreakpoint method calls. This enumeration does not include code breakpoints set using IRemoteMethodField::SetBreakpoint.

Syntax

HRESULT GetCodeBreakpoints(IEnumCodeBreakpoints **ppiecbp)

Parameters

[out] ppiecbp Returns an enumerator of the code breakpoints set in this method using the IMethodLocation::SetBreakpoint method.

Return Value

S_OK Success.

E_NOBREAKPOINTS No code breakpoints are set in this method by IMethodLocation::SetBreakpoint.

E_OUTOFMEMORY Insufficient memory.


IRemoteMethodFieldEx::GetMethodLocationForPC

 Microsoft SDK for Java

IRemoteMethodFieldEx::
GetMethodLocationForPC

The GetMethodLocationForPC method of the IRemoteMethodFieldEx interface returns the IMethodLocation interface representing a given interpreted bytecode offset in this method.

Syntax

HRESULT GetMethodLocationForPC(ULONG ulPC, IMethodLocation **ppiml)

Parameters

[in] ulPC | The interpreted bytecode offset for which the method location is requested.
[out] ppiml | Returns the method location for the given interpreted bytecode offset in this method.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.

Remarks

The Microsoft VM will not validate that the given offset corresponds to the beginning of a bytecode instruction. A method location can be obtained for any offset within the method’s bytecodes.


IEnumRemoteField : IUnknown

The IEnumRemoteField interface enumerates all the fields contained within a class, method, or container.

  // Methods
  HRESULT Clone(IJavaEnumRemoteField **ppEnum)
  HRESULT GetCount(ULONG *pcelt)
  HRESULT Next(ULONG celt, IRemoteField *rgelt[], ULONG *pceltFetched)
  HRESULT Reset(void)
  HRESULT Skip(ULONG celt)


Methods (IEnumRemoteField Interface)

 Microsoft SDK for Java

IEnumRemoteField Interface Methods

The IEnumRemoteField interface contains the following methods:

Clone copies a pointer to the current position in the list to another enumerator object.
GetCount returns the number of fields being pointed to by the enumerator object.
Next retrieves an array of IRemoteField objects that represent the fields within a class, method, or container.
Reset sets or resets the positions of the enumerator to the beginning of the field list.
Skip moves the position of the enumeration forward.


IEnumRemoteField::Clone

 Microsoft SDK for Java

IEnumRemoteField::
Clone

The Clone method of the IEnumRemoteField interface copies a pointer to the current position in the list to another enumerator object.

Syntax

HRESULT Clone(IJavaEnumRemoteField **ppEnum)

Parameters

[out] **ppEnum Returns an enumerator object pointing to the fields in a class, method, or container representing the current position in the list of fields.


IEnumRemoteField::GetCount

 Microsoft SDK for Java

IEnumRemoteField::
GetCount

The GetCount method of the IEnumRemoteField interface returns the number of fields being pointed to by the enumerator object.

Syntax

HRESULT GetCount (ULONG *pcelt)

Parameters

[out] *pcelt The number of fields pointed to by the enumerator object.


IEnumRemoteField::Next

 Microsoft SDK for Java

IEnumRemoteField::
Next

The Next method of the IEnumRemoteField interface retrieves an array of IRemoteField objects that represent the fields within a class, method, or container. The number of fields to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

Syntax

HRESULT Next(ULONG celt, IRemoteField *rgelt[], ULONG *pceltFetched)

Parameters

[in] celt | The number of IRemoteField objects requested to be retrieved.
[out] *rgelt[] | The pointer to the array of IRemoteField objects that is retrieved.
[out] *pceltFetched | The number of actual IRemoteField objects that were retrieved.


IEnumRemoteField::Reset

 Microsoft SDK for Java

IEnumRemoteField::
Reset

The Reset method of the IEnumRemoteField interface sets or resets the positions of the enumerator to the beginning of the field list.

Syntax

HRESULT Reset(void)


IEnumRemoteField::Skip

 Microsoft SDK for Java

IEnumRemoteField::
Skip

The Skip method of the IEnumRemoteField interface moves the position of the enumeration forward. The number of objects to be skipped is based on a parameter passed to the method.

Syntax

HRESULT Skip(ULONG celt)

Parameters

[in] celt The number of IRemoteField objects requested to be skipped.


IJavaEnumRemoteField : IEnumRemoteField

The IJavaEnumRemoteField interface enumerates IRemoteField pointers. It enumerates fields in a container, such as a class or method.

  // Methods
  HRESULT Clone(IJavaEnumRemoteField **ppEnum)
  HRESULT GetCount(ULONG *pcelt)
  HRESULT GetNext(IRemoteField **ppirf)
  HRESULT Next(ULONG celt, IRemoteField *rgelt[], ULONG *pceltFetched)
  HRESULT Reset(void)
  HRESULT Skip(ULONG celt)


Methods (IJavaEnumRemoteField Interface)

 Microsoft SDK for Java

IJavaEnumRemoteField Interface Methods

The IJavaEnumRemoteField interface contains the following methods:

Clone copies a pointer to the current position in the list to another enumerator object.
GetCount returns the number of fields being pointed to by the enumerator object.
GetNext retrieves the next IRemoteField object being pointed to by the enumerator object and increments the enumeration pointer by one.
Next retrieves an array of IRemoteField objects that represent the fields within a class, method, or container.
Reset sets or resets the positions of the enumerator to the beginning of the field list.
Skip moves the position of the enumeration forward.


IJavaEnumRemoteField::Clone

 Microsoft SDK for Java

IJavaEnumRemoteField::
Clone

The Clone method of the IJavaEnumRemoteField interface copies a pointer to the current position in the list to another enumerator object.

Syntax

HRESULT Clone(IJavaEnumRemoteField **ppEnum)

Parameters

[out] **ppEnum Returns an enumerator object pointing to the fields in a class, method, or container representing the current position in the list of fields.


IJavaEnumRemoteField::GetCount

 Microsoft SDK for Java

IJavaEnumRemoteField::
GetCount

The GetCount method of the IJavaEnumRemoteField interface returns the number of fields being pointed to by the enumerator object.

Syntax

HRESULT GetCount (ULONG *pcelt)

Parameters

[out] *pcelt The number of fields pointed to by the enumerator object.


IJavaEnumRemoteField::GetNext

 Microsoft SDK for Java

IJavaEnumRemoteField::
GetNext

The GetNext method of the IJavaEnumRemoteField interface retrieves the next IRemoteField object being pointed to by the enumerator object and increments the enumeration pointer by one.

Syntax

HRESULT GetNext(IRemoteField **ppirf)

Parameters

[out] **ppirf The pointer to the IRemoteField object that is retrieved.


IJavaEnumRemoteField::Next

 Microsoft SDK for Java

IJavaEnumRemoteField::
Next

The Next method of the IJavaEnumRemoteField interface retrieves an array of IRemoteField objects that represent the fields within a class, method, or container. The number of fields to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

Syntax

HRESULT Next(ULONG celt, IRemoteField *rgelt[], ULONG *pceltFetched)

Parameters

[in] celt | The number of IRemoteField objects requested to be retrieved.
[out] *rgelt[] | The pointer to the array of IRemoteField objects that is retrieved.
[out] *pceltFetched | The number of actual IRemoteField objects that were retrieved.


IJavaEnumRemoteField::Reset

 Microsoft SDK for Java

IJavaEnumRemoteField::
Reset

The Reset method of the IJavaEnumRemoteField interface sets or resets the positions of the enumerator to the beginning of the field list.

Syntax

HRESULT Reset(void)


IJavaEnumRemoteField::Skip

 Microsoft SDK for Java

IJavaEnumRemoteField::
Skip

The Skip method of the IJavaEnumRemoteField interface moves the position of the enumeration forward. The number of objects to be skipped is based on a parameter passed to the method.

Syntax

HRESULT Skip(ULONG celt)

Parameters

[in] celt The number of IRemoteField objects requested to be skipped.


IEnumLINEINFO : IUnknown

The IEnumLINEINFO interface provides access to line number information. Line number information represents the mapping between Java source code line numbers and byte offsets in the method. This information is represented as an array of LINEINFO structures maintained for each method.

  // Methods
  HRESULT Next(ULONG celt, LPLINEINFO *rgelt[], ULONG *pceltFetched)
  HRESULT Skip(ULONG celt)
  HRESULT Reset(void)
  HRESULT Clone(IJavaEnumLINEINFO **ppEnum)
  HRESULT GetCount(ULONG * pcelt)


Methods (IEnumLINEINFO Interface)

 Microsoft SDK for Java

IEnumLINEINFO Interface Methods

The IEnumLINEINFO interface contains the following methods:

Clone copies a pointer to the current position in the list to another enumerator object.
GetCount returns the number of LINEINFO structures being pointed to by the enumerator object.

Next retrieves an array of LINEINFO structures that represent the mapping between Java source code line numbers and byte offsets in the method.

Reset sets or resets the positions of the enumerator to the beginning of the list of LINEINFO structures.
Skip moves the position of the enumeration forward.


IEnumLINEINFO::Clone

 Microsoft SDK for Java

IEnumLINEINFO::
Clone

The Clone method copies a pointer to the current position in the list to another enumerator object.

Syntax

HRESULT Clone(IJavaEnumLINEINFO **ppEnum)

Parameters

[out] ppEnum Returns an enumerator object representing the current position in the list of LINEINFO structures.


IEnumLINEINFO::GetCount

 Microsoft SDK for Java

IEnumLINEINFO::
GetCount

The GetCount method returns the number of LINEINFO structures being pointed to by the enumerator object.

Syntax

HRESULT GetCount(ULONG * pcelt)

Parameters

[out] pcelt The number of LINEINFO structures pointed to by the enumerator object.


IEnumLINEINFO::Next

 Microsoft SDK for Java

IEnumLINEINFO::
Next

The Next method is used to retrieve an array of LINEINFO structures that represent the mapping between Java source code line numbers and byte offsets in the method. The number of LINEINFO structures to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

Syntax

HRESULT Next(ULONG celt, LPLINEINFO *rgelt[], ULONG *pceltFetched)

Parameters

[in] celt | The number of LINEINFO structures requested to be retrieved.
[out] drgelt | The pointer to the array of LINEINFO structures that are retrieved.
[out] pceltFetched | The number of actual LINEINFO structures that was retrieved.


IEnumLINEINFO::Reset

 Microsoft SDK for Java

IEnumLINEINFO::
Reset

The Reset method sets or resets the positions of the enumerator to the beginning of the list of LINEINFO structures.

Syntax

HRESULT Reset(void)


IEnumLINEINFO::Skip

 Microsoft SDK for Java

IEnumLINEINFO::
Skip

The Skip method moves the position of the enumeration forward. The number of LINEINFO structures to be skipped is based on a parameter passed to the method.

Syntax

HRESULT Skip(ULONG celt)

Parameters

[in] celt The number of LINEINFO structures requested to be skipped.


IJavaEnumLINEINFO : IEnumLINEINFO

The IJavaEnumLINEINFO interface provides access to line number information. Line number information represents the mapping between Java source code line numbers and byte offsets in the method. This information is represented as an array of LINEINFO structures maintained for each method. The IJavaEnumLINEINFO interface derives from IEnumLINEINFO and adds one method.

  // Methods
  HRESULT Next(ULONG celt, LPLINEINFO rgelt[], ULONG *pceltFetched)
  HRESULT Skip(ULONG celt)
  HRESULT Reset(void)
  HRESULT Clone(IJavaEnumLINEINFO **ppEnum)
  HRESULT GetCount(ULONG *pcelt)
  HRESULT GetNext(LPLINEINFO *pli)

Remarks

The LINEINFO structure is defined as follows:

typedef struct lineinfo
{
  USHORT offPC;  // bytecode offset in method
  USHORT iLine;  // line number, first line is line 1
}
LINEINFO;


Methods (IJavaEnumLINEINFO Interface)

 Microsoft SDK for Java

IJavaEnumLINEINFO Interface Methods

The IJavaEnumLINEINFO interface includes the following methods:

Clone copies a pointer to the current position in the list to another enumerator object.
GetCount returns the number of LINEINFO structures being pointed to by the enumerator object.
GetNext retrieves the next LINEINFO structure being pointed to by the enumerator object and increments the enumeration pointer by one.
Next retrieves an array of LINEINFO structures that represent the mapping between Java source code line numbers and byte offsets in the method.
Reset sets or resets the positions of the enumerator to the beginning of the list of LINEINFO structures.
Skip moves the position of the enumeration forward.


IJavaEnumLINEINFO::Next

 Microsoft SDK for Java

IJavaEnumLINEINFO::
Next

The Next method of the IJavaEnumLINEINFO interface is used to retrieve an array of LINEINFO structures that represent the mapping between Java source code line numbers and byte offsets in the method. The number of LINEINFO structures to be retrieved is passed as one of the parameters; the enumeration pointer is incremented by that amount.

Syntax

HRESULT Next(ULONG celt, LPLINEINFO rgelt[], ULONG *pceltFetched)

Parameters

[in] celt | The number of LINEINFO structures requested to be retrieved.
[out] drgelt | The pointer to the array of LINEINFO structures that are retrieved.
[out] *pceltFetched | The number of actual LINEINFO structures that was retrieved.


IJavaEnumLINEINFO::Skip

 Microsoft SDK for Java

IJavaEnumLINEINFO::
Skip

The Skip method of the IJavaEnumLINEINFO interface moves the position of the enumeration forward. The number of LINEINFO structures to be skipped is based on a parameter passed to the method.

Syntax

HRESULT Skip(ULONG celt)

Parameters

[in] celt The number of LINEINFO structures to be skipped.


IJavaEnumLINEINFO::Reset

 Microsoft SDK for Java

IJavaEnumLINEINFO::
Reset

The Reset method of the IJavaEnumLINEINFO interface sets or resets the positions of the enumerator to the beginning of the list of LINEINFO structures.

Syntax

HRESULT Reset(void)


IJavaEnumLINEINFO::Clone

 Microsoft SDK for Java

IJavaEnumLINEINFO::
Clone

The Clone method of the IJavaEnumLINEINFO interface copies a pointer to the current position in the list to another enumerator object.

Syntax

HRESULT Clone(IJavaEnumLINEINFO **ppEnum)

Parameters

[out] **ppEnum Returns an enumerator object representing the current position in the list of LINEINFO structures.


IJavaEnumLINEINFO::GetCount

 Microsoft SDK for Java

IJavaEnumLINEINFO::
GetCount

The GetCount method of the IJavaEnumLINEINFO interface returns the number of LINEINFO structures being pointed to by the enumerator object.

Syntax

HRESULT GetCount(ULONG *pcelt)

Parameters

[out] *pcelt The number of LINEINFO structures pointed to by the enumerator object.


IJavaEnumLINEINFO::GetNext

 Microsoft SDK for Java

IJavaEnumLINEINFO::
GetNext

The GetNext method of the IJavaEnumLINEINFO interface is used to retrieve the next LINEINFO structure being pointed to by the enumerator object and increments the enumeration pointer by one.

Syntax

HRESULT GetNext(LPLINEINFO *pli)

Parameters

[out] *pli The pointer to the LINEINFO structure that is retrieved.


Dynamic Information Debugger Interfaces Overview

Debugger Interfaces Reference

Dynamic information on a Java process is available through the IRemoteObject hierarchy of interfaces. These interfaces provide bound access to objects of different types. These objects are not necessarily class instances, but may be instances of any type. The information obtained from an IRemoteObject is only valid during the lifetime of the object it represents. Therefore, the debugger cannot cache dynamic information.

For general information, see Retrieving Dynamic Information in the Programmer's Guide.

Access to dynamic information in a Java process is based on using the IRemoteThreadGroup and IRemoteThread passed on each ThreadGroupCreateEvent and ThreadCreateEvent notification to the debugger. The IRemoteProcess:GetGlobalContainerObject method can also be used to access the root of this object hierarchy and descend down it to retrieve IRemoteClassField objects.

The dynamic information interfaces consist primarily of IRemoteObject, IRemoteObjectEx, IEnumRemoteObject, the IEnumRemoteValue interfaces, and a collection of other interfaces designed for a specific Java object (primitive data types, arrays, or classes) that inherit from IRemoteObject or IEnumRemoteValue.

This section contains the following:

Interfaces

Hierarchy


Dynamic Information Debugger Interfaces

The dynamic information debugger interfaces are as follows:

IRemoteObject represents bound access to objects of different types in a Java process.

IRemoteXXXXObject is an abstraction of some of the Java primitive type variable manipulation interfaces.

IRemoteObjectEx represents bound access to objects in a Java process.

IRemoteArrayObject represents bound access to a Java array object.

IRemoteBooleanObject manipulates the value of a Java boolean variable.

IRemoteByteObject manipulates the value of a Java byte variable.

IRemoteCharObject manipulates the value of a Java character variable.

IRemoteContainerObject provides run-time access to a container object (an object reference or a running method) in a Java process.

IRemoteClassObject provides run-time access to a class object in a Java process.

IRemoteDoubleObject manipulates the value of a Java double variable.

IRemoteFloatObject manipulates the value of a Java float variable.

IRemoteIntObject manipulates the value of a Java integer variable.

IRemoteLongObject manipulates the value of a Java long variable.

IRemoteShortObject manipulates the value of a Java short variable.

IEnumXXXX represents an abstraction of some of the enumeration interfaces.

IJavaEnumXXXX represents an abstraction of some of the enumeration interfaces.

IJavaEnumRemoteObject enumerates IRemoteObject pointers.

IEnumRemoteValue is a base interface whose derived interfaces enumerate values of elements in Java arrays of primitive values.

IJavaEnumRemoteBooleanValue enumerates the values of the elements in a Java array of booleans.

IJavaEnumRemoteByteValue enumerates the values of the elements in a Java array of bytes.

IJavaEnumRemoteCharValue enumerates the values of the elements in a Java array of characters.

IJavaEnumRemoteDoubleValue enumerates the values of the elements in a Java array of doubles.

IJavaEnumRemoteFloatValue enumerates the values of the elements in a Java array of floats.

IJavaEnumRemoteIntValue enumerates the values of the elements in a Java array of integers.

IJavaEnumRemoteLongValue enumerates the values of the elements in a Java array of longs.

IJavaEnumRemoteShortValue enumerates the values of the elements in a Java array of shorts.


Dynamic Information Debugger Interfaces Hierarchy

The dynamic information debugger interfaces have the following hierarchy:

IUnknown
  |
  +--IRemoteObject
  |  |
  |  +--IRemoteXXXXObject
  |  |
  |  +--IRemoteObjectEx
  |  |
  |  +--IRemoteBooleanObject
  |  |
  |  +--IRemoteByteObject
  |  |
  |  +--IRemoteCharObject
  |  |
  |  +--IRemoteContainerObject
  |  |  |
  |  |  +--IRemoteClassObject
  |  |
  |  +--IRemoteDoubleObject
  |  |
  |  +--IRemoteFloatObject
  |  |
  |  +--IRemoteIntObject
  |  |
  |  +--IRemoteLongObject
  |  |
  |  +--IRemoteShortObject
  |  |
  |  +--IRemoteArrayObject
  |
  +--IEnumXXXX
  |  |
  |  +--IJavaEnumXXXX
  |
  +--IEnumRemoteObject
  |  |
  |  +--IJavaEnumRemoteObject
  |
  +--IEnumRemoteValue
  |  |
  |  +--IEnumRemoteBooleanValue
  |  |
  |  |  +--IJavaEnumRemoteBooleanValue
  |  |
  |  +--IEnumRemoteByteValue
  |  |
  |  |  +--IJavaEnumRemoteByteValue
  |  |
  |  +--IEnumRemoteCharValue
  |  |
  |  |  +--IJavaEnumRemoteCharValue : IEnumRemoteCharValue
  |  |
  |  +--IEnumRemoteDoubleValue
  |  |
  |  |  +--IJavaEnumRemoteDoubleValue
  |  |
  |  +--IEnumRemoteFloatValue
  |  |
  |  |  +--IJavaEnumRemoteFloatValue
  |  |
  |  +--IEnumRemoteIntValue
  |  |
  |  |  +--IJavaEnumRemoteIntValue
  |  |
  |  +--IEnumRemoteLongValue
  |  |
  |  |  +--IJavaEnumRemoteLongValue
  |  |
  |  +--IEnumRemoteShortValue
  |  |
  |  |  +--IJavaEnumRemoteShortValue


IRemoteObject : IUnknown

The IRemoteObject hierarchy of interfaces represents bound access to objects of different types in a Java process. The information obtained from an IRemoteObject is only valid during the lifetime of the actual object that it represents. Consequently, dynamic information cannot be cached by the debugger across execution of the object being debugged.

  // Methods
  HRESULT ClearBreakpoint(void)
  HRESULT GetType(IRemoteField **ppType)
  HRESULT SetBreakpoint(void)


Methods (IRemoteObject Interface)

 Microsoft SDK for Java

IRemoteObject Interface Methods

The IRemoteObject interface contains the following methods:

ClearBreakpoint clears a data breakpoint on this object that was previously set by SetBreakpoint.

GetType returns an IRemoteField interface that represents the type of this object.

SetBreakpoint sets a data breakpoint on this object.


IRemoteObject::ClearBreakpoint

 Microsoft SDK for Java

IRemoteObject::
ClearBreakpoint

The ClearBreakpoint method of the IRemoteObject interface clears a data breakpoint on this object that was previously set by SetBreakpoint.

Syntax

HRESULT ClearBreakpoint(void)

Return Value

S_OK The data breakpoint was cleared.

E_FAIL No data breakpoint was set on this variable.


IRemoteObject::GetType

 Microsoft SDK for Java

IRemoteObject::
GetType

The GetType method of the IRemoteObject interface returns an IRemoteField interface that represents the type of this object. A debugger then normally calls IRemoteField::GetKind to determine the FIELDKIND of this object. The type will be an array type, a class type, or a Java primitive data type.

Syntax

HRESULT GetType(IRemoteField **ppType)

Parameters

[out] **ppType Returns an IRemoteField representing the type of this object.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IRemoteObject::SetBreakpoint

 Microsoft SDK for Java

IRemoteObject::
SetBreakpoint

The SetBreakpoint method of the IRemoteObject interface sets a data breakpoint on this object. If the data breakpoint is hit, the Microsoft VM will call the debugger's IRemoteProcessCallbackEx2::DataBreakpointEvent method.

Syntax

HRESULT SetBreakpoint(void)

Return Value

S_OK Success.

E_FAIL Unable to set a data breakpoint on this object.

E_TOOMANYBREAKPOINTS The maximum number of data breakpoints of the type required by this object's location have already been set. For example, if page breakpoints are disabled and the maximum number of hardware breakpoints supported by the processor architecture has already been used, this error code will be returned. Breakpoints in stack frame objects (local variables) are restricted to hardware breakpoints. This error might be returned even if page breakpoints are enabled.

E_OUTOFMEMORY Insufficient memory.

Remarks

For a primitive variable, the value of the variable changes when the variable is assigned a value. For an object reference variable, the value of the variable changes when the variable references a different instance of that class, not when any of the instance's data members change. For an array variable, the value of the variable changes when the variable references a different array, not when any of the array's elements change.


IRemoteObjectEx : IRemoteObject

The IRemoteObjectEx interface represents bound access to objects in a Java process. A debugger typically obtains an IRemoteObjectEx interface by calling QueryInterface for IID_IRemoteObjectEx on an IRemoteObject interface provided by the Microsoft VM.

  // Methods
  HRESULT GetContainer(IRemoteObject **ppContainer)
  HRESULT GetIdentity(IRemoteObjectEx **ppIdentity)
  HRESULT IsSameObject(IRemoteObject *other)


Methods (IRemoteObjectEx Interface)

 Microsoft SDK for Java

IRemoteObjectEx Interface Methods

The IRemoteObjectEx interface contains the following methods:

GetContainer returns an IRemoteObject interface representing the container of this object.

GetIdentity returns a new IRemoteObjectEx interface that is detached from any container.

IsSameObject determines whether a given IRemoteObject interface represents this object.


IRemoteObjectEx::GetContainer

 Microsoft SDK for Java

IRemoteObjectEx::
GetContainer

The GetContainer method of the IRemoteObjectEx interface returns an IRemoteObject interface representing the container of this object.

Syntax

HRESULT GetContainer(IRemoteObject **ppContainer)

Parameters

[out] **ppContainer Returns the container of this object.

Return Value

S_OK Success.

Remarks

**ppContainer will be NULL if the object has no container.


IRemoteObjectEx::GetIdentity

 Microsoft SDK for Java

IRemoteObjectEx::
GetIdentity

The GetIdentity method of the IRemoteObjectEx interface returns a new IRemoteObjectEx interface that is detached from any container. This method is typically used for data breakpoints, and allows a debugger to retain an object reference across debuggee execution.

Syntax

HRESULT GetIdentity(IRemoteObjectEx **ppIdentity)

Parameters

[out] **ppIdentity Returns a new object representing the current object detached from all containers.

Return Value

S_OK Success.

E_FAIL This object is not a data object.

E_OUTOFMEMORY Insufficient memory.


IRemoteObjectEx::IsSameObject

 Microsoft SDK for Java

IRemoteObjectEx::
IsSameObject

The IsSameObject method of the IRemoteObjectEx interface determines whether a given IRemoteObject interface represents this object.

Syntax

HRESULT IsSameObject(IRemoteObject *other)

Parameters

[in] *other The other object to compare with this object.

Return Value

S_OK The given object is this object.

S_FALSE The given object is not this object.


IRemoteXXXXObject : IRemoteObj

 Microsoft SDK for Java

IRemoteXXXXObject : IRemoteObject

Manipulation of the value of a Java primitive type variable is a common operation supported by the Microsoft VM's debugger interfaces. The Java primitive type variable manipulation interfaces defined as part of the Microsoft VM's debugger interfaces follow a similar design model. Thus, the IRemoteXXXXObject interface is an abstraction of some of these interfaces. Each particular IRemoteXXXXObject interface differs from the others only in the data type returned by the GetValue method and set by the SetValue method. The Java primitive types are boolean, byte, char, double, float, int, long, and short.

  // Methods
  HRESULT GetValue(<variable_type> *pvalue)
  HRESULT SetValue(<variable_type> value)


Methods (IRemoteXXXXObject Interface)

 Microsoft SDK for Java

IRemoteXXXXObject Interface Methods

The IRemoteXXXXObject interface contains the following methods:

GetValue returns the value of a Java primitive type variable.

SetValue sets the value of a Java primitive type variable.


IRemoteXXXXObject::GetValue

 Microsoft SDK for Java

IRemoteXXXXObject::
GetValue

The GetValue method of the IRemoteXXXXObject interface returns the value of a Java primitive type variable.

Syntax

HRESULT GetValue(<variable_type> *pvalue)

Parameters

[out] *pvalue Returns the value of this Java primitive type variable.

Return Value

S_OK Success.

E_NOTINITIALIZED The variable's value has not yet been set.


IRemoteXXXXObject::SetValue

 Microsoft SDK for Java

IRemoteXXXXObject::
SetValue

The SetValue method of the IRemoteXXXXObject interface sets the value of a Java primitive type variable.

Syntax

HRESULT SetValue(<variable_type> value)

Parameters

[in] value The new value of this Java primitive type variable.

Return Value

S_OK Success.


IRemoteArrayObject : IRemoteObject

The IRemoteArrayObject interface represents bound access to a Java array object. The information obtained from an IRemoteArrayObject is valid only during the lifetime of the Java array object that it represents.

  // Methods
  GetElementObjects
  GetElementValues
  GetSize


Methods (IRemoteArrayObject Interface)

 Microsoft SDK for Java

IRemoteArrayObject Interface Methods

The IRemoteArrayObject interface contains the following methods:

GetElementObjects returns an IJavaEnumRemoteObject enumerator for the elements of this array of object references, starting at index 0 (zero).

GetElementValues returns an IJavaEnumRemoteValue enumerator for the values of the elements of this array of primitive data types, starting at index 0 (zero).

GetSize returns the number of elements in this array.


IRemoteArrayObject::GetElementObjects

 Microsoft SDK for Java

IRemoteArrayObject::
GetElementObjects

The GetElementObjects method of the IRemoteArrayObject interface returns an IJavaEnumRemoteObject enumerator for the elements of this array of object references, starting at index 0 (zero).

Syntax

HRESULT GetElementObjects(IJavaEnumRemoteObject **ppEnum)

Parameters

[out] ppEnum Returns an enumerator for the elements of this array of object references, starting at index 0 (zero).

Return Value

S_OK Success.

E_FAIL The elements of this array are not object references.

E_NOLONGERVALID The underlying object is no longer valid.

E_NULLOBJECTREF This object reference is the null object reference.

E_OUTOFMEMORY Insufficient memory.


IRemoteArrayObject::GetElementValues

 Microsoft SDK for Java

IRemoteArrayObject::
GetElementValues

The GetElementValues method of the IRemoteArrayObject interface returns an IJavaEnumRemoteValue enumerator for the values of the elements of this array of primitive data types, starting at index 0 (zero).

Syntax

HRESULT GetElementValues(IJavaEnumRemoteValue **ppEnum)

Parameters

[out] ppEnum Returns an enumerator for the values of the elements of this array of primitive data types, starting at index 0 (zero).

Return Value

S_OK Success.

E_FAIL The elements of this array are not of a primitive type.

E_NOLONGERVALID The underlying object is no longer valid.

E_NULLOBJECTREF This object reference is the null object reference.

E_OUTOFMEMORY Insufficient memory.


IRemoteArrayObject::GetSize

 Microsoft SDK for Java

IRemoteArrayObject::
GetSize

The GetSize method of the IRemoteArrayObject interface returns the number of elements in this array.

Syntax

HRESULT GetSize(ULONG *pcElements)

Parameters

[out] pcElements Returns the number of elements in this array.

Return Value

S_OK Success.

E_NOLONGERVALID The underlying object is no longer valid.

E_NULLOBJECTREF This object reference is the null object reference.

E_OUTOFMEMORY Insufficient memory.


IRemoteBooleanObject : IRemoteObject

The IRemoteBooleanObject interface manipulates the value of a Java boolean variable. See the IRemoteXXXXObject interface for details.

A Java boolean variable can be represented as a C or C++ typedef as follows:

typedef unsigned char JAVA_BOOLEAN;


IRemoteByteObject : IRemoteObject

The IRemoteByteObject interface manipulates the value of a Java byte variable. See the IRemoteXXXXObject interface for details.

A Java byte variable can be represented as a C or C++ typedef as follows:

typedef signed char JAVA_BYTE;


IRemoteCharObject : IRemoteObject

The IRemoteCharObject interface manipulates the value of a Java character variable. See the IRemoteXXXXObject interface for details.

A Java character variable can be represented as a C or C++ typedef as follows:

typedef unsigned short JAVA_CHAR;


IRemoteContainerObject : IRemoteObject

The IRemoteContainerObject interface provides runtime access to a container object (an object reference or a running method) in a Java process. The information obtained from the IRemoteContainerObject interface is valid only during the lifetime of the object that it represents.

  // Methods
  GetFieldObject


Methods (IRemoteContainerObject interface)

 Microsoft SDK for Java

IRemoteContainerObject Interface Methods

The IRemoteContainerObject interface contains the GetFieldObject method, which returns an IRemoteObject interface representing the given field in this container object.


IRemoteContainerObject::GetFieldObject

 Microsoft SDK for Java

IRemoteContainerObject::
GetFieldObject

The GetFieldObject method of the IRemoteContainerObject interface returns an IRemoteObject interface that represents the given field contained within this container object. The IRemoteObject interface that is returned is bound to this container object. A single IRemoteField interface can be used to extract the value of that field from many different container objects in the same Java process.

Syntax

HRESULT GetFieldObject(IRemoteField *pField, IRemoteObject **ppFieldObject)

Parameters

[in] *pField | The field in this container object whose runtime content is requested.
[out] **ppFieldObject | The object representing the runtime content of the given field in this container.

Return Value

S_OK Success.

E_FIELDNOTINOBJECT The given field is not in this container object.

E_FIELDOUTOFSCOPE The given field is out of scope in this method object.

E_NOLONGERVALID The content of the given field is no longer valid.

E_NOTINITIALIZED The given field has not yet been assigned.

E_NULLOBJECTREF The content of the given field is the null object reference.

E_OUTOFMEMORY Insufficient memory.

Remarks

Calling the GetType method on the returned IRemoteObject interface will return the original IRemoteField that was passed to the GetFieldObject method.

The Microsoft VM will not return E_NULLOBJECTREF from GetFieldObject if the MSJDBG_CREATE_NULL_OBJECTS (0x800) flag is set in the MSJAVA_DEBUGGING_FLAGS environment variable, or if the MSJAVA_DEBUGGING_FLAGS environment variable is not set and the MSJDBG_CREATE_NULL_OBJECTS flag is set in the DebuggingFlags DWORD value of the HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM registry key. Instead, the Microsoft VM will return an IRemoteObject interface representing the null object reference. This is necessary to enable a debugger to set a data breakpoint on an object reference that is currently null.

See Enabling Debugging in the Microsoft VM for more details on controlling the Microsoft VM's debugging options.


IRemoteClassObject : IRemoteContainerObject

The IRemoteClassObject interface provides runtime access to a class object in a Java process. The information obtained from the IRemoteClassObject interface is valid only during the lifetime of the class object that it represents.


Methods (IRemoteClassObject Interface)

 Microsoft SDK for Java

IRemoteClassObject Interface Methods

The IRemoteClassObject interface contains the GetDerivedMostType method, which returns an IRemoteClassField interface representing the object's derived-most type.


IRemoteClassObject::GetDerivedMostType

 Microsoft SDK for Java

IRemoteClassObject::
GetDerivedMostType

The GetDerivedMostType method of the IRemoteClassObject interface returns an IRemoteClassField interface that represents the object's derived-most type. For example, if the IRemoteClassObject represented an instance of the MyException class, and the MyException class was derived from the java.io.IOException class, the object's derived-most type would be the MyException class.

Syntax

HRESULT GetDerivedMostType(IRemoteClassField **ppDerivedMostField)

Parameters

[out] ppDerivedMostField The object's derived-most type.

Return Value

S_OK Success.

E_NOLONGERVALID The underlying object is no longer valid.

E_NOTINITIALIZED This object reference has not yet been initialized.

E_NULLOBJECTREF This object reference is the null object reference.

E_OUTOFMEMORY Insufficient memory.


IRemoteDoubleObject : IRemoteObject

The IRemoteDoubleObject interface manipulates the value of a Java double variable. See the IRemoteXXXXObject interface for details.

A Java double variable can be represented as a C or C++ typedef as follows:

typedef double JAVA_DOUBLE;


IRemoteFloatObject : IRemoteObject

The IRemoteFloatObject interface manipulates the value of a Java float variable. See the IRemoteXXXXObject interface for details.

A Java float variable can be represented as a C or C++ typedef as follows:

typedef float JAVA_FLOAT;


IRemoteIntObject : IRemoteObject

The IRemoteIntObject interface manipulates the value of a Java integer variable. See the IRemoteXXXXObject interface for details.

A Java integer variable can be represented as a C or C++ typedef as follows:

typedef signed long JAVA_INT;


IRemoteLongObject : IRemoteObject

The IRemoteLongObject interface manipulates the value of a Java long variable. See the IRemoteXXXXObject interface for details.

A Java long variable can be represented as a C or C++ typedef as follows:

typedef hyper JAVA_LONG;


IRemoteShortObject : IRemoteObject

The IRemoteShortObject interface manipulates the value of a Java short variable. See the IRemoteXXXXObject interface for details.

A Java short variable can be represented as a C or C++ typedef as follows:

typedef short int JAVA_SHORT;


IEnumXXXX : IUnknown

Enumeration of a list of elements is a common operation supported by the Microsoft VM's debugger interfaces. The enumeration interfaces defined as part of the Microsoft VM's debugger interfaces follow a similar design model. The IEnumXXXX interface represents an abstraction of some of the enumeration interfaces. Each particular IEnumXXXX enumeration interface differs from the others only in the type of element returned by the Next method.


Methods (IEnumXXXX Interface)

 Microsoft SDK for Java

IEnumXXXX Interface Methods

The IEnumXXXX interface contains the following methods:

Clone creates a copy of the enumerator, including the enumerator's current position in its list of elements.

GetCount returns the number of elements in the enumerator's list.

Next retrieves the next specified number of elements from the enumerator's list.

Reset resets the enumerator's current position in its list of elements to the first element in the list.

Skip moves the enumerator's current position ahead in its list of elements by the given number of elements.


IEnumXXXX::Clone

 Microsoft SDK for Java

IEnumXXXX::
Clone

The Clone method of the IEnumXXXX interface creates a copy of the enumerator, including the enumerator's current position in its list of elements.

Syntax

HRESULT Clone(IEnumXXXX **ppEnum)

Parameters

[out] ppEnum Returns a pointer to the copied enumerator.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IEnumXXXX::GetCount

 Microsoft SDK for Java

IEnumXXXX::
GetCount

The GetCount method of the IEnumXXXX interface returns the number of elements in the enumerator's list.

Syntax

HRESULT GetCount (ULONG *pcelt)

Parameters

[out] pcelt Returns the number of elements in the enumerator.

Return Value

S_OK Success.


IEnumXXXX::Next

 Microsoft SDK for Java

IEnumXXXX::
Next

The Next method of the IEnumXXXX interface retrieves the next specified number of elements from the enumerator's list.

Syntax

HRESULT Next(ULONG celt, <element_type> *rgelt[], ULONG *pceltFetched)

Parameters

[in] celt | The number of elements requested.
[out] rgelt | The array to be filled in with the elements.
[out] pceltFetched | The number of elements actually returned in rgelt. This can be less than celt if fewer than celt elements remained in the list.

Return Value

S_OK Celt elements were returned.

S_FALSE Fewer than celt elements were returned.


IEnumXXXX::Reset

 Microsoft SDK for Java

IEnumXXXX::
Reset

The Reset method of the IEnumXXXX interface resets the enumerator's current position in its list of elements to the first element in the list.

Syntax

HRESULT Reset(void)

Return Value

S_OK Success.


IEnumXXXX::Skip

 Microsoft SDK for Java

IEnumXXXX::
Skip

The Skip method of the IEnumXXXX interface moves the enumerator's current position ahead in its list of elements by the given number of elements.

Syntax

HRESULT Skip(ULONG celt)

Parameters

[in] celt The number of elements to be skipped.

Return Value

S_OK Celt elements were skipped.

S_FALSE Fewer than celt elements were skipped. Fewer than celt elements remained in the list.


IEnumRemoteValue : IUnknown

The IEnumRemoteValue interface is a base interface whose derived interfaces enumerate values of elements in Java arrays of primitive values. The IEnumRemoteValue interface does not include the Next method, but does include the other IEnumXXXX enumerator methods. A Java primitive type-specific Next method is included in each of the interfaces derived from IEnumRemoteValue. See the IEnumXXXX interface description for details.


IJavaEnumXXXX : IEnumXXXX

Enumeration of a list of elements is a common operation supported by the Microsoft VM's debugger interfaces. The enumeration interfaces defined as part of the Microsoft VM's debugger interfaces follow a similar design model. The IJavaEnumXXXX interface represents an abstraction of some of the enumeration interfaces. Each particular IJavaEnumXXXX enumeration interface differs from the others only in the type of element returned by the GetNext and Next methods.


Methods (IJavaEnumXXXX Interface)

 Microsoft SDK for Java

IJavaEnumXXXX Interface Methods

The IJavaEnumXXXX interface contains the following methods:

Clone creates a copy of the enumerator, including the enumerator's current position in its list of elements.

GetCount returns the number of elements in the enumerator's list.

GetNext retrieves the next element from the enumerator's list.
Next retrieves the next specified number of elements from the enumerator's list.

Reset resets the enumerator's current position in its list of elements to the first element in the list.

Skip moves the enumerator's current position ahead in its list of elements by the given number of elements.


IJavaEnumXXXX::Clone

 Microsoft SDK for Java

IJavaEnumXXXX::
Clone

The Clone method of the IJavaEnumXXXX interface creates a copy of the enumerator, including the enumerator's current position in its list of elements.

Syntax

HRESULT Clone(IJavaEnumXXXX **ppEnum)

Parameters

[out] ppEnum Returns a pointer to the copied enumerator.

Return Value

S_OK Success

E_OUTOFMEMORY Insufficient memory.


IJavaEnumXXXX::GetCount

 Microsoft SDK for Java

IJavaEnumXXXX::
GetCount

The GetCount method of the IJavaEnumXXXX interface returns the number of elements in the enumerator's list.

Syntax

HRESULT GetCount(ULONG *pcelt)

Parameters

[out] pcelt Returns the number of elements in the enumerator.

Return Value

S_OK Success.


IJavaEnumXXXX::GetNext

 Microsoft SDK for Java

IJavaEnumXXXX::
GetNext

The GetNext method of the IJavaEnumXXXX interface retrieves the next element from the enumerator's list.

Syntax

HRESULT GetNext(<element_type> *pelt)

Parameters

[out] pelt Returns the next element in the enumerator's list.

Return Value

S_OK The next element was returned.

S_FALSE No element was returned. There were no elements remaining in the enumerator's list.


IJavaEnumXXXX::Next

 Microsoft SDK for Java

IJavaEnumXXXX::
Next

The Next method of the IJavaEnumXXXX interface retrieves the next specified number of elements from the enumerator's list.

Syntax

HRESULT Next(ULONG celt, <element_type> *rgelt[], ULONG *pceltFetched)

Parameters

[in] celt | The number of elements requested.
[out] rgelt | The array to be filled in with the elements.
[out] pceltFetched | The number of elements actually returned in rgelt. This can be less than celt if fewer than celt elements remained in the list.

Return Value

S_OK celt elements were returned.

S_FALSE Fewer than celt elements were returned.


IJavaEnumXXXX::Reset

 Microsoft SDK for Java

IJavaEnumXXXX::
Reset

The Reset method of the IJavaEnumXXXX interface resets the enumerator's current position in its list of elements to the first element in the list.

Syntax

HRESULT Reset(void)

Return Value

S_OK Success.


IJavaEnumXXXX::Skip

 Microsoft SDK for Java

IJavaEnumXXXX::
Skip

The Skip method of the IJavaEnumXXXX interface moves the enumerator's current position ahead in its list of elements by the given number of elements.

Syntax

HRESULT Skip(ULONG celt)

Parameters

[in] celt The number of elements to be skipped.

Return Value

S_OK celt elements were skipped.

S_FALSE Fewer than celt elements were skipped. Fewer than celt elements remained in the list.


IJavaEnumRemoteBooleanValue : IEnumRemoteBooleanValue

The IJavaEnumRemoteBooleanValue interface enumerates the values of the elements in a Java array of booleans. See the IJavaEnumXXXX interface description for details.


IJavaEnumRemoteByteValue : IEnumRemoteByteValue

The IJavaEnumRemoteByteValue interface enumerates the values of the elements in a Java array of bytes. See the IJavaEnumXXXX interface description for details.


IJavaEnumRemoteCharValue : IEnumRemoteCharValue

The IJavaEnumRemoteCharValue interface enumerates the values of the elements in a Java array of characters. See the IJavaEnumXXXX interface description for details.


IJavaEnumRemoteDoubleValue : IEnumRemoteDoubleValue

The IJavaEnumRemoteDoubleValue interface enumerates the values of the elements in a Java array of doubles. See the IJavaEnumXXXX interface description for details.


IJavaEnumRemoteFloatValue : IEnumRemoteFloatValue

The IJavaEnumRemoteFloatValue interface enumerates the values of the elements in a Java array of floats. See the IJavaEnumXXXX interface description for details.


IJavaEnumRemoteIntValue : IEnumRemoteIntValue

The IJavaEnumRemoteIntValue interface enumerates the values of the elements in a Java array of integers. See the IJavaEnumXXXX interface description for details.


IJavaEnumRemoteLongValue : IEnumRemoteLongValue

The IJavaEnumRemoteLongValue interface enumerates the values of the elements in a Java array of longs. See the IJavaEnumXXXX interface description for details.


IJavaEnumRemoteObject : IEnumRemoteObject

The IJavaEnumRemoteObject interface enumerates IRemoteObject pointers. It is used to enumerate the elements in a Java array of object references. This interface is implemented by the Microsoft VM. See the IJavaEnumXXXX interface description for details.


IJavaEnumRemoteShortValue : IEnumRemoteShortValue

The IJavaEnumRemoteShortValue interface enumerates the values of the elements in a Java array of shorts. See the IJavaEnumXXXX interface description for details.


Execution Control Debugger Interfaces Overview

Debugger Interfaces Reference

The execution control debugger interfaces provide access to the Java method call stacks of the threads executing in the Java process being debugged.

For general information, see Controlling Execution in the Programmer's Guide.

This topic contains the following sections:

Interfaces

Hierarchy


Execution Control Debugger Interfaces

The execution control interfaces are as follows:

IEnumCodeBreakpoints enumerates IMethodLocation pointers.

IEnumRemoteStackFrames enumerates IRemoteStackFrame pointers.

IJavaEnumRemoteThread enumerates IRemoteThread pointers.

IJavaEnumRemoteThreadGroup enumerates IRemoteThreadGroup pointers.

IRemoteStackFrame provides access to a stack frame of a thread running in a Java process.

IRemoteStackFrameEx provides access to a stack frame of a thread running in a Java process.

IRemoteThread provides access to threads.

IRemoteThreadEx provides access to threads.

IRemoteThreadEx2 extends IRemoteThreadEx with one method. It obtains the return value of a method that just returned.

IRemoteThreadGroup provides access to thread groups.

IRemoteThreadGroupEx provides access to thread groups.

IJITAttachDebugger notifies the debugger when a Java process running under the Microsoft VM throws an unhandled Java exception.

IMethodLocation represents a location within a method where code can execute.


Execution Control Debugger Interfaces Hierarchy

The execution control debugger interfaces have the following hierarchy:

IUnknown
  |
  +--IEnumCodeBreakpoints
  |
  +--IEnumRemoteStackFrames
  |
  +--IEnumRemoteThread : IUnknown
  |  |
  |  +--IJavaEnumRemoteThread
  |
  +--IEnumRemoteThreadGroup : IUnknown
  |  |
  |  +--IJavaEnumRemoteThreadGroup
  |
  +--IRemoteStackFrame
  |  |
  |  +--IRemoteStackFrameEx
  |
  +--IRemoteThread
  |  |
  |  +--IRemoteThreadEx
  |  |  |
  |  |  +--IRemoteThreadEx2
  |
  +--IRemoteThreadGroup
  |  |
  |  +--IRemoteThreadGroupEx
  |
  +--IJITAttachDebugger
  |
  +--IMethodLocation


IEnumCodeBreakpoints : IUnknown

The IEnumCodeBreakpoints interface enumerates IMethodLocation pointers. See the IEnumXXXX interface description for details.


IRemoteStackFrame : IUnknown

The IRemoteStackFrame interface provides access to a stack frame of a thread running in a Java process. Each stack frame represents the state of execution of a method.

  // Methods
  GetCallingFrame
  GetKind
  GetMethodObject
  GetPC
  SetPC


Methods (IRemoteStackFrame Interface)

 Microsoft SDK for Java

IRemoteStackFrame Interface Methods

The IRemoteStackFrame interface contains the following methods:

GetCallingFrame returns an IRemoteStackFrame interface representing the stack frame of the caller of this method.
GetKind returns the execution model of this stack frame.
GetMethodObject returns an IRemoteContainerObject interface representing this stack frame’s executing method.
GetPC returns the bytecode offset from the start of the method executing in this stack frame of the next instruction to be executed.
SetPC sets the bytecode offset from the start of the method executing in this stack frame of the next instruction to be executed.


IRemoteStackFrame::GetCallingFrame

 Microsoft SDK for Java

IRemoteStackFrame::
GetCallingFrame

The GetCallingFrame method of the IRemoteStackFrame interface returns an IRemoteStackFrame interface representing the stack frame of the caller of this method.

Syntax

HRESULT GetCallingFrame(IRemoteStackFrame **ppCallingFrame)

Parameters

[out] **ppCallingFrame Returns the stack frame of the caller of this method.

Return Value

S_OK Success.

E_NOLONGERVALID The underlying stack frame is no longer valid.

E_OUTOFMEMORY Insufficient memory.

Remarks

GetCallingFrame will return S_OK and a NULL *ppCallingFrame when called on the topmost stack frame on a thread.


IRemoteStackFrame::GetKind

 Microsoft SDK for Java

IRemoteStackFrame::
GetKind

The GetKind method of the IRemoteStackFrame interface returns the execution model of this stack frame.

Syntax

HRESULT GetKind(FRAMEKIND *pfk)

Parameters

[out] *pfk Returns the execution model of this stack frame.

Return Value

S_OK Success.

E_NOLONGERVALID The underlying stack frame is no longer valid.

Remarks

The execution model of this stack frame is indicated by a value from the FRAMEKIND enumeration, listed below.

FRAMEKIND Enumeration: FRAME_KIND_INTERPRETED

Value: 1

Execution Model: Interpreted

FRAMEKIND Enumeration: FRAME_KIND_NATIVE

Value: 2

Execution Model: Native Win32

FRAMEKIND Enumeration: FRAME_KIND_JIT_COMPILED

Value: 3

Execution Model: JIT-compiled

FRAMEKIND Enumeration: FRAME_KIND_FAST_INTERPRETED

Value: 4

Execution Model: Fast-interpreted

FRAMEKIND Enumeration: FRAME_KIND_COM

Value: 5

Execution Model: COM


IRemoteStackFrame::GetMethodObject

 Microsoft SDK for Java

IRemoteStackFrame::
GetMethodObject

The GetMethodObject method of the IRemoteStackFrame interface returns an IRemoteContainerObject interface representing this stack frame’s executing method.

Syntax

HRESULT GetMethodObject(IRemoteContainerObject **ppMethodObject)

Parameters

[out] **ppMethodObject Returns this stack frame’s method object.

Return Value

S_OK Success.


IRemoteStackFrame::GetPC

 Microsoft SDK for Java

IRemoteStackFrame::
GetPC

The GetPC method of the IRemoteStackFrame interface returns the bytecode offset from the start of the method executing in this stack frame of the next instruction to be executed. In non-topmost stack frames, GetPC returns the bytecode offset of the invoke instruction that is being executed, not the bytecode offset of the return location.

Syntax

HRESULT GetPC(ULONG *offPC)

Parameters

[out] *offPC Returns the instruction’s bytecode offset.

Return Value

S_OK Success.

E_FAIL Failure.

E_NOLONGERVALID The underlying stack frame is no longer valid.


IRemoteStackFrame::SetPC

 Microsoft SDK for Java

IRemoteStackFrame::
SetPC

The SetPC method of the IRemoteStackFrame interface sets the bytecode offset from the start of the method executing in this stack frame of the next instruction to be executed.

Syntax

HRESULT SetPC(ULONG offPC)

Parameters

[in] offPC Sets the bytecode offset of the next instruction to be executed.

Return Value

S_OK Success.

E_BADMETHOD The method fails bytecode verification.

E_FAIL Failure.

E_INVALIDPC The PC cannot be set to the given bytecode offset.

E_NODEBUGINFORMATION There is no source line mapping information for this method.

E_NOLONGERVALID The underlying stack frame is no longer valid.

E_OUTOFMEMORY Insufficient memory.


IRemoteStackFrameEx : IRemoteStackFrame

The IRemoteStackFrameEx interface provides access to a stack frame of a thread running in a Java process. Each stack frame represents the state of execution of a method.

  // Methods
  GetMethodLocation
  GetRealPC
  GetStackRange


Methods (IRemoteStackFrameEx Interface)

 Microsoft SDK for Java

IRemoteStackFrameEx Interface Methods

The IRemoteStackFrameEx interface contains the following methods:

GetMethodLocation returns the IMethodLocation interface representing the current location where execution will resume in the current execution model (interpreted or JIT-compiled, for example) for this stack frame.
GetRealPC returns the bytecode offset from the start of the method executing in this stack frame of the next instruction to be executed.
GetStackRange returns the addresses of the upper and lower bounds of this stack frame.


IRemoteStackFrameEx::GetMethodLocation

 Microsoft SDK for Java

IRemoteStackFrameEx::
GetMethodLocation

The GetMethodLocation method of the IRemoteStackFrameEx interface returns the IMethodLocation interface. IMethodLocation represents the current location where execution will resume in the current execution model (interpreted or JIT-compiled, for example) for this stack frame. See Controlling Execution and the IMethodLocation interface for more details.

Syntax

HRESULT GetMethodLocation(IMethodLocation *ppiml)

Parameters

[out] *ppiml Returns the current location where execution will resume in this stack frame.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IRemoteStackFrameEx::GetRealPC

 Microsoft SDK for Java

IRemoteStackFrameEx::
GetRealPC

The GetRealPC method of the IRemoteStackFrameEx interface returns the bytecode offset of the next instruction to be executed, beginning from the method executing in this stack frame. In non-topmost stack frames, GetPC returns the bytecode offset of the return location, not the bytecode offset of the invoke instruction that is being executed.

Syntax

HRESULT GetRealPC(ULONG *offPC)

Parameters

[out] *offPC Returns the instruction’s bytecode offset.

Return Value

S_OK Success.

E_FAIL Failure.

E_NOLONGERVALID The underlying stack frame is no longer valid.


IRemoteStackFrameEx::GetStackRange

 Microsoft SDK for Java

IRemoteStackFrameEx::
GetStackRange

The GetStackRange method of the IRemoteStackFrameEx interface returns the addresses of the upper and lower bounds of this stack frame.

Syntax

HRESULT GetStackRange(ULONG *pdwMin, ULONG *pdwLim)

Parameters

[out] *pdwMin | Returns the address of the lower bound of this stack frame.
[out] *pdwLim | Returns the address of the upper bound of this stack frame.

Return Value

S_OK Success.


IRemoteThread : IUnknown

The IRemoteThread interface provides access to threads.

  // Methods
  Destroy
  GetCurrentFrame
  GetName
  GetSuspendCount
  GetThreadGroup
  Go
  RangeStep
  RangeStepIn
  Resume
  Step
  StepIn
  StepOut
  Suspend


Methods (IRemoteThread Interface)

 Microsoft SDK for Java

IRemoteThread Interface Methods

The IRemoteThread interface contains the following methods:

Destroy is not currently implemented in the Microsoft virtual machine.
GetCurrentFrame returns an IRemoteStackFrame interface representing the currently executing stack frame on this thread.
GetName returns the name of this thread.
GetSuspendCount returns a the number of times the Suspend method has been called on this thread.
GetThreadGroup returns an IRemoteThreadGroup interface representing the thread group that contains this thread.
Go resumes execution of the Java process.
RangeStep continues execution of this thread until the PC is outside the given range.
RangeStepIn continues execution of this thread until the PC is outside the given range.
Resume resumes execution of this thread after it was suspended by a previous call to Suspend.
Step steps over the current bytecode instruction in an interpreted method or the current source line in a JIT-compiled method.
StepIn steps over the current bytecode instruction in an interpreted method or the current source line in a JIT-compiled method.
StepOut continues execution until the current method returns to its caller.
Suspend suspends execution of this thread.


IRemoteThread::Destroy

 Microsoft SDK for Java

IRemoteThread::
Destroy

The Destroy method of the IRemoteThread interface is not currently implemented in the Microsoft VM. It returns E_FAIL.

The Destroy method terminates a thread. ThreadDestroyEvent is called when the thread has terminated.

Syntax

HRESULT Destroy(void)

Return Value

S_OK Success.

E_FAIL Failure.


IRemoteThread::GetCurrentFrame

 Microsoft SDK for Java

IRemoteThread::
GetCurrentFrame

The GetCurrentFrame method of the IRemoteThread interface returns an IRemoteStackFrame interface representing the currently executing stack frame on this thread.

Syntax

HRESULT GetCurrentFrame(IRemoteStackFrame **ppCurrentFrame)

Parameters

[out] **ppCurrentFrame Returns the currently executing stack frame on this thread.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IRemoteThread::GetName

 Microsoft SDK for Java

IRemoteThread::
GetName

The GetName method of the IRemoteThread interface returns the name of this thread.

Syntax

HRESULT GetName(LPOLESTR *ppszName)

Parameters

[out] *ppszName Returns the name of this thread.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IRemoteThread::GetSuspendCount

 Microsoft SDK for Java

IRemoteThread::
GetSuspendCount

The GetSuspendCount method of the IRemoteThread interface returns the number of times the Suspend method has been called on this thread.

Syntax

HRESULT GetSuspendCount(ULONG *pcSuspend)

Parameters

[out] *pcSuspend Returns the number of times the Suspend method has been called on this thread.

Return Value

S_OK Success.


IRemoteThread::GetThreadGroup

 Microsoft SDK for Java

IRemoteThread::
GetThreadGroup

The GetThreadGroup method of the IRemoteThread interface returns an IRemoteThreadGroup interface representing the thread group that contains this thread.

Syntax

HRESULT GetThreadGroup(IRemoteThreadGroup **ppThreadGroup)

Parameters

[out] **ppThreadGroup Returns the thread group containing this thread.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.

Remarks

If this thread does not belong to a thread group, S_OK is returned with a NULL *ppThreadGroup.


IRemoteThread::Go

 Microsoft SDK for Java

IRemoteThread::
Go

The Go method of the IRemoteThread interface resumes execution of the Java process. This method clears the execution control state of this thread and returns immediately.

Syntax

HRESULT Go(void)

Return Value

S_OK Success.


IRemoteThread::RangeStep

 Microsoft SDK for Java

IRemoteThread::
RangeStep

The RangeStep method of the IRemoteThread interface continues execution of this thread until the PC is outside the given range. The RangeStep method steps over method calls. IRemoteProcessCallbackEx2::StepEvent is called when execution stepping is complete.

Syntax

HRESULT RangeStep(ULONG offStart, ULONG offEnd)

Parameters

[in] offStart | The starting bytecode offset from the beginning of the current method.
[in] offEnd | The ending bytecode offset from the beginning of the current method.

Return Value

S_OK Success.

E_FAIL The associated thread has terminated.

Remarks

The [offStart, offEnd] range is an inclusive range.


IRemoteThread::RangeStepIn

 Microsoft SDK for Java

IRemoteThread::
RangeStepIn

The RangeStepIn method of the IRemoteThread interface continues execution of this thread until the PC is outside the given range. The RangeStepIn method steps into method calls. CanStopEvent is called on entry to a called method. StepEvent is called when execution stepping is complete.

Syntax

HRESULT RangeStepIn(ULONG offStart, ULONG offEnd)

Parameters

[in] offStart | The starting bytecode offset from the beginning of the current method.
[in] offEnd | The ending bytecode offset from the beginning of the current method.

Return Value

S_OK Success.

E_FAIL The associated thread has terminated.

Remarks

The [offStart, offEnd] range is an inclusive range.


IRemoteThread::Resume

 Microsoft SDK for Java

IRemoteThread::
Resume

The Resume method of the IRemoteThread interface resumes execution of this thread after it was suspended by a previous call to Suspend.

Syntax

HRESULT Resume(void)

Return Value

S_OK Success.

Remarks

Suspending a thread's execution is a reference counted operation. Resume must be called on a thread the same number of times that Suspend has been called on it before the thread’s execution resumes.


IRemoteThread::Step

 Microsoft SDK for Java

IRemoteThread::
Step

The Step method of the IRemoteThread interface steps over the current bytecode instruction in an interpreted method or the current source line in a JIT-compiled method. The Step method steps over method calls. StepEvent is called when execution is complete.

Syntax

HRESULT Step(void)

Return Value

S_OK Success.

E_FAIL The associated thread has terminated.


IRemoteThread::StepIn

 Microsoft SDK for Java

IRemoteThread::
StepIn

The StepIn method of the IRemoteThread interface steps over the current bytecode instruction in an interpreted method or the current source line in a JIT-compiled method. The StepIn method steps into method calls. IRemoteProcessCallbackEx2::CanStopEvent is called on entry to a called method. IRemoteProcessCallbackEx2::StepEvent is called when execution is complete.

Syntax

HRESULT StepIn(void)

Return Value

S_OK Success.

E_FAIL The associated thread has terminated.


IRemoteThread::StepOut

 Microsoft SDK for Java

IRemoteThread::
StepOut

The StepOut method of the IRemoteThread interface continues execution until the current method returns to its caller. The next instruction to be executed is the first instruction after the call in the calling method. StepEvent is called when execution is complete.

Syntax

HRESULT StepOut(void)

Return Value

S_OK Success.

E_FAIL The associated thread has terminated.


IRemoteThread::Suspend

 Microsoft SDK for Java

IRemoteThread::
Suspend

The Suspend method of the IRemoteThread interface suspends execution of this thread.

Syntax

HRESULT Suspend(void)

Return Value

S_OK Success.

E_FAIL Failure.

Remarks

Suspending a thread's execution is a reference counted operation. Resume must be called on a thread the same number of times that Suspend has been called on it before the thread's execution resumes.


IRemoteThreadEx : IRemoteThread

The IRemoteThreadEx interface provides access to threads.

  // Methods
  AllowExecution
  ClearExecutionState
  Continue
  GetStackFrames
  GetThreadId
  IsStartBlock
  PassExceptionToDebuggee
  WatchForStep


Methods (IRemoteThreadEx Interface)

 Microsoft SDK for Java

IRemoteThreadEx Interface Methods

The IRemoteThreadEx interface contains the following methods:

AllowExecution controls whether execution of this thread should be enabled or disabled.
ClearExecutionState clears the execution control state of this thread and returns immediately.
Continue resumes execution of this thread, but leaves the thread in step mode.
GetStackFrames returns an IEnumStackFrames enumerator for all the stack frames on this thread.
GetThreadId returns the Win32 thread ID for this thread.
IsStartBlock indicates whether the given stack frame is at the top of this thread's Java call stack.
PassExceptionToDebuggee is used to control how exceptions are handled during an IRemoteProcessCallbackEx2::ExceptionEventEx call.
WatchForStep watches for execution on this thread above or below a given stack address.


IRemoteThreadEx::AllowExecution

 Microsoft SDK for Java

IRemoteThreadEx::
AllowExecution

The AllowExecution method of the IRemoteThreadEx interface controls whether execution of this thread should be enabled or disabled. This method is typically used for expression evaluation.

Syntax

HRESULT AllowExecution(BOOL fAllow)

Parameters

[in] fAllow Set to TRUE to allow execution; set to FALSE to disallow execution.

Return Value

S_OK Success.


IRemoteThreadEx::ClearExecutionState

 Microsoft SDK for Java

IRemoteThreadEx::
ClearExecutionState

The ClearExecutionState method of the IRemoteThreadEx interface clears the execution control state of this thread and returns immediately.

Syntax

HRESULT ClearExecutionState(void)

Return Value

S_OK Success.


IRemoteThreadEx::Continue

 Microsoft SDK for Java

IRemoteThreadEx::
Continue

The Continue method of the IRemoteThreadEx interface resumes execution of this thread, but leaves the thread in step mode. This call returns immediately.

Syntax

HRESULT Continue(void)

Return Value

S_OK Success.


IRemoteThreadEx::GetStackFrames

 Microsoft SDK for Java

IRemoteThreadEx::
GetStackFrames

The GetStackFrames method of the IRemoteThreadEx interface returns an IEnumStackFrames enumerator for all the stack frames on this thread.

Syntax

HRESULT GetStackFrames(IEnumRemoteStackFrames **ppEnum)

Parameters

[out] **ppEnum Returns an enumerator for all the stack frames on this thread.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IRemoteThreadEx::GetThreadId

 Microsoft SDK for Java

IRemoteThreadEx::
GetThreadId

The GetThreadId method of the IRemoteThreadEx interface returns the Win32 thread ID for this thread.

Syntax

HRESULT GetThreadId(ULONG *pdwTid)

Parameters

[out] *pdwTid Returns the Win32 thread ID for this thread.

Return Value

S_OK Success.

E_FAIL The associated thread has terminated.


IRemoteThreadEx::IsStartBlock

 Microsoft SDK for Java

IRemoteThreadEx::
IsStartBlock

The IsStartBlock method of the IRemoteThreadEx interface indicates whether the given stack frame is at the top of this thread's Java call stack (that is, whether the given stack frame is the current Java stack frame on this thread).

Syntax

HRESULT IsStartBlock(IRemoteStackFrame *pFrame)

Parameters

[in] *pFrame The stack frame.

Return Value

S_OK The given stack frame is this thread's topmost Java stack frame.

S_FALSE The given stack frame is not this thread's topmost Java stack frame.


IRemoteThreadEx::PassExceptionToDebuggee

 Microsoft SDK for Java

IRemoteThreadEx::
PassExceptionToDebuggee

The PassExceptionToDebuggee method of the IRemoteThreadEx interface is used to control how exceptions are handled during an ExceptionEventEx call. If this method is called with FALSE as its parameter, the Microsoft VM ignores the exception that just occurred, hiding it from the process being debugged. If this method is called with TRUE as its parameter, the Microsoft VM passes the exception that just occurred to the debuggee, as usual. This method should only be called during an ExceptionEventEx callback.

Syntax

HRESULT PassExceptionToDebuggee(BOOL fPass)

Parameters

[in] fPass Set to FALSE to have the Microsoft VM ignore the exception that just occurred; set to TRUE to have exception handling occur normally.

Return Value

S_OK Success.


IRemoteThreadEx::WatchForStep

 Microsoft SDK for Java

IRemoteThreadEx::
WatchForStep

The WatchForStep method of the IRemoteThreadEx interface watches for execution on this thread above or below a given stack address.

Syntax

HRESULT WatchForStep(BOOL fWatch, DWORD dwStack)

Parameters

[in] fWatch | Set to TRUE to enable watching for stepping; set to FALSE to disable watching for stepping.
[in] dwStack | The stack address above which to watch for stepping. Any stack frames below this address will be ignored for stepping.

Return Value

S_OK Success.

E_FAIL The associated thread has terminated.


IRemoteThreadEx2 : IRemoteThreadEx

IRemoteThreadEx2 extends IRemoteThreadEx with one method. It obtains the return value of a method that just returned, which is usable until execution resumes. This is useful only after a StepOut, or a step at the return site of the method.

Stepping over a method call will not provide the return value. To obtain the return value in that case, the debugger must manually step in and out of each call in the source line.

  // Methods
GetReturnValue


IRemoteThreadEx2 Interface Methods

The IRemoteThreadEx2 interface contains the following methods:

GetReturnValue obtains the return value of a method that just returned.


IRemoteThreadEx2::GetReturnValue

 Microsoft SDK for Java

IRemoteThreadEx2::
GetReturnValue

The GetReturnValue method of the IRemoteThreadEx2 interface obtains the return value of a method that just returned. The return value is usable until execution resumes.

Syntax

HRESULT GetReturnValue(IRemoteObject **pReturnValue)

Parameters

[out] **pReturnValue The return value of a method.


IRemoteThreadGroup : IUnknown

The IRemoteThreadGroup interface provides access to thread groups.

  // Methods
  GetName
  GetThreadGroups
  GetThreads


Methods (IRemoteThreadGroup Interface)

 Microsoft SDK for Java

IRemoteThreadGroup Interface Methods

The IRemoteThreadGroup interface contains the following methods:

GetName returns the name of this thread group.
GetThreadGroups returns an IJavaEnumRemoteThreadGroup enumerator for the thread groups in this thread group.
GetThreads returns an IJavaEnumRemoteThread enumerator for the threads in this thread group.


IRemoteThreadGroup::GetName

 Microsoft SDK for Java

IRemoteThreadGroup::
GetName

The GetName method of the IRemoteThreadGroup interface returns the name of this thread group.

Syntax

HRESULT GetName(LPOLESTR *ppszName)

Parameters

[out] *ppszName Returns the name of this thread group.

Return Value

S_OK Success.

E_NOLONGERVALID The underlying object is no longer valid.

E_OUTOFMEMORY Insufficient memory.


IRemoteThreadGroup::GetThreadGroups

 Microsoft SDK for Java

IRemoteThreadGroup::
GetThreadGroups

The GetThreadGroups method of the IRemoteThreadGroup interface returns an IJavaEnumRemoteThreadGroup enumerator for the thread groups in this thread group.

Syntax

HRESULT GetThreadGroups(IJavaEnumRemoteThreadGroup **ppEnum)

Parameters

[out] **ppEnum Returns an enumerator for the thread groups in this thread group.

Return Value

S_OK Success.

E_NOLONGERVALID The underlying object is no longer valid.

E_OUTOFMEMORY Insufficient memory.


IRemoteThreadGroup::GetThreads

 Microsoft SDK for Java

IRemoteThreadGroup::
GetThreads

The GetThreads method of the IRemoteThreadGroup interface returns an IJavaEnumRemoteThread enumerator for the threads in this thread group.

Syntax

HRESULT GetThreads(IJavaEnumRemoteThread **ppEnum)

Parameters

[out] **ppEnum Returns an enumerator for the threads in this thread group.

Return Value

S_OK Success.

E_NOLONGERVALID The underlying object is no longer valid.

E_OUTOFMEMORY Insufficient memory.


IRemoteThreadGroupEx : IRemoteThreadGroup

The IRemoteThreadGroupEx interface provides access to thread groups. A debugger typically obtains an IRemoteThreadGroupEx interface by calling QueryInterface for IID_IRemoteThreadGroupEx on an IRemoteThreadGroup interface provided by the Microsoft VM.

  // Methods
  GetParent


Methods (IRemoteThreadGroupEx Interface)

 Microsoft SDK for Java

IRemoteThreadGroupEx Interface Methods

The IRemoteThreadGroupEx interface contains the following methods:

GetParent returns the parent thread group of this thread group.


IRemoteThreadGroupEx::GetParent

 Microsoft SDK for Java

IRemoteThreadGroupEx::
GetParent

The GetParent method of the IRemoteThreadGroupEx interface returns the parent thread group of this thread group.

Syntax

HRESULT GetParent(IRemoteThreadGroupEx **ppParentGroup)

Parameters

[out] **ppParentGroup Returns the parent thread group of this thread group.

Return Value

S_OK Success.

E_NOLONGERVALID The underlying object is no longer valid.

Remarks

If this thread group has no parent thread group, S_OK will be returned and ppParentGroup will be NULL.

The GetParent method returns S_OK and NULL for the system thread group to indicate that this thread group does not have a parent thread group. The system thread group is the only thread group without a parent.


IEnumRemoteStackFrames : IUnknown

The IEnumRemoteStackFrames interface enumerates IRemoteStackFrame pointers. See the IEnumXXXX interface description for details.


IJavaEnumRemoteThread : IEnumRemoteThread

The IJavaEnumRemoteThread interface enumerates IRemoteThread pointers. It is used to enumerate the threads in a thread group. Note that IJavaEnumRemoteThread does not include a GetCount method. See the IEnumXXXX interface description for details.


IJavaEnumRemoteThreadGroup : IEnumRemoteThreadGroup

The IJavaEnumRemoteThreadGroup interface enumerates IRemoteThreadGroup pointers. It is used to enumerate the thread groups in a process or thread group. Note that IJavaEnumRemoteThreadGroup does not include a GetCount method. See the IEnumXXXX interface description for details.


IJITAttachDebugger : IUnknown

The IJITAttachDebugger interface notifies the debugger when a Java process running under the Microsoft VM throws an unhandled Java exception.

To notify the debugger when an unhandled Java exception is thrown in a running Java process, follow these steps.

  1. Register the CLSID of the debugger’s COM class that implements the IJITAttachDebugger interface in the JITAttachDebugger string value of the HKEY_CURRENT_USER\Software\Microsoft\Java VM registry key.

  2. Enable the debugging mode of the Microsoft VM by creating the HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\Debug registry key, or by setting the MSJAVA_ENABLE_DEBUGGING environment variable to a non-zero value.

Note the space between Java and VM in the previous registry keys.

The JITAttachDebugger registry string value is treated as a semicolon-delimited list of CLSIDs for debuggers that the Microsoft VM should create and attempt to attach to for Just-In-Time (JIT) debugging. The Microsoft VM will attempt to create an instance of each CLSID listed in the order that they appear in this string, and will call its IJITAttachDebugger::JITAttach method until one of them returns a successful HRESULT. Only one debugger is allowed to attach to a Java process at a time. If the JITAttachDebugger registry value does not exist, the Microsoft VM won't automatically try to attach to a debugger when an unhandled Java exception is thrown.

  // Methods
JITAttach


Methods (IJITAttachDebugger Interface)

 Microsoft SDK for Java

IJITAttachDebugger Interface Methods

The IJITAttachDebugger interface contains the following methods:

JITAttach is called by the Microsoft VM to notify it that an unhandled Java exception was thrown in a running Java process.


IJITAttachDebugger::JITAttach

 Microsoft SDK for Java

IJITAttachDebugger::
JITAttach

This method is called to notify the Microsoft VM that an unhandled Java exception was thrown in a running Java process. The IJITAttachDebugger interface description indicates how to register a debugger for JIT debugging when an unhandled Java exception is thrown.

Syntax

HRESULT JITAttach(IRemoteProcess *pRunningProcess, IRemoteThread *pThread, IRemoteClassObject *pExceptionObject)

Parameters

[in] *pRunningProcess | A pointer to the IRemoteProcess interface of the Java process in which an unhandled Java exception was thrown.
[in] *pThread | A pointer to the IRemoteThread interface of the Java thread that threw the unhandled Java exception.
[in] *pExceptionObject | A pointer to the IRemoteClassObject interface of the thrown Java object.

Return Value

S_OK The debugger attached to debug the running Java process.

E_FAIL The debugger did not attach to debug to the running Java process.


IMethodLocation : IUnknown

The IMethodLocation interface represents a location within a method where code can execute. The IMethodLocation interface allows a debugger to set a code breakpoint within a source line at a JIT-compiled location. IMethodLocation allows code breakpoints to be set on interpreted bytecode locations within a source line. This differs from IRemoteMethodField::SetBreakpoint, which always sets a code breakpoint at the first JIT-compiled opcode for the containing source line.

The debugger can obtain an IEnumCodeBreakpoints enumerator for all the IMethodLocation code breakpoints set in a method by calling GetCodeBreakpoints.

In some cases, the Microsoft VM might use multiple execution models for a single method (both interpreted and JIT-compiled, for example) executing in different stack frames. Using the IMethodLocation interface for setting code breakpoints yields consistent behavior across these different execution models.

  // Methods
  HRESULT ClearBreakpoint(void)
  HRESULT GetBasePC(ULONG *pulPC)
  HRESULT GetMethod(IRemoteMethodField **ppirmf)
  HRESULT SetBreakpoint(void)


Methods (IMethodLocation Interface)

 Microsoft SDK for Java

IMethodLocation Interface Methods

The IMethodLocation interface contains the following methods:

ClearBreakpoint clears a code breakpoint at this method location that was previously set by IMethodLocation::SetBreakpoint.
GetBasePC returns the interpreted bytecode offset of the start of the source line that contains this location.
GetMethod returns an IRemoteMethodField interface representing the method that contains this location.
SetBreakpoint sets a code breakpoint at this method location.


IMethodLocation::ClearBreakpoint

 Microsoft SDK for Java

IMethodLocation::
ClearBreakpoint

The ClearBreakpoint method of the IMethodLocation interface clears a code breakpoint at this method location that was previously set by IMethodLocation::SetBreakpoint.

Syntax

HRESULT ClearBreakpoint(void)

Return Value

S_OK The code breakpoint was cleared and is no longer in effect.

S_FALSE The code breakpoint was partially cleared, but is still in effect due to outstanding SetBreakpoint calls.

E_FAIL No code breakpoint was set at this method location.

Remarks

If a code breakpoint is set multiple times, it must be cleared the same number of times to eliminate it.


IMethodLocation::GetBasePC

 Microsoft SDK for Java

IMethodLocation::
GetBasePC

The GetBasePC method of the IMethodLocation interface returns the interpreted bytecode offset of the start of the source line that contains this location.

Syntax

HRESULT GetBasePC(ULONG *pulPC)

Parameters

[out] *pulPC Returns the interpreted bytecode offset of the start of the source line that contains this location.

Return Value

S_OK Success.

E_NODEBUGINFORMATION There is no source line mapping information for this method.

E_FAIL Failure.


IMethodLocation::GetMethod

 Microsoft SDK for Java

IMethodLocation::
GetMethod

The GetMethod method of the IMethodLocation interface returns an IRemoteMethodField interface representing the method that contains this location.

Syntax

HRESULT GetMethod(IRemoteMethodField **ppirmf)

Parameters

[out] **ppirmf Returns the method that contains this location.

Return Value

S_OK Success.

E_OUTOFMEMORY Insufficient memory.


IMethodLocation::SetBreakpoint

 Microsoft SDK for Java

IMethodLocation::
SetBreakpoint

The SetBreakpoint method of the IMethodLocation interface sets a code breakpoint at this method location. If the code breakpoint is hit, the Microsoft VM will call the debugger’s IRemoteProcessCallbackEx2::CodeBreakpointEventEx method.

Syntax

HRESULT SetBreakpoint(void)

Return Value

S_OK Success.

E_INVALIDPC This is not a location at which a code breakpoint will ever be hit.

E_OUTOFMEMORY Insufficient memory.


Profiler Interfaces Reference

The Java profiler interfaces assist in the analysis of code for speed, memory use, redundancy, and other performance factors.

These sections provide information on the profiler interfaces, which all inherit from IUnknown. They are categorized as follows:

Event Monitor Information Profiler Interfaces register event masks with the Microsoft virtual machine (Microsoft VM) and request information when specific events occur.

Event Notification Profiler Interfaces notify the profiler when events occur.

Heap Monitor Information Profiler Interface are used by a profiler to register its callback interfaces for heap monitoring with the Microsoft VM and to request heap information.

Heap Monitor Notification Profiler Interfaces notify the profiler of each object allocation and provide a heap dump after garbage collection.

See Also

Profiler Interfaces Overview

Profiler Interfaces Hierarchy

Debugging and Profiling Java Applications (white paper)


Profiler Interfaces Hierarchy

The profiler interfaces have the following hierarchy. All profiler interfaces ultimately derive from IUnknown.

Event Monitor Information Profiler Interfaces
IUnknown
  |
  +--IJavaEventMonitorIDInfo
  |  |
  |  +--IJavaEventMonitorIDInfo2
  |  |  |
  |  |  +--IJavaEventMonitorIDInfo3
  |  |  |  |
  |  |  |  +--IJavaEventMonitorIDInfo4

Event Notification Profiler Interfaces
IUnknown
  |
  +--IJavaEventMonitor
  |  |
  |  +--IJavaEventMonitor2

Heap Monitor Information Profiler Interface
IUnknown
  |
  +--IJavaHeapMonitor
  |  |
  |  +--IJavaHeapMonitor2

Heap Monitor Notification Profiler Interfaces
IUnknown
  |
  +--IHeapInfoCallBack
  |
  +--IObjectAllocationCallBack


Event Monitor Information Profiler Interfaces Overview

Profiler Interfaces Reference

The event monitor information profiler interfaces register event masks with the Microsoft virtual machine (Microsoft VM) and request information when specific events occur.

For general information, see Implementing Event Monitor Information Interfaces in the Programmer's Guide.

This section contains the following:

Interfaces

Hierarchy


Event Monitor Information Profiler Interfaces

The event monitor information profiler interfaces are as follows:

IJavaEventMonitorIDInfo allows the profiler to communicate with the Microsoft VM to control event monitoring and request basic information about classes, objects, event categories, and interpreted and JIT-compiled methods.

IJavaEventMonitorIDInfo2 extends IJavaEventMonitorIDInfo by adding sixteen methods dealing with classes and objects with special properties, arrays, handles, and threads.

IJavaEventMonitorIDInfo3 extends IJavaEventMonitorIDInfo2 by adding three methods dealing with method call events.

IJavaEventMonitorIDInfo4 extends IJavaEventMonitorIDInfo3 by adding three methods that deal with initialization.


Event Monitor Information Profiler Interfaces Hierarchy

The event monitor information profiler interfaces have the following hierarchy:

IUnknown
  |
  +--IJavaEventMonitorIDInfo
  |  |
  |  +--IJavaEventMonitorIDInfo2
  |  |  |
  |  |  +--IJavaEventMonitorIDInfo3
  |  |  |  |
  |  |  |  +--IJavaEventMonitorIDInfo4


IJavaEventMonitorIDInfo : IUnknown

The IJavaEventMonitorIDInfo interface is used by a profiler to communicate with the Microsoft virtual machine (Microsoft VM) to control event monitoring and request information.

The Microsoft VM implements IJavaEventMonitorIDInfo, IJavaEventMonitorIDInfo2, or IJavaEventMonitorIDInfo3. The Microsoft VM passes an IJavaEventMonitorIDInfo interface to each profiler or event monitor during initialization.

The Microsoft VM implements the IJavaEventMonitorIDInfo3 object. A profiler application can call QueryInterface on the IJavaEventMonitorIDInfo interface object passed to its Initialize method to determine if the Microsoft VM supports the IJavaEventMonitorIDInfo2 or IJavaEventMonitorIDInfo3 interface. The profiler or event monitor that is set to use the interface should call the AddRef method on this interface.

A profiler or event monitor can call methods on the IJavaEventMonitorIDInfo interface to get information about a Java process being executed. Information is available on classes, methods, and other objects.

The IJavaEventMonitorIDInfo interface implemented by the Microsoft VM uses the free-threading model. Events are dispatched from within the VM or on a thread that is making the Java profiler method call. Interface methods implemented by the VM can be called from any thread (that has been CoInitialized) at any time.

The methods implemented on this interface return S_OK on success, or E_FAIL on failure.

For parameters returned from these methods that are [out] buffer parameters filled with pointers to buffers (and not NULL pointers), these objects were allocated by the Microsoft VM using CoTaskMemAlloc. The profiler must free these objects using calls to CoTaskMemFree.

  // Methods
  ClassInformation
  GetEventMask
  GetMonitorUsage
  InterpretedMethodInformation
  JITCompiledMethodInformation
  MethodInformation
  ObjectInformation
  SetEventMask


Methods (IJavaEventMonitorIDInfo Interface)

 Microsoft SDK for Java

IJavaEventMonitorIDInfo Interface Methods

The IJavaEventMonitorIDInfo interface contains the following methods.

ClassInformation retrieves information on a Java class.
GetEventMask retrieves the current event categories for which it is to receive notification from the Microsoft VM.
GetMonitorUsage retrieves information about Java monitors (Java synchronization objects or critical sections).
InterpretedMethodInformation retrieves additional information on an interpreted method.
JITCompiledMethodInformation retrieves additional information on a JIT-compiled method.
MethodInformation retrieves information on a method.
ObjectInformation retrieves information about an object (an instance of a class).
SetEventMask sets the event categories for which it is set to receive notification from the Microsoft VM.


IJavaEventMonitorIDInfo::ClassInformation

 Microsoft SDK for Java

IJavaEventMonitorIDInfo::
ClassInformation

The ClassInformation method of the IJavaEventMonitorIDInfo interface is called by a profiler to retrieve information on a Java class. The profiler passes in the ClassID of the class it is interested in.

Syntax

HRESULT ClassInformation(ClassID class_id, LPSTR *ppclass_name, LPSTR *ppsource_file_name, int *pmethods, MethodID **ppmethod_ids, __int64 *pobjects_created);

Return Value

The name of the class, the source file attribute contained within the class file, an array of MethodIDs representing the class's methods, and a count of the number of objects of this class that have been created since the Microsoft VM was started.

Parameters

[in] class_id | The ClassID of the class the profiler is interested in.
[out] *ppclass_name | The UTF-8 string name of the method. This consists of the class name with dots. This item is taken directly from the constant pool of the class file and modified with dots instead of forward slashes.
[out] *ppsource_file_name | The UTF-8 source file attribute taken directly from the constant pool of the class file, unmodified.
[out] *pmethods | The number of MethodIDs in the array.
[out] **ppmethod_ids | A pointer to an array of MethodIDs for the class.
[out] *pobjects_created | A counter that represents the number of instances of this class that have been created since the class was loaded.


IJavaEventMonitorIDInfo::GetEventMask

 Microsoft SDK for Java

IJavaEventMonitorIDInfo::
GetEventMask

The GetEventMask method of the IJavaEventMonitorIDInfo interface retrieves the current event categories for which it is to receive notification from the Microsoft VM. This method allows a profiler to dynamically retrieve and set the bitmask for event type categories for which the Microsoft VM will send event notifications.

Syntax

HRESULT GetEventMask(DWORD *pevents);

Return Value

A bitmask of flags.

Parameters

[out] *pevents A bitmask of flags from JAVA_EVENT_CATEGORY indicating the events for which the profiler is to receive notification.

Remarks

Profilers or event monitors can receive notification for any combination of the event categories as defined in the JAVA_EVENT_CATEGORY enumeration.


IJavaEventMonitorIDInfo::GetMonitorUsage

 Microsoft SDK for Java

IJavaEventMonitorIDInfo::
GetMonitorUsage

The GetMonitorUsage method of the IJavaEventMonitorIDInfo interface is called by a profiler to retrieve information about Java monitors (Java synchronization objects or critical sections).

Syntax

HRESULT GetMonitorUsage(hyper *pmonitors_used);

Return Value

A count of how many Java monitors are currently in use.

Parameters

[out] *pmonitors_used The count of how many Java monitors are currently in use.


IJavaEventMonitorIDInfo::InterpretedMethodInformation

 Microsoft SDK for Java

IJavaEventMonitorIDInfo::
InterpretedMethodInformation

The InterpretedMethodInformation method of the IJavaEventMonitorIDInfo interface is called by a profiler to retrieve additional information on an interpreted method. The profiler passes in the MethodID of the method to be profiled.

Syntax

HRESULT InterpretedMethodInformation(MethodID method_id, unsigned int *pbyte_code_length, BYTE_CODE **ppbyte_codes);

Return Value

An array of the bytecodes for this method.

Parameters

[in] method_id | The MethodID of the method the profiler is interested in.
[out] *pbyte_code_length | The length of the bytecode information returned. This represents the number of elements in the array.
[out] **ppbyte_codes | A pointer to an array of Java bytecodes for the method.

Remarks

If this method is called before a MethodID has been JIT-compiled, interpreted bytecode information will always be returned. Depending on the mode of the Microsoft VM, interpreted bytecode information might not be available after the method has been JIT-compiled.


IJavaEventMonitorIDInfo::JITCompiledMethodInformation

 Microsoft SDK for Java

IJavaEventMonitorIDInfo::
JITCompiledMethodInformation

The JITCompiledMethodInformation method of the IJavaEventMonitorIDInfo interface is called by a profiler to retrieve additional information on a JIT-compiled method. The profiler passes in the MethodID of the method to be profiled.

Syntax

HRESULT JITCompiledMethodInformation(MethodID method_id, unsigned int *pjit_code_length, unsigned char **ppjit_code);

Return Value

An array of JIT-compiled code for this method.

Parameters

[in] method_id | The MethodID of the method the profiler is interested in.
[out] *pjit_code_length | The length of the JIT-compiled code information returned. This represents the number of elements in the array.
[out] **ppjit_code | A pointer to an array of JIT-compiled codes for the method.

Remarks

This method must be called only after the profiler has received notification that the method has been JIT-compiled.


IJavaEventMonitorIDInfo::MethodInformation

 Microsoft SDK for Java

IJavaEventMonitorIDInfo::
MethodInformation

The MethodInformation method of the IJavaEventMonitorIDInfo interface is called by a profiler to retrieve information on a method. The profiler passes in the MethodID of a method to be profiled.

Syntax

HRESULT MethodInformation(MethodID method_id, LPSTR *ppmethod_name, ClassID *pclass_id, JAVA_EXECUTION_MODEL *pexec, int *psource_line_info_length, SourceLineInfo **ppsource_line_info);

Return Value

The name of the method, the ClassID of the class that contains the method, the default execution model (interpreted, JIT-compiled, native, and so on) that is used for the method, and source line information.

Parameters

[in] method_id | The MethodID of the method to be profiled.
[out] *ppmethod_name | The UTF-8 string name of the method. This consists of the class name with forward slashes (java/lang/Object, for example) followed by a dot and the method name followed by the method signature. This item is taken directly from the constant pool of the Class file, unmodified.
[out] *pclass_id | This ClassID of the class that contains this method.
[out] *pexec | The default Java execution model (interpreted, JIT-compiled, native, and so on) that is used for this method. This parameter is one of the JAVA_EXECUTION_MODEL enumeration constants that describe how the Microsoft VM goes about executing this method.
[out] *psource_line_info_length | The length of the source line information returned. This represents the number of elements in the array.
[out] **ppsource_line_info | A pointer to an array of SourceLineInfo structures containing source line information for the method.

Remarks

MethodInformation returns a value indicating the execution model of a Java method, which describes how the Microsoft VM executes this method. The possible execution models can be one of the types defined in the JAVA_EXECUTION_MODEL enumeration.

JAVA_EXECUTION_MODEL

Constant | Value | Description
JVM_EXECUTION_INVALID | -1 | The execution model for this method is invalid.
JVM_EXECUTION_JIT_COMPILED | 0 | The method is JIT-compiled.
JVM_EXECUTION_NATIVE | 1 | The method is a native Win32 method.
JVM_EXECUTION_INTERPRETED | 2 | The method is interpreted.
JVM_EXECUTION_FAST_INTERPRETED | 3 | The method is fast-interpreted.
JVM_EXECUTION_COM | 4 | The method is a native COM method.

The following structure is used for returning source line information for a method.

typedef struct tagSourceLineInfo {
    DWORD code_offset;
    DWORD line_number;
} SourceLineInfo;

If a Java method is interpreted, the profiler can call the InterpretedMethodInformation method to retrieve a pointer to an array of the Java bytecodes that implement the interpreted method. This method can be called anytime before the given Java method has been JIT-compiled. Depending on the mode of the Microsoft VM, interpreted bytecode information may not be available after the given method has been JIT-compiled.

If a Java method is JIT-compiled, the profiler can call JITCompiledMethodInformation to retrieve a pointer to an array of JIT-compiled instructions that implement the JIT-compiled method. This method should only be called after the profiler has received notification that the method has been JIT-compiled.

If this method is called by a profiler application before JIT compilation, the code_offset member of the SourceLineInfo structure returns the code offset for the interpreted bytecodes.

If this method is called by a profiler after JIT-compilation is finished when the profiler receives a call to its NotifyEvent method (the JVM_EVENT_TYPE_ JIT_COMPILE_FINISHED event), the code_offset member of the SourceLineInfo structure returns the code offset for the JIT-compiled code. Note that the profiler must call MethodInformation during the NotifyEvent method call, indicating that JIT-compilation for this method is finished and before the profiler returns from this NotifyEvent method call.


IJavaEventMonitorIDInfo::ObjectInformation

 Microsoft SDK for Java

IJavaEventMonitorIDInfo::
ObjectInformation

The ObjectInformation method of the IJavaEventMonitorIDInfo interface retrieves information about an object (an instance of a class). The profiler passes the ObjectID of the object to be profiled.

Syntax

HRESULT ObjectInformation(ObjectID object_id, ClassID *pclass_id);

Return Value

The ClassID of an object.

Parameters

[in] object_id | The ObjectID of the object to be profiled.
[out] *pclass_id | The ClassID of an object.


IJavaEventMonitorIDInfo::SetEventMask

 Microsoft SDK for Java

IJavaEventMonitorIDInfo::
SetEventMask

The SetEventMask method of the IJavaEventMonitorIDInfo interface is called by a profiler to set event categories to receive notification from the Microsoft VM. This method allows a profiler to dynamically retrieve and set the bitmask for event type categories for which the Microsoft VM will the send event notifications.

Syntax

HRESULT SetEventMask(DWORD events);

Parameters

[in] events A bitmask of flags from JAVA_EVENT_CATEGORY indicating which events that the profiler wants to receive notification for.

Remarks

Profilers or event monitors can request notification for any combination of the event categories as defined in the JAVA_EVENT_CATEGORY enumeration.


IJavaEventMonitorIDInfo2 : IJavaEventMonitorIDInfo

IJavaEventMonitorIDInfo2 extends IJavaEventMonitorIDInfo by adding several methods dealing with method call events.

  // Methods
  DescribeObject
  FieldInformation
  FreeHandlesToObjects
  GetArrayElement
  GetClassFields
  GetClassPath
  GetCurrentThread
  GetHandlesToObjects
  GetObjectField
  GetObjectSize
  GetObjectsFromHandles
  GetProfilingCapabilities
  GetSpecialClassProperties
  GetStackTrace
  SampleThreadLocation
  StaticClassInformation
  ThreadInformation


Methods (IJavaEventMonitorIDInfo2 Interface)

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2 Interface Methods

The IJavaEventMonitorIDInfo2 interface has the following methods:

DescribeObject obtains a description of a special Java object that contains Microsoft VM-dependent fields.
FieldInformation retrieves information about a field in a Java class.
FreeHandlesToObjects frees an array of persistent handles to Java objects that were previously obtained by calling the GetHandlesToObjects method.
GetArrayElement obtains the value of an array element in a Java array.
GetClassFields retrieves an array of the fields in a Java class.
GetClassPath retrieves the current Java class path for the Win32 process being monitored.
GetCurrentThread retrieves the ThreadID for the currently executing Java thread.
GetHandlesToObjects obtains an array of persistent handles to Java objects that are valid across garbage collections, and that can be converted to ObjectIDs to allow tracking of specific objects.
GetObjectField obtains the value of a field in a Java class instance.
GetObjectSize retrieves information about the size of a Java object. The profiler passes in the ObjectID of the object it is interested in. The Microsoft VM returns the size of the object in memory.
GetObjectsFromHandles obtains an array of ObjectIDs from an array of persistent handles retrieved previously by calling GetHandlesToObjects.
GetProfilingCapabilities queries the Microsoft VM for the profiling capabilities that it supports.
GetSpecialClassProperties obtains a list of Java classes that have special properties.
GetStackTrace obtains a stack trace for the specified Java thread.
SampleThreadLocation obtains sample profiling information.
StaticClassInformation retrieves information about the static data in a Java class and the size of an instance of the class.
ThreadInformation retrieves the Win32 thread ID for a Java thread.


IJavaEventMonitorIDInfo2::DescribeObject

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
DescribeObject

The DescribeObject method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to obtain a description of special objects containing Microsoft VM-dependent fields. These special objects are instances of classes with special properties. A list of objects supported by this function can be obtained through GetSpecialClassProperties. Classes for which special information is available include instances of Java.Lang.Class, Java.Lang.Reflect.Method, Java.Lang.Reflect.Field, Java.Lang.String, and Java.Lang.StringBuffer.

The DescribeObject method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT DescribeObject(ObjectID object_id, LPWSTR *pdescr);

Return Value

A string describing the special object. For example, for an instance of java.lang.Class, the Microsoft VM returns the associated Java class's name. For an instance of java.lang.reflect.Method, the Microsoft VM returns the class name, method name, and signature (parameters and return value) for the associated method.

Parameters

[in] object_id | The ObjectID of the class instance that the profiler is interested in.
[out] *pdescr | A string that describes the special object.

Remarks

The DescribeObject method works on any class with JVM_CLS_HAS_DESCRIPTION for its JVM_CLASS_PROPERTIES.


IJavaEventMonitorIDInfo2::FieldInformation

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
FieldInformation

The FieldInformation method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to retrieve information about a field in a class. The profiler must pass the FieldID it is interested in.

The FieldInformation method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT FieldInformation(FieldID field_id, LPSTR *pname, DWORD *pflags);

Return Value

A pointer to the name of the field and a bitmask of flags from the JAVA_FIELD_FLAGS enumeration representing access modifiers.

Parameters

[in] field_id | The FieldID of the class the profiler is interested in.
[out] *pname | The UTF-8 string name of the field taken directly from the constant pool of the class file, unmodified.
[out] *pflags | A bitmask of flags from JAVA_FIELD_FLAGS.

Remarks

The possible field flags can be a combination of the JAVA_FIELD_FLAGS types or the last predefined combined type as defined in the JAVA_STATE_FLAGS enumeration.

JAVA_FIELD_FLAGS

Constant | Value | Description
JVM_FIELD_STATIC | 1 | This is a static field.
JVM_FIELD_OBJECTREF | 2 | This field contains an object reference or an array, not a Java primitive type.
ALL_JVM_FIELD_FLAGS | 3 | A combination of all the previous flags.

JAVA_STATE_FLAGS

Constant | Value | Description
JVM_STATE_INTERPRETER_ENABLED | 0x1 | The Java interpreter is enabled.
JVM_STATE_FAST_INTERPRETER_ENABLED | 0x2 | The fast interpreter is enabled.
JVM_STATE_JIT_COMPILER_ENABLED | 0x4 | The JIT-compiler is enabled.
JVM_STATE_DEBUGGER_ENABLED | 0x8 | The debugger is enabled.
ALL_JVM_FLAGS | 0xF | All the previous flags are enabled.


IJavaEventMonitorIDInfo2::FreeHandlesToObjects

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
FreeHandlesToObjects

The FreeHandlesToObjects method of the IJavaEventMonitorIDInfo2 interface is called by a profiler or heap monitoring program to free an array of persistent handles to objects that were previously obtained by calling the GetHandlesToObjects method. The profiler must pass an array of persistent handles to objects that are to be freed.

The FreeHandlesToObjects method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT FreeHandlesToObjects(unsigned int nhandles, ObjectHandleID *pobject_handles);

Parameters

[in] nhandles | The number of ObjectHandleIDs in the array.
[in] *pobject_handles | The array of persistent ObjectHandleIDs that should be freed.

Remarks

NULL handles are ignored in the object_id array.


IJavaEventMonitorIDInfo2::GetArrayElement

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetArrayElement

The GetArrayElement method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to obtain the value of an array element in a class instance. The profiler must pass the ObjectID representing the array and an index to the array element it is interested in.

The GetArrayElement method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetArrayElement(ObjectID object_id, unsigned index, __int64 *pvalue);

Return Value

If the array element is an object, the ObjectID is returned. If the array element is a primitive Java type, the value of the array element is returned.

Parameters

[in] object_id | The ObjectID of the class instance that the profiler is interested in.
[in] index | The index (zero-based) of the array element that the profiler is interested in.
[out] *pvalue | The value of the array element or an ObjectID if the array element is an object.

Remarks

For arrays of objects, pvalue will be NULL or an ObjectID.

To properly interpret the value returned (its type and value), a profiler program will need to parse the array signature.


IJavaEventMonitorIDInfo2::GetClassFields

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetClassFields

The GetClassFields method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to retrieve additional information about a class (the fields in a class). The profiler must pass the ClassID it is interested in.

The GetClassFields method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetClassFields(ClassID class_id, unsigned int *pnfields, FieldID **pfield_ids);

Return Value

An array of FieldIDs for the fields in the class.

Parameters

[in] class_id | The ClassID of the class the profiler is interested in.
[out] *pnfields | The number of FieldIDs in the array.
[out] **pfield_ids | A pointer to an array of FieldIDs for the class.


IJavaEventMonitorIDInfo2::GetClassPath

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetClassPath

The GetClassPath method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to retrieve the current class path for the Java process being monitored. The class path is established by the Microsoft VM based on the CLASSPATH environment variable and four Win32 registry settings. The class path describes locations searched by the Microsoft VM when loading system classes.

The GetClassPath method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetClassPath(LPSTR *ppszClassPath);

Return Value

A class path for a Java process.

Parameters

[out] *ppszClassPath The current class path for the Java process being monitored.


IJavaEventMonitorIDInfo2::GetCurrentThread

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetCurrentThread

The GetCurrentThread method of the IJavaEventMonitorIDInfo2 interface retrieves the ThreadID for the currently executing Java thread. This method is called by a profiler.

The GetCurentThread method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetCurrentThread(ThreadID * pcurrent_thread_id);

Return Value

The ThreadID of the currently executing Java thread.

Parameters

[out] *pcurrent_thread_id The ThreadID of the currently executing Java thread.


IJavaEventMonitorIDInfo2::GetHandlesToObjects

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetHandlesToObjects

The GetHandlesToObjects method of the IJavaEventMonitorIDInfo2 interface is called by a profiler or heap monitoring program to obtain an array of persistent handles to objects that are valid across garbage collections and can be converted to ObjectIDs to allow tracking of specific objects. The debugger or profiler must pass an array of ObjectIDs for which it wants to obtain persistent handles.

The GetHnadlesToObjects method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetHandlesToObjects(unsigned nobjects, ObjectID *pobject_ids, ObjectHandleID *pobject_handles);

Return Value

An array of persistent handles for ObjectIDs.

Parameters

[in] nobjects | The number of ObjectIDs in the array.
[in] *pobject_ids | The array of ObjectIDs for which persistent handles are requested.
[in, out] *pobject_handles | The array to receive the persistent handles (ObjectHandleIDs).

Remarks

Note that owning a handle to an object will not prevent the object from being garbage-collected.


IJavaEventMonitorIDInfo2::GetObjectField

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetObjectField

The GetObjectField method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to obtain the value of a field in a class instance. The profiler must pass the ObjectID representing the instance of a class and the FieldID it is interested in.

The GetObjectField method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetObjectField(ObjectID object_id, FieldID field_id, __int64 *pvalue);

Return Value

The value of the field. If the JVM_FIELD_OBJECTREF flag is set for the FieldID by FieldInformation, the returned value will be NULL or an ObjectID.

Parameters

[in] object_id | The ObjectID of the class instance that the profiler is interested in.
[in] field_id | The FieldID of the field that the profiler is interested in.
[out] *pvalue | The value of the field.


IJavaEventMonitorIDInfo2::GetObjectsFromHandles

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetObjectsFromHandles

The GetObjectsFromHandles method of the IJavaEventMonitorIDInfo2 interface is called by a profiler or heap monitoring program to obtain an array of ObjectIDs from an array of persistent handles retrieved previously by calling GetHandlesToObjects. The debugger or profiler must pass an array of persistent handles for which it wants to obtain the current ObjectIDs.

The GetObjectsFromHandles method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetObjectsFromHandles(unsigned nhandles, ObjectHandleID *pobject_handles, ObjectID *pobject_ids);

Return Value

An equivalent array of object IDs.

Parameters

[in] nhandles | The number of handles (ObjectHandleIDs) in the array.
[in, out] *pobject_handles | The array of persistent handles for which ObjectIDs are requested.
[in, out] *pobject_ids | The array to receive the ObjectIDs.

Remarks

ObjectIDs are only valid between garbage-collections; consequently, persistent handles can be used for long-term tracking of objects in memory.

If an object referenced by a handle has been garbage-collected, the ObjectID in pobject_ids will be NULL and the corresponding ObjectHandleID will be automatically freed and set to NULL in pobject_handles.


IJavaEventMonitorIDInfo2::GetObjectSize

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetObjectSize

The GetObjectSize method of the IJavaEventMonitorIDInfo2 interface retrieves information about the size of an object. This method is called by a profiler. The profiler must pass the ObjectID of the Java monitor (synchronization object) it is interested in.

The GetObjectSize method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetObjectSize(ObjectID object_id, DWORD *pSize);

Return Value

The size of the object in memory.

Parameters

[in] object_id | The ObjectID of the object the profiler is interested in.
[out] *pSize | The size of the object in memory.


IJavaEventMonitorIDInfo2::GetProfilingCapabilities

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetProfilingCapabilities

The GetProfilingCapabilities method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to query the Microsoft VM for the profiling capabilities that it supports.

The GetProfilingCapabilities method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetProfilingCapabilities(DWORD *pStates, DWORD *pCategories, JAVA_EXECUTION_MODEL *pLastModel, JVM_EVENT_TYPE *pLastType, JVM_EVENT_TYPE2 *pLastType2);

Return Value

A bitmask of flags indicating the maximum possible list of event categories on which a profiler can request notification, a bitmask of flags indicating which event categories are currently being notified, the highest possible value for the Java execution model, and the highest possible value for the type of events that will be notified on the profiler's NotifyEvent and NotifyEvent2 methods.

Parameters

[out] *pStates | A bitmask of flags from JAVA_STATE_FLAGS indicating the possible state flags that are supported for this Java process.
[out] *pCategories | A bitmask of flags indicating the possible list of event categories (JVM_EVENT_CATEGORY) supported by the Microsoft VM for this Java process on which a profiler can request notification.
[out] *pLastModel | The highest possible value for the Java execution model supported by the Microsoft VM.
[out] *pLastType | The highest possible value for the type of events that will be notified on the profiler's NotifyEvent method.
[out] *pLastType2 | The highest possible value for the type of events that will be notified on the profiler's NotifyEvent2 method.

Remarks

The possible Java state flags can be a combination of the JAVA_STATE_FLAGS types or the last predefined combined type as defined in the JAVA_STATE_FLAGS enumeration.

JAVA_STATE_FLAGS

Constant | Value | Description
JVM_STATE_INTERPRETER_ENABLED | 0x1 | The Java interpreter is enabled.
JVM_STATE_FAST_INTERPRETER_ENABLED | 0x2 | The fast interpreter is enabled.
JVM_STATE_JIT_COMPILER_ENABLED | 0x4 | The JIT-compiler is enabled.
JVM_STATE_DEBUGGER_ENABLED | 0x8 | The debugger is enabled.
ALL_JVM_FLAGS | 0xF | All the previous flags are enabled.

Profilers or event monitors can request notification for any combination of the following event categories as defined in the JAVA_EVENT_CATEGORY enumeration.

JAVA_Event_Category

Constant | Value | Description
JVM_MONITOR_NONE | 0 | Do not send notification for any event categories.
JVM_MONITOR_CLASS_LOADS | 1 | Send event notification when a Java class is loaded or when the class is unloaded. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_METHOD_CALLS | 2 | Send event notification when a Java method is about to be called and upon completion of the method call. The Microsoft VM will call the MethodEntry and MethodExit methods implemented by the profiler. If the profiler implements IJavaEventMonitor2 interface, the Microsoft VM will call MethodExit2 on this interface rather than MethodExit.
JVM_MONITOR_JIT_COMPILATION | 4 | Send event notification when a Java class is about to be JIT compiled and after JIT compilation is completed. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_BYTE_CODE_EXECUTION | 8 | Send event notification when a byte code instruction of an interpreted method is about to be executed. The Microsoft VM will call the ExecuteByteCode method implemented by the profiler. If any profiler requests this event category, then JIT compilation will be disabled for all methods.
JVM_MONITOR_SOURCE_LINE_EXECUTION | 0x10 | Send event notification when a Java source line is about to be executed. The Microsoft VM will call the ExecuteSourceLine method implemented by the profiler.
JVM_MONITOR_EXCEPTIONS | 0x20 | Send event notification when an exception is about to be thrown. The Microsoft VM will call the NotifyEvent2 method if the IJavaEventMonitor2 interface is implemented by the profiler. Otherwise the Microsoft VM will call the NotifyEvent method.
JVM_MONITOR_GARBAGE_COLLECTIONS | 0x80 | Send event notification when the VM is about to execute garbage collection. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_THREADS | 0x100 | Send event notification when a Java thread is about to be created or destroyed. The Microsoft VM will call the NotifyEvent method implemented by the profiler. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will also call the NotifyEvent2 method when a thread's name has been set.
JVM_MONITOR_SAMPLING | 0x200 | Changes the behavior of the Microsoft VM to improve the accuracy of sampling. Note that this event category doesn't generate any additional event notifications, but improves the accuracy of the SampleThreadLocation method implemented by the Microsoft VM. Specifying this event category slows down the execution of non-JIT compiled methods, but improves the accuracy of the sampling data for these methods.
JVM_MONITOR_EXCEPTION_UNWIND | 0x400 | Send event notification when a Java exception is about to be thrown past a stack frame. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will call the NotifyEvent2 method.
JVM_MONITOR_SPECIFIC_METHOD_CALLS | 0x800 | Send event notification when specific methods are called. The Microsoft VM will call the MethodEntry and MethodExit methods implemented by the profiler. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will call the MethodExit2 method rather than MethodExit.
ALL_JVM_MONITOR_EVENTS | 0xFFF | Send event notification on all event categories.

The possible execution models can be one of the types defined in the JAVA_EXECUTION_MODEL enumeration.

JAVA_EXECUTION_MODEL

Constant | Value | Description
JVM_EXECUTION_INVALID | -1 | The execution model for this method is invalid.
JVM_EXECUTION_JIT_COMPILED | 0 | The method is JIT-compiled.
JVM_EXECUTION_NATIVE | 1 | The method is a native Win32 method.
JVM_EXECUTION_INTERPRETED | 2 | The method is interpreted.
JVM_EXECUTION_FAST_INTERPRETED | 3 | The method is fast-interpreted.
JVM_EXECUTION_COM | 4 | The method is a native COM method.

The possible event types that can be passed to the NotifyEvent method can be one of the following types as defined in the JVM_EVENT_TYPE enumeration.

JVM_EVENT_TYPE

Constant | Value | Description
JVM_EVENT_TYPE_EXCEPTION_OCCURRED | 0 | An exception occurred. The UniqueID passed as the second parameter is a StackID of the stack frame that the exception handler will be executed in.
JVM_EVENT_TYPE_THREAD_CREATE | 4 | A Java thread is being created. The UniqueID passed as the second parameter is the ThreadID of the Java thread.
JVM_EVENT_TYPE_THREAD_DESTROY | 5 | A Java thread is being destroyed. The UniqueID passed as the second parameter is the ThreadID of the Java thread.
JVM_EVENT_TYPE_CLASS_LOAD_STARTED | 6 | A Java class is starting to be loaded. The UniqueID passed as the second parameter is a pointer to the class name (a UTF-8 string) of the class.
JVM_EVENT_TYPE_CLASS_LOAD_FINISHED | 7 | A Java class is finished loading. The UniqueID passed as the second parameter is a pointer to the ClassID of the class loaded.
JVM_EVENT_TYPE_CLASS_LOAD_FAILED | 17 | A Java class failed to be loaded. The UniqueID passed as the second parameter is a pointer to the class name (a UTF-8 string) of the class.
JVM_EVENT_TYPE_CLASS_UNLOAD | 8 | A Java class is being unloaded. The UniqueID passed as the second parameter is the ClassID of the class.
JVM_EVENT_TYPE_JIT_COMPILE_STARTED | 9 | The JIT compiler is starting to compile a class method. The UniqueID passed as the second parameter is the MethodID of the class method being compiled.
JVM_EVENT_TYPE_JIT_COMPILE_FINISHED | 10 | The JIT compiler is finished compiling a class method. The UniqueID passed as the second parameter is the MethodID of the class method that was compiled.
JVM_EVENT_TYPE_GC_STARTED | 11 | Garbage collection is starting. The UniqueID passed as the second parameter is undefined (this parameter is not used).
JVM_EVENT_TYPE_GC_FINISHED | 12 | Garbage collection has finished. The UniqueID passed as the second parameter is undefined. (This parameter is not used.)
JVM_EVENT_TYPE_SHUTDOWN | 12 | The program is exiting. The UniqueID passed as the second parameter is undefined. (This parameter is not used.)
JVM_EVENT_TYPE_RESERVED_14 | 14 | This event type, formerly called JVM_EVENT_TYPE_SHUTDOWN_ERROR, is deprecated and no longer dispatched by the Microsoft VM.
JVM_EVENT_TYPE_RESERVED_15 | 15 | This event type, formerly called JVM_EVENT_TYPE_SHUTDOWN_INTERRUPTED, is deprecated and no longer dispatched by the Microsoft VM.
JVM_EVENT_TYPE_RESERVED_17 | 17 | This formerly reserved event type is now used for JVM_EVENT_TYPE_CLASS_LOAD_FAILED.

The possible event types that can be passed to the NotifyEvent2 method can be one of the types defined in the JVM_EVENT_TYPE2 enumeration.

JAVA_EVENT_TYPE2

Constant | Value | Description
JVM_EVENT_TYPE2_THREAD_SET_NAME | 1025 | A thread's name has been set.
JVM_EVENT_TYPE2_EXCEPTION_OCCURRED | 1026 | An exception occurred. This event supercedes JVM_EVENT_TYPE_EXCEPTION_OCCURRED if IJavaEventMonitor2 is implemented and JVM_EVENT_TYPE_EXCEPTION_OCCURRED will never be passed to NotifyEvent.
JVM_EVENT_TYPE2_EXCEPTION_THROWN | 1027 | An exception is about to be thrown.
JVM_EVENT_TYPE2_EXCEPTION_UNWIND | 1028 | An exception is being thrown past this frame.
JVM_EVENT_TYPE2_STACK_TRACE | 1029 | This event notifies a callback from GetStackTrace.
JVM_EVENT_TYPE2_INITIALIZED | 1030 | The Microsoft VM has fully initialized.
JVM_EVENT_TYPE2_MONITORS_INITIALIZED | 1031 | All event monitors have initialized. ID1 is the number of event monitors attached to the VM. ID2 is a bitmask of JAVA_EVENT_CATEGORY, indicating the maximum possible set of events that may be enabled by all attached profilers.

Note JVM_EVENT_TYPE2_MONITORS_INITIALIZED is the number of monitors that were attached at the time the VM started initializing. This number is used by the VM as part of optimizing profiling overhead. If profilers detach in response to this event, this overhead remains, based on the original number. Programmatically, it is really a BOOL. Any profiler that needs timing accuracy will care only that there are other profilers, not how many. However, if it needed to present the user interface, this would indicate how many applicationss were running that needed to be closed. Otherwise, you keep re-running it until it says there are none.


IJavaEventMonitorIDInfo2::GetSpecialClassProperties

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetSpecialClassProperties

The GetSpecialClassProperties method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to obtain a list of classes that have special properties.

The GetSpecialClassProperties method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetSpecialClassProperties(unsigned *pnspecial_classes, ClassID **ppclass_ids, DWORD **ppclass_flags);

Return Value

An array of ClassIDs and an array of associated flags for these ClassIDs for classes for which special information is available.

Parameters

[out] *pnspecial_classes | The number of ClassIDs in the array.
[out] **ppclass_ids | A pointer to an array of ClassIDs that have special properties.
[out] **ppclass_flags | A pointer to a parallel array of a JVM_CLASS_PROPERTIES bitmask for each class with special properties.

Remarks

Classes for which special information is available include instances of java.lang.Class, java.lang.reflect.Method, java.lang.reflect.Field, java.lang.String, and java.lang.StringBuffer.

The possible bitmask flag for each special class can be a combination of the JVM_CLASS_PROPERTIES types or the last predefined combined type.

JVM_CLASS_PROPERTIES

Constant | Value | Description
JVM_CLS_VARIABLE_SIZE | 1 | Fields might not be present in all instances of the class.
JVM_CLS_HAS_DESCRIPTION | 2 | The object might proxy to, or contain internal VM data structures. The DescribeObject method can be used to describe the contents of instances.
ALL_JVM_CLS_PROPERTIES | 3 | All the previous flags are enabled.


IJavaEventMonitorIDInfo2::GetStackTrace

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetStackTrace

The GetStackTrace method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to obtain a stack trace for the specified thread. The profiler must pass the thread ID it is interested in. The Microsoft VM will call the NotifyEvent2 method exported by the profiler, enumerating stack traces for the specified thread from the lowest stack frame to the highest.

The GetStackTrace method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetStackTrace(ThreadID thread_id);

Return Value

E_FAIL if the thread is not in a state in which a stack trace can be obtained. Otherwise, this method call returns the result of the last NotifyEvent2 callback, or S_OK if the stack was empty, or all callbacks return S_OK.

Parameters

[in] thread_id The ThreadID that the profiler is interested in obtaining a stack trace for.

Remarks

Frames are enumerated from lowest to highest through calls to the NotifyEvent2 method implemented by the profiler application. The event type passed to this method will be JVM_EVENT_TYPE2_STACK_TRACE.

The Java thread will be temporarily suspended and no other events will be sent for this thread for the duration of this method. The NotifyEvent2 callback implemented by the profiler should return S_OK to continue enumerating stack frames.

The thread_id parameter can be NULL to indicate the current thread.


IJavaEventMonitorIDInfo2::SampleThreadLocation

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
SampleThreadLocation

The SampleThreadLocation method of the IJavaEventMonitorIDInfo2 interface obtains sample profiling information. This method is called by a profiler program. The profiler must pass the ThreadID it is interested in.

The SampleThreadLocation method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT SampleThreadLocation(ThreadID thread_id, JVM_METHOD_SAMPLE *psample);

Return Value

A sampling structure filled in with current information at that precise moment.

Parameters

[in] thread_id | The ThreadID that the profiler is interested in sampling data on.
[in, out] *psample | The sampling structure filled in with the current information. Note that the first member of this structure (flags) is used upon entry to pass a list of fields that the profiler is interested in getting filled in. Upon exit, this first structure member (flags) indicates which fields contain valid information.

Remarks

This method samples the current method for the given thread. If the method is not known, a "guess" (a recent caller, nearest native caller, and so on) might be returned, along with an estimate of the accuracy. A precise sample can always be obtained using the GetStackTrace method. This method is slower, however, and might require code to be executed before reporting stack frames. The JVM_MONITOR_SAMPLING event notification category is not required to be enabled, but its use will improve the ability to provide accurate samples at the expense of some overhead on non—JIT-compiled method calls.

To collect sample data, a profiler must arrange a way to call the SampleThreadLocation method of the IJavaEventMonitorIDInfo2 interface at periodic intervals. A profiler application is free to use a variety of methods to make periodic calls to SampleThreadLocation. The profiler can call this method in a loop followed by Win32 Sleep function calls. The profiler can set a short timer and call this method when the timer expires. The profiler can use other schemes (waiting for other events) to trigger when to call this method.

To call the SampleThreadLocation method, a profiler must pass in a JVM_METHOD_SAMPLE structure that will receive the sample data. The fields in this structure are defined as shown in the following table.

Variable Type | Structure Member | Comments
DWORD | Flags | Upon entry, this field represents a bitmask of flags from the JVM_METHOD_SAMPLE_FLAGS enumeration indicating which structure fields that the Microsoft VM should fill in. Upon return, this field represents a bitmask of flags indicating which structure fields contain valid data.
JVM_METHOD_SAMPLE_ACCURACY | Accuracy | An estimate of the relative accuracy of the information in this structure.
StackID | stack_id | The stack frame for the currently executing location.
MethodID | Method_id | The method for which the code is executing.
JVM_METHOD_SAMPLE_LOCATION | Location_type | The type (activity) of the code at the location, if known.
DWORD | Ip | The instruction pointer at the time of the sample.
DWORD | Sp | The stack pointer at the time of the sample.
DWORD | pc_offset | The bytecode offset at the time of the sample if the method is currently interpreted.

Upon entry, the flag's DWORD in the JVM_METHOD_SAMPLE structure indicates which fields in the structure are to be filled in by the Microsoft VM. Upon exit, the flag's member indicates which structure members were filled in with data. The allowable value for the JVM_METHOD_SAMPLE_FLAGS can be a combination of the enumeration constants or one of the predefined combinations.

JVM_METHOD_SAMPLE_FLAGS

Constant | Value | Description
JVM_SAMPLE_STACK_ID | 0x1 | On entry to SampleThreadLocation, this value indicates that the StackID should be included in the sampled data. As a returned value from this method, this value indicates that the StackID is valid.
JVM_SAMPLE_METHOD_ID | 0x2 | On entry to SampleThreadLocation, this value indicates that the MethodID should be included the sampled data. As a returned value from this method, this value indicates that the MethodID is valid.
JVM_SAMPLE_LOCATION | 0x4 | On entry to SampleThreadLocation, this value indicates that the JVM_METHOD_SAMPLE_LOCATION (location_type) should be included in the sampled data. As a returned value from this method, this value indicates that the location_type is valid.
JVM_SAMPLE_GENERATED_CODE | 0x8 | This value is only used as a return value to indicate that the sampled ip was in VM-generated code. If possible, the ip field in the JVM_METHOD_SAMPLE structure will be filled in with the caller of the generated code, which can also be generated code.
JVM_SAMPLE_PC | 0x10 | On entry to SampleThreadLocation, this value indicates that the pc_offset (bytecode offset for an interpreted method) should be included in the sampled data. As a returned value from this method, this value indicates that the pc_offset is valid.
ALL_JVM_SAMPLE_FIELDS | 0x17 | This value is a combination of JVM_SAMPLE_STACK_ID, JVM_SAMPLE_METHOD_ID, JVM_SAMPLE_LOCATION, and JVM_SAMPLE_PC.
ALL_JVM_SAMPLE_FLAGS | 0x1F | This value is a combination of JVM_SAMPLE_STACK_ID, JVM_SAMPLE_METHOD_ID, JVM_SAMPLE_LOCATION, JVM_SAMPLE_PC, and JVM_SAMPLE_GENERATED_CODE.

The accuracy member indicates an estimate of the relative accuracy of the information returned into this structure by the Microsoft VM. The accuracy member can be one of the enumeration constants in the following table.

JVM_METHOD_SAMPLE_ACCURACY

Enumeration | Value | Description
JVM_SAMPLE_NONE | 0 | A sample could not be obtained.
JVM_SAMPLE_POOR | 1 | The sample is not very accurate.
JVM_SAMPLE_EXACT | 100 | The sample is 100% accurate.

The location_type indicates where the Java process was executing when the Microsoft VM captured the sampled data. It may be one of the enumeration constants in JVM_METHOD_SAMPLE_LOCATION_TYPES.

JVM_METHOD_SAMPLE_LOCATION_TYPES

Constant | Value | Description
JVM_LOCATION_UNKNOWN | 0 | The sampled location could not be determined.
JVM_LOCATION_JIT | 1 | The sampled location is in JIT-compiled code.
JVM_LOCATION_NATIVE | 2 | The sampled location is in miscellaneous native code (VM, DLL, OS, and so on).
JVM_LOCATION_GC | 3 | The sampled location is performing a garbage collection.
JVM_LOCATION_COMPILER | 4 | The sampled location is compiling a method or performing on-first-call tasks for a method.
JVM_LOCATION_LOADER | 5 | The sampled location is performing a VM class loader-related task.
JVM_LOCATION_DEBUGGER | 6 | The sampled location is performing a VM debugger-related task.
JVM_LOCATION_SECURITY | 7 | The sampled location is performing a VM security-related task.
JVM_LOCATION_PROFILER | 8 | The sampled location is performing a VM profiler-related task.
JVM_LOCATION_BLOCKING | 9 | The sampled location is in a wait state.


IJavaEventMonitorIDInfo2::StaticClassInformation

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
StaticClassInformation

The StaticClassInformation method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to retrieve information about the static data in a class and the size of an instance of the class. The profiler must pass the ClassID of the Java class it is interested in.

The StaticClassInformation method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT StaticClassInformation(ClassID class_id, DWORD *pStaticDataSize, DWORD *pInstanceSize);

Return Value

The size of the static data in the class and the size of the class instance (size of the object on the heap).

Parameters

[in] class_id | The ClassID of the Java class the profiler is interested in.
[out] *pStaticDataSize | The size of the static data in the class.
[out] *pInstanceSize | The size of the class instance (the size of the object on the heap).


IJavaEventMonitorIDInfo2::ThreadInformation

 Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
ThreadInformation

The ThreadInformation method of the IJavaEventMonitorIDInfo2 interface retrieves the Microsoft® Win32® system ThreadID for a Java thread. This method is called by a profiler program. The profiler must pass the Java ThreadID

The ThreadInformation method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT ThreadInformation(ThreadID thread_id, DWORD *pWin32ThreadID);

Return Value

The Win32 thread ID.

Parameters

[in] thread_id | The ThreadID of the Java thread the profiler is interested in.
[out] *pWin32ThreadID | The Win32 thread ID.


IJavaEventMonitorIDInfo3 : IJavaEventMonitorIDInfo2

The IJavaEventMonitorIDInfo3 interface extends IJavaEventMonitorIDInfo2 by adding three methods dealing with method call events.

  // Methods
  ClassInformation2
  EnableMethodCallEvents
  GetMethodEntryParameters
  GetMethodExitReturnValue


Methods (IJavaEventMonitorIDInfo3 Interface)

 Microsoft SDK for Java

IJavaEventMonitorIDInfo3 Interface Methods

The IJavaEventMonitorIDInfo3 interface extends the IJavaEventMonitorIDInfo2 interface with the following methods:

ClassInformation2 returns the ClassID of the Java class's superclass, an array of ClassIDs representing interfaces implemented by the class, and an array of MethodIDs for all methods of the class.

EnableMethodCallEvents can be used to query the current settings, enable notification, or disable method notification callback events for a specific method.
GetMethodEntryParameters can be used to retrieve the entry parameters that are passed to a method before execution of the method begins.
GetMethodExitReturnValue can be used to retrieve the return value from the method call that was just completed.


IJavaEventMonitorIDInfo3::ClassInformation2

 Microsoft SDK for Java

IJavaEventMonitorIDInfo3::
ClassInformation2

The ClassInformation2 method of the IJavaEventMonitorIDInfo3 interface returns the ClassID of the Java class's superclass, an array of ClassIDs representing interfaces implemented by the class, and an array of MethodIDs for all methods of the class.

Use this method to retrieve more detailed information about a class including the ClassID of the class's superclass (or NULL if the class is java.lang.Object), an array of ClassIDs for all the interfaces implemented by the class, and an array of MethodIDs for all the class's methods. An interface may appear in the returned interface list more than once. Base interfaces of explicitly implemented interfaces will be in the list. Consequently, it is not necessary to call ClassInformation2 again for each listed interface to retrieve the interfaces implemented by a superclass.

The list of methods returned by ClassInformation2 includes the contents of the class's vtable plus all static and non-virtual methods. The list of methods will include any private methods of superclasses or other methods that may not be accessible through the given class. Methods may be in the list more than once, and if the class is abstract, abstract methods may also be listed.

The ClassInformation2 method is implemented only by the IJavaEventMonitorIDInfo3 interface.

Syntax

HRESULT ClassInformation2(ClassID class_id, ClassID *psuperclass, ClassID*pinterfaces, unsigned int *pinterfaces_length, MethodID *pimplemented_methods, unsigned int *pimplemented_methods_length);

Parameters

[in] class_id | The ClassID of the class to be profiled.
[out] *psuperclass | The ClassID of the class's superclass.
[out] *pinterfaces | The ClassIDs for all the interfaces implemented by the class.
[out] *pinterfaces_length | The number of interfaces in the returned list.
[out] *pimplemented_methods | The MethodIDs for all the class's methods.
[out] *pimplemented_methods_length | The number of methods in the returned list.


IJavaEventMonitorIDInfo3::EnableMethodCallEvents

 Microsoft SDK for Java

IJavaEventMonitorIDInfo3::
EnableMethodCallEvents

The EnableMethodCallEvents method of the IJavaEventMonitorIDInfo3 interface can be used to query the current settings, enable notification, or disable method notification callback events (MethodEntry, MethodExit, or MethodExit2 calls) for a specific method. The profiler or event monitor passes in an ID of the method or class that it is concerned with, an enumeration value that represents the type of the ID, and an enumeration that represents the disposition requested for this ID.

The EnableMethodCallEvents method is implemented only by the IJavaEventMonitorIDInfo3 interface.

Syntax

HRESULT EnableMethodCallEvents(ObjectID unique_id, JVM_ID_TYPE idtype, JVM_METHOD_CALL_EVENTS_DISPOSITION disposition);

Parameters

[in] unique_id | The ClassID or MethodID that the profiler is interested in.
[in] idtype | The type of the unique_id parameter, either a ClassID (JVM_ID_CLASS) or a MethodID (JVM_ID_METHOD).
[in] disposition | The disposition requested for this ID.

Remarks

The profiler interfaces allow a profiler application to control whether method call events (notifications) are received on a global basis (for all method calls) or only for specific methods. To control method call events on a specific method, the profiler application must have set the bitmask for event type categories for which the Microsoft VM will the send event notifications to include the JVM_MONITOR_SPECIFIC_METHOD_CALLS value of the JAVA_EVENT_CATEGORY enumeration.

The disposition or request type can be any of the values defined in the JVM_METHOD_CALL_EVENTS_DISPOSITION enumeration.

JVM_METHOD_CALL_EVENTS_DISPOSITION

Constant | Value | Description
JVM_PROHIBIT_METHOD_CALL_EVENTS | 1 | Disable method call events for this ClassID or MethodID.
JVM_PERMIT_METHOD_CALL_EVENTS | 2 | Enable method call events for this ClassID or MethodID.
JVM_QUERY_DISPOSITION | 3 | Query the Microsoft VM on the status of method call events for this ClassID or MethodID.

The ID type passed to this method can be either value of the JVM_ID_TYPE enumeration.

JVM_ID_Type

Constant | Value | Description
JVM_ID_METHOD | 5 | A MethodID on which method call events will be enabled or disabled. A MethodID uniquely identifies a method.
JVM_ID_CLASS | 7 | A Class ID on which all method call events will be enabled or disabled. A ClassID uniquely identifies a class.

For example, if a ClassID is passed to EnableMethodCallEvents, the disposition (query, permit, or prohibit method call events) queries or modifies the behavior for all methods of this class.

The JVM_QUERY_DISPOSITION can be specified to determine the status of method call events. This method returns S_OK if the method will be notified (the method is hooked), S_FALSE if not, or E_FAIL if the method is already running. Hooking does not apply to the method, or hooking cannot be disabled for the method.

If the ID type is a JVM_ID_METHOD, the ObjectID passed to this method should be a MethodID. If the ID type is a JVM_ID_CLASS, the ObjectID passed should be a ClassID. The effect of using a ClassID is the same as enumerating all the MethodIDs of a class and invoking this function on each. In this case, the function returns S_OK if all the methods will be notified (hooked), S_FALSE if any of them will not or cannot be notified, or E_FAIL if none of them can be notified.

The final determination by the Microsoft VM to issue method call events on a class method is decided based on the following criteria: If any profiler has requested that a specific method not be hooked by specifying JVM_PROHIBIT_METHOD_CALL_EVENTS, no profilers or event monitors will receive callbacks for the method. The decision by a profiler to prohibit method call events on a method is irreversible. This feature is intended for use by a profiler to disable hooking of methods that are required to execute unobstructed for the proper functioning of the profiler (for example, a profiler that has Java-implemented methods that are invoked in response to a method call event).

If any profiler enables JVM_MONITOR_METHOD_CALLS, all methods (except those specifically prohibited by calls to EnableMethodCallEvents) will result in method call events being sent by the Microsoft VM to any profilers. Any profiler that has requested JVM_MONITOR_METHOD_CALLS or JVM_MONITOR_SPECIFIC_METHOD_CALLS will receive method call events for the method.

If any profiler turns on method call events for a specific set of methods by specifying JVM_PERMIT_METHOD_CALL_EVENTS, all profilers that have requested JVM_MONITOR_SPECIFIC_METHOD_CALLS will receive the events for the methods. If one profiler requests events for a specific method, all profilers will receive the events.

A profiler should not use JVM_PROHIBIT_METHOD_CALL_EVENTS to selectively disable method call events for a method. Instead, the profiler should request that no methods be hooked, and then enable hooking for those particular methods that are of interest. For example, a profiler could implement IJavaEventMonitorIDInfo2, but not return JVM_MONITOR_METHOD_CALLS from GetPossibleEventCategories, enable JVM_MONITOR_CLASS_LOADS, and at each JVM_EVENT_TYPE_CLASS_LOAD_FINISHED event, call EnableMethodCallEvents with JVM_PERMIT_METHOD_CALL_EVENTS to receive method call events for any methods that are interesting.

To prohibit or permit method call events, EnableMethodCallEvents must be called before the method has been executed. Currently, this function will fail if the method has already been executed; it should be called during the class load event for the method's class.


IJavaEventMonitorIDInfo3::GetMethodEntryParameters

 Microsoft SDK for Java

IJavaEventMonitorIDInfo3::
GetMethodEntryParameters

The GetMethodEntryParameters method of the IJavaEventMonitorIDInfo3 interface can be used to retrieve the entry parameters that are passed to a method before execution of the method begins.

A profiler can only call GetMethodEntryParameters during a MethodEntry callback notification.

The GetMethodEntryParameters method is implemented only by the IJavaEventMonitorIDInfo3 interface.

Syntax

HRESULT GetMethodEntryParameters(DWORD **ppslots, DWORD **ppreserved, JVM_CALLING_CONVENTION *pcalling_convention, DWORD *pflags);

Return Value

A pointer to the base of an array of the parameters passed to the current method, a bitmask of call flags, and value that represents the calling convention for the method.

Parameters

[out] **ppslots | A pointer to the base of an array of the parameters passed to the current method.
[out] **ppreserved | A pointer to an array of reserved elements.
[out] *pcalling_convention | The calling convention for the method.
[out] *pflags | A bitmask of JVM_CALL_FLAGS.

Remarks

The calling convention for the method about to be executed can be any of the values defined in the JVM_CALLING_CONVENTION enumeration.

JVM_CALLING_CONVENTION

Constant | Value | Description
JVM_CALL_PASCAL | 1 | This method uses the Pascal calling convention where the parameters are pushed on the stack in the order that they appear in the method's prototype.
JVM_CALL_CDECL | 2 | This method uses the C calling convention where the parameters are pushed on the stack in the reverse order that they appear in the method's prototype.

To properly interpret method parameters, a profiler application would need to parse the signature for this method. This parameter signature can be retrieved by calling the MethodInformation method.

Only the JVM_CALL_THIS value of the JVM_CALL_FLAGS enumeration is defined for the call flags for a method.

JVM_CALL_FLAGS

Constant | Value | Description
JVM_CALL_THIS | 1 | When this call flag is set, it indicates that the method is non-static. When this flag is clear, it indicates that the method is static.


IJavaEventMonitorIDInfo3::GetMethodExitReturnValue

 Microsoft SDK for Java

IJavaEventMonitorIDInfo3::
GetMethodExitReturnValue

The GetMethodExitReturnValue method of the IJavaEventMonitorIDInfo3 interface can be used to retrieve the return value from the method call that was just completed.

The profiler can only call GetMethodExitReturnValue during a MethodExit or MethodExit2 callback notification.

The GetMethodExitReturnValue method is implemented only by the IJavaEventMonitorIDInfo3 interface.

Syntax

HRESULT GetMethodExitReturnValue(MethodID *preturning_method_id, __int64 **pret_value);

Return Value

The MethodID of the method that is exiting and its return value.

Parameters

[out] *preturning_method_id | The MethodID of the method that was just completed.
[out] **pret_value | The method return value for the method that was just completed.

Remarks

To properly interpret the return value (its type and value), a profiler would need to parse the signature for this method. This parameter signature can be retrieved by calling the MethodInformation method.


IJavaEventMonitorIDInfo4 : IJavaEventMonitorIDInfo3

The IJavaEventMonitorIDInfo4 interface extends IJavaEventMonitorIDInfo3 by adding three methods that deal with initialization.

  // Methods
  GetMonitorInitializationOptions
  SetMonitorInitializationOptions
  GetFinalInitializationOptions


Methods (IJavaEventMonitorIDInfo4 Interface)

 Microsoft SDK for Java

IJavaEventMonitorIDInfo4 Interface Methods

The IJavaEventMonitorIDInfo4 interface has the following methods.

GetMonitorInitializationOptions retrieves the per-monitor initialization options that were set through SetMonitorInitializationOptions.
SetMonitorInitializationOptions sets the initialization options requested by this monitor.
GetFinalInitializationOptions retrieves the final options used to initialize profiling support.


IJavaEventMonitorIDInfo4::GetMonitorInitializationOptions

 Microsoft SDK for Java

IJavaEventMonitorIDInfo4::
GetMonitorInitializationOptions

The GetMonitorInitializationOptions method of the IJavaEventMonitorIDInfo4 interface retrieves the per-monitor initialization options that were set through SetMonitorInitializationOptions. After all monitors have been initialized, GetFinalInitializationOptions may be used to retrieve the options that were actually used to initialize profiling support.

Syntax

HRESULT GetMonitorInitializationOptions([out] DWORD *pflags);

Parameters

[out] *pflags A bitmask of JAVA_MONITOR_INIT_OPTIONS.


IJavaEventMonitorIDInfo4::SetMonitorInitializationOptions

 Microsoft SDK for Java

IJavaEventMonitorIDInfo4::
SetMonitorInitializationOptions

The SetMonitorInitializationOptions method of the IJavaEventMonitorIDInfo4 interface sets the initialization options requested by this monitor. This method will fail after all monitors have been initialized, which is indicated by receipt of JVM_EVENT_TYPE2_MONITORS_INITIALIZED. Event monitors may call GetFinalInitializationOptions when JVM_EVENT_TYPE2_MONITORS_INITIALIZED is received to check which options were enabled.

Syntax

HRESULT SetMonitorInitializationOptions([in] DWORD flags);

Parameters

[in] flags A bitmask of JAVA_MONITOR_INIT_OPTIONS.


IJavaEventMonitorIDInfo4::GetFinalInitializationOptions

 Microsoft SDK for Java

IJavaEventMonitorIDInfo4::
GetFinalInitializationOptions

The GetFinalInitializationOptions method of the IJavaEventMonitorIDInfo4 interface retrieves the final options used to initialize profiling support. This method will fail before all monitors have been initialized, which is indicated by receipt of JVM_EVENT_TYPE2_MONITORS_INITIALIZED.

Syntax

HRESULT GetFinalInitializationOptions([out] DWORD *pflags);

Parameters

[out] *pflags A bitmask of JAVA_MONITOR_INIT_OPTIONS.


Event Notification Profiler Interfaces Overview

Profiler Interfaces Reference

The Microsoft VM communicates with a profiler application using these interfaces to notify the profiler when events occur.

For general information, see Implementing Event Notification Interfaces in the Programmer's Guide.

This section contains the following:

Interfaces

Hierarchy


Event Notification Profiler Interfaces

The event notification profiler interfaces are as follows:

IJavaEventMonitor notifies a profiler when registered events occur.

IJavaEventMonitor2 extends IJavaEventMonitor by adding three methods.


Event Notification Profiler Interfaces Hierarchy

The event notification profiler interfaces have the following hierarchy.

IUnknown
  |
  +--IJavaEventMonitor
  |  |
  |  +--IJavaEventMonitor2


IJavaEventMonitor : IUnknown

The Microsoft VM uses IJavaEventMonitor to notify a profiler when registered events occur or are about to occur in an active Java process. This is the primary callback interface through which the Microsoft VM communicates with the profiler. The CLSID of the class implementing this callback interface must be registered by the profiler in the Win32 registry or in the environment. This interface includes several methods that are called by the VM when an event occurs in an executing Java process.

To use the Java profiler interfaces, a profiler program must either set an environment variable or create a registry entry to register IJavaEventMonitor with the Microsoft VM. Note that this differs from using the debugger interfaces, which are based on a debugger program calling registration interfaces implemented by the Microsoft VM.

  // Methods
  ExecuteByteCode
  ExecuteSourceLine
  Initialize
  MethodEntry
  MethodExit
  NotifyEvent


Methods (IJavaEventMonitor Interface)

 Microsoft SDK for Java

IJavaEventMonitor Interface Methods

The IJavaEventMonitor interface contains the following methods.

ExecuteByteCode is called by the Microsoft VM to notify the profiler when the execution of a Java bytecode instruction is about to occur.
ExecuteSourceLine is called by the Microsoft VM to notify the profiler when the execution of a source line is about to occur. Not currently implemented.
Initialize is called by the Microsoft VM to initialize the profiler (event monitor) whenever a new Java process is started.
MethodEntry is called by the Microsoft VM to notify the profiler when a Java method is about to be entered.
MethodExit is called by the Microsoft VM to notify the profiler when a Java method is about to be exited.
NotifyEvent is called by the Microsoft VM to notify the profiler when an event from the JVM_EVENT_TYPE enumeration is about to occur.


IJavaEventMonitor::ExecuteByteCode

 Microsoft SDK for Java

IJavaEventMonitor::
ExecuteByteCode

The ExecuteByteCode method of the IJavaEventMonitor interface is called by the Microsoft VM to notify the profiler when the execution of a Java bytecode instruction is about to occur. The Microsoft VM passes in a MethodID for the method that is executing, a pointer to the bytecode instructions for this method, and an offset from the start of the method to the bytecode instruction that is about to be executed.

Syntax

HRESULT ExecuteByteCode(MethodID method_id, BYTE_CODE *pbyte_code, DWORD byte_code_offset);

Parameters

[in] method_id | The MethodID of the method that is executing.
[in] *pbyte_code | A pointer to the bytecode instructions for this method.
[in] byte_code_offset | An offset to the bytecode from the start of the method for the instruction that is about to be executed.

Remarks

The profiler can call the MethodInformation method implemented by the Microsoft VM to retrieve information about this MethodID. In particular, MethodInformation will return the execution model for this method (interpreted, fast-interpreted, JIT-compiled, native Win32, or COM).


IJavaEventMonitor::ExecuteSourceLine

 Microsoft SDK for Java

IJavaEventMonitor::
ExecuteSourceLine

The ExecuteSourceLine method of the IJavaEventMonitor interface is called by the Microsoft VM to notify the profiler when the execution of a source line is about to occur. The Microsoft VM passes in a MethodID for the method that is executing and a line number of the source line that is about to be executed. This method is not currently implemented.

Syntax

HRESULT ExecuteSourceLine(MethodID method_id, DWORD line_number);

Parameters

[in] method_id | The MethodID of the method that is executing.
[in] line_number | The line number of the source line that is about to be executed.

Remarks

The profiler can call the MethodInformation method implemented by the Microsoft VM to retrieve information about this MethodID. In particular, MethodInformation will return source line information and the execution model for this method (interpreted, fast-interpreted, JIT-compiled, native Win32, or COM).


IJavaEventMonitor::Initialize

 Microsoft SDK for Java

IJavaEventMonitor::
Initialize

The Initialize method of the IJavaEventMonitor interface is called by the Microsoft VM to initialize the profiler (event monitor) whenever a new Java process is started. The Microsoft VM passes in the class name of the Java class that started the VM, a pointer to an IJavaEventMonitorIDInfo object implemented by the Microsoft VM, the Microsoft VM state flags, and a pointer to the requested events that will trigger notification. The profiler must set the requested events bitmask to the list of events for which it wants to receive notification.

Syntax

HRESULT Initialize(LPCSTR pclass_file_name, IJavaEventMonitorIDInfo *pmonitor_info, DWORD java_flags, DWORD *prequested_events);

Return Value

A list of events for which the profiler wants to receive notification.

Parameters

[in] pclass_file_name | The string name of the class in UTF-8 format that started the Microsoft VM. This parameter is taken directly from the Java class file, unmodified.
[in] pmonitor_info | The Microsoft VM passes in a pointer to the IJavaEventMonitorIDInfo object that it implements. The profiler application calls methods on this interface to communicate with the MicrosoftVM.
[in] java_flags | A bitmask of JVM_STATE_FLAGS that indicate which features are enabled in the Microsoft VM for this Java process.
[out] prequested_events | A pointer to a bitmask of flags from the JAVA_EVENT_CATEGORY enumeration indicating events for which the profiler wants to receive notification.

Remarks

The Microsoft VM passes the profiler the name of Java class that has started execution of the VM. The profiler is also passed a set of flags that indicate the state of the Microsoft VM and which features are enabled. These state flags can be a combination of the flags defined in the JVM_STATE_FLAGS enumeration.

JAVA_STATE_FLAGS

Constant | Value | Description
JVM_STATE_INTERPRETER_ENABLED | 0x1 | The Java interpreter is enabled.
JVM_STATE_FAST_INTERPRETER_ENABLED | 0x2 | The fast interpreter is enabled.
JVM_STATE_JIT_COMPILER_ENABLED | 0x4 | The JIT-compiler is enabled.
JVM_STATE_DEBUGGER_ENABLED | 0x8 | The debugger is enabled.
ALL_JVM_FLAGS | 0xF | All the previous flags are enabled.

The Microsoft VM passes the profiler application a pointer to a bitmask of flags from JAVA_EVENT_CATEGORY indicating which events that the profiler wants to receive notification for. The profiler application should set this parameter to the bitmask of events for which it wants to receive notification. Profilers or event monitors can request notification for any combination of the event categories as defined in the JAVA_EVENT_CATEGORY enumeration.

JAVA_Event_Category

Constant | Value | Description
JVM_MONITOR_NONE | 0 | Do not send notification for any event categories.
JVM_MONITOR_CLASS_LOADS | 1 | Send event notification when a Java class is loaded or when the class is unloaded. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_METHOD_CALLS | 2 | Send event notification when a Java method is about to be called and upon completion of the method call. The Microsoft VM will call the MethodEntry and MethodExit methods implemented by the profiler. If the profiler implements IJavaEventMonitor2 interface, the Microsoft VM will call MethodExit2 on this interface rather than MethodExit.
JVM_MONITOR_JIT_COMPILATION | 4 | Send event notification when a Java class is about to be JIT compiled and after JIT compilation is completed. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_BYTE_CODE_EXECUTION | 8 | Send event notification when a byte code instruction of an interpreted method is about to be executed. The Microsoft VM will call the ExecuteByteCode method implemented by the profiler. If any profiler requests this event category, then JIT compilation will be disabled for all methods.
JVM_MONITOR_SOURCE_LINE_EXECUTION | 0x10 | Send event notification when a Java source line is about to be executed. The Microsoft VM will call the ExecuteSourceLine method implemented by the profiler.
JVM_MONITOR_EXCEPTIONS | 0x20 | Send event notification when an exception is about to be thrown. The Microsoft VM will call the NotifyEvent2 method if the IJavaEventMonitor2 interface is implemented by the profiler. Otherwise the Microsoft VM will call the NotifyEvent method.
JVM_MONITOR_GARBAGE_COLLECTIONS | 0x80 | Send event notification when the VM is about to execute garbage collection. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_THREADS | 0x100 | Send event notification when a Java thread is about to be created or destroyed. The Microsoft VM will call the NotifyEvent method implemented by the profiler. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will also call the NotifyEvent2 method when a thread's name has been set.
JVM_MONITOR_SAMPLING | 0x200 | Changes the behavior of the Microsoft VM to improve the accuracy of sampling. Note that this event category doesn't generate any additional event notifications, but improves the accuracy of the SampleThreadLocation method implemented by the Microsoft VM. Specifying this event category slows down the execution of non-JIT compiled methods, but improves the accuracy of the sampling data for these methods.
JVM_MONITOR_EXCEPTION_UNWIND | 0x400 | Send event notification when a Java exception is about to be thrown past a stack frame. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will call the NotifyEvent2 method.
JVM_MONITOR_SPECIFIC_METHOD_CALLS | 0x800 | Send event notification when specific methods are called. The Microsoft VM will call the MethodEntry and MethodExit methods implemented by the profiler. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will call the MethodExit2 method rather than MethodExit.
ALL_JVM_MONITOR_EVENTS | 0xFFF | Send event notification on all event categories.


IJavaEventMonitor::MethodEntry

 Microsoft SDK for Java

IJavaEventMonitor::
MethodEntry

The MethodEntry method of the IJavaEventMonitor interface is called by the Microsoft VM to notify the profiler when a Java method is about to be entered. The Microsoft VM passes in a MethodID for this method and a StackID for this method's stack frame. The profiler must manually keep track of each StackID to determine which method is about to exit (notified by MethodExit or MethodExit2).

Syntax

HRESULT MethodEntry(MethodID method_id, StackID stack_id);

Parameters

[in] method_id | The MethodID for this method.
[in] stack_id | The StackID for this method call.

Remarks

The profiler can call the MethodInformation method implemented by the Microsoft VM to retrieve information about this MethodID. In particular, MethodInformation will return the class name for this method, the ClassID for the class containing this method, source line information, and the execution model for this method (interpreted, fast-interpreted, JIT-compiled, native Win32, or COM). Depending on the execution model, a profiler application can call InterpretedMethodInformation to retrieve the interpreted bytecodes for an interpreted method or JITCompiledMethodInformation to retrieve the JIT code for a JIT-compiled method.


IJavaEventMonitor::MethodExit

 Microsoft SDK for Java

IJavaEventMonitor::
MethodExit

The MethodExit method of the IJavaEventMonitor interface is called by the Microsoft VM to notify the profiler when a Java method is about to be exited. The Microsoft VM passes in a StackID for the calling frame that the method is exiting to. At the topmost method return, MethodExit is called with a NULL StackID. The profiler must have saved the StackID passed to a MethodEntry call to determine which method is about to be exited.

Syntax

HRESULT MethodExit(StackID stack_id);

Parameters

[in] stack_id The StackID for the calling frame that the method is exiting to. At the topmost method return, MethodExit is called with a NULL StackID.


IJavaEventMonitor::NotifyEvent

 Microsoft SDK for Java

IJavaEventMonitor::
NotifyEvent

The NotifyEvent method of the IJavaEventMonitor interface is called by the Microsoft VM to notify the profiler when an event from the JVM_EVENT_TYPE enumeration is about to occur. The Microsoft VM passes in the event type and a unique ID. The type of the ID passed is dependent on the type of event that is about to occur.

Syntax

HRESULT NotifyEvent(JVM_EVENT_TYPE event, UniqueID event_id);

Parameters

[in] event | The JVM_EVENT_TYPE that is about to occur.
[in] event_id | A UniqueID that is interpreted differently depending on the JVM_EVENT_TYPE that is about to occur.

Remarks

The NotifyEvent method receives an event type passed as its first parameter along with a unique ID to some object for the second parameter. The type of the ID passed to NotifyEvent is determined by the event type. The possible event types and the associated unique IDs passed to the NotifyEvent method can be one of the types defined in the JVM_EVENT_TYPE enumeration.

JVM_EVENT_TYPE

Constant | Value | Description
JVM_EVENT_TYPE_EXCEPTION_OCCURRED | 0 | An exception occurred. The UniqueID passed as the second parameter is a StackID of the stack frame that the exception handler will be executed in.
JVM_EVENT_TYPE_THREAD_CREATE | 4 | A Java thread is being created. The UniqueID passed as the second parameter is the ThreadID of the Java thread.
JVM_EVENT_TYPE_THREAD_DESTROY | 5 | A Java thread is being destroyed. The UniqueID passed as the second parameter is the ThreadID of the Java thread.
JVM_EVENT_TYPE_CLASS_LOAD_STARTED | 6 | A Java class is starting to be loaded. The UniqueID passed as the second parameter is a pointer to the class name (a UTF-8 string) of the class.
JVM_EVENT_TYPE_CLASS_LOAD_FINISHED | 7 | A Java class is finished loading. The UniqueID passed as the second parameter is a pointer to the ClassID of the class loaded.
JVM_EVENT_TYPE_CLASS_LOAD_FAILED | 17 | A Java class failed to be loaded. The UniqueID passed as the second parameter is a pointer to the class name (a UTF-8 string) of the class.
JVM_EVENT_TYPE_CLASS_UNLOAD | 8 | A Java class is being unloaded. The UniqueID passed as the second parameter is the ClassID of the class.
JVM_EVENT_TYPE_JIT_COMPILE_STARTED | 9 | The JIT compiler is starting to compile a class method. The UniqueID passed as the second parameter is the MethodID of the class method being compiled.
JVM_EVENT_TYPE_JIT_COMPILE_FINISHED | 10 | The JIT compiler is finished compiling a class method. The UniqueID passed as the second parameter is the MethodID of the class method that was compiled.
JVM_EVENT_TYPE_GC_STARTED | 11 | Garbage collection is starting. The UniqueID passed as the second parameter is undefined (this parameter is not used).
JVM_EVENT_TYPE_GC_FINISHED | 12 | Garbage collection has finished. The UniqueID passed as the second parameter is undefined. (This parameter is not used.)
JVM_EVENT_TYPE_SHUTDOWN | 12 | The program is exiting. The UniqueID passed as the second parameter is undefined. (This parameter is not used.)
JVM_EVENT_TYPE_RESERVED_14 | 14 | This event type, formerly called JVM_EVENT_TYPE_SHUTDOWN_ERROR, is deprecated and no longer dispatched by the Microsoft VM.
JVM_EVENT_TYPE_RESERVED_15 | 15 | This event type, formerly called JVM_EVENT_TYPE_SHUTDOWN_INTERRUPTED, is deprecated and no longer dispatched by the Microsoft VM.
JVM_EVENT_TYPE_RESERVED_17 | 17 | This formerly reserved event type is now used for JVM_EVENT_TYPE_CLASS_LOAD_FAILED.

Certain events might require special synchronization with the use of methods that operate on the event's parameters. For example, a JVM_EVENT_TYPE_THREAD_DESTROY event might be sent before another thread gets to use the ThreadInformation method. The Microsoft VM does not check that the ID of the thread has been destroyed. Profiler applications should take care to synchronize the destruction events with their uses of these IDs by ensuring that the last use of the ID occurs before returning from handling the destruction event.

Events and IDs that need to be synchronized include these:

JVM_EVENT_TYPE_THREAD_DESTROY

The ThreadID of the destroyed thread can no longer be used by the profiler application.

JVM_EVENT_TYPE_CLASS_UNLOAD

The ClassID, MethodIDs for the methods of the unloaded class, and FieldIDs for fields of the unloaded class can no longer be used by the profiler application.


IJavaEventMonitor2 : IJavaEventMonitor

IJavaEventMonitor2 extends IJavaEventMonitor by adding three methods.

  // Methods
  GetPossibleEventCategories
  MethodExit2
  NotifyEvent2


Methods (IJavaEventMonitor2 Interface)

 Microsoft SDK for Java

IJavaEventMonitor2 Interface Methods

The IJavaEventMonitor2 interface has the following methods:

GetPossibleEventCategories is called by the Microsoft VM to query the profiler to determine which event categories might ever be enabled for notification.
MethodExit2 is called by the Microsoft VM to notify the profiler when a method is about to be exited.
NotifyEvent2 is called by the Microsoft VM to notify the profiler when an event from JVM_EVENT_TYPE2 is about to occur.


IJavaEventMonitor2::GetPossibleEventCategories

 Microsoft SDK for Java

IJavaEventMonitor2::
GetPossibleEventCategories

The GetPossibleEventCategories method of the IJavaEventMonitor2 interface is called by the Microsoft VM to query the profiler to determine which event categories might ever be enabled for notification. This method is only supported on the IJavaEventMonitor2 interface.

Syntax

HRESULT GetPossibleEventCategories(DWORD *ppossible_events);

Return Value

The MethodID of the method the profiler is interested in.

Parameters

[out] *ppossible_events The MethodID of the method the profiler is interested in.

Remarks

After the Initialize method is called (and returns S_OK), the Microsoft VM checks to determine if the IJavaEventMonitor2 interface is supported by the profiler application. If this interface is supported, the VM calls the GetPossibleEventCategories method to determine which event categories might ever be enabled by the profiler in this Java process (the bitmask for the maximum possible list of event categories). If some event categories will never be enabled for this process, the VM can optimize internal operations by eliminating some profiling overhead.

The profiler application should set the possible_events parameter to the bitmask of the maximum possible list of events for which it might ever want to receive notification. The possible events that can be notified can be any combination of the event categories defined in the JAVA_EVENT_CATEGORY enumeration.

JAVA_Event_Category

Constant | Value | Description
JVM_MONITOR_NONE | 0 | Do not send notification for any event categories.
JVM_MONITOR_CLASS_LOADS | 1 | Send event notification when a Java class is loaded or when the class is unloaded. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_METHOD_CALLS | 2 | Send event notification when a Java method is about to be called and upon completion of the method call. The Microsoft VM will call the MethodEntry and MethodExit methods implemented by the profiler. If the profiler implements IJavaEventMonitor2 interface, the Microsoft VM will call MethodExit2 on this interface rather than MethodExit.
JVM_MONITOR_JIT_COMPILATION | 4 | Send event notification when a Java class is about to be JIT compiled and after JIT compilation is completed. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_BYTE_CODE_EXECUTION | 8 | Send event notification when a byte code instruction of an interpreted method is about to be executed. The Microsoft VM will call the ExecuteByteCode method implemented by the profiler. If any profiler requests this event category, then JIT compilation will be disabled for all methods.
JVM_MONITOR_SOURCE_LINE_EXECUTION | 0x10 | Send event notification when a Java source line is about to be executed. The Microsoft VM will call the ExecuteSourceLine method implemented by the profiler.
JVM_MONITOR_EXCEPTIONS | 0x20 | Send event notification when an exception is about to be thrown. The Microsoft VM will call the NotifyEvent2 method if the IJavaEventMonitor2 interface is implemented by the profiler. Otherwise the Microsoft VM will call the NotifyEvent method.
JVM_MONITOR_GARBAGE_COLLECTIONS | 0x80 | Send event notification when the VM is about to execute garbage collection. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_THREADS | 0x100 | Send event notification when a Java thread is about to be created or destroyed. The Microsoft VM will call the NotifyEvent method implemented by the profiler. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will also call the NotifyEvent2 method when a thread's name has been set.
JVM_MONITOR_SAMPLING | 0x200 | Changes the behavior of the Microsoft VM to improve the accuracy of sampling. Note that this event category doesn't generate any additional event notifications, but improves the accuracy of the SampleThreadLocation method implemented by the Microsoft VM. Specifying this event category slows down the execution of non-JIT compiled methods, but improves the accuracy of the sampling data for these methods.
JVM_MONITOR_EXCEPTION_UNWIND | 0x400 | Send event notification when a Java exception is about to be thrown past a stack frame. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will call the NotifyEvent2 method.
JVM_MONITOR_SPECIFIC_METHOD_CALLS | 0x800 | Send event notification when specific methods are called. The Microsoft VM will call the MethodEntry and MethodExit methods implemented by the profiler. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will call the MethodExit2 method rather than MethodExit.
ALL_JVM_MONITOR_EVENTS | 0xFFF | Send event notification on all event categories.


IJavaEventMonitor2::MethodExit2

 Microsoft SDK for Java

IJavaEventMonitor2::
MethodExit2

The MethodExit2 method of the IJavaEventMonitor2 interface is called by the Microsoft VM to notify the profiler when a method is about to be exited. The Microsoft VM passes in the MethodID for caller and a StackID of the calling frame that the method is exiting to. At the topmost method return, MethodExit2 is called with a NULL MethodID and a NULL StackID. The profiler must have saved the MethodID or StackID passed to a MethodEntry call to know which method is about to be exited.

The MethodExit2 method is supported only by the IJavaEventMonitor2 interface.

Syntax

HRESULT MethodExit2(MethodID method_id StackID stack_id);

Parameters

[in] method_id | The MethodID of the method that is about to exit.
[in] stack_id | The StackID for this method call.

Remarks

Note that the MethodExit2 method will be called by the Microsoft VM if the profiler implements the IJavaEventMonitor2 interface. The MethodExit method will not be called under these circumstances.


IJavaEventMonitor2::NotifyEvent2

 Microsoft SDK for Java

IJavaEventMonitor2::
NotifyEvent2

The NotifyEvent2 method of the IJavaEventMonitor2 interface is called by the Microsoft VM to notify the profiler when an event from JVM_EVENT_TYPE2 is about to occur. The Microsoft VM passes in the event type and two unique IDs. The type of the IDs passed is dependent on the type of the event that is about to occur.

The MethodExit2 method is supported only by the IJavaEventMonitor2 interface.

Syntax

HRESULT NotifyEvent2(JVM_EVENT_TYPE2 event2, UniqueID first_event_id, UniqueID second_event_id);

Parameters

[in] event2 | The JVM_EVENT_TYPE2 that is about to occur.
[in] first_event_id | A UniqueID that is interpreted according to the JVM_EVENT_TYPE2 that is about to occur.
[in] second_event_id | A UniqueID that is interpreted according to the JVM_EVENT_TYPE2 that is about to occur.

Remarks

The NotifyEvent2 method receives an event type passed as its first parameter along with two unique IDs to some objects. The type of the object IDs passed to NotifyEvent2 is determined by the event type. The possible event types and the associated unique IDs passed to the NotifyEvent2 method can be one of the types defined in the JVM_EVENT_TYPE2 enumeration.

JAVA_EVENT_TYPE2

Constant | Value | Description
JVM_EVENT_TYPE2_THREAD_SET_NAME | 1025 | A thread's name has been set.
JVM_EVENT_TYPE2_EXCEPTION_OCCURRED | 1026 | An exception occurred. This event supercedes JVM_EVENT_TYPE_EXCEPTION_OCCURRED if IJavaEventMonitor2 is implemented and JVM_EVENT_TYPE_EXCEPTION_OCCURRED will never be passed to NotifyEvent.
JVM_EVENT_TYPE2_EXCEPTION_THROWN | 1027 | An exception is about to be thrown.
JVM_EVENT_TYPE2_EXCEPTION_UNWIND | 1028 | An exception is being thrown past this frame.
JVM_EVENT_TYPE2_STACK_TRACE | 1029 | This event notifies a callback from GetStackTrace.
JVM_EVENT_TYPE2_INITIALIZED | 1030 | The Microsoft VM has fully initialized.


Heap Monitor Information Profiler Interface Overview

Profiler Interfaces Reference

A profiler or heap monitoring application uses IJavaHeapMonitor to register its callback interfaces for heap monitoring with the Microsoft VM and request heap information.

For general information, see Registering with the Heap Monitor in the Programmer's Guide.

This section contains the following:

Interface


Heap Monitor Information Profiler Interface

The heap monitor information interfaces are as follows:

IJavaHeapMonitor is used by a memory profiler to communicate with the Microsoft VM for registering the heap monitoring callback interfaces implemented by the profiler and to request heap monitoring information from the Microsoft VM.

IJavaHeapMonitor2 extends IJavaHeapMonitor by adding one method.


IJavaHeapMonitor : IUnknown

The IJavaHeapMonitor interface is used by a memory profiler to communicate with the Microsoft VM for registering the heap monitoring callback interfaces implemented by the profiler and to request heap monitoring information from the Microsoft VM.

The Microsoft VM implements the IJavaHeapMonitor interface. A profiler can determine if the Microsoft VM supports heap monitoring and locate this interface by calling QueryInterface on the IJavaEventMonitorIDInfo interface passed to the profiler upon startup. The profiler application should query for the IJavaHeapMonitor interface (IID_IJavaHeapMonitor).

The profiler or heap monitoring application that plans to use the interface should call the AddRef method on IJavaHeapMonitor.

A profiler or heap monitoring application can call methods on the IJavaHeapMonitor interface to request heap information about an executing Java process. The profiler must call GetHeapInfo on this object's interface to provide a callback through which the Microsoft VM communicates with the profiler regarding heap enumerations after garbage collection. The profiler must call NotifyOnObjectAllocations on this object's interface to provide a callback through which the Microsoft VM communicates with the profiler for notification on individual Java object allocations.

The heap monitoring interface uses the concept of containers for representing heap usage. Using containers, a memory profiler application can completely rebuild all the containment hierarchy for heap memory starting from root containers. Container types are defined for threads, static class references, objects awaiting finalization, internal VM objects, and various frames (native, native garbage collection, COM, interpreted method, and fast-interpreted method).

The methods implemented on this interface return S_OK on success, or E_FAIL on failure.

  // Methods
  GetContainerDescription
  GetHeapInfo
  GetObjectAge
  ModifyHeapMonitorCapabilities
  NotifyOnObjectAllocations


Methods (IJavaHeapMonitor Interface)

 Microsoft SDK for Java

IJavaHeapMonitor Interface Methods

The IJavaHeapMonitor interface contains the following methods.

GetContainerDescription is called by a memory profiler to obtain a description of a given container type.
GetHeapInfo is called by a memory profiler to register its callback interface for receiving notification when the heap is dumped at the end of each garbage collection.
GetObjectAge is called by a memory profiler to determine the number of garbage collections a Java object has survived.
ModifyHeapMonitorCapabilities is called by a memory profiler to query or modify the heap monitoring capabilities provided by the Microsoft VM.
NotifyOnObjectAllocations is called by a memory profiler to register its callback interface for receiving notification when an individual object is created (allocated on the heap).


IJavaHeapMonitor::GetContainerDescription

 Microsoft SDK for Java

IJavaHeapMonitor::
GetContainerDescription

The GetContainerDescription method of the IJavaHeapMonitor interface is called by a memory profiler to obtain a description of a given container type.

Syntax

HRESULT GetContainerDescription(CONTAINER_TYPE type, LPWSTR *pshort, LPWSTR *plong);

Return Value

A short Unicode string (shorter description) and a long Unicode string (longer description) describing the container.

Parameters

[in] type | The type of the container that the profiler is interested in.
[out] *pshort | A short Unicode string, describing the container type.
[out] *plong | A long Unicode string, describing the container type.

Remarks

If a memory profiler has registered a callback, the Microsoft VM will send notifications to BeginContainer with a container type. A memory profiler can pass this container type to GetContainerDescription to obtain a description the container type.


IJavaHeapMonitor::GetHeapInfo

 Microsoft SDK for Java

IJavaHeapMonitor::
GetHeapInfo

The GetHeapInfo method of the IJavaHeapMonitor interface is called by a memory profiler to register its callback interface for receiving notification when the heap is dumped at the end of each garbage collection. The single parameter passed in is a pointer to the IHeapInfoCallback interface implemented by the profiler. A memory profiler application can only have one callback installed at a time. To unregister the callback, this method can be called with a NULL pointer.

The Microsoft VM communicates with the profiler dumping the heap by calling various methods on the profiler's callback interface that is passed to GetHeapIno.

Syntax

HRESULT GetHeapInfo(IHeapInfoCallback *pihicb);

Parameters

[in] *pihicb A pointer to the IHeapInfoCallback interface implemented by the profiler.

Remarks

If a memory profiler has registered a callback, the Microsoft VM will dump the heap after each garbage collection to methods on the profiler's IHeapInfoCallback interface passed to this function. If a profiler does not want this heap dump to occur, it must unregister this callback by calling GetHeapInfo method with a NULL pointer.


IJavaHeapMonitor::GetObjectAge

 Microsoft SDK for Java

IJavaHeapMonitor::
GetObjectAge

The GetObjectAge method of the IJavaHeapMonitor interface is called by a memory profiler to determine the number of garbage collections a Java object has survived.

Syntax

HRESULT GetObjectAge(ObjectID object_id, DWORD *pncollections_survived);

Return Value

A count of the number of garbage collections survived.

Parameters

[in] object_id | The ObjectID of the object that the memory profiler is interested in.
[out] *pncollections_survived | This returned parameter is a count of the number of garbage collections the object has survived.

Remarks

The ObjectID of a heap object is passed to the profiler's OnObjectAllocated method when individual objects are allocated. To maintain a persistent handle to an object across garbage collections, a profiler should call GetHandlesToObjects to obtain a persistent handle. At some later time, the profiler application can call GetObjectsFromHandles to convert this persistent handle to an ObjectID to be used in calling the GetObjectAge method.


IJavaHeapMonitor::ModifyHeapMonitorCapabilities

 Microsoft SDK for Java

IJavaHeapMonitor::
ModifyHeapMonitorCapabilities

The ModifyHeapMonitorCapabilities method of the IJavaHeapMonitor interface is called by a memory profiler to query or modify the heap monitoring capabilities provided by the Microsoft VM. The application can request that specific heap monitoring functions be enabled or disabled. This method takes two input parameters: a bitmask of heap monitoring capability flags (from the JVM_HEAPMON_CAPABILITIES enumeration) and a Boolean variable that indicates whether these capabilities should be enabled or disabled. Currently, the only capability supported is whether the object's age (the number of garbage collections that the object has survived) is maintained by the Microsoft VM.

Syntax

HRESULT ModifyHeapMonitorCapabilities(DWORD capabilities, BOOL fenable, DWORD *penabled_capabilities);

Return Value

A bitmask of flags representing the enabled heap monitoring capabilities from the JVM_HEAPMON_CAPABILITIES enumeration.

Parameters

[in] capabilities | A bitmask of flags of heap monitoring capabilities (JVM_HEAPMON_CAPABILITIES) that are requested.
[in] fenable | A boolean variable that indicates whether these capabilities should be enabled (when set to TRUE) or disabled (when set to FALSE).
[out] *penabled_capabilities | A bitmask representing the enabled heap monitoring capabilities (JVM_HEAPMON_CAPABILITIES).

JVM_HEAPMON_CAPABILITIES

Constant | Value | Description
JVM_HEAPMON_OBJECT_AGE | 1 | Keeps track of the age of an object (how many garbage collections the object has survived). This can be modified only during the profiler's Initialize callback.


IJavaHeapMonitor::NotifyOnObjectAllocations

 Microsoft SDK for Java

IJavaHeapMonitor::
NotifyOnObjectAllocations

The NotifyOnObjectAllocations method of the IJavaHeapMonitor interface is called by a memory profiler to register its callback interface for receiving notification when an individual object is created (allocated on the heap). The single parameter passed in is a pointer to the IObjectAllocationCallback interface implemented by the profiler. A memory profiler can only have one callback installed at a time. To unregister the callback, this method can be called with a NULL pointer.

The Microsoft VM communicates with the profiler, notifying it when an object is allocated. The VM does so by calling the OnObjectAllocated method on the profiler's callback interface that is passed to NotifyOnObjectAllocations.

Syntax

HRESULT NotifyOnObjectAllocations(IObjectAllocationCallback *pioacb);

Parameters

[in] *pioacb A pointer to the IObjectAllocationCallback interface implemented by the profiler.

Remarks

If a memory profiler has registered a callback, the Microsoft VM will send a notification on each Java object that is allocated to a method on the profiler's IObjectAllocationCallback interface passed to this function. To stop receiving these notifications, a profiler must unregister this callback by calling a IObjectAllocationCallback method with a NULL pointer.


IJavaHeapMonitor2 : IJavaHeapMonitor

The IJavaHeapMonitor2 interface extends IJavaHeapMonitor with one method.

  // Methods
  WalkHeap


Methods

 Microsoft SDK for Java

IJavaHeapMonitor2 Interface Methods

The IJavaHeapMonitor2 interface contains the WalkHeap method, which initiates a heap dump.


IJavaHeapMonitor2::WalkHeap

 Microsoft SDK for Java

IJavaHeapMonitor2::
WalkHeap

This method of the IJavaHeapMonitor2 interface initiates a heap dump. This method may only be called from the profiler's BeginContainer callback when C_END is received. It will return E_FAIL if called from a different thread or at any other time. ObjectIDs from the previous heap dump will remain valid across the new heap dump. Unlike passive heap callbacks, C_BEGIN and C_END notifications will not be received. (They convey no useful information because the caller is initiating the dump.)

Syntax

HRESULT WalkHeap([in]IHeapInfoCallback *pihicb, [in]DWORD flags);

Parameters

[in] *pihicb | A pointer to the IHeapInfoCallback interface implemented by the profiler.
[in] flags | Mask of JVM_WALKHEAP_FLAGS.

Remarks

WalkHeap enables an event monitor to request multiple traversals of the heap within a single garbage collection. It does not replace GetHeapInfo. A profiler must already have an IHeapInfoCallback interface registered in order to use this API.

Although the behavior of WalkHeap's callback is identical to the normal passive callback mechanism, WalkHeap differs from the passive mechanism in the following ways:

  1. This API must be called from within the C_END BeginContainer method of the registered callback, on the thread that received the callback. The API will return E_FAIL under any other conditions.

  2. C_BEGIN and C_END notifications will not be received. (Normal passive heap dumps always receive C_BEGIN and C_END notifications.)

  3. The heap dump is complete when the WalkHeap API call returns. Execution will remain suspended until the calling BeginContainer method returns. (Normal passive heap dumps resume execution when the BeginContainer callback for the C_END container returns.)

  4. ObjectIDs will remain valid across multiple WalkHeap calls within the same garbage collection. (For normal passive heap dumps, all ObjectIDs are invalid when the BeginContainer callback for the C_END container returns.)

  5. Like passive heap dumping, root containers, references from root containers, and objects within the C_HEAP container may or may not be reported in the same order across multiple heap dumps. This also applies to multiple heap dumps within the same garbage collection. References from within objects will always be reported in the same order.

  6. WalkHeap does not cause garbage collection to occur, but should be considered an expensive operation, equivalent in magnitude to performing another garbage collection.

JVM_WALKHEAP_FLAGS

Constant | Value | Description
JVM_WALKHEAP_NO_ROOTS | 1 | Bypasses traversal from roots. No BeginContainer or RootReferences calls will be received. (Normal passive heap dumps always traverse roots.)


Heap Monitor Notification Profiler Interfaces Overview

Profiler Interfaces Reference

The Microsoft VM communicates with a profiler application using these interfaces to notify the profiler of each object allocation and to provide a heap dump after garbage collection.

For general information, see Using the Heap Monitor Interfaces in the Programmer's Guide.

This section contains the following:

Interfaces

Hierarchy


Heap Monitor Notification Profiler Interfaces

The heap monitor notification interfaces are as follows:

IHeapInfoCallBack notifies a profiler or heap monitoring application when garbage collection has occurred, and to provide a heap dump to the profiler.

IObjectAllocationCallBack notifies a profiler or heap monitoring application when individual objects are created (allocated).


Heap Monitor Notification Profiler Interfaces Hierarchy

The heap monitor notification profiler interfaces have the following hierarchy:

IUnknown
  |
  +--IHeapInfoCallBack
  |
  +--IObjectAllocationCallBack


IHeapInfoCallBack : IUnknown

The IHeapInfoCallback interface is used by the Microsoft virtual machine (Microsoft VM) to notify a profiler or heap monitoring application when garbage collection has occurred, and to provide a heap dump to the profiler. This object is one of two callbacks through which the Microsoft VM communicates with the profiler or heap monitor regarding heap information.

A profiler or heap monitoring application must register this interface with the Microsoft VM by calling GetHeapInfo.

The profiler or event monitoring application implements IHeapInfoCallback object. The IHeapInfoCallback object has several methods that receive information from the Microsoft VM after garbage collection as part of a heap dump of an executing Java process.

The methods implemented on this interface return S_OK on success, or E_FAIL on failure.

  // Methods
  BeginContainer
  ObjectReferences
  RootReferences


Methods (IHeapInfoCallBack Interface)

 Microsoft SDK for Java

IHeapInfoCallBack Interface Methods

The IHeapInfoCallBack interface contains the following methods.

BeginContainer is called by the Microsoft VM to notify the memory profiler when a garbage collection has occurred and to dump the heap.
ObjectReferences may be called by the Microsoft VM to notify the memory profiler of object references after a garbage collection has occurred during a heap dump.
RootReferences may be called by the Microsoft VM to notify the memory profiler of root references after a garbage collection has occurred during a heap dump.


IHeapInfoCallback::BeginContainer

 Microsoft SDK for Java

IHeapInfoCallback::
BeginContainer

The BeginContainer method of the IHeapInfoCallBack interface is called by the Microsoft VM to notify the memory profiler when a garbage collection has occurred and to dump the heap. The Microsoft VM passes in the container type and two other IDs. The interpretation of these two other IDs is dependent on the container type.

The beginning and end of a heap dump are indicated by passing in special container types (C_BEGIN and C_END).

Syntax

HRESULT BeginContainer(CONTAINER_TYPE type, UniqueID id1, UniqueID id2);

Parameters

[in] type | The type of the container (CONTAINER_TYPE).
[in] id1 | A unique value identifying the container, except for the C_BEGIN, C_END and C_HEAP container types.
[in] id2 | A UniqueID whose meaning depends on the container type.

Remarks

The heap dump process uses the concept of a container type for representing the hierarchy of memory objects on the heap.

The container types are defined as CONTAINER_TYPE enumeration constants.

CONTAINER_TYPE

Constant | Value | Description
C_BEGIN | 1 | A "dummy" container noting the start of the heap dump. UniqueID id1 and id2 are undefined. (These parameters are not used.)
C_RT_THREAD | 2 | Root containers for threads. UniqueID id1 contains the ThreadID for this thread container. UniqueID id2 is undefined. (This parameter is not used.)
C_RT_JIT | 3 | A JIT-compiled method frame. UniqueID id1 contains the StackID for this container. UniqueID id2 contains the MethodID for this container.
C_RT_NATIVE | 4 | A native Win32 method frame. UniqueID id1 contains the StackID for this container. UniqueID id2 contains the MethodID for this container.
C_RT_NATIVEGC | 5 | A native garbage collection frame. UniqueID id1 contains the StackID for this container. UniqueID id2 is undefined. (This parameter is not used.)
C_RT_COM | 6 | A COM method frame. UniqueID id1 contains the StackID for this container. UniqueID id2 contains the MethodID for this container.
C_RT_INTERPRETED | 7 | An interpreted method frame. UniqueID id1 contains the StackID for this container. UniqueID id2 contains the MethodID for this container.
C_RT_FASTINTERPRETED | 8 | A fast-interpreted method frame. UniqueID id1 contains the StackID for this container. UniqueID id2 contains the MethodID for this container.
C_RT_INTERNALFRAME | 9 | An internal VM frame. UniqueID id1 contains the StackID for this container. UniqueID id2 is undefined. (This parameter is not used.)
C_RT_INTERNALVM | 10 | An internal VM object. UniqueIDs id1 and id2 are undefined. (These parameters are not used.)
C_RT_CLASS | 11 | Static class references. UniqueID id1 contains the ClassID for this container. UniqueID id2 is undefined. (This parameter is not used.)
C_RT_ROOTTABLE | 12 | Miscellaneous root references. UniqueIDs id1 and id2 are undefined (these parameters are not used).
C_RT_STRONGPTR | 13 | A strong pointer. UniqueIDs id1 and id2 are undefined. (These parameters are not used.)
C_RT_FINALIZED | 14 | Objects awaiting finalization. UniqueIDs id1 and id2 are undefined. (These parameters are not used.)
C_HEAP | 15 | The remaining portions of the heap not reported elsewhere. UniqueIDs id1 and id2 are undefined. (These parameters are not used.)
C_END | 16 | A dummy container noting the end of the heap dump. UniqueIDs id1 and id2 are undefined. (These parameters are not used.)

Execution of the Java process is suspended during the entire process of a heap dump after garbage collection has occurred. The profiler receives notification of the beginning of a heap dump when it receives a call to BeginContainer with a container type of C_BEGIN.

The profiler will then get a BeginContainer method call followed by zero (0) or more RootReferences and ObjectReferences method calls. This process will repeat any number of times (hundreds or thousands of times, for example) until the profiler receives a BeginContainer notification with a container type of C_END, signifying the end of the heap dump. When this last BeginContainer call returns from the profiler, execution of the Java process resumes.

The various container types will be heap dumped to the profiler in any order, with two exceptions: The container type C_RT_THREAD will always be dumped before any of the associated thread's stack frame roots. The container type C_HEAP will always be dumped last. Multiple BeginContainer calls may be received for the same container, with any number of intervening BeginContainer calls for different ids. That is, the same value of id1 is passed to both BeginContainer calls, and the calls may or may not be successive.

The RootReferences method reports root memory references from the current container. The heap container (container type C_HEAP) is a special container that won't generate any RootReferences method calls. The ObjectReferences method reports an object and the object's memory references. When calling the ObjectReferences method, each memory reference will be traversed depth-first.

The profiler can return E_FAIL to abort the heap dump. The profiler will receive no further callbacks during this garbage collection, with the one exception of a C_END container notification. A C_END notification will always be sent, even if the heap dump is aborted. After the C_END notification is sent, execution resumes.

If S_POSTPONE_REFERENCES is returned from the ObjectReferences method, the heap dump will not descend references from the current object, but will report these memory references either from other as-yet unvisited objects or in the heap container (C_HEAP container type). A profiler can obtain a flat list of objects by always returning this value from the ObjectReferences method.

If S_OK is returned, the heap dump will proceed normally.


IHeapInfoCallback::ObjectReferences

 Microsoft SDK for Java

IHeapInfoCallback::
ObjectReferences

The ObjectReferences method of the IHeapInfoCallBack interface is called by the Microsoft VM to notify the memory profiler of object references after a garbage collection has occurred during a heap dump. The Microsoft VM passes in the ObjectID for the object, a bitmask of JVM_OBJECT_FLAGS for the object, an array of other references (ObjectIDs) within this object, the number of object references being reported, and a bitmask of JVM_OBJECT_FLAGS for each other reference.

Syntax

HRESULT ObjectReferences(ObjectID object_id, DWORD flags, const ObjectID *prefs, unsigned nrefs, const DWORD *pflags);

Parameters

[in] object_id | The ObjectID that is being reported.
[in] flags | The JVM_OBJECT_FLAGS for this object.
[in] *prefs | A pointer to an array of ObjectID references within this object.
[in] nrefs | The number of ObjectID references within this object.
[in] *pflags | A pointer to a parallel array of JVM_OBJECT_FLAGS, one flag for each ObjectID reference within this object.

Remarks

The heap dump process associates an object flag with each object (ObjectID). The JVM_OBJECT_FLAGS can be a combination of the first three enumeration constants or the predefined combination listed as the last enumeration constant.

JVM_OBJECT_FLAGS

Constant | Value | Description
JVM_OBJ_ALREADY_REPORTED | 0x00001 | The Java object has already been reported as a reference.
JVM_OBJ_ALREADY_VISITED | 0x00002 | The Java object has already been visited and will not be traversed.
JVM_OBJ_MORE_REFERENCES | 0x10000 | Additional references from the same Java object will be reported in subsequent calls.
ALL_JVM_OBJECT_FLAGS | 0x10003 | A combination of the previous enumeration constants (JVM_OBJ_ALREADY_REPORTED, JVM_OBJ_ALREADY_VISITED, and JVM_OBJ_MORE_REFERENCES).

Each reference corresponds to a field in the same order obtained from the GetClassFields method, so null object references are reported. Note that only fields with the JVM_FIELD_OBJECTREF access modifier and without the JVM_FIELD_STATIC access modifier are relevant. For some objects (java.lang.String objects, for example), the number of references reported might not match the number of fields (JVM_CLS_VARIABLE_SIZE is set for the class properties).

The ObjectReferences method reports an object and the object's memory references. When calling the ObjectReferences method, each memory reference will be traversed depth-first. A parallel array indicates objects that have been seen before will not be traversed. There are two possible object flags from the JVM_OBJECT_FLAGS enumeration that might be reported for these objects by the VM: JVM_OBJ_ALREADY_REPORTED or JVM_OBJ_ALREADY_VISITED. If the VM passes the JVM_OBJ_ALREADY_REPORTED flag in the object flags of an ObjectID, the VM has already reported the existence of this memory object during the heap dump. This process identifies recursive structures and objects with multiple references to the same objects.

For example, a stack frame might have two local variables pointing to the same object. JVM_OBJ_ALREADY_REPORTED will be set for the reference for the second variable. If the JVM_OBJ_ALREADY_VISITED flag is set for a reference, an ObjectReferences call has already been made for the references object and another call will not be made. If an object has a reference to itself, the reference will be reported as visited.

All references in an object will be reported before descending. If all references cannot be reported in a single call, the JVM_OBJ_MORE_REFERENCES flag will be set for the object flag. If this flag is clear, no further ObjectReferences calls will be received for that object.

The profiler can return E_FAIL to abort the heap dump. The profiler will receive no further callbacks during this garbage collection, with the one exception of a C_END container notification. A C_END notification will always be sent, even if the heap dump is aborted. After the C_END notification is sent, execution resumes.

The profiler might return S_POSTPONE_REFERENCES from the last ObjectReferences call for an object to indicate that the references from this object should not be descended. Note that these referenced objects that have been skipped might still be reported and visited through references from different objects. Any objects that were not visited during root traversal are reported later within the heap container type (C_HEAP).

If S_POSTPONE_REFERENCES is returned from the ObjectReferences method, the heap dump will not descend references from the current object, but will report these memory references, either from other as-yet unvisited objects or in the heap container (C_HEAP container type). A profiler can obtain a flat list of objects by always returning this value from ObjectReferences.

If S_OK is returned, the heap dump will proceed normally.


IHeapInfoCallback::RootReferences

 Microsoft SDK for Java

IHeapInfoCallback::
RootReferences

The RootReferences method of the IHeapInfoCallBack interface is called by the Microsoft VM to notify the memory profiler of root references after a garbage collection has occurred during a heap dump. The Microsoft VM passes in an array of references within this root, the number of root references being reported, and a bitmask of JVM_OBJECT_FLAGS for each reference.

The RootReferences method reports root memory references from the current container. The heap container (container type C_HEAP) is a special container that won't generate any RootReferences method calls.

Syntax

HRESULT RootReferences(const ObjectID *prefs, unsigned nrefs, const DWORD *pflags);

Parameters

[in] *prefs | A pointer to an array of ObjectID references in this root.
[in] nrefs | The number of references in this root.
[in] *pflags | A pointer to a parallel array of JVM_OBJECT_FLAGS, one flag for each ObjectID reference in this root.

Remarks

The heap dumping process associates an object flag with each object (ObjectID). The JVM_OBJECT_FLAGS can be a combination of the first three enumeration constants or the predefined combination listed as the last enumeration constant.

JVM_OBJECT_FLAGS

Constant | Value | Description
JVM_OBJ_ALREADY_REPORTED | 0x00001 | The Java object has already been reported as a reference.
JVM_OBJ_ALREADY_VISITED | 0x00002 | The Java object has already been visited and will not be traversed.
JVM_OBJ_MORE_REFERENCES | 0x10000 | Additional references from the same Java object will be reported in subsequent calls.
ALL_JVM_OBJECT_FLAGS | 0x10003 | A combination of the previous enumeration constants (JVM_OBJ_ALREADY_REPORTED, JVM_OBJ_ALREADY_VISITED, and JVM_OBJ_MORE_REFERENCES).

Each reference corresponds to a field in the same order obtained from the GetClassFields method, so null object references are reported. Note that only fields with the JVM_FIELD_OBJECTREF access modifier and without the JVM_FIELD_STATIC access modifier are relevant. For some objects (java.lang.String objects, for example), the number of references reported might not match the number of fields (JVM_CLS_VARIABLE_SIZE is set for the class properties).

The profiler can return E_FAIL to abort the heap dump. The profiler will receive no further callbacks during this garbage collection, with the one exception of a C_END container notification. A C_END notification will always be sent, even if the heap dump is aborted. After the C_END notification is sent, execution resumes.

If S_OK is returned from this method, the heap dump will proceed normally.


IObjectAllocationCallBack : IUnknown

The IObjectAllocationCallback interface is used by the Microsoft VM to notify a profiler or heap monitoring application when individual objects are created (allocated). This object is one of two callbacks through which the Microsoft VM communicates with the profiler or heap monitor regarding heap information.

A profiler or heap monitoring application must register this interface with the Microsoft VM by calling NotifyOnObjectAllocations.

The profiler or event monitoring application implements IObjectAllocationCallback object. The IObjectAllocationCallback object has several a single method that receives information from the Microsoft VM when an individual object is created (allocated on the heap) in an executing Java process.

The single method implemented on this interface returns S_OK on success, or E_FAIL on failure.

  // Methods
  OnObjectAllocated


Methods (IObjectAllocationCallback Interface)

 Microsoft SDK for Java

IObjectAllocationCallback Interface Methods

The IObjectAllocationCallback interface contains the following method.

OnObjectAllocated is called by the Microsoft VM to notify the memory profiler when an individual object is created (allocated on the heap).


IObjectAllocationCallback::OnObjectAllocated

 Microsoft SDK for Java

IObjectAllocationCallback::
OnObjectAllocated

The OnObjectAllocated method of the IObjectAllocationCallback interface is called by the Microsoft VM to notify the memory profiler when an individual object is created (allocated on the heap). These objects can be either an instance of a class or an array. The Microsoft VM passes in the ObjectID and the ClassID of the object. The ClassID is the class type of the newly created instance.

This method should return S_OK.

Syntax

HRESULT OnObjectAllocated(ObjectID object_id, ClassID class_id);

Parameters

[in] object_id | The ObjectID of the object created.
[in] class_id | A ClassID of the object being created.

Remarks

The profiler can call the ClassInformation method implemented by the Microsoft VM to retrieve class information about this object. In particular, if the class name begins with a left bracket ([), this object is an array object.


Raw Native Interface Reference

This reference describes the functions and structures defined in the native.h and nativcom.h header files (unless noted, the prototype is found in native.h). These functions are used by the Raw Native Interface (RNI) defined by the Microsoft virtual machine (Microsoft VM) for efficiently interfacing Java code with native code.

To learn how to use the API, see Using the Raw Native Interface.


Raw Native Interface Functions

The following functions are defined in native.h and nativcom.h.

AddModuleResourceClassSource | Notifies the virtual machine of a Microsoft® Win32® resource containing class files.
AddPathClassSource | Adds a path to Microsoft virtual machine's internal class path.
ArrayAlloc | Creates an array of primitive type objects.
ArrayCopy | Copies an array using the Java System.ArrayCopy method.
c2jhook_getexposingclass | Returns the class defining the interface method (Nativcom.h).
c2jhook_getsizeofuserdata | Gets size of the user data in the MCCustomMethod descriptor (Nativcom.h).
c2jhook_getuserdata | Gets writable pointer to the user data in the MCCustomMethod descriptor (Nativcom.h).
Class_CopyConstantPoolItem | Copies a constant pool item.
Class_GetAttributes | Returns a combination of the ACC_XXX flags for a class as they appear in the Java class file.
Class_GetConstantPoolCount | Gets a constant pool count.
Class_GetField | Returns a handle to a field explicitly specified by name.
Class_GetFieldByIndex | Returns a handle to a field specified by index.
Class_GetFieldCount | Retrieves the total number of fields in the class, including super and static fields.
Class_GetInterface | Retrieves an interface specified by index.
Class_GetInterfaceCount | Retrieves the total number of interfaces that are implemented by the class.
Class_GetMethod | Returns a handle to a method explicitly specified by name.
Class_GetMethodByIndex | Returns a handle to a method specified by index.
Class_GetMethodCount | Retrieves the total number of methods in the class, including super and static methods.
Class_GetName | Retrieves the class name.
Class_GetSuperS | Retrieves the superclass name.
ClassArrayAlloc | Creates an array of objects given the class signature.
ClassArrayAlloc2 | Creates an array of objects given the class address; added as of versions 2925 through 3167 of the Microsoft virtual machine.
ClassClassToClassObject | Returns a java.lang.Class object from a ClassClass pointer.
ClassObjectToClassClass | Returns a ClassClass pointer from a java.lang.Class object.
convert_IUnknown_to_Java_Object | Returns a Java callable wrapper that can be used to access the specified interface pointer (Nativcom.h).
convert_IUnknown_to_Java_Object2 | Returns a Java callable wrapper that can be used to access the specified interface pointer (Nativcom.h).
convert_Java_Object_to_Iunknown | Returns an interface pointer usable from the current COM context (Nativcom.h).
convert_ptr_to_jcdw | Returns a data wrapper object of the supplied Class type that points at the supplied data pointer (Nativcom.h).
do_execute_java_method | Calls a Java method or constructor.
do_execute_java_method64 | Calls a Java method or constructor and returns a 64-bit integer.
do_execute_java_methodV | Calls a Java method or constructor using a va_list as a parameter instead of ellipses.
exceptionClear | Clears any pending exceptions.
exceptionDescribe | Invokes printStackTrace on the pending exception.
exceptionOccurred | Determines if an exception has occurred in the called Java method without exiting the native code.
exceptionSet | Sets a pending exception.
execute_java_constructor | Allocates a new Java object and invokes a constructor.
execute_java_constructor_method | Invokes a Java constructor method.
execute_java_constructor_methodV | Calls a Java constructor method using a va_list as a parameter instead of ellipses.
execute_java_constructorV | Allocates a new Java object and invokes a constructor. This method accepts a va_list argument list as a parameter instead of ellipses.
execute_java_dynamic_method | Invokes a Java dynamic method.
execute_java_dynamic_method64 | Invokes a Java dynamic method and returns a 64-bit integer.
execute_java_dynamic_methodV | Invokes a Java dynamic method using a va_list as a parameter instead of ellipses.
execute_java_interface_method | Invokes a Java interface method.
execute_java_interface_method64 | Invokes a Java interface method and returns a 64-bit integer.
execute_java_interface_methodV | Invokes a Java interface method using a va_list as a parameter instead of ellipses.
execute_java_static_method | Invokes a Java static method.
execute_java_static_method64 | Invokes a Java static method and returns a 64-bit integer.
execute_java_static_methodV | Invokes a Java static method using a va_list as a parameter instead of ellipses.
field_GetOffset | Returns the offset of dynamic fields in the class.
Field_GetStaticPtr | Returns a pointer to the static data.
field_GetXXX | Retrieves the value of the specified field.
field_SetXXX | Sets the value of the specified field.
findClass | Retrieves a class object pointer for a named class.
findClassEx | Retrieves a class object pointer according to specified flags.
FindClassFromClass | Similar to findClassEx, but adds a parameter for ClassLoader lookups; added as of versions 2925 through 3167 of the Microsoft virtual machine.
GCDisable | Increments the block count and disables garbage collection.
GCDisableCount | Returns the current GCDisable count
GCDisableMultiple | Increments the block count a specified number of times.
GCEnable | Decrements the block count and enables garbage collection by the Microsoft VM.
GCEnableCompletely | Decrements the block count to 0 (zero) and enables garbage collection by the virtual machine.
GCFramePop | Restores the GCFrame with current values for members of the structure.
GCFramePush | Informs the Microsoft VM garbage collector of a GCFrame to track.
GCFreeHandle | Frees a strong pointer originally obtained using GCNewHandle.
GCFreePtr | Frees a pointer originally allocated using GCGetPtr.
GCGetPtr | Allocates a weak pointer for an object and updates it when garbage collection occurs.
GCNewHandle | Creates a strong pointer to an object.
GCSetObjectReferenceForHandle | Garbage collection-safe method for updating contents of a handle.
GCSetObjectReferenceForObject | Garbage collection-safe method for updating the fields in an object.
get_methodblock | Retrieves a pointer to a method block structure containing the class name, method name, and parameter and return types of a method.
GetCurrentJavaTimeMillis | Returns the same result as defined by java.lang.System.currentTimeMillis.
GetNativeMethodCallersClass | Determines the class type of the caller.
GetNativeMethodCallersMethodInfo | Gets information about the caller's method.
GetNativeMethodsClass | Retrieves information about a native method's class; added as of versions 2925 through 3167 of the Microsoft virtual machine.
GetNativeMethodsMethodInfo | Retrieves information about a native method added as of versions 2925 through 3167 of the Microsoft virtual machine.
getPendingException | Retrieves a pending exception.
HresultFromException | Creates an HRESULT return type from a Java exception object.
ImplementsInterface | Determines if a class type implements the interface represented by the second class type.
is_instance_of | Determines if an object is an instance of a specified class type.
is_subclass_of | Determines if a class is a subclass of the second specified class type.
isInstanceOf | Determines if a specified Java object is an instance of a particular class.
j2chook_getmethodblock | Returns the method block of the target method (Nativcom.h).
j2chook_getsizeofuserdata | Gets the size of the user data in the MCCustomMethod descriptor (Nativcom.h).
j2chook_getuserdata | Gets writable pointer to the user data in the MCCustomMethod descriptor (Nativcom.h).
j2chook_getvtblindex | Gets the vtable index of the target method (Nativcom.h).
JavaString2Cstring | Copies the characters of the String object into a C string buffer.
javaStringLength | Retrieves the length of the Java String object.
javaStringLengthAsCString | Retrieves the length of the Java String object as a C string.
javaStringStart | Returns a temporary pointer to the first character of the Java String object.
jcdw_java_owned | Returns true if the Microsoft VM frees the non—garbage-collected heap memory that this data wrapper contains when the data wrapper is garbage collected (Nativcom.h).
jcdw_memory_freed_on_gc | Returns true if the virtual machine allocated the non—garbage-collected heap memory contained in the data wrapper (Nativcom.h).
jcdwClassOffsetOf | Returns the byte offset within the non—garbage-collected heap memory to the specified field name from the supplied java.lang.Class object (Nativcom.h).
jcdwClassSizeOf | Returns the size of the non-garbage-collected heap memory used by instances of the supplied java.lang.Class object (Nativcom.h).
jcdwGetData | Returns the data pointer to the non—garbage-collected heap memory contained in the data wrapper object (Nativcom.h).
jcdwNewData | Replaces the data pointer contained in the data wrapper with a new quantity of heap memory that is not garbage-collected (Nativcom.h).
jcdwOffsetOf | Returns the byte offset within the non-garbage-collected heap memory to the specified field name (Nativcom.h).
jcdwPropagateToJava | Propagates field values from the object's associated native memory to the Java object.
jcdwPropagateToNative | Propagates field values from the Java object to the object's associated native memory.
jcdwSetData | Replaces the data pointer that this data wrapper represents with the specified data pointer (Nativcom.h).
jcdwSizeOf | Returns the size of the non—garbage-collected heap memory contained in the data wrapper object (Nativcom.h).
jio_snprintf | Prints to a string with a buffer limit.
jio_vsnprintf | Prints to a string with a buffer limit using a va_list macro for arguments.
MakeByteString | Create and return a new array of bytes initialized from the C string.
makeJavaString | Returns a string formatted as a Java String object.
MakeJavaStringFromUtf8 | Creates a new Java String object, initialized from a null-terminated, UTF8-formatted, C string.
MakeJavaStringW | Constructs a Java string from a Unicode C string.
MarshalCallToJavaObjectHostThread | Thread marshaling helper that re-executes the RNI method on the apartment thread for the supplied thread ID for the supplied Java object (Nativcom.h).
MarshalCallToJavaThreadId | Thread marshaling helper that re-executes the RNI method on the supplied thread ID for the supplied Java object (Nativcom.h).
Member_GetAttributes | Returns a combination of the ACC_XXX flags for a field or method, as they appear in the Java class file.
Member_GetClass | Retrieves the name of the class that the field or method is implemented in.
Member_GetName | Retrieves the member name.
Member_GetSignature | Retrieves the signature of the field or method.
MonitorEnter | Enters a synchronization object.
MonitorExit | Exits a synchronization object.
MonitorNotify | Wakes up a single thread that is waiting on this object's monitor.
MonitorNotifyAll | Wakes up all threads that are waiting on this object's monitor.
MonitorWait | Waits to be notified by another thread of a change in this object.
Object_GetClass | Retrieves the class that the object points to.
PrepareThreadForJava | Thread entry function for calls into the Microsoft VM.
PrepareThreadForJavaEx | Extended thread entry function for calls into the Microsoft VM.
RNIGetCompatibleVersion | Exported by the DLL to allow the Microsoft VM to check compatibility.
SignalError | Creates a Java exception object, which is thrown when it returns from the native code.
SignalErrorHResult | Creates a Java exception object from an HRESULT return type.
SignalErrorPrintf | Creates a Java exception object and specifies format string for exception description to be printed when thrown.
Thread_IsInterrupted | Checks to see if the current thread is interrupted and optionally resets the interrupt flag.
UnprepareThreadForJava | Thread exit function for calls into the Microsoft VM.


AddModuleResourceClassSource

Notifies the Microsoft VM of a Microsoft® Win32® resource containing class files. This resource must be in the format created by jexegen. When classes are being loaded, the resource is searched for classes as if it were a directory on the class path.

Syntax

__cdecl AddModuleResourceClassSource(HMODULE hMod, DWORD dwResID);

Parameters

hMod | The module handle.
dwResID | The resource ID.

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


AddPathClassSource

Adds a path to the Microsoft VM's internal class path.

Syntax

BOOL __cdecl AddPathClassSource(const char *path, BOOL fAppend);

Parameters

*path | The pointer to the path that is to be appended or prepended.
fAppend | If true, a path is appended to the class path. If false, a path is prepended to the class path.

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


ArrayAlloc

Creates an array of primitive types.

Syntax

HObject* __cdecl ArrayAlloc(int type, int cItems);

Return Value

Returns an allocated array.

Parameters

type | Primitive data type as defined in Native.h. The following types are supported: T_BOOLEAN is a Boolean. T_BYTE is a Byte. T_CHAR is a Character. T_DOUBLE is a Double. T_FLOAT is a Float. T_INT is an Integer. T_LONG is a Long. T_SHORT is a Short.
cItems | The number of items in the array.


ArrayCopy

Copies an array using the Java System.ArrayCopy method.

Syntax

void __cdecl ArrayCopy(HObject *srch, long src_pos, HObject *dsth, long dst_pos, long length);

Parameters

*srch | The source object.
src_pos | The starting position in the source object array to copy.
*dsth | The destination object.
dst_pos | The position in the destination object array to copy to.
length | The number of objects in the array to copy.


c2jhook_getexposingclass

Returns the class defining the interface method. This is the class containing the MCCustomMethod descriptor.

Syntax

ClassClass * __cdecl c2jhook_getexposingclass(C2JMethodHookInfo *phookinfo);

Parameters

*phookinfo The pointer to the class that contains the MCCustomMethod descriptor.


c2jhook_getsizeofuserdata

Gets size of user data in the MCCustomMethod descriptor.

Syntax

WORD __cdecl c2jhook_getsizeofuserdata(C2JMethodHookInfo *phookinfo);

Parameters

*phookinfo The pointer to the class that contains the MCCustomMethod descriptor.


c2jhook_getuserdata

Gets the writable pointer to the user data in the MCCustomMethod descriptor.

Syntax

LPVOID __cdecl c2jhook_getuserdata(C2JMethodHookInfo *phookinfo);

Parameters

*phookinfo The pointer to the class that contains the MCCustomMethod descriptor.


Class_CopyConstantPoolItem

Copies a constant pool item. For Utf8 items, the buffer size is not the number of characters, and the copied string will be null-terminated; size includes the null-terminator. For ClassRef, FieldRef, and so on, the buffer is filled in with a struct ptr.

Syntax

int __cdecl Class_CopyConstantPoolItem(ClassClass *cls, unsigned index, BYTE *pbuf, int size, DWORD flags, BYTE *ptype);

Parameters

*cls | The address of the class object.
index | The index value of the field in the class. The index must be between 0 (zero) and the field count (returned from Class_GetConstantPoolCount) minus 1, inclusive.
*pbuf | The address of the buffer.
size | The size of pbuf in bytes. May be NULL to obtain only the size/type.
ptype | The type of the pool item. Returns the number of bytes copied or needed, or -1 if failed. Filled in on output with the type of the item.
flags | A bitmask. The only flag currently defined is COPYCPITEM_RESOLVE_REFERENCES. If the constant pool item has not yet been used, this flag forces its referent to be loaded or looked up. With this flag set, the method may cause garbage collection.

CP Type | Buffer Contents
CP_Utf8 | Null-terminated string.
CP_Unicode | (error)
CP_Integer | long
CP_Float | float
CP_Long | __int64
CP_Double | double
CP_Class | ClassClass*
CP_String | HObject*
CP_FieldRef | fieldblock*
CP_MethodRef | methodblock*
CP_IntfMethod | methodblock*
CP_NameAndType | (error)

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


Class_GetAttributes

Retrieves a combination of the ACC_XXX flags for a class as they appear in the Java class file.

Syntax

int __cdecl Class_GetAttributes(ClassClass *cls);

Return Value

Returns attributes flags.

Parameters

*cls The address of the class object.

Remarks

The following attributes are defined for use in a Java class file and can be retrieved using this function as shown in the following table.

Flag | Value
ACC_PUBLIC | 0x0001
ACC_PRIVATE | 0x0002
ACC_PROTECTED | 0x0004
ACC_STATIC | 0x0008
ACC_FINAL | 0x0010
ACC_SYNCH | 0x0020
ACC_SUPER | 0x0020
ACC_THREADSAFE | 0x0040
ACC_VOLATILE | 0x0040
ACC_TRANSIENT | 0x0080
ACC_NATIVE | 0x0100
ACC_INTERFACE | 0x0200
ACC_ABSTRACT | 0x0400


Class_GetConstantPoolCount

Gets the constant pool count.

Syntax

unsigned __cdecl Class_GetConstantPoolCount(ClassClass *cls);

Parameters

*cls The address of the class object.

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


Class_GetField

Retrieves a handle to a field explicitly specified by name. This handle is needed to get any further information about the field.

Syntax

struct fieldblock * __cdecl Class_GetField(ClassClass *cls, const char *name);

Return Value

Returns a pointer to the field block.

Parameters

*cls | The address of the class object. Use FindClass to determine this.
*name | The name of the field in the class.


Class_GetFieldByIndex

Retrieves a handle to a field specified by index.

Syntax

struct fieldblock * __cdecl Class_GetFieldByIndex(ClassClass *cls, unsigned index);

Return Value

Returns a field block pointer.

Parameters

*cls | The address of the class object. Use FindClass to determine the class.
index | The index value of the field in the class. The index must be between 0 (zero) and the field count (returned from Class_GetFieldCount) minus 1, inclusive.


Class_GetFieldCount

Retrieves the total number of fields in the class, including super and static fields.

Syntax

unsigned __cdecl Class_GetFieldCount(ClassClass *cls);

Return Value

Returns the number of fields.

Parameters

*cls The address of the class object. Use FindClass to determine the class.

Remarks

This function is intended to be used with Class_GetFieldByIndex to enumerate fields on a class.


Class_GetInterface

Retrieves an interface specified by index.

Syntax

ClassClass* __cdecl Class_GetInterface(ClassClass *cls, unsigned index);

Return Value

Returns a pointer to a class interface object.

Parameters

*cls | The address of the class object. Use FindClass to determine the class.
index | The index value of the interface in the class. The index must be between 0 and the interface count (returned from Class_GetInterfaceCount) minus 1, inclusive.


Class_GetInterfaceCount

Retrieves the total number of interfaces implemented by the class.

Syntax

unsigned __cdecl Class_GetInterfaceCount(ClassClass *cls);

Return Value

Returns the number of interfaces.

Parameters

*cls The address of the class object. Use FindClass to determine the class.


Class_GetMethod

Retrieves a handle to a method explicitly specified by name. This handle is needed to get any further information about the method.

Syntax

struct methodblock* __cdecl Class_GetMethod(ClassClass *cls, const char *name, const char *signature);

Return Value

Returns a handle to a method in the given class specified by name and signature.

Parameters

cls | The address of the class object. Use FindClass to determine the class.
*name | The name of the method in the class.
*signature | The types of parameters passed to the constructor.


Class_GetMethodByIndex

Retrieves a handle to a method specified by index.

Syntax

struct methodblock* __cdecl Class_GetMethodByIndex(ClassClass* cls, unsigned index);

Return Value

Returns a method block pointer.

Parameters

cls | The address of the class object. Use FindClass to determine.
index | The index value of the method in the class. The index must be between 0 (zero) and the method count (returned from Class_GetMethodCount) minus 1, inclusive.


Class_GetMethodCount

Retrieves the total number of methods in the class, including non-static super methods.

Syntax

unsigned __cdecl Class_GetMethodCount(ClassClass *cls);

Return Value

Returns the number of methods.

Parameters

*cls The address of the class object. Use FindClass to determine.

Remarks

This function is intended for use with Class_GetMethodByIndex to enumerate methods in a class.

This function returns the total count of all members, not just the count of those declared in the class specified. To find declared members, you must enumerate methods and call Member_GetClass on each to determine where the method is implemented.


Class_GetName

Retrieves the class name.

Syntax

const char * __cdecl Class_GetName(ClassClass *cls);

Return Value

Returns the class name.

Parameters

*cls The address of the class object.


Class_GetSuper

Retrieves the superclass.

Syntax

ClassClass* __cdecl Class_GetSuper(ClassClass *cls);

Return Value

Returns the superclass.

Parameters

*cls The address of the class object.


ClassArrayAlloc

Creates an array of objects given the class signature.

Syntax

HObject* __cdecl ClassArrayAlloc(int type, int cItems, char *szSig);

Return Value

Returns an allocated object array.

Parameters

type | Set this parameter to T_CLASS. Otherwise, the function will behave like ArrayAlloc and return an array of primitives. The exact type depends on whether this parameter is set to T_BOOLEAN, T_BYTE, T_CHAR, T_DOUBLE, T_FLOAT, T_INT, T_LONG, or T_SHORT.
cItems | The number of elements in the array to allocate.
*szSig | The signature of the class if type is T_CLASS. (For example, java/awt/Rectangle.)


ClassArrayAlloc2

Creates an array of objects given the class address.

Syntax

HObject* __cdecl ClassArrayAlloc2(int type, int cItems, ClassClass *cb);

Return Value

Returns an allocated object array.

Parameters

type | Set this parameter to T_CLASS. Otherwise, the function will behave like ArrayAlloc and return an array of primitives. The exact type depends on whether this parameter is set to T_BOOLEAN, T_BYTE, T_CHAR, T_DOUBLE, T_FLOAT, T_INT, T_LONG, or T_SHORT.
cItems | The number of elements in the array to allocate.
*cb | The address of the class object. If the address is not known, use the function ClassArrayAlloc instead. If the type is T_CLASS, cb must be valid.

Remarks

This function was added as of versions 2925 through 3167 of the Microsoft virtual machine.


ClassClassToClassObject

Retrieves a java.lang.Class object for a ClassClass.

Note This method can cause a garbage collection to occur; guard any objects that you want to use after calling this method.

Syntax

HObject* __cdecl ClassClassToClassObject(ClassClass *cls);

Return Value

Returns a java.lang.Class object.

Parameters

*cls The address of the class object.

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


ClassObjectToClassClass

Retrieves a ClassClass pointer from a java.lang.Class object.

Note This method can cause a garbage collection to occur; guard any objects that you want to use after calling this method.

Syntax

ClassClass* __cdecl ClassObjectToClassClass(HObject *object);

Return Value

Returns a ClassClass pointer.

Parameters

*object A java.lang.Class object.

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


convert_IUnknown_to_Java_Object

Returns a Java callable wrapper that can be used to access the specified interface pointer. The Microsoft VM will keep a reference to this interface pointer.

Syntax

Hjava_lang_Object *__cdecl convert_IUnknown_to_Java_Object(IUnknown *punk, Hjava_lang_Object *phJavaClass, int fAssumeThreadSafe);

Parameters

*punk | The address of the IUnknown interface.
*phJavaClass | The reference to the Java class.
fAssumeThreadSafe | The flag which, if false, causes the Microsoft VM to auto-marshal all COM calls to the current COM context.


convert_IUnknown_to_Java_Object2

Returns a Java callable wrapper that can be used to access the specified interface pointer. The Microsoft VM will keep a reference to this interface pointer. If fFreeThreaded is false, the Microsoft VM auto-marshals all COM calls to the current COM context.

Syntax

Hjava_lang_Object *__cdecl convert_IUnknown_to_Java_Object2(IUnknown *punk, ClassClass *pClassClass, int fFreeThreaded);

Parameters

*punk | The address of the IUnknown interface.
*pClassClass | The reference to the specified class.
fFreeThreaded | The flag which, if false, causes the Microsoft VM to auto-marshal all COM calls to the current COM context.


convert_Java_Object_to_IUnknown

Returns a usable interface pointer from the current COM context.

Syntax

IUnknown *__cdecl convert_Java_Object_to_IUnknown(Hjava_lang_Object *phJavaObject, const IID *pIID);

Parameters

*phJavaObject | The address of the Java object.
*pIID | The address of the interface identifier.


convert_ptr_to_jcdw

Returns a data wrapper object of the supplied class type that points at the supplied data pointer. The memory is not owned by the Microsoft VM.

Syntax

Hjava_lang_Object *__cdecl convert_ptr_to_jcdw(void *pExtData, Hjava_lang_Object *phJavaClass);

Parameters

*pExtData | The address of the external data.
*phJavaClass | The address of the Java class.


do_execute_java_method64

Calls a Java method or constructor and returns a 64-bit integer.

Syntax

int64_t __cdecl do_execute_java_method64(ExecEnv *ee, void *obj, const char *method_name, const char *signature, struct methodblock *mb, bool_t isStaticCall, ...);

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. This parameter should be set to NULL.
*obj | The object pointer.
*method_name | The name of the method to invoke. Set to NULL if using a method block.
*signature | The types of parameters passed to the constructor. See execute_java_dynamic_method for a description of signature characters. Pass NULL if using a method block.
*mb | The address of the cached method block data structure. Use get_methodblock to retrieve this. The underlying structure of the method block is not defined; it is used only to prevent accidental type misuse using the alternative, PVOID.
isStaticCall | True if calling a static method, or false otherwise.

Remarks

get_methodblock is a helper function for this function. It can be used when making repeated calls to a method to avoid the overhead of name lookup on each call. Note that invoking a Java method can cause garbage collections.


do_execute_java_methodv

Calls a Java method or constructor and returns a 64-bit integer.

Syntax

int64_t __cdecl do_execute_java_methodv(ExecEnv *ee, void *obj, const char *method_name, const char *signature, struct methodblock *mb, bool_t isStaticCall, va_list args);

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. This parameter should be set to NULL.
*obj | The object pointer.
*method_name | The name of the method to invoke. Set to NULL if using a method block.
*signature | The types of parameters passed to the constructor. See execute_java_dynamic_method for a description of signature characters. Pass NULL if using a method block.
*mb | The address of the cached method block data structure. Use get_methodblock to retrieve this. The underlying structure of the method block is not defined; it is used only to prevent accidental type misuse using the alternative, PVOID.
isStaticCall | True if calling a static method, or false otherwise.
args | The va_list used instead of ellipses.

Remarks

get_methodblock is a helper function for this function. It can be used when making repeated calls to a method to avoid the overhead of name lookup on each call. Note that invoking a Java method can cause garbage collections.

do_execute_java_methodV was added as of versions 2437 through 2925 of the Microsoft virtual machine.


do_execute_java_method

Calls a Java method.

Syntax

long __cdecl do_execute_java_method(ExecEnv *ee, void *obj, char *method_name, char *signature, struct methodblock *mb, bool_t isStaticCall);

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. This parameter should be set to NULL.
*obj | The object pointer.
*method_name | The name of the method to invoke. Set to NULL if using a method block.
*signature | The types of parameters passed to the constructor. See execute_java_dynamic_method for a description of signature characters. Pass NULL if using a method block.
*mb | The address of the cached method block data structure. Use get_methodblock to retrieve this. The underlying structure of the method block is not defined; it is used only to prevent accidental type misuse using the alternative, PVOID.
isStaticCall | True if calling a static method; otherwise, is false.

Remarks

get_methodblock is a helper function for this function. It can be used when making repeated calls to a method to avoid the overhead of name lookup on each call. Note that invoking a Java method can cause garbage collections.

The following example demonstrates calling this function for repeated access to the Rectangle.move method.

struct {
    Hjava_awt_Rectangle *phRectangle;
} gc;

struct methodblock *pmb = get_methodblock(gc.phRectangle, "move", "(II)V");

for (i=0; i < 10; i++)
{
  do_execute_java_method(NULL, gc.phRectangle, NULL, NULL, pmb, FALSE, x, y);
}


exceptionClear

Clears any pending exceptions.

Syntax

void __cdecl exceptionClear(ExecEnv *ee);

Parameters

*ee The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.


exceptionDescribe

Invokes printStackTrace on the pending exception.

Syntax

void __cdecl exceptionDescribe(ExecEnv *ee);

Parameters

*ee The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.


exceptionOccurred

Determines if an exception has occurred in the called Java method without exiting the native code.

Syntax

bool_t __cdecl exceptionOccurred(ExecEnv *ee);

Return Value

Returns TRUE if an exception occurred; otherwise , returns FALSE.

Parameters

*ee The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.


exceptionSet

Sets the pending exception. Calling exceptionSet(ee, NULL) produces the same result as calling exceptionClear(ee).

Syntax

void exceptionSet(ExecEnv *ee, HObject *phThrowable);

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.
*phThrowable | A pointer to the exception to set.


execute_java_constructor

Allocates a new Java object and invokes a constructor.

Syntax

HObject* __cdecl execute_java_constructor(ExecEnv *ee, char *classname, ClassClass *cb, char *signature);

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. This parameter should be set to NULL.
*classname | The name of the class if cb is NULL. Use forward slashes (/) instead of dots (.) as package delimiters. (For example, java/lang/System.)
*cb | The address of the class object. Use NULL and provide classname if the address is not known.
*signature | The types of parameters passed to the constructor. See execute_java_dynamic_method for a description of signature characters. V is the return type for all constructors. V is automatically appended and should not be specified.


execute_java_constructorV

Allocates a new Java object and invokes a constructor. This method accepts a va_list argument list as a parameter instead of ellipses.

Syntax

HObject* __cdecl execute_java_constructorV(ExecEnv *ee, const char *classname, ClassClass *cb, const char *signature, va_list args);

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. This parameter should be set to NULL.
*classname | The name of the class if cb is NULL. Use forward slashes (/) instead of dots (.) as package delimiters. (For example, java/lang/System.)
*cb | The address of the class object. Use NULL and provide classname if the address is not known.
*signature | The types of parameters passed to the constructor. See execute_java_dynamic_method for a description of signature characters. The return type for all constructors, V, is automatically appended and should not be specified.
args | Additional arguments.


execute_java_constructor_method

Invokes a Java constructor method.

Syntax

__cdecl execute_java_constructor_method(struct methodblock *mb, ...);

Parameters

*mb The pointer to the methodblock structure.

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


execute_java_constructor_methodV

Calls a Java constructor method using a va_list as a parameter instead of ellipses.

Syntax

__cdecl execute_java_constructor_methodV(struct methodblock *mb, va_list args);

Parameters

*mb | The pointer to the methodblock structure.
args | Additional arguments.

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


execute_java_dynamic_method

Invokes a Java dynamic method.

Syntax

long __cdecl execute_java_dynamic_method(ExecEnv *ee, HObject *obj, char *method_name, char *signature);

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.
*obj | The address to the Java object containing the method.
*method_name | The name of the method to be called.
*signature | The types of parameters and return type of the method (see the following table).

Remarks

The signature parameter specifies the parameters and return type of the method by enclosing the character codes for parameter types in parentheses, followed by the character code for the return type. The following table shows the mapping of types to signature characters:

Character | Java type
[ | array
Z | boolean
B | byte
C | char
D | double
F | float
I | int
J | long
L | object
S | short
V | void

Arrays must be followed by the array type; for example, [C for a character array. For multidimensional arrays, repeat [ for the number of dimensions. For example, [[Z signifies a two-dimensional Boolean array.

For objects, the signature is followed by the object class name and ends with a semicolon (;). For example, the signature for the a Rectangle object is "Ljava/awt/Rectangle;".

The following example uses this function to call the Rectangle.move method with two integer parameters to the method, x and y:

long lrval = execute_java_dynamic_method(NULL, phRectangle, "move","(II)V", x, y);


execute_java_dynamic_method64

Invokes a Java dynamic method. This method is equivalent to the execute_java_dynamic_method, except it returns a 64-bit value instead of a 32-bit long.

Syntax

int64_t __cdecl execute_java_dynamic_method64(ExecEnv *ee, HObject *obj, char *method_name, char *signature);

Return Value

A 64-bit value.

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.
*obj | The address to the Java object containing the method.
*method_name | The name of the method to be called.
*signature | The types of parameters and return type of the method.


execute_java_dynamic_methodV

Invokes a Java dynamic method. This method is equivalent to the execute_java_dynamic_method, except it returns a 64-bit value instead of a 32-bit long, and accepts a va_list argument list as a parameter.

Syntax

int64_t __cdecl execute_java_dynamic_methodV(ExecEnv *ee, HObject *obj, const char *method_name, const char *signature, va_list args);

Return Value

A 64-bit value.

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.
*obj | The address to the Java object containing the method.
*method_name | The name of the method to be called.
*signature | The types of parameters and return type of the method.
args | Additional arguments.


execute_java_interface_method

Invokes a Java interface method.

Syntax

long __cdecl execute_java_interface_method(ExecEnv *ee, HObject *pobj, ClassClass j_interface, const char *method_name, const char *signature);

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.
*pobj | The address of the Java object containing the method named by the method_name parameter.
j_interface | A Java class interface.
*method_name | The name of the method to be called.
*signature | The types of parameters and return type of the method.


execute_java_interface_method64

Invokes a Java interface method. This method is equivalent to the execute_java_interface_method, except it returns a 64-bit value instead of a 32-bit long.

Syntax

int64_t __cdecl execute java_interface_method64(ExecEnv *ee, HObject *pobj, ClassClass j_interface, const char *method_name, const char *signature);

Return Value

A 64-bit value.

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.
*pobj | The address to the Java object containing the method named by the method_name parameter.
j_interface | A Java class interface.
*method_name | The name of the method to be called.
*signature | The types of parameters and return type of the method.


execute_java_interface_methodV

Invokes a Java interface method. This method is equivalent to the execute_java_interface_method, except it returns a 64-bit value instead of a 32-bit long and accepts a va_list argument list as a parameter.

Syntax

int64_t __cdecl execute_java_interface_methodV(ExecEnv *ee, HObject *pobj, ClassClass j_interface, const char *method_name, const char *signature, va_list args);

Return Value

A 64-bit value.

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.
*pobj | The address to the Java object containing the method named by the method_name parameter.
j_interface | A Java class interface.
*method_name | The name of the method to be called.
*signature | The types of parameters and return type of the method.
args | Additional arguments.


execute_java_static_method

Invokes a Java static method.

Syntax

long __cdecl execute_java_static_method(ExecEnv *ee, ClassClass *cb, char *method_name, char *signature);

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Pass NULL.
*cb | The address of the class object, obtained with the FindClass function.
*method_name | The name of the method to be called.
*signature | The types of parameters passed to the constructor. For a description of signature characters, see execute_java_dynamic_method.


execute_java_static_method64

Invokes a Java static method. This method is equivalent to the execute_java_dynamic_method, except it returns a 64-bit value instead of a 32-bit long.

Syntax

int64_t __cdecl execute_java_static_method64(ExecEnv *ee, ClassClass* cb, char *method_name, char *signature);

Return Value

A 64-bit value.

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Pass NULL.
*cb | The address of the class object, obtained with the FindClass function.
*method_name | The name of the method to be called.
*signature | The types of parameters passed to the constructor. For a description of signature characters, see execute_java_dynamic_method64.


execute_java_static_methodV

Invokes a Java static method. This method is equivalent to the execute_java_dynamic_method, except it returns a 64-bit value instead of a 32-bit long, and accepts a va_list argument list as a parameter.

Syntax

int64_t __cdecl execute_java_static_methodV(ExecEnv *ee, ClassClass *cb, const char *method_name, const char *signature, va_list args);

Return Value

A 64-bit value.

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Pass NULL.
*cb | The address of the class object, obtained with the FindClass function.
*method_name | The name of the method to be called.
*signature | The types of parameters passed to the constructor. For a description of signature characters, see execute_java_dynamic_method64.
args | Additional arguments.


Field_GetXXX

Retrieves the value of the specified field. Both static and non-static members of these functions can be passed a field block.

Syntax

__int32 __cdecl Field_GetValue(HObject *obj, struct fieldblock * field);

__int64 __cdecl Field_GetValue64(HObject *obj, struct fieldblock * field);

float __cdecl Field_GetFloat(HObject *obj, struct fieldblock * field);

double __cdecl Field_GetDouble(HObject *obj, struct fieldblock * field);

#define Field_GetBoolean(obj,field) ((bool_t) Field_GetValue(obj,field))

#define Field_GetByte(obj,field) ((signed char) Field_GetValue(obj,field))

#define Field_GetChar(obj,field) ((unicode) Field_GetValue(obj,field))

#define Field_GetShort(obj,field) ((short) Field_GetValue(obj,field))

#define Field_GetInt(obj,field) Field_GetValue(obj,field)

#define Field_GetLong(obj,field) Field_GetValue64(obj,field)

#define Field_GetObject(obj,field) ((HObject*) Field_GetValue(obj,field))

#define Field_GetFloat(obj,field) Field_GetFloat(obj,field)

#define Field_GetDouble(obj,field) Field_GetDouble(obj,field)

Return Value

Returns a value of a type determined by the function.

Parameters

obj | The address of the object that the field belongs to. Must be NULL for static fields, non-NULL for non-static fields.
field | The field block of the field.

Exceptions

SignalError if the obj parameter is not NULL for static fields.

NullPointerException if the obj parameter is NULL for non-static fields.

Remarks

These functions operate on static or non-static fields, including both of the component object model (COM) MapsTo fields and the fields in Java objects.


Field_GetOffset

Returns the offset of dynamic fields in the class.

Syntax

unsigned __cdecl Field_GetOffset(struct fieldblock *field);

Return Value

Returns the offset of the field relative to the object for non-static fields. Returns 0 (zero) for static fields.

Parameters

*field The field block of the field. The underlying structure of field block is not defined; it is used only to prevent accidental type misuse using the alternative, PVOID.

Remarks

Note This function accounts for the MSReserved value at the top of structures generated by msjavah. This means you can just add this value to the base of the object to get to the data.


Field_GetStaticPtr

Returns an address of the static data.

Syntax

PVOID __cdecl Field_GetStaticPtr(struct fieldblock *field);

Return Value

Returns an address to the data for static fields, or NULL for non-static fields.

Parameters

*field The field block of the field. The underlying structure of field block is not defined; it is used only to prevent accidental type misuse using the alternative, PVOID.


Field_SetXXX

Sets the value of the specified field.

Syntax

void __cdecl Field_SetValue(HObject *obj, struct fieldblock * field, __int32 value);

void __cdecl Field_SetValue64(HObject *obj, struct fieldblock * field, __int64 value);

void __cdecl Field_SetFloat(HObject *obj, struct fieldblock * field, float value);

void __cdecl Field_SetDouble(HObject *obj, struct fieldblock * field, double value);

#define Field_SetBoolean(obj,field,value) Field_SetValue(obj,field,(bool_t)(value))

#define Field_SetByte(obj,field,value) Field_SetValue(obj,field,(signed char)(value))

#define Field_SetChar(obj,field,value) Field_SetValue(obj,field,(unicode)(value))

#define Field_SetShort(obj,field,value) Field_SetValue(obj,field,(short)(value))

#define Field_SetInt(obj,field,value) Field_SetValue(obj,field,value)

#define Field_SetLong(obj,field,value) Field_SetValue64(obj,field,value)

#define Field_SetObject(obj,field,value) Field_SetValue(obj,field,(__int32)(value))

#define Field_SetFloat(obj,field,value) Field_SetFloat(obj,field,value)

#define Field_SetDouble(obj,field,value) Field_SetDouble(obj,field,value)

Parameters

obj | The address of the object that the field belongs to.
field | The field block of the field.
value | The value of the field.

Remarks

These functions operate on static or non-static fields, including both of the COM MapsTo fields and the fields in Java objects.


FindClass

Retrieves a class object pointer for a named class.

Syntax

ClassClass* __cdecl FindClass(ExecEnv *ee, char *classname, bool_t resolve);

Return Value

Returns a pointer to the class.

Parameters

*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Set this parameter to NULL.
*classname | The name of the class to locate.
resolve | Ignored. Classes found will always be resolved.

Remarks

Use this function to get a pointer to a class, named by classname. This pointer can be used in the execute_java_static_method function to identify the class.


FindClassEx

Retrieves a class object pointer for a named class, according to the specified flags.

Syntax

ClassClass* __cdecl FindClassEx(char *pszClassName,DWORD dwFlags);

Return Value

Returns a pointer to the class.

Parameters

*pszClassName The name of the class to locate.
dwFlags One of the following flags:

FINDCLASSEX_NOINIT: If the class is a system class, prevents the class’s static initializer from running.

FINDCLASSEX_IGNORECASE: Performs a case-insensitive validation of the class name, as opposed to the case-sensitive validation that normally occurs.

FINDCLASSEX_SYSTEMONLY: Looks only for the named class as a system class.

Remarks

This method is similar to the FindClass method, but accepts arguments to control the class load operation. See also FindClassFromClass.


FindClassFromClass

This function is similar to FindClassEx, but takes a ClassClass, supplying the ClassLoader context to use to

Syntax

ClassClass* __cdecl FindClassFromClass(const char *pszClassName, DWORD dwFlags, ClassClass *pContextClass);

Parameters

*pszClassName | The name of the class to locate.
dwFlags One of the following flags:

FINDCLASSEX_NOINIT: If the class is a system class, prevents the class’s static initializer from running.

FINDCLASSEX_IGNORECASE: Performs a case-insensitive validation of the class name, as opposed to the case-sensitive validation that normally occurs.

FINDCLASSEX_SYSTEMONLY: Looks only for the named class as a system class.
*pContextClass | An extra ClassClass parameter to do java.lang.ClassLoader relative lookups.

Remarks

This function was added as of versions 2925 through 3167 of the Microsoft virtual machine.


GCDisable

Increments the block count and disables garbage collection.

Syntax

int __cdecl GCDisable();

Return Value

Returns the incremented block count.

Remarks

Use this function to disable garbage collection after you have enabled it using GCEnable.


GCDisableCount

Returns the current GCDisable count.

Syntax

int __cdecl GCDisableCount();

Return Value

Returns the current count.

Remarks

Used for diagnostic purposes. Because the use of GCEnable and GCDisable requires a counter, this provides a way to verify that the count is what is expected.


GCDisableMultiple

Increments the block count a specified number of times.

Syntax

void __cdecl GCDisableMultiple(int cDisable);

Parameters

cDisable The number of times to increment the block count.

Remarks

This function is useful when you have previously called GCEnableCompletely to allow garbage collection on all referenced objects, but later want to reinstate the block count with one call. The following example shows enabling garbage collection around a sleep call.

    int nEnable = GCEnableCompletely();
    Sleep( (int) millis );
    GCDisableMultiple(nEnable);


GCEnable

Decrements the block count and enables garbage collection by the Microsoft VM.

Syntax

int __cdecl GCEnable();

Return Value

Returns the decremented block count.

Remarks

When calling a native function from within Java, garbage collection is blocked by default. If the native function call is going to take some time, you can enable garbage collection with this call. However, you should first use the GCFramePush function to allow the garbage collector to track any Java objects that you care about during garbage collection.


GCEnableCompletely

Decrements the block count to 0 (zero) and enables garbage collection by the Microsoft VM.

Syntax

int __cdecl GCEnableCompletely();

Return Value

Returns the block count before entering this function.

Remarks

This function enables garbage collection, regardless of the number of calls previously made to GCDisable.


GCFramePop

Restores the GCFrame with current values for members of the structure.

Syntax

void __cdecl GCFramePop(PVOID pGCFrame);

Parameters

pGCFrame The address of a garbage collection frame that references a structure with Java objects that are being tracked.


GCFramePush

Informs the Microsoft VM garbage collector of a GCFrame to track.

Syntax

void __cdecl GCFramePush(PVOID pGCFrame, PVOID pObjects, DWORD cbObjectStructSize);

Parameters

pGCFrame | The address of a garbage collection frame referencing the pObjects structure.
pObjects | The structure containing the Java objects to track during garbage collection.
cbObjectStructSize | The size of pObjects structure.

Remarks

The garbage collector initializes the structure referenced by pObjects to NULL.


GCFreeHandle

Frees a strong pointer that was originally obtained using GCNewHandle.

Syntax

void __cdecl GCFreeHandle(HObject **pphobj);

Parameters

**pphobj The pointer to a pointer to be freed.


GCFreePtr

Frees a garbage collection pointer that was originally obtained using GCGetPtr.

Syntax

void __cdecl GCFreePtr(HObject **pphobj);

Parameters

**pphobj The pointer to a pointer to be freed.


GCGetPtr

Allocates a weak pointer for an object, and then updates it when garbage collection occurs.

Syntax

HObject** __cdecl GCGetPtr(HObject *phobj);

Return Value

Returns an address to a pointer to a Java object handle.

Parameters

*phobj The address of a Java object.

Remarks

Given a pointer to an object, this function allocates and returns the address of that object pointer, and then updates the contained pointer when garbage collection occurs. Note that if the object gets freed during garbage collection, the value of the contained pointer will be NULL. A weak pointer is different from a strong pointer (as allocated by GCNewHandle). A weak pointer will not block garbage collection (removal) of the referenced object, but a strong pointer will. (Strong pointers are scanned like any other object during garbage collection; weak pointers are updated after the garbage collection has been completed.)


GCNewHandle

Creates a strong pointer to an object.

Syntax

HObject** __cdecl GCNewHandle(HObject *phobj);

Return Value

Returns an address to the object pointer.

Parameters

*phobj The object that is to be referenced.

Remarks

Using this function is similar to placing an object in a GCFrame; however, strong pointers can be stored statically across calls. A strong pointer prevents the object from being collected as garbage, whereas a weak pointer only tracks the object's movement.


GCSetObjectReferenceForHandle

Garbage-collection safe method for updating the contents of a handle.

Syntax

void __cdecl GCSetObjectReferenceForHandle(HObject **handle, HObject *phobj);

Parameters

**handle | The result of calling GCGetPtr for a weak pointer or GCNewHandle for a strong handle.
*phobj | The new object pointer.

Remarks

If handles are not updated using a garbage-collection safe method, the Microsoft VM will fault during the next garbage collection.


GCSetObjectReferenceForObject

Garbage-collection safe method for updating the fields in an object.

Syntax

void __cdecl GCSetObjectReferenceForObject(HObject **location, HObject *phobj);

Parameters

**location | The pointer to a field of an object.
*phobj | The new object pointer.

Remarks

The safest method to set a field in an object is to use the Field_SetValue method. If objects are not updated using a garbage-collection safe method, the Microsoft VM will fault during the next garbage collection.


GetCurrentJavaTimeMillis

Returns the same result as defined by java.lang.System.currentTimeMillis().

Syntax

__int64 __cdecl GetCurrentJavaTimeMillis();

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


get_methodblock

Retrieves a pointer to a method block structure containing the class name, method name, and parameter and return types of a method.

Syntax

struct methodblock* __cdecl get_methodblock(HObject *pjobj, char *method_name, char *signature);

Return Value

Returns a handle to a method in the given object specified by name and signature. This is useful for functions like do_execute_java_method, which can use this information directly instead of having to look it up.

Parameters

*pjobj | The address of the structure.
*method_name | The name of the method to invoke.
*signature | The types of parameters passed to the constructor. For a description of signature characters, see execute_java_dynamic_method.


GetNativeMethodCallersClass

Determines the class type of the caller.

Syntax

ClassClass* __cdecl GetNativeMethodCallersClass();

Return Value

Returns a pointer to the class type of the caller.


GetNativeMethodCallersMethodInfo

Retrieves information about the caller's method.

Syntax

struct methodblock* __cdecl GetNativeMethodCallersMethodInfo();

Return Value

Returns a method block pointer.


GetNativeMethodsClass

Retrieves information about a native method's class.

Syntax

ClassClass * __cdecl GetNativeMethodsClass();

Return Value

Returns a pointer to the class type of the caller.

Remarks

This function was added as of versions 2925 through 3167 of the Microsoft virtual machine.


GetNativeMethodsMethodInfo

Retrieves information about the native method.

Syntax

struct methodblock* __cdecl GetNativeMethodsMethodInfo();

Return Value

Returns a method block pointer.

Remarks

This function was added as of versions 2925 through 3167 of the Microsoft virtual machine.


getPendingException

Retrieves a pending exception.

Syntax

HObject *getPendingException(ExecEnv *ee);

Return Value

Returns the pending exception; if no exception is pending, NULL is returned.

Parameters

*ee The placeholder for the execution environment, which is not needed by the Microsoft VM. Pass NULL.


HResultFromException

Creates an HRESULT return type from a Java exception object. This function prototype is found in the Nativcom.h header file.

Syntax

HResult __cdecl HResultFromException(OBJECT *exception_object);

Return Value

An HRESULT type.

Parameters

*exception_object The exception object to covert to an HRESULT.


is_instance_of

Determines whether the specified object phobj can be cast to the specified class type dcb.

Syntax

BOOL is_instance_of(JHandle *phobj, ClassClass *dcb, ExecEnv *ee);

Return Value

Returns TRUE if the object can be cast to the class type; otherwise, returns FALSE.

Parameters

*phobj | A pointer to an object.
*dcb | A class type.
*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Pass NULL.


is_subclass_of

Determines whether the class type cb is a subclass of type dcb.

Syntax

BOOL is_subclass_of(ClassClass *cb, ClassClass *dcb, ExecEnv *ee);

Return Value

Returns TRUE if the class is a subclass of dcb; otherwise, returns FALSE.

Parameters

*cb | The class type that is being tested.
*dcb | The class type to test against.
*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Pass NULL.


ImplementsInterface

Determines whether the class type cb implements the interface represented by the icb class type.

Syntax

BOOL ImplementsInterface(ClassClass *cb, ClassClass *icb, ExecEnv *ee);

Return Value

Returns TRUE if the class implements the specified interface.

Parameters

*cb | The class type to test.
*icb | The class type that represents an interface to test against.
*ee | The placeholder for the execution environment, which is not needed by the Microsoft VM. Pass NULL.


isInstanceOf

Determines if a specified Java object is an instance of a particular class.

Syntax

BOOL __cdecl isInstanceOf(JHandle *phobj, char *classname);

Return Value

Returns TRUE if the handle is an instance of the class, or FALSE otherwise.

Parameters

*phobj | The address of the Java handle.
*classname | The name of the Java class.


j2chook_getmethodblock

Returns the methodblock of the target method.

Syntax

struct methodblock* __cdecl j2chook_getmethodblock(J2CMethodHookInfo *phookinfo);

Parameters

*phookinfo The address of the method hook information.


j2chook_getsizeofuserdata

Gets the size of the user data in the MCCustomMethod descriptor.

Syntax

WORD __cdecl j2chook_getsizeofuserdata(J2CMethodHookInfo *phookinfo);

Parameters

*phookinfo The address of the method hook information.


j2chook_getuserdata

Gets the writable pointer to the user data in the MCCustomMethod descriptor.

Syntax

LPVOID __cdecl j2chook_getuserdata(J2CMethodHookInfo *phookinfo);

Parameters

*phookinfo The address of the method hook information.


j2chook_getvtblindex

Returns the vtable index of the target method.

Syntax

WORD __cdecl j2chook_getvtblindex(J2CMethodHookInfo *phookinfo);

Parameters

*phookinfo The address of the method hook information.


javaString2CString

Retrieves the characters of the Java String object into a C string buffer.

Syntax

char* __cdecl javaString2CString(Hjava_lang_String *s, char *buf, int buflen);

Return Value

Returns the address of the C string.

Parameters

*s | The Java String object.
*buf | The C string buffer.
buflen | The length of the C string buffer.

Remarks

Use this function in place of the JDK makeCString function, which is unsupported by the Microsoft RNI. No allocation occurs with this function.


javaStringLength

Retrieves the length of the Java String object.

Syntax

int __cdecl javaStringLength(Hjava_lang_String *s);

Return Value

Returns the number of characters in the string.

Parameter

*s The address of the Java String object.


javaStringLengthAsCString

Retrieves the length of the Java String object as a C string.

Syntax

int __cdecl javaStringLengthAsCString(HString *phString);

Return Value

Returns the length of the string object.

Parameter

*phString The address of the Java String object.

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


javaStringStart

Returns a temporary pointer to the first character of the Java String object. It is important that you use this method rather than try to manipulate RNI structures that handle string types. The Microsoft VM handles strings differently in certain situations, and strings may be stored with multiple objects.

Syntax

unicode * __cdecl javaStringStart(HString *string);

Return Value

Returns a string pointer.

Parameters

*string The String handle to reference.

Remarks

Note This pointer may change after garbage collection.


jcdw_java_owned

Returns true if Microsoft VM frees the non-garbage-collected heap memory that this data wrapper contains when the data wrapper is garbage-collected.

Syntax

int __cdecl jcdw_java_owned(Hjava_lang_Object *phJCDW);

Parameters

*phJCDW The data pointer to the heap memory.


jcdw_memory_freed_on_gc

Returns true if the Microsoft VM allocated the non-garbage-collected heap memory contained by the data wrapper.

Syntax

int __cdecl jcdw_memory_freed_on_gc(Hjava_lang_Object *phJCDW);

Parameters

*phJCDW The data pointer to the heap memory.


jcdwClassOffsetOf

Returns the byte offset within the non—garbage-collected heap memory to the specified field name from the supplied java.lang.Class object.

Syntax

unsigned int __cdecl jcdwClassOffsetOf(Hjava_lang_Object *phJCDWClass, const char *pFieldName);

Parameters

*phJCDWClass | The data pointer to the heap memory.
*pFieldName | The specified field.


jcdwClassSizeOf

Returns the size of the non-garbage-collected heap memory used by instances of the supplied java.lang.Class object.

Syntax

unsigned int __cdecl jcdwClassSizeOf(Hjava_lang_Object *phJavaClass);

Parameters

*phJavaClass The data pointer to the heap memory.


jcdwGetData

Returns the data pointer to the non-garbage-collected heap memory contained by the data wrapper object.

Syntax

void* __cdecl jcdwGetData(Hjava_lang_Object *phJCDW);

Parameters

*phJCDW The data pointer to be replaced.


jcdwNewData

Replaces the data pointer contained in the data wrapper with a new quantity of non—garbage-collected heap memory. The previous memory, if any, is freed if it is owned by the Microsoft VM.

Syntax

void* __cdecl jcdwNewData(Hjava_lang_Object *phJCDW, unsigned int numBytes);

Parameters

*phJCDW | The data pointer to be replaced.
numBytes | The size of the heap memory in bytes.


jcdwOffsetOf

Returns the byte offset within the non—garbage-collected heap memory to the specified field name.

Syntax

unsigned int __cdecl jcdwOffsetOf(Hjava_lang_Object *phJCDW, const char *pFieldName);

Parameters

*phJCDW | The data pointer to the heap memory.
*pFieldName | The specified field.


jcdwPropagateToJava

Given an object, propagates field values from the object's associated native memory to the Java object. If fFreeIndirectNativeMemory is TRUE, the native memory used for any reference fields (strings, custom marshaled fields, and so on) is released.

Syntax

int __cdecl jcdwPropagateToJava(Hjava_lang_Object *phJCDW, BOOL fFreeIndirectNativeMemory);

Return Value

Returns FALSE on error, else TRUE.

Parameters

*phJCDW | The data pointer to the heap memory.
fFreeIndirectNativeMemory | Indicates whether the native memory used for any reference fields will be released.


jcdwPropagateToNative

Given an object, propagates field values from the Java object to the object's associated native memory.

Syntax

int __cdecl jcdwPropagateToNative(Hjava_lang_Object *phJCDW);

Return Value

Returns FALSE on error, else TRUE.

Parameters

*phJCDW The data pointer to the heap memory.


jcdwSetData

Replaces the data pointer that this data wrapper represents with the specified pointer.

Syntax

int __cdecl jcdwSetData(Hjava_lang_Object *phJCDW, LPVOID pv);

Parameters

*phJCDW | The data pointer to be replaced.
pv | The specified data pointer.


jcdwSizeOf

Returns the size of the non-garbage-collected heap memory contained by the data wrapper object.

Syntax

unsigned int __cdecl jcdwSizeOf(Hjava_lang_Object *phJCDW);

Parameters

*phJCDW The data pointer to the heap memory.


jio_snprintf

Prints to a string with a buffer limit.

Syntax

int __cdecl jio_snprintf(char *str, size_t count, const char *fmt);

Return Value

Returns the length of the string after printing to it.

Parameters

*str | The address of the string to print to.
count | The limit of the number of characters to print.
*fmt | The address of the format string.

Remarks

%ls and %S now print a Unicode string.

%p prints the address using hexadecimal.


jio_vsnprintf

Prints to a string with a buffer limit using a va_list macro for arguments.

Syntax

int __cdecl jio_vsnprintf(char *str, size_t count, const char *fmt, va_list args);

Return Value

Returns the length of the string after printing to it.

Parameters

*str | The address of the string to print to.
count | The limit of the number of characters to print.
*fmt | The address of the format string.
args | Argument list.


makeJavaString

Constructs a Java string from a given ANSI C character buffer, converting it to Unicode.

Syntax

Hjava_lang_String* __cdecl makeJavaString(char *str, int len);

Return Value

Returns a string formatted as a java.lang.String object.

Parameters

*str | The address of the C string to convert.
len | The number of characters in the C string, excluding the terminating NULL.


makeJavaStringW

Constructs a Java string from a Unicode C character buffer.

Syntax

Hjava_lang_String* __cdecl makeJavaStringW( unicode *pszwSrc, int cch );

Return Value

Returns a string formatted as a Java String object.

Parameters

*pszwSrc | The address of the C string to convert.
cch | The number of characters in the C string, excluding the terminating NULL.


makeJavaStringFromUtf8

Creates a new Java String object, initialized from a NULL-terminated, UTF8-formatted, C string.

Syntax

Hjava_lang_String* __cdecl makeJavaStringFromUtf8(const char *pszUtf8);

Return Value

Returns a string formatted as a Java String object.

Parameters

*pszUtf8 The address of the initialization string.

Remarks

Unlike other RNI string conversion functions, makeJavaStringFromUtf8 does not require a character count but does require NULL termination of the UTF8 string.


MakeByteString

Creates a new array of bytes initialized from the C string.

Syntax

HArrayOfByte* __cdecl MakeByteString(char *str, long len);

Return Value

Returns the converted byte string.

Parameters

*str | The address of the C string to convert.
len | The number characters in the string, excluding the terminating NULL character.


MarshalCallToJavaObjectHostThread

Re-executes the Raw Native Interface (RNI) method on the apartment thread ID for the supplied Java object.

Syntax

HRESULT __cdecl MarshalCallToJavaObjectHostThread(Hjava_lang_Object *phobj, int64_t *pResult);

Parameters

*phobj | The address of the Java object.
*pResult | The address of the value to be returned upon S_FALSE.

Remarks

MarshalCallToJavaObjectHostThread and MarshalCallToJavaThreadID return the following sets of HRESULTs:

S_OK -- The call was successfully marshaled to the target thread. The marshaled call may have generated an exception, which can be checked by calling exceptionOccurred.

S_FALSE -- The call did not require marshaling to the other thread. The currently executing thread is the target thread.

E_<> -- An error occurred inside the MarshalCall API, such as invalid arguments, out of memory, and so on.

The typical use of these APIs is to call the appropriate MarshalCall API and if the HRESULT is S_FALSE, execute the rest of the RNI method; otherwise, return with the value contained in pResult.


MarshalCallToJavaThreadId

Re-executes the RNI method on the supplied thread ID for the supplied Java object.

Syntax

HRESULT __cdecl MarshalCallToJavaThreadId(JAVATID tid, int64_t *pResult);

Parameters

tid | The thread ID.
*pResult | The address of the value to be returned upon S_FALSE.

Remarks

MarshalCallToJavaThreadId and MarshalCallToJavaObjectHostThread return the following sets of HRESULTs:

S_OK -- The call was successfully marshaled to the target thread. The marshaled call may have generated an exception, which can be checked by calling exceptionOccurred.

S_FALSE -- The call did not require marshaling to the other thread. The currently executing thread is the target thread.

E_<> -- An error occurred inside the MarshalCall API, such as invalid arguments, out of memory, and so on.

The typical use of these APIs is to call the appropriate MarshalCall API and if the HRESULT is S_FALSE, execute the rest of the RNI method; otherwise, return with the value contained in pResult.


Member_GetAttributes

Retrieves a combination of the ACC_XXX flags for a field or method as it appears in the Java class file.

Syntax

int __cdecl Member_GetAttributes(PVOID member);

Return Value

Returns attributes flags.

Parameters

member The method or field block of the member.


Member_GetClass

Retrieves the name of the class that the field or method is implemented in.

Syntax

ClassClass* __cdecl Member_GetClass(PVOID member);

Return Value

Returns the name of a class.

Parameters

member The address of a method or field block.


Member_GetName

Retrieves the method or field name.

Syntax

const char * __cdecl Member_GetName(PVOID member);

Return Value

Returns the method or field name.

Parameters

member The address of a method or field block.


Member_GetSignature

Retrieves the signature of the field or method.

Syntax

const char * __cdecl Member_GetSignature(PVOID member);

Return Value

Returns a signature.

Parameters

member The address of a method or field block.


monitorEnter

Enters a synchronization object.

Syntax

void __cdecl monitorEnter(UINT_PTR object);

Parameters

object The synchronization object to enter.

Remarks

You can use the ObjectMonitorEnter macro to automatically cast the synchronization object to an integer and call this method.


monitorExit

Exits a synchronization object.

Syntax

void __cdecl monitorExit(UINT_PTR object);

Parameters

object The synchronization object to exit.

Remarks

You can use the ObjectMonitorExit macro to automatically cast the synchronization object to an integer and call this method.


monitorNotify

Wakes up a single thread that is waiting on this object's monitor.

Syntax

void __cdecl monitorNotify(UINT_PTR object);

Parameters

object Synchronization object.

Remarks

You can use the ObjectMonitorNotify macro to automatically cast the synchronization object to an integer and call this method. This method is the native equivalent of the Java.lang.Object.notify method.


monitorNotifyAll

Wakes up all threads that are waiting on this object's monitor.

Syntax

void __cdecl monitorNotifyAll(UINT_PTR object);

Parameters

object The synchronization object.

Remarks

You can use the ObjectMonitorNotifyAll macro to automatically cast the synchronization object to an integer and call this method. This method is the native equivalent of the Java.lang.Object.notifyAll method.


monitorWait

Waits to be notified by another thread of a change in this object.

Syntax

void __cdecl monitorWait(UINT_PTR, int64_t millis);

Parameters

object | The synchronization object.
millis | The maximum time to wait, in milliseconds.

Remarks

You can use the ObjectMonitorWait macro to automatically cast the synchronization object to an integer and call this method. This method is the native equivalent of the Java.lang.Object.wait method.


Object_GetClass

Retrieves class that the object points to.

Syntax

ClassClass* __cdecl Object_GetClass(HObject *obj);

Return Value

Returns a class object pointer.

Parameters

*obj The address of the class object to retrieve.


PrepareThreadForJava

Thread entry function for calls into the virtual machine.

Syntax

BOOL __cdecl PrepareThreadForJava(PVOID pThreadEntryFrame);

Return Value

Returns TRUE if successful; otherwise, returns FALSE.

Parameters

pThreadEntryFrame An instance of a thread entry frame. This pointer is maintained by the Microsoft VM and the same pointer should be used in UnprepareThreadForJava when exiting the Microsoft VM.

Remarks

This method prepares a Java thread for entering the Microsoft VM so that calls can be safely made from the thread to native methods.

Allocate ThreadEntryFrames on the associated thread's stack rather than in the heap. The Microsoft virtual machine treats the ThreadEntryFrame as a stack frame on the associated thread's stack. All other stack frames are internally allocated on the associated thread's stack. Some code assumes that stack frame addresses are in monotonically increasing order. Linking in a ThreadEntryFrame that violates that assumption may cause problems. The ThreadEntryFrame should be a local variable in the method that calls PrepareThreadForJava.

Note that garbage collection is disabled between PrepareThreadforJava and UnprepareThreadForJava. An application can hang if each thread waits until it is about to exit before calling UnprepareThreadforJava.

The following code sample demonstrates the use of invocation APIs.

//  This code demonstrates the use of the PrepareThreadForJava and
//  UnprepareThreadForJava invocation APIs.

#include <windows.h>
#include <stdio.h>
#include <native.h>

void main(int argc, char *argv[])
{
    ThreadEntryFrame threadEntryFrame;
    ClassClass* pClass;

    //  Call this API before calling into the Microsoft VM to allow it
    //  to allocate any per-thread structures and to do any first-time
    //  initialization. After return from this call, Java objects may
    // be accessed or RNI APIs may be called.
    if (PrepareThreadForJava(&threadEntryFrame)) {

        pClass = FindClass(NULL, "TestClass", TRUE);

        if (pClass != NULL) {
            execute_java_static_method(NULL, pClass, "someMethod", "()V");
        } else {
            printf("Failed to find class!\n");
        }

        //  Detaches the "entry frame" from this thread. After return
        //  from this call, it is no longer safe to directly touch Java
        //  objects or call RNI APIs.
        UnprepareThreadForJava(&threadEntryFrame);

    } else {
        printf("Failed to initialize thread!\n");
    }
}


PrepareThreadForJavaEx

Extended thread entry function for calls into the Microsoft VM.

Syntax

BOOL __cdecl PrepareThreadForJavaEx(PVOID pThreadEntryFrame, DWORD dwFlags);

Parameters

pThreadEntryFrame | An instance of a thread entry frame. This pointer is maintained by the Microsoft VM and the same pointer should be used in UnprepareThreadForJava when exiting the Microsoft VM.
dwFlags | Flags.

Remarks

Allocate ThreadEntryFrames on the associated thread's stack rather than in the heap. The Microsoft virtual machine treats the ThreadEntryFrame as a stack frame on the associated thread's stack. All other stack frames are internally allocated on the associated thread's stack. Some code assumes that stack frame addresses are in monotonically increasing order. Linking in a ThreadEntryFrame that violates that assumption may cause problems. The ThreadEntryFrame should be a local variable in the method that calls PrepareThreadForJavaEx.

The dwFlags parameter has the PTFJ_DONTINSTALLSTANDARDSECURITY bit defined. If this flag is set, the default security manager is not installed for the first caller that initializes the VM.

PrepareThreadForJavaEx added as of versions 2437 through 2925 of the Microsoft virtual machine.


RNIGetCompatibleVersion

Allows the Microsoft VM to determine if the DLL is compatible with the Microsoft VM.

Syntax

DWORD __declspec(dllexport) __cdecl RNIGetCompatibleVersion();

Return Value

Returns the version used by the DLL (defined as RNIVER in Native.h).

Remarks

All raw native interface DLLs must export this function to enable compatibility-checking by the Microsoft VM.


SignalError

Creates a Java exception object, which is thrown upon returning from the native code.

Syntax

void __cdecl SignalError(struct execenv *ee, char *ename, char *DetailMessage);

Parameters

*ee | The placeholder for the executive environment, which is not needed. This parameter should be NULL.
*ename | The name of a valid Throwable exception class or subclass.
*DetailMessage | The message to display with the exception. Can be set to NULL.


SignalErrorHResult

Creates a Java exception object from an HRESULT return type. This function prototype is found in the Nativcom.h header file.

Syntax

void __cdecl SignalErrorHResult(HRESULT theHRESULT);

Parameters

theHRESULT The standard return value that indicates whether a function call is a success.


SignalErrorPrintf

Creates a Java exception object and specifies a format string for exception description to be printed when thrown.

Syntax

void __cdecl SignalErrorPrintf( char *ename, char *pszFormat);

Parameters

*ename | The name of a valid Throwable exception class or subclass.
*pszFormat | The format string. See the C printf function.


Thread_IsInterrupted

Checks to see if the current thread is interrupted and optionally resets the interrupt flag. Used in RNI code to determine if some other thread has called Thread.interrupt and wants the current thread to stop.

Syntax

BOOL __cdecl Thread_IsInterrupted(BOOL fResetInterruptFlag);

Parameters

fResetInterruptFlag Indicates whether to reset the interrupt flag.

Remarks

This function was added as of versions 2437 through 2925 of the Microsoft virtual machine.


UnprepareThreadForJava

Thread exit function for calls into the Microsoft VM.

Syntax

VOID __cdecl UnprepareThreadForJava(PVOID pThreadEntryFrame);

Return Value

Returns true if successful; otherwise, returns false.

Parameters

pThreadEntryFrame An instance of a thread entry frame. This pointer is maintained by the Microsoft VM and is the same pointer used in PrepareThreadForJava when entering the Microsoft VM.

Remarks

This method should be called from any thread when exiting the Microsoft VM.

Allocate ThreadEntryFrames on the associated thread's stack rather than in the heap. The Microsoft virtual machine treats the ThreadEntryFrame as a stack frame on the associated thread's stack. All other stack frames are internally allocated on the associated thread's stack. Some code assumes that stack frame addresses are in monotonically increasing order. Linking in a ThreadEntryFrame that violates that assumption may cause problems. The ThreadEntryFrame should be a local variable in the method that calls UnprepareThreadForJava.

Note that garbage collection is disabled between PrepareThreadForJava and UnprepareThreadForJava. An application can hang if each thread waits until it is about to exit before calling UnprepareThreadforJava.


Raw Native Interface Structures

Raw native interface (RNI) uses certain structures to access Java arrays and wrap native code for the Microsoft virtual machine (Microsoft VM).

The ThreadEntryFrame and GCFrame structures are used in several RNI functions, but are not manipulated directly by the user.

The ClassArrayOf* structures all share the same architecture. The MSReserved field is reserved for the Microsoft VM. Each structure contains a length and body field. The body field is a variable length array, with the array's length stored in the length field.

Structures that handle strings and arrays of strings have different architecture because the Microsoft VM handles strings differently in certain situations.

The following structures are defined in the Native.h header file.

ArrayOfSomething | Serves as a base structure from which others that access Java arrays are derived.
C2JMethodHookInfo | Information structure for COM-to-Java custom method hook.
ClassArrayOfArray | Accesses Java two-dimensional arrays from native RNI code.
ClassArrayOfByte | Accesses Java arrays of bytes from native RNI code.
ClassArrayOfChar | Accesses Java arrays of characters from native RNI code.
ClassArrayOfDouble | Accesses Java arrays of doubles from native RNI code.
ClassArrayOfFloat | Accesses Java arrays of floats from native RNI code.
ClassArrayOfInt | Accesses Java arrays of integers from native RNI code.
ClassArrayOfLong | Accesses Java arrays of long type primitives from native RNI code.
ClassArrayOfObject | Accesses Java arrays of Objects from native RNI code.
ClassArrayOfShort | Accesses Java arrays of short type primitives from native RNI code.
ClassArrayOfString | Accesses Java arrays of String types from native RNI code.
GCFrame | Wraps a garbage collection frame from native RNI code.
J2CMethodHookInfo | Information structure for Java-to-COM custom method hook.
ThreadEntryFrame | Used in the PrepareThreadForJava and UnprepareThreadForJava functions.


ArrayOfSomething

This structure serves as a base structure from which others that access Java arrays are derived.

Syntax

typedef struct

{

const int32_t MSReserved;

const unsigned long length;

} ArrayOfSomething;

Parameters

MSReserved | Reserved for the Microsoft VM.
length | The length of the array. Array lengths are measured in the unit of the array, not in bytes.


C2JMethodHookInfo

Information structure for COM-to-Java custom method hook.

Syntax

typedef struct {

DWORD cbSize; struct methodblock *javaMethod; LPVOID pComArgs;
const volatile JAVAARG *ppThis;

// Store the COM result here:

union {

HRESULT resHR;

DWORD resDWORD;

double resDouble;

};

} C2JMethodHookInfo;

Parameters

cbSize | The size of structure in bytes.
*javaMethod | The Java method to call.
pComArgs | The pointer to a COM method argument stack.
*ppThis | The pointer to a pointer to the Java keyword this.


ClassArrayOfArray

This structure is used to access Java two-dimensional arrays from native RNI code.

Syntax

typedef struct ClassArrayOfArray

{

const int32_t MSReserved;

const unsigned long length;

JHandle * const (body[1]);

} ClassArrayOfArray;

Parameters

MSReserved | Reserved for the Microsoft VM.
length | The length of the array (in elements).
body | A variable length array of JHandle pointers (it is declared as one element because not all C compilers support [] declarations).


ClassArrayOfByte

This structure is used to access Java arrays of bytes from native RNI code.

Syntax

typedef struct ClassArrayOfByte

{

const int32_t MSReserved;

const unsigned long length;

char body[1];

} ClassArrayOfByte;

Parameters

MSReserved | Reserved for the Microsoft VM.
length | The length of the array (in bytes).
body | A variable length array of characters (it is declared as one element because not all C compilers support [] declarations).


ClassArrayOfChar

This structure is used to access Java arrays of characters from native RNI code.

Syntax

typedef struct ClassArrayOfChar

{

const int32_t MSReserved;

const unsigned long length;

unsigned short body[1];

} ClassArrayOfChar;

Parameters

MSReserved | Reserved for the Microsoft Virtual Machine.
length | The length of the array (in shorts).
body | A variable length array of shorts (it is declared as one element because not all C compilers support [] declarations).


ClassArrayOfDouble

This structure is used to access Java arrays of doubles from native RNI code.

Syntax

typedef struct ClassArrayOfDouble

{

const int32_t MSReserved;

const unsigned long length;

double body[1];

} ClassArrayOfDouble;

Parameters

MSReserved | Reserved for the Microsoft VM.
length | The length of the array (in doubles).
body | A variable length array of doubles (it is declared as one element because not all C compilers support [] declarations).


ClassArrayOfFloat

This structure is used to access Java arrays of floats from native RNI code.

Syntax

typedef struct ClassArrayOfFloat

{

const int32_t MSReserved;

const unsigned long length;

float body[1];

} ClassArrayOfFloat;

Parameters

MSReserved | Reserved for the Microsoft VM.
length | The length of the array (in floats).
body | A variable length array of floats (it is declared as one element because not all C compilers support [] declarations).


ClassArrayOfInt

This structure is used to access Java arrays of integers from native RNI code.

Syntax

typedef struct ClassArrayOfInt

{

const int32_t MSReserved;

const unsigned long length;

long body[1];

} ClassArrayOfInt;

Parameters

MSReserved | Reserved for the Microsoft VM.
length | The length of the array (in long integers).
body | A variable-length array of long integers. It is declared as one element because not all C compilers support [] declarations.


ClassArrayOfLong

This structure is used to access Java arrays of long type primitives from native RNI code.

Syntax

typedef struct ClassArrayOfLong

{

const int32_t MSReserved;

const unsigned long length;

__int64 body[1];

} ClassArrayOfLong;

Parameters

MSReserved | Reserved for the Microsoft VM.
length | The length of the array in long integers.
body | A variable-length array of long integers. It is declared as one element because not all C compilers support [] declarations.


ClassArrayOfObject

This structure is used to access Java arrays of objects from native RNI code.

Syntax

typedef struct ClassArrayOfObject

{

const int32_t MSReserved;

const unsigned long length;

HObject * const body[1];

} ClassArrayOfObject;

Parameters

MSReserved | Reserved for the Microsoft VM.
length | The length of the array (in object references).
body | A variable length array of HObject pointers (it is declared as one element because not all C compilers support [] declarations).


ClassArrayOfShort

This structure is used to access Java arrays of short type primitives from native RNI code.

Syntax

typedef struct ClassArrayOfShort

{

const int32_t MSReserved;

const unsigned long length;

short body[1];

} ClassArrayOfShort;

Parameters

MSReserved | Reserved for the Microsoft VM.
length | The length of the array (in shorts).
body | A variable length array of shorts (it is declared as one element because not all C compilers support [] declarations).


ClassArrayOfString

This structure is used to access Java arrays of String types from native RNI code.

Syntax

typedef struct ClassArrayOfString

{

const int32_t MSReserved;

const unsigned long length;

HString * const (body[1]);

} ClassArrayOfString;

Parameters

MSReserved | Reserved for the Microsoft VM.
length | The length of the array (in string pointers).
body | A variable length array of HString pointers (it is declared as one element because not all C compilers support [] declarations).


GCFrame

This structure is used to wrap a garbage collection frame from native RNI code. It is used in the GCFramePush and GCFramePop methods. For more information on garbage collection issues, see the Overview of the Garbage Collection Architecture.

Syntax

typedef struct {DWORD reserved[6];

} GCFrame;

Parameters

reserved Reserved for the Microsoft VM.


J2CMethodHookInfo

Information structure for Java-to-COM custom method hook.

Syntax

typedef struct {

DWORD cbSize; IUnknown *punk; const volatile JAVAARG *pJavaArgs;

} J2CMethodHookInfo;

Parameters

cbSize | The size of the structure in bytes.
*punk | The pointer to the interface being invoked.
*pJavaArgs | The pointer to the Java argument stack.


ThreadEntryFrame

This structure is used in the PrepareThreadForJava and UnprepareThreadForJava functions. These functions are thread exit and entry functions that wrap calls into the Microsoft VM.

Syntax

typedef struct {

DWORD reserved[6];

} ThreadEntryFrame;

Parameters

reserved Reserved for the Microsoft VM.


Invocation Interfaces

 Microsoft SDK for Java

Invocation Interfaces Reference

The invocation interfaces are used to launch applications in the Microsoft virtual machine (Microsoft VM). The globally unique identifiers (GUIDs) for the invocation interfaces are defined in %SDKDIR%\Include\javaexec.h.

The invocation interfaces are as follows:

IJavaExecute

IJavaExecute2

IEnumJAVAPROPERTY

For details about the structures these interfaces use, see Invocation Interface Structures.

The Microsoft VM can load .class files and other Java visible resource files from Microsoft® Win32® portable executable (PE) image files (.exe and .dll files). In order for the Microsoft VM to find Java resources from within a PE, the Java resources must be stored within the PE as Win32 resources. The header file %SDKDIR%\Include\jexefmt.h describes the format of the data that must be stored within the resources of a PE image in order for the Microsoft VM to locate Java resources within that image. This format is referred to as the exegen format. There are two versions of it, depending on the version of your Microsoft VM.

Finding Java Resources in a PE Image

Assuming a Microsoft® Win32® PE image that has Java resources bound to it, there are three ways to tell the Microsoft VM that it should look for resources within that module:

  1. If the resources are bound into a DLL, then that DLL can be placed on the class path. The syntax is the same for adding a .zip file to the class path. The .dll extension must be specified. There is a restriction on how a DLL must be built in order to be placed on the class path. In particular, the resource containing the file directory must be stored in a resource with a specific ID.

  2. The COM interface IJavaExecute2::SetClassSource can be used to add a Win32 module to the list of locations where the Microsoft VM searches for Java resources. See %SDKDIR%\Include\javaexec.h.

  3. The RNI function AddModuleResourceClassSource can also be used to add a Win32 module to the list of locations where the Microsoft VM searches for Java resources. See %SDKDIR%\Include\native.h.


IJavaExecute Interface

The invocation interfaces are used to launch applications in the Microsoft virtual machine (Microsoft VM).

// IUnknown methods
HRESULT QueryInterface(REFIID riid, LPVOID *ppv);
ULONG AddRef();
ULONG Release();

//  Methods
  HRESULT Execute(LPJAVAEXECUTEINFO pjei, LPERRORINFO *pperrorinfo);
  HRESULT GetDefaultClassPath(LPOLESTR *ppszClassPath);


Methods (IJavaExecute Methods)

 Microsoft SDK for Java

IJavaExecute Interface Methods

The IJavaExecute interface has the following methods:

Execute loads a Java class and executes its static main method.
GetDefaultClassPath sets a variable to a string that describes the default class path.


IJavaExecute::Execute

This method of the IJavaExecute interface loads a Java class and executes its static main method. The main method must have the following signature:

public static void main( String[] );

Syntax

HRESULT Execute(LPJAVAEXECUTEINFO pJavaExecuteInfo, LPERRORINFO *ppErrorInfo);

Return Value

If the main method runs successfully and does not throw an uncaught Java exception, the Execute method returns S_OK and ppErrorInfo is set to NULL.

If the main method runs successfully and throws an uncaught Java exception, the Execute method returns S_OK and ppErrorInfo is set to an IErrorInfo object that describes the exception.

If the class is not found or does not expose a main method, or if there are insufficient resources to run the method, the Execute method returns a failing HRESULT.

Parameters

pJavaExecuteInfo | Provides the name of the class, the arguments, and the execution environment. See JAVAEXECUTEINFO.
*ppErrorInfo | Points to a buffer that receives an IErrorInfo interface object if the main method throws a Java exception. This parameter can be NULL if this information is not needed.


IJavaExecute::GetDefaultClassPath

This method of the IJavaExecute interface sets ppszClassPath to a string describing the default class path (computed from the registry and the CLASSPATH environment variable).

Syntax

HRESULT GetDefaultClassPath(LPOLESTR *ppszClassPath);

Parameters

*ppszClassPath The address of the buffer to receive the class path. The elements in the class path are separated by semicolons (;). Elements are searched in the order that they appear in the String.

Remarks

The caller must free the returned string using the CoTaskMemFree function.


IJavaExecute2 Interface

IJavaExecute2 extends IJavaExecute by adding two methods.

// IUnknown methods
HRESULT QueryInterface(REFIID riid, LPVOID *ppv);
ULONG AddRef();
ULONG Release();

//  Methods
  HRESULT Execute(LPJAVAEXECUTEINFO pjei, LPERRORINFO *pperrorinfo);
  HRESULT GetDefaultClassPath(LPOLESTR *ppszClassPath);
  HRESULT SetClassSource(DWORD dwType, LPVOID pData, DWORD dwLen);
  HRESULT SetSystemProperties(LPENUMJAVAPROPERTY penum);

See also IJavaExecute.


Methods (IJavaExecute2 Interface)

 Microsoft SDK for Java

IJavaExecute2 Methods

The IJavaExecute2 interface has the following methods:

SetClassSource inserts a special source of classes into the class path.
SetSystemProperties sets property values for java.lang.System.


IJavaExecute2::SetClassSource

This method of the IJavaExecute2 interface inserts a special source of classes into the class path. These elements are searched before any other elements in the class path.

Syntax

HRESULT SetClassSource(DWORD dwType, LPVOID pData, DWORD dwLen);

Parameters

dwType | The type of class source. The following types are recognized: CLASS_SOURCE_TYPE_MODULERESOURCES Allows classes to be stored within a Microsoft® Win32® resource. CLASS_SOURCE_TYPE_ISTORAGE Not currently implemented. These values are defined in Javaexec.h, which is in the \Include subdirectory of the Microsoft SDK for Java installation.
pData | The address of an information structure whose format is type-dependent. For CLASS_SOURCE_TYPE_MODULERESOURCES, this is an address of a JAVACLASSRESOURCEINFO structure.
dwLen | The size (in bytes) of the structure pointed to by pData.


IJavaExecute2::SetSystemProperties

This method of the IJavaExecute2 interface sets property values for java.lang.System.

Syntax

HRESULT SetSystemProperties(LPENUMJAVAPROPERTY pEnumJavaProperty);

Parameters

pEnumJavaProperty The enumeration object that produces a set of key/value pairs. SetSystemProperties will enumerate through the entire collection and map each key to the associated value.


IEnumJAVAPROPERTY

This enumerator lists key/value pairs for IJavaExecute2::SetSystemProperties.

//  IUnknown methods
  HRESULT QueryInterface(REFIID riid, LPVOID *ppv);
  ULONG AddRef();
  ULONG Release();

// IEnumJavaPROPERTIES methods
  HRESULT Clone(LPENUMJAVAPROPERTY *ppenum);
  ULONG Next(ULONG celt, LPJAVAPROPERTY rgelt, ULONG *pceltFetched);
  HRESULT Reset();
  HRESULT Skip(ULONG celt);


Methods (IEnumJAVAPROPERTY Interface)

 Microsoft SDK for Java

IEnumJAVAPROPERTY Methods

The IEnumJAVAPROPERTY interface has the following methods:

Clone creates a copy of the enumerator, including the enumerator's current position in its list of elements.
Next retrieves the next specified number of elements from the enumerator's list.
Reset resets the enumerator's current position in its list of elements to the first element in the list.
Skip moves the enumerator's current position ahead in its list of elements by the given number of elements.


IEnumJAVAPROPERTY::Clone

This method of the IEnumJAVAPROPERTY interface creates a copy of the enumerator, including the enumerator's current position in its element list.

Syntax

HRESULT Clone(LPENUMJAVAPROPERTY *ppenum);

Parameters

[out] *ppenum Returns a pointer to the copied enumerator.


IEnumJAVAPROPERTY::Next

This method of the IEnumJAVAPROPERTY interface retrieves the next specified number of elements from the enumerator's list.

Syntax

ULONG Next(ULONG celt, LPJAVAPROPERTY rgelt, ULONG *pceltFetched);

Parameters

[in] celt | The number of elements requested.
[out] rgelt | The array to be filled in with the elements.
[out] *pceltFetched | The number of elements actually returned in rgelt. This can be less than celt if fewer than celt elements remained in the list.


IEnumJAVAPROPERTY::Reset

This method of the IEnumJAVAPROPERTY interface resets the enumerator's current position to first in its element list.

Syntax

HRESULT Reset();


IEnumJAVAPROPERTY::Skip

This method of the IEnumJAVAPROPERTY interface moves the enumerator's current position ahead in its element list by the given number of elements.

Syntax

HRESULT Skip(ULONG celt);

Parameters

[in] celt The number of elements requested.


Invocation Interface Structures

The structures used by IJavaExecute, IJavaExecute2, and IEnumJAVAPROPERTY are as follows:

JAVACLASSRESOURCE defines the format of data found in a Jexegen-created image.JAVACLASSRESOURCEINFO is passed to IJavaExecute::SetClassSource.JAVAEXECUTEINFO is passed into IJavaExecute::Execute.
JAVAEXECUTEINFO2 extends JAVAEXECUTEINFO.
JAVAPROPERTY is used as part of IEnumJAVAPROPERTY.
JAVASYSTEMEXITPROC provides the opportunity for custom shutdown logic.


JAVACLASSRESOURCE (Invocation Interfaces)

 Microsoft SDK for Java

JAVACLASSRESOURCE

This structure defines the format of data found in a Jexegen-created image.

struct {
  DWORD dwNameOffset;
  DWORD dwDataSize;
  DWORD  cbFileSize;
  DWORD  dwDataOffset;
  JEXRESID ResourceID;
  JEXRESID ResourceType;};

Members

dwNameOffset | Offset from the beginning of the main resource to a null terminated UTF8 string which contains the name of the java resource. The name must be a complete name (class files must be terminated with a '.class' extension). Forward slashes ('/') must be used as package separators.
dwDataSize | If set to 0xFFFFFFFF (JEX_USE_RESOURCE_LENGTH), then the length of the java resource is the size of the Microsoft® Win32® resource that it lives within. Otherwise, this value is simply the length of the Java resource in bytes.
cbFileSize | File size.
dwDataOffset | Offset from the beginning of the owning resource to the data for this java resource. Must be 0 if dwDataSize is set to 0xFFFFFFFF.
ResourceID | Specifies the Microsoft® Win32® resource ID within the jexegen-generated PE image which contains the bits for this Java resource. See JEXRESID for details of how to map these values to an actual Win32 resource.
ResourceType | Specifies the Microsoft® Win32® resource type within the jexegen-generated PE image which contains the bits for this Java resource. See JEXRESID for details of how to map these values to an actual Win32 resource.

Different Versions of the Exegen Format

There are two versions of the exegen format. The original format, version 1, only supported .class files, and could not store arbitrarily named resources. Version 4.79.2582 and earlier of the Microsoft virtual machine only support the version 1 format. Newer Microsoft VMs support the version 2 format, which adds the ability to store non-class resources. The version 1 format also required that all the data be stored within a single Microsoft® Win32® resource. The version 2 format removes this restriction.

Version 1 Format

All classes are stored in a single Microsoft® Win32® binary resource within the PE. This resource begins with a table that lists the names of the files contained within the resource, and information that indicates where the raw bits for those files are located. The actual data for the contained files follows this table.

If IJavaExecute2::SetClassSource or AddModuleResourceClassSource is used to tell the Microsoft VM about the module, then this resource can be stored with any resource ID (although the resource type must be RT_RCDATA), since those APIs allow you to specify the resource ID. If you are building a DLL to be placed on the class path, then this resource must be stored with a resource ID of 1000 (JEX_DEFAULT_CLASS_RESOURCE_ID), and the resource type must be RT_RCDATA.

The layout of this resource consists of three sections in this order:

[JEXHEADER]
[FILEINFO SECTION]
[RAW DATA SECTION]
  1. [JEXHEADER] The resource begins with a header that contains a signature, a format version, flags, and a count of the number of class files contained within the resource. The layout of the header is defined in the JEXHEADER structure. The dwFormatVersion of the JEXHEADER structure must be set to 1 for the version 1 format.

  2. [FILEINFO SECTION] Immediately following the header is an array of file information structures. The number of elements in this list is equal to the cNumFiles field in the header. The layout of each of these file information structures is defined in the JEXFILEINFOV1 structure. Each specifies the name and location of a class file that is contained within the resource. Note that the dwNameOffset field points to the name of the class file. This name must be in UTF8 form. Forward slashes must be used as package separators. The name is the class name, not the name of a class file, so do not append a .class extension. For example, the following is correct:
    java/lang/Class

    The following are incorrect:

    java\lang\Class
java.lang.Class
java/lang/Class.class
  3. [RAW DATA SECTION] Following the list of JEXFILEINFOV1 structures is the string data for the class names, and raw binary data of the class files. Note that there is no implied ordering on this data. The only requirement is that the resource offsets in the JEXFILEINFOV1 structures must point to the proper data. The jexegen tool happens to place all the string data immediately after the file information list, followed by the raw binary data of the class files, but no other generation tool must follow this layout.

Version 2 Format

The exegen version 2 format adds two features that the version 1 format did not support.

  1. The ability to store arbitrarily named resources within the module.

    This allows image files, audio clips, and so on to be stored in addition to class files. These named resources can be retrieved from the Java side with any APIs that can load class path-relative data (such as java.lang.Class.getResourceAsStream).

  2. The ability to store the class/resource data in multiple Microsoft® Win32® resources.

    The version 1 format required that all class data be contained within the exegen resource. The version 2 format allows class/resource data in Win32 resources other than the primary exegen resource. This allows individual Java resources to be stored as individual Win32 resources. This makes it possible to utilize Win32 internationalization of Java resources.

As with the version 1 format, there is a primary exegen resource that contains the JEXHEADER and file information structures. The rules for how the Microsoft VM locates this information have not changed. The resource identifier specified with either IJavaExecute2::SetClassSource or AddModuleResourceClassSource refers to this primary resource. This main resource must be stored as resource ID JEX_DEFAULT_CLASS_RESOURCE_ID in DLLs intended for the class path.

The layout of the main resource is essentially the same as version 1. A header is followed by a list of file information structures, which is followed by string data and possibly file data.

The JEXHEADER structure remains unchanged, with the exception that the dwFormatVersion field must be set to 2.

Following the header is a list of JEXFILEINFOV2 structures. The number of elements in this list is determined by the cNumFiles field in the header. These are similar to the JEXFILEINFOV1 structures, with the addition of two fields (ResourceID and ResourceType) which specify the Win32 resource which contains the bits for each Java resource. Following the list of JEXFILEINFOV2 structures is the string data for the file names, and resource names (if any). Some of the java resource files may be found here as well, although all the file data may be found in other resources.

Note that the fields ResourceID and ResourceType do not contain Win32 resource IDs. See the JEXRESID type in %SDKDIR%\Include\jexefmt.h for mapping these values to Win32 resource IDs.

As in the version 1 format, the dwNameOffset field in the JEXFILEINFOV2 structure is an offset to the name of the Java resource in UTF8 form. Unlike the original format, this name is file name not a class name. Class files must be stored with the .class extension. Forward slashes are used as package separators. For example, the following is correct:

java/lang/Class.class

The following are incorrect:

java\lang\Class.class
java.lang.Class.class
java/lang/Class

The version 2 format gives a good deal of flexibility in laying out the Java resources within the .exe or .dll file.

  1. Just like in the original format, the files can exist in the main resource. The ResourceID and ResourceType fields of the corresponding JEXFILEINFOV2 structures need to be set to JEX_MAINRESOURCE_MARKER. The cbFileSize and dwDataOffset fields need to be filled in to specify where in the main resource the resource file is located.

  2. You can have a one-to-one mapping between a java resource file and a Microsoft® Win32® resource that it is located in. ResourceID and ResourceType need to contain the proper values to point to the Win32 resource (either by name or integer IDs). cbFileSize should be set to JEX_USE_RESOURCE_LENGTH to indicate that the size of the Java resource is the same as the Win32 resource that it is found in. dwDataOffset should be 0.

  3. You can have external Win32 resources (that is, not the main resource) that contain multiple Java resources. ResourceID and ResourceType point to the Win32 resource, and dwDataOffset and cbFileSize specify which portion of that Win32 resource contains the data for the Java resource.


JAVACLASSRESOURCEINFO (Invocation Interfaces)

 Microsoft SDK for Java

JAVACLASSRESOURCEINFO

This structure is passed to IJavaExecute::SetClassSource.

struct {
   HMODULE hModule;
   DWORD dwResourceID;
};

Members

hModule | The handle to the module that contains the resource.
dwResourceID | Identifies the resource that contains the class data. The resource must be of type RCDATA. For the format of the resource data, see JAVACLASSRESOURCE.


JAVAEXECUTEINFO

This structure is passed into IJavaExecute::Execute.

struct {
   DWORD cbSize;
   DWORD dwFlags;
   LPCOLESTR pszClassName;
   LPCOLESTR *rgszArgs;
   ULONG cArgs;
   LPCOLESTR pszClassPath;
} JAVAEXECUTEINFO, *LPJAVAEXECUTEINFO;

Members

cbSize | Must be set to the size of JAVAEXECUTEINFO in bytes.
dwFlags Can be:

JEIF_VERIFYCLASSES: Turn verification of all classes on. By default, the verification setting from the registry will be used.
pszClassName The name of the class to load. The class must have a public method that matches the following signature:
public static void main(java.lang.String[]);
rgszArgs | The array of Unicode strings. This string is converted to a Java array of strings. The array is then passed as the argument to the main method. The cArgs member indicates the number of strings in this array.
cArgs | The number of strings in rgszArgs.
pszClassPath Specifies additional class path elements, which are separated by semicolons (;). These class path elements will be searched before those in the default class path.

pszClassPath can be NULL if no additional class path elements are required.

Remarks

The class path is a per-process variable. Any extensions made to the class path by IJavaExecute::Execute will persist after IJavaExecute::Execute has returned. IJavaExecute::Execute is unsuitable, therefore, for use in a shared library.


JAVAEXECUTEINFO2 (Invocation Interfaces)

 Microsoft SDK for Java

JAVAEXECUTEINFO2

This structure extends JAVAEXECUTEINFO by adding a single function pointer.

struct JAVAEXECUTEINFO2
{
  JAVAEXECUTEINFO jei;
  JAVASYSTEMEXITPROC pfnSystemExitProc;
} JAVAEXECUTEINFO2, *LPJAVAEXECUTEINFO2;


JAVAPROPERTY (Invocation Interfaces)

 Microsoft SDK for Java

JAVAPROPERTY

This structure is used as part of IEnumJAVAPROPERTY. The pszKey and pszValue members are both allocated using the CoTaskMemAlloc function, and are released by the caller of IEnumJAVAPROPERTIES::Next.

struct {
   LPOLESTR pszKey;
   LPOLESTR pszValue;
}   JAVAPROPERTY, * LPJAVAPROPERTY;

See Also

IEnumJAVAPROPERTY


JAVASYSTEMEXITPROC

This structure provides the opportunity for custom shutdown logic.

void JAVASYSTEMEXITPROC(int ExitCode);

Members

ExitCode
The exit code passed to System.exit, by which the Microsoft VM invokes JAVASYSTEMEXITPROC.

Remarks

JAVASYSTEMEXITPROC is called if the Java application calls java.lang.System.exit. JAVASYSTEMEXITPROC is not called if the Java application drops out of its main method and returns to the Microsoft VM. If this function returns, the Microsoft® Win32® ExitProcess function is called; application shutdown cannot be canceled. Multiple threads may call System.exit at once; the Microsoft VM does not serialize calls to this function. The function is not called in a mode where Raw Native Interface (RNI) functions can be directly used. PrepareThreadForJava can be used, however, to enter a mode where RNI can be used.


Compiler Directives Reference

The Microsoft Java compiler directives are optional special comments inserted in source code to aid in Java/COM integration and development. This reference describes their syntax and parameters, lists their related attributes and directives, and gives usage examples.

Directive parameters are optional unless otherwise specified. Those parameters that are valid only in conjunction with others, or have other dependencies, are marked as such.

The parameters and their values are case-sensitive. Each directive exists as part of a special comment block. Therefore, it must be preceded by a forward slash and two asterisks (/**) and closed with a forward slash (/). Directives in comment blocks beginning with a forward slash and only one asterisk (/*) are not recognized by the compiler.

Note The com.ms.com.NoAutoScripting and com.ms.com.NoAutoMarshaling interfaces assert behavior on Java/COM objects that complements the directives' functionality.

The Microsoft Java compiler directives are as follows:

@com.class specifies that this Java object represents a COM coclass with the given GUID, casting support, and Java security requirements.

@com.interface indicates that this Java interface represents a COM interface with the specified GUID, threading model, and types.

@com.method marks the Java method as a COM interface method, which should be exposed in the object's vtable, dispatch table, or neither.

@com.parameters specifies which parameters are in, out, or a return value and how they should be mapped to COM and from COM to Java.

@com.register used by the Microsoft® Visual J++® vjreg tool to register the compiled Java class as a COM object in the system registry.

@com.struct (see @dll.struct) specifies that the Java class will be a Java-Callable Data Wrapper (JCDW).

@com.structmap (see @dll.structmap) indicates how a JCDW field should map to COM and from COM back to this field in Java.

@com.transaction indicates various transaction situations in which the Microsoft Transaction Server can host COM objects.

@com.typeinfo specifies that additional information from the type library represents this COM object.

@dll.import maps a C function from the specified DLL to a Java method.

@dll.struct specifies that the Java class will be a Java-Callable Data Wrapper (JCDW).

@dll.structmap indicates how a JCDW field should map to COM and from COM back to this field in Java.

@security modifies class link-time access check behavior and stack crawl behavior for J/Direct method calls.

Attributes Reference describes the special attributes generated by the compiler directives. These attributes support Java/COM integration and Java/Microsoft® Win32® integration.

See Also

Integrating Java and COM (programmer's guide)
Using COM Objects from Java (white paper)
Integrating Java and COM (white paper)
COM Samples
J/Direct Samples


@com.class

The @com.class directive is applied at the class level to indicate that the Java class definition represents a COM component object class (coclass).

Syntax

@com.class(classid=GUID, iid=GUID, DynamicCasts, safe, safeAddFlags=integer)

Parameters

classid=GUID This parameter is required. Example: classid=0BE35203-8F91-11CE-9DE3-00AA004BB851 | Represents the class identifier (CLSID) associated with this Java-implemented COM object.
iid=GUID | Represents the interface identifier (IID) for this interface.
DynamicCasts | Indicates that this class supports dynamic casts, which allow the user to cast instances of this class to COM interfaces not directly implemented by the class. The Microsoft virtual machine determines that the Java object supports the interface by requesting it in a call to QueryInterface on the Java object's underlying COM object.
safe | Specifies that the structure may be used safely by untrusted classes. A COM_Safety attribute is attached to the class.
safeAddFlags=integer | Specifies a word of information to be put in the COM_Safety attribute. Note The Microsoft VM currently ignores this data when reading the COM_Safety attribute.

Attributes

COM_Class_Type | Class scope.
COM_GuidPool | Class scope.
COM_Safety | Class scope.

Related Directives

@com.interface

@com.register

@com.typeinfo

@com.transaction

Example

The following declaration indicates that the defined class represents a COM object with the given CLSID that supports dynamic casts.

/**
* @com.class(classid=D7D6E07A-DCCD-11D0-AA4B-60970DEBAE, DynamicCasts)
*/
public class MyObject implements com.ms.com.IUnknown { }


@com.interface

The @com.interface directive marks the current Java interface as a COM interface.

Syntax

@com.interface(iid=GUID, [thread=AUTO | NO, type=DISPATCH | DUAL | VTABLE])

Parameters

iid=GUID This parameter is required. | Represents the interface identifier (IID) for this interface.
thread=AUTO | NO | Specifies the default Microsoft VM marshaling behavior to be applied to any COM object parameters (type=DISPATCH or type=OBJECT in the @com.parameters directive) in this interface's methods. If AUTO is specified, the Microsoft VM automatically marshals any calls from Java on these objects to the thread that the object was created in, which is the thread that originally received the object. This is the safest option, and the default. If NO is specified, the Microsoft VM assumes that the object is callable on any Java thread. Default: AUTO
type=DISPATCH | DUAL | VTABLE | DISPATCH indicates that this interface can be used only as a dispatch interface. DUAL indicates that this interface is a dual interface, accessible as both a dispatch interface and a vtable interface. VTABLE indicates that this interface can be used only as a vtable interface. Default: VTABLE.

Attributes (indirect)

COM_ExposedAs_Group | Method scope.
COM_GuidPool | Class scope.
COM_MethodPool | Class scope.
COM_ProxiesTo | Method scope.

Related Directives

@com.class

@com.register

@com.typeinfo

@com.transaction

Examples

The following @com.interface directive describes a custom interface with the given IID. All COM object parameters in the methods of this interface are assumed to be apartment-neutral because the thread=NO directive parameter is specified.

/**
*@com.interface(iid=B643D339-2CAB-11D2-94EB-00C04FB92EC2, thread=NO)
*/
public interface IPing extends com.ms.com.IUnknown { }

A dual interface can be described with:

/** @com.interface(iid=D30C1661-CDAF-11D0-8A3E-00C04FC9E26E, thread=AUTO, type=DUAL) */
public interface IWebBrowser2 extends com.ms.com.IUnknown { }

See Also

iid_is and size_is Support
%SDKDIR%\Samples\com\iid_is_size_is


@com.method

The @com.method directive specifies how a COM object method is mapped between Java and COM. It supplies a set of directive parameters that indicate the mapping to the equivalent Microsoft Interface Definition Language (MIDL) form.

Syntax

@com.method([vtoffset=integer | long], [dispid=integer | long], [name=string], [name2=string], [type=METHOD | PROPGET | PROPPUT | PROPPUTREF], [thread=AUTO | NO], [nodispatch], [returntype=VOID | HRESULT], [addFlagsVtable=integer], [addFlagsDispatch=integer])

Parameters

vtoffset=integer | long | Specifies the vtable offset for this method, not counting the methods in IUnknown. Thus, the first method in an interface has an offset of zero, the second method has an offset of one, and so on. Dependency: Used only for custom (vtable) and dual interfaces. Default: The method's index within the COM methods in the Java interface (that is, those methods with @com.method directives).
dispid=integer | long | Indicates the dispatch ID (DISPID) for this method Dependency: Used only for methods that will be members of a dispatch or dual interface. Default: The method’s index within the COM methods in the Java interface (that is, those methods with @com.method directives).
name=string | Specifies how to expose this Java method to COM by means of IDispatch. The Microsoft VM implements a dispatch interface that maps the name given by this parameter to the dispatch ID given by the dispid parameter. Dependency: Used only for methods that will be members of a dispatch or dual interface. Default: The method's name.
name2=string | Specifies a secondary mapping from this Java method to COM by means of IDispatch. The Microsoft VM implements a dispatch interface that maps the name given by this parameter to the dispatch ID given by the dispid parameter. Dependency: Used only for methods that will be members of a dispatch or dual interface.
type=METHOD | PROPGET | PROPPUT | PROPPUTREF | Indicates the dispatch invocation type of the Java method. It can be for manipulating COM object properties or an actual COM object method. The semantics of each possible value are directly related to those of the corresponding DISPATCH_* flag used in calls to IDispatch::Invoke. Dependency: Used only for methods that will be members of a dispatch or dual interface. Default: METHOD.
thread=AUTO | NO | Specifies the default Microsoft VM marshaling behavior to be applied to any COM object parameters (type=DISPATCH or type=OBJECT in the @com.parameters directive) in this method. If AUTO is specified, the Microsoft VM automatically marshals any calls from Java on these objects to the thread that the object was created in, which is the thread that originally received the object. This is the safest option, and the default. If NO is specified, the Microsoft VM assumes that the object is callable on any Java thread. Default: AUTO.
nodispatch | Specifies that this method should not be accessible from a dispatch interface.
returntype=VOID | HRESULT | Specifies the return type for this method. Generally, the default, HRESULT, is used. If specified, the COM method associated with this Java method returns an HRESULT. The Microsoft VM hides this fact by mapping HRESULT values other than S_OK to instances of com.ms.com.ComException, and vice versa. If the Java method returns a value, it is mapped to the last parameter in the COM method, which is assumed to be a return value. If VOID is specified, the Java and COM method return values are directly related. For instance, if the COM method returns an integer value, the Java method will return this same integer value. Dependency: Used only for methods that will be members of a vtable or dual interface. Default: HRESULT.
addFlagsDispatch=integer | A low-level parameter that allows direct modification of created class attributes. The value is truncated to a WORD (2 bytes) and then combined with the Flags field of the MCFuncDesc attribute that will get created for the dispatch method. Dependency: Used only for methods that will be members of a dispatch or dual interface.
addFlagsVtable=integer Example: addFlagsVtable=4 | A low-level parameter that allows direct modification of created class attributes. The value is truncated to a WORD (2 bytes) and then combined with the Flags field of the MCFuncDesc attribute that will get created for the vtable method. Specify the value 4 to cause the Microsoft VM to ignore non-failing HRESULT values. The VM will still throw a ComFailException for failing HRESULT values, but will not throw a ComSuccessException for successful HRESULT values. Dependency: Used only for methods that will be members of a vtable or dual interface.

Attributes

COM_ProxiesTo | Method scope.
COM_ExposedAs_Group | Method scope.
COM_GuidPool | Class scope.
COM_MethodPool | Class scope.

Related Directives

@com.parameters

Support for iid_is and size_is

To express iid_is and size_is from an @com directive, declare methods as follows:

/** @com.method(...)
@com.parameters([in,type=PTR] riid, [customMarshal="com.ms.com.IIDIsMarshaler",type=CUSTOM] return) */
public IUnknown BindToObject(_Guid riid);

/** @com.method(...)
@com.parameters([in,type=U4] length, [in,out,customMarshal="com.ms.com.SizeIsMarshaler",type=CUSTOM] items) */
public void GetItems(int length, int[] items);

See the sample in Samples\com\iidis_sizeis for more information.

Examples

A good way to learn how IDL descriptions are mapped to @com directives is to look at the generated Java wrappers from Jactivex and the IDL notation from oleview and compare the outputs. This is easily accomplished by picking a COM dynamic-link library (DLL), like Shdocvw.dll, and generating wrappers as follows:

jactivex shdocvw.dll

Use oleview to view the IDL representation of the COM objects and interfaces within Shdocvw.dll:

oleview shdocvw.dll

This is a representation of IDL and Java code that illustrates how a property from a dual interface is mapped to @com.method directives.

Here is how the Count method of the IShellWindows interface looks in the OLE/COM Object Viewer:

[id(0x60020000), propget, helpstring("Get count of open Shell windows")]
    HRESULT Count([out, retval] long* Count);

Here is how jactivex maps IShellWindows.Count to @com.method and @com.parameters directives:

/** @com.method(vtoffset=4, dispid=1610743808, type=PROPGET, name="Count", addFlagsVtable=4) */
/**@com.parameters([type=I4] return) */
public int getCount();

See Also

iid_is and size_is Support
%SDKDIR%\Samples\com\iid_is_size_is


@com.parameters

The @com.parameters directive is used with the @com.method directive to specify how Java parameter types and return types are mapped to the underlying COM or native types. It is also possible to specify a custom marshaler that handles how the parameters are represented in the native and Java representations.

Each @com.parameters directive contains a group of directive parameters inside square braces for every parameter in the method, and for the return value if it is not void.

Syntax

@com.parameters([parameters] methodParamName1, [parameters] methodParamName2, … [[parameters] return])

Parameters

iid=GUID Specifies the interface identifier (IID) of this parameter. The Microsoft VM will ensure that only interfaces of this "type" are given to COM clients and servers.

Dependency: Valid only for Java parameters declaring type=OBJECT or type=DISPATCH.

Default: IID_IUnknown.
thread=AUTO | NO Specifies the marshaling behavior to be applied to the COM object parameter. If AUTO is specified, the Microsoft virtual machine automatically marshals any calls from Java on this object to the thread that the object was created in. This is the safest option, and the default.

If NO is specified, the Microsoft VM assumes that the object is callable on any Java thread.

Dependency: Valid only for Java parameters declaring type=OBJECT or type=DISPATCH.

Default: AUTO.
type=ARRAY | BOOLEAN | CURRENCY | CUSTOM | CUSTOMBYREF | CUSTOMBYVAL | DATE | DISPATCH | I1 | I2 | I4 | I8 | OBJECT | PTR | R4 | R8 | SAFEARRAY | STRING | STRUCT | U1 | U2 | U4 | U8 | VARIANT Defines the native type of the Java parameter. See Type Values for @com.parameters and @dll.structmap for details.

If this directive parameter is not declared, a default native type is used, according to the table below.

Dependencies:

ARRAY: Secondary information may be specified using the size and elementType directive parameters.

CUSTOM, CUSTOMBYREF, and CUSTOMBYVAL: The directive parameter customMarshal must be declared.

DISPATCH and OBJECT: Secondary information may be specified using the iid directive parameter.

PTR: Secondary information may be specified using the elementType directive parameter.

Note For return value parameters declaring type=PTR, the VM does not auto-propagate the struct parameter. Call com.ms.com.DllLib.propagateStructFields(JCDW, true) to manually propagate the structure.

SAFEARRAY: The directive parameter vt must be specified.
methodParamNameN or return methodParamNameN is the name of the Nth parameter in the Java method. The preceding directive parameters apply to this parameter in the method.

return indicates that the preceding directive parameters apply to the return value of the Java method, which corresponds to the COM return value (which may be retval-mapped.
in Indicates that the parameter is to be passed from the calling procedure to the called procedure. The out directive parameter may also be specified.
out Indicates that data contained in the parameter is to be passed back from the called procedure to the calling procedure. This allows the calling procedure to obtain data modified by the called procedure. The directive parameter in may also be specified.

Valid only for reference parameters (objects and arrays).
elementType=DISPATCH | I2 | I4 | OBJECT | R4 | R8 | STRING | U1 | VARIANT Specifies the element type of arrays if type=ARRAY or type=PTR.

Dependency: Valid only for Java parameters declaring type=ARRAY or type=PTR.

Default: Determined by the Java array element type as defined in the Java and Native Array Type Mappings table.
size=integer | long For Java parameters declaring type=ARRAY, specifies the number of elements in the array parameter. For Java parameters declaring type=STRUCT, specifies the size, in bytes, of the Java parameter’s corresponding native structure.

Dependency: Valid only for Java parameters declaring type=ARRAY or type=STRUCT.

Default: 1 for type=ARRAY, 0 for type=STRUCT.
customMarshal=string

Example: customMarshal="com.ms.
com.UniStringMarshaller"

 Specifies the name of a class. This class will be asked to marshal the field.

Dependency: Valid only for Java parameters declaring type=CUSTOM, type=CUSTOMBYREF, or type=CUSTOMBYVAL.
customMarshalFlags=integer Specifies bits available to the custom marshaler when invoked. Must be in the range 0 to 3. These bits move into the high two bits of this parameter's MCTypeDesc.Flags field in the method pool entries generated for the method.

Dependency: Valid only for Java parameters declaring type=CUSTOM, type=CUSTOMBYREF, or type=CUSTOMBYVAL.
vt=integer Specifies the VARTYPE of elements within a SAFEARRAY parameter. Use the VT_* values (for example, for an array of integers, use 3=VT_I4).

Dependency: Valid only for Java parameters declaring type=SAFEARRAY.
byref Specifies that this argument is passed by reference (VT_BYREF) in a VARIANT.

Dependency: Valid only for dispatch methods.
array Specifies that this parameter is passed as an array (VT_ARRAY) in a VARIANT.

Dependency: Valid only for dispatch methods.

name=string

Example:

name="Hello"

 Specifies a name to be associated with this parameter.

Dependency: Valid only for dispatch methods.

Note This parameter is not currently used by the VM.

Type Values for @com.parameters and @dll.structmap

type | Native Type (for vtable Method Parameters and struct Fields) | VARTYPE (for dispatch Method Parameters)
ARRAY A native array. The size of the native array is given by the size directive parameter. See the Java and Native Array Type Mappings table for details. The elementType directive parameter defines the array element VARTYPE.

Call this element VARTYPE vtElement. The VARTYPE of this parameter is then VT_BYREF | vtElement.

A default VARTYPE is generated if elementType is not declared. See the Java and Native Array Type Mappings table for details.

BOOLEAN | VARIANT_BOOL (16-bit value) | VT_BOOL
CURRENCY | __int64 (unsigned 64-bit integer) | VT_CY
CUSTOM | Specifies that this parameter or field will be custom marshaled by the class specified in the customMarshal directive parameter. The native type is defined by the custom marshaling class. | N/A
CUSTOMBYREF | Specifies that this parameter will be custom marshaled by the class specified in the customMarshal directive parameter as a by-reference value. This means that the custom marshaler's toExternal method will be called to marshal the parameter to native code, and its toJava method will be called to marshal the parameter from native code to Java. The native type is defined by the custom marshaling class. | N/A
CUSTOMBYVAL | Specifies that this parameter or field will be custom marshaled by the class specified in the customMarshal directive parameter as a by-value parameter. This means that the custom marshaler's copyToExternal method will be called to marshal the parameter to native code, and its copyToJava method will be called to marshal the value from native code to Java. The native type is defined by the custom marshaling class. | N/A
DATE | double (64-bit float) | VT_DATE
DISPATCH | The native type is a pointer to an IDispatch-derived interface. The exact type of the interface is given by the iid directive parameter. | VT_DISPATCH
FIXEDARRAY | The native type is an embedded array. The size of the array is given by the size directive parameter. Valid only for fields typed as an array of primitive type (asserted by the Microsoft VM). For arrays with elements of type char, the native element type is determined by the structure's default character type (see the @dll.struct directive parameters ansi, unicode, and auto). Arrays with elements of type boolean are mapped to native arrays with elements of type BOOL. | N/A
I1 | char (unsigned 8-bit integer) | VT_I2
I2 | short (signed 16-bit integer) | VT_I2
I4 | long (signed 32-bit integer) | VT_I4
I8 | __int64 (signed 64-bit integer) | N/A
OBJECT | The native type is a pointer to an IUnknown-derived interface. The exact type of the interface is given by the iid directive parameter. | VT_UNKNOWN
PTR For parameters of type java.lang.String, the native type is a Unicode string allocated using the CoTaskMemAlloc API.

For parameters or fields of struct type (those classes with @com.struct or @dll.struct declarations), the native type is a pointer to a structure.

 For parameters of array type, the elementType directive parameter defines the array element VARTYPE. Call this element VARTYPE vtElement. The VARTYPE of this parameter is then VT_BYREF | vtElement.

A default VARTYPE is generated if elementType is not declared. See the Java and Native Array Type Mappings table for details.

For parameters of type com.ms.com.Variant, if the elementType parameter directive is declared, the VARTYPE is determined as above. Otherwise, the VARTYPE is VT_BYREF | VT_VARIANT.
R4 | float (32-bit float) | VT_R4
R8 | double (64-bit float) | VT_R8
SAFEARRAY | If the value of the vt directive parameter has the VT_BYREF bit set, the native type is a pointer to a pointer to SAFEARRAY (SAFEARRAY**). Otherwise, the native type is a pointer to SAFEARRAY (SAFEARRAY*). | VT_ARRAY | vt
STRING | BSTR | VT_BSTR
STRUCT | By-value structure. | N/A
TCHAR | Native character (char, WCHAR, or TCHAR). The character's encoding (ANSI or Unicode, signed 8-bit or unsigned 16-bit values, respectively) is dependent on the struct's desired character encoding. See the @dll.struct directive parameters ansi, unicode, and auto. | N/A
TCHAR[integer] | The native type is an embedded string; that is, an embedded character array with length integer and null termination. The character encoding used (ANSI or Unicode) is dependent on the struct's desired character encoding. See the @dll.struct directive parameters ansi, unicode, and auto. Valid only for fields of type java.lang.String (asserted by the Microsoft VM). | N/A
U1 | unsigned char (unsigned 8-bit integer) | VT_UI1
U2 | unsigned short (unsigned 16-bit integer) | VT_I4
U4 | unsigned long (unsigned 32-bit integer) | VT_I4
U8 | unsigned __int64 (unsigned 64-bit integer) | N/A
VARIANT | By-value VARIANT | Determined directly by VARIANT parameter.

Default Native Types for Java Parameters

Java Parameter Type | Native Type (vtable Method) | VARTYPE (dispatch Method)
boolean | VARIANT_BOOL | VT_BOOL
byte | char (signed 8-bit integer) | VT_UI1
char | WCHAR (Unicode character, unsigned 16-bit integer) | VT_I2
double | double (64-bit float) | VT_R8
float | float (32-bit float) | VT_R4
int | long (signed 32-bit integer) | VT_I4
long | __int64 (signed 64-bit integer) | N/A
short | short (signed 16-bit integer) | VT_I2
java.lang.String | BSTR | VT_BSTR
com.ms.com.Variant | VARIANT | VT_VARIANT
OtherObjectType | N/A | VT_UNKNOWN
ArrayType | Native array. The element type is determined by the Java and Native Array Type Mappings table. | VT_BYREF | vtElement, where vtElement is the array element VARTYPE determined by the Java and Native Array Type Mappings table.

Java and Native Array Type Mappings

JAVA ARRAY ELEMENT TYPE | NATIVE ARRAY ELEMENT TYPE | DISPATCH ELEMENT VARTYPE
boolean | VARIANT_BOOL | VT_BOOL
byte | 8-bit signed integer | VT_UI1
char | 16-bit unsigned integer | VT_I2
short | 16-bit signed integer | VT_I2
int | 32-bit signed integer | VT_I4
long | 64-bit signed integer | N/A
float | 32-bit float | VT_R4
double | 64-bit float | VT_R8
java.lang.String | BSTR | VT_BSTR
com.ms.com.Variant | VARIANT | VT_VARIANT
StructWrapperType | StructType * | VT_UNKNOWN
java.lang.Object | IUnknown * | VT_UNKNOWN
InterfaceWrapperType | InterfaceType * | VT_UNKNOWN

Note All types are taken statically from the method signature (that is, compile-time types). Actual run-time types are not used. StructWrapperType represents a generic JCDW type with corresponding native type StructType, while InterfaceWrapperType represents a generic COM interface wrapper type for the COM interface InterfaceType.

Attributes

COM_GuidPool | Class scope.
COM_MethodPool | Class scope.

Related Directives

@com.method

Support for iid_is and size_is

To express iid_is and size_is from an @com directive, declare methods as follows:

/** @com.method(...)
@com.parameters([in,type=PTR] riid, [customMarshal="com.ms.com.IIDIsMarshaler",type=CUSTOM] return) */
public IUnknown BindToObject(_Guid riid);

/** @com.method(...)
@com.parameters([in,type=U4] length, [in,out,customMarshal="com.ms.com.SizeIsMarshaler",type=CUSTOM] items) */
public void GetItems(int length, int[] items);

See the sample in Samples\com\iidis_sizeis for more information.

Examples

/** @com.method(vtoffset=30, dispid=301, type=METHOD, name="ClientToWindow", addFlagsVtable=4)
    @com.parameters([in,out,size=1,elementType=I4,type=ARRAY] pcx, [in,out,size=1,elementType=I4,type=ARRAY] pcy) */
public void ClientToWindow(int[] pcx, int[] pcy);

/** @com.method(vtoffset=32, dispid=303, type=METHOD, name="GetProperty")
    @com.parameters([in,type=STRING] Property, [type=VARIANT] return) */
public com.ms.com.Variant GetProperty(java.lang.String Property);

/** @com.method(vtoffset=12, dispid=200, type=PROPGET, name="Application")
    @com.parameters([iid=00020400-0000-0000-C000-000000000046,thread=AUTO,type=DISPATCH] return) */
public java.lang.Object getApplication();


@com.register

The information provided by this directive is used by Microsoft® Visual J++® (specifically, the vjreg tool) to register the compiled Java class as a COM object in the system registry. It contains all the information necessary to make these registry entries. The Microsoft VM does not use any of the class attributes at runtime.

An @com.register directive must be specified if an @com.transaction or @com.typeinfo directive is present.

Syntax

@com.register(clsid=GUID, [typelib=GUID], [version=string], [description=string], [progid=string])

Parameters

clsid=GUID | The CLSID for the COM object that this class represents.
typelib=GUID | The GUID of the type library for this Java-implemented COM object.
version=string Example: version="3.2" | The version of the Java-implemented object, in the form "<major version>, <minor version>", where both <major version> and <minor version> are 16-bit integers.
description=string | Some descriptive text about the COM object.
progid=string | This string will be registered in the ProgID section of the registry for creation of this COM object with the specified friendly name.

Attributes

COM_Register Class scope.

Related Directives

@com.transaction

@com.typeinfo

Examples

The following example shows some simple registration information for a Java/COM object with the given CLSID and type library GUID.

/** @com.register(clsid=8856F961-340A-11D0-A96B-00C04FD705A2, typelib=EAB22AC0-30C1-11CF-A7EB-0000C05BAE0B, version="1.1", description="WebBrowser Control", progid="Shell.Explorer.2")*/
public class WebBrowser implements com.ms.com.IUnknown { }


@com.struct

See @dll.struct.


@com.structmap

See @dll.structmap.


@com.transaction

The @com.transaction directive specifies the transaction requirements for this Java/COM object when it is running within the Microsoft® Transaction Server (MTS). This attribute is equivalent to using @com.typeinfo({<GUID for required | requiresNew | supported | notSupported>}=0).

An @com.register directive must be specified if an @com.transaction directive is present.

The related GUIDs are shown in the following table.

17093CC5-9BD2-11CF-AA4F-304BF89C0001 | required
17093CC6-9BD2-11CF-AA4F-304BF89C0001 | notSupported
17093CC7-9BD2-11CF-AA4F-304BF89C0001 | requiresNew
17093CC8-9BD2-11CF-AA4F-304BF89C0001 | supported

Syntax

@com.transaction(required | requiresNew | supported | notSupported)

Parameters

required | Specifies that this Java/COM object requires a transaction when it is operating in MTS. If it is created within the scope of an existing transaction, the existing transaction is used. If there is no existing transaction, a new one is created. Dependency: Cannot be used with requiresNew, notSupported, or supported.
requiresNew | Specifies that this Java/COM object requires a new transaction to be created for it, regardless of whether one already exists. Dependency: Cannot be used with required, notSupported, or supported.
supported | Specifies that this Java/COM object will use a transaction if one has already been created, but that a new transaction should not be created if one does not already exist. Dependency: Cannot be used with requiresNew, notSupported, or required.
notSupported | Specifies that this Java/COM object does not support transactions. Dependency: Cannot be used with requiresNew, required, or supported.

Attributes

COM_CustData Class scope.

Related Directives

@com.typeinfo

@com.register

Examples

A COM object is marked with the @com.transaction directive as follows:

/** @com.transaction(required) */
public class MyCOMObject { }

The equivalent specification with @com.typeinfo is

/** @com.typeinfo({17093CC5-9BD2-11CF-AA4F-304BF89C0001}=0) */
public class MyCOMObject { }


@com.typeinfo

The @com.typeinfo directive is used on a Java-implemented COM class and specifies custom data to be exposed for this class by the Microsoft virtual machine. This custom data is available by way of ITypeLib::GetCustData on type libraries obtained from the Microsoft VM for the class that declares this directive. You may declare more than one of these directives for a class.

If an @com.typeinfo directive is present, an @com.register directive must be specified.

Syntax

@com.typeinfo({GUID}=number | string)

or

@com.typeinfo(attrid=GUID, value=number | string)

Parameters

attrid=GUID | The GUID for the custom data.
value= number | string | A number or string representing the custom data to associate with the given GUID.

Attributes

COM_CustData Class scope.

Related Directives

@com.register

@com.transaction

Examples

The following adds some Unicode data keyed by the specified GUID.

/** @com.typeinfo(attrid=FF0FFCC7-9BD2-1FFF-AA4F-3FFF89C0001, value="\u1234\u7689\u00AF") */
public class MyCOMObject { }

This is equivalent to:

/** @com.typeinfo({FF0FFCC7-9BD2-1FFF-AA4F-3FFF89C0001}="\u1234\u7689\u00AF") */
public class MyCOMObject { }


@dll.import

The @dll.import directive maps a C function from the specified DLL to a Java method. If the entrypoint parameter is not used, the Microsoft virtual machine assumes that the Java method name is exactly the same as the exported DLL function name (case-sensitive). The Microsoft VM will make various attempts to find the method, such as by appending A (for ANSI) or W (for Unicode).

If this directive is used at the class level, every method prototype specified with the native keyword will, by default, have the same @dll.import tag. However, a method can override the global @dll.import tag by specifying its own @dll.import directive. The global @dll.import is not required if individual @dll.import directives are used for every native J/Direct method specified in the Java class.

You can specify the DLL to use for static native methods in a whole class by putting the directive immediately above the class declaration. Alternatively, you can specify which DLL to use on a method-by-method basis, as shown in the J/Direct Message Box example. The @dll.import directive also has parameters to allow you to link to ordinals, use an alias for the function name, and modify the calling convention.

The Java data types that you choose for the parameters and for the return value of the method should be types that map to the types of the DLL function parameters and return value. For more information about how Java data types map to native types, see How Data Types are Marshaled.

The directive parameters ansi, auto, unicode, and ole determine the native character encoding (ANSI or Unicode) that the Microsoft VM will use when converting Java string and character parameters to their native counterparts. In operating systems that use ANSI as their base character encoding, such as Microsoft® Windows® 95 or Microsoft® Windows® 98, ANSI strings and characters are generally required in structures and parameters. In Unicode-based operating systems, such as Microsoft® Windows NT® and Microsoft® Windows® 2000, Unicode strings and characters are generally desirable. The auto parameter causes the Microsoft VM to choose the correct encoding type at runtime, depending on the base character encoding of the operating system that the class is used on. If ole is specified, the Unicode character encoding will be used. The auto parameter also determines how methods will be linked by adding the appropriate A (ANSI) or W (Unicode) suffix. See Calling Different Versions of DLL Functions for details.

At most one of the directive parameters ansi, auto, unicode, ole, and raw can be specified in a given @dll.import directive. If none are specified at the method level, the value specified at the class level is used. If none are specified at the class level, the default is ansi.

Syntax

@dll.import([string], [entrypoint=string], [ansi | auto | unicode | ole | raw], [setLastError], [linktype=integer])

Parameters

string This parameter is required. | Indicates the DLL file name that the function is imported from. Don't include the .dll file extension. The DLL to be loaded must be in the system path when the method is invoked. This directive parameter must be declared at the class or method level.
entrypoint= string | Specifies the exported DLL function name. The Java method is mapped to this method in the DLL. A secondary form can be used to link to DLL exports by ordinal. In this case, the string must have the form "#integer", where the integer is a 16-bit decimal representation of the ordinal number.
ansi | Specifies that the VM should use an ANSI character encoding when converting Java string and character parameters to their native counterparts. Dependency: Cannot be used with auto, unicode, ole, or raw.
auto | Specifies that the character encoding that the Microsoft VM should use when converting Java string and character parameters to their native counterparts should be determined at runtime. Specifically, the base character encoding of the operating system will be used. Dependency: Cannot be used with ansi, unicode, ole, or raw.
unicode | Specifies that the Microsoft VM should use the Unicode character encoding when converting Java string and character parameters to their native counterparts. Dependency: Cannot be used with ansi, auto, ole, or raw.
ole | Specifies that the method will be mapped to an OLE-compatible native function. The native function must return an HRESULT value, and all string and character parameters will be in Unicode. Generally, the last parameter is a return value. This causes the Java method to throw a com.ms.comComFailException (if there is a non-zero HRESULT) rather than return an HRESULT from the Java method. Because the last function parameter is a pointer to the location where the result of the function call should be placed, the return value from the Java method can generally be the last parameter to the native function. This parameter is used to make COM function mappings (and other functions that follow the OLE calling convention) more similar to Java methods. Strings or characters are mapped to Unicode native values. Dependency: Cannot be used with ansi, auto, unicode, or raw.
raw | Specifies that the method is a standard Java native method (that is, one using RNI or JNI) and should be marshaled accordingly. Dependency: Cannot be used with ansi, auto, unicode, or ole.
setLastError | Indicates that the imported function provides error information to the application through the Win32 GetLastError function. Because the VM is running this method for the Java application, manually calling GetLastError from Java may return the last error the Microsoft VM caused rather than the error from the J/Direct function call. Specifying setLastError in the @dll.import directive causes the VM to hold the error code from the function call. The client can retrieve the error code by using com.ms.dll.DllLib.getLastWin32Error.
linktype=integer | The integer value can be one of NLT_RAW, NLT_INHERIT, NLT_ANSI, NLT_UNICODE, NLT_DUAL, or NLT_OLE and becomes the value of the m_LinkType field in the NAT_L attribute. See the linktype values table for possible values of this field. This is a more extensible way of setting the link type, as compared with ansi, auto, unicode, ole, and raw. Dependency: Cannot be used with ansi, auto, unicode, ole, or raw.

Attributes

NAT_L Method scope.

Related Directives

@dll.structmap (and @com.structmap)

@dll.struct (and @com.struct)

See Also

Specifying @dll.import for an Entire Class

Examples

The @dll.import directive must precede a non-synchronized, static native method, or the class keyword. A @dll.import directive that precedes the class keyword is interpreted as a global @dll.import. It specifies default values for any methods declared by the class.

/** @dll.import(auto, "KERNEL32") */
public static native void DebugBreak();

The @dll.import tag shown here is applied to an entire class.

/** @dll.import("advapi32", setLastError) */
public class Advapi32{
  public static native boolean StartServiceCtrlDispatcher(...);
  public static native boolean ReportEvent(...);
}

Use the ole parameter to make imported functions more Java-like by mapping the last C parameter to the Java return value. The Microsoft VM automatically throws the HRESULT error codes as ComFailExceptions.

The C function prototype:

HRESULT CoGetMalloc(DWORD dwMemContext, ImMalloc **ppMalloc);

The Java method:

/** @dll.import("ole32") */
public static native IMalloc CoGetMalloc( int dwMemContext );

The following table presents the @dll.import syntax for several situations.

Situation Required syntax Remarks
Calling Win 32 DLLs /**@dll.import
("LibName")*/
Calling OLE APIs /**@dll.import
("LibName",ole)*/
Aliasing /**@dll.import
("LibName", entrypoint=
"DLLFunctionName")*/ 		In the method declaration, use the Java name that you selected.
Linking by Ordinal /**@dll.import
("LibName",
entrypoint="#ordinal")*/ 		"#ordinal" is a 16-bit decimal integer indicating the DLL function you are importing.


@dll.struct

The @dll.struct directive is specified at the class level and marks the class declaration as equivalent to a C structure definition. Instances of the class can then be passed through J/Direct and COM method calls that require a C structure with the same composition.

Note The syntax for @dll.struct and @com.struct is nearly identical. The only difference between them is the way that some fields are marshaled between Java and native code.

Within the class declaration, you need to supply fields whose Java types map to the types of the fields in the native structure in the order they occur in the native structure. For information about choosing the data types of the fields, see Correspondence Between Types Inside Structures.

All strings and characters in a class with an @com.struct directive will be converted to and from their native counterparts using the Unicode character encoding.

A Java-callable data wrapper (JCDW) is a Java object exposed by the Microsoft VM for external data (such as a C struct). Values are automatically propagated between fields in the Java object and fields in the external structure. You can explicitly cause propagation of the fields by calling com.ms.dll.DllLib.propagateStructFields.

Note When passing an array of JCDW's between COM/Microsoft® Win32® APIs and Java, in either direction, if the JCDW contains complex types such as Strings, then these complex types may not be properly propagated to memory that is not garbage collected. For normal JCDW parameters, the marshaling engine always attempts to propagate structs, but this is not true for the case of marshaling arrays.

The directive parameters ansi, auto, and unicode, used with the @dll.struct directive, determine the native character encoding (ANSI or Unicode) that the Microsoft VM will use when converting Java string and character fields to their native counterparts. In operating systems that use ANSI as their base character encoding, such as Microsoft® Windows® 95 or Windows® 98, ANSI strings and characters are generally required in structures. In Unicode-based operating systems, such as Microsoft® Windows NT® and Microsoft® Windows® 2000, Unicode strings and characters are generally desirable. The auto parameter causes the VM to choose the correct encoding type at runtime, depending on the base character encoding of the operating system that the class is used on.

At most one of the directive parameters ansi, auto, and unicode can be specified in a given @dll.struct directive. If none are specified, the default is ansi.

Syntax

@dll.struct([ansi | unicode | auto], [pack=1 | 2 | 4 | 8], [noAutoOffset], [safe], [safeAddFlags=integer])

Parameters

ansi | Specifies that the VM should use an ANSI character encoding when converting Java string and character fields to and from their native counterparts. Dependency: Cannot be used with auto or unicode. Not a valid parameter for the @com.struct directive.
unicode | Specifies that the VM should use the Unicode character encoding when converting Java string and character fields to and from their native counterparts. Dependency: Cannot be used with ansi or auto. Not a valid parameter for the @com.struct directive.
auto | Specifies that the character encoding that the VM should use when converting Java string and character fields to and from their native counterparts should be determined at runtime. Specifically, the base character encoding of the operating system will be used. Dependency: Cannot be used with ansi or unicode. Not a valid parameter for the @com.struct directive.
pack=1 | 2 | 4 | 8 | Specifies the packing alignment of the structure, which determines how fields will be aligned in memory. Typically, the packing alignment for a structure is specified in C by using the #pragma pack(n) syntax. The value given for the Java pack parameter should be the same as that used for the corresponding C structure. The default value is 8, which is the default Microsoft® Visual C++® packing alignment. For more information on setting the packing size, see Structure Packing. Dependency: If the noAutoOffset parameter is specified, the Microsoft VM ignores this parameter.
noAutoOffset | Specifies that the offset of each field in the structure will be explicitly defined. Each field in the class must have an @dll.structmap directive that specifies the field’s offset via the offset directive parameter. If this parameter is not specified, the Microsoft VM automatically calculates offsets for each field in the structure. In this case, the default packing size is 8 bytes, but can be modified by the pack parameter. Dependency: @dll.structmap
safe | Specifies that the structure may be used safely by untrusted classes. A COM_Safety attribute is attached to the class.
safeAddFlags=integer | Specifies a word of information to be put in the COM_Safety attribute. Note The Microsoft VM currently ignores this data when reading the COM_Safety attribute.

Attributes

COM_Class_Type | Class scope.
COM_MapsTo | Field scope.
COM_Safety | Class scope.

Related Directives

@dll.structmap (and @com.structmap)

See Also

Calling Different Versions of DLL Functions

Examples

The following table describes the syntax for several situations that you might use the @dll.struct directive in.

Situation | Required Syntax | Explanation
Declare a structure. | /**@dll.struct()*/ | When you do not specify ansi, unicode, or auto, character and string fields will be converted to their native counterparts using an ANSI character encoding.
Set a structure's packing size. | /**@dll.struct (pack=integer)*/ | integer can be 1, 2, 4, or 8.
Declare a structure that has a field of type char. | /**@dll.struct(ansi)*/ | The character field represents an ANSI character.
Declare a structure with a field of type string and set the packing size. | /**@dll.struct (unicode, pack=integer)*/ | The string fields will be in Unicode format, and the packing size is set to 1, 2, 4, or 8, depending on the value of integer.

When used without parameters, @dll.struct defaults to auto, and assumes that pack=8, that it is unsafe to link to this class from untrusted classes, and that field offsets are automatically generated by the Microsoft VM. An example @dll.struct directive using no parameters has the following syntax:

/** @dll.struct() */
public class MyStruct{
  public int x;
  public int y;
}


@dll.structmap

The @dll.structmap directive is applied to a field in an @dll.struct class to specify how a field is exposed to native memory. This directive must be used for each field if the structure was declared using @dll.struct(noAutoOffset), which requires the offset keyword in each @dll.structmap directive. This directive can also be used to override the default field mappings in other struct classes.

Note When passing an array of JCDW's between COM/Microsoft® Win32® APIs and Java, in either direction, if the JCDW contains complex types such as Strings, then these complex types may not be properly propagated to memory that is not garbage collected. For normal JCDW parameters, the marshaling engine always attempts to propagate structs, but this is not true for the case of marshaling arrays.

Static fields in a Java class with an @dll.struct directive are not considered part of the class’ corresponding native structure. Therefore, such fields can hold information that is not present in the native structure.

Note There are currently no differences between @dll.structmap and @com.structmap directives.

Syntax

@dll.structmap([[[offset=integer | long], [type=BOOLEAN | CURRENCY | CUSTOM | CUSTOMBYVAL | DATE | DISPATCH | FIXEDARRAY | I1 | I2 | I4 | I8 | OBJECT | PTR | R4 | R8 | STRING | TCHAR | TCHAR[integer] | U1 | U2 | U4 | U8], [iid=GUID], [thread=AUTO | NO], [size=integer | long], [customMarshal=string], [customMarshalFlags=integer], [addFlags=integer]]] [string])

Parameters

offset=integer | long

Example: offset=4

 Specifies the byte offset of the starting byte in this field.

Dependency: Should be used if noAutoOffset is declared in the @dll.struct or @com.struct directive at class level.
type=BOOLEAN | CURRENCY | CUSTOM | CUSTOMBYVAL | DATE | DISPATCH | FIXEDARRAY | I1 | I2 | I4 | I8 | OBJECT | PTR | R4 | R8 | STRING | TCHAR | TCHAR[integer] | U1 | U2 | U4 | U8 Defines the native type of the Java field. See Type Values for @com.parameters and @dll.structmap for more information.

If this directive parameter is not declared, a default native type is used, according to the Default Native Types for Java Parameters table. Fields of struct type are special cases. These are Java-Callable Data Wrappers (JCDWs), those classes that declare an @com.struct or @dll.struct directive. In such cases, the native type is an embedded struct. There is no way to declare this mapping using the type parameter.

Dependencies:

CUSTOM and CUSTOMBYVAL: The customMarshal directive parameter must be declared.

DISPATCH and OBJECT: Secondary information may be specified using the iid directive parameter.

FIXEDARRAY: Secondary information may be specified using the size directive parameter.

Note By-value structures containing any primitive types with @com.stuctmap [(type=FIXEDARRAY size=n)] are not automatically propagated. Call com.ms.com.DllLib.propagateStructFields(MyStruct, false) before passing values to the native side.

SAFEARRAY: The vt directive parameter must be specified.

TCHAR and TCHAR[integer]: Secondary information may be specified using the ansi, unicode, and auto directive parameters in the @dll.struct directive for the class containing this field.
iid=GUID

Example: iid=0000000F-0000-0000-C000-000000000046

 Specifies the interface identifier (IID) of this field. The Microsoft VM ensures that only interfaces of this type are given to COM clients and servers.

Dependency: Valid only for Java fields declaring type=OBJECT or type=DISPATCH.

Default: IID_IUnknown.
thread=AUTO | NO Specifies the marshaling behavior to be applied to the COM object field. If AUTO is specified, the Microsoft VM automatically marshals any calls from Java on this object to the thread that the object was created in. This is the safest option, and the default.

If NO is specified, the Microsoft VM assumes that the object is callable on any Java thread.

Dependency: Valid only for Java fields declaring type=DISPATCH or type=OBJECT.

Default: AUTO.
size=integer | long

Example: size=3

 Specifies the number of elements in an array.

Dependency: Valid only for Java fields declaring type=FIXEDARRAY.

Default: 1.
customMarshal=string

Example:
customMarshal=
"com.ms.com.UniStringMarshaller"

 Specifies the name of a class. This class will be asked to marshal the field.

Dependency: Valid only for Java fields declaring type=CUSTOM or type=CUSTOMBYVAL.
customMarshalFlags=integer Specifies bits available to the custom marshaler when invoked. Must be in the range 0 to 3. These bits move into the high two bits of the MCMapsTo.typedesc.Flags field in the COM_MapsTo attribute generated for the field.

Dependency: Valid only for Java fields declaring type=CUSTOM or type=CUSTOMBYVAL.
addFlags=integer A low-level parameter that allows direct modification of created class attributes. Specifies a word of information to be put in the COM_Safety attribute.

A low-level parameter that specifies a byte value in the range 0 to 255 that is moved into the MCMapsTo.typedesc.Flags field in the COM_MapsTo attribute generated for the field.
string The name of the Java field. The preceding directive parameters apply to this field in the class.

Dependency: The field name specified must be that of the field immediately following the directive.

Attributes

COM_MapsTo Field scope.

Related Directives

@dll.struct (and @com.struct)

@dll.structmap (and @com.structmap)

See Also

Fixed-size Strings Embedded within Structures

Fixed-Size Scalar Arrays Embedded within Structures

Example

Situation Required syntax Explanation
Structure that contains a fixed-size field.
/**@dll.structmap
([type=TCHAR[size]])*/
 size is a decimal integer that indicates the number of characters in the string, including space for the null terminator.
Structure that contains a fixed-size array.
/**@dll.structmap
([type=FIXEDARRAY,
size=n])*/
 n is a decimal integer that represents the number of elements in the array.

The following structure uses the noAutoOffset directive parameter and specifies the offset for each field using the @com.structmap directive. The safe parameter indicates that this structure is safe to use by untrusted classes. The unicode parameter indicates that any strings or characters in the structure should be represented as native Unicode characters.

/** @com.struct(noAutoOffset, safe, unicode) */
public final class MULTI_QI {
  /** @com.structmap([offset=0, type=PTR] pIID) */
  public com.ms.com._Guid pIID;

  /** @com.structmap([offset=4, iid=00000000-0000-0000-C000000000000046, thread=AUTO, type=OBJECT] pItf) */
  public com.ms.com.IUnknown pItf;

  /** @com.structmap([offset=8, type=U4] hr) */
  public int hr;
}

The following example illustrates how a custom marshaler can be specified using the @dll.structmap directive.

/** @dll.struct() */
public final class StringStruct {
  /** @dll.structmap([type=CUSTOM, customMarshal="com.ms.com.UniStringMarshaller"]) */
  String strUnicode;

  /** @dll.structmap([type=CUSTOM, customMarshal="com.ms.com.AnsiStringMarshaller"]) */
  String strAnsi;

  /** @dll.structmap([type=CUSTOM, customMarshal="com.ms.dll.StringMarshaler"]) */
  String strAuto;
}


@security

The @security directive is used to modify class link-time access check behavior and stack crawl behavior for J/Direct method calls.

Syntax

@security([checkClassLinking=on | off | auto], [checkDllCalls=on | off])

Parameters

checkClassLinking=on | off | auto | Specifies whether the VM should allow only trusted classes to use this class (on), or whether all Java class can use this class (off). Default is auto, which specifies normal Java access checks (for example, only trusted classes may use other trusted classes).
checkDllCalls=on | off | If on is specified, the Microsoft VM performs a security stack crawl when a J/Direct method is invoked. If the classes on the stack are untrusted and permissions have not been asserted, the J/Direct call fails with a SecurityException. off disables the requirement that all callers in the stack chain be fully trusted. Default is on.

Attributes

LinkSafe | Class scope.
LinkUnsafe | Class scope.
NAT_L_DCTS | Class scope.

Related Directives

@dll.import

Example

The following code disables the requirement that all callers in the stack chain be fully trusted.

/** @security(checkDllCalls=off) */
public class SomeStruct { }

The following code will mark the class as accessible to only trusted classes.

/** @security(checkClassLinking=on) */
public class SomeStruct { }


Attributes Reference

To correctly expose Java objects to COM and COM objects to Java, the virtual machine uses attributes in the Java class file that give information about COM parameter types, COM method vtable offsets, COM struct field offsets, and so on.

The Microsoft SDK for Java contains the header file comattr.h, which defines the layouts and valid values of the attributes. This reference describes the class file attributes that must be in any class file that invokes a COM object from Java or exposes a Java object as a COM object.

This reference contains the following topics.

ActualAccessFlags implements the protection rules for inner and nested classes.

COM_Class_Type pertains to the class level and denotes the implementation language. It indicates that a Java class is to be used as a native structure, COM interface, or COM object.

COM_CustData pertains to the class level. It stores type library custom data (CUSTDATA) for a Java class.

COM_ExposedAs_Group pertains to the method level. It exposes a Java method to COM and prescribes the external interface (vtable or dispatch) of a COM-Callable wrapper created for a Java object.

COM_GuidPool pertains to the class level. It stores the class IDs (CLSIDs) and interface IDs (IIDs) that are referenced by index from other attributes in the class.

COM_MapsTo pertains to the field level. It exposes external data to Java, providing type and layout information about each field in a COM class.

COM_MethodPool pertains to the class level. It stores distilled type library information about the COM methods that are invoked and implemented by the Java methods in the Java class file.

COM_ProxiesTo pertains to the method level. It exposes a COM method to Java.

COM_Register stores data for registering a class as a COM coclass.

COM_Safety indicates that a COM class can safely be used by an untrusted class.

Delegate specifies that a class is a delegate type and will be used for method invocations, or that a method is an invocation method.

JITMeNot specifies that a method or the class's static initializer should not be JIT-compiled.

LinkSafe specifies that a class is accessible to untrusted classes.

LinkUnsafe specifies that a class is not accessible to untrusted classes.

MulticastDelegate specifies that a method is to be treated as a multicast invocation method by the Microsoft VM.

NAT_L specifies the DLL name and DLL entry point (method) name associated with a J/Direct Java method.

NAT_L_DCTS specifies that no extra call-time security checks are required when a J/Direct method is called.

SecurityAPI specifies that a method requires additional space in its stack frame. The extra frame space is used to store security information at runtime.

SourceDir specifies the source directory of the Java source file for this class.

The attributes in the following table are for backward compatibility with older Java compilers, and are not documented here.

Old classes, methods, and fields | New attributes
Microsoft_COM_Class_Type (Class) | COM_Class_Type
Microsoft_COM_ExposedAs_Group (Method) | COM_ExposedAs_Group
Microsoft_COM_GuidPool (Class) | COM_GuidPool
Microsoft_COM_MapsTo (Field) | COM_MapsTo
Microsoft_COM_MethodPool (Class) | COM_MethodPool
Microsoft_COM_ProxiesTo (Method) | COM_ProxiesTo
Microsoft_COM_Safety (Class) | COM_Safety

Note that the attributes specify detail at the method level whenever possible. That is, while you customarily think of interfaces having IIDs, the attribute specification specifies an iid for each method, so that one Java interface could conceivably proxy to methods on multiple IIDs.

Unless otherwise noted, successive items in an attribute structure are stored sequentially in a Java class file. There is no padding between or after attribute fields. Any required padding will be declared explicitly as unused fields. Data items that use multiple bytes are always stored in big-endian order (high bytes first) unless otherwise specified. Several data types are used in a Java class file. These data types include u1, u2, and u4, which represent an unsigned one-, two-, or four-byte quantity. A standard 6-byte attribute_info structure (the header for every attribute) exists for all Java class attributes.

The following table shows C/C++ data types that are used to describe attributes.

C/C++ data type | Java data type | Description and representation
BYTE | u1 | One unsigned byte.
WORD | u2 | Two unsigned bytes (big endian).
DWORD | u4 | Four unsigned bytes (big endian).

In terms of alignment, there is no implicit padding between structure fields or after the last structure field.

All unused bits in Flag fields must be zero.

Several of these attributes use the equivalent of C/C++ structures or unions. These are as follows.

Structures Used by Attributes | Applies to | Comments
MCCustomMethod | COM_MethodPool | Used to describe a method that is custom-marshaled.
MCSpecialArgumentEntry | COM_MethodPool | Used to describe the arguments to a custom-marshaled method.
MCDispMethod | COM_MethodPool | Used to describe a dispatch method.
MCExposedAs | COM_ExposedAs_Group | Used to expose a Java method as a COM method.
MCFuncDesc | COM_MethodPool | A general structure used to describe any method type.
MCTypeDesc | COM_MapsTo, COM_MethodPool | Used to describe the type of a single field in a class or a single argument and return type of a vtable method.
MCVarTypeDesc | COM_MethodPool | Used to describe the type of a single parameter or return value to an IDispatch method.
MCVtblMethod | COM_MethodPool | A structure used to describe a vtable method.

See Also

Integrating Java and COM (programmer's guide)
Using COM Objects from Java (white paper)
Integrating Java and COM (white paper)


ActualAccessFlags

The ActualAccessFlags attribute applies to a field or method. It implements protection rules for inner and nested classes. This attribute specifies the access flags that the field or method was declared with.

The ActualAccessFlags attribute has the following layout:

ActualAccessFlags_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 access_flags;
}

The items of the ActualAccessFlags structure are as follows:

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "ActualAccessFlags".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and must be two.

access_flags

This value indicates a mask of modifiers used to describe the access permission flags that the field or method was declared with.

Remarks

This attribute is generated and used by the Microsoft® Visual J++® compiler. It is used where a method or field is declared as private and is accessed from a different class. This can occur in nested classes when one class is contained in another or both the classes are contained inside a common class.

The Microsoft VM does not currently use this attribute.


COM_Class_Type

The COM_Class_Type attribute marks a class as a Java-Callable Wrapper (JCW) or a Java-Callable Data Wrapper (JCDW). For JCWs, the CLSIDIndex field specifies the CLSID of the associated COM component. For JCDWs, the packing field defines the alignment requirement of the associated native structure.

Attribute Level | Generated By Directives
Class | @com.struct @dll.struct @com.class

COM_Class_Type_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 Flags;
    u2 Classtype;
    union {
        u2 CLSIDIndex;
        {   u1 packing;
            u1 reserved1;
        } jcdw;
    }
}

The C structure MCClassType, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

Restrictions

If the class type is MCCTCT_JCW, the access flags for the class must be a subset of ACC_PUBLIC, ACC_FINAL, or ACC_ABSTRACT.

If the class type is MCCTCT_JCDW, the access flags for the class must be a subset of ACC_PUBLIC or ACC_FINAL (required). The class's superclass must be java.lang.Object or a JCDW class.

If the class type is MCCTCT_JCDW, all fields defined by the class must have a COM_MapsTo attribute.

Attribute Elements

attribute_name_index

This value must be a valid index into the constant pool table. The constant pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "COM_Class_Type".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and must be six.

Flags

CCTF_NODYNAMICIFCCASTS

This bit is used only for JCWs. If on, instances of this class can be legally cast only to interfaces explicitly implemented by either the instance's class or one of its ancestors. If off, instances of this class can be cast at runtime to any interface containing a methodpool item, provided that the underlying COM object returns a valid interface for the IID of the interface.

CCTF_CHARSIZEMASK

For JCWs, these bits must be zero. For JCDWs, these bits indicate ansi (CCTF_CHARSIZEANSI), unicode (CCTF_CHARSIZEUNICODE), or dual (CCTF_CHARSIZEDUAL) string and character array types.

ClassType

The only legal values are MCCTCT_JCW and MCCTCT_JCDW. The class type is determined as follows:

  • If neither the class nor any of its ancestors has a ClassType attribute, the type is "pure."

  • If the class has no ClassType attribute but a single ancestor (which must be a direct descendant of java.lang.Object) has a JCW ClassType attribute, the type is "Derived from JCW."

  • If the class has the ClassType "MCCTCT_JCW", the class type is "JCW."

  • If the class has the ClassType "MCCTCT_JCDW", the class type is "JCDW."

CLSIDIndex

If ClassType is not MCCTCT_JCW, CLSIDIndex must be 0xffff.

If the ClassType is MCCTCT_JCW and the CLSIDIndex is not 0xffff, CLSIDIndex must indicate a valid index into the GuidPool. The GUID corresponding to this index will be used as the CLSID of the COM object to load when an instance of this class is created using the "new" operator.

packing

When used in the context of the @com.struct directive, this value indicates the value of the pack= parameter in the directive, which may be set to 1, 2, 4 or 8. For backward compatibility, a value of 0xFF defaults to 4. This parameter indicates the packing alignment for structure members of this class (see "Padding and Alignment of Structure Members" in the MSDN™ Library for more information). For Java/COM, packing defaults to 8.

reserved1

When used in the context of the @com.struct directive, this value is reserved and must be set to 0xFF.


COM_CustData

This attribute exposes type library CUSTDATA elements. Callers may query a class's type library at runtime (such as through IProvideClassInfo) for these attributes using methods like ITypeInfo2::GetCustData.

Attribute Level | Generated By Directives
Class | @com.transaction @com.typeinfo

COM_CustData_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 nCustDatas;
    {   u2 GuidIndex;
        u2 DataIndex;
    } aCustData[nCustDatas];
}

The C structure MCCustData, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

The @com.transaction directive that generates this attribute has the following syntax:

/** @com.transaction(required | requiresNew | supported | notSupported) */

These four possible parameters get converted to well-known GUIDs (see the following table).

The @com.typeinfo directive indicates a GUID and its data value where the value can be an int, long, float, double, or string data type. Raw data is expressed using Unicode escape sequences. This directive can exist in two syntax forms:

/** @com.typeinfo(attrid=GUID, value=number | string) */

/** @com.typeinfo({GUID}=number | string) */

For example, the following are valid directives:

/** @com.typeinfo(attrid=17093CC7-9BD2-11CF-AA4F-304BF89C0001,
value="\u1234\u7689\u00AF")*/

/** @com.typeinfo({17093CC7-9BD2-11CF-AA4F-304BF89C0001}=0) */

The parameter options for the @com.transaction directive get converted to the well-known GUIDs as shown in the following table.

Parameter to @com.transaction | Well-Known GUID | Comments
requiresNew | 17093CC7-9BD2-11cf-AA4F-304BF89C0001 | TLBATTR_TRANS_REQNEW
required | 17093CC5-9BD2-11cf-AA4F-304BF89C0001 | TLBATTR_TRANS_required
supported | 17093CC8-9BD2-11cf-AA4F-304BF89C0001 | TLBATTR_TRANS_supported
notSupported | 17093CC6-9BD2-11cf-AA4F-304BF89C0001 | TLBATTR_TRANS_NOTSUPP

The effect of the @com.transaction directive with one of these parameters is equivalent to an @com.typeinfo directive with these well-known GUIDs entered. For example, the following two directives create identical COM_CustData attribute items:

/** @com.transaction(requiresNew) */
/** @com.typeinfo({17093CC7-9BD2-11cf-AA4F-304BF89C0001}=0) */

An @com.register directive must be specified if an @com.transaction or @com.typeinfo directive is present.

Restrictions

The class access flags must be a subset of ACC_PUBLIC, ACC_FINAL, ACC_INTERFACE, or ACC_ABSTRACT.

Attribute Elements

attribute_name_index

This value must be a valid index into the constant pool table. The constant pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "COM_CustData".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and varies depending on the value of nCustDatas.

aCustData[]

GuidIndex

Index into the COM_GuidPool attribute table. The value indexed in this table represents the GUID identity for this custom data element.

DataIndex

Index into this class's constant_pool. Only CP_Utf8 and CP_Integer constant pool entries are currently supported.

nCustDatas

The number of aCustData items defined in this table.


COM_ExposedAs_Group

The ExposedAs_Group attribute is a collection of ExposedAs structures, each of which causes the Java method to be exposed as a COM method. It exposes a Java method to COM and prescribes the external interface (vtable or dispatch) of a COM-Callable Wrapper created for a Java object.

Attribute Level | Generated By Directives
Method | @com.method

COM_ExposedAs_Group_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 Flags;
    u2 nExposedAs;
    {   u2 Flags;
        u2 MethodPoolIndex;
    } aExposedAs[nExposedAs];
}

The C structures MCExposedAsGroup and MCExposedAs, declared in comattr.h, define the layout of this attribute for use in C/C++ programs.

Restrictions

The access flags for the method must be a subset of ACC_PUBLIC, ACC_PRIVATE, ACC_PROTECTED, ACC_FINAL, ACC_SYNCHRONIZED, or ACC_NATIVE ACC_ABSTRACT.

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "COM_ExposedAs_Group".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and varies depending on the value of nExposedAs.

Flags

Must be 0 (zero).

nExposedAs

The number of ExposedAs attributes that follow.

Flags

This value is not currently used and must be 0 (zero).

MethodPoolIndex

This value must be a valid index into the method pool (the COM_MethodPool attribute). The method pool entry describes how to expose this Java method to COM.

aExposedAs[]

nExposedAs

The number of aExposedAs attributes that follow.


COM_GuidPool

The COM_GuidPool attribute stores the CLSIDs and IIDs that are referenced by index from the MethodPool. Valid indices range from 0 inclusive to nGuids exclusive. The index 0xffff is reserved to indicate the "null" index. Therefore, the GuidPool can contain a maximum of 65535 GUIDs.

Attribute Level | Generated By Directives
Class | @com.class @com.interface @com.method @com.parameters @com.structmap @dll.structmap when a GUID is specified.

COM_GuidPool_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 nGuids;
    GUID aGuid[nGuids];
}

The C structure MCGuidPool, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

Restrictions

The class access flags must be a subset of ACC_PUBLIC, ACC_FINAL, ACC_INTERFACE, or ACC_ABSTRACT.

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "COM_GuidPool".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and varies depending on the value of nGuids.

nGuids

This value indicates the number of GUIDs defined in this table.

aGuid[]

This array stores the actual GUID representations based on the nGuids item.

nGuids

The number of actual GUID representations in the aGuid array.

A GUID is a 16-byte integer that is subdivided into fields as follows:

GUID {
    u4 Data1;
    u2 Data2;
    u2 Data3;
    u1 Data4[8];
}

Note Each field in a GUID is stored in little endian format in the Java class file. This is an exception from the normal rule that numeric items stored in a Java class file are stored in big endian format.

An example of the @com.class directive that generates a GUID and item data for this attribute has the following syntax:

/** @com.class(clsid=2BEBEC42-6499-11D0-BFFC-00AA003CFDFC) */

The @com.interface directive that generates a GUID and item data for this attribute has the following syntax:

/** @com.interface(iid=GUID, [thread=AUTO | NO, type=DISPATCH | DUAL | VTABLE]) */

The iid parameter is required. Parameters to the @com.interface directive can appear in any order. When the type parameter is not specified, the default value is a vtable interface.

When used without optional parameters, this directive might look like the following:

/** @com.interface(iid=B2CD9D14-BD00-11D0-B5B3-00A0C913D22B) */

When used with optional parameters specified, this directive has the following syntax:

/** @com.interface(iid=B2CD9D14-BD00-11D0-B5B3-00A0C913D22B,
 thread=AUTO, type=DUAL) */

The @com.structmap and @dll.structmap directives use a similar syntax. The @com.structmap and @dll.structmap directives that generate a GUID and item data for this attribute have the following syntax:

/** @dll.structmap([[[offset=integer | long], [type=BOOLEAN | CURRENCY
| CUSTOM | CUSTOMBYVAL | DATE | DISPATCH | FIXEDARRAY | I1 | I2 | I4 | I8
| OBJECT | PTR | R4 | R8 | STRING | TCHAR | TCHAR[integer] | U1 | U2 | U4
| U8], [iid=GUID], [thread=AUTO | NO], [size=integer | long],
[customMarshal=string], [customMarshalFlags=integer],
[addFlags=integer]]] [string]) */

The @com.structmap and @dll.structmap directives have a syntax similar to the @com.parameter directive. Parameters may be specified in any order. The first enclosing brackets are required for the @com.structmap and @dll.structmap directive if any parameters are to be specified. The brackets for the TCHAR type are optional. The iid and thread parameter values for the @com.structmap and @dll.structmap directives can be specified only if the type is OBJECT or DISPATCH.

When used with optional parameters specified, this directive might look like the following:

/** @com.structmap( [offset=4, type=OBJECT,
     iid=2BEBEC42-6499-11D0-BFFC-00AA003CFDFC, thread=NO] ) */

Any of these @com directives that specify a GUID will cause an entry to be created in the COM_GuidPool attribute.


COM_MapsTo

The COM_MapsTo attribute denotes that the data for the field is actually stored in externally allocated memory. This attribute describes how the fields of a JCDW or JCW map to offsets in the underlying data structure.

Attribute Level | Generated By Directives
Field | @com.struct @com.structmap @dll.struct @dll.structmap

COM_MapsTo_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
    u2 Flags;
    u2 wPad;
    u4 dwOffset;
    MCTypeDesc typedesc;
}

The C structures MCMapsTo and MCTypeDesc, declared in comattr.h, define the layout of this attribute for use in C/C++ programs.

Restrictions

The access flags for the field must be a subset of ACC_PUBLIC, ACC_PRIVATE, ACC_PROTECTED, or ACC_FINAL.

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "COM_MapsTo".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and must be 12.

Flags

The Flags for the COM_MapsTo attribute are as follows.

Flag | Meaning
MTF_AUTOOFFSET | If this flag is set, dwOffset must be 0 and the offset will be computed by the Microsoft virtual machine for the hosting platform. This allows the structure definition to move freely between platforms. Every MapsTo in a .class file must use the same setting for MTF_AUTOOFFSET. A current offset is kept while determining the offset of fields. It is initialized to zero.
wPad | Must be 0 (zero).
dwOffset | The offset in bytes within the external data structure. If MTF_AUTOOFFSET is on, this field has no meaning and must be set to 0.
MCTypeDesc typedesc | Describes the native type of the field.

The @com.struct directive that generates this attribute has the following syntax:

/** @com.struct([ansi | unicode | auto], [pack=1 | 2 | 4 | 8],
 [noAutoOffset], [safe], [safeAddFlags=integer]) */

Remarks

The COM_MapsTo attribute uses an MCTypeDesc structure to indicate the type of the field and other attributes. The MCTypeDesc structure does not attempt to describe the type of the corresponding Java data types. This same structure is also used by other attributes (describing parameters and return values for methods, for example) and some values and interpretations are attribute-specific.

The possible values for the Type enumeration applicable to the COM_MapsTo attribute describing a field are shown in the following table.

Type Enumeration | Value | Comments
TD_I1 | 0x01 | A signed 8-bit integer.
TD_I2 | 0x02 | A signed 16-bit integer.
TD_I4 | 0x03 | A signed 32-bit integer.
TD_I8 | 0x04 | A signed 64-bit integer.
TD_U1 | 0x05 | An unsigned 8-bit integer.
TD_U2 | 0x06 | An unsigned 16-bit integer.
TD_U4 | 0x07 | An unsigned 32-bit integer.
TD_U8 | 0x08 | An unsigned 64-bit integer.
TD_R4 | 0x09 | A 32-bit IEEE floating value.
TD_R8 | 0x0a | A 64-bit IEEE floating value.
TD_PTR | 0x0b | A pointer to some data structure.
TD_INTF | 0x0d | An interface (an IUnknown derivative).
TD_JSTR | 0x0e | A Java string.
TD_CUSTOM | 0x11 | A custom data type.
TD_CUSTOMBYREF | 0x12 | A custom data type passed by reference.
TD_CUSTOMBYVAL | 0x13 | A custom data type passed by value.
TD_SYSCHAR | 0x15 | A Unicode character or an ANSI character, depending on platform setting.
TD_SYSFIXEDSTRING | 0x16 | A fixed ANSI or Unicode string. The SizeIndex item of the MCTypeDesc structure must be set to the number of characters, including the null terminator.
TD_FIXEDARRAY | 0x17 | A fixed size array of scalars. The SizeIndex item of the MCTypeDesc structure must be set to the number of elements in the array.
TD_OBJECT | 0x18 | A field type of L<something>. This field should be treated as embedded struct and must be a JCDW class.

The Flags item represents a bitmask of options. The possible values for these options applicable to the MCTypeDesc structure used in the COM_MapsTo attribute are shown in the following table.

Flags Options | Value | Comments
TDF_AUTOMARSHAL | 0x04 | When marshaling an interface field from native memory to a Java representation (JCW field), the current thread will become the home thread for the created JCW. Subsequent access to COM methods invoked through JCW methods on the created JCW will be marshaled by the Microsoft VM to the home thread. This allows non-threadsafe COM objects to be invoked from multiple Java threads without explicit marshaling. This option is meaningful only for the TD_INTF type. For all others, it must be set to 0 (zero).
TDF_NOMARSHAL | 0x08 | When marshaling an interface field from native memory to a Java representation (a JCW field), the created JCW will be marked as being free-threaded. COM methods invoked through JCW methods on the created JCW will occur on the calling thread. This mode is most suitable for thread-safe COM objects. If the object is not thread-safe and this mode is used, the caller must restrict calls to the JCW to the thread on which the JCW was received. This option is meaningful only for the TD_INTF type. For all others, it must be set to 0 (zero).
TDF_USER2 | 0x40 | User-defined.
TDF_USER1 | 0x80 | User-defined.

The marshaling mode is a property of an instance of a JCW class, not of the JCW class itself. In certain cases, the Microsoft VM may produce a Java object that assumes a different marshaling mode than this option indicates. This can happen if the interface pointer was previously marshaled to Java through another method whose parameter was flagged with the less-restrictive marshaling mode. It can also happen if the Microsoft VM itself created the incoming interface pointer (these interface pointers are all thread-safe).


COM_MethodPool

The COM_MethodPool attribute stores the signatures of the COM methods that are invoked by and implemented by the Java methods in the .class file. These signatures (MCFuncDescs) are referenced by index by other attributes in the class. Valid indices range from 0 inclusive to nFuncs exclusive. The index 0xffff is reserved to indicate the "null" index.

Attribute Level | Generated By Directives
Class | @com.method @com.parameters

COM_MethodPool_attribute {
  u2 attribute_name_index;
  u4 attribute_length;
  u2 nFuncs
  // MCFuncDesc aMCFunc[nFuncs]
}

The C structure MCMethodPool, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

Restrictions

The class access flags must be a subset of ACC_PUBLIC, ACC_FINAL, ACC_INTERFACE, or ACC_ABSTRACT.

Though the MCFuncDesc structure allows you to specify an IID for an individual MCFuncDesc, the Microsoft virtual machine requires that all MCFuncDescs in a .class file reference the same IID in the GuidPool. (This restriction does not apply to IIDs embedded in the MCTypeDescs within the parameter arrays and return types of the MCFuncDescs.)

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "COM_MethodPool".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and varies depending on the value of nFuncs. The attribute_length must have a minimum value of 2.

nFuncs

This field indicates the number of MCFuncDescs defined in this table.

MCFuncDesc aFuncDesc[nFuncs]

This array stores the actual MCFuncDescs. MCFuncDescs are variable-sized structures.

The @com.method directive that generates an entry for this attribute has the following syntax:

/** @com.method([vtoffset=integer | long], [dispid=integer | long],
[name=string], [name2=string], [type=METHOD | PROPGET | PROPPUT
| PROPPUTREF], [thread=AUTO | NO], [nodispatch], [returntype=VOID
| HRESULT], [addFlagsVtable=integer], [addFlagsDispatch=integer]) */

The name2 parameter requires that the interface be DUAL or dispatch.

An example of the @com.method directive that generates item data for this attribute has the following syntax:

/** @com.method(vtoffset=0) */

The @com.parameters directive that generates an entry for this attribute has the following syntax:

/** @com.parameters([parameters] methodParamName1, [parameters]
 methodParamName2, … [[parameters] return]) */

Valid types for a vtable class include array, BOOLEAN, CURRENCY, CUSTOM, CUSTOMBYREF, CUSTOMBYVAL, DATE, DISPATCH, numeric types, PTR, SAFEARRAY, STRING, STRUCT, and VARIANT. Valid types for dispatch class include numeric types except I8 and U8 (unless nodispatch is specified in the @com.method directive), array, BOOLEAN, CURRENCY, DATE, DISPATCH, OBJECT, PTR (when the parameter is of type com.ms.com.Variant), SAFEARRAY, STRING, and VARIANT.

The elementType parameter should be specified only if type = PTR or type = ARRAY. The vt parameter is required if type = SAFEARRAY. The size parameter should be specified only if type = ARRAY or type = STRUCT. When specifying information about the return type, return is used as the <parameter name>.

Any forms of these @com.method or @com.parameters directives create an entry that will be compiled into the COM_MethodPool attribute for a Java/COM class.

See Also

MCCustomMethod (includes MCSpecialArgumentEntry)
MCDispMethod
MCFuncDesc
MCTypeDesc
MCVarTypeDesc
MCVtblMethod


MCCustomMethod

The MCCustomMethod structure describes a COM vtable method that uses a custom method marshaling hook (DISPATCH and DUAL methods cannot be custom marshaled). This feature is only supported in Microsoft® Internet Explorer 4.0 or later.

SpecialArgumentEntry_attribute {
    u1 bArgIndex;
    u1 bArgFlavor;
}

CustomMethod_attribute {
    u2 IIDIndex;
    u2 VTblIndex;
    u2 hookclsIndex;
    u2 j2cmethodIndex;
    u2 c2jmethodIndex;
    u2 cbUserData;
    u4 reserved;
    u1 bRetFlavor;
    u1 cbSpecialComArgs;
    MCSpecialArgumentEntry paramFlavor[cbSpecialComArgs];
    u1 UserData[cbUserData];
};

The C structure MCCustomMethod, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

MCARGF-Defined Types

Name | Value | Comments
MCARGF_I4 | 0 | A signed 32-bit integer.
MCARGF_R4 | 1 | A 32-bit IEEE floating value.
MCARGF_R8 | 2 | A 64-bit IEEE floating value.
MCARGF_I8 | 3 | A signed 64-bit integer.
MCARGF_PTR | 4 | A pointer (a machine address).
MCARGF_STRUCT | 5 | A by-value structure. Note that entries of this type take two slots. Only the bArgFlavor field of the first slot is valid, and will be MCARGF_STRUCT. The following slot (two bytes, treated as a WORD) is the size of the structure in bytes.

Structure Elements

IIDIndex

This value must be a valid index into the GUIDPool represented by the COM_GuidPool attribute and denotes the IID through which this method is exposed.

VtblIndex

Denotes which vtable element this method occupies. Index values of 0, 1 and 2 are not legal because these correspond to the IUnknown interface methods, which cannot be overridden. In addition, if the method pool contains MCDispMethods using the same IID, index values of 3, 4, 5, and 6 cannot be specified because they correspond to IDispatch methods that are supplied by the Microsoft VM.

hookclsIndex

An index of a CONSTANT_Class constant pool item that denotes the Java class that holds the hook methods. This class should derive directly from java.lang.Object to avoid circular loading problems.

j2cmethodIndex

Index of a CONSTANT_Utf8 constant pool item that denotes the method within the hook class that handles Java calls to COM. The method has the following prototype:

   public static JTYPE j2chook(int)

where JTYPE must be identical to the return type of the associated Java method, with one exception: If the associated Java method returns a reference type (object or array), JTYPE can be declared as "java.lang.Object".

c2jmethodIndex

Index of a CONSTANT_Utf8 constant pool item that denotes the method within the hook class that handles COM calls to Java. The method has the following prototype:

   public static void c2jhook(int)

cbUserData

Number of bytes of user data following the paramFlavor[] array. The Microsoft VM will not interpret this data but will make it available to the hook methods. This allows one hook method to handle multiple methods.

reserved

Must be set to 0 (zero).

bRetFlavor

Certain platforms have calling conventions that require distinguishing between normal and floating point values. See the MCARGF table for the possible flavors. Because COM methods almost universally return HRESULT values, this field will usually be set to MCARGF_I4. This field cannot be used to indicate the flavor of an [out,retval] parameter. These must be set in the paramFlavor[] array, and the flavor is MCARGF_PTR).

cbSpecialComArgs

Indicates the size of the paramFlavor[] array.

MCSpecialArgumentEntry paramFlavor[cbSpecialComArgs]

This is a variable-length array and is not indicated in the struct definition. It follows the cbSpecialComArgs field. This array indicates the flavor of all parameters that are not type MCARGF_I4 or the final parameter. The final parameter must always be declared because on some platforms, the total size of the argument stack is needed to implement the stdcall calling convention correctly. The fields of MCSpecialArgumentEntry are as follows:

bArgIndex

In this index of the argument, 0 denotes the first 4-byte argument after the "this" pointer, 1 denotes the second 4-byte argument after the "this" pointer, and so forth. The "this" pointer is implicitly MCARGF_PTR, so its flavor neither can nor need be indicated in bArgIndex.

bArgFlavor

This must be one of the MCARGF values.

UserData

This is a variable-length array and is not indicated in the struct definition. It follows the cbSpecialComArgs field. This array indicates any user data associated with this method. The Microsoft VM does not interpret this data, but hook methods can access it.


MCDispMethod

The MCDispMethod structure describes an OLE Automation method or property.

DispMethod_attribute {
    u2 IIDIndex;
    u4 Dispid;
    u2 disptype;
    u2 dispname;
    u2 nArguments;
    MCVarTypeDesc RetType;
    MCVarTypeDesc aParamType[nArguments];
};

The C structure MCDispMethod, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

Structure Elements

IIDIndex

This field must be a valid index into the GUID pool and denotes the IID through which this method is exposed. Typically, the IID is IID_IDispatch, but it can be any COM interface that derives from IDispatch.

Dispid

Indicates the dispatch identifier (DISPID) of this method or property.

disptype

This value represents the wFlags parameter used by the IDispatch::Invoke method and indicates the dispatch type. It may be one of the values listed in the following table. These flags are defined in the OLEAUTO.H header file supplied with Microsoft® Visual C++® and the MSDN™ Library.

Disptype Definitions

Name | Value | Comments
DISPATCH_METHOD | 0x1 | Indicates that this method corresponds to an IDispatch method invocation.
DISPATCH_PROPERTYGET | 0x2 | Indicates that this method corresponds to an IDispatch property get.
DISPATCH_PROPERTYPUT | 0x4 | Indicates that this method corresponds to an IDispatch property put.
DISPATCH_PROPERTYPUTREF | 0x8 | Indicates that this method corresponds to an IDispatch property put by-reference.

dispname

If this value is non-zero, it must be a valid index into the constant pool and the index must reference a CP_Utf8 that provides the method name. This field is required only if this MCDispMethod is referenced by a COM_ExposedAs_Group attribute.

nArguments

The number of arguments.

RetType

Describes the type of the return value.

aParamType[nArguments]

Describes the type of each parameter.


MCFuncDesc

The COM_MethodPool attribute uses an MCFuncDesc structure to store a method signature for each of the COM methods that are invoked by and implemented by the Java methods in the Java class file. This method signature indicates the parameters and return value of a method as well as the method name. These signatures (MCFuncDesc structures) are referenced by index by other attributes in the class. Valid indices range from 0 (zero) inclusive to nFuncs exclusive. The index 0xffff is reserved to indicate the null index.

FuncDesc_attribute {
  u2 cbSize;
  u2 Flags;
  union {
    MCVtblMethod mvm;
    MCDispMethod mdm;
    MCCustomMethod mcm;
    };
};

The C structure MCFuncDesc, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

Structure Elements

cbSize

This value indicates the size of entire MCFuncDesc structure in bytes including the cbSize member.

Flags

The following table describes the flags used by the FuncDesc attribute.

Flag | Value | Meaning
MCMDF_DISPATCH | 0x0001 | Indicates that the function is a dispatch method.
MCMDF_HRESULT_RETVAL | 0x0002 | Indicates that the return type of the method is an HRESULT and that it is to be mapped to an exception on the Java side. If this option is used, the declared type of the RetVal must be TD_VOID. MCMDF_HRESULT_RETVAL must not be used together with MCMDF_DISPATCH. When MCMDF_HRESULT_RETVAL is on, the Microsoft VM treats all return values from COM objects as HRESULTs and will throw a Java exception if the HRESULT is not S_OK. Conversely, the Microsoft VM will map all uncaught exceptions from Java code into a failing HRESULT, and will otherwise supply a return value of S_OK.
MCMDF_IGNORE_ NONFAILING_HRESULTS | 0x0004 | This flag works in conjunction with MCMDF_HRESULT_RETVAL. If this option is set, only HRESULTs that have the high bit set (FAIL) will generate a Java exception. Non-zero HRESULTs that do not set the bit (such as S_FALSE) will not generate an exception. MCMDF_IGNORE_NONFAILING_HRESULTS must not be used together with MCMDF_DISPATCH. If both the flags MCMDF_HRESULT_RETVAL (0x0002) and MCMDF_IGNORE_NONFAILING_HRESULTS (0x0004) are set, only HRESULTs that have the high bit (FAIL) set will generate a Java exception. Non-zero HRESULTs that do not set the bit (such as S_FALSE) will not generate an exception.
MCMDF_CUSTOM | 0x0008 | Indicates a custom method. Legal only if none of the other flags are set.

mvm

If the Flags indicate that this is a vtable method (MCMDF_DISPATCH is not set), the MCVtblMethod structure is used to describe this method.

mdm

If the Flags indicate that this is a dispatch method (MCMDF_DISPATCH is set), a MCDispMethod structure is used to describe this method.

mcm

If the Flags indicate that this is a custom method (MCMDF_CUSTOM is set), a MCCustomMethod structure is used to describe this method.


MCTypeDesc

The MCTypeDesc structure describes the type of a parameter or return value of a COM method.

TypeDesc_attribute {
  u1 Type;
  u1 Flags;
  union {
    u2 IIDIndex;
    u2 SizeIndex;
    u2 wSize;
    u2 wiHookClass;
    VARTYPE VarType;
    struct {
      u1 biParam;
      u1 bReserved;
  } a;
 }
}

The C structure MCTypeDesc, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

Structure Elements

Type

This value indicates the type of the parameter or return value. Legal values are described in the MCTypeDesc enumerations table.

Flags

The flags are grouped into in/out, threading-model, and attribute flags. Legal values are described in the MCTypeDesc flags table.

IIDIndex

If the type is TD_INTF and TDF_USES_IID_IS is not set, IIDIndex must be set to a valid index into the GUID pool. The entry at this index indicates the IID of the interface. A null index (0xffff) is invalid.

SizeIndex

If the type is TD_STRUCT, SizeIndex must be set to an index into the constant pool. The constant pool item must be type CP_Integer and must indicate the size of the struct in bytes.

wSize

If the type is TD_SYSFIXEDSTRING, TD_FIXEDARRAY, or TD_JARR, wSize must be set to the number of elements in the array.

wiHookClass

If the type is TD_CUSTOM, TD_CUSTOMBYREF, or TD_CUSTOMBYVAL, wiHookClass must be set to an index into the constant pool. The constant pool item must be type CP_Class or CP_Utf8 (in which case the string is a class name) and specify the class that will perform the custom marshaling.

VarType

If the type is TD_SAFEARRAY, VarType must be set to a valid VarType that describes the element type. VT_ARRAY may not be set on this type. If VT_BYREF is set, this parameter will be interpreted as a SAFEARRAY** rather than a SAFEARRAY*.

biParam

If the type is TD_JARR and TDF_USES_SIZE_IS is specified in the flags, a.biParam is the zero-based index of the parameter that determines the dynamic (run time) size of this array parameter. The referenced parameter must be an integral or array of integral type. This is similar to the MIDL attribute "size_is." a.bReserved must be set to zero.

If the type is TD_INTF and TDF_USES_SIZE_IS is specified in the flags, a.biParam is the zero-based index of the parameter that determines the dynamic (run time) IID of this interface parameter. The referenced parameter must be of struct or array of struct type. This is similar to the MIDL attribute "iid_is." a.bReserved must be set to zero.

For types other than TD_STRUCT, TD_INTF, TD_SAFEARRAY, TD_SYSFIXEDSTRING, TD_FIXEDARRAY, TD_JARR, TD_CUSTOM, TD_CUSTOMBYREF, and TD_CUSTOMBYVAL, this union must be set to zero.

MCTypeDesc Enumerations

Name | Value | Comments
TD_VOID | 0x00 | A void, used only for return types.
TD_I1 | 0x01 | A signed 8-bit integer.
TD_I2 | 0x02 | A signed 16-bit integer.
TD_I4 | 0x03 | A signed 32-bit integer.
TD_I8 | 0x04 | A signed 64-bit integer.
TD_U1 | 0x05 | An unsigned 8-bit integer.
TD_U2 | 0x06 | An unsigned 16-bit integer.
TD_U4 | 0x07 | An unsigned 32-bit integer.
TD_U8 | 0x08 | An unsigned 64-bit integer.
TD_R4 | 0x09 | A 32-bit IEEE floating value.
TD_R8 | 0x0a | A 64-bit IEEE floating value.
TD_PTR | 0x0b | A pointer to some data structure.
TD_STRUCT | 0x0c | A structure that is being passed by value. SizeIndex must specify the size of the structure.
TD_INTF | 0x0d | A pointer to an interface (an IUnknown* derivative).
TD_JSTR | 0x0e | A JString.
TD_JARR | 0x0f | A JArray.
TD_VARIANT | 0x10 | A variant.
TD_CUSTOM | 0x11 | A custom data type.
TD_CUSTOMBYREF | 0x12 | A custom data type passed by reference.
TD_CUSTOMBYVAL | 0x13 | A custom data type passed by value.
TD_SAFEARRAY | 0x14 | A SAFEARRAY.
TD_SYSCHAR | 0x15 | Unicode or ANSI char, depending on platform setting.
TD_SYSFIXEDSTRING | 0x16 | Fixed Unicode or ANSI string (for use inside structs: SizeIndex == #ofchars, including null terminator).
TD_FIXEDARRAY | 0x17 | Fixed size array of scalars (for use inside structs: SizeIndex == # of elements).
TD_OBJECT | 0x18 | Field type of "L<something>". Treat as embedded struct if JCDW; treat as COM interface if Object or interface.

MCTypeDesc Flags

In/Out Flags: If MCTypeDesc or MCVarTypeDesc is used to describe a parameter, the flags must specify one of TDF_IN, TDF_OUT or TDF_INOUT.

MCTypeDesc: For all types other than TD_PTR, TD_SAFEARRAY and TD_JARR, the value of this subflag must be TD_IN. If the MCTypeDesc is used to describe a return value or a MapsTo type, this subflag must be set to zero.

MCVarTypeDesc: If the type field does not have VTD_BYREF set, TDF_IN must be specified. TDF_INOUT is illegal in this case. If the MCVarTypeDesc is used to describe a return value, this subflag must be set to zero.
Name | Value | Comments
TDF_IN 0x01 The parameter is an [in] parameter to the method.

This option is only applicable to method parameters.
TDF_OUT 0x02 The parameter is an [out] parameter to the method.

This option is only applicable to method parameters.
TDF_INOUT 0x03 The parameter is an [in, out] parameter to the method.

This option is only applicable to method parameters.
Threading-Model Flags: Indicates the expected threading model of the interface pointer. In certain cases, the VM may produce a Java object that assumes a less restrictive threading model than is indicated by this subflag. This can happen if the interface pointer had been previously marshaled to Java through another method whose parameter was flagged with the less restrictive threading model. It can also happen if the incoming interface pointer was created by the VM itself (these interface pointers are all free-threaded.)

MCTypeDesc: This subflag is meaningful only for the TD_INTF type. For all others, it must be set to zero.

MCVarTypeDesc: This subflag is meaningful only for the VTD_DISPATCH and VTD_UNKNOWN types. For all others, it must be set to zero.

Name | Value | Comments
TDF_AUTOMARSHAL | 0x04 | If the VM creates a JCW to represent this COM interface, it will do the appropriate marshaling.
TDF_NOMARSHAL | 0x08 | If this MCTypeDesc is being used to marshal to a Java class that is not a JCW, TDF_NOMARSHAL must be set.
Attribute Flags: These flags are used only on method parameters and return values of type TD_JARR and TD_INTF. They must not be set in a COM_MapsTo attribute. These flags indicate that a second parameter will be used to dynamically describe this parameter in some way (similar to iid_is and size_is in MIDL).
Name | Value | Comments
TDF_USER2 | 0x40 | User-defined.
TDF_USER1 | 0x80 | User-defined.
TDF_USES_IIS_IS TDF_PARAM_
DEPENDENCY 		This flag is meaningful only for the TD_INTF type, and signifies that the IID of the interface parameter is determined dynamically at runtime using the value of another parameter.
TDF_USES_SIZE_IS TDF_PARAM_
DEPENDENCY 		This flag is meaningful only for the TD_JARR type, and signifies that the size of the array parameter is determined dynamically at runtime using the value of another parameter.

VarType Values

Name | Value | Comments
VT_I2 | 2 | A signed 16-bit integer.
VT_I4 | 3 | A signed 32-bit integer.
VT_R4 | 4 | A 32-bit IEEE floating value.
VT_R8 | 5 | A 64-bit IEEE floating value.
VT_CURRENCY | 6 | A 64-bit fixed-point number used for a currency data type.
VT_DATE | 7 | A 64-bit floating-point fractional number indicating the number of days since December 30, 1899.
VT_BSTR | 8 | A BSTR, a length-prefixed automation string data type.
VT_DISPATCH | 9 | A pointer to a dispatch interface.
VT_ERROR | 10 | An HRESULT, a built-in error type.
VT_BOOL | 11 | A data item that can have a value of true (0xff) or false (0). The size of this item corresponds to an unsigned character.
VT_VARIANT | 12 | A VARIANT pointer.
VT_UNKNOWN | 13 | A pointer to an interface that is not derived from IDispatch. Any interface can be represented by its IUnknown interface.
VT_DECIMAL | 14 | A 128-bit fixed-point data type.
VT_UI1 | 17 | An unsigned 8-bit character.


MCVarTypeDesc

The MCVarTypeDesc structure describes the type of a single parameter or return value of an IDispatch method.

VarTypeDesc_attribute {
    u1 type;
    u2 optname;
    u1 Flags;
}

The C structure MCVarTypeDesc, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

Structure Elements

type

Contains a compressed VARTYPE value, as defined by the VTD enumeration values table.

optname

If non-zero, this field must be a constant-pool index to a CP_Utf8 that gives the parameter name. This field is optional.

Flags

These are grouped into in/out flags and threading-model flags. Legal values for this parameter are defined by the MCTypeDesc Flags table.

VTD Enumeration Values

Name | Value | Comments
VTD_EMPTY | 0 | A void (applicable only to return type).
VTD_NULL | 1 | An invalid type.
VTD_I2 | 2 | A signed 16-bit integer.
VTD_I4 | 3 | A signed 32-bit integer.
VTD_R4 | 4 | A 32-bit IEEE floating number.
VTD_R8 | 5 | A 64-bit IEEE floating number.
VTD_CY | 6 | A 64-bit fixed-point number used for a currency data type.
VTD_DATE | 7 | A 64-bit floating-point fractional number indicating the number of days since December 30, 1899.
VTD_BSTR | 8 | A BSTR, a length-prefixed OLE automation string data type.
VTD_DISPATCH | 9 | A pointer to an IDispatch interface.
VTD_ERROR | 10 | An HRESULT, a built-in error type.
VTD_BOOL | 11 | A data item that can have a value of true (0xff) or false (0). The size of this item corresponds to an unsigned character.
VTD_VARIANT | 12 | A VARIANT pointer.
VTD_UNKNOWN | 13 | A pointer to an interface that is not derived from IDispatch. Any interface can be represented by its IUnknown interface.
VTD_UI1 | 17 | An unsigned 8-bit character.
Modifiers to VTD Types: Two modifier bits can be applied to the previous VTD-defined types that affect their interpretation.
Name | Value | Comments
VTD_ARRAY | 0x40 | The parameter or return type is a SAFEARRAY pointer (an array of one of the VTD-defined types).
VTD_BYREF | 0x80 | The parameter or return type is passed by reference rather than by value.


MCVtblMethod

The MCVtblMethod structure describes a vtable-based method in a COM interface. References to this structure can appear in both COM_ExposedAs_Group and COM_ProxiesTo attributes.

VtblMethod_attribute {
    u2 IIDIndex;
    u2 VTblIndex;
    u2 nArguments;
    u2 wRetValParameter
    MCTypeDesc RetType;
    MCTypeDesc aParamType[nArguments];
}

The C structure MCVtblMethod, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

Structure Elements

IIDIndex

A valid index into the GUID pool that describes the IID of the COM interface that implements this method. An index of 0xffff is invalid.

VTblIndex

Denotes which vtable element the method occupies. Index values of 0 (zero), 1 and 2 are not legal because these correspond to the IUnknown* methods, which cannot be overridden. In addition, if the method pool contains MCDispMethods using the same IID (a DUAL interface), index values 3, 4, 5, and 6 must not be specified because they correspond to IDispatch* methods supplied by the Microsoft VM.

nArguments

Indicates the number of parameters in the aParamType[] element. This count does not include the automatic this parameter passed to all COM methods. If the wRetValParameter element is 0xffff, this count must exactly match the number of parameters in the corresponding Java signature. Otherwise, the count must be exactly one greater than the corresponding Java signature.

wRetValParameter

If this item contains a value other than 0xffff, it must contain a value between 0 (zero) (inclusive) and nArguments (exclusive). This indicates that the parameter whose index is equal to wRetValParameter is actually a pointer through which the method returns its true return value. The aParamType entry for this parameter must indicate the type of the buffer (the pointer to is implicit), and RetType must be TD_VOID. In addition, the return type of the Java method signature must be compatible with the retval parameter.

If this COM method is invoked from Java, the VM will supply a return value buffer of the appropriate type to the COM method. See the MCFuncDesc flags for what constitutes a successful return from the COM method.

If Java is used to implement this COM method, the VM will remove the retval pointer parameter from the list of arguments presented to the Java method. When the Java method returns, the VM converts the Java method's return value to COM representation, then write it to the retval buffer passed in from COM. The VM creates a COM return value that indicates success See the MCFuncDesc flags for what constitutes a successful return.

RetType

An MCTypeDesc structure that describes the return type. This type must be TD_VOID if wRetValParameter contains a value other than 0xffff, or if MCFuncDesc.Flags has the MCMDF_HRESULT_RETVAL bit set.

aParamType

Describes the parameter of each COM method.


COM_ProxiesTo

The COM_ProxiesTo attribute denotes that the Java method is implemented using COM. For a given method of a JCW, this attribute describes a mapping between the Java method and a COM interface function in the underlying COM object.

Attribute Level | Generated By Directives
Method | @com.method @com.interface

COM_ProxiesTo_attribute {
  u2 attribute_name_index;
  u4 attribute_length;
  u2 MCP_Flags;
  u2 MethodPoolIndex;
}

The C structure MCProxiesTo, declared in comattr.h, defines the layout of this attribute for use in C/C++ programs.

Restrictions

The access flags for the method must be a subset of ACC_PUBLIC, ACC_PRIVATE, ACC_PROTECTED, ACC_FINAL ACC_NATIVE (required), or ACC_ABSTRACT (on interfaces only).

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "COM_ProxiesTo".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and must be 4.

MCP_Flags

This value must be 0 (zero).

MethodPoolIndex

This value must be a valid index into the MethodPool.


COM_Register

The COM_Register attribute stores data for registering a class as a COM component class (coclass).

Attribute Level | Generated By Directives
Class | @com.register

COM_Register_attribute {
  u2 attribute_name_index;
  u4 attribute_length;
  u2 Flags;
  u2 clsidIndex;
  u2 tlbIndex;
  u2 majorTLB;
  u2 minorTLB;
  u2 progIDIndex;
  u2 descIndex;
}

Attribute Elements

attribute_name_index

This value must be a valid index into the constant pool table. The constant pool item must be a CP_Utf8 representing the string "COM_Register".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and must be 14.

Flags

This value indicates options for this attribute.

clsidIndex

This value must be a valid index into the GUIDPool represented by the COM_GuidPool attribute.

tlbIndex

This may be 0xffff (which means unspecified) or a valid index into the GUIDPool represented by the COM_GuidPool attribute.

tlbMajor

This value indicates the major version of the type library. By default, it is 1.

tlbMajor

This value indicates the minor version of the type library. By default, it is 0 (zero).

progIDIndex

This value must be zero (which means unspecified) or a valid index into the constant pool table. The constant pool item must be CP_Utf8 representing the string.

descIndex

This value must be zero (which means unspecified) or a valid index into the constant pool table. The constant pool item must be CP_Utf8 representing the string description of the control.


COM_Safety

The COM_Safety attribute indicates that a COM class can safely be used by an untrusted class. A COM class can normally only be used from trusted classes. This attribute is generated by the safe parameter of the @com.class, @com.struct, and @dll.struct directives.

Attribute Level | Generated By Directives
Class | "safe" parameters of: @com.class @com.struct @dll.struct

COM_Safety_attribute {
  u2 attribute_name_index;
  u4 attribute_length;
  u2 reserved1;
}

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "COM_Safety".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes.

reserved1

This value must be 0 (zero).


Delegate

When applied at the class level, the Delegate attribute specifies that a class is a delegate type and will be used for method invocations.

When applied to a method, the Delegate attribute indicates that the method is an invocation method.

Attribute Level | Generated By
Class or method | The delegate keyword

Delegate_attribute {
  u2 attribute_name_index;
  u4 attribute_length;
  u2 signature; // Present only at the class level.
}

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "Delegate".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and may be 0 (zero) (at method level) or two (at class level).

signature

When present, this optional value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the signature of the invoke method.

Remarks

A method marked with the delegate attribute will not be JIT-compiled or interpreted by the Microsoft VM, but will instead use a special stub.

See Also

Delegate Class
MulticastDelegate Class
MulticastDelegate Attribute


JITMeNot

The JITMeNot attribute specifies that a method or the class's static initializer should not be JIT-compiled.

Attribute Level | Generated By Directives
Class or method | N/A

JITMeNot_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
}

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "JITMeNot".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and may be 0 (zero).


LinkSafe

The LinkSafe attribute specifies that a class is accessible to untrusted classes. A native or COM class can normally only be used by trusted classes.

Attribute Level | Generated By Directives
Class | @security

LinkSafe_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
}

The @security directive that generates this attribute has the following syntax:

@security(checkClassLinking=off)

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "LinkSafe".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and may be 0 (zero).

Remarks

This attribute indicates that this class is explicitly declaring that it is safe for use by non-system (less than fully trusted) classes.


LinkUnSafe

The LinkUnsafe attribute specifies that a class is not accessible to untrusted classes. A native or COM class can normally only be used from trusted classes.

Attribute Level | Generated By Directives
Class | @security

LinkUnSafe_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
}

The @security directive that generates this attribute has the following syntax:

@security(checkClassLinking=on)

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "LinkUnSafe".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and may be 0 (zero).

Remarks

This attribute indicates that this class is explicitly declaring that it is unsafe for use by non-system (less than fully trusted) classes.


MulticastDelegate

The MulticastDelegate attribute applies to a method. It specifies that a method should be treated as a multicast invocation method by the Microsoft VM.

Attribute Level | Generated By
Method | multicast and delegate keywords

MulticastDelegate_attribute {
  u2 attribute_name_index;
  u4 attribute_length;
}

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "MulticastDelegate ".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and may be 0 (zero).

Remarks

A method marked with the MulticastDelegate attribute will not be JIT-compiled or interpreted by the Microsoft VM, but will use a special stub instead.

See Also

Delegate Class
MulticastDelegate Class
Delegate Attribute


NAT_L

The NAT_L (Native Link) attribute specifies the dynamic-link library (DLL) name and DLL entry point (method) name associated with a J/Direct Java method, as well as the calling convention (ansi, Unicode, ole, or raw native) and other semantics.

Attribute Level | Generated By Directives
Class or method | @dll.import

NAT_L_attribute {
  u2 attribute_name_index;
  u4 attribute_length;
  u1 linktype;
  u1 Flags;
  u2 LibName_CPIndex;
  u2 EntryName_CPIndex;
}

The @dll.import directive that generates this attribute has the following syntax:

/** @dll.import([string], [entrypoint=string], [ansi | auto | unicode
| ole | raw], [setLastError], [linktype=integer]) */

If the DLL name is specified at the global level (a global @dll.import directive) in a class, this parameter may be omitted in subsequent @dll.import directives at the method level. The entrypoint name must be omitted in a global @dll.import directive.

The @dll.import directive must precede a non-synchronized, static native method, or the class keyword. A @dll.import directive that precedes the class keyword is interpreted as a global @dll.import. Its purpose is to specify default values for any methods declared by the class.

When used with some parameters specified, this directive might look like the following:

/** @dll.import("KERNEL32",AUTO, setLastError) */

When used with minimal parameters, this directive might look like the following:

/** @dll.import("KERNEL32") */

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "NAT_L".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and may be six.

linktype

This value indicates the calling convention, which can be specified as ansi, auto, Unicode, raw, or OLE corresponding to the @dll.import parameters. If the linktype is set in a global @dll.import directive, this value will become the default linktype for all methods in the class unless it is overridden. If the linktype is omitted in a global dll.import directive, the default calling convention is set to ANSI for the methods of the Java class.

Flags

This value has a single option and indicates whether the setLastError parameter was used in the @dll.import directive. If this parameter was set, the Flags option has a value of 0x01 (NLF_LASTWIN32ERRORSAVE); otherwise, it is 0 (zero).

LibName_CPIndex

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the DLL library name. The Microsoft VM will call LoadLibrary on this DLL name.

If this index is set with a global @dll.import directive, the DLL library name defaults to this value for all methods in the class and this parameter can be omitted from subsequent @dll.import directives for each method. When the DLL name is omitted from the @dll.import directive, a LibName_CPIndex of zero is stored in the NAT_L attribute.

EntryName_CPIndex

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the entry point name of the function to call in the DLL. The Java compiler need not add this "A" or "W" to this method name to signify the ANSI or Unicode version of these functions. When a @dll.import directive applies to an individual method, the EntryName can be omitted if the Java method name exactly corresponds with the entrypoint name in the DLL. When this entrypoint is omitted from the @dll.import directive, an EntryName_CPINdex of zero is stored in the NAT_L attribute.

Possible Values of linktype

Parameter Name | Value | Comments
NLT_RAW | 0 | The Microsoft VM will link using RNI.
NLT_INHERIT 1 None of the LinkType parameter keywords were specified in the @dll.import directive.

At the global level, when no parameter keyword (for example, ole) is specified, a LinkType of NLT_INHERIT is equivalent to setting the LinkType to NLT_ANSI (use the ANSI calling convention by default).

At the method level, when no parameter keyword is entered, a linktype of 1 causes the method to use the linktype specified at the global level or the ANSI calling convention if linktype was omitted at the global level.
NLT_ANSI | 2 | The ANSI keyword was specified for the linktype in the @dll.import directive. The Microsoft VM will convert all characters and strings to ANSI and link to the ANSI entrypoint (suffixed by "A") when available.
NLT_UNICODE | 3 | The Unicode keyword was specified for the linktype in the @dll.import directive. The Microsoft VM will convert all characters and strings to Unicode and link to the Unicode entrypoint (suffixed by "W") when available.
NLT_DUAL | 4 | The AUTO keyword was specified for the linktype in the @dll.import directive. The Microsoft VM will automatically handle the calling convention and will choose between NLT_ANSI and NLT_unicode at runtime. The Microsoft VM will choose NLT_ANSI on Windows 95 and NLT_unicode on Windows NT.
NLT_OLE | 5 | The ole keyword was specified for the linktype in the @dll.import directive. The Microsoft VM will use the ole calling convention for this platform.

Possible Values for Flags

Flag Names | Value | Comments
NLF_LASTWIN32ERRORUNDECL | 0x00 | The setLastError keyword was not specified in the @dll.import directive. The Microsoft VM will not save the value of the last Microsoft® Win32® error.
NLF_LASTWIN32ERRORSAVE | 0x01 | The setLastError keyword was specified in the @dll.import directive. The Microsoft VM will save the value of the last Win32 error.
NLF_LASTWIN32ERRORIGNORE | 0x02 | The Microsoft VM will ignore the value of the last Win32 error.


NAT_L_DCTS

The NAT_L_DCTS (Native Link Disable Call-Time Security) attribute specifies that no extra call-time security checks are required when a J/Direct method is called. Normally, the Microsoft VM ensures that all classes on the stack are fully trusted before allowing a J/Direct call to succeed.

Attribute Level | Generated By Directives
Class | @security

NAT_L_DCTS_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
}

The @security directive that generates this attribute has the following syntax:

/** @security(checkDLLCalls=off) */

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "NAT_L_DCTS".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and may be 0 (zero).


SecurityAPI

The SecurityAPI attribute specifies that a method requires additional space in its stack frame. The extra frame space is used to store security information at runtime.

Attribute Level | Generated By Directives
Method | N/A

SecurityAPI_attribute {
    u2 attribute_name_index;
    u4 attribute_length;
};

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "SecurityAPI".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and may be 0 (zero).


SourceDir

The SourceDir attribute specifies the source directory of the Java source file for this class.

Attribute Level | Generated By Directives
Class | N/A

SourceDir_attribute {
  u2 attribute_name_index;
  u4 attribute_length;
  u2 sourcedir_index;
}

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "SourceDir".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and must be two.

sourcedir_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string name of the source directory for the source file from which this class file was compiled.

Remarks

The name of the source file is provided in the SourceFile attribute defined by The Java Virtual Machine Specification by Addison Wesley. The SourceDir attribute represents the name of the directory containing this source file.


Glossary

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

%SDKDIR%

The folder where you have chosen to install the Microsoft® SDK for Java; the root of the SDK tree.

A

accessor

Typically refers to an accessor method, which exposes the properties of an object for getting and setting the value. Properties should not be directly exposed.

AFC

See Application Foundation Classes.

apartment

  1. A logical construct for thinking about concurrency, such as how threads relate to a set of COM objects.

  2. A set of rules programmers must obey to receive the concurrency behavior they expect from the COM environment.

  3. A system-supplied code that helps programmers manage thread concurrency with respect to COM objects.

Application Foundation Classes

A set of Java class libraries that provide user interface components and graphics effects for use in applets and applications using Java. AFC packages are available in the Microsoft SDK for Application Foundation Classes.

application namespace

A private namespace where packages can be installed by the Java Package Manager (JPM). Packages installed in an application namespace are only visible to applications and applets running in the namespace. Java packages with identical names can exist without conflict as long as they are in separate application namespaces. See also global namespace.

attribute

Information that the Microsoft VM uses to map COM objects to Java objects. Attributes are generated at compile time for files containing @com or @dll compiler directives. (Attributes also have meaning outside the COM context.)

AWT

Abstract Windowing Toolkit, a portable windowing library. AWT has classes and behavior for creating GUI-based applications in Java.

B

bitmask

A portion of a bitwise operation.

bitwise operation

An operation that can be performed on any integral type, such as byte, char, int, long, and so on.

breakpoint

A location in a program at which execution is halted so that a programmer can examine the program's status, the contents of variables, and so on. A breakpoint is set and used within a debugger and is usually implemented by inserting at the point some kind of jump, call, or trap instruction that transfers control to the debugger.

bytecode

Machine-independent code generated by the Java compiler and executed by the Java interpreter or compiled at the last minute by a JIT compiler. Bytecode resembles machine code but is not specific to any one processor; also called machine code.

C

.cab

The cabinet file extension.

cabinet file

The Microsoft archive standard for Java files.

casting

  1. Converting the value of an object or primitive type into another type. The result of a cast is a new reference or value; casting does not affect the original object or value. A cast operation on a COM object calls AddRef.

  2. A programmer-specified data conversion from one type to another, such as a conversion from integer to floating point. Also called coercion.

catch

Exception term; dealing with an exception so the program does not crash.

CCW

See COM-callable wrapper.

class file format

The file format for compiled Java code that isn't dependent on a particular platform or implementation.

class path

The Microsoft VM searches the class path for classes, among other areas.

CLASSPATH environment variable

Specifies additional class path information when compiling from the command line.

coclass

An implemented Java object. Coclasses are useful in COM only for creating the instance. The new instance's functionality is contained in the COM interfaces it implements.

COM

See Component Object Model.

COM object

An object that conforms to Component Object Model (COM) architecture. A COM object is an instance of an object definition, which specifies the object's data and one or more implementations of interfaces on the object. Clients interact with a COM object only through its interfaces.

COM-Callable Wrapper

(CCW); a generic COM object whose virtual table supports some default COM interfaces as well as any COM interfaces that a given Java object implements. The CCW neutrally presents the Java object for use in COM components and COM-compliant languages.

compiler

Any program that transforms one set of symbols into another by following a set of syntactic and semantic rules. In Java, a program that generates bytecodes from Java code.

compiler, Microsoft JIT

A Java compiler that converts bytecodes into native code when the Java program executes.

compiler, Microsoft jvc

The compiler provided by the Microsoft SDK for Java. The current release of jvc is compatible with the language enhancements specified in JDK 1.1. The version of jvc included with Microsoft® Visual J++® uses the same underlying technology, but does not support all the language features as the SDK version. To obtain the additional support, you can replace the Visual J++ compiler (or any older versions of jvc) with the current SDK compiler. For instructions, see Microsoft Visual J++ Compiler.

Component Object Model

(COM); a software architecture that allows components made by different software vendors to be combined into a variety of applications. COM defines a standard for component interoperability, is not dependent on any particular programming language, is available on multiple platforms, and is extensible. COM provides the interoperability between components and their clients. COM is the foundation of the OLE, ActiveX, and DirectX specifications.

constant

  1. A named item that retains a consistent value throughout the execution of a program, as opposed to a variable, which can have its value changed during execution.

  2. An object or variable that is not modifiable; in Java, the nearest equivalent to a C or C++ preprocessor constant is a static final variable declared within a class definition (Java has no preprocessor).

D

data binding, complex

The direct relationship between a recordset and a WFC component.

data binding, simple

The relationship between a field in a recordset and the property of a WFC component. Differs from complex data binding because the WFC component does not need explicit information about the data protocol or data provider.

DCOM

Acronym for Distributed Component Object Model. The version of Microsoft's Component Object Model (COM) specification that stipulates how components communicate over Windows-based networks. It permits the distribution of different components for a single application across two or more networked computers. This is accomplished by running an application distributed across a network. (The distribution of components is not apparent to the user, and remotely displaying an application.) Also called Distributed COM. See also Component Object Model.

debugger

A program designed to aid in debugging another program by allowing the programmer to step through the program, examine the data, and monitor conditions such as the values of variables.

delta distribution unit

Same as split distribution unit.

Distribution Unit Profile

(DUP); same as Open Software Distribution manifest.

distribution unit

(DU); a cabinet file that provides a way to distribute software using the code download feature of Microsoft® Internet Explorer 4.0. A DU contains an Open Software Distribution manifest file and content files.

DUP

Distribution Unit Profile. Same as Open Software Distribution manifest.

E

exception

An indicator that some kind of exceptional condition has occurred (file not found, for example).

exegen format

A data format that must be used for Java resources stored within a portable executable (PE) image so that those resources can be located by the VM.

F

G

garbage collection

The automatic system for allocating and freeing memory in Java.

global namespace

A namespace where packages and classes that must be visible to all applications (such as system classes) are installed. If no namespace is specified, the Java Package Manager stores packages in the global namespace and searches there for packages. See also application namespace.

GUID

Globally unique identifiers, 128-bit integers. In COM, a 16-byte code that identifies an interface to an object across all computers and networks.

H

HRESULT

A 32-bit integer that provides error information. See the com.ms.com.ComFailException class for a list of common system-defined HRESULTs.

I

instance

Synonym for an actual object. If a class is the general (generic) representation of an object, an instance is its concrete representation.

interface, invocation

A group of declarations and definitions used to launch applications in the Microsoft VM.

internationalization

Features and support in the Microsoft VM to accommodate other languages at runtime.

J

JAR

Sun Microsystem's archiving standard for Java files (Java Archive); .jar files.

Java Package Manager

(JPM); a feature in the Microsoft VM that handles package installation and management. JPM's primary function is to find classes when they are needed by the Microsoft VM.

Java process

See process, Java.

JCDW

(Java-callable data wrapper); a structure or class (usually in C or C++) that Java can easily map to native types, usually by using Microsoft® J/Direct™. For example, most of the com.ms.win32 classes, such as Rect.java, are JCDWs.

JCW

(Java-callable wrapper); a Java class with Microsoft-specific attributes that tell the Microsoft VM how to map the Java object to the COM component that it represents.

jvc

See compiler, Microsoft jvc

K

L

M

marshaling

The packaging, sending, and unpackaging of interface method parameters across process or machine boundaries.

MIDL

Microsoft Interface Definition Language, a compiler (Midl.exe).

monitor, event

A feature in the Microsoft VM that notifies the profiler when a specified event has occurred.

N

namespace

A keyword; a technique for avoiding name conflicts. The names within each namespace must be unique to avoid conflict, but an identical name can appear in more than one namespace. The compiler can resolve references based on the syntactic context of the identifier in the program. See also application namespace and global namespace.

native code

Platform-dependent code, any non-Java code.

O

ODL

Object Description Language.

Open Software Distribution manifest

(OSD); a file written in XML that is used to build distribution units (DUs). The file contains details on the version of the DU, the contents and their versions, and installation instructions for the Java Package Manager. Also called Distribution Unit Profile (DUP).

OSD

See Open Software Distribution manifest.

P

process, Java

An executing application that has its own memory space, code, data, and other operating-system resources. A process also contains one or more threads that run in the context of the process.

profiler interfaces

A set of interfaces to analyze Java for speed, memory use, redundancy, and other performance factors. These interfaces inherit from IUnknown, are COM objects, and are implemented by the Microsoft virtual machine.

Q

R

raw native interface

(RNI); a high-performance interface supported by the Microsoft VM that provides efficient traversing between Java and native code; provides easy manipulation of objects while in native code.

reflection API

The combination of java.lang.Class and the java.lang.reflect package, which is used to obtain information about a class and its members.

registration interface

Registers Java classes to be debugged and to receive notification when new Java processes are created.

S

sandbox model

A layer of security in the Java language that allows you to run untrusted code, which cannot access any part of your local file system. A SecurityManager class enforces other restrictions.

split distribution unit

A distribution unit (DU) used to update software versions. A split DU contains only the changed packages and a pointer to a secondary DU that contains the unchanged packages. Also called delta distribution unit.

T

thread

The basic (memory) entity to which the operating system allocates CPU time. A thread can execute any part of the application's code, including a part currently being executed by another thread. All threads of a process share the virtual address space, global variables, and operating-system resources of the process.

thread safe

A resource or process that internally handles synchronization. Threads that need to access thread-safe resources can do so as if they were in a single-threaded environment.

threading model, apartment

A component's methods execute only on the execution path that created it.

threading model, both

Objects that have the characteristics of apartment threading and free threading.

threading model, free

See multithreading

threading model, multithreading

An implementation of IMarshal that can be aggregated allowing direct access to interfaces on an object from any thread in the same process. This speeds up cross-apartment calls, and is intended for classes that use the Both threading model.

threading model, single

All a component's methods are executed only on the main thread.

U

V

virtual machine

Software that mimics the performance of a hardware device. In Java as a programming language, the foundation for its cross-platform flexibility; a specification for a program of how bytecodes are interpreted, the recognition of the class file format, a symbol table, and other pertinent information.

virtual machine object model

A function of the VM that breaks down objects into their smallest parts (member components).

vtable

Virtual function table. COM defines a standard way to lay out memory in vtables.

W

Windows Foundation Classes

(WFC); a set of Java class libraries that access the Microsoft® Windows® API, enabling you to write full-featured Windows applications with the Java programming language. WFC also wraps the Dynamic HTML (DHTML) object model implemented in Microsoft® Internet Explorer 4.0, which allows you to dynamically manipulate HTML on both the client and the server.

wrapper classes

Classes generated by jactivex that map COM objects to Java objects for a DLL that represents a COM/ActiveX component.

wrapper, Java-callable

See JCW.

wrapper, Java-callable data

See JCDW.

X

Y

Z


Document Conventions

The following table shows the typographic conventions that are used in Microsoft® SDK for Java.

Example | Convention
public boolean equals(Object objOther); | Bold font indicates method names in syntax.
clipping

zCmpCaps

D3DBLEND_ONE

 Bold font indicates field names. They can be lowercase, concatenated with internal capitals, or all uppercase.
setup | Bold font indicates words, other than language commands, that you must type.
On the File menu, choose Open. | Bold font is used in procedures to highlight interface elements such as the name of a window, menu, dialog box, toolbar, button, or option.
HRESULT | Bold font is used for this COM return type.
/base: Bold font is used for command-line options.
Control | "Control" in bold font indicates a Java class that has been registered as a COM object, implying that the object is a Microsoft® ActiveX® Control.
cannot | Bold font is used for emphasis in important statements.
C:\%Windir%\System[32] | Bold font and initial capital letters identify folders and directories, and file names are separated by backslashes (\).
Example.cab | Initial capital letters indicate file names.
ComExeception
readLicense
IPermission 		Initial capital letters indicate the names of classes, interfaces, and methods. However, some methods have initial lowercase letters. If the name consists of more than one word, the initial letter of each word is capitalized and the group of words are concatenated.
http://www.microsoft.com/ | Lowercase letters are used for URLs. Server, share, and file names are separated by forward slashes (/).(Example not an active link.)
hr | Italicized letters or words indicate parameters.
<file name> | Italicized words enclosed in angle brackets (in examples and syntax) indicate placeholders for information you supply.
@commandfile | Italicized words indicate command-line arguments.
The Java Virtual Machine Specification | Italicized words indicate titles of publications.
thread | Single-underlined words or phrases denote Glossary terms. Click the term to see its definition. (Example not an active link.)
myMethod | Single-underlined words, concatenated words, or phrases indicate links either inside or outside the SDK for Java. (Example not an active link.)
[!] For tools, square brackets indicate options on the command line. For example,
/bx [!]. Information in square brackets is not required.
| For tools and attributes, a bar indicates a choice. For example, /bx [x|-]. Although a choice is given, information on either side of the bar is not required.
public static int cbByValSize;
Monospace font in a gray background indicates members of classes and interfaces; is also for example and sample code.


Copyright Notice

Information in this document is subject to change without notice. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1996-1999 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, MS, Windows, Windows NT, Active Accessibility, ActiveX, Direct3D, DirectDraw, DirectPlay, DirectSound, DirectX, J/Direct, MSDN, Visual Basic, Visual C++, Visual J++, and Win32, are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

TrueType is a registered trademark of Apple Computer, Inc.

Other product and company names mentioned herein may be the trademarks of their respective owners.


Application Foundation Classes (AFC) Has Moved

The Microsoft Application Foundation Classes are no longer included in the SDK for Java. AFC and its documentation has moved to the Microsoft® SDK for Application Foundation Classes, which can be downloaded from the following location:

http://www.microsoft.com/java/download.htm This link takes you to a site on microsoft.com.