Oracle forms les22

Editor's Notes

• #3: Introduction Overview Forms Builder has a variety of features that enable you to write code in a flexible, reusable way.
• #4: What Is Flexible Code? Flexible code is code that you can use again. Flexible code is often generic code that you can use in any form module in an application. It typically includes the use of system variables instead of hard-coded object names. Why Write Flexible Code? Writing flexible code gives you the following advantages: It is easier for you and others to maintain. It increases productivity.
• #5: Using System Variables for Current Context In this lesson, you use the system variables that provide the current status of the record, the block, and the form, as well as system variables that return the current input focus location. System Variables for Locating Current Input Focus Example The example above shows code that could be put in a When-Button-Pressed trigger to enable users to navigate to another block in the form. It tests the current block name, then navigates depending on the result. Note: Be sure to set the button’s Mouse Navigate property to No; otherwise the :SYSTEM.CURSOR_BLOCK will always be the block on which the button is located.
• #6: Using System Variables for Current Context (continued) System Variables for Locating Trigger Focus Uses for Trigger Focus Variables The variables for locating trigger focus are useful for navigating back to the initial block, record, and item after the trigger code completes. For example, the trigger code may navigate to other blocks, records, or items to perform actions upon them, but after the trigger fires, you may want the cursor to be in the same item instance that it was in originally. Because the navigation in the trigger occurs behind the scenes, the user will not even be aware of it. Note: The best way to learn about system variables is to look at their values when a form is running. You can examine the system variables by using the Debugger.
• #7: System Variables for Determining the Current Status of the Form You can use these system status variables presented in the previous lesson to write the code that performs one action for one particular status and a different action for another: SYSTEM.RECORD_STATUS SYSTEM.BLOCK_STATUS SYSTEM.FORM_STATUS The example in the slide performs a commit before clearing a block if there are changes to commit within that block.
• #8: Using Built-In Subprograms for Flexible Coding Some of Forms Builder built-in subprograms provide the same type of run-time status information that built-in system variables provide. GET_APPLICATION_PROPERTY The GET_APPLICATION_PROPERTY built-in returns information about the current Forms application. Example The following example captures the username and the operating system information: :GLOBAL.username := GET_APPLICATION_PROPERTY(USERNAME);:GLOBAL.o_sys := GET_APPLICATION_PROPERTY(OPERATING_SYSTEM); Note: The GET_APPLICATION_PROPERTY built-in returns information about the Forms application running on the middle tier. If you require information about the client machine, you can use a JavaBean.
• #9: Using Built-In Subprograms for Flexible Coding (continued) GET_BLOCK_PROPERTY The GET_BLOCK_PROPERTY built-in returns information about a specified block. Example To determine the current record that is visible at the first (top) line of a block: ...GET_BLOCK_PROPERTY(’blockname’,top_record)... GET_ITEM_PROPERTY The GET_ITEM_PROPERTY built-in returns information about a specified item. Example To determine the canvas that the item with the input focus displays on, use: DECLAREcv_name varchar2(30);BEGIN cv_name := GET_ITEM_PROPERTY(:SYSTEM.CURSOR_ITEM,item_canvas);...
• #10: SET_<object>_PROPERTY Built-Ins SET_ITEM_INSTANCE_PROPERTY The SET_ITEM_INSTANCE_PROPERTY built-in modifies the specified instance of an item in a block by changing the specified item property. Example The following example sets the visual attribute to VA_CURR for the current record of the current item: SET_ITEM_INSTANCE_PROPERTY(:SYSTEM.CURSOR_ITEM, VISUAL_ATTRIBUTE, CURRENT_RECORD, ’VA_CURR’); SET_MENU_ITEM_PROPERTY The SET_MENU_ITEM_PROPERTY built-in modifies the given properties of a menu item. Example To enable the save menu item in a file menu: SET_MENU_ITEM_PROPERTY(’FILE.SAVE’,ENABLED,PROPERTY_TRUE);
• #11: SET_<object>_PROPERTY Built-Ins (continued) SET_TAB_PAGE_PROPERTY The SET_TAB_PAGE_PROPERTY built-in sets the tab page properties of the specified tab canvas page. Example To enable tab_page_1, if it is already disabled, use: DECLAREtbpg_id TAB_PAGE; BEGINtbpg_id := FIND_TAB_PAGE(’tab_page_1’);IF GET_TAB_PAGE_PROPERTY(tbpg_id, enabled) = ’FALSE’ THEN SET_TAB_PAGE_PROPERTY(tbpg_id, enabled,property_true);END IF; END;
• #12: Referencing Objects by Internal ID Forms Builder assigns an ID to each object that you create. An object ID is an internal value that is never displayed. You can get the ID of an object by calling the built-in FIND_ subprogram appropriate for the object. The FIND_ subprograms require a fully qualified object name as a parameter. For instance, when referring to an item, use BLOCKNAME.ITEMNAME. The return values of the FIND_ subprograms (the object IDs) are of a specific type. The types for object IDs are predefined in Forms Builder. There is a different type for each object. Three Reasons for Using Object IDs Improving performance (Forms looks up the object only once when you initially call the FIND_ subprogram to get the ID. When you refer to an object by name in a trigger, Forms must look up the object ID each time.) Writing more generic code Testing whether an object exists (using the ID_NULL function and FIND_object)
• #13: Forms Builder FIND_ Built-Ins The table below lists some of the FIND_ subprograms, along with the object classes that use them and the return types they produce:
• #14: Declaring Variables for Object IDs To use an object ID, you must first assign it to a variable. You must declare a variable of the same type as the object ID. The following example uses the FIND_ITEM built-in to assign the ID of the item that currently has input focus to the variable id_var. Once you assign an object ID to a variable in a trigger or PL/SQL program unit, you can use that variable to reference the object, rather than referring to the object by name. DECLARE id_var item;BEGIN id_var := FIND_ITEM(:SYSTEM.CURSOR_ITEM);. . . END;
• #15: Declaring Variables for Object IDs (continued) The following two examples show that you can pass either an item name or an item ID to the SET_ITEM_PROPERTY built-in subprogram. The following calls are logically equivalent: SET_ITEM_PROPERTY(’ORDERS.order_id’,position,50,35); SET_ITEM_PROPERTY(id_var,position,50,35); You can use either object IDs or object names in the same argument list, provided that each individual argument refers to a distinct object. You cannot, however, use an object ID and an object name to form a fully qualified object_name (blockname.itemname). The following call is illegal: GO_ITEM(block_id.’item_name’); Note: Use the FIND_ built-in subprograms only when referring to an object more than once in the same trigger or PL/SQL program unit.
• #16: Using Object IDs Outside the Initial PL/SQL Block You have seen how object IDs are referenced within the trigger or program unit by means of PL/SQL variables. You can reference these PL/SQL variables only in the current PL/SQL block; however, you can increase the scope of an object ID. To reference an object ID outside the initial PL/SQL block, you need to convert the ID to a numeric format using an .id extension for your declared PL/SQL variable, then assign it to a global variable. Example The following example of trigger code assigns the object ID to a local PL/SQL variable (item_var) initially, then to a global variable (global.item): DECLARE item_var item;BEGIN item_var := FIND_ITEM(:SYSTEM.CURSOR_ITEM); :GLOBAL.item := item_var.id;END;
• #17: Using Object IDs Outside the Initial PL/SQL Block (continued) You can pass the global variable around within the application. To be able to reuse the object ID, you need to convert it back to its original data type. Example The following example shows the conversion of the global variable back to its original PL/SQL variable data type: DECLARE item_var item;BEGIN item_var.id := TO_NUMBER(:GLOBAL.item); GO_ITEM(item_var); END;
• #18: Referencing Items Indirectly By referencing items indirectly, you can write more generic, reusable code. Using variables instead of actual item names, you can write a PL/SQL program unit to use any item whose name is assigned to the indicated variable. You can reference items indirectly with the NAME_IN and COPY built-in subprograms. Note: Use indirect referencing when you create procedures and functions in a library module, because direct references cannot be resolved.
• #19: Referencing Items Indirectly (continued) Using the NAME_IN Built-in Function The NAME_IN function returns the contents of an indicated variable. The following statements are equivalent. The first one uses a direct reference to customer.name, whereas the second uses an indirect reference: IF :CUSTOMERS.cust_last_name = ’Welles’... In a library, you could avoid this direct reference by using: IF NAME_IN(’CUSTOMERS.cust_last_name’) = ’Welles’... The return value of NAME_IN is always a character string. To use NAME_IN for a date or number item, convert the string to the desired data type with the appropriate conversion function. For instance: date_var := TO_DATE(NAME_IN(’ORDERS.order_date’));
• #20: Referencing Items Indirectly (continued) Using the COPY Built-in Procedure The COPY built-in assigns an indicated value to an indicated variable or item. Unlike the standard PL/SQL assignment statement, using the COPY built-in enables you to indirectly reference the item whose value is being set. The first example in the slide shows copying using a direct reference to the form item. Using COPY with NAME_IN Use the COPY built-in subprogram with the NAME_IN built-in to indirectly assign a value to an item whose name is stored in a global variable, as in the second example in the slide.
• #21: Summary Use the following to write flexible code: System variables: To avoid hard-coding object names To return information about the current state of the form
• #22: Summary (continued) GET_<object>_PROPERTY built-ins, to return current property values for Forms Builder objects Object IDs, to improve performance Indirect referencing, to allow form module variables to be referenced in library and menu modules
• #23: Practice 22 Overview In this practice, you use properties and variables in the ORDGXX form to provide flexible use of its code. You also make use of object IDs. Populating product images only when the image item is displayed Modifying the When-Button-Pressed trigger of the Image_Button in order to use object IDs instead of object names Writing generic code to print out the names of blocks in a form and using the same code in two different forms Note: For solutions to this practice, see Practice 22 in Appendix A, “Practice Solutions.”
• #24: Practice 22 1.In the ORDGXX form, alter the code called by the triggers that populate the Product_Image item when the image item is displayed.Add a test in the code to check Product_Image. Perform the trigger actions only if the image is currently displayed. Use the GET_ITEM_PROPERTY built-in function. The code is contained in pr22_1.txt. 2.Alter the When-Button-Pressed trigger on the Image_Button so that object IDs are used.Use a FIND_object function to obtain the IDs of each item referenced by the trigger. Declare variables for these IDs, and use them in each item reference in the trigger. The code is contained in pr22_2.txt. 3.Create a button called Blocks_Button in the CONTROL block and place it on the Toolbar canvas. Label the button Show Blocks. Set its navigation and color properties the same as the other toolbar buttons.The code for the button should print a message showing what block the user is currently in. It should keep track of the block and item where the cursor was located when the trigger was invoked (:SYSTEM.CURSOR_BLOCK and :SYSTEM.CURSOR_ITEM). It should then loop through the remaining navigable blocks of the form and print a message giving the names (SYSTEM.current_block) of all the navigable blocks in the form. Finally, it should navigate back to the block and item where the cursor was located when the trigger began to fire. Be sure to set the Mouse Navigate property of the button to No. You may import the code for the trigger from pr22_3.txt. 4.Save, compile, and run the form to test these features. 5.The trigger code above is generic, so it will work with any form. Open the CUSTGXX form and define a similar Blocks_Button, labeled Show Blocks, in the CONTROL block, and place it just under the Color button on the CV_CUSTOMER canvas. Drag the When-Button-Pressed trigger you created for the Blocks_Button of the ORDGXX form to the Blocks_Button of the CUSTGXX form. Run the CUSTGXX form to test the button.