Code References Window
Beta Draft
Author: (Author's Name)
Date Last Updated: (Date)
Scheduled Release: (Release Number)
Revision History
The following revisions have been made to this document:
Date: (date)
Revision: (rev-no)
Developer: (developer)
Summary of Changes: (summary)
Copyright (C) 2000 by Progress Software Corporation ("PSC"), 14 Oak Park, Bedford, MA 01730, and other contributors as listed below. All Rights Reserved.
The Initial Developer of the Original Code is PSC. The Original Code is Progress IDE code released to open source December 1, 2000.
The contents of this file are subject to the Possenet Public License Version 1.0 (the "License"); you may not use this file except in compliance with the License. A copy of the License is available as of the date of this notice at:
http://www.possenet.org/license.html
Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. You should refer to the License for the specific language governing rights and limitations under the License.
Contributors
Jane Contributor, Joe Contributor
Contents
The Code References window is used to insert preprocessor names and object names into code sections edited in the Section Editor. Because it is a modeless window, it can remain displayed and accessible while you perform other tasks in AppBuilder.
The Code References window is the SmartWindow _coderefs.w. It contains a SmartFolder with two tabs: Objects and Preprocessor. The contents of the Objects and Preprocessor tabs are the Simple SmartObjects _coderef-objnames.w< and _coderef-preproc.w, each of which displays its own selection list and “Insert” button widgets.
Figure 1 shows the Code References window architecture.
Figure 1: Code References Window Displaying Objects Tab
Displaying the Code References window starts instances of SmartObject super procedures, such as smart.p and visual.p. If you delete any of these super procedure instances (for example, using the PRO*Tools Procedure Object Viewer delete option), the Code References window might stop functioning properly.
The SmartObjects that visualize the Code References window (the SmartWindow and the Simple SmartObjects) include the file adecomm/_adetool.i to indicate they are design-time ADE procedures. Because these SmartObjects include _adetool.i, the persistently running SmartObject procedures that comprise the Code References window display in the Procedure Object Viewer only when the "Hide ADE Objects" option is turned off.
AppBuilder defines the shared handle variable _h_CodeRefs (in adeuib/sharvars.i) to store the persistent SmartWindow procedure handle of the Code References window (_coderefs.w). It is used by AppBuilder to check if the Code References window has already been created and to run internal procedures in the Code References window procedure.
The SmartObjects that comprise the Code References window use the AppBuilder-defined, shared handle variable, _h_UIB to run internal AppBuilder procedures as needed.
4 Primary Algorithms and Processes
Algorithms and processes provided by this feature include:
4.1 Starting the Code References Window
The Section Editor calls its own internal procedures InsertWidgetName and InsertPreProcName to invoke the Code References window when the user chooses Insert®Object Name or Insert®Preprocessor Names, respectively. The following code shows these insert procedures:
/* adeuib/_seprocs.i */
PROCEDURE InsertWidgetName.
RUN call_coderefs IN _h_uib (INPUT "displayTab:Objects":u).
END.
.
.
PROCEDURE InsertPreProcName.
RUN call_coderefs IN _h_uib (INPUT "displayTab:Preprocessor":u).
END.
The Section Editor insert procedures run an AppBuilder-defined internal procedure named call_coderefs (adeuib/uibmproa.i) to display the Code References window. Procedure call_coderefs has one input parameter—a colon-delimited character string comprised of a run command and its run parameters. In the code above, both insert procedures specify “displayTab” as the run command portion of the input character string and each specifies their own run parameters portion (the strings “Objects” and “Preprocessor”).
When run, AppBuilder procedure call_coderefs uses _h_CodeRefs to see if the Code References window has already been created. If the handle is not valid, call_coderefs runs procedure adeuib/_coderefs.w persistently to create and display the Code References window. Otherwise, call_coderefs restores the Code References window by invoking the restoreWindow procedure in _h_CodeRefs.
4.2 >Displaying a Code Reference Tab
After creating or restoring the Code References window, the call_coderefs procedure final task is to display the appropriate tab in the Code References window.
Call_coderefs uses the run command portion of its parameter as the name of an internal procedure to run in _h_CodeRefs procedure, using the run parameters portion as the input to that procedure. For example, if the Section Editor InsertWidgetName procedure had been invoked, call_coderefs would run procedure “displayTab” in _h_CodeRefs and pass in the “Objects” parameter string to specify the display of the Objects tab. This is the code for procedure call_coderefs:
/* adeuib/uibmproa.i */
PROCEDURE call_coderefs :
DEFINE INPUT PARAMETER pcCommand AS CHARACTER NO-UNDO.
DEFINE VARIABLE runCommand AS CHARACTER NO-UNDO.
DEFINE VARIABLE runParams AS CHARACTER NO-UNDO.
DO ON STOP UNDO, LEAVE:
IF NOT VALID-HANDLE(_h_CodeRefs) THEN
DO:
RUN adeuib/_coderefs.w PERSISTENT SET _h_CodeRefs.
RUN initializeObject IN _h_CodeRefs.
END.
ELSE
DO:
RUN restoreWindow IN _h_CodeRefs.
END.
IF NUM-ENTRIES(pcCommand , ":":U) > 1 THEN
ASSIGN runCommand = ENTRY(1, pcCommand, ":":U)
runParams = ENTRY(2, pcCommand, ":":U).
ELSE
ASSIGN runCommand = pcCommand.
RUN VALUE(runCommand) IN _h_CodeRefs (INPUT runParams).
END. /* DO ON STOP */
END PROCEDURE. /* call_coderefs */
Call_coderefs uses the “displayTab” portion of the input parameter string as the name of an internal procedure to run in the Code References persistent procedure. Procedure displayTab activates the appropriate folder tab using a selectPage call and then places focus into the selection list of the displayed tab using an apply entry statement. This is the code for procedure displayTab:
/* adeuib/_coderefs.w */
PROCEDURE displayTab :
DEFINE INPUT PARAMETER pcTab AS CHARACTER NO-UNDO.
CASE pcTab:
WHEN "Objects":U THEN
DO:
RUN selectPage ( INPUT 1 ).
/* Put focus in the insert window. Fixes 19990603-009 (jep). */
RUN ApplyEntry IN h_coderef-objnames.
END.
WHEN "Preprocessor":U THEN
DO:
RUN selectPage ( INPUT 2 ).
/* Put focus in the insert window. Fixes 19990603-009 (jep). */
RUN ApplyEntry IN h_coderef-preproc.
END.
END CASE.
END PROCEDURE.
4.3 Populating the Tab Selection Lists
To populate the selection lists of the tabs, the Simple SmartObjects override their viewObject procedures to run internal procedure refreshDisplay before running the viewObject super.
For the “Objects” SmartObject, procedure refreshDisplay runs Section Editor procedure getInsertWidgetNameList and receives back the current design object’s widget or object name list. For the “Preprocessor” SmartObject, procedure refreshDisplay runs Section Editor procedure getPreProcNameList and receives back the current design object’s preprocessor list.
4.4 Inserting an Item from the Selection Lists
When an item is selected in the Objects or Preprocessor tab selection list and you choose the Insert button or double-click the list item, the item is inserted into the current Section Editor code section.
To insert an Objects item from the selection list into the current Section Editor code section, the “Objects” tab SmartObject procedure run its internal procedure InsertObjName. That procedure calls Section Editor procedure doInsertWidgetName to appropriately insert the selected item. The following code shows this call:
RUN doInsertWidgetName IN hSecEd (INPUT s_PickList).
To insert a Preprocessor item from the selection list into the current Section Editor code section, the “Preprocessor” tab SmartObject procedure runs its internal procedure InsertPreProcName. That procedure calls Section Editor procedure doInsertPreProcName to appropriately insert the selected item. The following code shows this call:
RUN doInsertPreProcName IN hSecEd (INPUT s_PickList).
4.5 Refreshing the Code References Window
The Code References window displays information appropriate for the currently active Section Editor window. When you change from one Section Editor window to another, the Code References window refreshes its display to show the appropriate information for that Section Editor. The Code References window also refreshes when you change the design object for which a single Section Editor is open.
To refresh the Code References window when changing the Section Editor window, each tab SmartObject procedure subscribes to the AppBuilder event message "AB_call_sew_setHandle" and runs procedure refreshDisplay to update the Code References window when the event occurs.
To refresh the Code References window when changing the design object, the “Objects” tab SmartObject procedure subscribes to the AppBuilder event message "SE_UPDATE_WIDGETS" and runs procedure refreshDisplay to update the Code References window when the event occurs. The “Preprocessor” SmartObject procedure does not subscribe to this message. Its contents do not change when the design object changes.
4.6 Minimizing the Code References Window
The Code References window minimizes and restores when you minimize and restore AppBuilder's main window. This is accomplished in the _coderefs.w initializeObject override procedure with these lines:
/* Parent the Code References window to AB main so when AB main is minimized,
this window minimizes. (jep) */
ASSIGN
{&WINDOW-NAME}:PARENT = _h_menu_win
{&WINDOW-NAME}:PRIVATE-DATA = "{&UIB_SHORT_NAME}":u.
Not Applicable
The Code References window has dependencies/interdependencies with the AppBuilder tool and its code Section Editor, as described in other sections of this document.
This tool uses the following source files:
Source File |
Description |
adeuib/_coderefs.w |
SmartWindow procedure that is the Code References window. |
adeuib/_coderef-objnames.w |
“Objects” tab Simple SmartObject procedure. |
adeuib/_coderef-preproc.w |
“Preprocessor” tab Simple SmartObject procedure. |
Not Applicable
See Section 4.1 Starting the Code References Window for a description on invoking the tool.
10 Requirements and Strategies
Because the Code References window is comprised of SmartObjects, its procedure instances run persistently. If you want to test changes to any of the Code References source files, you must close the Code References window and be sure none of its source files are running persistently.
Not Applicable
The following documents provide additional information about the tool: