# LinkCardNode
Class Inherits Node
## About
`LinkCardNode` is the shared base of `BookmarkNode` and `EmbedNode`. It holds an address and the metadata fetched for it, and draws a card from that metadata. Live third-party content is never shown in the editor.
**Fetching.** Metadata is fetched only when a user adds a card from the toolbar, changes its `URL` in an editor, or chooses Refresh in the inspector, and when the application calls `FetchMetadata`. Opening a document, importing HTML or JSON, and pasting never fetch. Each fetch first raises `Editor.FetchLinkMetadata`; a handler that returns True supplies the metadata itself by setting `Title`, `Description`, and the other properties, or turns fetching off.
**Changes.** A fetch reports its metadata as one content change when it finishes, including any properties a `FetchLinkMetadata` handler set. `FetchMetadata(False)` reports none, for an application that fetches while it builds or loads a document. Restoring metadata from JSON or HTML never reports a change.
The built-in fetch uses `URLConnection` with a 10-second timeout. A web page is read only until the end of its `head`, and every response is limited in size. The preview image and the site icon are then downloaded, scaled down, and stored as data URIs, so the card draws the same way offline, in PDF, and in print.
**States.** `State` is `Empty` without an address, `Loading` while a fetch is in progress, `Loaded` with metadata, and `Unavailable` when there is none, in which case the card shows its address as a plain link.
**Links.** Clicking the card with Ctrl on Windows and Linux, or Command on macOS, raises `Editor.LinkPressed` with its address, like any other link. A vector PDF links the whole card.
## Enumerations
| Name | Value | Description |
| --- | :---: | --- |
| States | Empty <br > Loading <br > Loaded <br > Unavailable | (None) |
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| AddVectorPDFAnnotations | pdf As PDFDocument <br> pageNumber As Integer <br> offsetX As Double <br> offsetY As Double <br> usedNames As Dictionary <br> formAction As String = "" | (None) | Adds a link to the card's address over the card in a vector PDF. |
| Constructor | url As String = "" | (None) | Creates a card for the supplied address without fetching its metadata. |
| CopyPropertiesTo | target As Node | (None) | Copies the card's address and metadata to another card. |
| Destructor | (None) | (None) | Cancels any request in progress. |
| DrawPictureCover | g As Graphics <br> value As Picture <br> bounds As Rect | (None) | Draws the picture over the bounds, cropped from its middle to fill them. |
| FetchMetadata | reportChange As Boolean = True | (None) | Fetches the card's metadata again from its address and reports it as one content change when it arrives, or as none when reportChange is False. The application's Editor.FetchLinkMetadata handler can supply it instead. |
| FittedText | g As Graphics <br> value As String <br> width As Double | String | Returns the text shortened with an ellipsis to fit the width. |
| FromJSON | data As JSONItem | Boolean | Restores the card's address and metadata from JSON without fetching anything. |
| IconPicture | (None) | Picture | Returns the site's icon, or Nil when there is none. |
| ImagePicture | (None) | Picture | Returns the card's preview image, or Nil when there is none. |
| InspectorSections | (None) | InspectorSection | Returns the link section, with the address, title, and a Refresh action, followed by the node's common sections. |
| InvalidateAppearance | layoutChanged As Boolean = False | (None) | Records a change to the card's appearance. Changes made by an Editor.FetchLinkMetadata handler are reported once, when the fetch finishes. |
| LinkAtPoint | x As Double <br> y As Double <br> ByRef linkNode As GraffitiProEditor.Node <br> ByRef url As String <br> ByRef linkText As String <br> ByRef title As String | Boolean | Reports the card's address for a link click anywhere on the card. |
| MetadataRequestURL | (None) | String | Returns the address requested for the card's metadata. Subclasses that use a metadata service return its address. |
| PictureDataURI | data As String <br> maximumSize As Integer <br> opaque As Boolean | String | Returns downloaded image data as a data URI, scaled to fit the supplied size, or an empty string when it is not an image. |
| PlainText | (None) | String | Returns the card's title and address. |
| RestoreMetadata | data As JSONItem | (None) | Sets the card's address and metadata from JSON keys without fetching anything. Used by JSON and HTML import. |
| SetFetchedMetadata | title As String <br> description As String <br> siteName As String <br> imageURL As String <br> iconURL As String | (None) | Sets the fetched title, description, site name, and picture addresses without reporting a change. Used by ApplyMetadataResponse. |
| ShowsDescription | (None) | Boolean | Returns whether the inspector offers the description. Cards without one return False. |
| ToJSON | (None) | JSONItem | Returns the card's address and metadata, with its pictures as data URIs. |
| WrappedLines | g As Graphics <br> value As String <br> width As Double <br> maximumLines As Integer | String | Returns the text wrapped at spaces into at most the supplied number of lines, ending with an ellipsis when it is cut. |
## Shared Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| DescendantElement | element As GraffitiProEditor.HTMLSupport.HTMLElement <br> tagName As String <br> role As String | GraffitiProEditor.HTMLSupport.HTMLElement | Returns the first descendant element with the supplied tag name and data-role, or Nil. |
| isWebURL | value As String | Boolean | (None) |
| ResolvedURL | baseURL As String <br> reference As String | String | Returns a page's relative address resolved against the page's own address. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| Description | String | (None) | Gets or sets the page's description shown on the card. |
| IconSource | String | (None) | Gets or sets the site's icon as an image data URI. |
| IconURL | String | (None) | Gets or sets the address the site's icon was fetched from. |
| ImageSource | String | (None) | Gets or sets the card's preview image as an image data URI. |
| ImageURL | String | (None) | Gets or sets the address the preview image was fetched from. Markdown export links to it. |
| SiteName | String | (None) | Gets or sets the site's name shown on the card, such as the publication or service. |
| State | States | (None) | Returns whether the card has no address, is fetching, has metadata, or shows its address as a plain link. |
| Title | String | (None) | Gets or sets the title shown on the card. |
| URL | String | (None) | Gets or sets the card's address. Setting it in an editor fetches its metadata; an address without a scheme gets https. |