Office File API and Office-Inspired Desktop UI Controls – Tips, Tricks, and an Important Breaking Change (June-July 2021)

This post includes a series of interesting support tickets answered throughout June and July along with a breaking change notice and a series of enhancements made to our Office-inspired product line. We hope you find the contents of this post interesting and of business value. Should you have any questions about this post, feel free to comment below.

Upcoming Breaking Change

T1012049 - DataFormatOptions and DXRichEditDataFormatOptions properties are now obsolete
https://supportcenter.devexpress.com/ticket/details/t1012049

With our v21.1.5 release, the following DataFormatOptions and DXRichEditDataFormatOptions members will become obsolete:

• AllowHtml
• AllowRtf
• AllowPlainText

These properties affected both copy and paste operations with format-specific content (after the T964531 breaking change). The insertion of HTML content was disabled by default, but you could set the AllowHtml property to true to enable it. We received a lot of feedback regarding this breaking change and decided to restore and enhance previous behavior.

We added Html, Rtf, and PlainText properties to DataFormatOptions and DXRichEditDataFormatOptions classes instead of the now obsolete members. Set new properties for the appropriate RichEditClipboardMode enumeration value to enable copy/paste operations or enable/disable all clipboard operations. Insertion of HTML content from the clipboard is now enabled by default.

We plan to remove these obsolete members in our v22.1 major release (we will post a second notice on this blog once this change is made).

Tips & Tricks

Word Processing Document API

• T998620 - How to replace a document field with a different field
  https://supportcenter.devexpress.com/ticket/details/t998620

  Iterate through the Document.Fields collection and obtain the field code for each field. Split the code string by words and check whether this string contains the phrase "MERGEFIELD.” Obtain the word after this phrase (which represents the field name). Replace the field name in the code range and save your results. See the code below for more information.

  using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
  {
     Document document = wordProcessor.Document;
     FieldCollection fields = document.Fields; 
  
     // Fill the list of field replacements as needed:
     var newFieldList;
     // ...
  
     wordProcessor.BeginUpdate();
  
     // Iterate through the field collection:
     for (int i = 0; i < document.Fields.Count; i++)
     {
        Field field = fields[i]; 
  
        // Get field code:
        string codeRange = document.GetText(field.CodeRange).Trim();
  
        // Split the code string:
        string[] mergeField = codeRange.Split(' ');    
  
        // Find field name in the replacement list:
        if (newFieldList.ContainsKey(mergeField[1]))
        {
           DocumentRange range = 
           	document.CreateRange(field.CodeRange.Start, field.CodeRange.Length);
           document.BeginUpdate();
  
           // Enable field code:
           field.ShowCodes = true;
  
           // Replace field:
           document.Replace(range,
           	string.Format("MERGEFIELD {0}", newFieldList[mergeField[1]]));
  
           // Update field:
           field.Update();
           document.EndUpdate();
        }
     }
  
     wordProcessor.EndUpdate();
     wordProcessor.SaveDocument("Result.docx", DocumentFormat.OpenXml);
  }

• T1009825 - How to align text in a table cell
  https://supportcenter.devexpress.com/ticket/details/t1009825

• T1007313 - How to create a table style with specific formatting for the header row
  https://supportcenter.devexpress.com/ticket/details/t1007313

Excel Export Library

• T1010166 - How to use a single cell (XlCellRange) as a function parameter
  https://supportcenter.devexpress.com/ticket/details/t1010166

WinForms and WPF Rich Text Editors/Word Processors

• T1014207 - How to display a tooltip above the caret position
  https://supportcenter.devexpress.com/ticket/details/t1014207

  Call the RichEditControl.GetBoundsFromPosition method within the SelectionChanged event handler to obtain caret screen coordinates. Use the retrieved coordinates to calculate the position for the TooltipController component. The code sample below illustrates use of this API:

  using DevExpress.XtraRichEdit;
  using DevExpress.XtraRichEdit.API.Native;
  using System.Drawing;
  using DevExpress.Office.Utils;
  
  richEditControl.SelectionChanged += richEditControl_SelectionChanged;       
  
  private void richEditControl_SelectionChanged(object sender, EventArgs e)
  {
      RichEditControl richEditor = (RichEditControl)sender; 
  
      // Get caret position: 
      DocumentPosition caretPosition = richEditor.Document.CaretPosition;   
  
      // Calculate tooltip position:
      Rectangle rectangle =
      	Units.DocumentsToPixels(richEditor.GetBoundsFromPosition(caretPosition),
          	richEditor.DpiX, richEditor.DpiY);
      Point point =
      	richEditor.PointToScreen(new Point(rectangle.Left, rectangle.Top));
    
      // Specify tooltip text and position:
      toolTipController1.ShowHint("Tooltip text", point);
  }

• T1007536 - How to right-align Arabic text
  https://supportcenter.devexpress.com/ticket/details/t1007536

• T1005930 - How to specify a file path to save a document
  https://supportcenter.devexpress.com/ticket/details/t1005930

