Methods of the ICON_GRID Object

Directions assigned to method parameters:

(I)	Input
(O)	Output
(I/O)	Input and Output

Error codes that may be returned:

_ICG_ERR_SUCCESS	The function was executed successfully.
_ICG_ERR_ERROR	An unexpected error occurred.
_ICG_ERR_INVALID_PAGE_INDEX	Invalid page index.
_ICG_ERR_INVALID_PARAMETER	Invalid function parameter.
_ICG_ERR_INVALID_POSITION	Invalid icon position (either outside the grid or because there is already an icon in this position).
_ICG_ERR_INVALID_ICON_ID	Invalid icon ID (does not exist or a duplicate).

ADD_ICON

Adds an icon to the page.

Syntax
CALL_METHOD ObjectName ADD_ICON Index X Y Id Image Title ReturnCode
Parameters
NUM_BIN_4 Index (I)	Page index.
NUM_BIN_4 X (I)	Horizontal position of the icon, the value must be between 1 and the grid width.
NUM_BIN_4 Y (I)	Vertical position of the icon, the value must be between 1 and the grid height.
ALPHA(250) Id (I/O)	Icon ID. The value will be returned in the ICON_ID property on ClickIcon and DoubleClickIcon events. If the value is not provided, a unique identifier will be generated and returned as an output.
IMAGE Image (I)	Icon image.
ALPHA(250) Title (I)	Icon title.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

ADD_PAGE

Adds a page.

Syntax
CALL_METHOD ObjectName ADD_PAGE Index Title ReturnCode
Parameters
NUM_BIN_4 Index (I/O)	Page index or -1 to add to the end of the list. If -1, the index is returned.
ALPHA(250) Title (I)	Page title (optional).
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

ALIGN_ICONS

Aligns the icons on the selected page, horizontally or vertically, sorting them by name as an option.

Syntax
CALL_METHOD ObjectName ALIGN_ICONS Page Vertical Sort ReturnCode
Parameters
NUM_BIN_4 P (I)	Page number.
BOOL Vertical (I)	If *TRUE, the icons are aligned vertically (columns filled first), otherwise they are aligned horizontally (lines filled first).
BOOL Sort (I)	If *TRUE, the icons are sorted by name.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

DD_CANCEL_DATA

Erases any data stored in the object that could have been used for a drag and drop operation.

This method concerns the data previously created by the DD_WRITE_DATA method.

Syntax
CALL_METHOD ObjectName DD_CANCEL_DATA ReturnCode
Parameters
NUM_BIN_4 ReturnCode (O)	Return code for the operation. Possible values: _ERR_OK : Method run successfully.
Conditions for use	None.

DD_DATA_AVAILABLE

This method specifies if data in a specified format is available among the data concerned by the drag-and-drop operation in progress. The format can either be one predefined in Windows or one defined by the developer.

Syntax

CALL_METHOD ObjectName DD_DATA_AVAILABLE Format Availability ReturnCode

Parameters

ALPHA(50) Format (I)

Name of the data format to be sought.

Possible values:

_CF_TEXT	Format for text data items in the ANSI format.
_CF_OEMTEXT	Format for text data items in the OEM format.
_CF_UNICODETEXT	Format for text data items in the UNICODE format.
_CF_DIB	Format for DIB (Device Independent Bitmap) data items.
_CF_HDROP	Format for file and/or folder list data (format used particularly during a drag-and-drop action initiated from Windows explorer).
Any string not starting with "CF_" for a format defined by the developer.

BOOL Availability (O)

This value is set to *TRUE if any data in the requested format is available.

NUM_BIN_4 ReturnCode (O)

Return code for the operation.

Possible values:

_ERR_OK	Method run successfully.
_ERR_CTX_USE	Method used other than as part of an event enabled for it.
_ERR_INVALID_FORMAT	The specified format name does not match any data or is invalid.

Conditions for use

This method can only be used with the DD_EnterDrag, DD_DragOver and DD_Drop events.

DD_EXECUTE_DRAG

Initiates a drag and drop operation between a source object and a destination object using the data stored in the source object by the DD_WRITE_DATA method.

The relevant data can be either copied or moved to the destination object..

The set formed by this data is identified by a format name. The format can be either one predefined in Windows or one defined by the developer.

Note: Where a predefined format is used, only the first data item written by the DD_WRITE_DATA method is taken into consideration.

Syntax

CALL_METHOD ObjectName DD_EXECUTE_DRAG Format AllowedActions ActionDone ReturnCode

Parameters

ALPHA(50) Format (I)

Data format name.

Possible values:

