PDFViewCtrl.h

Go to the documentation of this file.

//---------------------------------------------------------------------------------------
// Copyright (c) 2001-2025 by Apryse Software Inc. All Rights Reserved.
// Consult legal.txt regarding legal and license information.
//---------------------------------------------------------------------------------------
#ifndef PDFTRON_H_CPPPDFPDFViewCtrl
#define PDFTRON_H_CPPPDFPDFViewCtrl
 
#include <PDF/PDFDoc.h>
#include <PDF/PDFRasterizer.h>
#include <PDF/Highlights.h>
#include <PDF/LinkInfo.h>
#include <PDF/OCG/Context.h>
#include <PDF/Selection.h>
#include <SDF/ObjSet.h>
#include <C/PDF/TRN_PDFViewCtrl.h>
#include <vector>
#include <PDF/ActionParameter.h>
 
namespace pdftron {
    namespace PDF {

class PDFViewCtrl
{
public:

    PDFViewCtrl(void* parent_hwnd, void* hinstance, bool compatibility = false);
    ~PDFViewCtrl();

    bool SetDoc(PDFDoc& doc, const char* password = 0);

    void CloseDoc();

    PDFDoc* GetDoc();

     void DocLock(bool cancel_threads);

     void DocUnlock();

     bool DocTryLock( int milliseconds = 0 );

     void DocLockRead();

     void DocUnlockRead();

     bool DocTryLockRead( int milliseconds = 0 );

    enum WindowID {
        e_main_view,
        e_thumb_view,
        e_layers_view,
        e_bookmark_view,
        e_navigation_pane,
        e_navigation_toolbar,
        e_toolbar,
        e_status_bar,
        e_dialog_modal,
        e_dialog_modeless
    };
 
    enum ControlEventType {
        e_mouse_move,
        e_mouse_enter,
        e_mouse_leave,
        e_mouse_left_down,
        e_mouse_left_up,
        e_mouse_left_dclick,
        e_mouse_right_down,
        e_mouse_right_up,
        e_mouse_right_dclick,
        e_mouse_middle_down,
        e_mouse_middle_up,
        e_mouse_middle_dclick,
        e_mouse_wheel,
        e_context_menu,
        e_key_down,
        e_key_up,
        e_key_press,
        e_paint,
        e_window_open,
        e_window_close
    };
 

    struct MouseEvent {
        int         m_x;
        int         m_y;
        int         m_wheelRotation;
        int         m_wheelDelta;
        int         m_linesPerAction;
        UInt8       m_leftDown;
        UInt8       m_middleDown;
        UInt8       m_rightDown;
        UInt8       m_controlDown;
        UInt8       m_shiftDown;
        UInt8       m_altDown;
        UInt8       m_metaDown;
 
        // identifies  the type of event
        enum ControlEventType m_event_type;
        // identifies which window emitted the event
        enum WindowID m_event_window;
        // if TRUE, this event was emitted after PDFViewCtrl has processed it
        UInt8        m_pdfviewctrl_processed; 
    };

    struct KeyEvent {
        int          m_x;
        int          m_y;
        long int     m_keyCode;
        Unicode       m_unicode;
        UInt8        m_controlDown;
        UInt8        m_shiftDown;
        UInt8        m_altDown;
        UInt8        m_metaDown;
        // identifies  the type of event
        enum ControlEventType m_event_type;
        // this helps you identify which window emitted the event
        enum WindowID m_event_window;
        // if TRUE, this event was emitted after PDFViewCtrl has processed it
        UInt8        m_pdfviewctrl_processed; 
    };

    struct PaintEvent {
        // platform-dependent device context pointer
        void*           m_hdc;
        enum TRN_PDFViewCtrlWindowID m_event_window;
        TRN_Bool        m_pdfviewctrl_processed; 
    };
 
    struct SizeEvent {
        int m_width;
        int m_height;
        int m_x_position;
        int m_y_position;
        // this helps you identify which window emitted the event
        enum WindowID m_event_window;
    };

    struct WindowEvent {
        // identifies  the type of event
        enum ControlEventType m_event_type;
        // this helps you identify which window emitted the event
        enum WindowID m_event_window;
    };

