API Improvements in Studio 2021

In this release of Studio, public API were improved to make interaction with Studio more easy and more robust.

Based on the feedback we received in the Community we exposed couple of events for: Segment Split action, Segment Merged action. The full list of events will be presented in a separate section of this wiki.

To promote:

  1. Automation Testing we expose interfaces which will allow users to write Integration Tests by mocking common objects from the Integration API.
  2. Windows Presentation Foundation (WPF), plugins which have View Parts written using WPF now are recognized by Studio whithout using an Windows Forms Element Host.

Before starting to update your pluginsto support API Changes, please make sure the plugin is migrated correctly to Studio 2021. More information can be found here.

View Parts Changes

How to update plugins which have View Parts

In the bellow example we'll update the DSI VIewer plugin to support the latest chages in the Integration API. The view part of this plugin is written using WPF and is a great example which ilustrates how easy the View Parts can be recognized by Studio.

The source code of this plugin is open Source on our GitHub Repository.

Plugin architecture

Before the API Changes we had to create an Windows Forms Control which had an ElementHost control in which we added our WPF View.

After

After you change the references to point to Studio16 folder you'll see in Visual Studio following error:

Why this error appeared and how to fix it

  • First thing we need to do is to make the WPF View to Implement the IUIControl interface exposed by Studio.
  • Second we need to remove the reference to WindowsForms control and use the WPF control instead.

In our plugin we use MVVM design pattern, that means we need to add the data context to the view. Before it was added in the WindowsForms Control before settings the WPF control to the Element Host.

As we mentioned before we can delete the Windows Froms control and return the WPF instead. In the class which inherits from AbstractViewPartController we can set the data context of the view.

At this point the error form Visual Studio console should dissapear and the plugin will be successfully be displayed in Studio.

IStudioDocument and IDisplayFilterRowInfo interfaces

We exposed two new interfaces in the Integration API  that promotes a testable environment for developers integrating with the Document object.

How to update plugins which have references to Studio Document

If a plugin have a reference to Document this error will appear in Visual Studio:

How to fix it

To fix it is quite simple, you only need to change the type of the object and use the new interface exposed in the API (IStudioDocument)

The same fix applies to the plugins which have references to DisplayFilterRowInfo, we need to use the interface instead IDisplayFilterRowInfo. 

New events exposed using IStudioEventAggregator

Based on the feedback we received on the Community we exposed couple of events using Event Aggregator.

In order to use Event Aggregator in your plugin first of all System.Reactive needs to be installed from NuGet. 

After the reference is added to the Visual Studio project, include the library into the manifest file:

<Include>
    <File>System.Reactive.dll</File>
  </Include>  

Open project for selected language event 

This event allows user using the API to open the Files View for a specific target language.

Code sample:

var eventAggregator = SdlTradosStudio.Application.GetService<IStudioEventAggregator>(); 
eventAggregator.Publish(new OpenProjectForSelectedLanguageEvent(activeProject,targetLanguage));

Change source content settings event 

This event allows to change the source settings for following properties for a Project: 

  1. Allow source editing
  2. Allow merge across paragraphs
  3. Enable Icu Tokenization

Code sample:

var eventAggregator = SdlTradosStudio.Application.GetService<IStudioEventAggregator>();
 
eventAggregator.Publish(new ChangeSourceContentSettingsEvent(activeProject,true,true));
 
or
 
eventAggregator.Publish(new ChangeSourceContentSettingsEvent(activeProject,false,false,true));

Segment split event 

User can subscribe to SegmentSplit event and it will be notified every time a segment is split in Studio Editor. Following details are received in the event arguments:

  1. Document name
  2. The original segment id which was split
  3. The ID of the first new segment
  4. The ID of the second new id

Source code

var eventAggregator = SdlTradosStudio.Application.GetService<IStudioEventAggregator>();
 
eventAggregator.GetEvent<SegmentSplitEvent>().Subscribe(SegmentSplit);
 
