Tutorial - Using the Sample Screenset

Tutorial - Adding and Customizing a Menu Bar and Toolba

Chapter 20: Tutorial - Adding and Customizing a Status Bar

This tutorial takes you through adding the status bar control program to the sample Customer screenset supplied with Dialog System. You use the same steps to add a status bar to any window in any screenset. The same principles apply to adding any other control program to a screenset. You will find out how to:

• Add a status bar to the screenset.

• Run the screenset.

• Manipulate the status bar.

• Register Events for the Status Bar

Before starting this tutorial you should have:

• Read through the chapter Programming Your Own Controls.

The user control objects and control programs are also documented in:

• Objects and Properties in the Help.

  The topic on user controls describes how to create a user control and set its properties.

• Control programs in the Help.

  The topics in this section give detailed information on the control programs and the functions available.

• The COBOL source code itself.

A separate demonstration of using a status bar control program is provided in the screenset sbards.gs, and is documented in the file sbards.txt in your DialogSystem\demo\sbards subdirectory.

20.1 Setting Up

1. You will be using the Customer screenset, and making many changes to it, so we advise you to make a backup of customer.gs before starting.

2. Start NetExpress.

3. Open customer.app in your DialogSystem\demo\customer subdirectory.

4. Right-click on customer.gs in the left-hand pane, and select Edit from the context menu.

   Dialog System starts up and the Customer Details window is displayed.

20.2 Adding a Status Bar to the Screenset

Before using any of the control programs, a common data area must be defined in the screenset Data Block. This is used to pass information between a screenset and the control programs at run time.

20.2.1 Defining the Data Items

Each user control that you define in a screenset must have a Data Block item (master field) associated with it. The data item must be defined as OBJ-REF as it is used to hold the class library object reference of the created control. The data item must be defined before you add the user control. If you do not have any object references defined in your screenset, then Dialog System will not let you define a user control.

Include the following data item in the Data Block of the screenset, to hold the object reference of the status bar:

MAIN-WINDOW-SBAR-OBJREF          OBJ-REF

Include the following data definition for FUNCTION-DATA in the screenset Data Block:

FUNCTION-DATA                           1
  WINDOW-HANDLE                  C5     4.0
  OBJECT-REFERENCE               OBJ-REF
  CALL-FUNCTION                  X     30.0
  NUMERIC-VALUE                  C5     4.0
  NUMERIC-VALUE2                 C5     4.0
  SIZE-WIDTH                     C5     4.0
  SIZE-HEIGHT                    C5     4.0
  POSITION-X                     C5     4.0
  POSITION-Y                     C5     4.0
  IO-TEXT-BUFFER                 X    256.0
  IO-TEXT-BUFFER2                X    256.0

The FUNCTION-DATA definition can also be imported from the file funcdata.imp in the DialogSystem\source subdirectory. Select File, Import, Screenset and click OK to acknowlege the currently loaded screenset might be overwritten. Click the File button, double-click funcdata.imp, click the Import button and then OK and Close.

Since FUNCTION-DATA is common to all the control programs, you need define it only once in each screenset that uses the control programs.

20.2.2 Defining the Status Bar

When you have defined the required data, define the user control:

1. Select the Customer Details window, MAIN-WINDOW, to which you want to add the status bar.

2. Select User control on the Object menu.
   - or -
   Select User Control on the Objects toolbar.

3. Position and size the user control.

   The status bar control program does not use the position and size of the user control, as a status bar always appears at the bottom of a window. We therefore recommend that you position the user control for a status bar along the bottom of the window.

4. Complete the following items on the User Control Properties dialog box:
   • Choose an appropriate name for the user control. Make this as descriptive as possible, for example MAIN-WINDOW-STATUS-BAR.

   • Specify MAIN-WINDOW-SBAR-OBJREF as the master field name.

   • Specify SBAR2 as the name of the user control program.

   • Select Status Bar on the Control Type drop down list.

   • Check Add program to current project.

   • Click Generate to generate the User Control program sbar2.cbl.

     A message box appears, reminding you that you need to include the necessary entries in the Data Block for use by the generated control program. You have done this in the earlier steps, so click OK to continue.

     You can see the generated program being added to your Customer project in the background.

