Standard Group Methods

A group is a special type of object that contains a number of related objects. Some groups are static, while others change dynamically at runtime, such as the $iwindows group which contains all the window instances currently open. The group methods perform some action on the group as a whole, or return some information about the group or an individual object in the group.

The methods listed here are standard item group methods. Items which have a standard item group method only include the method name in their method table - please use the entry here to read about the method.

Method Description
$addafter $addafter(rItem,<params>) inserts a new item into the group immediately after rItem and returns an item reference to it; <params> are the parameters for the $add() method of the group
$addbefore $addbefore(rItem,<params>) inserts a new item into the group immediately before rItem and returns an item reference to it; <params> are the parameters for the $add() method of the group
$appendlist $appendlist(lList,$ref.$att1,$ref.$att2,...) appends a list representing the item group to the specified list
$count $count() Returns the count of items in the item group
For example, Do $components.$count() Returns lXcompNum, returns the number of external components currently available in the Omnis environment.
$findident $findident(iIdent) Returns an item reference to the item in the group with the unique numeric identifier iIdent; $findident() returns NULL if such an item does not exist
$findname $findname(cName) Returns an item reference to a named item from within the group; if an item with the name cName does not exist, $findname() returns NULL
$first $first() Returns an item reference to the first item in the group; if the group is empty, $first() returns NULL
For example, Do $iwindows.$first() Returns lTopWin, returns a reference to the top open user window.
$insertlist $insertlist(lList,iLine,$ref.$att1,$ref.$att2,...) inserts a list representing the item group into the specified list at the specified line
$makelist $makelist($ref.$att1,$ref.$att2,...) generates a list from the item group
For example, Do $components.$makelist($ref.$name) Returns lXcompList builds a list of external components currently available in your system, or Do $iwindows.$makelist($ref.name) Returns lWinList builds a list of window instances currently open in the order that they appear on the screen.
$next $next(rItem) Returns the next item in the item group (the item after rItem). If rItem is the last item,$next() returns NULL
$sendall $sendall(message [,condition, bIgnoreUnrecognizedCustomAttribute=kFalse]) sends a message to all the items in the group

For example, $cwind.$objs.$sendall($ref.$visible.$assign(kFalse)) hides all the fields on the current window; $sendall() returns the number of objects which received the message; the return values of the messages sent to each individual object are discarded.

You can optionally specify a condition which determines the objects in the group which will be sent the message. The condition is a calculation which evaluates to non-zero for items which are to be sent the message, for example, $cwind.$objs.$sendall($ref.$visible.$assign(kFalse), $ref.$order<=5) hides all the fields on the current window which have a $order property less than or equal to five.

You can also specify an optional third argument, which disables the "unrecognized custom attribute" error. This allows you to use the $reportnotationerrors library preference with a value of kTrue, and at the same time use $sendall to call optional custom attributes in a group, without generating a notation error. To disable the "unrecognized custom attribute" error, pass kTrue as the third argument. Note that in order to pass this third argument, you must pass a condition argument; you can use kTrue for the condition argument if you wish the message to be sent to all objects in the group.

When using $sendall, you can normally use $ref to refer to the group member receiving the message. Alternatively, you can use $sendallref, which is an item reference to the item currently receiving the message sent with $sendall (note that $sendallref is not supported in client methods). Consider the case where a parameter passed to the message is evaluated by calling another notation method, or a function implemented in an external component. In this case, if you use $ref in the parameters passed to this other method or function, it will actually refer to the item involved in making the call to evaluate the parameter. This is where $sendallref would be used, if you wish to pass some property of the group member receiving the message to the other method or function.

For example:
Do $cinst.$bobjs.$sendall( $ref.$text.$assign( StringTable.$gettext( $cclass.$bobjs.[$sendallref.$ident].$text)))

The example uses the text stored in the class as the row id in the string table, and assigns the text stored in the string table to the background object.

In the example, $sendallref.$ident returns the ident of the background object receiving the message. If you were to use $ref.$ident, then $ref refers to the custom attribute representing the external component function, and the call to $sendall will not have the desired effect.