    struct TextFindDoneEvent {
        bool m_found;
        enum ControlEventType m_event_type;
        enum WindowID m_event_window;
 
        TextFindDoneEvent( PDFViewCtrl::WindowID id, ControlEventType tp, bool found )
            : m_event_type(tp),
              m_event_window(id),
              m_found(found)
        {}
    };

    struct AnnotationEditPermissionEvent {
        TRN_Annot m_annot;
        // identifies  the type of event
        enum ControlEventType m_event_type;
        // this helps you identify which window emitted the event
        enum WindowID m_event_window;
 
        AnnotationEditPermissionEvent(PDFViewCtrl::WindowID id, ControlEventType tp, TRN_Annot annot)
            : m_annot(annot),
              m_event_type(tp),
              m_event_window(id)
        {}
    };
 
    // handlers for generic event signals emitted by PDFViewCtrl;
    // they return boolean, return value of true means no PDFViewCtrl processing should take place
    typedef UInt8 (*MouseEventHandler) ( struct MouseEvent* evt, void* custom_data );
    typedef UInt8 (*KeyEventHandler)   ( struct KeyEvent* evt,   void* custom_data );
    typedef UInt8 (*PaintEventHandler) ( struct PaintEvent* evt, void* custom_data );
    typedef UInt8 (*SizeEventHandler)  ( struct SizeEvent* evt,  void* custom_data );
    typedef UInt8 (*WindowEventHandler)( struct WindowEvent* evt, void* custom_data);
    typedef UInt8 (*TextFindDoneHandler)(struct TextFindDoneEvent* evt, void* custom_data);
    typedef UInt8 (*AnnotationEditPermissionHandler)(struct AnnotationEditPermissionEvent* evt, void* custom_data);

    struct EventHandlers
    {
        MouseEventHandler mouse_move;
        MouseEventHandler mouse_enter;
        MouseEventHandler mouse_leave;
        MouseEventHandler mouse_left_down;
        MouseEventHandler mouse_left_up;
        MouseEventHandler mouse_left_dclick;
        MouseEventHandler mouse_right_down;
        MouseEventHandler mouse_right_up;
        MouseEventHandler mouse_right_dclick;
        MouseEventHandler mouse_middle_down;
        MouseEventHandler mouse_middle_up;
        MouseEventHandler mouse_middle_dclick;
        MouseEventHandler on_mousewheel;
        MouseEventHandler on_context_menu;
        KeyEventHandler    key_down;
        KeyEventHandler   key_up;
        KeyEventHandler   character_entered;
        PaintEventHandler on_paint;
        SizeEventHandler  on_size;
        WindowEventHandler on_window_event;
        TextFindDoneHandler on_find_text_done;
        AnnotationEditPermissionHandler on_edit_annotation;
 
        void* custom_data;
 
        EventHandlers();
    };

    void SetCustomEventHandlers( EventHandlers* handlers );

    typedef UInt8 (*ActionHandler) ( TRN_Action action, void* custom_data );

    void SetActionHandler( ActionHandler action_callback, void* custom_data  );

    void ExecuteAction(ActionParameter action_param );

    typedef void (*CurrentPageHandler) (int current_page, int num_pages, void* data);

    void SetCurrentPageHandler(CurrentPageHandler curr_pagenum_proc, void* data);

    typedef void (*CurrentZoomHandler) (double current_zoom, void* data);

    void SetCurrentZoomHandler(CurrentZoomHandler curr_zoom_proc, void* data);
 
    typedef void (*ErrorReportHandler) (const char* message, void* data);

    void SetErrorReportHandler(ErrorReportHandler error_proc, void* data);

    void OnSize(int x, int y, int width, int height);

    void Find();

    void Copy();

    void SelectAll();

    void SetProgressiveRendering(bool progressive=true);

    void ShowNavPanel(bool show);
    
    bool IsNavPanelVisible() const;

    void EnableScrollbar( bool show );

    void ShowToolbar( bool show);

    void ShowStatusBar( bool show);

    void ShowNavToolbar( bool show);

    void ShowMenuBar( bool show );

    void EnableInteractiveForms(bool on);

    void ShowDialogs(bool show);
 
