01 Welcome to Trimble Business Center Macros!

Document created by David Kosakowski on Apr 30, 2018Last modified by Gary Lantaff on Oct 17, 2018
Version 11Show Document
  • View in full screen mode

Disclaimer

The functionality for writing macros for Trimble Business Center (TBC) is designed for people with coding experience. Even software developers who want to create macros should consider getting training from Trimble. To get macros training, contact your dealer. Once trained, the only support for questions and means for sharing macros will be through the Trimble Macro Language forum.

Introduction

Writing macros for Trimble Business Center enables you to create your own commands so that you can customize and automate unique functions that you use frequently. These commands appear just like the native commands in TBC. Trimble provides several predefined macros that get installed with the program. You can either cut-and-paste code snippets from these to create your own macros or you can write macros from scratch. Once you copy and modify or write a macro and place it in a specified Macros folder, it will appear alphabetically in the All Commands list in TBC.

You can also tell your macros to use specific icons and then add those icons to your ribbons or the Quick Access toolbar like any other command. Unlike Terramodel TMLs, the Trimble Macro Language (also known as TML) gives you "create, read, update, and delete" (CRUD) access to all of the objects and data in TBC that Trimble developers use.

Why use macros?

  • They are extensible; you can add on to an existing command to do what you need.

  • They support your individual workflows.

  • You can quickly fix program issues you encounter without waiting for a future release or patch.

  • They can be used to create additional commands that were previously available in Terramodel.

A simple example

Challenge

A customer had a TBC project file (.vce) with ~590 closed linework shapes and an equal number of text items enclosed by and associated with the shapes. He wanted to automatically name each closed line with the text encompassed by the shape so when he exported the lines, they were named by the text. This would be laborious and time-consuming to achieve manually.

Solution

We wrote a macro command called Assign Names from Inside Text (the AssignNameFromInsideText.py file in your MacroCommands folder). All of the manual line naming operations are performed by the macro using a single Execute() function that selects the ~590 polygons and associated text objects and performs more than one million point and polyseg computations).

Prerequisites

  • Macros are only available in TBC version 5.0 and above. Also, a license of "Survey Advanced" is required in order to run macro commands. If such a license is not detected, the macro functionality will not be visible in the program (even if you have added macro commands to menus and/or toolbars).

Overview

You will begin by setting up an integrated development environment (IDE) consisting of:

  • IronPython – This free, open-source tool allows you to code in a variant of the Python programming language. IronPython is tightly integrated with the .NET Framework. Python scripts are text files that can be used to define a TBC command and its functionality.

  • Any text or code editor, such as Notepad ++ – In these instructions, Visual Studio Community is used as the example. It is a free*, extensible tool for enables you to code in the XAML programming language to develop non-enterprise Windows programs. XAML is part of the Microsoft Windows Presentation Foundation (WPF), which is the category of features in the Microsoft .NET Framework 3.5 that deals with the visual presentation of Windows- and Web browser-based client applications. XAML files provide the user interface (UI) for the TBC macro written in Python. Visual Studio (VS) also provides debug functions for your macros. VS is also the helper in which you will write the scripts. You can, of course, use you own copy of Visual Studio instead.

    Note: You may be prompted to renew your ‘trial’ VS Community license.

    *See the Microsoft Visual Studio Community license terms when you install to see the restrictions.

UPDATE

Macro Types

There are three kinds of macro commands that you can create:

  • No UI - These are commands that simply execute with no further input (such as Select All and Zoom Extents).

  • Modal dialog UI - These are commands that open a window for additional input on top of the application window (such as Project Settings and Layer Manager). You cannot interact with the program while the window is open.

  • Non-modal Command pane UI - These are commands that generally appear in the Command pane next to the view panes (such as Create Point and Change Elevation). These are the typical commands that enable you to interact with the program other views and objects while the pane is open.

