Oracle Forms: Set Item Property

SET_ITEM_PROPERTY built-in

Description

Modifies all instances of an item in a block by changing a specified item property. Note that in some cases you can get but not set certain object properties.

Syntax

SET_ITEM_PROPERTY (item_id ITEM, property NUMBER, value VARCHAR2);

SET_ITEM_PROPERTY (item_name VARCHAR2, property NUMBER, value VARCHAR2);

SET_ITEM_PROPERTY (item_id ITEM, property NUMBER, x NUMBER);

SET_ITEM_PROPERTY

(item_name     VARCHAR2,

property        NUMBER,

x                          NUMBER);

SET_ITEM_PROPERTY (item_id ITEM, property NUMBER,

x               NUMBER,

y               NUMBER);

SET_ITEM_PROPERTY (item_name VARCHAR2, property NUMBER,

x                 NUMBER,

y                 NUMBER);

Built-in Type  unrestricted procedure

Enter Query Mode  yes

Parameters

item_id                                      The unique ID that Form Builder assigned to the object when it created it. Use the   FIND_ITEM built-in to return the ID to a variable with datatype of ITEM.

item_name                                The name you gave the item when you created it.  Datatype is

VARCHAR2.

property                                    The property you want to set for the given item.  Possible properties are:

ALIGNMENT The text alignment (text and display items only).  Valid

values are ALIGNMENT_START, ALIGNMENT_END,

ALIGNMENT_LEFT, ALIGNMENT_ CENTER, ALIGNMENT_RIGHT.

AUTO_HINT Determines if Form Builder will display help hints on the status line automatically when input focus is in the specified item. Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

AUTO_SKIP Specifies whether the cursor should skip to the next item automatically when the end user enters the last character in a text item. Valid only for a text item. Valid values are PROPERTY_TRUE and

PROPERTY_FALSE.

BACKGROUND_COLOR  The color of the object’s background region.

BORDER_BEVEL Specifies the item border bevel for the specified item instance. Valid values are RAISED, LOWERED, or PLAIN (unbeveled).

Note: You cannot set BORDER_BEVEL if the item’s Bevel property is set to None in Form Builder.

CASE_INSENSITIVE_QUERY Specifies whether query conditions entered in the item should be case-sensitive. Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

CASE_RESTRICTION Specifies the case restriction applied to any text entered in the indicated text item. Valid values are UPPERCASE, LOWERCASE, or NONE.

COMPRESSSpecifies whether the sound data from a sound object should be compressed before Form Builder writes the data to the file. Valid values are COMPRESSION_ON, COMPRESSION_OFF, and ORIGINAL_SETTING (retain the default compression setting of the data).

CONCEAL_DATA Specify the constant PROPERTY_TRUE if you want the item to remain blank or otherwise obscured when the end user enters a value. Specify the constant PROPERTY_FALSE if you want any value that is typed into the text item to be visible.

CURRENT_RECORD_ATTRIBUTE Specifies the VARCHAR2 name of a named visual attribute to be associated with the given item. If the named visual attribute does not exist, you will get an error message.

CURRENT_ROW_BACKGROUND_COLOR The color of the object’s background region.

CURRENT_ROW_FILL_PATTERN The pattern to be used for the object’s fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

CURRENT_ROW_FONT_NAME The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

CURRENT_ROW_FONT_SIZE The size of the font, specified in points.

CURRENT_ROW_FONT_SPACING The width of the font, that is, the amount of space between characters (kerning).

CURRENT_ROW_FONT_STYLE  The style of the font.

CURRENT_ROW_FONT_WEIGHT The weight of the font.

CURRENT_ROW_FOREGROUND_COLOR The color of the object’s foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

CURRENT_ROW_WHITE_ON_BLACK Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

DIRECTION Specifies the layout direction for bidirectional objects. Valid values are DIRECTION_DEFAULT, RIGHT_TO_LEFT, LEFT_TO_RIGHT.

DISPLAYED Specifies whether the item will be displayed/enabled or hidden/disabled.

ECHO Specifies whether characters an end user types into a text item should be visible. When Echo is false, the characters typed are hidden. Used for password protection. Valid values are PROPERTY_TRUE and

PROPERTY_FALSE.

ENABLED Specifies whether end users should be able to manipulate an item. Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

Note: Setting Enabled to false will cause other item property settings to change. Consult the "Propagation of Property Changes" section for details.

FILL_PATTERN The pattern to be used for the object’s fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

FIXED_LENGTH Specifies whether the item’s value should be validated against the setting of the item’s Max Length property. When FIXED_LENGTH is true, the item is valid only if the number of characters in its value equals the Max Length setting. Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

FONT_NAME The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

FONT_SIZE The size of the font, specified in hundredths of a point (i.e., for a font size of 8 points, the value should be set to 800).

FONT_SPACING The width of the font, that is, the amount of space between characters (kerning).

FONT_STYLE The style of the font.

FONT_WEIGHT The weight of the font.

FOREGROUND_COLOR The color of the object’s foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

FORMAT_MASK Specifies the display format and input accepted for data in text items.

HEIGHT Specifies the height of the item.

HINT_TEXT Specifies the item-specific help text displayed on the message line at runtime. If the text specified is NULL, the original hint text, specified in Form Builder, will be restored.

ICON_NAME Specifies the file name of the icon resource associated with a button item having the Iconic property set to YES.

IMAGE_DEPTH Specifies the depth of color to be applied to an image item.

INSERT_ALLOWED In a new record, allows end user to insert items normally when set to PROPERTY_TRUE. Specify PROPERTY_FALSE to specify that the item does not accept modification, but is displayed normally (not grayed out). (Insert_Allowed does not propagate changes to the Enabled property.)

ITEM_IS_VALID Specifies whether the current item should be considered valid. Set to PROPERTY_TRUE or PROPERTY_FALSE.

ITEM_SIZE Specifies a width and height for the item as two numbers separated by a comma. Use the syntax that includes x, y.

KEEP_POSITION Specifies whether the Keep Cursor Position property should be true or false. When Keep Cursor Position is true, the cursor returns to the same position it was in when it left the text item. When Keep Cursor Position is false, the cursor returns to the default position in the text item. Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

LABEL Specifies the VARCHAR2 string that you want displayed as the label of the item. This property is only valid for items that have labels, such as buttons.

LOCK_RECORD_ON_CHANGE Specify the constant PROPERTY_TRUE if you want the record to be locked when this item is changed. Specify the constant PROPERTY_FALSE if you do not want the record locked when this item is changed. Use primarily when connecting to a non-ORACLE data source that does not have row-level locking.

LOV_NAME Specify the VARCHAR2 name of an LOV to be associated with the given item. If the LOV name does not exist, you will get an error message.

MERGE_CURRENT_ROW_VA Merges the contents of the specified visual attribute with the current row’s visual attribute (rather than replacing it).

MERGE_TOOLTIP_ATTRIBUTE Merges the contents of the specified visual attribute with the tooltip’s current visual attribute (rather than replacing it).

MERGE_VISUAL_ATTRIBUTE Merges the contents of the specified visual attribute with the object’s current visual attribute (rather than replacing it).

MOUSE_NAVIGATE Specifies whether Form Builder should navigate and set focus to the item when the end user activates the item with the mouse. Specify the constant PROPERTY_TRUE if you want the end user to be able to navigate to the item using the mouse. Specify the constant

PROPERTY_FALSE if you want a mouse click to keep the input focus in the current item.

NAVIGABLE Specify the constant PROPERTY_TRUE if you want the end user to be able to navigate to the item using default keyboard navigation. Specify the constant PROPERTY_FALSE if you want to disable default keyboard navigation to the item. (Keyboard Navigable does not propagate changes to the Enabled property.)

NEXT_NAVIGATION_ITEM Specifies the name of the item that is defined as the "next navigation item" with respect to this current item.

POPUPMENU_CONTENT_ITEM Specifies the setting for any of the OLE popup menu item properties:

POPUPMENU_COPY_ITEM

POPUPMENU_CUT_ITEM

POPUPMENU_DELOBJ_ITEM

POPUPMENU_INSOBJ_ITEM

POPUPMENU_LINKS_ITEM

POPUPMENU_OBJECT_ITEM

POPUPMENU_PASTE_ITEM