_CF_TEXT	Format for text data items in the ANSI format.
_CF_OEMTEXT	Format for text data items in the OEM format.
_CF_UNICODETEXT	Format for text data items in the UNICODE format.
_CF_DIB	Format for DIB (Device Independent Bitmap) data items.
Any string that does not begin with "CF_" for a format defined by the developer, and which contains all the written data.

NUM_BIN_4 AllowedActions (I)

Actions permitted in the destination object.

Possible values:

_DD_ACTION_COPY	Data are copied to the destination object.
_DD_ACTION_MOVE	Data can be moved to the destination object (and deleted from the source object).
_DD_ACTION_COPY_MOVE	Combination of the above two actions.

NUM_BIN_4 ActionDone (O)

Action performed in the destination object.

Possible values:

_DD_ACTION_NONE	The use released the mouse button over an object that does not accept the data, or cancelled the operation by pressing Escape.
_DD_ACTION_COPY	The data must be copied to the destination object.
_DD_ACTION_MOVE	The data must be moved to the destination object (and deleted from the source object).

NUM_BIN_4 ReturnCode (O)

Return code for the operation.

Possible values:

_ERR_OK	Method run successfully.
_ERR_INVALID_PARAM	One or more parameters have invalid values.
_ERR_CTX_USE	Method used other than as part of an event enabled for it.
_ERR_NO_DATA	No data was stored for a drag and drop operation.
_ERR_INVALID_FORMAT	The specified format name is invalid.

Conditions for use

This method must be used with the DD_BeginDrag event.

DD_READ_DATA

Reads the data transferred as part of the current drag and drop operation. This data is in fact a copy of the data written in the source object by the DD_WRITE_DATA method.

It must be used in a loop to run through all the data for a given Adelia type.

All the data for a given type are read when the number of data items read is less than the number of data items to be read.

Notes:

- Calling this method with an Adelia array containing x elements has the same effect as calling the method x times with an Adelia variable.
- If the DD_WRITE_DATA method has been used to write x records each containing two ALPHA variables, the DD_READ_DATA method must be run twice, with the indexes (2x – 1) and 2x, in order to retrieve the strings in the nth record, or once with the index (2x-1) and an array capable of receiving two data items.
- No distinction is made between packed and extended numerical variables, however long they are and however many decimal places they have. The values of numerical or extended variables may be truncated when they are read. With strings, the read operation will fail if the Adelia variable is too small to contain the string being read.

Syntax

CALL_METHOD ObjectName DD_WRITE_DATA Format AdeliaVar Index DataNumber ReturnCode

Parameters

ALPHA(50) Format (I)

Name of the data format to be sought.

Possible types for the AdeliaVar parameter (I)

ALPHA, DATE, TIME, NUM_E, NUM_P, NUM_BIN_2, NUM_BIN_4, BOOL, TIMESTAMP, IMAGE

Variable or array filled with data.

NUM_BIN_4 Index (I)

Index of the data to be read for a given type.

The first column takes the index 1.

NUM_BIN_4 DataNumber (I/O)

Number of data items to be added.

With variables, this parameter must be 1, and with arrays, less than or equal to the number of elements in the array.

Once the method has been called, it contains the number of data items written.

NUM_BIN_4 ReturnCode (O)

Return code for the operation.

Possible values:

_ERR_OK	Method run successfully.
_ERR_CTX_USE	Method used other than as part of an event enabled for it.
_ERR_INVALID_TYPE	A variable used in the method is not a suitable Adelia type.
_ERR_INVALID_PARAM	One or more parameters have invalid values.
_ERR_STRING_LEN	The data to be read includes a character string longer than the Adelia variable.
_ERR_VAR_NOT_AVAIL	The data to be read does not contain data of the specified Adelia type.
_ERR_INVALID_FORMAT	The specified format name does not match any data or is invalid.

Conditions for use

This method can only be used with the DD_EnterDrag, DD_DragOver and DD_Drop events.

DD_WRITE_DATA

This methods adds data (i.e. the contents of the Adelia variables) to the data to be transferred by a drag and drop operation. This data is stored in the object until the end of the drag and drop operation, and are then deleted automatically.

Notes:

Calling this method with an array containing x elements has the same effect as calling the method x times with a variable containing the individual array elements.
No distinction is made between the extended and packed numerical data types.

Syntax

CALL_METHOD ObjectName DD_WRITE_DATA AdeliaVar DataNumber ReturnCode

Parameters

Possible types for the AdeliaVar parameter (I):

ALPHA, DATE, TIME, NUM_E, NUM_P, NUM_BIN_2, NUM_BIN_4, BOOL, TIMESTAMP, IMAGE

Variable or array containing the data.

