Mercurial > hg > forks > geeqie

view web/help/GuideReferenceLua.html @ 2835:bb44bd76f857

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Simplify OSD settings in Preferences Move Overlay Screen Display settings in Preferences from the Windows tab to its own tab. Allow preformatted tags to be set by button click or drag-and-drop.
author Colin Clark <colin.clark@cclark.uk>
date Tue, 02 Oct 2018 13:01:06 +0100
parents 54ae25ba376b
children
line wrap: on
line source

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Lua Extensions</title>
<link rel="previous" href="GuideReferenceMetadata.html" title="Metadata Processing">
<link rel="next" href="GuideReferenceConfig.html" title="Configuration Files and Locations">
<link rel="top" href="GuideIndex.html" title="The Geeqie User Manual">
<style type="text/css">

html { height: 100%; }
body {
  margin: 0px; padding: 12px;
  background-color: #f9f9f6;
  min-height: 100%;
  direction: ltr;
}
div, p, pre, blockquote { margin: 0; padding: 0; }
p img { vertical-align: middle; }
sub { font-size: 0.83em; }
sub sub { font-size: 1em; }
sup { font-size: 0.83em; }
sup sup { font-size: 1em; }
table { border-collapse: collapse; }
table.table-pgwide { width: 100%; }
td { vertical-align: top; }
td { padding: 0.2em 0.83em 0.2em 0.83em; }
th { padding: 0 0.83em 0 0.83em; }
tr.tr-shade {
  background-color: #f9f9f6;
}
td.td-colsep { border-right: solid 1px; }
td.td-rowsep { border-bottom: solid 1px; }
thead { border-top: solid 2px; border-bottom: solid 2px; }
tfoot { border-top: solid 2px; border-bottom: solid 2px; }
div.body {
  padding: 1em;
  max-width: 60em;
  background-color: #ffffff;
  border: solid 1px #e0e0df;
}
div.body-sidebar {
  margin-right: 13em;
}
div.division div.division { margin-top: 1.72em; }
div.division div.division div.division { margin-top: 1.44em; }
div.header {
  margin: 0;
  color: #3f3f3f;
  border-bottom: solid 1px #e0e0df;
}
h1, h2, h3, h4, h5, h6, h7 {
  margin: 0; padding: 0;
  color: #3f3f3f;
}
h1.title { font-size: 1.72em; }
h2.title { font-size: 1.44em; }
h3.title { font-size: 1.2em; }
h4.title, h5.title, h6.title, h7.title { font-size: 1em; }
.block { margin-top: 1em; }
.block .block-first { margin-top: 0; }
.block-indent {
  margin-left left: 1.72em;
  margin-: 1em;
}
.block-indent .block-indent { margin-left: 0em; margin-right: 0em; }
td .block-indent  { margin-left: 0em; margin-right: 0em; }
dd .block-indent  { margin-left: 0em; margin-right: 0em; }
.block-verbatim { white-space: pre; }
div.title {
  margin-bottom: 0.2em;
  font-weight: bold;
  color: #3f3f3f;
}
div.title-formal { padding-left: 0.2em; padding-right: 0.2em; }
div.title-formal .label { font-weight: normal; }
a {
  color: #1f609f;
  text-decoration: none;
}
a:hover { text-decoration: underline; }
a:visited { color: #9f1f6f; }
ul, ol, dl { margin: 0; padding: 0; }
li {
  margin-top: 1em;
  margin-left: 2.4em;
  padding: 0;
}
li.li-first { margin-top: 0; }
dt { margin: 1em 0 0 0; }
dt.dt-first { margin: 0; }
dd {
  margin-left: 1.72em;
  margin-top: 0.5em;
}
dl.dl-compact dt { margin-top: 0; }
dl.dl-compact dd { margin-top: 0; margin-bottom: 0; }


ul.linktrail {
  display: block;
  margin: 0.2em 0 0 0;
  text-align: right;
}
li.linktrail { display: inline; margin: 0; padding: 0; }

li.linktrail::before {
  content: '  /  ';
  color: #3f3f3f;
}

li.linktrail-first::before, li.linktrail-only::before { content: ''; }


div.navbar {
  padding: 0.5em 1em 0.5em 1em;
  max-width: 60em;
  background-color: #ffffff;
  border: solid 1px #e0e0df;
}
div.navbar-top { margin-bottom: 1em; }
div.navbar-bottom { margin-top: 1em; clear: both; }
div.navbar img { border: 0; vertical-align: -0.4em; }
table.navbar { width: 100%; margin: 0; border: none; }
table.navbar td { padding: 0; border: none; }
td.navbar-next {
  text-align: right;
}
a.navbar-prev::before {
  
  content: '◀  ';
  color: #3f3f3f;
}
a.navbar-next::after {
  
  content: '  ▶';
  color: #3f3f3f;
}


div.sidebar {
  float: right;
  padding: 0; margin: 0; width: 12em;
}
div.sidenav {
  padding: 0.5em 1em 0 1em;
  background-color: #ffffff;
  border: solid 1px #e0e0df;
}
div.sidenav div.autotoc {
  background-color: #ffffff;
  border: none; padding: 0; margin: 0;
}
div.sidenav div.autotoc div.autotoc { margin-top: 0.5em; }
div.sidenav div.autotoc li { margin-bottom: 0.5em; }
div.sidenav div.autotoc div.autotoc div.autotoc {
  margin-left: 1em;
  margin-top: 0;
}
div.sidenav div.autotoc div.autotoc div.autotoc li { margin-bottom: 0; }


div.autotoc {
  
  display: table;
  margin-top: 1em;
  margin-left: 1.72em;
  padding: 0.5em 1em 0.5em 1em;
  background-color: #f0f9ff;
  border: solid 1px #c0c9ff;
}
div.autotoc ul { margin: 0; padding: 0; }
div.autotoc li { list-style-type: none; margin: 0; }
div.autotoc div.autotoc-title { margin-bottom: 0.5em; }
div.autotoc div.autotoc { border: none; padding: 0; margin-top: 0; margin-bottom: 0.5em; }
div.autotoc div.autotoc div.autotoc { margin-bottom: 0; }


span.bibliolabel {
  color: #3f3f3f;
}


div.admonition {
  padding: 0.5em 6px 0.5em 6px;
  border: solid 1px #e0e0df;
  background-color: #fffff0;
}
div.caution-inner, div.important-inner, div.note-inner, div.tip-inner, div.warning-inner {
  padding-left: 60px;
  background-position: left top;
  background-repeat: no-repeat;
  min-height: 48px;
}
div.caution-inner { background-image: url("admon-caution.png"); }
div.important-inner { background-image: url("admon-important.png"); }
div.note-inner { background-image: url("admon-note.png"); }
div.note-bug div.note-inner { background-image: url("admon-bug.png"); }
div.tip-inner { background-image: url("admon-tip.png"); }
div.warning-inner { background-image: url("admon-warning.png"); }
div.blockquote {
  
  background-image: url('watermark-blockquote-201C.png');
  background-repeat: no-repeat;
  background-position: top left;
  padding: 0.5em;
  padding-left: 4em;
}
div.attribution {
  margin-top: 0.5em;
  color: #3f3f3f;
}
div.attribution::before {
  
  content: '― ';
}
div.epigraph {
  text-align: right;
  margin-left: 20%;
  margin-right: 0;
  color: #3f3f3f;
}
div.figure, div.informalfigure {
  
  display: table;
  padding: 0.5em;
  background-color: #f9f9f6;
  border: solid 1px #e0e0df;
}
div.figure-inner, div.informalfigure-inner {
  padding: 0.5em;
  background-color: #ffffff;
  border: solid 1px #e0e0df;
}
div.caption { margin-top: 0.5em; }
div.programlisting {
  padding: 0.5em;
  
  background-color: #f9f9f6;
  border: solid 1px #e0e0df;
}
div.screen {
  padding: 0.5em;
  
  background-color: #f9f9f6;
  border: solid 1px #e0e0df;
}
div.screen .prompt {
  color: #3f3f3f;
}
div.screen .userinput {
  font-weight: bold;
  color: #3f3f3f;
}
div.programlisting .userinput {
  font-weight: bold;
  color: #3f3f3f;
}
pre.linenumbering {
  color: #3f3f3f;
  margin: 0;
  padding-right: 1em;
  float: left;
  text-align: right;
}



dl.index dt { margin-top: 0; }
dl.index dd { margin-top: 0; margin-bottom: 0; }
dl.indexdiv dt { margin-top: 0; }
dl.indexdiv dd { margin-top: 0; margin-bottom: 0; }
dl.setindex dt { margin-top: 0; }
dl.setindex dd { margin-top: 0; margin-bottom: 0; }
div.list div.title-formal span.title {
  border-bottom: solid 1px #e0e0df;
}
div.simplelist {
  margin-left: 1.72em;
}
div.simplelist table { margin-left: 0; border: none; }
div.simplelist td {
  padding: 0.5em;
  border-left: solid 1px #e0e0df;
}
div.simplelist td.td-first {
  padding-left: 0;
  border-left: 0;
}
div.synopsis {
  padding: 0.5em;
  
  background-color: #f9f9f6;
  border-top: solid 2px #c0c9ff;
  border-bottom: solid 2px #c0c9ff;
}
div.synopsis div.synopsis {
  padding: 0;
  border: none;
}
div.synopsis div.block { margin-top: 0.2em; }
div.synopsis div.block-first { margin-top: 0; }
div.cmdsynopsis { font-family: monospace; }

span.accel { text-decoration: underline; }
span.acronym { font-family: sans-serif; }
span.application { font-style: italic; }
span.classname, span.exceptionname, span.interfacename { font-family: monospace; }
span.code {
  font-family: monospace;
  border: solid 1px #e0e0df;
  padding-left: 0.2em;
  padding-right: 0.2em;
}
pre span.code { border: none; padding: 0; }
span.command {
  font-family: monospace;
  border: solid 1px #e0e0df;
  padding-left: 0.2em;
  padding-right: 0.2em;
}
pre span.command { border: none; padding: 0; }
span.computeroutput { font-family: monospace; }

span.constant { font-family: monospace; }
span.database { font-family: monospace; }
span.email { font-family: monospace; }
span.emphasis { font-style: italic; }
span.emphasis-bold { font-style: normal; font-weight: bold; }
span.envar { font-family: monospace; }

span.filename { font-family: monospace; }
span.firstterm { font-style: italic; }
span.foreignphrase { font-style: italic; }
span.function { font-family: monospace; }

dt.glossterm span.glossterm { font-style: normal; }


span.glossterm { font-style: italic; }

span.guibutton, span.guilabel, span.guimenu, span.guimenuitem, span.guisubmenu, span.interface {
  font-weight: bold;
  color: #3f3f3f;
}
span.keycap {
  font-weight: bold;
  color: #3f3f3f;
}
span.lineannotation { font-style: italic; }
span.literal { font-family: monospace; }
span.markup  { font-family: monospace; }
span.medialabel { font-style: italic; }
span.methodname { font-family: monospace; }
span.ooclass, span.ooexception, span.oointerface { font-family: monospace; }
span.option { font-family: monospace; }
span.parameter { font-family: monospace; }
span.paramdef span.parameter { font-style: italic; }
span.prompt { font-family: monospace; }
span.property { font-family: monospace; }
span.replaceable  { font-style: italic; }
span.returnvalue { font-family: monospace; }
span.sgmltag { font-family: monospace; }
span.structfield, span.structname { font-family: monospace; }
span.symbol { font-family: monospace; }
span.systemitem { font-family: monospace; }
span.token { font-family: monospace; }
span.type { font-family: monospace; }
span.uri { font-family: monospace; }
span.userinput { font-family: monospace; }
span.varname { font-family: monospace; }
span.wordasword { font-style: italic; }



div.footnotes { font-style: italic; font-size: 0.8em; }
div.footnote { margin-top: 1.44em; }
span.footnote-number { display: inline; padding-right: 0.83em; }
span.footnote-number + p { display: inline; }
a.footnote { text-decoration: none; font-size: 0.8em; }
a.footnote-ref { text-decoration: none; }

span.co {
  margin-left: 0.2em; margin-right: 0.2em;
  padding-left: 0.4em; padding-right: 0.4em;
  border: solid 1px #000000;
  -moz-border-radius: 8px;
  background-color: #000000;
  color: #FFFFFF;
  font-size: 8px;
}
span.co:hover {
  border-color: #333333;
  background-color: #333333;
  color: #FFFFFF;
}
span.co a { text-decoration: none; }
span.co a:hover { text-decoration: none; }

dt.question { margin-left: 0em; }
dt.question div.label { float: left; }
dd + dt.question { margin-top: 1em; }
dd.answer {
  margin-top: 1em;
  margin-left: 2em;
  margin-right: 1em;
}
dd.answer div.label { float: left; }
</style>
</head>
<body>
<div class="navbar navbar-top"><table class="navbar"><tr>
<td class="navbar-prev"><a class="navbar-prev" href="GuideReferenceMetadata.html" title="Metadata Processing">Metadata Processing</a></td>
<td class="navbar-next"><a class="navbar-next" href="GuideReferenceConfig.html" title="Configuration Files and Locations">Configuration Files and Locations</a></td>
</tr></table></div>
<div class="sidebar"><div class="sidenav"><div class="autotoc"><ul>
<li><a href="GuideIndex-info.html" title="About This Document">About This Document</a></li>
<li>
<a class="xref" href="GuideIndex.html" title="The Geeqie User Manual">The Geeqie User Manual</a><div class="autotoc"><ul>
<li><a class="xref" href="GuideIntroduction.html" title="Introduction">Introduction</a></li>
<li><a class="xref" href="GuideMainWindow.html" title="Main Window">Main Window</a></li>
<li><a class="xref" href="GuideSidebars.html" title="Sidebars">Sidebars</a></li>
<li><a class="xref" href="GuideOtherWindows.html" title="Stand-alone Windows">Stand-alone Windows</a></li>
<li><a class="xref" href="GuideImageSearch.html" title="Search and Select">Search and Select</a></li>
<li><a class="xref" href="GuideImageManagementPlugins.html" title="Plugins">Plugins</a></li>
<li><a class="xref" href="GuideImageManagement.html" title="File Management">File Management</a></li>
<li><a class="xref" href="GuideColorManagement.html" title="Color Management">Color Management</a></li>
<li><a class="xref" href="GuideImagePresentation.html" title="Image Presentation">Image Presentation</a></li>
<li><a class="xref" href="GuidePrinting.html" title="Printing">Printing</a></li>
<li><a class="xref" href="GuideOptionsMain.html" title="Preferences">Preferences</a></li>
<li><a class="xref" href="GuideOptionsAdditional.html" title="Additional Preferences">Additional Preferences</a></li>
<li>
<a class="xref" href="GuideReference.html" title="Reference">Reference</a><div class="autotoc"><ul>
<li><a class="xref" href="GuideReferenceCommandLine.html" title="Command Line Options">Command Line Options</a></li>
<li><a class="xref" href="GuideReferenceKeyboardShortcuts.html" title="Keyboard and Mouse Shortcuts">Keyboard and Mouse Shortcuts</a></li>
<li><a class="xref" href="GuideReferenceThumbnails.html" title="Thumbnails">Thumbnails</a></li>
<li><a class="xref" href="GuideReferenceMetadata.html" title="Metadata Processing">Metadata Processing</a></li>
<li>Lua Extensions</li>
<li><a class="xref" href="GuideReferenceConfig.html" title="Configuration Files and Locations">Configuration Files and Locations</a></li>
<li><a class="xref" href="GuideReferenceLIRC.html" title="Infra-red controller">Infra-red controller</a></li>
<li><a class="xref" href="GuideReferenceXmpExif.html" title="XMP, Exif and IPTC">XMP, Exif and IPTC</a></li>
<li><a class="xref" href="GuideReferenceSupportedFormats.html" title="Supported File Formats">Supported File Formats</a></li>
<li><a class="xref" href="GuideReferencePixbufLoaders.html" title="Additional pixbuf loaders">Additional pixbuf loaders</a></li>
<li><a class="xref" href="GuideReferenceUTC.html" title="UTC and Daylight Saving Time (DST)">UTC and Daylight Saving Time (DST)</a></li>
<li><a class="xref" href="GuideReferenceDecodeLatLong.html" title="Decoding Latitude and Longitude">Decoding Latitude and Longitude</a></li>
<li><a class="xref" href="GuideReferenceStandards.html" title="Standards">Standards</a></li>
<li><a class="xref" href="GuideReferencePCRE.html" title="Perl Compatible Regular Expressions">Perl Compatible Regular Expressions</a></li>
</ul></div>
</li>
<li><a class="xref" href="GuideFaq.html" title="Frequently Asked Questions">Frequently Asked Questions</a></li>
<li><a class="xref" href="GuideLicence.html" title="Licence">Licence</a></li>
<li><a class="xref" href="GuideCredits.html" title="Credits">Credits</a></li>
<li><a class="xref" href="GuideGnuFdl.html" title="GNU Free Documentation License">GNU Free Documentation License</a></li>
</ul></div>
</li>
</ul></div></div></div>
<div class="body body-sidebar"><div class="division section">
<a name="GuideReferenceLua"></a><div class="header"><h1 class="section title"><span class="title">Lua Extensions</span></h1></div>
<ul class="linktrail">
<li class="linktrail linktrail-first"><a class="linktrail" href="GuideIndex.html" title="The Geeqie User Manual">The Geeqie User Manual</a></li>
<li class="linktrail linktrail-last"><a class="linktrail" href="GuideReference.html" title="Reference">Reference</a></li>
</ul>
<p class="para block block-first">
    Lua scripts allow the functionality of Geeqie to be extended. Lua scripts may only be used in conjunction with the
    <a class="link" href="GuideOptionsOSD.html#OverlayScreenDisplay" title="Overlay Screen Display">Overlay Screen Display</a>
    and the
    <div dir="ltr" class=" block programlisting block-indent"><pre class="programlisting">geeqie --remote --lua:</pre></div>
    command line option.
  </p>
<p class="para block"></p>
<p class="para block">Some knowledge of the Lua programming language is required.</p>
<div class="autotoc"><ul>
<li>
<span class="label">13.5.1. </span><a class="xref" href="GuideReferenceLua.html#Requirements" title="Requirements">Requirements</a>
</li>
<li>
<span class="label">13.5.2. </span><a class="xref" href="GuideReferenceLua.html#HowToUseLua" title="How to use Lua">How to use Lua</a>
</li>
<li>
<span class="label">13.5.3. </span><a class="xref" href="GuideReferenceLua.html#GeeqieBuiltIn%20Functions" title="Geeqie Lua built-in functions">Geeqie Lua built-in functions</a>
</li>
<li>
<span class="label">13.5.4. </span><a class="xref" href="GuideReferenceLua.html#Examples" title="Examples">Examples</a>
</li>
<li>
<span class="label">13.5.5. </span><a class="xref" href="GuideReferenceLua.html#Warning" title="Warning">Warning</a>
</li>
</ul></div>
<div class="division section">
<a name="Requirements"></a><div class="header"><h2 class="section title"><span class="title"><span class="label">13.5.1. </span>Requirements</span></h2></div>
<p class="para block block-first">Use of Lua within Geeqie requires Lua to be installed. If you are compiling from sources, Lua functionality will be available if the development files dependencies are met.</p>
<p class="para block">If you are using a pre-compiled distribution, availability depends on the package maintainer.</p>
</div>
<div class="division section">
<a name="HowToUseLua"></a><div class="header"><h2 class="section title"><span class="title"><span class="label">13.5.2. </span>How to use Lua</span></h2></div>
<p class="para block block-first">
      Lua scripts must be stored in a single folder as defined in
      <a class="link" href="GuideReferenceConfig.html" title="Configuration Files and Locations">Configuration Files and Locations</a>
      .
    </p>
<p class="para block">
      A link to a Lua script must be inserted into the overlay template. Refer to the
      <a class="link" href="GuideOptionsOSD.html#OverlayScreenDisplay" title="Overlay Screen Display">Overlay Screen Display</a>
      section of Window Options.
    </p>
<p class="para block">The full extent of the Lua language is available.</p>
</div>
<div class="division section">
<a name="GeeqieBuiltIn%20Functions"></a><div class="header"><h2 class="section title"><span class="title"><span class="label">13.5.3. </span>Geeqie Lua built-in functions</span></h2></div>
<p class="para block block-first">The following functions are built in to Geeqie:</p>
<p class="para block">
      <div class="table block block-indent"><table style="border: solid 1px;"><tbody>
<tr>
<td class="td-colsep">
                <span class="emphasis emphasis-bold">Function</span>
              </td>
<td>
                <span class="emphasis emphasis-bold">Returns</span>
              </td>
</tr>
<tr class="tr-shade">
<td class="td-colsep">Image:get_path()</td>
<td>The full path of the file, including filename and extension</td>
</tr>
<tr>
<td class="td-colsep">Image:get_name()</td>
<td>The full filename including extension</td>
</tr>
<tr class="tr-shade">
<td class="td-colsep">Image:get_extension</td>
<td>The file extension including preceeding dot</td>
</tr>
<tr>
<td class="td-colsep">Image:get_date()</td>
<td>The file date in Unix timestamp format.</td>
</tr>
<tr class="tr-shade">
<td class="td-colsep">Image:get_size()</td>
<td>The file size in bytes</td>
</tr>
<tr>
<td class="td-colsep">Image:get_marks()</td>
<td>An integer representing the marks set for the file</td>
</tr>
<tr class="tr-shade">
<td class="td-colsep">Image:get_exif()</td>
<td>A data structure containing the entire exif data</td>
</tr>
<tr>
<td class="td-colsep">&lt;exif_str&gt;:get_datum("&lt;exif_tag&gt;")</td>
<td>A single exif tag extracted from a structure output by the above command</td>
</tr>
</tbody></table></div>
    </p>
<p class="para block">The keyword "Image" refers to the file currently being displayed by Geeqie.</p>
</div>
<div class="division section">
<a name="Examples"></a><div class="header"><h2 class="section title"><span class="title"><span class="label">13.5.4. </span>Examples</span></h2></div>
<p class="para block block-first">
      The following example, which outputs the jpeg comment of a file, demonstrates the use of a built-in function and how to call a system command from a Lua script:
      <div dir="ltr" class=" block programlisting block-indent block-first"><pre class="programlisting">        path=Image:get_path()
        commentfile=io.popen("exiv2 -p c \"" .. path .. "\"" )
        comment = commentfile:read("*a")
        commentfile:close()
        return (comment)
      </pre></div>
    </p>
<p class="para block">Note that it is necessary to have escape characters surrounding path and filenames.</p>
<p class="para block">
      The following example demonstrates how to extract exif data from a file:
      <div dir="ltr" class=" block programlisting block-indent block-first"><pre class="programlisting">        --Retrieve the DateTimeDigitized exif tag
        exif_structure = Image:get_exif();
        DateTimeDigitized = exif_structure:get_datum("Exif.Photo.DateTimeDigitized");
        return (os.date(DateTimeDigitized))
      </pre></div>
    </p>
</div>
<div class="division section">
<a name="Warning"></a><div class="header"><h2 class="section title"><span class="title"><span class="label">13.5.5. </span>Warning</span></h2></div>
<div class="admonition block warning block-first block-indent"><div class="warning-inner">
      <p class="para block block-first">Lua is a powerful programming language. Errors in script files, besides having undesirable side-effects, may cause Geeqie to crash.</p>
    </div></div>
</div>
</div></div>
<div class="navbar navbar-bottom"><table class="navbar"><tr>
<td class="navbar-prev"><a class="navbar-prev" href="GuideReferenceMetadata.html" title="Metadata Processing">Metadata Processing</a></td>
<td class="navbar-next"><a class="navbar-next" href="GuideReferenceConfig.html" title="Configuration Files and Locations">Configuration Files and Locations</a></td>
</tr></table></div>
</body>
</html>