Oracle Developer Server 6.0 
Pluggable Java Components

KeyFilter

Author:  Oracle Developer Product Management Team
Creation Date:  10-APR-2000
Last Updated:  10-APR-2000
Version:  1.0
Copyright (C) 2000 Oracle Corporation
All Rights Reserved


Change Record

Date Author Version Comments
10-APR-2000 PM Team 1.0 initial creation
       
       


Overview

This Pluggable Java Component (PJC) provides an example of enhancing a normal Forms Text Item with the ability to both filter the keystrokes that the user enters into the item, and to obtain information about the keys that the user has actually pressed. The code currently extends single line text items but could be simply adapted for multi-line text items or combo-boxes.

The Distribution

This distribution contains the following directories:
Directory Contents
.\src The Java source files for the PJC. 
.\classes The compiled classes for the PJC that can be used in an Oracle Developer application.  This directory contains a JAR file and also a signed JAR file.
.\doc The Javadoc generated documentation from the PJC source files. This documents the method and attributes used within the PJC. Click here to view the documentation. 
.\forms Contains an example Form which uses the component and demonstrate how to work with the PJC from the Forms environment. 

Deployment

You should perform the following steps to install and configure the PJC for development and deployment in an Oracle Developer Server application:

        <ARCHIVE = "f60all.jar, keyfilter.jar">

Using the KeyFilter PJC

The fully qualified name for this PJC is oracle.forms.demos.KeyFilter (note that Java is case sensitive).

This PJC must be added to a Form application using a single line Text item. Place the Text item on a canvas and then set the implementation class property to be the fully qualified name for the KeyPress PJC. You do not need to add the .class suffix. Alternatively you can set the implementation class of an existing Text item to oracle.forms.demos.KeyFilter

The example Form that ships with this distribution demonstrates how to use the component with Developer 6i. The PJC can be queried using GET_CUSTOM_PROPERTY from PL/SQL to determine what key the user last pressed within the item. The PJC can also apply a filter to the item which restricts the keystrokes that will actually register in the field. Note that the property names below are case sensitive.


PL/SQL Property Gettable Settable Valid Values Usage
KEY_CODE Yes No n/a Returns the ASCII code of the last keypress in the field. Note both upper and lower case keypresses return the same code (the code for the uppercase character. use KEY_MODIFIER or KEY_CHARACTER to determine if an Uppercase or Lowercase character was entered.

Developer 6i Usage

key_pressed_code := GET_CUSTOM_PROPERTY(hItem,1,'KEY_CODE');
KEY_CHARACTER Yes No n/a Returns the actual character entered. If the last keypress was a function key or editing key, then the returned value will be enclosed in braces e.g. if the user presses the letter A then 'A' will be returned by this value, if the user presses the function key F1 then '{F1}' will be returned. Simply pressing a modifier on it's own on the field will return '{Modifier}' for this value and you should check KEY_MODIFIER for the modifier that was pressed.
Developer 6i Usage

key_pressed_char := GET_CUSTOM_PROPERTY(hItem,1,'KEY_CHARACTER');
KEY_MODIFIER Yes No n/a Returns any modifiers in force when the key was pressed. These can be CTRL, SHIFT or ALT (including combinations of these joined by a plus sign). These are all returned in upper case.

Developer 6i Usage

key_mod := GET_CUSTOM_PROPERTY(hItem,1,'KEY_MODIFIER');
FILTER_TYPE Yes Yes NONE
ALPHA
NUMERIC
ALPHANUMERIC
CUSTOM
Allows you to get and set the filter in force:
  • NONE - No filter is active and any character can be typed into the item
  • ALPHA - Only A-Z, a-z and space can be entered
  • NUMERIC - Only Numbers 0-9 and ',' and '.' can be entered
  • ALPHANUMERIC - A combination of ALPHA and NUMERIC
  • CUSTOM - Your own Custom Filter is in force this can be set using the CUSTOM_FILTER property
Developer 6i Usage

-- Set the Filter to allow Numbers only
SET_CUSTOM_PROPERTY(hItem,1,'FILTER_TYPE','NUMERIC');
CUSTOM_FILTER Yes Yes Ant characters you want to be allowed in the field The CUSTOM_FILTER property allows you to create your own filter which comes into force when the FILTER_TYPE is set to CUSTOM_FILTER. If you have not defined a custom filter, or if the value is set to NULL then Custom will act in the same way as NONE - e.g. all characters will be allowed. You must include both the uppercase and lowercase versions of each character you require if you want both upper and lower characters to be entered. This even applies if the items "Case Restriction" property if set.
A simple example of a customer filter would be "1234567890ABCDEFabcdef". This would define a field that could only take Hexadecimal numbers.
Developer 6i Usage

-- Set the Filter to allow Hex Numbers only
SET_CUSTOM_PROPERTY( hItem,1,'CUSTOM_FILTER','1234567890ABCDEFabcdef');

Running the Sample

The sample form that ships with this distribution uses the KeyFilter PJC. The sample form has no dependencies on a database. To run the sample form you must perform the following steps:

Building the Java Classes

This distribution contains the Java source code for the PJC so you can make any changes you wish to the way the component works for your applications.
Java Source File Notes
KeyFilter.java The source file for the KeyFilter PJC. It is defined to be in the oracle.forms.demos package. 

To compile the KeyFilter PJC you will need to have the following software components installed and configured on your computer :

A batch script (for Windows NT) has been provided in the src directory that will compile the KeyFilter.java into the classes directory. This batch file also recreates the JAR file using the newly compiled classes and regenerates the Javadoc documentation.

To run the batch file the following environment variables must be set:
   
Environment Variable Notes
ORACLE_HOME Specifies the location of the Oracle software installation. In the case where more than one Oracle home exists, it should specify the location where Oracle Developer Server is installed.
JDK_HOME Specifies the location where a Java Development Kit is installed. This should point to the top level directory only.

Dependencies

This PJC has been tested with the following software components: