 |
|
| Handling Events in SAS/EIS Legacy Objects |
Communication between Legacy Objects
Note: Event handling for newer versions of SAS/EIS objects
is different than it was for Version 6. This appendix discusses how events
are handled for legacy (Version 6) objects. For information on
handling events in newer versions of SAS/EIS software,
refer to
Modifying or Adding Event Handling. ![[cautionend]](../../../../common/61925/HTML/default/images/cautend.gif)
When you develop a SAS/EIS application in Version 6, you might want to establish communications between two or more objects. When one object communicates with another, it can send to the second object information about its current status or state. For example, one object can send information to a second object about the action that was just performed by the user, such as drilling or selecting an item on a report. The second object can then perform functions that you define based on the information it receives from the first object. To better understand how much power and flexibility this communication between objects gives your applications, consider the following example.
Suppose you want to develop an application that enables users to point and click on a report and then to view other reports that show what they have chosen in the first report. A typical application might include a summary report that shows regional sales broken down by individual products. After analyzing the summary report, a user might want to click on a particular sales region or a specific product and get a report that shows the sales numbers for that region or product.
| Deciding Which GUI to Use |
When you design an EIS in Version 6, you first need to decide which graphical user interface (GUI) that you want to use for displaying the application reports. One design would enable you to display both reports in the same window. Another design would enable you to display the second report in a separate window when the user selects an item or acts on the first report. Both designs might have advantages and disadvantages for your application. For example, displaying both reports side-by-side might be the best way for users to understand their data. However, placing both reports in one window might reduce the display size of each report and require users to scroll to view an entire report. In some cases, it may be critical to see complete information for each report, so you would display the second report in a separate window to maximize the viewing area.
You can design SAS/EIS applications that use either method of displaying results when objects communicate with each other. The type of GUI you choose for displaying your reports will determine which communication method you should establish. To display your reports in separate windows, you define one or more hotspots in your first object and assign a target application that executes when the hotspot is selected. To display your reports side-by-side, you will link objects in a Desktop application. The following sections describe the features of both communication methods.
| Using Target Applications to Communicate between Objects |
To develop an application in which two Version 6 SAS/EIS objects communicate and their results are displayed in separate windows, use the technique of assigning a target application to a hotspot that you define in the report. In a typical example, a user sees a window that contains the first report. When the user clicks on an area of the report, a second window opens to display the second report. To create a two-window display without writing any code, use any of the objects that enable you to create hotspots and to assign target applications.
In many situations, assigning hotspots and associating target applications with those hotspots may satisfy your application requirements. However, because you must manually define each hotspot and assign its target application, consider the following cases in which using target applications may not be the most efficient method:
-
If the report has several items that represent hotspots, defining the hotspots and assigning target applications may take a significant amount of time.
-
If the content of the first report changes constantly (for example, if the items on the report are not always the same), it may be impossible to permanently define hotspots and their target applications when you develop the application.
Several objects provide additional information that can be queried by the target application at run time. For example, in these objects, a target application can find out what was selected or acted upon in the first application and can respond accordingly. To do this, the target application reads from a list on the local environment list at run time. This list contains information about the current state of the object. The target application can retrieve and process that information.
Passing Parameters to Target Applications
Many Version 6 SAS/EIS applications support target applications, which are executed when a user selects certain areas of an application display. The Catalog Entry Viewer with Hotspots, External File Viewer with Hotspots, Graphics with Hotspots, and Organizational Chart objects store application-specific information about the local environment list before calling the target application. This information may be used by the target application in user-specified methods. The information is stored on the local environment list as the INFOLIST list, which can be retrieved with the following SCL code:
infolist = getniteml(envlist('L'),'INFOLIST', 1,1,0);
Note that this information is stored on the local environment list only when both one or more hotspots and a target application have been defined.
The first items in the parameters list are
- APPLTYPE
- objectid
-
the object identifier of the viewer in the application that is calling the target.
The other items on the parameters list are application specific and are the same parameters that are passed when the SELECT event is issued in a Graphics Menu Builder application. See the tables in the following section for complete lists of the parameters that are passed for each object.
| Using Events to Communicate between Objects |
To develop a Version 6 SAS/EIS application in which two objects communicate and their results are displayed in the same window, you can use the Graphics Menu Builder object. This object enables you to link two objects through the sending and receiving of events.
What Is an Event?
When a SAS/EIS object executes certain methods that change its status or state, the object issues an event. The event describes what changed and includes a list of parameter values that changed. For example, if a user drills down in a 3D graph, the 3D Business Graphs object issues the following event:
DRILLDOWN, Active_cell=
The ability to issue and receive events becomes very powerful when you link two or more SAS/EIS objects together. Objects can communicate changes in their states by issuing and receiving events. This communication can initiate changes in one object as a result of changes in another object to which it is linked.
Events and Event Handling in a Graphics Menu Builder
When you place Version 6 SAS/EIS objects in a Graphics Menu Builder object, you can link the objects so that they communicate changes in their states and can react to those changes through events.
Objects placed in a Graphics Menu Builder do not automatically receive events. You must link the objects and specify which events the objects will receive. When an object receives an event, the object executes the method that was specified when it was placed in the Graphics Menu Builder and linked to another object. A method name can be filled in by default when you select an event to receive. For example, for the SELECT event, the default receiver method might be _CHANGE_. If this method is not the one the receiver should execute when the event is received, then type in a new method name.
Note: In newer versions
of SAS/EIS software, the Application
Screen Builder object has replaced the Graphics Menu Builder object. for more
information on the Application Screen Builder object, refer to the SAS/EIS online
Help.
When an object issues an event, it also sends parameters that further describe the event. The parameters vary depending on which event is being issued. The receiving method must be able to receive these parameters.
When an object receives an event, the object verifies the parameters that are passed with the event to ensure that it can act in the same manner as the sending object.
Note: For information on handling events in newer versions
of SAS/EIS software, refer to
Modifying or Adding Event Handling.
Catalog Entry Viewer with Hotspots
Note: In newer versions of SAS/EIS software,
the Text Viewer object has replaced the Catalog Entry Viewer with Hotspots
object. For more information on the Text Viewer object, refer to the SAS/EIS online
Help.
In a Version 6 Catalog Entry Viewer with Hotspots, the following parameters are passed by the SELECT event when the user double-clicks in the frame:
External File Viewer with Hotspots
Note: In newer versions of
SAS/EIS software,
the Text Viewer object has replaced the External File Viewer with Hotspots
object. For more information on the Text Viewer object, refer to the SAS/EIS online
Help.
In a Version 6 External File Viewer with Hotspots, the following parameters are passed by the SELECT event when the user double-clicks in the frame:
| Parameter Name | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Parameter Type | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Parameter Description |
a list containing the following:
|
Graphics with Hotspots
The following parameters are passed by the SELECT event when the user double-clicks in the frame:
| Parameter Name | |||||||||||||||||||||||||
| Parameter Type | |||||||||||||||||||||||||
| Parameter Description |
a list containing the following:
|
Events for Multiple Objects
The events and parameter described in this section apply to these objects:
| Events | Parameter Name | Parameter Type | Parameter Description | |
|---|---|---|---|---|
| DRILLDOWN | active_cell | L | a list describing the selected item. |
The events and parameter described in this section apply to these objects:
| Events | Parameter Name | Parameter Type | Parameter Description | |
|---|---|---|---|---|
| COLLAPSE | active_cell | L | a list describing the selected item. |
The following table lists the events and the parameters that are passed when the events are executed:
| Event | Parameter Name | Parameter Type | Parameter Description | |
|---|---|---|---|---|
| CUSTOMIZE | CUSTOMIZE | L | a list of the customizations. | |
| REPORT_LAYOUT | REPORT_LAYOUT | L | a list of all the dimension variables, analysis variables, and statistics. | |
| STATS_L | STATS_L | L | a list of all the statistics. | |
| _SELECT_ | CHARTV | C | a variable name for the level selected in the tree. | |
| _SELECT_ | WHERE | C | a WHERE clause indicating where in the tree the user clicked. | |
| SUBSET | SUBSET | L | a where_list built from hierarchies that can be triggered by multiple methods. |
|
|
Copyright © 2007 by SAS Institute Inc., Cary, NC, USA. All rights reserved.