BindImage (Stringlist subroutine): Difference between revisions
Jump to navigation
Jump to search
m (moved BindImage (Stringlist function) to BindImage (Stringlist subroutine): It's not a function) |
No edit summary |
||
| (27 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:BindImage subtitle}} | {{Template:Stringlist:BindImage subtitle}} | ||
This method associates or binds an image to a Stringlist. BindImage is a subroutine that accepts one argument, an image name, and does not return anything | This method associates or binds an image to a <var>Stringlist</var>. <var>BindImage</var> is a subroutine that accepts one argument, an image name, and does not return anything. | ||
==Syntax== | ==Syntax== | ||
{{Template:Stringlist:BindImage syntax}} | {{Template:Stringlist:BindImage syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
< | <table class="syntaxTable"> | ||
< | <tr><th>sl</th> | ||
This argument is case sensitive. That is, in the likely event the User Language was written in mixed case, with automatic upper-casing in effect, the image name should be in uppercase. | <td>A <var>Stringlist</var> object.</td></tr> | ||
</ | <tr><th>imageName</th> | ||
<td>A string that contains the name of an image. This argument is case sensitive. That is, in the likely event the <var class="product">User Language</var> was written in mixed case, with automatic upper-casing in effect, the image name should be in uppercase.</td></tr> | |||
</table> | |||
==Usage notes== | ==Usage notes== | ||
<ul><li>All errors in BindImage result in request cancellation. | <ul><li>All errors in <var>BindImage</var> result in request cancellation. | ||
<li>These methods can use the association between an image and a Stringlist: | <li>These methods can use the association between an image and a <var>Stringlist</var>: | ||
<ul> | <ul> | ||
<li>[[AddImage (Stringlist function)]] | <li><var>[[AddImage (Stringlist function)|AddImage]]</var> | ||
<li>[[GetImage (Stringlist subroutine)]] | <li><var>[[GetImage (Stringlist subroutine)|GetImage]]</var> | ||
<li>[[InsertImage (Stringlist function)]] | <li><var>[[InsertImage (Stringlist function)|InsertImage]]</var> | ||
<li>[[ReplaceImage (Stringlist function)]] | <li><var>[[ReplaceImage (Stringlist function)|ReplaceImage]]</var> | ||
<li>[[Sort (Stringlist subroutine)]] | <li><var>[[Sort (Stringlist subroutine)|Sort]]</var> | ||
<li>[[SortNew (Stringlist function)]] | <li><var>[[SortNew (Stringlist function)|SortNew]]</var> | ||
</ul> | </ul> | ||
</li> | |||
The association between an image and a Stringlist is generally used when all Stringlist items have the same layout as the image. Methods that create a new Stringlist usually propagate the image binding from the method Stringlist to the output Stringlist.</ul> | <li>The association between an image and a <var>Stringlist</var> is generally used when all <var>Stringlist</var> items have the same layout as the image. Methods that create a new <var>Stringlist</var> usually propagate the image binding from the method <var>Stringlist</var> to the output <var>Stringlist</var>. | ||
</li> | |||
<li>A <var>BindImage</var> done inside a subroutine or method is not undone/popped when the subroutine or method returns, so care must be taken when adding a <var>BindImage</var> against a subroutine/method parameter as the subroutine/method caller must restore its own <var>BindImage</var> in such a case.</li> | |||
</ul> | |||
==Examples== | ==Examples== | ||
<ol><li>Once an image is bound to a Stringlist, methods that operate on an image can omit the image name parameter. This is not only convenient from a coding perspective, it is more efficient | <ol><li>Once an image is bound to a <var>Stringlist</var>, methods that operate on an image can omit the image name parameter. This is not only convenient from a coding perspective, it is more efficient — no image name lookup needs to be done in NTBL. | ||
The following example illustrates such a use of BindImage: | The following example illustrates such a use of <var>BindImage</var>: | ||
< | <p class="code">%list is object stringList | ||
%list is object stringList | |||
... | ... | ||
image customer | image customer | ||
id is string len 8 | id is string len 8 | ||
lname is string len 32 | lname is string len 32 | ||
end image | end image | ||
... | ... | ||
| Line 44: | Line 46: | ||
... | ... | ||
for each record in %recset | for each record in %recset | ||
%customer:id = id | %customer:id = id | ||
%customer:lname = lname | %customer:lname = lname | ||
%list:addImage | %list:addImage | ||
end for | end for | ||
</ | </p> | ||
<li>BindImage could also enable the Sort and SortNew methods to use the names of image items in the sort criteria rather than column numbers, for example, where a Stringlist has a layout described by an image: | <li><var>BindImage</var> could also enable the <var>[[Sort (Stringlist subroutine)|Sort]]</var> and <var>[[SortNew (Stringlist function)|SortNew]]</var> methods to use the names of image items in the sort criteria rather than column numbers, for example, where a <var>Stringlist</var> has a layout described by an image: | ||
< | <p class="code">%list is object stringList | ||
%list is object stringList | |||
... | ... | ||
image customer | image customer | ||
id is string len 8 | id is string len 8 | ||
lname is string len 32 | lname is string len 32 | ||
end image | end image | ||
... | ... | ||
| Line 64: | Line 65: | ||
... | ... | ||
%list:sort('LNAME,A ID,D') | %list:sort('LNAME,A ID,D') | ||
</ | </p> | ||
<li>It is probably quite common that one and only one image is bound to a Stringlist in a request. In such cases, the BindImage functionality can be achieved with the New | <li>It is probably quite common that one and only one image is bound to a <var>Stringlist</var> in a request. In such cases, the <var>BindImage</var> functionality can be achieved with the <var>[[New (Stringlist constructor)|New]]</var> method by using an image name argument on the method invocation: | ||
< | <p class="code">%list is object stringList | ||
%list is object stringList | |||
... | ... | ||
image customer | image customer | ||
id is string len 8 | id is string len 8 | ||
lname is string len 32 | lname is string len 32 | ||
end image | end image | ||
... | ... | ||
%list = new('CUSTOMER') | %list = new('CUSTOMER') | ||
</ | </p></ol> | ||
</ol> | |||
==See also== | |||
{{Template:Stringlist:BindImage footer}} | |||
Latest revision as of 13:44, 19 January 2022
Associate a Stringlist with an image (Stringlist class)
This method associates or binds an image to a Stringlist. BindImage is a subroutine that accepts one argument, an image name, and does not return anything.
Syntax
sl:BindImage( imageName)
Syntax terms
| sl | A Stringlist object. |
|---|---|
| imageName | A string that contains the name of an image. This argument is case sensitive. That is, in the likely event the User Language was written in mixed case, with automatic upper-casing in effect, the image name should be in uppercase. |
Usage notes
- All errors in BindImage result in request cancellation.
- These methods can use the association between an image and a Stringlist:
- The association between an image and a Stringlist is generally used when all Stringlist items have the same layout as the image. Methods that create a new Stringlist usually propagate the image binding from the method Stringlist to the output Stringlist.
- A BindImage done inside a subroutine or method is not undone/popped when the subroutine or method returns, so care must be taken when adding a BindImage against a subroutine/method parameter as the subroutine/method caller must restore its own BindImage in such a case.
Examples
- Once an image is bound to a Stringlist, methods that operate on an image can omit the image name parameter. This is not only convenient from a coding perspective, it is more efficient — no image name lookup needs to be done in NTBL.
The following example illustrates such a use of BindImage:
%list is object stringList ... image customer id is string len 8 lname is string len 32 end image ... %list = new %list:bindImage('CUSTOMER') ... for each record in %recset %customer:id = id %customer:lname = lname %list:addImage end for
- BindImage could also enable the Sort and SortNew methods to use the names of image items in the sort criteria rather than column numbers, for example, where a Stringlist has a layout described by an image:
%list is object stringList ... image customer id is string len 8 lname is string len 32 end image ... %list = new %list:bindImage('CUSTOMER') ... %list:sort('LNAME,A ID,D')
- It is probably quite common that one and only one image is bound to a Stringlist in a request. In such cases, the BindImage functionality can be achieved with the New method by using an image name argument on the method invocation:
%list is object stringList ... image customer id is string len 8 lname is string len 32 end image ... %list = new('CUSTOMER')