diff --git a/controls/pdfviewer/features/annotations.md b/controls/pdfviewer/features/annotations.md index 843b84ae3..616785148 100644 --- a/controls/pdfviewer/features/annotations.md +++ b/controls/pdfviewer/features/annotations.md @@ -1,25 +1,26 @@ ---- -title: Annotations -page_title: Annotations - WinForms PdfViewer Control -description: WinForms PdfViewer supports Link annotations, which means that if you open a PDF file that includes hyperlinks to absolute URIs, you can click them and have a window open, navigated to the respective address. -slug: winforms/pdfviewer/annotations -tags: annotations -published: True -position: 0 ---- - -# Annotations -__RadPdfViewer__ supports link annotations, which means that if you open a PDF file that includes hyperlinks to absolute URIs, you can click them and have a window open, navigated to the respective address. In addition, if there are links pointing to bookmarks in the same document, the view port will be scrolled to the destination specified in the link. - -The current API includes the following members, which allow customization of the default behavior or implementing custom logic: - -* __AnnotationClicked__ event of __RadPdfViewer__: This event is fired when you click on an annotation such as a hyperlink. It comes handy when you want to detect or even cancel the opening of a web page. The __AnnotationEventArgs__ contain the Annotation as property and the Link itself has information of its Action, i.e. if it is a UriAction. Handling the event in the following manner will not only show the Uri of each clicked link as the text of a MessageBox, but will also cancel the default behavior. - -#### AnnotationClicked Event Handler - -{{source=..\SamplesCS\PdfViewer\PdfAnnotations.cs region=AnnotationClicked}} -{{source=..\SamplesVB\PdfViewer\PdfAnnotations.vb region=AnnotationClicked}} - +--- +title: Annotations +page_title: Annotations - WinForms PdfViewer Control +description: WinForms PdfViewer supports Link annotations, which means that if you open a PDF file that includes hyperlinks to absolute URIs, you can click them and have a window open, navigate to the respective address. +slug: winforms/pdfviewer/annotations +tags: annotations +published: True +position: 0 +--- + +# Annotations + +__RadPdfViewer__ supports link annotations, which means that if you open a PDF file that includes hyperlinks to absolute URIs, you can click them and have a window open, and navigate to the respective address. In addition, if there are links pointing to bookmarks in the same document, the view port will be scrolled to the destination specified in the link. + +The current API includes the following members, which allow customization of the default behavior or implementation of custom logic: + +* __AnnotationClicked__ event of __RadPdfViewer__: This event is fired when you click on an annotation such as a hyperlink. It comes in handy when you want to detect or even cancel the opening of a web page. The __AnnotationEventArgs__ contains the Annotation as property and the Link itself has information of its Action, i.e. if it is a UriAction. Handling the event in the following manner will not only show the Uri of each clicked link as the text of a MessageBox but will also cancel the default behavior. + +#### AnnotationClicked Event Handler + +{{source=..\SamplesCS\PdfViewer\PdfAnnotations.cs region=AnnotationClicked}} +{{source=..\SamplesVB\PdfViewer\PdfAnnotations.vb region=AnnotationClicked}} + ````C# private void radPdfViewer1_AnnotationClicked(object sender, Telerik.Windows.Documents.Fixed.Model.Annotations.EventArgs.AnnotationEventArgs e) @@ -37,8 +38,8 @@ private void radPdfViewer1_AnnotationClicked(object sender, Telerik.Windows.Docu MessageBox.Show(a.Uri.ToString()); e.Handled = true; } - -```` + +```` ````VB.NET Private Sub radPdfViewer1_AnnotationClicked(sender As Object, e As Telerik.Windows.Documents.Fixed.Model.Annotations.EventArgs.AnnotationEventArgs) Dim l As Telerik.Windows.Documents.Fixed.Model.Annotations.Link = TryCast(e.Annotation, Telerik.Windows.Documents.Fixed.Model.Annotations.Link) @@ -52,18 +53,64 @@ Private Sub radPdfViewer1_AnnotationClicked(sender As Object, e As Telerik.Windo MessageBox.Show(a.Uri.ToString()) e.Handled = True End Sub - -```` - -{{endregion}} - -* __Annotations__ property of __RadFixedDocument__ – A collection which returns all annotations in the document. For example you can retrieve all links using the following code: - -#### Get Annotation Links - -{{source=..\SamplesCS\PdfViewer\PdfAnnotations.cs region=GetAllLinks}} -{{source=..\SamplesVB\PdfViewer\PdfAnnotations.vb region=GetAllLinks}} - + +```` + +{{endregion}} + +* __HyperlinkClicked__ event of RadPdfViewer: This event is similar to AnnotationClicked, but it is raised only when you click on the hyperlink type annotations. It allows you to cancel the navigation to the associated URI or to modify the click action. The HyperlinkClickedEventArgs gives access to the URL, which can be manually checked if it is trusted. With the 2024 Q3 (2024.3.924), the default navigation behavior of the hyperlinks is to automatically open only valid and trusted addresses. If needed, the navigation can be canceled by either setting the __Handled__ property of the event args to _true_ or the __IsTrustedUrl__ property to _false_. Below is an example of using this event to prompt that the clicked hyperlink might be unsafe and provide the opportunity to cancel the navigation process upon receiving the end user confirmation: + +#### HyperlinkClicked Event Handler + +{{source=..\SamplesCS\PdfViewer\PdfAnnotations.cs region=HyperlinkClicked}} +{{source=..\SamplesVB\PdfViewer\PdfAnnotations.vb region=HyperlinkClicked}} + +````C# +private void RadPdfViewer1_HyperlinkClicked(object sender, Telerik.WinControls.Hyperlinks.HyperlinkClickedEventArgs e) +{ + var link = e.URL; + if (link.EndsWith("exe")) + { + e.Handled = true; MessageBoxResult Result = System.Windows.MessageBox.Show("You are about to open an executable file. Do you want to proceed", "Possible unsafe link", MessageBoxButton.YesNo, MessageBoxImage.Question); + if (Result == MessageBoxResult.Yes) + { + Process.Start(new ProcessStartInfo() + { + FileName = link, + UseShellExecute = true + }); + } + } +} + +```` +````VB.NET +Private Sub RadPdfViewer1_HyperlinkClicked(sender As Object, e As HyperlinkClickedEventArgs) + Dim link = e.URL + If link.EndsWith("exe") Then + e.Handled = True + Dim Result As MessageBoxResult = System.Windows.MessageBox.Show("You are about to open an executable file. Do you want to proceed", "Possible unsafe link", MessageBoxButton.YesNo, MessageBoxImage.Question) + If Result = MessageBoxResult.Yes Then + Process.Start(New ProcessStartInfo() With { + .FileName = link, + .UseShellExecute = True + }) + End If + End If +End Sub + +```` + +{{endregion}} + + +* __Annotations__ property of __RadFixedDocument__ – A collection which returns all annotations in the document. For example, you can retrieve all links using the following code: + +#### Get Annotation Links + +{{source=..\SamplesCS\PdfViewer\PdfAnnotations.cs region=GetAllLinks}} +{{source=..\SamplesVB\PdfViewer\PdfAnnotations.vb region=GetAllLinks}} + ````C# private IEnumerable GetAllLinks(Telerik.Windows.Documents.Fixed.Model.RadFixedDocument document) @@ -77,8 +124,8 @@ private IEnumerable GetA } } } - -```` + +```` ````VB.NET Private Iterator Function GetAllLinks(document As Telerik.Windows.Documents.Fixed.Model.RadFixedDocument) As IEnumerable(Of Telerik.Windows.Documents.Fixed.Model.Annotations.Link) For Each a As Telerik.Windows.Documents.Fixed.Model.Annotations.Annotation In document.Annotations @@ -88,18 +135,18 @@ Private Iterator Function GetAllLinks(document As Telerik.Windows.Documents.Fixe End If Next End Function - -```` - -{{endregion}} - -The bookmarks in terms of “docx bookmarks” are not explicitly saved in PDF files. They are persisted only if there are Link annotations to them, so you can use the snippet below to retrieve all destinations that have links to them: - -#### Get Annotation Bookmarks - -{{source=..\SamplesCS\PdfViewer\PdfAnnotations.cs region=Bookmarks}} -{{source=..\SamplesVB\PdfViewer\PdfAnnotations.vb region=Bookmarks}} - + +```` + +{{endregion}} + +The bookmarks in terms of “docx bookmarks” are not explicitly saved in PDF files. They are persisted only if there are Link annotations to them, so you can use the snippet below to retrieve all destinations that have links to them: + +#### Get Annotation Bookmarks + +{{source=..\SamplesCS\PdfViewer\PdfAnnotations.cs region=Bookmarks}} +{{source=..\SamplesVB\PdfViewer\PdfAnnotations.vb region=Bookmarks}} + ````C# private IEnumerable GetAllBookmarks(Telerik.Windows.Documents.Fixed.Model.RadFixedDocument document) @@ -113,8 +160,8 @@ private IEnumerablenote "{0}{1} to follow link" - The first parameter is the URL, the second is "Ctrl + Click" which is taken from the localization file. +>note "{0}{1} to follow link" - The first parameter is the URL, and the second is "Ctrl + Click" which is taken from the localization file. > You have control over it using the __HyperlinkToolTipFormatString__ of **RadRichTextEditor**, which will set the format for all hyperlinks in the document. -__HyperlinkClicked__ +### HyperlinkClicked event + +When a hyperlink is clicked, the __HyperlinkClicked__ event of __RadRichTextEditor__ is fired. The sender of the event is the document element, that you have clicked, e.g. a **Span**, an **Image**, **InlineUIContainer**, etc. The __HyperlinkClickedEventArgs__ provides the possibility either to cancel or replace the navigation action. This is helpful when you need to validate the clicked hyperlink and prevent it from navigating to an unsecured address or from starting a local process. + +With the 2024 Q3 (2024.3.924), the default navigation behavior of the hyperlinks is to automatically open only valid and trusted addresses. The hyperlink navigation can be canceled by either setting the __Handled__ property of the HyperlinkClickedEventArgs to _true_ or __IsTrustedUrl__ to _false_. + +Here is an example of using the HyperlinkClicked event prompting that the clicked hyperlink might be unsafe and allows to cancel the navigation process upon receiving the end user confirmation: + +{{source=..\SamplesCS\RichTextEditor\Features\HyperlinkCode.cs region=HyperlinkClickedEvent}} +{{source=..\SamplesVB\RichTextEditor\Features\HyperlinkCode.vb region=HyperlinkClickedEvent}} + +````C# +void radRichTextEditor1_HyperlinkClicked(object sender, HyperlinkClickedEventArgs e) +{ + var link = e.URL; + if (link.EndsWith("exe")) + { + e.Handled = true; MessageBoxResult Result = System.Windows.MessageBox.Show("You are about to open an executable file. Do you want to proceed", "Possible unsafe link", MessageBoxButton.YesNo, MessageBoxImage.Question); + if (Result == MessageBoxResult.Yes) + { + Process.Start(new ProcessStartInfo() + { + FileName = link, + UseShellExecute = true + }); + } + } +} + + +```` +````VB.NET +Private Sub radRichTextEditor1_HyperlinkClicked(ByVal sender As Object, ByVal e As HyperlinkClickedEventArgs) + Dim link = e.URL + + If link.EndsWith("exe") Then + e.Handled = True + Dim Result As MessageBoxResult = System.Windows.MessageBox.Show("You are about to open an executable file. Do you want to proceed", "Possible unsafe link", MessageBoxButton.YesNo, MessageBoxImage.Question) + If Result = MessageBoxResult.Yes Then + Process.Start(New ProcessStartInfo() With { + .FileName = link, + .UseShellExecute = True + }) + End If + End If +End Sub -When you click on a hyperlink, the __HyperlinkClicked__ event of __RadRichTextEditor__ is fired. The sender of the event is the document element, which you have clicked, e.g. a **Span**, an **Image**, **InlineUIContainer**, etc. The event args on the other hand, provide the possibility to mark the event as handled and prevent the default action. Custom logic can also be implemented depending on the __HyperlinkTarget__ and __URL__, which are also visible as properties of the event args. -![WinForms RadRichTextEditor Hyperlink Click Even Handler](images/richtexteditor-features-hyperlink002.png) +```` + +{{endregion}} + -## HyperlinkNavigationMode +### HyperlinkNavigationMode -This property allows you to control what action should trigger the opening of a hyperlink. The possible options are: +The __HyperlinkNavigationMode__ allows you to control what action should trigger the opening of a hyperlink. The possible options are: * **CtrlClick**: Triggers the hyperlink when users hold the Ctrl key and click on the hyperlink. * **Click**: Triggers the hyperlink when users click on the hyperlink. -#### Change the default hyperlink navigation mode +Below is demonstrated how to change the default hyperlink navigation mode: {{source=..\SamplesCS\RichTextEditor\Features\HyperlinkCode.cs region=HyperlinkMode}} {{source=..\SamplesVB\RichTextEditor\Features\HyperlinkCode.vb region=HyperlinkMode}} @@ -245,7 +294,7 @@ Me.radRichTextEditor1.HyperlinkNavigationMode = Telerik.WinForms.Documents.UI.Hy {{endregion}} -# See Also +## See Also * [Document Elements]({%slug winforms/richtexteditor-/document-elements%}) diff --git a/controls/richtexteditor/features/images/richtexteditor-features-hyperlink002.png b/controls/richtexteditor/features/images/richtexteditor-features-hyperlink002.png deleted file mode 100644 index 0e44d1be8..000000000 Binary files a/controls/richtexteditor/features/images/richtexteditor-features-hyperlink002.png and /dev/null differ diff --git a/controls/spreadsheet/events.md b/controls/spreadsheet/events.md index 01851604d..c214628a9 100644 --- a/controls/spreadsheet/events.md +++ b/controls/spreadsheet/events.md @@ -154,13 +154,60 @@ End Sub * **ActivePresenterChanged**: Occurs when the active presenter is changed. +* **HyperlinkClicked**: Occurs when a hyperlink in the document gets clicked. The event allows you to either cancel or replace the navigation logic. HyperlinkClicked event can be used as a confirmation from the end-user whether to proceed or not with opening a hyperlink due to security reasons. + With the 2024 Q3 (2024.3.924), the default navigation behavior of the hyperlinks is to automatically open only valid and trusted addresses. The hyperlink navigation can be canceled by either setting the __Handled__ property of the HyperlinkClickedEventArgs to _true_ or __IsTrustedUrl__ to _false_. + +#### Example 3: Using the HyperlinkClicked event to implement confirmation for the clicked links in the document + +{{source=..\SamplesCS\Spreadsheet\Events.cs region=HyperlinkClickedEvent}} +{{source=..\SamplesVB\Spreadsheet\Events.vb region=HyperlinkClickedEvent}} +````C# +private void ActiveWorksheetEditor_HyperlinkClicked(object sender, Telerik.WinControls.Hyperlinks.HyperlinkClickedEventArgs e) +{ + if (e.URL.EndsWith("exe")) + { + e.Handled = true; + MessageBoxResult Result = System.Windows.MessageBox.Show("You are about to open an executable file. Do you want to proceed?", "Possible unsafe link", MessageBoxButton.YesNo, MessageBoxImage.Question); + + if (Result == MessageBoxResult.Yes) + { + Process.Start(new ProcessStartInfo() + { + FileName = e.URL, + UseShellExecute = true + }); + } + } +} + +```` +````VB.NET +Private Sub ActiveWorksheetEditor_HyperlinkClicked(ByVal sender As Object, ByVal e As Telerik.WinControls.Hyperlinks.HyperlinkClickedEventArgs) + If e.URL.EndsWith("exe") Then + e.Handled = True + Dim Result As MessageBoxResult = System.Windows.MessageBox.Show("You are about to open an executable file. Do you want to proceed?", "Possible unsafe link", MessageBoxButton.YesNo, MessageBoxImage.Question) + + If Result = MessageBoxResult.Yes Then + Process.Start(New ProcessStartInfo() With { + .FileName = e.URL, + .UseShellExecute = True + }) + End If + End If +End Sub + +```` + +{{endregion}} + + >The events related to selection in RadSpreadsheet are described in the [Working with UI Selection]({%slug radspreadsheet-ui-working-with-selection%}) topic. ## Cells Events * **CellPropertyChanged**: Occurs when a property of a cell is changed. The event arguments are of type **CellPropertyChangedEventArgs** and expose information about the exact property that was changed as well as the affected cell range. **Example 3** demonstrates how you can use the event to get a notification when the users change the fill of a cell. -#### Example 3: Using the CellPropertyChangedEvent +#### Example 4: Using the CellPropertyChangedEvent {{source=..\SamplesCS\Spreadsheet\Events.cs region=radspreadsheet-events_3}} {{source=..\SamplesVB\Spreadsheet\Events.vb region=radspreadsheet-events_3}}