CPDFOutline.h 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104
  1. //
  2. // CPDFOutline.h
  3. // ComPDFKit
  4. //
  5. // Copyright © 2014-2023 PDF Technologies, Inc. All Rights Reserved.
  6. //
  7. // THIS SOURCE CODE AND ANY ACCOMPANYING DOCUMENTATION ARE PROTECTED BY INTERNATIONAL COPYRIGHT LAW
  8. // AND MAY NOT BE RESOLD OR REDISTRIBUTED. USAGE IS BOUND TO THE ComPDFKit LICENSE AGREEMENT.
  9. // UNAUTHORIZED REPRODUCTION OR DISTRIBUTION IS SUBJECT TO CIVIL AND CRIMINAL PENALTIES.
  10. // This notice may not be removed from this file.
  11. //
  12. #import <ComPDFKit/CPDFKitPlatform.h>
  13. @class CPDFDocument, CPDFDestination, CPDFAction;
  14. /**
  15. * A CPDFOutline object is an element in a tree-structured hierarchy that can represent the structure of a PDF document.
  16. *
  17. * @discussion An outline is an optional component of a PDF document, useful for viewing the structure of the document and for navigating within it.
  18. * Outlines are created by the document’s author. If you represent a PDF document outline using outline objects, the root of the hierarchy is obtained from the PDF document itself.
  19. * This root outline is not visible and serves merely as a container for the visible outlines.
  20. */
  21. @interface CPDFOutline : NSObject
  22. #pragma mark - Accessors
  23. /**
  24. * Returns the document with which the outline is associated.
  25. */
  26. @property (nonatomic,readonly) CPDFDocument *document;
  27. /**
  28. * Returns the parent outline object of the outline (returns NULL if called on the root outline object).
  29. */
  30. @property (nonatomic,readonly) CPDFOutline *parent;
  31. /**
  32. * Returns the number of child outline objects in the outline.
  33. */
  34. @property (nonatomic,readonly) NSUInteger numberOfChildren;
  35. /**
  36. * Returns the index of the outline item, relative to its siblings (and from the perspective of the parent).
  37. *
  38. * @discussion The root outline item (or any item with no parent) is always index 0.
  39. */
  40. @property (nonatomic,readonly) NSUInteger index;
  41. /**
  42. * Method to get / set the label for the outline.
  43. *
  44. * @discussion The root outline serves only as a container for the outlines it owns; it does not have a label.
  45. */
  46. @property (nonatomic,retain) NSString *label;
  47. /**
  48. * Method to get / set the destination associated with the outline.
  49. *
  50. * @discussion The root outline serves only as a container for the outlines it owns; it does not have a destination.
  51. * Note that a CPDFOutline object can have either a destination or an action, not both.
  52. * This method may return NULL if the outline has an associated action instead of a destination.
  53. * Note that if the associated action is a CPDFGoToAction, this method returns the destination from the CPDFGoToAction object.
  54. * However, it is better to use the action method for this purpose.
  55. */
  56. @property (nonatomic,retain) CPDFDestination *destination;
  57. /**
  58. * Method to get / set the action performed when users click the outline.
  59. *
  60. * @discussion The root outline serves only as a container for the outlines it owns; it does not have an action.
  61. * Note that a CPDFOutline object can have either an action or a destination, not both.
  62. * If the CPDFOutline object has a destination, instead of an action, action returns a CPDFGoToAction object (this is equivalent to calling destination on the CPDFOutline object).
  63. * For other action types, action returns the appropriate PDF Kit action type object, such as CPDFURLAction.
  64. */
  65. @property (nonatomic,retain) CPDFAction *action;
  66. /**
  67. * Returns the child outline object at the specified index.
  68. *
  69. * @discussion The index is zero-based. This method throws an exception if index is out of range.
  70. * A PDFOutline object retains all its children, so childAtIndex: returns the same retained child outline object every time it’s called.
  71. * This means that you do not need to retain the object returned by childAtIndex:.
  72. */
  73. - (CPDFOutline *)childAtIndex:(NSUInteger)index;
  74. /**
  75. * Create a outline object and inserts the outline object at the specified index.
  76. *
  77. * @discussion To build a PDF outline hierarchy, use this method to add child outline objects.
  78. */
  79. - (CPDFOutline *)insertChildAtIndex:(NSUInteger)index;
  80. /**
  81. * @discussion When moving items around within an outline hierarchy, you should retain the item and call -[removeFromParent] first.
  82. */
  83. - (void)insertChild:(CPDFOutline *)child atIndex:(NSUInteger)index;
  84. /**
  85. * Removes the outline object from its parent.
  86. */
  87. - (void)removeFromParent;
  88. @end