Attributes can also be set during the running of the application by using the SETATR operation code or the %SETATR built-in function. To query the value of an attribute in the application, use the GETATR operation code or the %GETATR built-in function. If you are not familiar with these new enhancements to the language definition, please refer to our article on the 'VRPG Language definition' published in a previous issue of this newsletter.

Events are actions that can be performed on a part. Examples of common events are: create (occurs when the part is created), destroy (occurs when the window that contains the part is destroyed), and press (occurs when the mouse is clicked on top of a button). Events have action subroutines, delimited with the operation codes BEGACT and ENDACT pair, associated with them. When an event occurs, the action subroutine coded for that event is executed. To see what events are associated with a part, click on the part with the right mouse button and select the "Events" menu item (see Figure 2.).

Figure 2. Audio Window Canvas and Events Pop-Up Menu.

The best way to describe how to build a window using the GUI Designer is to show an example. First, we need to start the Designer. Either double-click on the VRPG GUI Designer icon or drag and drop an existing project on the Designer icon. Once the Designer is up, we start building a window by first dragging a window part, from the palette, onto the GUI Designer desktop.

We will create an application to play .MID/.WAV files. In this example, we picked a simple function that you can implement using the VRPG product which you could not do using the typical 5250 screens and the RPG language on the AS/400. This is just to illustrate the additional functionality that VRPG provides. This application consists of a single window (or record format using the DDS terminology). On that window we will need an entry field to enter the sound file that is to be played, a static text part to add text that describes to the user what to type into the entry field, a media part to play and stop playing the file, a push button to end the application, and an audio part for actually playing the file. Drag each part from the Parts Palette onto the window. The following table shows each part used in this application and any changes that should be made to each part's attributes via its notebook (remember to get the notebook for a part, double click on the part).

Table 1. Notebook Changes for Each Part

PART ATTRIBUTE & VALUE

Window Part name - Win

Static Text Text - Audio File to Play

Entry Field Part name - ENTRYFLD

Text - blank

Data Length - 50

Media Panel Part Part name - MPP

Click off all buttons but the Play and Stop buttons on the Style page.

Check Enable notify target

Link Target Part name - AUDIO

Link Target Parent part name - WIN

Push Button Part name - PBEND

Label - End

Background Color - Red

Audio Part name - AUDIO

Check Initial state - Not visible

The table illustrates all the parts we need for this application. The window, which is similar to a record format is used so that we can place all parts needed for this application in it. The static text part is used as a label for the entry field to indicate to the user that the entry field is used to enter the audio file name. The push button is used to allow the user to terminate the application. That is the subroutine attached to this button will simply set the Last Indicator (LR) on.

The two more interesting parts used are the audio part and the media panel part. The audio part plays or records audio file information. If its visible attribute is on, it is displayed as an icon. In most applications, you will turn off the visibility attribute and link it to a media panel part whose main purpose is to provide a nice user interface. Note that parts that have visibility turned off still show up as an icon on the window canvas in the Designer but when the application is run, they will not be visible to the user. So the initial state of the audio part is not visible because, as we mentioned, the audio part is used for its functionality and not its user interface. For the user interface we linked the media panel part to the audio part. This causes a LINK event to be triggered for the audio part whenever the media panel part is pressed. In the LINK event action subroutine for the audio part, we can then check to see which button of the media panel part was pressed and take the appropriate action. The media panel part attribute PANELITEM gives us a numeric value from 0 to 10 that indicates which button on the media panel was pressed.

The following table illustrates the different values for this attribute:

Creating the Application Code

After creating the window with its parts and making any changes to part attributes, we are ready to add the different VRPG action subroutines that will make our user interface work. To code an action subroutine, we click on the part we want to write the routine for and we will see a pop-up menu with an item of Events. If you choose Events, you will see all the possible events that can be triggered for that part Figure 2. shows the events for the audio part in our example window. In this case, we have moved the mouse to the audio part and clicked on the right hand mouse button. The event we pick for our example is the LINK event.

Code is written for a VRPG application in pieces where each piece is associated with a window, part, and event. For example, when we enter the editor for the audio part and the link event, we are presented with the BEGACT and ENDACT pair for the action subroutine that is triggered when the link event occurs. The editor that is used by VRPG is called the Live Parsing Editor (LPEX). Figure 3. shows the LPEX editor and the prompter while editing an action subroutine.

Figure 3. LPEX Editor and Prompter.

