Document how to handle clicked `[url]` tags in RichTextLabel

tutorials/ui/bbcode_in_richtextlabel.rst

@@ -76,8 +76,12 @@ Reference
 | **indent**            | ``[indent]{text}[/indent]``                               | Increase the indentation level of {text}.                                |
 +-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
 | **url**               | ``[url]{url}[/url]``                                      | Show {url} as such, underline it and make it clickable.                  |
+|                       |                                                           | **Must be handled with the "meta_clicked" signal to have an effect.**    |
+|                       |                                                           | See :ref:`doc_bbcode_in_richtextlabel_handling_url_tag_clicks`.          |
 +-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
 | **url (ref)**         | ``[url=<url>]{text}[/url]``                               | Makes {text} reference <url> (underlined and clickable).                 |
+|                       |                                                           | **Must be handled with the "meta_clicked" signal to have an effect.**    |
+|                       |                                                           | See :ref:`doc_bbcode_in_richtextlabel_handling_url_tag_clicks`.          |
 +-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
 | **image**             | ``[img]{path}[/img]``                                     | Insert image at resource {path}.                                         |
 +-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
@@ -175,6 +179,31 @@ For opaque RGB colors, any valid 6-digit hexadecimal code is supported, e.g. ``[
 For transparent RGB colors, any 8-digit hexadecimal code can be used, e.g. ``[color=#88ffffff]translucent white[/color]``.
 In this case, note that the alpha channel is the **first** component of the color code, not the last one.
 
+.. _doc_bbcode_in_richtextlabel_handling_url_tag_clicks:
+
+Handling ``[url]`` tag clicks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, ``[url]`` tags do nothing when clicked. This is to allow flexible use
+of ``[url]`` tags rather than limiting them to opening URLs in a web browser.
+
+To handle clicked ``[url]`` tags, connect the RichTextLabel node's
+:ref:`meta_clicked <class_RichTextLabel_signal_meta_clicked>` signal to a script function.
+
+For example, the following method can be connected to ``meta_clicked`` to open
+clicked URLs using the user's default web browser::
+
+    # This assumes RichTextLabel's `meta_clicked` signal was connected to
+    # the function below using the signal connection dialog.
+    func _richtextlabel_on_meta_clicked(meta):
+        # `meta` is not guaranteed to be a String, so convert it to a String
+        # to avoid script errors at run-time.
+        OS.shell_open(str(meta))
+
+For more advanced use cases, it's also possible to store JSON in an ``[url]``
+tag's option and parse it in the function that handles the ``meta_clicked`` signal.
+For example: ``[url={"example": "value"}]JSON[/url]``
+
 Image vertical offset
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -242,7 +271,7 @@ You can extend the :ref:`class_RichTextEffect` resource type to create your own
 BBCode tags. You begin by extending the :ref:`class_RichTextEffect` resource type. Add
 the ``tool`` prefix to your GDScript file if you wish to have these custom effects run
 within the editor itself. The RichTextLabel does not need to have a script attached,
-nor does it need to be running in ``tool`` mode. The new effect will be activable in 
+nor does it need to be running in ``tool`` mode. The new effect will be activable in
 the Inspector through the **Custom Effects** property.
 
 There is only one function that you need to extend: ``_process_custom_fx(char_fx)``.