CursorPos Text Item Information

By Robin Zimmermann

Contents

Introduction

What does Forms do currently?
What does this PJC allow me to do?

Modules in this demo

Reusing the code

Setting up Forms Services
Using the PJCs in your Form
Enabling and Using the Cursor Position Capabilities of the PJC

How do I use this demo?

Introdution

The CursorPos Pluggable Java Component (PJC) provides extended versions of single line and multi-line text items.  These enhanced items allow the caret (cursor) position or selection of a field to be controlled.  This control is provided via a PL/SQL that you can use in Forms, which interacts with the PJC.

The demo form shows both single line and multi-line items with this enhancement.  It allows you to set the caret position or selection how you like, and test the result.  Not sure what to do in the demo?  See the How do I use this demo? section for a walk-through script.

What does Forms do currently?

Forms, by default, will always highlight all of the text in a field every time you navigate to it.  You may set the item property Keep Cursor Position to TRUE, and when you navigate back to a field, Forms will put the cursor where you last left it.  Even with Keep Cursor Position, Forms will select the entire field the first time you navigate to that field.

What does this PJC allow me to do?

The CursorPos PJC gives you more control.  It lets you specify a position for the cursor, or a selection of any length.  Moreover, it will do so even when you navigate to the field for the first time.  It does this by using Java to override the default behavior of a text item in Forms.

When using the PJC, you can specify the cursor position or selection using one of the following values:

There is a common setting that applies to all of the fields using the CursorPos PJC, although individual fields may choose to override the common setting.  By default, the common setting is FIELD_END, which means the cursor position is at the end of the field.  So any fields that use the common setting, which is all of the PJC-enabled ones, by default, wi ll have their cursor position after the last character.

Suppose your Form has 20 fields which all use this PJC.  You don't want to have to set the cursor position on all of those fields separately!  So by default they all will use the common setting, and you can set the common setting to your preferred choice, and all of the fields will therefore take on that setting.  You can then override the settings for individual fields that do something different than the common setting.  The common setting is just there as a convenience and there is not obligation to use it.

Note: For any item that uses the CursorPos PJC, and isn't set to FORMS_DEFAULT, the Keep Cursor Position property is ignored.

The API for interacting with the PJC is described later in this document.

You may choose to use use the CursorPos PJC in your own application, or you may wish to build your own similar PJC, and use the CursorPos PJC to see how it was done.  For example, you might like to implement a PJC which puts the cursor at the end of the field for the initial navigation, and revert to the Forms default cursor position afterwards.

Modules In This Demo

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

  1. cursorpos.fmb/fmx [forms]- The demo form
  2. CursorPosCommon.java [src/oracle/forms/demo/enhancedItems2] - source code for a helper class for the PJCs which is used to store the common CursorPos state and also provides some utility functions.
  3. CursorPosTextField.java [src/oracle/forms/demo/enhancedItems2] - source code for the single line text item PJC to control the cursor position.
  4. CursorPosTextArea.java [src/oracle/forms/demo/enhancedItems2] - source code for the multi line text item PJC to control the cursor position.
  5. cursorpos.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

Note: This step is not necessary if you installed the Oracle Forms Demos, and then installed Extension Pack 1 on top of that.  You only need this step if you plan to install this demo in a different iDS or iAS installation.

In order for an application to be able to use the CursorPos PJCs the relevant configuration in the formsweb.cfg file has to ensure that the supplied cursorpos.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 CursorPos PJCs  could look like this, assuming cursorpos.jar was in the same directory as frmall_jinit.jar:

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

Using the PJCs in your Form

CursorPos 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.enhancedItems2.CursorPosTextField.  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.enhancedItems2.CursorPosTextArea.  Note that this property is case sensitive and must be entered exactly as shown.

Enabling and Using the Cursor Position Capabilities of the PJC

By default the enhanced text items will take on the common setting, which is FIELD_END.  Normally you interact with a Forms PJC with using the Forms built-ins SET_CUSTOM_PROPERTY and GET_CUSTOM_PROPERTY.  That's still possible with the CursorPos PJC, but for your convenience, a PL/SQL wrapper package has been created for you.  The package, called CursorPos, contains procedures and functions that you can use to control the cursor position in a text field.

