Progress
Language Tutorial
for Character


Referencing Widgets

A field or variable name is both a valid reference to the value associated with the field or variable and to the widget associated with the field or variable. For example, in the first statement below, referencing Field1 and Variable1 in an expression manipulates their values. In the second and third statements, referencing the names in a screen I/O statement manipulates the widgets associated with them. Review these statements in the following code:

New-Total = Field1 + Variable1.
ENABLE Field1 Variable1 WITH FRAME Frame1.
HIDE Field1 IN FRAME Frame1 Variable1 IN FRAME Frame1 

This example also demonstrates the difference between using the frame phrase or IN FRAME to make an unambiguous reference to a widget. A single screen I/O statement can only work with the widgets in one frame. Thus the reference to the frame in the frame phrase creates an unambiguous reference to all widgets in the frame. On the other hand, you can append the
IN FRAME syntax to any widget reference in any other statement to make a single widget reference unambiguous.

Referencing Widget Attributes

You also use the IN FRAME syntax to make unambiguous widget attribute references. Recall that the basic syntax for accessing a widget attribute is as follows.

SYNTAX
widget-name:attribute-name 

You append the IN FRAME syntax to the widget attribute reference to make the reference unambiguous, as follows:

SYNTAX
widget-name:attribute-name IN FRAME frame-name 

For example, the assignment statement below assigns an attribute value to a variable:

Myvar = Mywidget:ROW IN FRAME Myframe 

Referencing Widget Methods

A method is a function associated with a particular type of widget that you access to manipulate an individual widget. You access methods in the same way that you access attributes.

SYNTAX
widget-name:method-name( ) IN FRAME frame-name 

Like a function, a method always returns a value. For methods, that value is usually LOGICAL and indicates whether or not Progress successfully applied the method to the widget. Methods also may use input and output parameters like a function.

Later in the chapter you’ll see programming examples that use methods.

Using Widget Handles

Using the field or variable name as a reference to both value and widget is convenient and makes readable code. At times, you may need to specifically reference the widget and not its associated field or variable. In these cases, you need to provide the widget handle. A widget handle is a unique internal identifier for a widget. Every widget has an attribute named HANDLE that contains the widget handle for that widget.

To access the handle, use the syntax presented in this example:

Widgetname:HANDLE 

You may also want to save the handle of a widget in a variable. Since Progress supports widget handles as a separate data type, you need to specify the WIDGET-HANDLE data type in your DEFINE VARIABLE statements as this shows:

DEFINE VARIABLE Myhandle AS WIDGET-HANDLE. 

Progress maintains several global variables that contain widget handles. These variables are part of a group of language elements known as system handles. System handles allow you to access information about the system. Table 7–4 describes the system handles that you can use to access information about widgets.

Table 7–4: Widget System Handles 
System Handle
Description
DEFAULT-WINDOW
Contains the widget handle of the window that all Progress applications create by default. In single-window applications, the default window is the only window. In multiple-window applications, you can choose to make another window the default window.
CURRENT-WINDOW
Contains the widget handle of the currently active window.
FOCUS
Contains the handle of the widget that currently has input focus.
SELF
Contains the handle of the widget for which a trigger is currently executing.

Widget Referencing Programming Example

The following exercise demonstrates widget referencing and system handles:

  1. Open lt-07-02.p and run it. The following display appears:
  2. Press TAB or use the mouse to move input focus or choose a button. Notice that the variables at the top of the screen keep track of your actions.
  3. Choose Exit and press SPACEBAR to return to the Procedure Editor.

Here is the code for this procedure:

lt-07-02.p
      /**********  DEFINE WIDGETS  **********/ 
      DEFINE VARIABLE Where-focus AS CHARACTER 
          LABEL "Input focus is currently on" VIEW-AS TEXT.
      DEFINE VARIABLE Which-chosen AS CHARACTER 
          LABEL "Last button chosen" VIEW-AS TEXT.
      DEFINE BUTTON Button1.
      DEFINE BUTTON Button2.
      DEFINE BUTTON Button3.
      DEFINE BUTTON Exit.
   
      /**********  DEFINE FRAMES  **********/ 
/*1*/  DEFINE FRAME Frame1
          SKIP(1)
          Where-focus SKIP
          Which-chosen SKIP
              WITH SIDE-LABELS NO-BOX CENTERED THREE-D.
/*2*/  DEFINE FRAME Frame2
          SKIP(1)
         Button1 Button2 Button3 Exit SKIP
              WITH NO-BOX CENTERED THREE-D.
                
      /**********  DEFINE TRIGGERS  **********/
/*3*/  ON ENTRY OF Button1 IN FRAME Frame2, Button2 IN FRAME Frame2,
                  Button3 IN FRAME Frame2, Exit IN FRAME Frame2
       DO:
/*4*/      APPLY "ENTRY" TO SELF.
/*5*/      ASSIGN Where-focus = FOCUS:LABEL.
/*6*/      DISPLAY Where-focus WITH FRAME Frame1.
       END.
/*7*/  ON CHOOSE OF Button1 IN FRAME Frame2, Button2 IN FRAME Frame2,
                 Button3 IN FRAME Frame2
       DO:
/*8*/      ASSIGN Which-chosen = SELF:LABEL.
           DISPLAY Which-chosen WITH FRAME Frame1.
       END. 
      /**********  MAIN LOGIC  **********/
      VIEW FRAME Frame1.
      ENABLE ALL WITH FRAME Frame2.
      WAIT-FOR CHOOSE OF Exit IN FRAME Frame2. 

The following notes describe the code highlights:

  1. The first frame contains the text widgets that track the user’s actions.
  2. The second frame contains the buttons.
  3. This trigger executes when any of the four buttons receive the ENTRY event. Notice the IN FRAME syntax for specifying the location of the widgets.
  4. The ENTRY event occurs before Progress actually moves input focus. This APPLY statement forces Progress to fully move focus to the new widget. Notice the SELF system handle. No matter which button executes the trigger, Progress evaluates this statement using the correct button.
  5. You can access an attribute of FOCUS or SELF exactly as you would with an explicit widget reference.
  6. On this screen I/O statement, the frame phrase option specifies the correct frame.
  7. Choosing any button except Exit executes this trigger.
  8. Again, you access the system handle attribute exactly as you would a named widget.

Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095