Class SumatraPDFControl

Windows Forms Control which embeds modifed version of SumatraPDF to read and view Portable Document Files (PDF)

Inheritance

System.Object

System.MarshalByRefObject

System.ComponentModel.Component

System.Windows.Forms.Control

SumatraPDFControl

Namespace: SumatraPDF

Assembly: SumatraPDFControl.dll

Syntax

[ToolboxBitmap(typeof(SumatraPDFControl), "Resources.SumatraPDFControlMini.png")]
[Guid("E5FDA170-ACF6-4C4D-AAF9-C8F9C70EE09C")]
public class SumatraPDFControl : Control, IDropTarget, ISynchronizeInvoke, IWin32Window, IArrangedElement, IBindableComponent, IComponent, IDisposable

Remarks

This control allows you to open and read PDF files with most features present in great SumatraPDF reader (https://www.sumatrapdfreader.org/). It requires an specific compiled Sumatra code version (https://github.com/marcoscmonteiro/sumatrapdf) which enables SumatraPDF working in an enhanced plugin mode. It's forked from original SumatraPDF code (https://github.com/sumatrapdfreader/sumatrapdf)

Constructors

SumatraPDFControl()

Default constructor

Declaration

public SumatraPDFControl()

Properties

ContextMenuStrip

Gets or sets the ContextMenuStrip associated with this control.

Declaration

public ContextMenuStrip ContextMenuStrip { get; set; }

Property Value

Type	Description
System.Windows.Forms.ContextMenuStrip

Remarks

The ContextMenuStrip for this control, or null if there is no ContextMenuStrip. The default is null.

DisplayMode

Get or set mode to display PDF pages (SinglePage, Facing, BookView, Continuous, ContinuousFacing, ContinuousBookView, Automatic)

Declaration

[Browsable(false)]
public SumatraPDFControl.DisplayModeEnum DisplayMode { get; set; }

Property Value

Type	Description
SumatraPDFControl.DisplayModeEnum

KeyAccelerators

Get or set if Keyboard accelerators (like CTRL+A, CTRL+P, etc.) are enable or not;

Declaration

[Browsable(false)]
public bool KeyAccelerators { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If keyboard accelerators are enable pressing keys will perform the following actions:

Key	Action
CTRL+A	Select All
CTRL+C	Copy Selection
CTRL+F	Find
CTRL+G	Goto Page
CTRL+P	Print Document
CTRL+Y	Zoom: Custom
CTRL+0	Zoom: Fit Page
CTRL+1	Zoom: Actual Size
CTRL+2	Zoom: Fit Width
CTRL+3	Zoom: Fit Content
CTRL+6	View: Single Page
CTRL+7	View: Facing
CTRL+8	View: Book
CTRL+PlusKey	Zoom In
CTRL+SHIFT+PlusKey	View: Rotate Right
CTRL+InsertKey	Copy Selection
F3	Find: Next
SHIFT+F3	Find: Previous
CTRL+F3	Find: Next Selection
CTRL+SHIFT+F3	Find: Previous Selection
CTRL+MinusKey	Zoom Out
CTRL+SHIFT+MinusKey	View: Rotate Left
ALT+LeftArrow	Navigate: Back
ALT+RightArrow	Navigate: Forward

Disabling these accelerators allow KeyDown raise event of these keys.

NamedDest

Get or set current PDF NamedDest viewing position

Declaration

[Browsable(false)]
public string NamedDest { get; set; }

Property Value

Type	Description
System.String

Page

Get or set current PDF page viewing position

Declaration

[Browsable(false)]
public int Page { get; set; }

Property Value

Type	Description
System.Int32

PageCount

Total pages count of loaded document

Declaration

public int PageCount { get; }

Property Value

Type	Description
System.Int32

Rotation

Get current PDF rotation (see RotateBy method to change rotation state)

Declaration

[Browsable(false)]
public SumatraPDFControl.RotationEnum Rotation { get; }

Property Value

Type	Description
SumatraPDFControl.RotationEnum

ScrollState

Get or set current PDF scroll state (X and Y units from visible PDF page)

Declaration

[Browsable(false)]
public SumatraPDFControl.ScrollStateStruct ScrollState { get; set; }

Property Value

Type	Description
SumatraPDFControl.ScrollStateStruct

SumatraPDFExe

SumatraPDF executable file name. Usually SumatraPDF.exe (default) or SumatraPDF-dll.exe

Declaration

public string SumatraPDFExe { get; set; }

Property Value

Type	Description
System.String

SumatraPDFPath

Path where SumatraPDF executable is present. If not informed assumes same SumatraPDFControl.dll directory

Declaration

public string SumatraPDFPath { get; set; }

Property Value

Type	Description
System.String

TocVisible

Get or set if SumatraPDF Table of contents (Toc) sidebar is visible (if document doesn't have Toc it always will be false)

Declaration

[Browsable(false)]
public bool TocVisible { get; set; }

Property Value

Type	Description
System.Boolean

ToolBarVisible

Get or set if SumatraPDF default toolbar is visible

Declaration

[Browsable(false)]
public bool ToolBarVisible { get; set; }

Property Value

Type	Description
System.Boolean

Zoom

Get or set current numeric PDF zoom scale.

Declaration

[Browsable(false)]
public float Zoom { get; set; }

Property Value

Type	Description
System.Single

Remarks

ZoomVirtual property to get or set zoom mode like fit width, fit page etc.

ZoomVirtual

Get or set currrent PDF virtual zoom mode (Fit width, Fit Page, Fit Content or None).

Declaration

[Browsable(false)]
public SumatraPDFControl.ZoomVirtualEnum ZoomVirtual { get; set; }

Property Value

Type	Description
SumatraPDFControl.ZoomVirtualEnum

Remarks

Zoom property to get or set numeric scale

Methods

CopySelection()

Copy to clipboard window text selection

Declaration

public void CopySelection()

Dispose(Boolean)

Cleaning resources being used

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing	true if necessary to dispose managed resources.

Overrides

System.Windows.Forms.Control.Dispose(System.Boolean)

GoToFirstPage()

Go to first document page

Declaration

public void GoToFirstPage()

GoToLastPage()

Go to last document page

Declaration

public void GoToLastPage()

GoToNextPage()

Go to next document page

Declaration

public void GoToNextPage()

GoToPrevPage()

Go to previous document page

Declaration

public void GoToPrevPage()

LoadFile(String, Int32, Boolean)

Load sumatra supported file. Current file will be closed.

Declaration

public void LoadFile(string PDFFile, int InitialPage = 1, bool NewSumatraInstance = false)

Parameters

Type	Name	Description
System.String	PDFFile	File name with complete path
System.Int32	InitialPage	Initial page to show
System.Boolean	NewSumatraInstance	Open a new SumatraPDF instance (other executable process)

Remarks

In case of multiple instances of SumatraPDFControl NewSumatraInstance indicates if an pre-existing instance will be used or not. If true new SumatraPDF executable will be started. The default is false.

OpenPrintDialog()

Show dialog to print current document (in background)

Declaration

public void OpenPrintDialog()

Remarks

After proceeding with print it occurs in background and SumatraPDF shows an interface to cancel the whole process. The following only applies for printing as image: Creates a new dummy page for each page with a large zoom factor, and then uses StretchDIBits to copy this to the printer's dc.

ReloadCurrentFile()

Reload current loaded document in order to reflect external changes made in it

Declaration

public void ReloadCurrentFile()

RotateBy(SumatraPDFControl.RotationEnum)

Rotate current document

Declaration

public void RotateBy(SumatraPDFControl.RotationEnum Rotation)

Parameters

Type	Name	Description
SumatraPDFControl.RotationEnum	Rotation	Degrees to Rotation

SelectAll()

Select all document text

Declaration

public void SelectAll()

TextSearch(String, Boolean)

Do a text search on document from beginning

Declaration

public void TextSearch(string searchText, bool matchCase)

Parameters

Type	Name	Description
System.String	searchText	Text to search
System.Boolean	matchCase	Match case

See Also

TextSearchNext(Boolean)

TextSearchNext(Boolean)

Do a text search on document after a first search by TextSearch(String, Boolean)

Declaration

public void TextSearchNext(bool forward = true)

Parameters

Type	Name	Description
System.Boolean	forward	True (default) if serching forward, false if backwards

See Also

TextSearch(String, Boolean)

WndProc(ref Message)

Processes Windows Messages.

Declaration

protected override void WndProc(ref Message m)

Parameters

Type	Name	Description
System.Windows.Forms.Message	m	The Windows System.Windows.Forms.Message to process.

Overrides

System.Windows.Forms.Control.WndProc(System.Windows.Forms.Message)

Remarks

This method has many customizations in order to process SumatraPDF messages. So, if there is need to override, remember to call base.WndProc.

Events

ContextMenuOpening

Occurs before trying to open ContextMenu by right mouse clicking button.

Declaration

public event EventHandler<SumatraPDFControl.ContextMenuOpeningEventArgs> ContextMenuOpening

Event Type

Type	Description
System.EventHandler<SumatraPDFControl.ContextMenuOpeningEventArgs>

DisplayModeChanged

Occurs after changing display mode.

Declaration

public event EventHandler<SumatraPDFControl.DisplayModeChangedEventArgs> DisplayModeChanged

Event Type

Type	Description
System.EventHandler<SumatraPDFControl.DisplayModeChangedEventArgs>

FileOpened

Occurs after a new document load by SumatraPDFControl

Declaration

public event EventHandler<EventArgs> FileOpened

Event Type

Type	Description
System.EventHandler<System.EventArgs>

Remarks

It's recomended to initilize application variables on this event because some properties and methods does not respond correctly during SumatraPDF.exe startup process. This event garantees that startup process was ended. See StartupFinished event for more details.

See Also

StartupFinished

KeyDown

Occurs when a key is pressed while the control has focus.

Declaration

public event KeyEventHandler KeyDown

Event Type

Type	Description
System.Windows.Forms.KeyEventHandler

KeyPress

Occurs when a character, space or backspace key is pressed while the control has focus.

Declaration

public event EventHandler<KeyPressEventArgs> KeyPress

Event Type

Type	Description
System.EventHandler<System.Windows.Forms.KeyPressEventArgs>

KeyUp

Occurs when a key is released while the control has focus.

Declaration

public event KeyEventHandler KeyUp

Event Type

Type	Description
System.Windows.Forms.KeyEventHandler

LinkClick

Occurs after clicking a document link.

Declaration

public event EventHandler<SumatraPDFControl.LinkClickedEventArgs> LinkClick

Event Type

Type	Description
System.EventHandler<SumatraPDFControl.LinkClickedEventArgs>

PageChanged

Occurs after changing current visible page

Declaration

public event EventHandler<SumatraPDFControl.PageChangedEventArgs> PageChanged

Event Type

Type	Description
System.EventHandler<SumatraPDFControl.PageChangedEventArgs>

ScrollStateChanged

Occurs after changing document scroll position (vertical and/or horizontal).

Declaration

public event EventHandler<SumatraPDFControl.ScrollStateEventArgs> ScrollStateChanged

Event Type

Type	Description
System.EventHandler<SumatraPDFControl.ScrollStateEventArgs>

StartupFinished

Occurs after SumatraPDF.exe terminates startup process.

Declaration

public event EventHandler<EventArgs> StartupFinished

Event Type

Type	Description
System.EventHandler<System.EventArgs>

Remarks

This event occurs only after a new SumatraPDF.exe execution. So, simply loading a new document reutilizing SumatraPDF.exe instance do not fire this event, but only FileOpened event.

Because SumatraPDF load documents asyncronously, some methods and properties requires end of startup process in order to function: eg.: PageCount or Page. So, use these methods or properties only after StartupFinished event or either FileOpened.

It is only recommended to carry out the initialization procedures when handling the FileOpened event because the StartupFinished event is only fired when a new instance of SumatraPDF.exe is executed.

See Also

FileOpened

SumatraMessage

A generic SumatraPDF message not managed by other events.

Declaration

public event EventHandler<SumatraPDFControl.SumatraMessageEventArgs> SumatraMessage

Event Type

Type	Description
System.EventHandler<SumatraPDFControl.SumatraMessageEventArgs>

ZoomChanged

Occurs after changing zoom factor.

Declaration

public event EventHandler<SumatraPDFControl.ZoomChangedEventArgs> ZoomChanged

Event Type

Type	Description
System.EventHandler<SumatraPDFControl.ZoomChangedEventArgs>