PreviousTutorial - Using the Sample Screenset Tutorial - Adding and Customizing a Menu Bar and ToolbarNext

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:

Before starting this tutorial you should have:

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

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 Net Express.

  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:

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

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

  7. Compile the generated control program using Rebuild All on the Net Express 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:

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).

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:

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

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:

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:

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 Net Express.

  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.

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


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousTutorial - Using the Sample Screenset Tutorial - Adding and Customizing a Menu Bar and ToolbarNext