Here is a list of the constants,  procedures, and functions and a description of what they do.

PACKAGE CursorPos IS

--
-- This package serves as a PL/SQL interface for the CursorPos PJC. It is
-- to necessary if you want to use the PJC, it is provided to make using the
-- PJC a little easier.
--

--
-- When setting a cursor or selection position, you specify a number 
-- greater than 0 to represent the position.
-- The following are special variables which are also valid. Refer to the
-- PJC documentation for more information.
-- Do not change these values, as they correspond to the what's used in the
-- PJC.
--
COMMON CONSTANT NUMBER := -1;
FORMS_DEFAULT CONSTANT NUMBER := -2;
FIELD_START CONSTANT NUMBER := -3;
FIELD_END CONSTANT NUMBER := -4;

--
-- Set the cursor position for the specified field.
-- pPos should be a number greater than 0, or one of the special values
-- mentioned above.
-- pField should be of the form 'block.item'.
--
PROCEDURE setCaretPosition
(
  pField IN VARCHAR2
, pRowNum IN NUMBER
, pPos IN NUMBER
);

--
-- Get the cursor position for the specified field.
-- pField should be of the form 'block.item'.
--
FUNCTION getCaretPosition
(
  pField IN VARCHAR2
, pRowNum IN NUMBER
)
RETURN NUMBER;

--
-- Set the common cursor position. This will affect all fields that
-- are set to use common.
-- pField and pRowNum can be any field that uses the PJC. It will still
-- affect all fields that use the CursorPos PJC. But the Forms PJC
-- implementation always needs to act on a field so it doesn't matter which
-- one you use.
-- pPos should be a number greater than 0, or one of the special values
-- mentioned above.
-- pField should be of the form 'block.item'.
--
PROCEDURE setCommonCaretPosition
(
  pField IN VARCHAR2
, pRowNum IN NUMBER
, pPos IN NUMBER
);

--
-- Get the common cursor position. This will affect all fields that
-- are set to use common.
-- pField should be of the form 'block.item'.
--
FUNCTION getCommonCaretPosition
(
  pField IN VARCHAR2
, pRowNum IN NUMBER
)
RETURN NUMBER;

--
-- Specify a selection range for pField.
-- pStartPos and pEndPos should be a number greater than 0, or one of the
-- special values mentioned above.
-- pField should be of the form 'block.item'.
--
PROCEDURE setSelection
(
  pField IN VARCHAR2
, pRowNum IN NUMBER
, pStartPos IN NUMBER
, pEndPos IN NUMBER
);

--
-- Get the start position of the selection for the given field.
-- The return value could be greater than 0, or one of the special values
-- mentioned above.
-- pField should be of the form 'block.item'.
--
FUNCTION getSelectionStart
(
  pField IN VARCHAR2
, pRowNum IN NUMBER
)
RETURN NUMBER;

--
-- Get the end position of the selection for the given field.
-- The return value could be greater than 0, or one of the special values
-- mentioned above.
-- pField should be of the form 'block.item'.
--
FUNCTION getSelectionEnd
(
  pField IN VARCHAR2
, pRowNum IN NUMBER
)
RETURN NUMBER;

--
-- Set the common selection. This will affect all fields that
-- are set to use common.
-- pField and pRowNum can be any field that uses the PJC. It will still
-- affect all fields that use the CursorPos PJC. But the Forms PJC
-- implementation always needs to act on a field so it doesn't matter which
-- one you use.
-- pStartPos and pEndPos should be a numb



er greater than 0, or one of the
-- special values mentioned above.
-- pField should be of the form 'block.item'.
--
PROCEDURE setCommonSelection
(
  pField IN VARCHAR2
, pRowNum IN NUMBER
, pStartPos IN NUMBER
, pEndPos IN NUMBER
);

