Jump to content

Kexi/Plugins/Forms/Button hyperlinks

From KDE Community Wiki

Design page for task: "Add support for opening hyperlink via a form button".

Rationale

It should be possible to assign hyperlink (URL) to a form button. URL could be:

  1. Static (assigned to a button via 'hyperlink' property of type string)
  2. Dynamic (bound to one of form's field)

Details

Hyperlink Type property

Distinction between Static/Dynamic URL has to be encoded somehow. To do so, add hyperlinkType property (translated name "Hyperlink Type") for Push button, of enum type:

  • NoHyperlink - clicking on button will not lead to opening of URL even if it has been provided in the hyperlink property or if a field has been bound
  • StaticHyperlink - clicking on button will lead to opening of URL provided in the hyperlink property; if not provided, nothing happens
  • DynamicHyperlink - clicking on button will lead to opening of URL provided in the bound field; if not bound or value is empty, nothing happens; hyperlink property is ignored in any case

Hyperlink property

When hyperlinkType == StaticHyperlink, hyperlink property of type string is used (translated name "Hyperlink") for Push button. It is encoded single URL to open.

Hyperlink Executable property

When URL is local and points to executable (script or program binary), hyperlinkExecutable property is examined (type: bool). If it's true, the executable is executed, otherwise error message is displayed.

Hyperlink Local property

If hyperlinkLocal property (type: bool) is true, and URL points to a local file or directory, it is opened. Otherwise error message is displayed. If hyperlinkLocal property is false, remote URLs are opened properly.

HyperlinkTool property

hyperlinkTool is of enum type and controls the tool used to open the hyperlink URL:

  • DefaultHyperlinkTool - uses default app for given hyperlink
  • BrowserHyperlinkTool - always invokes user's preferred browser for given hyperlink
  • MailerHyperlinkTool - always invokes the standard email application for given hyperlink

URLs

URL values are used for value of hyperlink property (for StaticHyperlink type) or for value bound field (for DynamicHyperlink type). The property can be:

  • empty (then, clicking the button has no effect)
  • local path relative to the database path
    • TODO: database path is well defined for SQLite-based driver but not for server databases...
  • local absolute path
  • local URL with file:/ protocol
  • remote with given protocol
  • local path to an executable

URL can lead to folder or file.

Opening URLs

See KRun explanation. Use KRun::runUrl(): 

QString type = KMimeType::findByUrl(url)->name();
KRun::runUrl(url, parentWidget, type);

If hyperlinkExecutable property is false, check if the URL points to executable: 

if (KRun::isExecutableFile(url, type)) {
  // show "<URL> is executable file" error message
}

If hyperlinkLocal property is true, check if the URL points to local: 

if (!KUrl::isLocalFile(url)) {
  // show "<URL> is not local file" error message
}

If hyperlinkTool == BrowserHyperlinkTool, use KToolInvocation::invokeBrowser(const QUrl &url).

If hyperlinkTool == MailerHyperlinkTool, use KToolInvocation::invokeMailer(const QUrl &mailtoURL).

See KToolInvocation API for details.

Further work

Appearance property

A future extension, we may want to display the button as a pure QLabel with a hyperlink in it set using <a>...</a>. For this we'd need extra property [Appearance] appearance, with these values:

  • ButtonAppearance, i18n("Button"), the default
  • HyperlinkAppearance, i18n("Hyperlink)
Retrieved from "https://community.kde.org/index.php?title=Kexi/Plugins/Forms/Button_hyperlinks&oldid=29911"