Using Named Expressions to drive interface items – A sample

AskInga logo

Using Named Expressions to drive interface items - A Sample

With thanks to Bentley's Sam Hendrick for this article suggestion and content.

By now you've heard and read about Named Expressions, but might not have had the inspiration to experiment with them. If this describes you, then the following tutorial might be just what you need to kick-start your learning and exploration of Named Expressions.

Named expressions can be used with the Customize utility to perform the following tasks:

define rules that control when a tool is available,
define rules to control when a task is available and to ,
define rules for right-click context menus, such as conditions under which a context menu item is hidden.

Knowing this, we'll use a couple of named expressions to load a different user interface depending upon the value of configuration variables defined in a pair UCF files:

The following instructions can be used as a guide to work through this tutorial. Of course this is just a sample workflow, what you employ to create your customized interface may differ.

Step 1: Create two UCFs and one PCF

Using the File Open dialog, or what us old-timers still call the MicroStation Manager dialog, create two new users and one new project. In this example, I'm using ENGINEERING and FACILITIES as the users and MyCity as the project.

From there you can locate and open each of the UCF files and add a couple of new variables which will be used by the named expressions to drive the interface items. In this example, MYCITY_ENG is for the Engineering user and MYCITY_FAC is for the facilities user.

Step 2: Define variables

In the UCF file for the Engineering, we define MYCITY_ENG=1 and MYCITY_FAC=2 while the variables for the facilities user would be the exact opposite (MYCITY_ENG=2 and MYCITY_FAC=1). Note, setting a variable to 1 is True, and when setting it to any value other than 1 is recognized as "False" when dealing with named expressions.

Step 3: Create named expressions

Back in the MicroStation Manager, navigate to the DGNLIB folder and create a new file to hold the named expression definitions. Note that this is optional, if you prefer you can add them to any dgnlib that's in a location pointed to by MS_DGNLIBLIST.

Note: In MicroStation Connect, DGNLIB should point to Configuration variable MS_GUIDGNLIBLIST

In the File Open dialog, ensure that you're set to the new ENGINEERING user and the MyCity project. Then open the dgnlib that will hold the named expressions and select Utilities > Named Expressions. The resulting dialog is used to define and manage named expressions in the active DGN library.

The next step is to create two named expressions that test for the presence of the variables created above. To do that, click on the New button and enter the following information.

Internal Name - sets the name of the named expression: MyCity_ENG

External Name - sets the text label that appears in the user interface to describe the test that will be applied when evaluating the named expression: MyCity ENGINEERING

Description: Is this user in Engineering Services?

Keywords - enables the named expression to be used in specific areas: File, Task, Tool, User Interface

Symbol Sets - defines the values and properties of the named expression: ConfigVar

Expression - is the text string that's to be evaluated. The expression is a single-line statement that contains symbols and operators: ConfigVar.GetExpandedConfigVar("MYCITY_ENG")=1

Step 4: Test expressions

Since you're using the ENGINEERING workspace, the test button should return True. This makes sense since the variable MyCity_ENG is set to 1 in the UCF file. This named expression will be used to control the display an ENGEERING User task that will be created in the next section.

You can repeat these steps to create a second named expression for MyCity_FAC. Testing this variable returns false since the variable is not set to 1. This named expression will be used to control the display of a FACILITIES User task that will be created later.

To determine what the expression should be, select Utilities > Report Symbols which opens expression_symbols.html in your browser. This is an index of available expression symbols that includes information such as the syntax to use, the description and an example. The symbol being used in this exercise is ConfigVar, which has four available expressions

ExpandConfigVar - returns string where all MicroStation configuration variables are expanded.

GetExpandedConfigVar - returns the expanded variable.

GetUnexpandedConfigVar - returns unexpanded variables.

IsConfigVarDefined - returns true if the variable is defined.

The named expressions can now be used for creating a show/hide test for tasks, tools, and other interface items. In this tutorial we'll be creating two tasks:

ENGINEERING User which contains specific tasks for Engineering Services users, and

FACILITIES User which contains tasks for the Facility Maintenance users.

The availability of these tasks will be driven by a Show/Hide test using the named expressions created earlier. Let's take a closer look.

Step 5: Create UI dgnlib

Start by creating a new DGN library to hold the interface customizations. You'll want to put this file in the projects .../dgnlib/ folder so it will be found by MS_DGNLIBLIST. Note that this is defined at the project level, so all customizations in this dgnlib file will be read by all user workspaces using this project.