If you are familiar with CODE/400, you will be familiar with the LPEX editor since it is the same editor. This powerful source editor is custom designed for the RPG user. It comes with features such as syntax checking, token highlighting, and specification prompting. These features provided with the LPEX editor make programming VRPG applications easier and improve the programmer's productivity. For example, when the syntax checker detects an error, LPEX puts up Error List window. The Error List window contains a list of errors for each syntax error in your LPEX edit session. As each syntax error is corrected, the error entry in the Error List window has a check mark placed beside it. Token highlighting allows you to have different colors for the different columns (such as factor 1, opcode, factor 2, and the result field). This can make the code easier to read. In addition, like the Source Entry Utility (SEU) on the AS/400, the LPEX editor provides you with prompting for all of the VRPG specifications using a graphical interface. Obviously, there is much more that can be said about the functionality of LPEX but space considerations, for this article, don't allow us to go into more detail.

After we have entered the code for each action subroutine that we need, we have the following audio player application:

*******************************************************************

* Program ID . . : Audio Player *

*******************************************************************

*

H

Dbutton s 2p 0

*

* User wants to end the application

C PBEND BEGACT PRESS WIN

C seton lr

C ENDACT

*

* User has pressed a button on the media panel

C AUDIO BEGACT LINK WIN

C eval button=%getatr('Win':'MPP':'PanelItem')

C select

C when button = 2

C exsr play

C when button = 4

C exsr stop

C endsl

C ENDACT

*

* Play the audio file

C PLAY BEGSR

C 'ENTRYFLD' getatr 'text' filename 50

C 'audio' setatr filename 'filename'

C 'audio' setatr 2 'audiomode'

C 'mpp' setatr 2 'PanelMode'

C ENDSR

*

* Stop playing the audio file

C STOP BEGSR

C 'audio' setatr 4 'audiomode'

C 'mpp' setatr 4 'PanelMode'

C ENDSR

As we mentioned earlier, each action subroutine is associated with different events, actions, and parts. Lets examine the source code shown in the previous figure.

The first action subroutine for the PRESS event (specified in factor 2) and PBEND part (specified on factor 1) for window name WIN (specified in the result field) is triggered when the End push button is pressed. To end the application, we simply turn the Last Record (LR) indicator on.

The second action subroutine, which is the main routine in this application, is triggered whenever the media part is pressed. Remember that at build time we linked the media part panel to the audio part. This is why when you press on the media part panel the LINK event of the audio part is activated. In this action subroutine, we get the id of the item that was pressed on the media panel using the PANELITEM attribute. This attribute gives you a value of 0 to 10 (see the list of values we gave earlier for more detail). If the id is 2, the play button was pressed and if the id is 4, the stop button was pressed. In each case we branch to the appropriate subroutine.

The first general subroutine, PLAY, reads the entry field (TEXT attribute of the ENTRYFLD part) and sets the FILENAME attribute of the audio part. Remember that the user will enter the file name for a sound file he wants to play in this entry field. It then sets the AUDIOMODE attribute of the audio part to 2 (for play) and the PANELMODE attribute of the media part to 2 (for play mode) using the SETATR operation code. Note that both of these attributes for these two parts must be changed as a pair. When the AUDIOMODE is set to 2, the audio part will play the file specified by its FILENAME attribute. When the PANELMODE of the media part is set to 2, the play button of the media panel is disabled and the stop button is enabled.

The STOP subroutine sets the AUDIOMODE of the audio part and the PANELMODE of the media part to 4 for stop mode. The audio player will stop playing the file and the stop button of the media panel will be disabled and the play button enabled.

As you can see, the amount of code required to implement such a powerful application is very minimal. In fact, learning how to implement such an application is easy.

Summary

This conclude our series of articles on the VRPG product. This article illustrated to you how to create a Graphical User Interface using the VRPG GUI Designer and hopefully showed you how easy it is to implement very powerful GUI applications with a language that is very much familiar to all of you. Obviously, there is a lot more functionality to VRPG than what we have shown in these articles. We have only skimmed the surface of information about this exciting product.

We will, in future articles, describe what will be available in the next release of VRPG which is scheduled for the end of this year.

For more information on VRPG and other IBM products, surf the IBM home page (URL http://www.ibm.com).
T < G

George Farr has a specialized honors degree from York University. He has been a member of the IBM Toronto Lab since May 1985. Since he joined the lab, he has been a member of the AS/400 RPG language team. He is a frequent speaker at COMMON and other conferences and has written numerous articles on the subject of AS/400 languages. He recently co-authored a book on ILE - 'ILE - A FIRST LOOK'. He is currently the development manager for the VRPG compiler. George can be reached via e-mail at gfarr@vnet.ibm.com .

Scott Ripley has a computer science degree from the University of New Brunswick. He has been a member of the IBM Toronto Lab since May 1985. He has worked on the run-time for the Ada, C, and VRPG compilers. Scott presently is a member of the VRPG development team. He can be reached via e-mail at ripper@vnet.ibm.com.

Back to top of page.
Back to TUG/400 menu.
Back to TUG's main page.