    static const UInt32 e_none=0x00;
    static const UInt32 e_bookmarks=0x01;
    static const UInt32   e_layers=0x02;
    static const UInt32   e_thumbview=0x04;
    static const UInt32   e_all=0x07;
    typedef UInt32 PanelType;

    void SetEnabledPanels(UInt32 panels);

    UInt32 GetEnabledPanels() const ;

    void SetSelectedPanel(PanelType panel);

    PanelType GetSelectedPanel() const ;

    void SetSplitPosition(int pos);

    int GetSplitPosition() const ;

    void Print();

    void Print(int first_page, int last_page, Page::Rotate rotation, 
        int copies, const char* printer_name);
 
    
    void Print(int first_page, int last_page, Page::Rotate rotation, 
        int copies, const UString& printer_name);
 
    
    void Refresh();
 

    void RequestRendering();
 

    void CaptureMouse();

    void ReleaseMouse();

    bool HasCapture() const;

    void EnableLinkActivation(bool enable);

    void LoadCurrentConfiguration( const UString & path );

    void SaveCurrentConfiguration( const UString & path, Common::ProgressMonitor* progress = 0 );

    Annot GetDefaultAnnotation( const char* type );
        
    void SetWindowBackgroundColor( WindowID winid, const ColorPt& color );
#ifdef WIN32
    void SetWindowCursor( PDFViewCtrl::WindowID winid, HCURSOR cursor );
#endif

    void SetFocus();
 
    /* dialogs creation API */

    void DocProperties();

    void DeletePages();

    void InsertPages(const UString& src_name);

    void InsertBlankPages();

    void ReplacePages(const UString& src_name = UString());

    void RotatePages();

    void ExtractPages();

    void CropPages();

    void AddWatermark();
 
    /* end of dialogs creation API */


    enum PageViewMode
    {
        e_fit_page = 0,
        e_fit_width,
        e_fit_height,
        e_zoom
    };

    void SetPageViewMode(PageViewMode mode);

    PageViewMode GetPageViewMode() const ;

    enum PagePresentationMode
    {
        e_single_page = 1,         //<<< Display one page at a time.
        e_single_continuous,       //<<< Display the pages in one column.
        e_facing,                  //<<< Display the pages two at a time, with odd-numbered pages on the left.
        e_facing_continuous,       //<<< Display the pages in two columns, with odd-numbered pages on the left.
        e_facing_cover,            //<<< Display the pages two at a time, with odd-numbered pages on the right.
        e_facing_continuous_cover  //<<< Display the pages in two columns, with odd-numbered pages on the right.
    };

    void SetPagePresentationMode(PagePresentationMode mode);

    PagePresentationMode GetPagePresentationMode() const ;
    
    void SetColorPostProcessMode(PDFRasterizer::ColorPostProcessMode mode);

    PDFRasterizer::ColorPostProcessMode GetColorPostProcessMode() const;

    int GetCurrentPage() const ;

    int GetPageCount() const ;

    std::vector<int> GetVisiblePages() const ;

    bool GotoFirstPage();

    bool GotoLastPage();

    bool GotoNextPage();

    bool GotoPreviousPage();

    bool SetCurrentPage(int page_num);

    bool ShowRect( int page_num, const Rect& rect );

    double GetZoom() const ;

    bool SetZoom(double zoom);

    bool SetZoom(int x, int y, double zoom);

    bool SmartZoom(int x, int y);

    void RotateClockwise();

    void RotateCounterClockwise();

    Page::Rotate GetRotation() const ;

    int GetPageNumberFromScreenPt(double x, double y) const ;

    void ConvScreenPtToCanvasPt(double& x, double& y) const ;

    void ConvCanvasPtToScreenPt(double& x, double& y) const;

    void ConvCanvasPtToPagePt(double& x, double& y, int page_num = -1) const;

    void ConvPagePtToCanvasPt(double& x, double& y, int page_num = -1) const;

    void ConvScreenPtToPagePt(double& x, double& y, int page_num = -1) const;

    void ConvPagePtToScreenPt(double& x, double& y, int page_num = -1) const;

    void SnapToNearestInDoc(double& screen_x, double& screen_y);

    void SetSnappingMode(UInt32 mode_flags);

    Common::Matrix2D GetDeviceTransform(int page_num = -1) const;

