This chapter shows you how to add hypertext links and targets to your documents, and how to respond to events fired by TX Text Control when a hypertext link is clicked. For an overview of the various classes, properties, methods and events involved, please refer to the chapter Text Fields and Hypertext Links in the Technical Articles part of this manual.
The source code for this example is contained in the subfolders Step1 to Step3 of the following directories:
Used TX Text Control controls:
Relevant API links:
In this first sample program, a hypertext link will be inserted in a text document. The document is then saved as an HTML file so that it can be displayed in a browser. This is what the sample program looks like:
To insert a hypertext link, we first need to create a HypertextLink object. The text to be displayed in the document ("Text Control Web Site") and the information about where to link to ("http://www.textcontrol.com") are passed as parameters to the constructor. The object that is thus created is then inserted at the current input position by adding it to a Text Control's HypertextLinks collection.
private void InsertHyperlink_Click(object sender, EventArgs e) {
TXTextControl.HypertextLink hlLink = new TXTextControl.HypertextLink("Text Control Web Site", "http://www.textcontrol.com");
m_txTextControl.HypertextLinks.Add(hlLink);
}Private Sub InsertHyperlink_Click(ByVal sender As Object, ByVal e As EventArgs) Handles m_btnInsertHyperlink.Click
Dim hlLink As TXTextControl.HypertextLink = New TXTextControl.HypertextLink("Text Control Web Site", "http://www.textcontrol.com")
m_txTextControl.HypertextLinks.Add(hlLink)
End SubNote that this first sample program does not handle the Click events, so clicking on a hypertext link in the TX Text Control will have no effect. Also, the link does not yet have the typical blue and underlined formatting style. Click events and formatting will be covered in Step 2.
The TextControl.Save method is used to save the document as an HTML file:
private void SaveAs_Click(object sender, EventArgs e) {
m_txTextControl.Save(TXTextControl.StreamType.HTMLFormat);
}Private Sub SaveAs_Click(ByVal sender As Object, ByVal e As EventArgs) Handles m_btnSaveAs.Click
m_txTextControl.Save(TXTextControl.StreamType.HTMLFormat)
End SubWhen the HTML file is opened in a web browser, the hypertext link is displayed as specified in your browser's settings.
Clicking on the link will take you to the TX Text Control web site.
In this second sample program, a dialog box is created which enables you to insert hypertext links in a more convenient way. Additionally, hypertext links which have previously been inserted or loaded from a file, can be edited and modified. Note that, while hypertext links are usually associated with HTML files, they can as well be stored in RTF or Microsoft Word files, or in TX Text Control's proprietary format.
The dialog box contains two text boxes. The first is for the text that represents the hypertext link in the document and the second is for the address, to which the link points.
The same dialog box is used for both, inserting a new and editing an existing hypertext link. Depending on whether the current input position is inside an existing link, this link is modified. Otherwise, a new one is inserted.
private void OpenHyperlinkDialog_Click(object sender, EventArgs e) {
// Open the custom hyperlink dialog to create or edit a hyperlink.
CustomHyperlinkDialog dlgInsertHyperlinkDialog = new CustomHyperlinkDialog(m_hlCurrentHyperlink, m_txTextControl);
dlgInsertHyperlinkDialog.ShowDialog(this);
}Private Sub OpenHyperlinkDialog_Click(ByVal sender As Object, ByVal e As EventArgs) Handles m_tmiInsertHyperlink.Click, m_tmiEditHyperlink.Click
' Open the custom hyperlink dialog to create or edit a hyperlink.
Dim dlgInsertHyperlinkDialog As CustomHyperlinkDialog = New CustomHyperlinkDialog(m_hlCurrentHyperlink, m_txTextControl)
dlgInsertHyperlinkDialog.ShowDialog(Me)
End SubWhen the form is loaded, the text boxes are filled with the text and link information, provided that the current input position is inside a link:
private void CustomHyperlinkDialog_Load(object sender, EventArgs e) {
// Set the caption of the dialog.
this.Text = m_hlLink == null ? "Insert Hyperlink" : "Edit Hyperlink";
// Update the text boxes.
if (m_hlLink != null) {
// The dialog is opened to edit a hyperlink:
// Insert the text of the hyperlink text and target into the
// corresponding text boxes.
m_tbxHyperlinkText.Text = m_hlLink.Text;
m_tbxLink.Text = m_hlLink.Target;
}
else {
// The dialog is opened to create a hyperlink:
// Insert the text of the current selection into the 'Hyperlink Text' text box.
TXTextControl.Selection selCurrentSelection = m_txTextControl.Selection;
if (selCurrentSelection.Length > 0) {
m_tbxHyperlinkText.Text = selCurrentSelection.Text;
}
}
// Update the enabled state of the 'OK' button.
m_btnOK.Enabled = IsValidHyperlink();
}Private Sub CustomHyperlinkDialog_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load
' Set the caption of the dialog.
Text = If(m_hlLink Is Nothing, "Insert Hyperlink", "Edit Hyperlink")
' Update the text boxes.
If m_hlLink IsNot Nothing Then
' The dialog is opened to edit a hyperlink:
' Insert the text of the hyperlink text and target into the
' corresponding text boxes.
m_tbxHyperlinkText.Text = m_hlLink.Text
m_tbxLink.Text = m_hlLink.Target
Else
' The dialog is opened to create a hyperlink:
' Insert the text of the current selection into the 'Hyperlink Text' text box.
Dim selCurrentSelection = m_txTextControl.Selection
If selCurrentSelection.Length > 0 Then
m_tbxHyperlinkText.Text = selCurrentSelection.Text
End If
End If
' Update the enabled state of the 'OK' button.
m_btnOK.Enabled = IsValidHyperlink()
End SubThe user then can change the displayed information. On clicking the OK button, the information is transfered to the document by either inserting a new link or modifying the existing one:
private void OK_Click(object sender, EventArgs e) {
if (m_hlLink != null) {
// The dialog is opened to edit a hyperlink:
// Update the text of the hyperlink.
m_hlLink.Text = m_tbxHyperlinkText.Text;
m_hlLink.Target = m_tbxLink.Text;
}
else {
// The dialog is opened to create a hyperlink:
// Create a new hyperlink and insert it into the TextControl.
m_hlLink = new TXTextControl.HypertextLink(m_tbxHyperlinkText.Text, m_tbxLink.Text);
m_hlLink.DoubledInputPosition = true;
m_txTextControl.HypertextLinks.Add(m_hlLink);
}
}Private Sub OK_Click(ByVal sender As Object, ByVal e As EventArgs) Handles m_btnOK.Click
If m_hlLink IsNot Nothing Then
' The dialog is opened to edit a hyperlink:
' Update the text of the hyperlink.
m_hlLink.Text = m_tbxHyperlinkText.Text
m_hlLink.Target = m_tbxLink.Text
Else
' The dialog is opened to create a hyperlink:
' Create a new hyperlink and insert it into the TextControl.
m_hlLink = New TXTextControl.HypertextLink(m_tbxHyperlinkText.Text, m_tbxLink.Text)
m_hlLink.DoubledInputPosition = True
m_txTextControl.HypertextLinks.Add(m_hlLink)
End If
End SubFinally, there is the Show menu item to switch the character format of the hyperlink's text to blue colored and underlined style. The menu item calls for each element of the TextControl's HypertextLinkCollection the function HighlightHyperlink that changes the hyperlink text to the desired display style.
private void HighlightHyperlink(TXTextControl.HypertextLink link, bool highlight) {
// Create a selection object to determine the color and underline style
// of the hyperlink text.
TXTextControl.Selection selLink = new TXTextControl.Selection(link.Start - 1, link.Length);
// Determine the fore color and underline style settings.
if (highlight) {
selLink.ForeColor = System.Drawing.Color.Blue;
selLink.Underline = TXTextControl.FontUnderlineStyle.Single;
}
else {
selLink.ForeColor = System.Drawing.Color.Black;
selLink.Underline = TXTextControl.FontUnderlineStyle.None;
}
// Apply the settings by adopting the selection.
m_txTextControl.Selection = selLink;
// Set the input position inside the hyperlink to prevent adopting the set formatting when
// typing right behind the hyperlink.
m_txTextControl.InputPosition = new TXTextControl.InputPosition(selLink.Start + selLink.Length, TXTextControl.TextFieldPosition.InsideTextField);
}Private Sub HighlightHyperlink(ByVal link As TXTextControl.HypertextLink, ByVal highlight As Boolean)
' Create a selection object to determine the color and underline style
' of the hyperlink text.
Dim selLink As TXTextControl.Selection = New TXTextControl.Selection(link.Start - 1, link.Length)
' Determine the fore color and underline style settings.
If highlight Then
selLink.ForeColor = Drawing.Color.Blue
selLink.Underline = TXTextControl.FontUnderlineStyle.Single
Else
selLink.ForeColor = Drawing.Color.Black
selLink.Underline = TXTextControl.FontUnderlineStyle.None
End If
' Apply the settings by adopting the selection.
m_txTextControl.Selection = selLink
' Set the input position inside the hyperlink to prevent adopting the set formatting when
' typing right behind the hyperlink.
m_txTextControl.InputPosition = New TXTextControl.InputPosition(selLink.Start + selLink.Length, TXTextControl.TextFieldPosition.InsideTextField)
End SubStep 1 and 2 introduced references to external resources, i.e. addresses of web pages or files. In this step, links to positions in the same document will be discussed. These links are called document links and the positions, to which they point, are called document targets. Document targets are also referred to as anchors (in the context of HTML editors) or bookmarks (in word processors).
When running this sample program, first add some text and then one or two targets with the Document Targets / Insert... menu item.
Finally use the Links / Insert... menu item to add links to these targets. The names of the targets you have inserted will be displayed in the Link Location combo box.
Inserting a Target
A target is created by adding a DocumentTarget object to the DocumentTargets collection.
Unlike links, targets have no visible text. The constructor therefore has only a single parameter, which is the target's name.
TXTextControl.DocumentTarget dtDocumentTarget = new TXTextControl.DocumentTarget(m_tbxTargetName.Text);
dtDocumentTarget.Deleteable = m_chbxCanBeDeleted.Checked;
m_txTextControl.DocumentTargets.Add(dtDocumentTarget);Dim dtDocumentTarget As TXTextControl.DocumentTarget = New TXTextControl.DocumentTarget(m_tbxTargetName.Text)
dtDocumentTarget.Deleteable = m_chbxCanBeDeleted.Checked
m_txTextControl.DocumentTargets.Add(dtDocumentTarget)Inserting Links to Targets
The Insert Hyperlink dialog box from Step 2 needs to be extended so that it will not only accept URLs as link targets, but also lets us select from a list of document targets. This is done by adding a combo box that replaces the hyperlink text box when the corresponding Document Link radio button is toggled. The combo box is filled with targets by adding all elements from the DocumentTargets collection:
TXTextControl.DocumentTargetCollection colDocumentTargets = m_txTextControl.DocumentTargets;
foreach (TXTextControl.DocumentTarget target in colDocumentTargets) {
m_cmbxDocumentTargets.Items.Add(new DocumentTargetItem(target));
}Dim colDocumentTargets = m_txTextControl.DocumentTargets
For Each target As TXTextControl.DocumentTarget In colDocumentTargets
m_cmbxDocumentTargets.Items.Add(New DocumentTargetItem(target))
NextJumping to a Target
When a document link is clicked on, text should automatically be scrolled so that the text part containing the link's target becomes visible. This is done by responding to the DocumentLinkClicked event and calling the ScrollTo method. The DocumentTarget class inherits this method from its parent class, TextField.
private void TextControl_DocumentLinkClicked(object sender, TXTextControl.DocumentLinkEventArgs e) {
TXTextControl.DocumentTarget dtTarget = e.DocumentLink.DocumentTarget;
if (dtTarget != null) {
dtTarget.ScrollTo();
}
}Private Sub TextControl_DocumentLinkClicked(ByVal sender As Object, ByVal e As TXTextControl.DocumentLinkEventArgs) Handles m_txTextControl.DocumentLinkClicked
Dim dtTarget As TXTextControl.DocumentTarget = e.DocumentLink.DocumentTarget
If dtTarget IsNot Nothing Then
dtTarget.ScrollTo()
End If
End SubDisplaying and Editing Targets
TX Text Control is able to display a marker to visualize the location of a target. But if targets are invisible, how can you locate them in your document, or delete one that's no longer required? The solution is a list box which displays the names of all targets a document contains, and lets you jump to or remove a selected target.
