This section describes item properties Oracle Applications uses to control how the user interacts with items when they are in specific states. Oracle Applications provides a cover routine to the Oracle Forms built-in routine SET_ITEM_PROPERTY. This cover routine, APP_ITEM_PROPERTY.SET_PROPERTY, modifies or augments the native Oracle Forms behaviors for specific properties.
Using APP_ITEM_PROPERTY.SET_PROPERTY helps your forms adhere to the Oracle Applications user interface standards and helps simplify coding. Using this routine also helps to protect your form from future changes in the native Oracle Forms SET_ITEM_PROPERTY built-in routine.
The APP_ITEM_PROPERTY.SET_PROPERTY cover routine modifies the following properties:
ALTERABLE
ALTERABLE_PLUS
ENTERABLE
DISPLAYED
ENABLED
REQUIRED
All other properties are processed with the native Oracle Forms functionality. Oracle recommends that you call this cover routine even for properties that do not currently have special behaviors in case they change in the future.
Note that calling APP_ITEM_PROPERTY.SET_PROPERTY and specifying a property that is not valid for the indicated item will give the same error as the native Forms built-in routine SET_ITEM_PROPERTY, except where certain conditions are masked as noted below.
The ALTERABLE property is intended to allow or disallow changes to a specific instance (one row) of an item regardless of whether the record is a new or queried record. The item remains keyboard navigable even if changes are not allowed.
The following code:
app_item_property.set_property(itemid, ALTERABLE,
PROPERTY_ON);
is equivalent to:
set_item_instance_property(itemid, CURRENT_RECORD,
INSERT_ALLOWED, PROPERTY_ON);
set_item_instance_property(itemid, CURRENT_RECORD,
UPDATEABLE, PROPERTY_ON);
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON);
set_item_property(itemid, UPDATEABLE, PROPERTY_ON);
If the item is currently hidden, no action is taken.
Item and item-instance values are both set to make sure the effect of both of them produces the desired result.
The following code:
app_item_property.set_property(itemid, ALTERABLE,
PROPERTY_OFF);
is equivalent to:
set_item_instance_property(itemid, CURRENT_RECORD,
INSERT_ALLOWED, PROPERTY_OFF);
set_item_instance_property(itemid, CURRENT_RECORD,
UPDATEABLE, PROPERTY_OFF);
If the item is currently hidden, no action is taken.
The ALTERABLE_PLUS property is intended to allow or disallow changes to all instances of an item (all rows of the block). Setting the property to PROPERTY_OFF prevents the user from making a change to that item on any row, regardless of whether each record is a new or queried record. The item remains keyboard navigable even if changes are not allowed.
The following code:
app_item_property.set_property(itemid, ALTERABLE_PLUS,
PROPERTY_ON);
is equivalent to:
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON); set_item_property(itemid, UPDATEABLE, PROPERTY_ON);
If the item is currently hidden, no action is taken.
The following code:
app_item_property.set_property(itemid, ALTERABLE_PLUS,
PROPERTY_OFF);
is equivalent to:
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_OFF); set_item_property(itemid, UPDATEABLE, PROPERTY_OFF);
If the item is currently hidden, no action is taken.
The ENTERABLE property is designed to simulate disabling a particular instance of an item (one row). It extends the ALTERABLE property by also controlling the NAVIGABLE property; however, there is no way to prevent the user from clicking into the item.
The following code:
app_item_property.set_property(itemid, ENTERABLE,
PROPERTY_ON);
is equivalent to:
set_item_instance_property(itemid, CURRENT_RECORD,
INSERT_ALLOWED, PROPERTY_ON);
set_item_instance_property(itemid, CURRENT_RECORD,
UPDATEABLE, PROPERTY_ON);
set_item_instance_property(itemid, CURRENT_RECORD,
NAVIGABLE, PROPERTY_ON);
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON);
set_item_property(itemid, UPDATEABLE, PROPERTY_ON);
set_item_property(itemid, NAVIGABLE, PROPERTY_ON);
If the item is currently hidden, no action is taken.
Item and item-instance values are both set to make sure the effect of both of them produces the desired result.
The following code:
app_item_property.set_property(itemid, ENTERABLE,
PROPERTY_OFF);
is equivalent to:
set_item_instance_property(itemid, CURRENT_RECORD,
INSERT_ALLOWED, PROPERTY_OFF);
set_item_instance_property(itemid, CURRENT_RECORD,
UPDATEABLE, PROPERTY_OFF);
set_item_instance_property(itemid, CURRENT_RECORD,
NAVIGABLE, PROPERTY_Off);
If the item is currently hidden, no action is taken.
The DISPLAYED property handles displaying and hiding items as well as resetting certain properties that Oracle Forms automatically sets when an item is hidden.
The following code:
app_item_property.set_property(itemid, DISPLAYED,
PROPERTY_ON);
is equivalent to:
set_item_property(itemid, DISPLAYED, PROPERTY_ON);
If the item is not a display item then also set:
set_item_property(itemid, ENABLED, PROPERTY_ON); set_item_property(itemid, NAVIGABLE, PROPERTY_ON);
If the item is neither a display item nor a button then also set:
set_item_property(itemid, QUERYABLE, PROPERTY_ON); set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON); set_item_property(itemid, UPDATEABLE, PROPERTY_ON);
The following code:
app_item_property.set_property(itemid, DISPLAYED,
PROPERTY_OFF);
is equivalent to:
set_item_property(itemid, DISPLAYED, PROPERTY_OFF);
The ENABLED property is primarily intended to disable an item that will never apply during the entire session of the form. It differs from the native Oracle Forms behavior in that when items are re-enabled certain properties that Oracle Forms set automatically are reset.
The following code:
app_item_property.set_property(itemid, ENABLED,
PROPERTY_ON);
is equivalent to (for a text item or a list item):
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON); set_item_property(itemid, UPDATEABLE, PROPERTY_ON); set_item_property(itemid, NAVIGABLE, PROPERTY_ON);
If the item is a button, then the APP_ITEM_PROPERTY.SET_PROPERTY call is equivalent to:
set_item_property(itemid, ENABLED, PROPERTY_ON);
If the item is not a text item, list, or button, then the APP_ITEM_PROPERTY.SET_PROPERTY call is equivalent to:
set_item_property(itemid, ENABLED, PROPERTY_ON); set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON); set_item_property(itemid, UPDATEABLE, PROPERTY_ON);
If the item is a display item or is currently hidden, then no action is taken.
The following code:
app_item_property.set_property(itemid, ENABLED,
PROPERTY_OFF);
is equivalent to (for a text item or list item):
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_OFF); set_item_property(itemid, UPDATEABLE, PROPERTY_OFF); set_item_property(itemid, NAVIGABLE, PROPERTY_OFF);
If the item is neither a text item nor a list then:
set_item_property(itemid, ENABLED, PROPERTY_OFF);
If the item is a display item or is currently hidden, then no action is taken.
The REQUIRED property sets whether an item is required or not, while adjusting for whether the field is currently hidden. The REQUIRED property is an item-level property (affects all rows of the block). If the REQUIRED property must change on a per-record basis, you must reset the property as the cursor moves between the rows (typically in the WHEN-NEW-RECORD-INSTANCE trigger). Alternatively, you may prefer to call the native Oracle Forms built-in routine SET_ITEM_INSTANCE_PROPERTY to set the REQUIRED property on a row-by-row basis. Oracle Applications does not currently provide a cover routine for SET_ITEM_INSTANCE_PROPERTY.
The following code:
app_item_property.set_property(itemid, REQUIRED,
PROPERTY_ON);
is equivalent to:
set_item_property(itemid, REQUIRED, PROPERTY_ON);
If the item is currently hidden, no action is taken.
The following code:
app_item_property.set_property(itemid, REQUIRED,
PROPERTY_OFF);
is equivalent to:
set_item_property(itemid, REQUIRED, PROPERTY_OFF);
Oracle Forms supports setting properties such as INSERT_ALLOWED, UPDATEABLE and NAVIGABLE at both the item level (all records) and item-instance level (just a particular row). A precedence is applied between these two levels to determine the net effect to the user. Thus, if a setting is OFF at the item-level, but ON at the item-instance level, the net effect is that it is OFF. For this reason, exercise caution when setting properties that involve multiple levels. For example, mixing ALTERABLE and ENABLED calls on the same widget may not produce the desired effect.
While working in the Form Builder be aware that setting the Enabled property to No on a text item or list item does not automatically exhibit the same behaviors as the runtime equivalent set through APP_ITEM_PROPERTY.SET_PROPERTY. Instead, you must set the Insert Allowed, Update Allowed, and Keyboard Navigable properties of the item to No, and keep the Enabled property set to Yes.
Behaviors such as ALTERABLE and ENTERABLE can only be achieved at runtime because they rely on item-instance properties that can only be set programmatically.
Unlike most Oracle Applications visual attributes that are applied as part of a property class or are applied automatically by APPCORE routines, the following visual attributes must be applied programmatically by the developer.
The DATA_DRILLDOWN visual attribute makes the contents of a text item appear in green with an underline. Applied programmatically, this visual attribute can be used to simulate a hypertext link for "drilldown" purposes. It only changes the appearance of the text; it does not perform any linking logic.
DATA_SPECIAL applies the color red on white to a field that needs special emphasis because it contains a value that violates a business rule or requires the user's close attention. For example, negative values in financial forms should be red on white. This visual attribute is ordinarily only applied at runtime.
Warning: Any use of color coding should augment an indicator that functions in a monochrome environment.
Oracle Applications do not use the DATA_REQUIRED visual attribute.