WinForms Spreadsheet Control

• T1007283 - How to convert strings to numbers when setting cell values
  https://supportcenter.devexpress.com/ticket/details/t1007283

  Use the CellRange.SetValueFromText(String) method to parse the supplied string and create a cell value (with the appropriate data type: for example, a number or date).

  worksheet.Cells["B1"].SetValueFromText("26-Jul-21 10:00AM");
  worksheet.Cells["B2"].SetValueFromText("3.1415926536");

• T1004513 – How to resolve data validation issues when you save a workbook as an XLS file
  https://supportcenter.devexpress.com/ticket/details/t1004513

• T1003778 - How to copy and paste formulas between two Spreadsheet controls
  https://supportcenter.devexpress.com/ticket/details/t997164

• T1006983 - How to print data from multiple worksheets on the same page
  https://supportcenter.devexpress.com/ticket/details/t1006983

WinForms PDF Viewer

• T1003207 - How to hide the Open button in the PDF Viewer's ribbon
  https://supportcenter.devexpress.com/ticket/details/t1003207

  Locate PdfFileOpenBarItem in the RibbonControl.Items collection and call the Remove method to delete this item:

  private void Form1_Load(object sender, EventArgs e)
  {
      pdfViewer.CreateRibbon(PdfViewerToolbarKind.All);
      RibbonControl ribbon = this.Controls.OfType<RibbonControl>().FirstOrDefault();
      if (ribbon != null)
       {
        BarItem item = ribbon.Items.First(x =>
        {
          return x is PdfFileOpenBarItem;
        });
        ribbon.Items.Remove(item);
       }
  }

• T1009531 - How to customize captions within the PDF Viewer's Navigation Pane
  https://supportcenter.devexpress.com/ticket/details/t1009531

WPF Spreadsheet Control

• T1013026 - How to display tooltips for specific cells
  https://supportcenter.devexpress.com/ticket/details/t1013026

Enhancements

Spreadsheet Document API and Spreadsheet Controls (for WinForms and WPF)

• T1012436 - We added a new ColorPalette property to the Workbook and IWorkbook objects.
  https://supportcenter.devexpress.com/ticket/details/t1012436

  This property returns a WorkbookColorPalette object and allows you to access a color palette for a given workbook. This palette includes 56 RGB colors. You can change each color, copy palette colors from another document, or reset a custom palette to default colors.

  The following code example demonstrates how to copy a color palette from one workbook to another:

  using (Workbook sourceWorkbook = new Workbook())
  using (Workbook targetWorkbook = new Workbook())
  {
      targetWorkbook.LoadDocument("Book1.xlsx");
      sourceWorkbook.LoadDocument("Book2.xlsx");
      targetWorkbook.ColorPalette.CopyFrom(sourceWorkbook.ColorPalette);
  }

Spreadsheet Document API

• T1008783 - We implemented new CrossType and CrossesAt properties for the Axis interface
  https://supportcenter.devexpress.com/ticket/details/t1008783

  Use the CrossType property to define where a specific axis crosses its perpendicular axis. The following options are available:

  • AxisCrossType.Auto– The category axis crosses at the zero point of the value axis - the minimum value (if minimum is greater than zero) - or the maximum value (if maximum is less than zero).
  • AxisCrossType.Min– The intersection point is the minimum value on the perpendicular axis.
  • AxisCrossType.Max– The intersection point is the maximum value on the perpendicular axis.
  • AxisCrossType.Custom– The CrossesAt property defines the axis intersection point.

  The code below creates a simple line chart and specifies that the chart’s category axis crosses the value axis at the minimum y-value.

  // Create line chart and specify its location.
  Chart chart = worksheet.Charts.Add(ChartType.LineMarker, worksheet["B2:C14"]);
  chart.TopLeftCell = worksheet.Cells["E2"];
  chart.BottomRightCell = worksheet.Cells["K14"];
      
  // Hide chart legend.
  chart.Legend.Visible = false;
      
  // Specify axis intersection point.
  chart.PrimaryAxes[0].CrossType = AxisCrossType.Min;

PDF Document API

• T999903 - We implemented new API to flatten annotations
  https://supportcenter.devexpress.com/ticket/details/t999903

  We added a Pages collection with PdfPageFacade objects to the PdfDocumentFacade class. You can use PdfPageFacade class methods to flatten page annotations. We also implemented a PdfAnnotationFacade class to flatten a specific annotation. Refer to the following blog post for more information about our new Facade API implementation: PDF Document API - Form Field Enhancements and Facade API (v21.1)

New Example: WPF PDF Viewer

The following example demonstrates how use an Adorner element to add a selection rectangle to the PDF Viewer control and extract selected text:
https://github.com/DevExpress-Examples/-How-to-draw-a-rectangle-over-a-PDF-document

As always, if you’ve come across an interesting support ticket you’d like to share with the rest of the DevExpress developer community, please comment below and include the appropriate link.