    double GetCanvasWidth() const;

    double GetCanvasHeight() const;

    double GetHScrollPos() const;

    double GetVScrollPos() const;
 

    void OnScroll(int pix_dx, int pix_dy);

    void SetHScrollPos(double pos);

    void SetVScrollPos(double pos);

    bool IsFinishedRendering(bool visible_region_only) const;

    void CancelRendering();

    void Update(bool all = false);

    void Update(const Rect& update);

    void Update(const Annot& annot, int page_num);

    void Update(const Field& field);

    void UpdatePageLayout();

    void HideAnnotation(const Annot& annot);

    void ShowAnnotation(const Annot& annot);

    int GetViewWidth() const;

    int GetViewHeight() const;
 

    void SetDrawAnnotations(bool render_annots);

    void SetUrlExtraction(bool enabled);

    LinkInfo GetLinkAt(int x, int y);

    void SetHighlightFields(bool highlight_fields);
    
    void SetRequiredFieldBorderColor(const ColorPt& new_border_color);

    void SetAntiAliasing(bool enable_aa);

    void SetPathHinting(bool enable_hinting);

    void SetThinLineAdjustment(bool pixel_grid_fit, bool stroke_adjust);

    void SetImageSmoothing(bool smoothing_enabled = true);

    void SetCaching(bool enabled);

    void SetRasterizerType (PDFRasterizer::Type type);

    void SetGamma(double exp);

    void SetOverprint(PDFRasterizer::OverprintPreviewMode op);

    void SetOCGContext(const OCG::Context& ctx);
 
    OCG::Context GetOCGContext();

    enum ToolMode 
    {
        e_custom,                   // Custom tool
        e_pan,                     // Pan tool
        e_text_rect_select,           // Rectangular text selection tool
        e_text_struct_select,       // HTML Style text selection tool
        e_zoom_in,                 // Zoom in tool
        e_zoom_out,                   // Zoom out tool
        e_annot_edit,               // Annotation editing tool
        e_line_create,             // Line creation tool
        e_arrow_create,               // Arrow creation tool
        e_rect_create,             // Rectangle creation tool
        e_oval_create,             // Oval/Ellipse creation tool
        e_ink_create,               // Freehand drawing tool
        e_text_annot_create,     // Text annotation creation tool
        e_stamp_create,               // Stamp Annotation creation tool
        e_highlight_create,           // highlight text tool 
        e_underline_create,           // underline text tool
        e_strikeout_create,           // cross out text tool
        e_squiggly_create,         // squiggly underline tool
        e_text_box_create,         // free text creation tool
        e_calloutbox_create,     // free text with a callout tool
        e_polygon_create,           // polygon creation tool
        e_polyline_create,         // polyline creation tool
        e_file_attachment,         // file attachment creation
        e_sound_attachment,           // sound annotation creation
        e_movie_attachment,           // movie annotation creation
        e_caret_create,               // caret placement tool
        e_redaction_create,           // redaction placement tool    
        e_text_field_create,     // interactive text field creation
        e_check_box_create,           // interactive check box creation tool
        e_radio_button_create,     // interactive radio button tool
        e_list_box_create,         // interactive list box creation tool
        e_combo_box_create,           // interactive combo box creation tool
        e_button_create,         // interactive button creation tool
        e_link_create,             // create a link annotation
        e_tool_mode_end
    };

    void SetToolMode(ToolMode mode);

    ToolMode GetToolMode() const;

    enum TextSelectionMode {
        e_structural,
        e_rectangular,
        e_structural_algorithm_2
    };

     void SetTextSelectionMode(TextSelectionMode tm);

    void SetRightToLeftLanguage(bool flag);

    bool GetRightToLeftLanguage() const;

    bool Select(double x1, double y1, double x2, double y2);

    bool SelectWithSnapping(double x1, double y1, double x2, double y2, bool snap_to_start, bool snap_to_end);

    bool SelectWithSmartSnapping(double x1, double y1, double x2, double y2);

    bool Select(double x1, double y1, int page1, double x2, double y2, int page2);

    bool SelectWithSnapping(double x1, double y1, int page1, double x2, double y2, int page2, bool snap_to_start, bool snap_to_end);