5. Click OK, save the screenset, and close it.

6. Return to NetExpress, right-click on customer.gs, and select Generate copyfile from the context menu.

7. Compile the generated control program using Rebuild All on the NetExpress Project menu to obtain an executable version of this program.

20.3 Running Your Screenset

Once you have completed all these steps with your screenset, you can run it to see the User Control working.

At this stage, the status bar will not do anything useful - the clock and key states on the status bar will not update.

You need to add dialog for the status bar updating to work correctly.

20.4 Manipulating the Status Bar

Each user control can be manipulated using the predefined functions in its control program. By setting FUNCTION-NAME and other parameters in FUNCTION-DATA you can perform actions on the control such as refreshing, deleting or updating data associated with it.

The following sections take you through implementing code that will maintain the state of information displayed in the status bar, including:

• Clock time.

• Insert/Caps/NumLock Key state information.

• Window/Status Bar section resizing.

• Mouse-over hint text.

20.4.1 Clock Time and Key State Maintenance

In order to maintain the accuracy of the clock and key state information, the status bar needs to be refreshed regularly. To do this, you need to use the timeout facility of Dialog System.

20.4.1.1 Using the Timeout Facility

To set the timeout, you need to add the WINDOW-CREATED event to the window containing the status bar (in this case MAIN-WINDOW).

• Select the Customer Details window and go to Object Dialog.

• Click the Event toolbar button and select WINDOW-CREATED.

Add the following line of dialog:

     TIMEOUT 25 REFRESH-STATUS-BAR

This dialog causes the REFRESH-STATUS-BAR procedure (which will be defined later) to be executed once every quarter of a second.

Note: If you try to debug the application using Screenset Animator, Screenset Animator will appear to execute the REFRESH-STATUS-BAR procedure in a loop. This is because it is difficult to interact with the application in the time between the last line of the REFRESH-STATUS-BAR being executed, and the time when the next timeout event is triggered (one quarter of a second later). For this reason, you may wish to adjust the timeout value, or remove this line altogether when debugging with Screenset Animator.

Next, you need to add the dialog to process the timeout event. In general, the procedure which is triggered when a timeout event occurs should be placed in global dialog. If you place the dialog on an object, and that object loses focus, the Dialog System run-time might no longer be able to find the timeout procedure (which will cause run-time error 8 to be generated).

The following dialog causes the status bar to be updated when the timeout event occurs (using the REFRESH-OBJECT function of the status bar control program). You must place this dialog in global dialog for it to work correctly.

   REFRESH-STATUS-BAR
     MOVE "REFRESH-OBJECT" CALL-FUNCTION(1)
     SET OBJECT-REFERENCE(1) MAIN-WINDOW-SBAR-OBJREF
     CALLOUT "SBAR2" 0 $NULL

20.4.2 Window/Status Bar Section Resizing

Next, you need to add dialog to resize the status bar correctly when the window is resized. The status bar control program has a RESIZE function which you need to call when the window is resized, maximized, or restored.

You do not need to call the function when the window is minimized, because the status bar is not visible when the window is minimized.

Note: In order to resize the window, it must have the Size Border property set.

Go to Object Dialog on the toolbar and add the following dialog to the window containing the status bar, to cause the status bar to resize when the window resizes:

 WINDOW-SIZED
     BRANCH-TO-PROCEDURE RESIZE-PROCEDURE

 WINDOW-RESTORED
     BRANCH-TO-PROCEDURE RESIZE-PROCEDURE

 WINDOW-MAXIMIZED
     BRANCH-TO-PROCEDURE RESIZE-PROCEDURE

   RESIZE-PROCEDURE
     MOVE "RESIZE" CALL-FUNCTION(1)
     SET OBJECT-REFERENCE(1) MAIN-WINDOW-SBAR-OBJREF 
     CALLOUT "SBAR2" 0 $NULL

