com.aspose.words

Property Getters/Setters Detail

• getEditableRangeEnd

  public EditableRangeEnd getEditableRangeEnd()
  

  Gets the node that represents the end of the editable range.

  Example:

  Shows how to work with an editable range.

  Document doc = new Document();
  doc.protect(ProtectionType.READ_ONLY, "MyPassword");
  
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
          " we cannot edit this paragraph without the password.");
  
  // Editable ranges allow us to leave parts of protected documents open for editing.
  EditableRangeStart editableRangeStart = builder.startEditableRange();
  builder.writeln("This paragraph is inside an editable range, and can be edited.");
  EditableRangeEnd editableRangeEnd = builder.endEditableRange();
  
  // A well-formed editable range has a start node, and end node.
  // These nodes have matching IDs and encompass editable nodes.
  EditableRange editableRange = editableRangeStart.getEditableRange();
  
  Assert.assertEquals(editableRangeStart.getId(), editableRange.getId());
  Assert.assertEquals(editableRangeEnd.getId(), editableRange.getId());
  
  // Different parts of the editable range link to each other.
  Assert.assertEquals(editableRangeStart.getId(), editableRange.getEditableRangeStart().getId());
  Assert.assertEquals(editableRangeStart.getId(), editableRangeEnd.getEditableRangeStart().getId());
  Assert.assertEquals(editableRange.getId(), editableRangeStart.getEditableRange().getId());
  Assert.assertEquals(editableRangeEnd.getId(), editableRange.getEditableRangeEnd().getId());
  
  // We can access the node types of each part like this. The editable range itself is not a node,
  // but an entity which consists of a start, an end, and their enclosed contents.
  Assert.assertEquals(NodeType.EDITABLE_RANGE_START, editableRangeStart.getNodeType());
  Assert.assertEquals(NodeType.EDITABLE_RANGE_END, editableRangeEnd.getNodeType());
  
  builder.writeln("This paragraph is outside the editable range, and cannot be edited.");
  
  doc.save(getArtifactsDir() + "EditableRange.CreateAndRemove.docx");
  
  // Remove an editable range. All the nodes that were inside the range will remain intact.
  editableRange.remove();

• getEditableRangeStart

  public EditableRangeStart getEditableRangeStart()
  

  Gets the node that represents the start of the editable range.

  Example:

  Shows how to work with an editable range.

  Document doc = new Document();
  doc.protect(ProtectionType.READ_ONLY, "MyPassword");
  
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
          " we cannot edit this paragraph without the password.");
  
  // Editable ranges allow us to leave parts of protected documents open for editing.
  EditableRangeStart editableRangeStart = builder.startEditableRange();
  builder.writeln("This paragraph is inside an editable range, and can be edited.");
  EditableRangeEnd editableRangeEnd = builder.endEditableRange();
  
  // A well-formed editable range has a start node, and end node.
  // These nodes have matching IDs and encompass editable nodes.
  EditableRange editableRange = editableRangeStart.getEditableRange();
  
  Assert.assertEquals(editableRangeStart.getId(), editableRange.getId());
  Assert.assertEquals(editableRangeEnd.getId(), editableRange.getId());
  
  // Different parts of the editable range link to each other.
  Assert.assertEquals(editableRangeStart.getId(), editableRange.getEditableRangeStart().getId());
  Assert.assertEquals(editableRangeStart.getId(), editableRangeEnd.getEditableRangeStart().getId());
  Assert.assertEquals(editableRange.getId(), editableRangeStart.getEditableRange().getId());
  Assert.assertEquals(editableRangeEnd.getId(), editableRange.getEditableRangeEnd().getId());
  
  // We can access the node types of each part like this. The editable range itself is not a node,
  // but an entity which consists of a start, an end, and their enclosed contents.
  Assert.assertEquals(NodeType.EDITABLE_RANGE_START, editableRangeStart.getNodeType());
  Assert.assertEquals(NodeType.EDITABLE_RANGE_END, editableRangeEnd.getNodeType());
  
  builder.writeln("This paragraph is outside the editable range, and cannot be edited.");
  
  doc.save(getArtifactsDir() + "EditableRange.CreateAndRemove.docx");
  
  // Remove an editable range. All the nodes that were inside the range will remain intact.
  editableRange.remove();