--
-- Get the start position of the common selection.
-- pField and pRowNum can be any field that uses the PJC. It will still
-- affect all fields that use the CursorPos PJC. But the Forms PJC
-- implementation always needs to act on a field so it doesn't matter which
-- one you use.
-- The return value could be greater than 0, or one of the special values
-- mentioned above.
-- pField should be of the form 'block.item'.
--
FUNCTION getCommonSelectionStart
(
  pField IN VARCHAR2
, pRowNum IN NUMBER
)
RETURN NUMBER;

--
-- Get the end position of the common selection.
-- pField and pRowNum can be any field that uses the PJC. It will still
-- affect all fields that use the CursorPos PJC. But the Forms PJC
-- implementation always needs to act on a field so it doesn't matter which
-- one you use.
-- The return value could be greater than 0, or one of the special values
-- mentioned above.
-- pField should be of the form 'block.item'.
--
FUNCTION getCommonSelectionEnd
(
  pField IN VARCHAR2
, pRowNum IN NUMBER
)
RETURN NUMBER;

END; -- CursorPos

How do I use this demo?

  1. Launch the demo.
     
  2. Click on the Cursor Position (Simple) tab.  The two fields in the upper area don't use the PJC, and therefore behave like normal Forms text items. This is so you can compare the behavior of fields with and without the PJC.  The three fields in the bottom section do have the PJC, and each is configured differently.

    Notice that the first field has the text highlighted.  This is what Forms does by default.
     
  3. TAB to the second field, it is also highlighted.
     
  4. Use the arrow key to move the cursor, and then press Shift+TAB to navigate to the first field.  It is again highlighted.
     
  5. Press TAB to go to the second field.  Notice that the cursor is where you left it.  This field has Keep Cursor Position set to TRUE and will remember the cursor position.  Not the first time you navigate to the field, though.  The first time you navigate to it, the entire field is selected, as it was in step 3.
     
  6. Now TAB to field 3.  Notice that text is not highlighted and the cursor is at the start of the field.
     
  7. Move the cursor using the arrow keys and Shift+TAB back up to the second field.  Now immediately TAB back to the third field.  See that the cursor is again at the front of the field.
     
  8. Test the fourth and fifth fields in the same way.  The PJC overrides Keep Cursor Position and will always put the cursor to where it is set.
     
  9. Click the Cursor Position (Advanced) tab.  Here you can control the behavior of the fields.

    By default, any field with the PJC will use the Common setting.  On this tab, only Test Field 1 is using Common by default.
     
  10. Press TAB to navigate to Test Field 1.  Notice that the cursor is at the end.  That's because it is using the Common setting, and as you can see from the top section, Common is set to Field End.
     
  11. Without making any changes, press TAB to navigate to all of the Test Fields and verify that they are behaving as specified.  Move the cursor using the arrow keys and navigate to the fields again to see that it had no effect.
     
  12. In the Common poplist, select User-Defined.  The Value field appears and the cursor is already there for you.  Type 2 to specify the second position.
     
  13. Press TAB to go to Test Field 1.  Notice that the cursor is in the second position.
     
  14. In the second row (for Test Field 2), select Common from the Cursor Position poplist.
     
  15. Press Shift+TAB to navigate back to Test Field 2 and notice that the cursor is in the second position, as specified by Common.
     
  16. Experiment with different settings on this page.

    If you select Forms Default from any of the poplists, the field will behave as normal Forms fields.  In that case, the Keep Cursor Position checkbox appears in case you want to test that.

    If you select User-Defined, a Value field will appear so you can specify a cursor position.
     
  17. Click the Range Selection tab.
     
  18. In the first section, you can specify the start and end position for the selection.  After making your choice, TAB or Shift+TAB to the Test Field to see the effect.
     
  19. In the Partial Selection section, the day part of the date will always be selected when you enter the field.
     
  20. In the Search section, press the Search button, and "fox" will be highlighted in the large text area.  This shows that the PJC also works on multi-line text items.
     
  21. Click the Code Generation tab.

    Here you can configure the Test Field to specify a cursor position or a range selection.  TAB to the field to test that it's what you want.  Then press the Generate button.  This code can be used in your Forms application if you are using the PJC.

 

Copyright (c) 2002 Oracle Corp