20.4.3 Adding Mouse-over Hint Text

To have a fully functioning status bar, you need to update the text that appears in the status bar whenever the mouse moves over objects on the window. To do this you need to:

• Enable MOUSE-OVER events for the window containing the status bar (using the SET-PROPERTY dialog function).
  • Add the following line of dialog to the WINDOW-CREATED event:

         SET-PROPERTY MAIN-WINDOW "MOUSE-OVER" 1

    You will also need to add this dialog to any other window on which you require MOUSE-OVER events.

• Respond to the MOUSE-OVER events (when they are generated) by adding dialog to set the text on the status bar. The MOUSE-OVER text usually goes in the leftmost section (section number one) on the status bar.
  • Add the following dialog procedure to the global dialog:

       DISPLAY-HINT-TEXT
         MOVE "UPDATE-SECTION-TEXT" CALL-FUNCTION(1)
         MOVE 1 NUMERIC-VALUE(1)
         SET OBJECT-REFERENCE(1) MAIN-WINDOW-SBAR-OBJREF 
         CALLOUT "SBAR2" 0 $NULL

• Update the status line whenever a MOUSE-OVER event occurs on an object by adding dialog similar to the following for each object on the window which needs to update the status text:

     MOUSE-OVER
       MOVE "Status text" IO-TEXT-BUFFER(1)
       BRANCH-TO-PROCEDURE DISPLAY-HINT-TEXT

  Replace the words Status text with the text you want to appear on the status bar.

  For example, replace Status Text with Load Record for the LOAD push button on MAIN-WINDOW of the CUSTOMER screenset.

If you now run the screenset, you will see that the CUSTOMER screenset has a status bar which:

• Displays MOUSE-OVER text in section 1 of the status bar.

• Displays the key states of the INSERT, CAPS LOCK and NUM LOCK keys in sections 2, 3 and 4 of the status bar.

• Displays the current time in section 5 of the status bar.

Click Abort when you have finished looking at the screenset, save it and close Dialog System.

The next section shows you how to register events for the status bar.

20.5 Registering Events for the Status Bar

The status bar control program has code to handle the event generated when the user clicks the mouse over one of the sections on the status bar. The section Customizing the Status Bar Control Program shows how to customize the status bar control program to add another event.

The class library sends events to your application by means of a callback. For example, the status bar control program registers its entry point SBar2Button1Down with the class library so that whenever the user clicks the left mouse button over the status bar, the code in the entry point Sbar2Button1Down is executed.

Callback registration is performed after full creation of the control in the Create Entrypoint of the generated program. You should register a callback in the "Register-callbacks" section for all events for which you need to provide code.

When an event is generated, the callback code associated with the event can update the data in your Data Block to pass back to the Dialog System screenset. See the topic Control programs in the Help for information on how to pass data between the control programs and the Dialog System screenset.

This completes the steps required to add a status bar control program to any Dialog System screenset.

You can use similar steps to these to add any control program to any screenset, tailoring the dialog to your requirements.

20.6 Customizing the Status Bar Control Program

This part of the tutorial describes how to add functionality to a status bar so that when a user double-clicks on the clock section, you can receive a callback to process the event as required.

The status bar control program which you generated at definition time may be used 'as is' and is coded in such a way as to allow the creation and maintenance of many controls on as many windows as you require. You can however, add your own features.

Note: Each screenset that contains a status bar must use its own generated status bar control program. This is because each generated status bar control program contains code specific to the screenset for which it was generated.

For example, you might want to add an extra section to the status bar. As an example, this section shows you how to tailor the status bar control program to add an extra event.

