The LOCATOR editor

The LOCATOR editor is a property editor providing a link to a file.

Property info definition

The property info definition in settings.agconf:
  • type="LOCATOR": as the property link to a file (.4gl).
  • filePath: sets the file path where the function is written.
  • locator: the locator attribute is a regular expression.
  • codeTemplate: this attribute is optional, if present and the locator regex is not found, the codeTemplate is added to the filePath document.

Example

<DynamicProperty name="my_identifier" type="LOCATOR" label="my_property_label" 
  description="my_property_tooltip" filePath="$(Dir)/$(BaseName).4gl" locator="/FUNCTION MY_FUNCTION()$" 
  codeTemplate="FUNCTION MY_FUNCTION() DISPLAY 'In MY_FUNCTION()' END FUNCTION"/>

Usage

The LOCATOR editor provides a property view with a feature to open a text file in the Code Editor and locate text. As the property has no value (it cannot be edited), the editor provides a link to a text file.

For example, the LOCATOR editor allows you to manage source code if you are adding custom code using code events. When you click the property button in a diagram, Genero Studio opens the file referenced in the property's filepath attribute and locates the function referenced by the locator. The LOCATOR functions differently depending on what values the locator, and codeTemplate attributes contain:
  1. If the locator property's regular expression is found, it is selected in the Code Editor.
  2. Or if the locator is not found, it creates it from the codeTemplate (if defined) and adds it. The function is then selected in the Code Editor.

This means the codeTemplate function signature is the same as the locator.

Once you have activated the property link, the property appears bold in the Properties view. Selecting the property button again returns you to the same location within the file.

As an option, the codeTemplate attribute allows you to create a function that is saved to the filepath file and used each time the application is compiled. You can edit or add code to the function as required.
Tip:

To remove all changes you have made, you can simply remove the function from the filepath file. The LOCATOR editor property is updated. It no longer appears bold in the Properties view to indicate the property is not used.

The filePath, locator, and codeTemplate attributes use regex syntax like XPath for dynamic values. The following nodes inside an expression $() can query values:

  • Dir: current document directory
  • Path: current document absolute path
  • BaseName: current document basename (without file extension)
  • Extension: current document extension
  • Name: current document filename or XPath from current selection

For example, $(./@name) references an attribute in the current XML element in the filepath document.

dbapp template code event

This is an example of a code event referenced by the DynamicProperty editor definition:

<DynamicProperty name="uc_record_dlgEvent_BeforeRow" 
...
                 filePath="$(Dir)/$(BaseName).4gl"
                 locator="/PUBLIC FUNCTION dlgEvent_$(./@name)_BeforeRow[^\\w].*$"
                 codeTemplate="
PUBLIC FUNCTION dlgEvent_$(./@name)_BeforeRow(dlg ui.DIALOG, uiMode SMALLINT, 
 ...
" />

In the example, the property uses the current filename with the "4gl" extension. The locator within the file is dlgEvent_<recordName>_BeforeRow. The code template is a function PUBLIC FUNCTION dlgEvent_<recordName>_BeforeRow( ...

You also have the option of registering the property, ("uc_record_dlgEvent_BeforeRow" in the example) on the record entity by adding its name to the existing <Items> record in the <File> section:
<Item nodeName="Record" dynamicProperties="...;uc_record_dlgEvent_BeforeRow;..."

It can also be added to a property group (for user convenience).