/////////////////////////////////////////////////////////////////////////////// 
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance"). 
// All rights reserved. 
// 
// This software and its documentation and related materials are owned by 
// the Alliance. The software may only be incorporated into application 
// programs owned by members of the Alliance, subject to a signed 
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable  
// trade secrets of the Alliance and its suppliers. The software is also 
// protected by copyright law and international treaty provisions. Application  
// programs incorporating this software must include the following statement 
// with their copyright notices:
//   
//   This application incorporates Open Design Alliance software pursuant to a license 
//   agreement with Open Design Alliance.
//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance. 
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you 
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////


///////////////////////////////////////////////////////////////////////////////
//
// PdfPublishMarkupAnnotation.h
//
///////////////////////////////////////////////////////////////////////////////

#ifndef _PDF_PUBLISH_MARKUP_ANNOTATION_INCLUDED_
#define _PDF_PUBLISH_MARKUP_ANNOTATION_INCLUDED_

#include "PdfPublishBaseObject.h"

/** \details
  Contains declarations for Publish SDK.
  <group TD_Namespaces>
*/
namespace OdPdfPublish{

/** \details
  This class implements base functionality for working with markup annotations in a PDF document created with Publish SDK.
  Markup annotations include sticky notes, which allow placing an icon on a page that, when clicked, displays a popup window with text information.
*/
class PDFPUBLISH_TOOLKIT OdMarkupAnnotation : public OdObject
{
  //DOM-IGNORE-BEGIN
protected:
  OdMarkupAnnotation();
  OdMarkupAnnotation(OdPublishObjectImpl* pImpl);
  //DOM-IGNORE-END

public:
  //DOM-IGNORE-BEGIN
  ODRX_DECLARE_MEMBERS(OdMarkupAnnotation);
  ODRX_HEAP_OPERATORS();
  //DOM-IGNORE-END

  /** \details
    Destroys the markup annotation object.
  */
  virtual ~OdMarkupAnnotation();

  /** \details
    Sets the location of the popup window that displays the annotation content.
    \param popup_location [in] A <exref target="../tkernel_api_cpp/ODRECT.html">rectangle</exref> that specifies the area on the page where the popup window appears.
  */
  void setPopupLocation(const OdRect& popup_location);

  /** \details
    Sets the open state of the popup window.
    \param state [in] A new flag value.
    \remarks
    If true, the popup window is initially displayed when the document is opened. The default value is false.
  */
  void setOpen(const bool state);

  /** \details
    Sets the content displayed in the popup window.
    \param value [in] A <exref target="../tkernel_api_cpp/OdString.html">string</exref> that contains the annotation content.
  */
  void setContents(const OdString& value);

  /** \details
    Sets the title of the popup window.
    \param value [in] A <exref target="../tkernel_api_cpp/OdString.html">string</exref> that contains the title.
    \remarks
    Typically, the title contains the name of the user who added the annotation.
  */
  void setTitle(const OdString& value);

  /** \details
    Sets the description of the annotation.
    \param value [in] A <exref target="../tkernel_api_cpp/OdString.html">string</exref> containing the description.
    \remarks
    The description is visible in the annotation properties dialog.
  */
  void setDescription(const OdString& value);

  /** \details
    Sets the creation date and time of the annotation.
    \param value [in] An <exref target="../tkernel_api_cpp/OdTimeStamp.html">OdTimeStamp</exref> object that stores the creation time.
  */
  void setCreationDate(const OdTimeStamp& value);

  /** \details
    Sets the icon opacity of the annotation.
    \param value [in] An opacity value in the range from 0 to 100. Default is 100.
  */
  void setOpacity(const OdUInt8& value);

  /** \details
    Sets the color of the annotation.
    \param color [in] A new color value.
    \remarks
    Affects the icon and the popup window border.
  */
  void setColor(const ODCOLORREF color);

  /** \details
    Sets the lock flag for the annotation.
    \param state [in] A new flag value.
    \remarks
    If true, the annotation cannot be modified. If false, it can be edited. Default is false.
  */
  void setLock(const bool state);

  /** \details
    Sets the <link OdPdfPublish::StickyNotes::StickyNoteMarkedStates, marked state> of the annotation.
    \param marked_state [in] A new <link OdPdfPublish::StickyNotes::StickyNoteMarkedStates, marked state> value.
    \remarks
    Default value is <link OdPdfPublish::StickyNotes::StickyNoteMarkedStates::kUnmarkedState, kUnmarkedState>.
  */
  void setMarkedState(const MarkupAnnotations::MarkupAnnotationMarkedStates& marked_state);

  /** \details
    Sets the <link OdPdfPublish::StickyNotes::StickyNoteReviewStates, review state> of the annotation.
    \param review_state [in] A new <link OdPdfPublish::StickyNotes::StickyNoteReviewStates, review state> value.
    \remarks
    Default value is <link OdPdfPublish::StickyNotes::StickyNoteReviewStates::kNone, kNone>.
  */
  void setReviewState(const MarkupAnnotations::MarkupAnnotationReviewStates& review_state);

  /** \details
    Returns the popup window location.
    \param popup_location [out] A rectangle to receive the location data.
  */
  void getPopupLocation(OdRect& popup_location) const;

  /** \details
    Returns the open state of the popup window.
    \param state [out] A boolean to receive the flag value.
  */
  void getOpen(bool& state) const;

  /** \details
    Returns the content displayed in the popup window.
    \param value [out] A string to receive the content.
  */
  void getContents(OdString& value) const;

  /** \details
    Returns the title of the popup window.
    \param value [out] A string to receive the title.
  */
  void getTitle(OdString& value) const;

  /** \details
    Returns the annotation description.
    \param value [out] A string to receive the description.
  */
  void getDescription(OdString& value) const;

  /** \details
    Returns the creation date and time of the annotation.
    \param value [out] An <exref target="../tkernel_api_cpp/OdTimeStamp.html">OdTimeStamp</exref> to receive the date and time.
    \returns true if the creation date is set, false otherwise.
  */
  bool getCreationDate(OdTimeStamp& value) const;

  /** \details
    Returns the opacity of the annotation.
    \param value [out] An unsigned 8-bit value to receive the opacity.
  */
  void getOpacity(OdUInt8& value) const;

  /** \details
    Returns the color of the annotation.
    \param color [out] A variable to receive the color value.
  */
  void getColor(ODCOLORREF& color) const;

  /** \details
    Returns the lock state of the annotation.
    \param state [out] A boolean to receive the lock flag.
  */
  void getLock(bool& state) const;

  /** \details
    Returns the <link OdPdfPublish::StickyNotes::StickyNoteMarkedStates, marked state> of the annotation.
    \param marked_state [out] A variable to receive the marked state value.
  */
  void getMarkedState(MarkupAnnotations::MarkupAnnotationMarkedStates& marked_state) const;

  /** \details
    Returns the <link OdPdfPublish::StickyNotes::StickyNoteReviewStates, review state> of the annotation.
    \param review_state [out] A variable to receive the review state value.
  */
  void getReviewState(MarkupAnnotations::MarkupAnnotationReviewStates& review_state) const;
};

/** \details
  A data type that represents a smart pointer to an <link OdPdfPublish::OdMarkupAnnotation, OdMarkupAnnotation> object.
*/
SMARTPTR(OdMarkupAnnotation);

}
#endif // _PDF_PUBLISH_MARKUP_ANNOTATION_INCLUDED_