For the purpose of this example, it is assumed you have generated a control program called sbar2.cbl, which you will now customize.

In all cases, you will need to ensure your tailored program is available on $COBDIR at run time.

20.6.1 Registering a Callback for the New Event

To add the left-mouse-button-double-click event to the status bar, you need to do two things:

• Add code to the Register-Callbacks section to register the new event.

• Add code to the control program to process the new event.

Registering a callback for the new event is very similar to the code for registering the callback for the left-mouse-button-down event. Before adding the callback registration code for the new event, it is worth explaining how the code for the new event works:

• MOVE ProgramID & "Button1Down " TO MessageName

  ---

  Note: The Program ID constant is used in the naming of the entry points in this program. This prevents different control programs loading duplicate names.

  ---

  Stores the name of the entry point that is to receive the callback (in this case, Button1Down) in MessageName.

• INVOKE EntryCallback "new" USING MessageName
                         RETURNING aCallback

  Creates a new callback object, using the entry point name specified above.

• MOVE p2ce-Button1Down TO i

  Stores the event number (p2ce-Button1Down) in the variable I. All of the available event numbers are listed in the file source\guicl\p2cevent.cpy in your NetExpress system.

• INVOKE aStatusBar "setEvent" USING i aCallback

  Sets the event (p2ce-Button1Down) to cause a callback to the entry point (ProgramID & "Button1Down").

• INVOKE aCallback "finalize" RETURNING aCallback

  The callback object is no longer required, so it can be deleted (finalized).

You can now add the code to register the callback for the new event. This is done by adding code to the Register-Callbacks section of the control program.

To add your left-mouse-button-double-click registration code:

1. Click on NetExpress.

2. Right-click on sbar2.cbl and select Edit from the context menu.

3. Insert the code below immediately after the registration code for the left-mouse-button-down event, before the comments.

   MOVE ProgramID & "DblClk1 " TO MessageName
   INVOKE EntryCallback "new" USING MessageName
                          RETURNING aCallback
   MOVE p2ce-Button1DblClk TO i
   INVOKE aStatusBar "setEvent" USING i aCallback
   INVOKE aCallback "finalize" RETURNING aCallback

20.6.2 Adding a Left-mouse-button-double-click Event

Since the left-mouse-button-double-click event is very similar to the left-mouse-button-down event, you can copy the existing code in the left-mouse-button-down section to add a new section which will process the event. The only code which is different between the events is the section and entry point names, and the user event number.

To add the code to process the new event, open sbar2.cbl for editing as above, and:

1. Duplicate all of the code in the section left-mouse-button-down. Call the new section LEFT-MOUSE-BUTTON-DBLCLK.

2. Change the name of the entry point in the LEFT-MOUSE-BUTTON-DBLCLK section from Button1Down to DblClk1.

3. Change the user event number in the LEFT-MOUSE-BUTTON-DBLCLK section from 34590 to 34591.

4. Save sbar2.cbl.

5. Rebuild the project.

Note: Please keep a note of the user events used and generated by the control programs used in your applications, so that duplication does not occur. Although you are not prevented from using duplicate user events, if you use the same user event for two different purposes on the same window, your program might not work as expected.

Once you have done this, you can add some additional dialog to make use of the new event that you have added to your customized status bar control program.

• As an example, right-click customer.gs in NetExpress, and select Edit from the context menu.

• Right-click in the Customer Details window and select Dialog from the context menu.

• To add the new event and make your machine beep when you double-click in the status bar, enter the following code:

  USER-EVENT
     XIF= $EVENT-DATA 34591 SBAR2-DOUBLE-CLICK
   SBAR2-DOUBLE-CLICK
     BEEP

• Save the screenset and run it.

• Double-click in the status bar to test the beep.

The next chapter explains how to add and customize a menu bar and toolbar.

Tutorial - Using the Sample Screenset

Tutorial - Adding and Customizing a Menu Bar and Toolba