POPUPEMNU_PASTESPEC_ITEM

Specify the character string HIDDEN for the OLE popup menu item not to be displayed on the OLE popup menu. Specify the character string ENABLED for the OLE popup menu item to be displayed and enabled. Specify the character string DISABLED for the OLE popup menu item to be displayed and not enabled.

POSITION Specify the x, y coordinates for the item as NUMBERs separated by a comma. Use the syntax that includes x, y.

PREVIOUS_NAVIGATION_ITEM Specifies the name of the item that is defined as the "previous navigation item" with respect to this current item.

PRIMARY_KEY Specify the constant PROPERTY_TRUE to indicate that any record inserted or updated in the block must have a unique characteristic in order to be committed to the database. Otherwise, specify the constant PROPERTY_FALSE.

PROMPT_ALIGNMENT_OFFSET Determines the distance between the item and its prompt.

PROMPT_BACKGROUND_COLOR The color of the object’s background region.

PROMPT_DISPLAY_STYLE Determines the prompt’s display style, either PROMPT_FIRST_RECORD, PROMPT_HIDDEN, or

PROMPT_ALL_RECORDS.

PROMPT_EDGE Determines which edge the item’s prompt is attached to, either START_EDGE, END_EDGE, TOP_EDGE, or

BOTTOM_EDGE.

PROMPT_EDGE_ALIGNMENT Determines which edge the item’s prompt is aligned to, either ALIGNMENT_START, ALIGNMENT_END, or ALIGNMENT_CENTER.

PROMPT_EDGE_OFFSET Determines the distance between the item and its prompt as a VARCHAR2 value.

PROMPT_FILL_PATTERN The pattern to be used for the object's fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

PROMPT_FONT_NAME The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

PROMPT_FONT_SIZE  The size of the font, specified in points.

PROMPT_FONT_SPACING The width of the font, that is, the amount of space between characters (kerning).

PROMPT_FONT_STYLE  The style of the font.

PROMPT_FONT_WEIGHT  The weight of the font.

PROMPT_FOREGROUND_COLOR The color of the object's foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

PROMPT_TEXT  Determines the text label that displays for an item.

PROMPT_TEXT_ALIGNMENT Determines how the prompt is justified, either ALIGNMENT_START, ALIGNMENT_LEFT, ALIGNMENT_RIGHT, ALIGNMENT_CENTER, or

ALIGNMENT_END.

PROMPT_VISUAL_ATTRIBUTE Specifies the named visual attribute that should be applied to the prompt at runtime.

PROMPT_WHITE_ON_BLACK Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

QUERYABLE Specify the constant PROPERTY_TRUE if you want the end user to be able to initiate a query against the item. Specify the constant PROPERTY_FALSE if you want to disallow the use of the item in a query.

QUERY_ONLY Specify an item to be queried, preventing that item from becoming part of insert or update statements. QUERY_ONLY is applicable to text items, radio groups, and check boxes. Enclose the fully-qualified item name in single quotes.

REQUIRED Specify the constant PROPERTY_TRUE if you want to force the end user to enter a value for the item. Specify the constant PROPERTY_FALSE if the item is not to be required.

SHOW_FAST_FORWARD_BUTTON Specify the constant PROPERTY_TRUE to display the fast forward button on a sound item, PROPERTY_FALSE to hide it.

SHOW_PLAY_BUTTON Specify the constant PROPERTY_TRUE to display the play button on a sound item, PROPERTY_FALSE to hide it. Note that Form Builder will hide either play or record, but not both.

SHOW_RECORD_BUTTON Specify the constant PROPERTY_TRUE to display the record on a sound item, PROPERTY_FALSE to hide it. Note that Form Builder will hide either play or record, but not both.

SHOW_REWIND_BUTTON Specify the constant PROPERTY_TRUE to display the rewind button on a sound item, PROPERTY_FALSE to hide it.

SHOW_SLIDER Specify the constant PROPERTY_TRUE to display the slider on a sound item, PROPERTY_FALSE to hide it.

SHOW_TIME_INDICATOR Specify the constant PROPERTY_TRUE to display the time indicator button on a sound item, PROPERTY_FALSE to hide it.

