OverlayImageItem (Stringlist subroutine): Difference between revisions
Jump to navigation
Jump to search
m (syntax digram, tags and links) |
m (→Examples) |
||
| (9 intermediate revisions by 2 users not shown) | |||
| Line 16: | Line 16: | ||
<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> | <tr><th>itemNum</th> | ||
<td>The number of the <var>stringlist</var> item that is to be updated. </td></tr> | <td>The number of the <var>stringlist</var> item that is to be updated. </td></tr> | ||
<tr><th> | <tr><th>imageItem</th> | ||
<td>The image item that indicates the overlay offset and length and, if the third argument is not specified, the value to be overlayed in the <var>stringlist</var> item. </td></tr> | <td>The image item that indicates the overlay offset and length and, if the third argument is not specified, the value to be overlayed in the <var>stringlist</var> item. </td></tr> | ||
<tr><th>value</th> | <tr><th>value</th> | ||
<td>The value to be placed at the image item's offset in the <var>stringlist</var> item. If this optional argument is not specified, the contents of the image item specified by the <var class="term"> | <td>The value to be placed at the image item's offset in the <var>stringlist</var> item. If this optional argument is not specified, the contents of the image item specified by the <var class="term">itemNum</var> argument are used to overlay the <var>stringlist</var> item.</td></tr> | ||
</table> | </table> | ||
| Line 27: | Line 27: | ||
<ul> | <ul> | ||
<li>All errors in <var>OverlayImageItem</var> result in request cancellation. | <li>All errors in <var>OverlayImageItem</var> result in request cancellation. | ||
<li><var>OverlayImageItem</var> does not change the length of a <var>Stringlist</var> item. If the overlay string does not completely overlay a <var>Stringlist</var> item, the characters after | <li><var>OverlayImageItem</var> does not change the length of a <var>Stringlist</var> item. If the overlay string does not completely overlay a <var>Stringlist</var> item, the characters before and after the overlayed string remain unchanged. | ||
<li>If the start column plus the length of the image item is greater than the current length of the <var>Stringlist</var> item, the request is cancelled. | <li>If the start column plus the length of the image item is greater than the current length of the <var>Stringlist</var> item, the request is cancelled. | ||
</ul> | </ul> | ||
==Examples== | ==Examples== | ||
< | <ol><li><var>OverlayImageItem</var> is especially useful for <var>Stringlists</var> whose contents map to an image. In the following example, the <var>Stringlist</var> item associated with product code <code>983</code> has its description overlayed with a new description: | ||
<p class="code">image product | <p class="code">image product | ||
| Line 38: | Line 38: | ||
desc is string len 30 | desc is string len 30 | ||
end image | end image | ||
... | |||
fr products | fr products | ||
%product:code = code | %product:code = code | ||
| Line 44: | Line 44: | ||
%rc = %list:addImage('PRODUCT') | %rc = %list:addImage('PRODUCT') | ||
end for | end for | ||
... | |||
%product:code = 983 | %product:code = 983 | ||
%num = %list:findImageItem(%product:code) | %num = %list:findImageItem(%product:code) | ||
| Line 51: | Line 51: | ||
</p> | </p> | ||
<li>If a <var class="term">value</var> is specified in addition to the <var class="term"> | <li>If a <var class="term">value</var> is specified in addition to the <var class="term">imageItem</var>, processing is performed as if the <var class="term">value</var> were assigned to the <var class="term">imageItem</var>, before any overlaying is performed, and then the <var class="term">imageItem</var> is restored to its original value. Any data type conversions required between the <var class="term">value</var> and the <var class="term">imageIitem</var> are performed before the overlay is performed. | ||
That is, this method invocation: | That is, this method invocation: | ||
| Line 64: | Line 64: | ||
%list:overlayImageItem(%num, %product:code) | %list:overlayImageItem(%num, %product:code) | ||
%product:code = %temp | %product:code = %temp | ||
</p></ | </p></ol> | ||
{{Template:Stringlist:OverlayImageItem footer}} | {{Template:Stringlist:OverlayImageItem footer}} | ||
==See also== | |||
Latest revision as of 22:09, 7 February 2011
Overlay part of Stringlist item with image item (Stringlist class)
This method is used to overlay a stringlist item with either of the following:
- The contents of a given image item.
- A specified value, but at the same offset as that of a given image item in its image.
OverlayImageItem is a subroutine that accepts three arguments, and returns no value.
Syntax
sl:OverlayImageItem( itemNum, imageItem, [value])
Syntax terms
| sl | A stringlist object. |
|---|---|
| itemNum | The number of the stringlist item that is to be updated. |
| imageItem | The image item that indicates the overlay offset and length and, if the third argument is not specified, the value to be overlayed in the stringlist item. |
| value | The value to be placed at the image item's offset in the stringlist item. If this optional argument is not specified, the contents of the image item specified by the itemNum argument are used to overlay the stringlist item. |
Usage notes
- All errors in OverlayImageItem result in request cancellation.
- OverlayImageItem does not change the length of a Stringlist item. If the overlay string does not completely overlay a Stringlist item, the characters before and after the overlayed string remain unchanged.
- If the start column plus the length of the image item is greater than the current length of the Stringlist item, the request is cancelled.
Examples
- OverlayImageItem is especially useful for Stringlists whose contents map to an image. In the following example, the Stringlist item associated with product code
983has its description overlayed with a new description:image product code is binary len 2 desc is string len 30 end image ... fr products %product:code = code %product:desc = desc %rc = %list:addImage('PRODUCT') end for ... %product:code = 983 %num = %list:findImageItem(%product:code) %product:desc = 'Insertion widget' %list:overlayImageItem(%num, %product:desc)
- If a value is specified in addition to the imageItem, processing is performed as if the value were assigned to the imageItem, before any overlaying is performed, and then the imageItem is restored to its original value. Any data type conversions required between the value and the imageIitem are performed before the overlay is performed.
That is, this method invocation:
%list:overlayImageItem(%num, %product:code, 543)
is identical to this:
%temp = %product:code %product:code = 543 %list:overlayImageItem(%num, %product:code) %product:code = %temp