NUM_BIN_4 DataNumber (I/O)

Number of data items to be added.

With variables, this parameter must be 1, and with arrays, less than or equal to the number of elements in the array.

Once the method has been called, it contains the number of data items written.

NUM_BIN_4 ReturnCode (O)

Return code for the operation.

Possible values:

_ERR_OK	Method run successfully.
_ERR_INVALID_TYPE	A variable used in the method is not a suitable Adelia type.
_ERR_INVALID_PARAM	One or more parameters have invalid values.

Conditions for use

None.

DELETE_ICON

Deletes an icon.

Syntax
CALL_METHOD ObjectName DELETE_ICON Id ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

DELETE_PAGE

Deletes a page.

Syntax
CALL_METHOD ObjectName DELETE_PAGE Index ReturnCode
Parameters
NUM_BIN_4 Index (I)	Index of the page to delete.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

GET_ICON_DATA

Modifies the data associated with an icon.

Syntax
CALL_METHOD ObjectName GET_ICON_DATA Id Data ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
ALPHA(4096) Data (O)	Data associated with the icon.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

GET_ICON_IMAGE

Gets an icon image.

Syntax
CALL_METHOD ObjectName GET_ICON_IMAGE Id Icon ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
IMAGE Icon (O)	Image icon.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

GET_ICON_NOTIF_COLORS

Gets icon notification text colors.

Syntax
CALL_METHOD ObjectName GET_ICON_NOTIF_COLORS Id TextColor BackgroundColor ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
NUM_BIN_4 TextColor (O)	Notification text color.
NUM_BIN_4 BackgroundColor (O)	Notification text background color.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

GET_ICON_NOTIF_TEXT

Gets an icon notification text.

Syntax
CALL_METHOD ObjectName GET_ICON_NOTIF_TEXT Id NotifText ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
ALPHA(250) NotifText (O)	Icon notification text.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

GET_ICON_POSITION

Gets the position of an icon on the page.

Syntax
CALL_METHOD ObjectName GET_ICON_POSITION Id X Y ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
NUM_BIN_4 X (O)	Horizontal position of the icon.
NUM_BIN_4 Y (O)	Vertical position of the icon.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

GET_ICON_TEXT

Gets an icon's text.

Syntax
CALL_METHOD ObjectName GET_ICON_TEXT Id Text ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
ALPHA(250) Text (O)	Icon text.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

ICON_AT

Gets the icon ID at the selected position, or *BLANK if the position is empty.

Syntax
CALL_METHOD ObjectName ICON_AT Page X Y Id ReturnCode
Parameters
NUM_BIN_4 P (I)	Page number.
NUM_BIN_4 X (I)	Horizontal position of the icon, the value must be between 1 and the grid width.
NUM_BIN_4 Y (I)	Vertical position of the icon, the value must be between 1 and the grid height.
ALPHA(250) Id (O)	Icon ID.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

SET_ICON_DATA

Modifies the data associated with an icon.

Syntax
CALL_METHOD ObjectName SET_ICON_DATA Id Data ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
ALPHA(4096) Data (I)	Data associated with the icon.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

SET_ICON_IMAGE

Modifies an icon image.

Syntax
CALL_METHOD ObjectName SET_ICON_IMAGE Id Icon ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
IMAGE Icon (I)	Icon image.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

SET_ICON_NOTIF_COLORS

Modifies an icon notification text colors.

Syntax
CALL_METHOD ObjectName SET_ICON_NOTIF_COLORS Id TextColor BackgroundColor ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
NUM_BIN_4 TextColor (I)	Notification text color.
NUM_BIN_4 BackgroundColor (I)	Notification text background color.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

SET_ICON_NOTIF_TEXT

Modifies an icon notification text.

Syntax
CALL_METHOD ObjectName SET_ICON_NOTIF_TEXT Id NotifText ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
ALPHA(250) NotifText (I)	Icon notification text.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

SET_ICON_POSITION

Changes the position of an icon on the page.

Syntax
CALL_METHOD ObjectName SET_ICON_POSITION Id X Y ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
NUM_BIN_4 X (I)	Horizontal position of the icon, the value must be between 1 and the grid width.
NUM_BIN_4 Y (I)	Vertical position of the icon, the value must be between 1 and the grid height.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.

SET_ICON_TEXT

Modifies an icon text.

Syntax
CALL_METHOD ObjectName SET_ICON_TEXT Id Text ReturnCode
Parameters
ALPHA(250) Id (I)	Icon ID.
ALPHA(250) Text (I)	Icon text.
NUM_BIN_4 ReturnCode (O)	Return code for the operation.
Conditions for use	None.