SHOW_VOLUME_CONTROL Specify the constant PROPERTY_TRUE to display the volume control on a sound item, PROPERTY_FALSE to hide it.

TOOLTIP_BACKGROUND_COLOR The color of the object’s background region.

TOOLTIP_FILL_PATTERN The pattern to be used for the object’s fill region. Patterns are rendered in the two colors specified by Background Color and Foreground Color.

TOOLTIP_FONT_NAME The font family, or typeface, that should be used for text in the object. The list of fonts available is system-dependent.

TOOLTIP_FONT_SIZE The size of the font, specified in points.

TOOLTIP_FONT_SPACING The width of the font, that is, the amount of space between characters (kerning).

TOOLTIP_FONT_STYLE The style of the font.

TOOLTIP_FONT_WEIGHT The weight of the font.

TOOLTIP_FOREGROUND_COLOR The color of the object’s foreground region. For items, the Foreground Color attribute defines the color of text displayed in the item.

TOOLTIP_TEXT Determines the item’s tooltip text.

TOOLTIP_WHITE_ON_BLACK Specifies that the object is to appear on a monochrome bitmap display device as white text on a black background.

UPDATE_ALLOWED Specify the constant PROPERTY_TRUE if you want the end user to be able to update the item. Specify the constant PROPERTY_FALSE if you want the item protected from update.

UPDATE_COLUMN Specify the constant PROPERTY_TRUE if this column should be treated as updated, and included in the columns to be written to the database. Specify the constant PROPERTY_FALSE if this

column should be treated as not updated, and not be included in the columns to be written to the database.

UPDATE_NULL Specify the constant PROPERTY_TRUE if you want the end user to be able to update the item only if its value is NULL. Specify the constant PROPERTY_FALSE if you want the end user to be able to update the value of the item regardless of whether the value is NULL.

UPDATE_PERMISSION Use UPDATE_ ALLOWED when you run against non-ORACLE data sources. Specify the constant PROPERTY_TRUE to turn on the item’s UPDATEABLE and UPDATE_NULL properties. Specify the constant PROPERTY_FALSE to turn off the item’s UPDATEABLE and UPDATE_NULL properties.

VALIDATE_FROM_LIST Specifies that Form Builder should validate the value of the text item against the values in the attached LOV when set to PROPERTY_TRUE. Specify PROPERTY_FALSE to specify that Form Builder should not use the LOV for validation.

VISIBLE Specifies whether the indicated item should be visible or hidden.

Valid values are PROPERTY_TRUE and PROPERTY_FALSE.

Note: Setting Visible to false will cause other item property settings to change. Consult the "Propagation of Property Changes" section for details.

VISUAL_ATTRIBUTE Specify a valid named visual attribute that exists in the current form.

Note:  You cannot set the visual attribute for an image item.

WHITE_ON_BLACK  Specifies that the object is to appear on a

monochrome bitmap display device as white text on a black background.

WIDTH Specify the width of the item as a NUMBER.  The size of the

units depends on how you set the Coordinate System property and default

font scaling for the form.

X_POS  Specify the x coordinate as a NUMBER.

Y_POS  Specify the y coordinate as a NUMBER.

value                                          Specify the value to be applied to the given property.  The data type of the

property determines the data type of the value you enter.  For instance, if

you want to set the VISIBLE property to true, you specify the constant

PROPERTY_TRUE for the value.  If you want to change the LABEL for

the item, you specify the value, in other words, the label, as a VARCHAR2

string.

PROPERTY_TRUE Specifies that the property is to be set to the TRUE

state.

PROPERTY_FALSE Specifies that the property is to be set to the

FALSE state.

If you want to reset the value of the property to be the value originally

established for it at design time, enter two single quotes with no space

between:  ‘’.  For example, SET_ITEM_PROPERTY(‘DEPTNO’,

FORMAT_MASK, ‘’); would reset that format mask to its design-time

value.

x                                                  Specifies the NUMBER value of the x coordinate or the width, depending

on the property you specified.  Specify the argument in form coordinate

system units.

y                                                  Specifies the NUMBER value of the y coordinate or the height, depending

on the property you specified.  Specify the argument in form coordinate

system units.

Usage Notes