    bool SelectWithSmartSnapping(double x1, double y1, int page1, double x2, double y2, int page2);

    bool Select(const Highlights& highlights);
 
    
    bool Select(const Selection& select);

    bool HasSelection() const;

    void ClearSelection();

    Selection GetSelection( int page = -1 ) const;

    int GetSelectionBeginPage() const ;

    int GetSelectionEndPage() const;

    bool HasSelectionOnPage( int ipage ) const;

    void PrepareWords(int page_num);

    bool WereWordsPrepared(int page_num) const;

    bool IsThereTextInRect(double x1, double y1, double x2, double y2) const;

    void PrepareAnnotsForMouse(int page_num, double distance_threshold, double minimum_line_weight);

    bool WereAnnotsForMousePrepared(int page_num) const;

    Annot::Type GetAnnotTypeUnder(double x, double y);

    void SetPageBorderVisibility(bool border_visible);

    void SetPageTransparencyGrid(bool trans_grid_visible);

    void SetDefaultPageColor(UInt8 r, UInt8 g, UInt8 b);

    void SetBackgroundColor(UInt8 r, UInt8 g, UInt8 b);

    void SetHorizontalAlign(int align);

    void SetVerticalAlign(int align);

    void SetPageSpacing(int horiz_col_space, int vert_col_space, int horiz_pad, int vert_pad);

    Rect GetScreenRectForAnnot(Annot annot, int page_num = -1);

    Annot GetAnnotationAt(int x, int y);

    void SetDownloadReportHandler(DownloadReportHandler download_proc, void* data);

    void OpenURLAsync(const char* url, UString cache_pdf="", const char* password = 0, const class HTTPRequestOptions* options = 0);

    void UpdateCustomHeaders(const class HTTPRequestOptions& options);

    void SetupThumbnails(bool use_embedded, bool generate_at_runtime, bool use_disk_cache, int thumb_max_side_length, size_t max_abs_cache_size, double max_perc_cache_size);

    void ClearThumbCache();

    typedef void (*ThumbAsyncHandler) (int page_num, bool was_thumb_found, const char* thumb_buf, int thumb_width, int thumb_height, void* custom_data);

    void GetThumbAsync(int page_num,  ThumbAsyncHandler proc, void* custom_data);
 
     /*
      * Cancel all pending GetThumbAsync requests. Your callback function will still be called
      * for each canceled request, but 'was_thumb_found' will be set to 'false'.
      */
     void CancelAllThumbRequests();

     typedef void (*RequestRenderInWorkerThreadProc) (void* custom_data);

#ifdef SWIG
     void SetRequestRenderInWorkerThreadProc(Callback* instance);
#else
     void SetRequestRenderInWorkerThreadProc(RequestRenderInWorkerThreadProc proc, void* custom_data);
#endif
 
#ifdef SWIG
    void SetFindTextHandler(Callback * instance);
#else
    typedef void (*FindTextAsyncHandler) (bool success, Selection& select, void * custom_data);

    void SetFindTextHandler(FindTextAsyncHandler proc, void * custom_data);
#endif
    void FindTextAsync(const UString& search_str, bool match_case, bool match_whole_word, 
                        bool search_up, bool reg_exp);
 
 
// @cond PRIVATE_DOC
private:
    TRN_PDFViewCtrl mp_view;
    TRN_PDFDoc temp_doc;
 
    // PDFViewCtrl should not be copied
    PDFViewCtrl(const PDFViewCtrl& other);
    PDFViewCtrl& operator= (const PDFViewCtrl&);
 
    //For FindTextAsync callback landing pad
    FindTextAsyncHandler m_findtext_proc;
    void * m_findtext_data;
    static void NativeFindTextHandler(unsigned char success, TRN_PDFViewSelection select, void * custom_data);
    // @endcond
};

class HTTPRequestOptions
{
public:
    HTTPRequestOptions();
    void AddHeader(const UString& header, const UString& val);
protected:
    TRN_Obj m_obj;
    friend class PDF::PDFViewCtrl;
    SDF::ObjSet m_objset;
};
 
#include <Impl/PDFViewCtrl.inl>
 
    }   // namespace PDF
}   // namespace pdftron
 
#endif // PDFTRON_H_CPPPDFPDFViewCtrl