How TBC Macros Work

  1. When Trimble Business Center is started, it looks for Python files (.py) in C:\ProgramData\Trimble\MacroCommands. Any Python file found there that includes these is treated as a command:

    • a function named “Setup” (with one argument)

    • a defined “Key” (that is unique from existing command keys)

    For example, here is a simple macro (that does nothing);

    def Setup(cmdData): cmdData.Key = "_DoesNothing"

    The only required data is the key.

  2. The file is compiled and its setup method is called. The setup function passes the “Command Data” class to query/define all the properties of the command.

  3. The program creates a dictionary of file names and command data in “..\MacroCommands” and all subfolders (with *.py files).

    • The name is “<folder>.dict”

    • The command data holds the file modify date.

  4. The macro provides the key, icon bitmap, help file, tooltip, ribbon placement, etc. , all of which is saved in the dictionary file.

  5. Every time TBC runs, if all the files are the same, the dictionary is accurate and it starts up and registers all the commands.

  6. If the modify date of file does not match, the file is compiled (and the setup function called) and the command is added to command list. If the modify dates match, the command is added, but not compiled. The file will be compiled the first time the macro is run.

  7. When the macro command is executed by the UI, one of these will happen:

    • If you have an “Execute(cmd, currentProject, parameters)” function defined, it will be called. The command that is running in the current project, the folder that the macro was found in, and any parameters are passed to it. Use this method to open dialogs or run command that do not require UI (see macro types).

    • If macro that defines a UIForm (in command data at startup) that fit in a stock command shell that is configured to look just like a native TBC command, then C# command class is created and macro assigned. (most of the time, this is the one you should use)

    • If macro defined UIViewForm (in command data at startup), then c# view class is created and macro assigned put a form in one of the MDI views such as Point Spreadsheet (this is rarely used)

    • There is very little affect on the program's startup once the macro commands have been initially compiled.

  8. When the setup is run, a command data class is assigned to each command. The key is the most important and only required field. Each key is unique and is used when:

    • Commands are assigned to toolbars

    • Commands are called in code or from the Command line

Why to Use IronPython

  • Python is a programming language for the .NET Framework.

  • Python is open source.

  • It is "pretty complete" (much more than Terramodel's TML language was), yet also as simple as you want to keep it.

  • It is already used in Trimble Business Center’s 3rd party raw data importer.

  • There is good support for Windows Presentation Foundation (WPF), the newer way of defining layout in scripting language. This is much easier to use and generates Intermediate Language (IL) code for .NET, so performance is good (it runs quickly).

  • There are lots of  help resources to help with the general syntax, including some that describe the slight differences with Python. Most of the difference is that IronPython has been extended to also call .NET objects. The typical Python programmer will not understand much of the .NET code. The Python resources will not advocate using .NET classes to open files, but most likely you would when writing a macro for Trimble Business Center.

  • It is an easy language to learn, at least as easy as TML. As a code interpreter, it interfaces well with assemblies written in C# written, and is easier for most people to code in.

Why to Use Visual Studio Community

  • You will use Visual Studio to write XML files and reference Trimble Business Center DLLs and the objects they contain.

Versioning

  • Macros are not versioned, but they only create currently-supported objects, so your TBC project files will remain backward compatible.

Trimble Business Center Macro and Extension Community

In this forum, you can:

  • Ask and answer questions so all macro developers and users share knowledge.

  • Join group discussions on best practices and more.

  • Find macro-related product announcements.

  • Take surveys on the macros and see results.

  • Upload and download shareware macros for everyone to use. TBC will also include an installed set of usable samples.

  • Find Getting Started guides and other training materials and documentation on macros.

Macro Security

You can convert macro into compiled .NET DLL. at runtime, the program looks for a .py or .pydll file (which is the Python file saved as compiled code). Either will run, but with the .pydll, no one can corrupt your macro code. If both file types exist, the newer file type is used. To convert a python file into a DLL, you yoll need to use a Python command that is located in the Macro Forum's Repository.

Next topic: 02 Setting Up an Integrated Development Environment (IDE)

Attachments

    Outcomes