Insert/Replace Text Item Information

The Insert / Replace Pluggable Java Component (PJC) provides extended versions of single line and multi-line text items.  These enhanced items allow the field to toggle between the default insert mode to a replace mode - much like a word processor.  The mode can be toggled using the standard keyboard insert key, or programmatically.  All instances of the controls share the same insert or replace state.

The demo form shows both single line and multi-line items with this enhancement.  It also uses an additional Java Bean that is supplied with the PJC set which can be used to send an event back into Forms when the user toggles the insert mode from the keyboard.  In the demo, this event is used to update a status indicator on the screen 

Modules In This Demo

The InsertReplace demo consists of the following files (relative directories shown in brackets):

  1. replacel.fmb/fmx [forms]- The demo form
  2. InsertReplaceHelper.java [src/oracle/forms/demo/enhancedItems] - source code for a helper class for the PJCs which is used to store the common Insert/Replace state and also provides some utility functions.
  3. InsertReplaceTextField.java [src/oracle/forms/demo/enhancedItems] - source code for the single line text item PJC that can be toggled back and forth between insert and replace mode.
  4. InsertReplaceTextArea.java [src/oracle/forms/demo/enhancedItems] - source code for the multi line text item PJC that can be toggled back and forth between insert and replace mode.
  5. InsertReplaceLWTextArea.java [src/oracle/forms/demo/enhancedItems] - source code for the a class that is used by InsertReplaceTextArea to create a insert / replace capable text area.
  6. InsertReplaceIndicator.java [src/oracle/forms/demo/enhancedItems] - source code for a Java Bean that can be included in a bean area on the Form.  Whenever the insert / replace mode is changed the bean will raise a Custom-Item-Event in PL/SQL for the programmer to catch and use - for instance to update an indicator on the screen.
  7. insertreplace.jar [classes]- the compiled and jarred java classes.

The doc directory and the classes directory contain the JavaDoc for the code and the compiled classes respectively

Reusing the code

Setting up Forms Services

In order for an application to be able to use the insert replace PJCs the relevant configuration in the formsweb.cfg file has to ensure that the supplied insertreplace.jar (or another jar file containing the compiled classes) is included in the relevant archive setting.

An entry in the formsweb.cfg file for an application that used the insert / replace PJCs  would look like this:

[InsertReplace]
pageTitle=OracleAS Forms Services - Insert / Replace Demo
IE=jinitiator
baseHTMLJInitiator=demobasejini.html
archive_jini=frmall_jinit.jar,insertreplace.jar
form=replaceforms/java
width=675
height=480
separateFrame=false
splashScreen=no
lookAndFeel=oracle
colorScheme=blue
background=/formsdemo/images/blue.gif

Using the PJCs in your Form

Insert / Replace Enabled Single Line Text Item

You must first create a normal Forms text item with the Multi-Line property set to No

Then set the Implementation Class property for this text item to oracle.forms.demos.enhancedItems.InsertReplaceTextField.  Note that this property is case sensitive and must be entered exactly as shown.

Insert / Replace Enabled Multi Line Text Item

You must first create a normal Forms text item with the Multi-Line property set to Yes

Then set the Implementation Class property for this text item to oracle.forms.demos.enhancedItems.InsertReplaceTextArea.  Note that this property is case sensitive and must be entered exactly as shown.

Insert / Replace Toggle Indicator

The toggle indicator is a Java Bean that is hooked into the insert / replace PJCs in the Form.  When the mode is toggled between insert and replace or visa versa this JavaBean will raise a custom item event which can be used to update a screen flag (or whatever).  This component is optional and only required if you need this programmatic information.

To use the indicator bean, you must first create a Forms bean area  item.  This item must be on a canvas and visible, although it can be defined as 1 pixel by one pixel with no border to effectively render it hidden. 

Then set the Implementation Class property for this bean area item to oracle.forms.demos.enhancedItems.InsertReplaceIndicator.  Note that this property is case sensitive and must be entered exactly as shown.

Enabling and Using the Insert capabilities of the PJC

By default the enhanced text items continues to operate just like a normal text items with the same behavoirs and properties, One addition property is supported which will act as a way to toggle the control (and all the other insert / replace) between modes. In order to swich the control into replace mode you must set a custom property on the item REPLACE_MODE to the string value 'true' e.g.

 SET_CUSTOM_PROPERTY('PJC.RESUME',1,'REPLACE_MODE','true');

The first argument to Set_Custom_Property() is the name or id of the PJC enabled item.  The second parameter defines the instance of the control that you wish to set the property on.  As the REPLACE_MODE applies to all the controls at once you only need to set the property on the first instance.  The third argument is the custom property that is being set on the PJC and the forth the value.

Using the Replace Mode Toggle JavaBean

If you want to have an event raised whenever the insert / replace mode is toggled then you have to create a Bean Area in the form with the implementation class of InsertReplaceIndicator (see above).  Then you need to create a When-Custom-Item-Event trigger on this bean area.  whenever the mode is changed this trigger will fire.

When the trigger fires a the system parameter :SYSTEM.CUSTOM_ITEM_EVENT will be set to the value REPLACE_TOGGLE. You can examine the REPLACE_MODE value in the :SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS parameter list to see if the mode is currently Replace (TRUE) or Insert (FALSE). An example of the trigger code might be:

[When-Custom-Item-Event]

declare 
  vcState varchar2(10);
  pType number;
begin
  if :SYSTEM.CUSTOM_ITEM_EVENT = 'REPLACE_TOGGLE' then
    get_parameter_attr(:SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS,'REPLACE_MODE',pType,vcState);
    if upper(vcState) = 'TRUE' then 
      :CONTROL.CURRENT_STATE_IND := '** Replace **';
    else
      :CONTROL.CURRENT_STATE_IND := '** Insert **';
    end if;
  end if;
end;

Custom Property Summary

The following properties apply to the PJCs for single and multi-line text items. 

Property Get Set Valid Values / Return Value Purpose
REPLACE Yes Yes 'true' | 'false' Switches the fields in and out of replace mode
DEBUGMESSAGES No Yes 'true' | 'false' Enables/disables debugging to the Java Console for this instance of the control.
DEBUGMESSAGES_ALL No Yes 'true' | 'false' Enables/disables debugging to the Java Console for all instances of the control.