Managing Hotlinks - MapBasic - 2023

The hotlink settings are persisted via the Set Map statement Layer Activate clause, which supports multiple hotlink definitions. This includes the ability to add new items, modify the attribute of existing items, remove and reorder items. For a discussion of how MapInfo Pro supports legacy syntax, see Exceptions to Support Backwards Compatibility.

Purpose

The purpose of Activate is to allow you to define new hotlinks. You use a hotlink to launch a file or a URL from a Map window.

Syntax

Set Map
[ Window window_id ]
[ Layer layer_id 
	[ Activate LAYER_ACTIVATE_CLAUSES ] ] 

Where LAYER_ACTIVATE_CLAUSES is:

	Using launch_expr  [ On  {  Labels |  Objects | Labels Objects } ]  
	[ Relative Path { On | Off } ] 
	[ Enable { On | Off }] 	
	[ Alias expression ]  
	[ ,LAYER_ACTIVATE_CLAUSES ]

window_id is the integer window identifier of a Map window.

layer_id identifies which layer to modify; can be a SmallInt (for example, use 1 to specify the top map layer other than Cosmetic) or a string representing the name of a table displayed in the map.

launch_expr is an expression that will resolve to the name of the file to launch when the object is activated.

expression the placeholder of the actual file name expression being set (any URL or filename).

Description

Relative Path lets you define links to files stored in locations relative to the tables. For example: if the table C:\DATA\STATES.TAB contains HotLinks to workspace files that are stored in directories under C:\data. The workspace file for New York, NEWYORK.WOR, is stored in C:\data\ny and the HotLink associated with New York is "NY\NEWYORK.WOR". Setting Relative Path to On tells MapInfo Pro to prefix the HotLink string with the location of the .tab file, in this case resulting in the launch string "C:\DATA\NY\NEWYORK.WOR".

Enable clause has two options On and Off. When set to On, it enables the hotlink definition and when set to Off, it disables the hotlink definition.

For an individual hotlink the Enable clause allow the user to "turn off" a hotlink while preserving the definition. (In versions prior to 10.0, the user disabled the hotlink by setting the expression to "", losing the original expression.)

An active object is an object in a Map window that has a URL or filename associated with it. Clicking on an active object with the HotLink Tool will launch the associated URL or file. For example, if the string http://www.boston.com is associated with a point object on the map, then clicking the point, or its label, will result in the default browser being started with the site http://www.boston.com. You can associate other types of files with map objects; MapInfo workspace (.wor), table (.tab) or application (.mbx) files, Word documents (.doc), executable files (.exe), etc. Any type of file that the system knows how to "launch" can be associated with a map object. From version 10.0 onwards another clause "Alias" has been added for hotlinks. This alias clause is used to set an expression, which will basically be the placeholder of the actual File Name Expression being set. In the current hotlinks implementation, the FileName Expression can be set to any URL or filename. It has been found that URL's can be very long and hence when an user clicks on an active Hotlinks object having multiple hotlink definitions, it becomes difficult to show the lengthy URL's in the popup window. To solve this problem, the Alias Expression has been added to the GUI. The similar work is performed by the Alias keyword in MapBasic. When an active object has multiple hotlink definitions, if you set the Alias Expression to a valid expression, then the popup window shows the Alias Name, instead of the lengthy URL.

This version of the command wipes out any existing definitions and creates one or more new definitions. The Using clause is required and launch_expr must not be an empty string (for example, ""). When the Enable clause is included and set to Off, the hotlink definition will be disabled.

The On, Relative Path, Enable and Alias clauses are optional.

For more information about Hotlinks, see Adding New HotLink Definitions, Modifying Existing HotLink Definitions, Removing HotLink Definitions, and Reordering HotLink Definitions.

Exceptions to Support Backwards Compatibility

The Using clause can be omitted, but only from the first HotLink definition. The Using expression can be empty (""), but only for the first HotLink definition.

No Using Clause

Both of the following commands omit the Using clause, and in 850 this has the consequence of updating the properties of the one/only hotlink def, even if the user has never issues a command to set the Using clause. As of 900 these commands are a problem because map layers are created without any hotlink definitions.

• Activate On Objects
• Activate Relative Path On

To solve this problem, MapInfo Pro allows empty expressions, but only for the first hotlink definition. As was the case in pre-900 versions, a hotlink with an empty expression is effectively disabled. Omitting the Using clause, generates an error unless the command originates from a pre-900 application or workspace.

Empty Using clause

The following command sets the hotlink expression to an empty string, which essentially disables hotlink capability for the layer. In fact, the default launch expression is the empty string, so the hotlink definition has no affect until the expression is set to a non-empty string. This works as a way to enable/disable a hotlink in 850. In 900 we support the notion of enabling/disabling via explicit syntax in the Set map Layer Activate Enable On/Off command, and do not really want to support hotlink definition with an empty expression string.

Set Map Layer 1 Activate Using ""

This statement allows empty expressions, but only for the first hotlink definition. As was the case in pre-9.0 versions, a hotlink with an empty expression is effectively disabled.

When a Set Map Layer Activate command is encounter with no Using clause or an empty Using clause, the action depends on the current state of the layer's hotlinks.

The table following contains examples of different scenarios.

Note that the same actions will apply when reading in table metadata.

Example

Set Map Layer 1 Activate Using Url1 On Objects Relative Path Off Enable 
On, Using Url2 On Objects Relative Path On Enable On