private void SegmentSplit(SegmentSplitEvent e)
{
var document = e.Document;
var originalSegId = e.OriginalSegmentId;
var firstNewSegmentId = e.FirstNewSegmentId;
var secondNewSegmentId = e.SecondNewSegmentId;
var paragraphUnit = e.ParagraphUnitId;
}

Segments merged event 

 SegmentsMergedEvent notifies the user when multiple segments are merged. Following details are received in the event arguments:

  1. Document name
  2. Paragraph Unit IdChangeSourceContentSettingsEvent 
  3. The ID of the new segment which resulted after merge operation
  4. The IDs of the segments which were merged

Source code

var eventAggregator = SdlTradosStudio.Application.GetService<IStudioEventAggregator>();
 
eventAggregator.GetEvent<SegmentsMergedEvent>().Subscribe(SegmentsMerged);
 
private void SegmentsMerged(SegmentsMergedEvent e)
{
var document = e.Document;
var paragraphUnit = e.ParagraphUnitId;
var newSegmentId = e.NewSegmentId;
var oldSegmentIds = e.OldSegmentIds;
}

Comments Changed event 

CommentsChangedEvent notifies the user when comments on a document have changed, it includes information about :

  1. Comment event type
  2. Comment scope
  3. A list of comments

Comment Added event type

If the comment was added for a selection in studio:

Following information will be displayed by the CommentsEvent:

Comment Deleted event type

Comment Changed event type

If we are adding a comment to the current file scope and the file does not have any other comments set, the event response will look like this:

Where the comments list contains the new comment added.

If the file already contains comments at the file scope when we add a new comment to the file, we'll receive the list with all the comments from the file scope.

Source code

_eventAggregator = SdlTradosStudio.Application.GetService<IStudioEventAggregator>();
 
_eventAggregator.GetEvent<CommentsChangedEvent>().Subscribe(CommentsChanged);
 
private void CommentsChanged(CommentsChangedEvent e)
{
 
}

Enahncements to ProjectInfo

Following properties were exposed in ProjectInfo:

  1. Project Origin
  2. Icon Path
  3. Project Status
  4. Project Type

With this new options when a studio project is created using the API project icon and project origin can be set: 

Source Code:

  var projectInfo = new ProjectInfo
{
    Name = _constants.LingotekTempProj,
    SourceLanguage = sourceLang,
    LocalProjectFolder = projectPath,
    ProjectOrigin= "Lingotek project",
    IconPath = GetIconPath(),
    TargetLanguages = new[] {targetLang}
 };
// Write the icon to the Plugins\Unpacked folder and use the icon's path from that folder in order to set the project's IconPath
private string GetIconPath()
{
   var assemblyPath = Assembly.GetExecutingAssembly().Location;
   var directoryInfo = Directory.GetParent(assemblyPath);
   var targetPath = Path.Combine(directoryInfo.FullName, "icon.ico");

   using (var fs = new FileStream(targetPath, FileMode.Create))
      {
           PluginResources.icon.Save(fs);
        }
            return targetPath;
 }

How to get the project status and project type

// Retrieve the needed information from the project
var projectInfo = proj.GetProjectInfo();
var status = projectInfo?.Status; // the current status of the project
var publicationStatus = projectInfo?.PublicationStatus; // the publication status of the project
var projectType = projectInfo?.ProjectType; // the type of the project
Full code sample can be found here.

New API Exposed - Versioning API

This API allows developers to have a easy access to the following information:

  1. A list of all Studio versions installed on the machine.
  2. Version of the Studio instance, which is currently running.
  3. Different useful information for development like: Install folder path, public version, short version

In order to use the new version api in the project you need to add a reference to: Sdl.Versioning.dll.

Full source code can be found here.

New controllers exposed

In the API were exposed 3 new controllers which allows you to add actions in following Studio Views:

  1. Welcome view
  2. Translation Memories View
  3. Reports View

Related
Recommended