The following issues can affect your decisions on how to apply certain property values to an item:

·         validation of property changes

·         propagation of property changes

Validation of Property Changes When you specify a change through the SET_ITEM_PROPERTY built-in, Form Builder validates the change before it adjusts the property. If the change is validated, Form Builder makes the change and leaves it in effect until another SET_ITEM_PROPERTY changes the same property or the current form is exited.

Illegal Settings If the change is not validated, Form Builder issues an error message. You cannot use SET_ITEM_PROPERTY to set the following item properties true or false, given the following target item conditions.

You cannot set this              To this restricted setting

property parameter...

(All)                                         true/false

ENABLED                             true/false

true

INSERT_ALLOWED          true

true

NAVIGABLE                        true/false

true

If this target item condition is true:

·          NULL-canvas item (item's canvas property is null)

·          current item

·          Visible item property is false

·          Enabled item property is false

·          Visible item property is false

·          current item

·          Visible item property is false

QUERYABLE	true	·	Visible item
(Query Allowed)			property is false
UPDATE_ALLOWED	true	·	Enabled item
			property is false
	true	·	Conceal Data item
			property is true
UPDATE_NULL	true	·	Enabled item
(Update if NULL)			property is false
	true	·	Conceal Data item
			property is true
VISIBLE	true/false	·	current item
		·

Form Builder does not consider the current contents of an item before allowing a property change. If SET_ITEM_PROPERTY changes an item property that would affect how Form Builder validates the data in an item (for example, FIXED_LENGTH or REQUIRED), the validation consequences are not retroactive. The new validation rules do not apply to the item until Form Builder next validates it under normal circumstances.

For example, suppose the application has a required text item, such as Employee ID. In the application, the end user needs to be able to leave this item (behavior not allowed for a REQUIRED item), so you temporarily set the REQUIRED property to False. At this point, Form Builder marks an existing NULL value as VALID. Later in the application, when you set the REQUIRED property to true again, Form Builder does not automatically change the VALID/INVALID marking. In order to have a NULL value marked as INVALID (expected for a REQUIRED item), you must make a change in the item that will cause Form Builder to validate it, such as:

IF :block.item IS NULL

THEN :block.item := NULL;

Propagation of Property Changes You can only specify a change to one item property at a time through the SET_ITEM_PROPERTY built-in. However, one SET_ITEM_PROPERTY statement can cause changes to more than one item property if the additional changes are necessary to complete, or propagate, the intended change. This is included primarily for compatibility with prior versions.

The following table shows the SET_ITEM_PROPERTY settings that cause Form Builder to propagate changes across item properties:

Setting this property	To this setting	Also causes these
parameter...		propagated changes:
ENABLED	False	·	sets the Navigable
			item property to
			False
		·	sets the
			Update_Null item

DISPLAYED                         False

UPDATEABLE                    True

UPDATE_NULL                  True

property to False

·         sets the Updateable item property to False

·         sets the Required item property to False

·         sets the Enabled and Navigable item properties to False

·         sets the Updateable item property to False

·         sets the Update_Null item property to False

·         sets the Required item property to False

·         sets the Queryable item property to False

·         sets the Update_Null item property to False

·         sets the Updateable item property to False

SET_ITEM_PROPERTY examples

/*

**  Built-in:  SET_ITEM_PROPERTY

**  Example:   Change the icon of an iconic button dynamically

**                   at runtime by changing its icon_name. The user

**                   clicks on this button to go into enter query

**                   mode, then clicks on it again (after the icon

**                   changed) to execute the query. After the query

**                   is executed the user sees the original icon

**                   again.

**  trigger:   When-Button-Pressed

*/

DECLARE

it_id Item;

BEGIN

it_id := Find_Item(’CONTROL.QUERY_BUTTON’); IF :System.Mode = ’ENTER-QUERY’ THEN

/*

**  Change the icon back to the enter query icon, and

**  execute the query.

*/ Set_Item_Property(it_id,ICON_NAME,’entquery’); Execute_Query;

ELSE /*

**  Change the icon to the execute query icon and get

**  into enter query mode.

*/ Set_Item_Property(it_id,ICON_NAME,’exequery’); Enter_Query;

END IF; END;