• getEditorGroup/setEditorGroup

  public int getEditorGroup() / public void setEditorGroup(int value)
  

  Returns or sets an alias (or editing group) which shall be used to determine if the current user shall be allowed to edit this editable range. The value of the property is EditorType integer constant.

  Single user and editor group cannot be set simultaneously for the specific editable range, if the one is set, the other will be clear.

  Example:

  Shows how to create nested editable ranges.

  Document doc = new Document();
  doc.protect(ProtectionType.READ_ONLY, "MyPassword");
  
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.writeln("Hello world! Since we have set the document's protection level to read-only, " +
                  "we cannot edit this paragraph without the password.");
  
  // Create two nested editable ranges.
  EditableRangeStart outerEditableRangeStart = builder.startEditableRange();
  builder.writeln("This paragraph inside the outer editable range and can be edited.");
  
  EditableRangeStart innerEditableRangeStart = builder.startEditableRange();
  builder.writeln("This paragraph inside both the outer and inner editable ranges and can be edited.");
  
  // Currently, the document builder's node insertion cursor is in more than one ongoing editable range.
  // When we want to end an editable range in this situation,
  // we need to specify which of the ranges we wish to end by passing its EditableRangeStart node.
  builder.endEditableRange(innerEditableRangeStart);
  
  builder.writeln("This paragraph inside the outer editable range and can be edited.");
  
  builder.endEditableRange(outerEditableRangeStart);
  
  builder.writeln("This paragraph is outside any editable ranges, and cannot be edited.");
  
  // If a region of text has two overlapping editable ranges with specified groups,
  // the combined group of users excluded by both groups are prevented from editing it.
  outerEditableRangeStart.getEditableRange().setEditorGroup(EditorType.EVERYONE);
  innerEditableRangeStart.getEditableRange().setEditorGroup(EditorType.CONTRIBUTORS);
  
  doc.save(getArtifactsDir() + "EditableRange.Nested.docx");

  Example:

  Shows how to limit the editing rights of editable ranges to a specific group/user.

  public void visitor() throws Exception
  {
      Document doc = new Document();
      doc.protect(ProtectionType.READ_ONLY, "MyPassword");
  
      DocumentBuilder builder = new DocumentBuilder(doc);
      builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
                      " we cannot edit this paragraph without the password.");
  
      // When we write-protect documents, editable ranges allow us to pick specific areas that users are allowed to edit.
      // There are two mutually exclusive ways to narrow down the list of allowed editors.
      // 1 -  Specify a user:
      EditableRange editableRange = builder.startEditableRange().getEditableRange();
      editableRange.setSingleUser("john.doe@myoffice.com");
      builder.writeln(MessageFormat.format("This paragraph is inside the first editable range, can only be edited by {0}.", editableRange.getSingleUser()));
      builder.endEditableRange();
  
      Assert.assertEquals(EditorType.UNSPECIFIED, editableRange.getEditorGroup());
  
      // 2 -  Specify a group that allowed users are associated with:
      editableRange = builder.startEditableRange().getEditableRange();
      editableRange.setEditorGroup(EditorType.ADMINISTRATORS);
      builder.writeln(MessageFormat.format("This paragraph is inside the first editable range, can only be edited by {0}.", editableRange.getEditorGroup()));
      builder.endEditableRange();
  
      Assert.assertEquals("", editableRange.getSingleUser());
  
      builder.writeln("This paragraph is outside the editable range, and cannot be edited by anybody.");
  
      // Print details and contents of every editable range in the document.
      EditableRangePrinter editableRangePrinter = new EditableRangePrinter();
  
      doc.accept(editableRangePrinter);
  
      System.out.println(editableRangePrinter.toText());
  }
  
  /// <summary>
  /// Collects attributes and contents of visited editable ranges in a string.
  /// </summary>
  public static class EditableRangePrinter extends DocumentVisitor {
      public EditableRangePrinter() {
          mBuilder = new StringBuilder();
      }
  
      public String toText() {
          return mBuilder.toString();
      }
  
      public void reset()
      {
          mBuilder.setLength(0);
          mInsideEditableRange = false;
      }
  
      /// <summary>
      /// Called when an EditableRangeStart node is encountered in the document.
      /// </summary>
      public /*override*/ /*VisitorAction*/int visitEditableRangeStart(EditableRangeStart editableRangeStart)
      {
          mBuilder.append(" -- Editable range found! -- ");
          mBuilder.append("\tID:\t\t" + editableRangeStart.getId());
          if (editableRangeStart.getEditableRange().getSingleUser().equals(""))
              mBuilder.append("\tGroup:\t" + editableRangeStart.getEditableRange().getEditorGroup());
          else
              mBuilder.append("\tUser:\t" + editableRangeStart.getEditableRange().getSingleUser());
          mBuilder.append("\tContents:");
  
          mInsideEditableRange = true;
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called when an EditableRangeEnd node is encountered in the document.
      /// </summary>
      public int visitEditableRangeEnd(final EditableRangeEnd editableRangeEnd) {
          mBuilder.append(" -- End of editable range -- " + "\r\n");
  
          mInsideEditableRange = false;
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called when a Run node is encountered in the document. This visitor only records runs that are inside editable ranges.
      /// </summary>
      public int visitRun(final Run run) {
          if (mInsideEditableRange) {
              mBuilder.append("\t\"" + run.getText() + "\"" + "\r\n");
          }
  
          return VisitorAction.CONTINUE;
      }
  
      private boolean mInsideEditableRange;
      private StringBuilder mBuilder;
  }

• getId

  public int getId()
  

  Gets the editable range identifier.

  The region must be demarcated using the EditableRangeStart and EditableRangeEnd

  Editable range identifiers are supposed to be unique across a document and Aspose.Words automatically maintains editable range identifiers when loading, saving and combining documents.

  Example:

  Shows how to work with an editable range.

  Document doc = new Document();
  doc.protect(ProtectionType.READ_ONLY, "MyPassword");
  
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
          " we cannot edit this paragraph without the password.");
  
  // Editable ranges allow us to leave parts of protected documents open for editing.
  EditableRangeStart editableRangeStart = builder.startEditableRange();
  builder.writeln("This paragraph is inside an editable range, and can be edited.");
  EditableRangeEnd editableRangeEnd = builder.endEditableRange();
  
  // A well-formed editable range has a start node, and end node.
  // These nodes have matching IDs and encompass editable nodes.
  EditableRange editableRange = editableRangeStart.getEditableRange();
  
  Assert.assertEquals(editableRangeStart.getId(), editableRange.getId());
  Assert.assertEquals(editableRangeEnd.getId(), editableRange.getId());
  
  // Different parts of the editable range link to each other.
  Assert.assertEquals(editableRangeStart.getId(), editableRange.getEditableRangeStart().getId());
  Assert.assertEquals(editableRangeStart.getId(), editableRangeEnd.getEditableRangeStart().getId());
  Assert.assertEquals(editableRange.getId(), editableRangeStart.getEditableRange().getId());
  Assert.assertEquals(editableRangeEnd.getId(), editableRange.getEditableRangeEnd().getId());
  
  // We can access the node types of each part like this. The editable range itself is not a node,
  // but an entity which consists of a start, an end, and their enclosed contents.
  Assert.assertEquals(NodeType.EDITABLE_RANGE_START, editableRangeStart.getNodeType());
  Assert.assertEquals(NodeType.EDITABLE_RANGE_END, editableRangeEnd.getNodeType());
  
  builder.writeln("This paragraph is outside the editable range, and cannot be edited.");
  
  doc.save(getArtifactsDir() + "EditableRange.CreateAndRemove.docx");
  
  // Remove an editable range. All the nodes that were inside the range will remain intact.
  editableRange.remove();

• getSingleUser/setSingleUser

  public java.lang.String getSingleUser() / public void setSingleUser(java.lang.String value)
  

  Returns or sets the single user for editable range.

  This editor can be stored in one of the following forms:

  DOMAIN\Username - for users whose access shall be authenticated using the current user's domain credentials.

  user@domain.com - for users whose access shall be authenticated using the user's e-mail address as credentials.

  user - for users whose access shall be authenticated using the current user's machine credentials.

  Single user and editor group cannot be set simultaneously for the specific editable range, if the one is set, the other will be clear.

  Example:

  Shows how to limit the editing rights of editable ranges to a specific group/user.

  public void visitor() throws Exception
  {
      Document doc = new Document();
      doc.protect(ProtectionType.READ_ONLY, "MyPassword");
  
      DocumentBuilder builder = new DocumentBuilder(doc);
      builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
                      " we cannot edit this paragraph without the password.");
  
      // When we write-protect documents, editable ranges allow us to pick specific areas that users are allowed to edit.
      // There are two mutually exclusive ways to narrow down the list of allowed editors.
      // 1 -  Specify a user:
      EditableRange editableRange = builder.startEditableRange().getEditableRange();
      editableRange.setSingleUser("john.doe@myoffice.com");
      builder.writeln(MessageFormat.format("This paragraph is inside the first editable range, can only be edited by {0}.", editableRange.getSingleUser()));
      builder.endEditableRange();
  
      Assert.assertEquals(EditorType.UNSPECIFIED, editableRange.getEditorGroup());
  
      // 2 -  Specify a group that allowed users are associated with:
      editableRange = builder.startEditableRange().getEditableRange();
      editableRange.setEditorGroup(EditorType.ADMINISTRATORS);
      builder.writeln(MessageFormat.format("This paragraph is inside the first editable range, can only be edited by {0}.", editableRange.getEditorGroup()));
      builder.endEditableRange();
  
      Assert.assertEquals("", editableRange.getSingleUser());
  
      builder.writeln("This paragraph is outside the editable range, and cannot be edited by anybody.");
  
      // Print details and contents of every editable range in the document.
      EditableRangePrinter editableRangePrinter = new EditableRangePrinter();
  
      doc.accept(editableRangePrinter);
  
      System.out.println(editableRangePrinter.toText());
  }
  
  /// <summary>
  /// Collects attributes and contents of visited editable ranges in a string.
  /// </summary>
  public static class EditableRangePrinter extends DocumentVisitor {
      public EditableRangePrinter() {
          mBuilder = new StringBuilder();
      }
  
      public String toText() {
          return mBuilder.toString();
      }
  
      public void reset()
      {
          mBuilder.setLength(0);
          mInsideEditableRange = false;
      }
  
      /// <summary>
      /// Called when an EditableRangeStart node is encountered in the document.
      /// </summary>
      public /*override*/ /*VisitorAction*/int visitEditableRangeStart(EditableRangeStart editableRangeStart)
      {
          mBuilder.append(" -- Editable range found! -- ");
          mBuilder.append("\tID:\t\t" + editableRangeStart.getId());
          if (editableRangeStart.getEditableRange().getSingleUser().equals(""))
              mBuilder.append("\tGroup:\t" + editableRangeStart.getEditableRange().getEditorGroup());
          else
              mBuilder.append("\tUser:\t" + editableRangeStart.getEditableRange().getSingleUser());
          mBuilder.append("\tContents:");
  
          mInsideEditableRange = true;
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called when an EditableRangeEnd node is encountered in the document.
      /// </summary>
      public int visitEditableRangeEnd(final EditableRangeEnd editableRangeEnd) {
          mBuilder.append(" -- End of editable range -- " + "\r\n");
  
          mInsideEditableRange = false;
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called when a Run node is encountered in the document. This visitor only records runs that are inside editable ranges.
      /// </summary>
      public int visitRun(final Run run) {
          if (mInsideEditableRange) {
              mBuilder.append("\t\"" + run.getText() + "\"" + "\r\n");
          }
  
          return VisitorAction.CONTINUE;
      }
  
      private boolean mInsideEditableRange;
      private StringBuilder mBuilder;
  }

Method Detail

• remove

  public void remove()
             throws java.lang.Exception

  Removes the editable range from the document. Does not remove content inside the editable range.

  Example:

  Shows how to work with an editable range.

  Document doc = new Document();
  doc.protect(ProtectionType.READ_ONLY, "MyPassword");
  
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.writeln("Hello world! Since we have set the document's protection level to read-only," +
          " we cannot edit this paragraph without the password.");
  
  // Editable ranges allow us to leave parts of protected documents open for editing.
  EditableRangeStart editableRangeStart = builder.startEditableRange();
  builder.writeln("This paragraph is inside an editable range, and can be edited.");
  EditableRangeEnd editableRangeEnd = builder.endEditableRange();
  
  // A well-formed editable range has a start node, and end node.
  // These nodes have matching IDs and encompass editable nodes.
  EditableRange editableRange = editableRangeStart.getEditableRange();
  
  Assert.assertEquals(editableRangeStart.getId(), editableRange.getId());
  Assert.assertEquals(editableRangeEnd.getId(), editableRange.getId());
  
  // Different parts of the editable range link to each other.
  Assert.assertEquals(editableRangeStart.getId(), editableRange.getEditableRangeStart().getId());
  Assert.assertEquals(editableRangeStart.getId(), editableRangeEnd.getEditableRangeStart().getId());
  Assert.assertEquals(editableRange.getId(), editableRangeStart.getEditableRange().getId());
  Assert.assertEquals(editableRangeEnd.getId(), editableRange.getEditableRangeEnd().getId());
  
  // We can access the node types of each part like this. The editable range itself is not a node,
  // but an entity which consists of a start, an end, and their enclosed contents.
  Assert.assertEquals(NodeType.EDITABLE_RANGE_START, editableRangeStart.getNodeType());
  Assert.assertEquals(NodeType.EDITABLE_RANGE_END, editableRangeEnd.getNodeType());
  
  builder.writeln("This paragraph is outside the editable range, and cannot be edited.");
  
  doc.save(getArtifactsDir() + "EditableRange.CreateAndRemove.docx");
  
  // Remove an editable range. All the nodes that were inside the range will remain intact.
  editableRange.remove();