Controlling Canvases in Forms Programmatically

This article describes how to control canvases in Forms programmatically. It covers the triggers and built-ins that you can use to manage the properties and behavior of canvases at run-time and describes how to:

     — Control canvases in the forms

     — Manipulate canvases in the forms

     — Manipulate tab canvases

Contents:

1. What are the Built-ins for manipulating canvases?

2. What triggers are required to work with tab-style canvases?

3. What are the tab canvas system variables?

4. What are the built-ins for manipulating tab-style canvases?

5. Other Arguments for Canvas Built-ins

6. Modifying the when-tab-page-changed trigger to change the label on the tab canvas

 

1. What are the Built-ins for manipulating canvases?

The following built-ins are used for manipulating canvases:

Find_canvas returns the internal canvas ID(of datatype CANVAS) of a canvas with the given name.

Find_View returns the internal view ID (of datatype VIEWPORT) of a canvas with the given name.

Get_Canvas_property returns the current value of the specified Canvas property for the given canvas.

Get_View_property returns the current value of the specified View property for the canvas.

Hide_View hides the canvas.

Replace_Content_View replaces the content canvas currently displayed in the window with the specified content canvas.

Scroll_view moves the view of a given canvas to a different position on its canvas. It does not move the window to a different position on the screen.

Set_canvas_property sets the specified Canvas property for the given canvas to a specified value.

Set_view_property sets the specified View property for the given canvas to a specified value.

Show_view makes the given canvas visible at the current display position.

Note: Replace_content_view does not hide the stacked canvas already displayed in the window, whereas show_view and Set_view_property (with the visible property) display the given canvas in front of any stacked canvas.

 

2. What triggers are required to work with tab-style canvases?

The When-tab-page-changed form-level trigger fires when there is explicit item or mouse navigation from one tab page to another in a tab canvas.  In other words, when the user clicks a tab or presses the [control] + [PageUP] or [control] + [PageDown] keys.

This trigger is often used to perform actions when any tab page is changed during item or mouse navigation; for instance, to enable or disable items or to set default or related item values.

Note: This trigger does not fire when the tab page is changed programmatically and does not fire with implicit navigation.

 

3. What are the tab canvas system variables ?

Within the when-tab-page-changed trigger, you can reference the following system variables to determine where you are coming from and going to:

:SYSTEM.TAB_NEW_PAGE returns the name of the tab page to which you are going

:SYSTEM.TAB_PREVIOUS_PAGE returns the name of the tab page that you are coming from

These system variables return only the page name, not the canvas name, so you must name all tab pages uniquely across the form if you need to be able to identify them programmatically.

Note: When changing to another tab page, the cursor does not automatically move to a different item. If you want to move the cursor, you must include a GO_ITEM statement in the when-tab-page-changed trigger. This is intended functionality which allows users to view other tab pages without navigating the cursor and thereby causing item navigating and validation as previously mentioned.

 

4. What are the built-ins for manipulating tab-style canvases?

The following built-ins are used for manipulating tab-style canvases:

Find_tab_page searches the list of tab pages in a given tab canvas and returns a tab page ID when it finds a valid tab page with the given name. You must define a variable of type TAB_PAGE to accept the return value.

Set_tab_page_property sets the tab page properties (ENABLED, LABEL, VISIBILE, VISUAL_ATTRIBUTE) of the specified tab canvas page.

Get_tab_page_property returns property values (CANVAS_NAME,  ENABLED,LABLE, VISIBLE, VISUAL_ATTRIBUTE) for a specified tab page.

Get_canvas_property identifies the topmost tab page;

Set_canvas_property brings a page to the top programmatically.

Get_tab_page_property returns the tab page label or the tab page canvas while

Set_tab_page_property enables changing of the tab page label.

 Here is an example:

DECLARE

       Tp_id tab_page;

BEGIN  

       Tp_id :=find_tab_page(‘canvas2.tabpage1’);

       IF      GET_TAB_PAGE_PROPERTY(tp_id, enabled) = ‘False’    THEN

               SET_TAB_PAGE_PROPERTY(tp_id, enabled, property_true);

       END IF;

END;

 

5. Other Arguments for Canvas Built-ins

If you want to make a tab page the top-most on its underlying tab canvas, you can use the built-in procedure SET_CANVAS_PROPERTY and set the canvas property TOPMOST_TAB_PAGE.  You can also get the top-most

tab page using the built-in function GET-CANVAS-PROPERTY. For example:

GET_CANVAS_PROPERTY(‘canvas_name’, TOPMOST_TAB_PAGE)

SET_CANVAS_PROPERTY(‘canvas_name’, TOPMOST_TAB_PAGE, page_name)

Where page_name is either a constant, in single quotes, or a variable.

 

6. Modifying the when-tab-page-changed trigger to change the label on the tab canvas

This example shows how to modify the when-tab-page-changed trigger to change the label (for example, “Comment”) on the tab page. That is, when “Comment” is topmost page, change its label to, for example,

“Employee XX…”, where XX is the employee’s ID number. When any other tab page is topmost, change the label back to the original tab name (in this case, “Comment”.) You would use the following code in the When-Tab-Page-Changed trigger:

:control.help_tab := ‘Displays ‘|| Initcap(:SYSTEM.TAB_NEW_PAGE) || ‘ information about —‘ ;

IF :SYSTEM.TAB_NEW_PAGE = ‘COMMENT’ THEN

 SET_TAB_PAGE_PROPERTY(‘CANVAS2.COMMENT’, LABEL, ‘Employee ‘ || :EMP.ID);

ELSE

 SET_TAB_PAGE_PROPERTY(‘CANVAS2.COMMENT’, LABEL, ‘Comment’);

END IF;

Note: Where control.help_tab is block_name.item.name, when you click on Comment TAB, its title changes to “Employee” instead. This is to change the TAB label when you navigate to that TAB. Then, when you navigate out of that TAB, the original label returns. As you long as you do not navigate to that tab, its original title is kept and still there.