|Tutorial - Using the Sample Screenset||Tutorial - Adding and Customizing a Menu Bar and Toolbar|
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:
The topic on user controls describes how to create a user control and set its properties.
The topics in this section give detailed information on the control programs and the functions available.
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.
Dialog System starts up and the Customer Details window is displayed.
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.
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
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
Include the following data item in the Data Block of the screenset, to hold the object reference of the status bar:
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.
When you have defined the required data, define 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.
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.
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.
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:
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.
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
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
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:
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.
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
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:
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.
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.
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.
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:
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 Net Express 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:
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
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:
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.
USER-EVENT XIF= $EVENT-DATA 34591 SBAR2-DOUBLE-CLICK SBAR2-DOUBLE-CLICK BEEP
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.
|Tutorial - Using the Sample Screenset||Tutorial - Adding and Customizing a Menu Bar and Toolbar|