Skip to content

Commit e0eb683

Browse files
IdamkinIIdamkinI
committed
Update documentation for deprecated methods in annotation package
DEVSIX-1401
1 parent aa06953 commit e0eb683

File tree

2 files changed

+48
-169
lines changed

2 files changed

+48
-169
lines changed

‎kernel/src/main/java/com/itextpdf/kernel/pdf/annot/PdfAnnotation.java

Lines changed: 26 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -360,21 +360,15 @@ public void setLayer(IPdfOCG layer) {
360360
}
361361

362362
/**
363-
* Sets a {@link PdfAction} to this annotation which will be performed when the annotation is activated.
364-
* @param action {@link PdfAction} to set to this annotation.
365-
* @return this {@link PdfAnnotation} instance.
363+
* @deprecated Supported only for {@link PdfLinkAnnotation}, {@link PdfScreenAnnotation}, {@link PdfWidgetAnnotation}, will be removed in 7.1
366364
*/
367365
@Deprecated
368366
public PdfAnnotation setAction(PdfAction action) {
369367
return put(PdfName.A, action.getPdfObject());
370368
}
371369

372370
/**
373-
* Sets an additional {@link PdfAction} to this annotation which will be performed in response to
374-
* the specific trigger event defined by {@code key}. See ISO-320001 12.6.3, "Trigger Events".
375-
* @param key a {@link PdfName} that denotes a type of the additional action to set.
376-
* @param action {@link PdfAction} to set as additional to this annotation.
377-
* @return this {@link PdfAnnotation} instance.
371+
* @deprecated Supported only for {@link PdfScreenAnnotation}, {@link PdfWidgetAnnotation}, will be removed in 7.1
378372
*/
379373
@Deprecated
380374
public PdfAnnotation setAdditionalAction(PdfName key, PdfAction action) {
@@ -889,9 +883,7 @@ public PdfAnnotation setStructParentIndex(int structParentIndex) {
889883
}
890884

891885
/**
892-
* A flag specifying whether the annotation shall initially be displayed open.
893-
* This flag has affect to not all kinds of annotations.
894-
* @return true if annotation is initially open, false - if closed.
886+
* @deprecated Supported only for {@link PdfTextAnnotation}, {@link PdfPopupAnnotation}, will be removed in 7.1
895887
*/
896888
@Deprecated
897889
public boolean getOpen() {
@@ -900,111 +892,67 @@ public boolean getOpen() {
900892
}
901893

902894
/**
903-
* Sets a flag specifying whether the annotation shall initially be displayed open.
904-
* This flag has affect to not all kinds of annotations.
905-
* @param open true if annotation shall initially be open, false - if closed.
906-
* @return this {@link PdfAnnotation} instance.
895+
* @deprecated Supported only for {@link PdfTextAnnotation}, {@link PdfPopupAnnotation}, will be removed in 7.1
907896
*/
908897
@Deprecated
909898
public PdfAnnotation setOpen(boolean open) {
910899
return put(PdfName.Open, PdfBoolean.valueOf(open));
911900
}
912901

913902
/**
914-
* An array of 8 × n numbers specifying the coordinates of n quadrilaterals in default user space.
915-
* Quadrilaterals are used to define:
916-
* <ul>
917-
* <li>regions inside annotation rectangle in which the link annotation should be activated;</li>
918-
* <li>a word or group of contiguous words in the text underlying the text markup annotation;</li>
919-
* <li>the content region that is intended to be removed for a redaction annotation;</li>
920-
* </ul>
921-
*
922-
* <p>
923-
* IMPORTANT NOTE: According to Table 179 in ISO 32000-1, the QuadPoints array lists the vertices in counterclockwise
924-
* order and the text orientation is defined by the first and second vertex. This basically means QuadPoints is
925-
* specified as lower-left, lower-right, top-right, top-left. HOWEVER, Adobe's interpretation
926-
* (tested at least with Acrobat 10, Acrobat 11, Reader 11) is top-left, top-right, lower-left, lower-right (Z-shaped order).
927-
* This means that if the QuadPoints array is specified according to the standard, the rendering is not as expected.
928-
* Other viewers seem to follow Adobe's interpretation. Hence we recommend to use and expect QuadPoints array in Z-order,
929-
* just as Acrobat and probably most other viewers expect.
930-
* @return an {@link PdfArray} of 8 × n numbers specifying the coordinates of n quadrilaterals.
903+
* @deprecated Supported only for {@link PdfLinkAnnotation}, {@link PdfTextMarkupAnnotation}, {@link PdfRedactAnnotation} will be removed in 7.1
931904
*/
932905
@Deprecated
933906
public PdfArray getQuadPoints() {
934907
return getPdfObject().getAsArray(PdfName.QuadPoints);
935908
}
936909

937910
/**
938-
* Sets n quadrilaterals in default user space by passing an {@link PdfArray} of 8 × n numbers. For more info of what
939-
* quadrilaterals define see {@link PdfAnnotation#getQuadPoints()}.
940-
*
941-
* <p>
942-
* IMPORTANT NOTE: According to Table 179 in ISO 32000-1, the QuadPoints array lists the vertices in counterclockwise
943-
* order and the text orientation is defined by the first and second vertex. This basically means QuadPoints is
944-
* specified as lower-left, lower-right, top-right, top-left. HOWEVER, Adobe's interpretation
945-
* (tested at least with Acrobat 10, Acrobat 11, Reader 11) is top-left, top-right, lower-left, lower-right (Z-shaped order).
946-
* This means that if the QuadPoints array is specified according to the standard, the rendering is not as expected.
947-
* Other viewers seem to follow Adobe's interpretation. Hence we recommend to use and expect QuadPoints array in Z-order,
948-
* just as Acrobat and probably most other viewers expect.
949-
* @param quadPoints an {@link PdfArray} of 8 × n numbers specifying the coordinates of n quadrilaterals.
950-
* @return this {@link PdfAnnotation} instance.
911+
* @deprecated Supported only for {@link PdfLinkAnnotation}, {@link PdfTextMarkupAnnotation}, {@link PdfRedactAnnotation} will be removed in 7.1
951912
*/
952913
@Deprecated
953914
public PdfAnnotation setQuadPoints(PdfArray quadPoints) {
954915
return put(PdfName.QuadPoints, quadPoints);
955916
}
956917

957918
/**
958-
* Sets border style dictionary that has more settings than the array specified for the Border entry ({@link PdfAnnotation#getBorder()}).
959-
* See ISO-320001, Table 166 and {@link PdfAnnotation#getBorderStyle()} for more info.
960-
* @param borderStyle a border style dictionary specifying the line width and dash pattern that shall be used
961-
* in drawing the annotation’s border.
962-
* @return this {@link PdfAnnotation} instance.
919+
* @deprecated Supported only for:
920+
* {@link PdfLinkAnnotation}, {@link PdfFreeTextAnnotation}, {@link PdfLineAnnotation}, {@link PdfSquareAnnotation},
921+
* {@link PdfCircleAnnotation}, {@link PdfPolyGeomAnnotation}, {@link PdfInkAnnotation}, {@link PdfWidgetAnnotation}
922+
* will be removed in 7.1
963923
*/
964924
@Deprecated
965925
public PdfAnnotation setBorderStyle(PdfDictionary borderStyle) {
966926
return put(PdfName.BS, borderStyle);
967927
}
968928

969929
/**
970-
* Setter for the annotation's preset border style. Possible values are
971-
* <ul>
972-
* <li>{@link PdfAnnotation#STYLE_SOLID} - A solid rectangle surrounding the annotation.</li>
973-
* <li>{@link PdfAnnotation#STYLE_DASHED} - A dashed rectangle surrounding the annotation.</li>
974-
* <li>{@link PdfAnnotation#STYLE_BEVELED} - A simulated embossed rectangle that appears to be raised above the surface of the page.</li>
975-
* <li>{@link PdfAnnotation#STYLE_INSET} - A simulated engraved rectangle that appears to be recessed below the surface of the page.</li>
976-
* <li>{@link PdfAnnotation#STYLE_UNDERLINE} - A single line along the bottom of the annotation rectangle.</li>
977-
* </ul>
978-
* See also ISO-320001, Table 166.
979-
* @param style The new value for the annotation's border style.
980-
* @return The annotation which this method was called on.
981-
* @see PdfAnnotation#getBorderStyle()
930+
* @deprecated Supported only for:
931+
* {@link PdfLinkAnnotation}, {@link PdfFreeTextAnnotation}, {@link PdfLineAnnotation}, {@link PdfSquareAnnotation},
932+
* {@link PdfCircleAnnotation}, {@link PdfPolyGeomAnnotation}, {@link PdfInkAnnotation}, {@link PdfWidgetAnnotation}
933+
* will be removed in 7.1
982934
*/
983935
@Deprecated
984936
public PdfAnnotation setBorderStyle(PdfName style) {
985937
return setBorderStyle(BorderStyleUtil.setStyle(getBorderStyle(), style));
986938
}
987939

988940
/**
989-
* Setter for the annotation's preset dashed border style. This property has affect only if {@link PdfAnnotation#STYLE_DASHED}
990-
* style was used for the annotation border style (see {@link PdfAnnotation#setBorderStyle(PdfName)}.
991-
* See ISO-320001 8.4.3.6, “Line Dash Pattern” for the format in which dash pattern shall be specified.
992-
* @param dashPattern a dash array defining a pattern of dashes and gaps that
993-
* shall be used in drawing a dashed border.
994-
* @return this {@link PdfAnnotation} instance.
941+
* @deprecated Supported only for:
942+
* {@link PdfLinkAnnotation}, {@link PdfFreeTextAnnotation}, {@link PdfLineAnnotation}, {@link PdfSquareAnnotation},
943+
* {@link PdfCircleAnnotation}, {@link PdfPolyGeomAnnotation}, {@link PdfInkAnnotation}, {@link PdfWidgetAnnotation}
944+
* will be removed in 7.1
995945
*/
996946
@Deprecated
997947
public PdfAnnotation setDashPattern(PdfArray dashPattern) {
998948
return setBorderStyle(BorderStyleUtil.setDashPattern(getBorderStyle(), dashPattern));
999949
}
1000950

1001951
/**
1002-
* The dictionaries for some annotation types (such as free text and polygon annotations) can include the BS entry.
1003-
* That entry specifies a border style dictionary that has more settings than the array specified for the Border
1004-
* entry (see {@link PdfAnnotation#getBorder()}). If an annotation dictionary includes the BS entry, then the Border
1005-
* entry is ignored. If annotation includes AP (see {@link PdfAnnotation#getAppearanceDictionary()}) it takes
1006-
* precedence over the BS entry. For more info on BS entry see ISO-320001, Table 166.
1007-
* @return {@link PdfDictionary} which is a border style dictionary or null if it is not specified.
952+
* @deprecated Supported only for:
953+
* {@link PdfLinkAnnotation}, {@link PdfFreeTextAnnotation}, {@link PdfLineAnnotation}, {@link PdfSquareAnnotation},
954+
* {@link PdfCircleAnnotation}, {@link PdfPolyGeomAnnotation}, {@link PdfInkAnnotation}, {@link PdfWidgetAnnotation}
955+
* will be removed in 7.1
1008956
*/
1009957
@Deprecated
1010958
public PdfDictionary getBorderStyle() {
@@ -1031,43 +979,31 @@ public PdfString getTitle() {
1031979
}
1032980

1033981
/**
1034-
* Sets an appearance characteristics dictionary containing additional information for constructing the
1035-
* annotation’s appearance stream. See ISO-320001, Table 189.
1036-
* This property affects {@link PdfWidgetAnnotation} and {@link PdfScreenAnnotation}.
1037-
* @param characteristics the {@link PdfDictionary} with additional information for appearance stream.
1038-
* @return this {@link PdfAnnotation} instance.
982+
* @deprecated Supported only for {@link PdfScreenAnnotation}, {@link PdfWidgetAnnotation}, will be removed in 7.1
1039983
*/
1040984
@Deprecated
1041985
public PdfAnnotation setAppearanceCharacteristics(PdfDictionary characteristics) {
1042986
return put(PdfName.MK, characteristics);
1043987
}
1044988

1045989
/**
1046-
* An appearance characteristics dictionary containing additional information for constructing the
1047-
* annotation’s appearance stream. See ISO-320001, Table 189.
1048-
* This property affects {@link PdfWidgetAnnotation} and {@link PdfScreenAnnotation}.
1049-
* @return an appearance characteristics dictionary or null if it isn't specified.
990+
* @deprecated Supported only for {@link PdfScreenAnnotation}, {@link PdfWidgetAnnotation}, will be removed in 7.1
1050991
*/
1051992
@Deprecated
1052993
public PdfDictionary getAppearanceCharacteristics() {
1053994
return getPdfObject().getAsDictionary(PdfName.MK);
1054995
}
1055996

1056997
/**
1057-
* An {@link PdfAction} to perform, such as launching an application, playing a sound,
1058-
* changing an annotation’s appearance state etc, when the annotation is activated.
1059-
* @return {@link PdfDictionary} which defines the characteristics and behaviour of an action.
998+
* @deprecated Supported only for {@link PdfLinkAnnotation}, {@link PdfScreenAnnotation}, {@link PdfWidgetAnnotation}, will be removed in 7.1
1060999
*/
10611000
@Deprecated
10621001
public PdfDictionary getAction() {
10631002
return getPdfObject().getAsDictionary(PdfName.A);
10641003
}
10651004

10661005
/**
1067-
* An additional actions dictionary that extends the set of events that can trigger the execution of an action.
1068-
* See ISO-320001 12.6.3 Trigger Events.
1069-
* @return an additional actions {@link PdfDictionary}.
1070-
* @see PdfAnnotation#getAction()
1006+
* @deprecated Supported only for {@link PdfScreenAnnotation}, {@link PdfWidgetAnnotation}, will be removed in 7.1
10711007
*/
10721008
@Deprecated
10731009
public PdfDictionary getAdditionalAction() {

0 commit comments

Comments
 (0)