Step 6: Create user tools and tasks

Once open, navigate to the Customize dialog and create several new tool boxes under User Tools. In this example, I created the following tool boxes and populated them with relevant tools: Annotation, Display, Draw, Measure, Modify, and Publishing.

Once the User Tools have been created, go to the Tasks pane and create a new task called ENGINEERING User. You can then populate this task with some or all of the user tools created above.

Likewise, create a new task called FACILITIES User and populate this task with some of the user tools. Since MicroStation builds the interface on-the-fly, you can easily verify your UI design as you go.

Step 7: Add Show/Hide test

Tasks and workflows have a variety of properties that are defined in the Tool Container pane of the Customize dialog. One of available properties is a Show/Hide Test which determines whether the item is displayed in the Tasks dialog. The tests are based on named expressions, and since we've already created those in Step 3, we can now define these tests.

In the Customize dialog, highlight ENGINEERING User in the Tasks pane, and note the available properties in the Tool Container. Since there is no Show/Hide test, add one via the right click menu.

Select the drop-down of the new Show/Hide test item and choose MyCity ENGINEERING from the pop-up dialog. At this time you may also want to click the Test button to ensure it returns True. (Remember, your active user workspace is ENGINEERING therefore MyCity_ENG = 1.)

Do the same for the FACILITIES User task. Choose MyCity FACILITIES from the available named expressions and verify that the test returns False.

You'll also notice that the FACILITIES User task has now been removed from the Tasks dialog on the interface!

Step 8: Test

To further test this, close MicroStation and change the workspace to FACILITIES/MyCity. Open any file and notice that you only have the FACILITIES User in the task dialog.

Close MicroStation and change the workspace to ENGINEERING/MyCity. This time, only the ENGINEERING User task is made available in the interface.

The obvious benefit of the method is that CAD Administrators can maintain a single DGNLIB for all customizations and simply use Named Expressions to turn on or off tasks. In this case, we used a simple configuration variable to drive the show/hide test.

The following content explores how to add the ENGINEERING User and FACILITIES User to the right click menu. Since this customization will also use a Show/Hide test based on the named expressions, the right click menu will change its content based upon the active workspace.

Step 9: Add ENGINEERING and FACILITIES to right-click menu

Using either the Engineering or Facilities workspace, and the MyCity project, re-open the UI dgnlib and navigate back to the customize dialog.

Then go to the Context Menus pane and add two new items, one for ENGINEERING and the other for FACILITIES. Add the appropriate Show/Hide Test and finally populate the items with the desired user tools as shown.

Testing this is going to produce similar results to the tasks. When the workspace is set to ENGINEERING/MyCity, the right-click menu will show the ENGINEERING User content, and when the workspace is set to FACILITIES/MyCity, it flip for the FACILITIES User.

Step 10: Add Switch User item to the right-click menu

As a final touch to the right-click menu, let's add a Switch User item that performs the following tasks:

Show tasks from both the engineering and facilities users.
Show only the ENGINEERING User tasks.
Show only the FACILITIES User tasks

This can be very useful for those users who are not running the ENGINEERING or FACILITIES workspace. For example, perhaps there's a CAD workspace that needs access to all items of both interfaces.

To start, create a new user workspace called CAD and open the UI dgnlib that contains the interface items for both ENGINEERING and FACILITIES.

There's no need to set any variables in the UCF file since this will be done by utilizing the expand set MicroStation keyin.

Navigate to the Customize dialog, and add a new menu called Switch User in the Context Menu. Then add three menu items that execute the following MicroStation key ins:

Show Both Users: expand set MYCITY_ENG = 1;expand set MYCITY_FAC = 1;task reload

ENGINEERING: expand set MYCITY_ENG = 1;expand set MYCITY_FAC = 2;task reload

FACILITIES: expand set MYCITY_ENG = 2;expand set MYCITY_FAC = 1;task reload

To finish this off, let's take a quick look at the keyins:

Expand set sets a temporary configuration variable for the active design session. Remember, the CAD user does not have MYCITY_ENG or MYCITY_FAC defined in the UCF file. Note that this is an excellent example of using the expand set keyin to set a variable that's not defined elsewhere.

Task reload, does exactly what it implies - it reloads all of the tasks.

This tutorial is only a small sampling of what can be done with named expressions, and with a little curiosity and creativity the possibilities are seemingly endless.

Thanks for reading and have fun!

Sample files:

http://communities.bentley.com/communities/other_communities/askinga/m/askinga-files/149094/download.aspx