GetImage (Stringlist subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
No edit summary
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:Stringlist:GetImage subtitle}}
{{Template:Stringlist:GetImage subtitle}}


This method copies data from a specified <var>Stringlist</var> item to an image.
This method copies data from a specified <var>Stringlist</var> item to an <var>Image</var>.


==Syntax==
==Syntax==
{{Template:Stringlist:GetImage syntax}}
{{Template:Stringlist:GetImage syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>sl</th>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object. </td></tr>
<td>A <var>Stringlist</var> object. </td></tr>
<tr><th>itemNum</th>
<tr><th>itemNum</th>
<td>The number of the item in the <var>Stringlist</var>. </td></tr>
<td>The number of the item in the <var>Stringlist</var>. </td></tr>
<tr><th>imageName</th>
<tr><th>imageName</th>
<td>A string that contains the name of an image. This is an optional argument if an image has already been associated with the <var>Stringlist</var> via [[BindImage (Stringlist function)|BindImage]]. Otherwise, it is a required argument. <b><i>This argument is case sensitive</i></b>.  That is, in the likely event the <var class="product">User Language</var> was written in mixed case, with automatic uppercasing in effect (see [[Mixed-case <var class="product">User Language</var>]]) the image name should be in <b><i>uppercase</i></b>.</td></tr>
<td>A string that contains the name of an <var>Image</var>. This is an optional argument if an image has already been associated with the <var>Stringlist</var> via <var>[[BindImage (Stringlist function)|BindImage]]</var>. Otherwise, it is a required argument. <b><i>This argument is case sensitive</i></b>.  That is, in the likely event the <var class="product">SOUL</var> was written in mixed case, with automatic uppercasing in effect (see [[Mixed-case SOUL]]) the image name should be in <b><i>uppercase</i></b>.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>All errors in <var>GetImage</var> result in request cancellation.
<li>All errors in <var>GetImage</var> result in request cancellation.</li>
<li><var>Stringlist</var> items longer than the target image are silently truncated.</li>
<li><var>Stringlist</var> items shorter than the target image do not modify the image contents beyond the <var>Stringlist</var> item length. As such, if <var>GetImage</var> is used with varying length <var>Stringlist</var> items, the images can contain "leftover" data after a <var>GetImage</var>. If this is a concern, a <var>[[Images#PREPARE_statement|Prepare Image]]</var> should be done before each <var>GetImage</var> invocation.</li>
</ul>
</ul>


==Examples==
==Examples==
<ol><li>One way to extract a <var>Stringlist</var> item into an image (called <code>Headstone</code>, below) is as follows:
One way to extract a <var>Stringlist</var> item into an image (called <code>Headstone</code>, below) is as follows:


<p class="code">%list:getImage(%n, 'HEADSTONE')
<p class="code">%list:getImage(%n, 'HEADSTONE')
</p>
</p>


<li>Here is a neater and more efficient way of doing this:
<p>
Here is a neater and more efficient way of doing this: </p>


<p class="code">%list:bindImage('HEADSTONE')
<p class="code">%list:bindImage('HEADSTONE')
Line 33: Line 39:
</p>
</p>


In this last example, the [[BindImage (Stringlist function)|BindImage]] associates the image with the <var>Stringlist</var>, eliminating the need to specify the image name on the <var>GetImage</var>.
In this last example, <var>BindImage</var> associates the image with the <var>Stringlist</var>, eliminating the need to specify the image name on the <var>GetImage</var>.
</ol>


==See also==
==See also==
{{Template:Stringlist:GetImage footer}}
{{Template:Stringlist:GetImage footer}}

Latest revision as of 21:51, 22 January 2015

Retrieve Stringlist item into image (Stringlist class)


This method copies data from a specified Stringlist item to an Image.

Syntax

sl:GetImage( itemNum, [imageName])

Syntax terms

sl A Stringlist object.
itemNum The number of the item in the Stringlist.
imageName A string that contains the name of an Image. This is an optional argument if an image has already been associated with the Stringlist via BindImage. Otherwise, it is a required argument. This argument is case sensitive. That is, in the likely event the SOUL was written in mixed case, with automatic uppercasing in effect (see Mixed-case SOUL) the image name should be in uppercase.

Usage notes

  • All errors in GetImage result in request cancellation.
  • Stringlist items longer than the target image are silently truncated.
  • Stringlist items shorter than the target image do not modify the image contents beyond the Stringlist item length. As such, if GetImage is used with varying length Stringlist items, the images can contain "leftover" data after a GetImage. If this is a concern, a Prepare Image should be done before each GetImage invocation.

Examples

One way to extract a Stringlist item into an image (called Headstone, below) is as follows:

%list:getImage(%n, 'HEADSTONE')

Here is a neater and more efficient way of doing this:

%list:bindImage('HEADSTONE') ... %list:getImage(%n)

In this last example, BindImage associates the image with the Stringlist, eliminating the need to specify the image name on the GetImage.

See also