GETITEM

7.8.5, PLBCMP GUI Only

The GETITEM instruction obtains the name or value of an object item. It uses one of the following formats:

(1)	[label]	GETITEM	{object},{item},{data}
(2)	[label]	GETITEM	{dialog},{dialog-no},{item},{data}

Where:

label

Optional. A Program Execution Label.

object

Required. A previously defined and created object or pointer to an object from which the name or value is retrieved.

item

Required. A Numeric Variable, numeric literal, or Expression that indicates the item within the object from which to retrieve the name or value.

data

Required. A previously defined Character String Variable or Numeric Variable that receives the name or value of the object or item.

dialog

Required. A previously defined and created DIALOG object variable or pointer to a DIALOG object containing an object from which the name or value is retrieved.

dialog-no

Required. A Numeric Variable, numeric literal, or Expression that indicates the item within the dialog from which to retrieve the name or value.

Flags Affected: EOS, OVER, ZERO

Note the following:

If {data} is a character variable, the following action occurs depending on the type of object and the value of {data}. If the conditions are not met, {data} is cleared (blank filled, FP = LP = 0).

Object	Action
BUTTON, CHECKBOX, GROUPBOX or RADIO	If {item} is zero, the Title is returned in {data}.
CHECKGRP or RADIOGRP	If {item} = zero and the group has a title, the title is returned in {data}. If 1 <= {item} <= number of objects in the group, the Name at the {item} object of the group is returned in {data}.
COMBOBOX or POPUPMENU	If {item} = zero and the object has a title, the title is returned in {data}. If 1 <= {item} <= number of entries in the object, the string at the {item} position in the object is returned in {data}. For a COMBOBOX, if {item} is a negative one (-1), the current selection is returned. (9.3A) If no item is selected, {data} will be null.
DATALIST, FLOATMENU, or SUBMENU	If 1 <= {item} <= number of entries in the object, the string at the {item} position in the object is returned in {data}.
EDITTEXT, EDITNUMBER	If {item} is zero, the entire text is returned in {data}. If {item} is 1, the selected text is returned in {data}.
MENU	If {item} is zero, the object's title is returned in {data}. If 1 <= {item} <= number of items in the object, the string at the {item} position in the object is returned in {data}.
STATTEXT or LABELTEXT	If {item} is zero, the entire text is returned in {data}.
TABCONTROL	If one <= {item} <= number of tabs on the object, the label at the {item} tab on the object is returned in {data}.

If {data} is a numeric variable the following action occurs depending on the type of object:

Object	Action
BUTTON	A value of zero is always returned.
CHECKBOX, RADIO	The state of {item} is stored in {data}. A zero is returned if the object is clear. Otherwise, a one is returned.
CHECKGRP	The value of {item} is stored in {data}.
COLOR	When the {item} value of zero is used, the returned value may be either the twenty-four bit RGB value or a thirty-two bit index value of a system color. The red component value is stored in {data} if {item} is one. The green component value is stored in {data} if {item} is two. The blue component value is stored in {data} if {item} is three. When {item} is a four, the RGB value is retrieved. If the value is a Windows system color, the RGB value for the system color is returned.
DATALIST	When {item} is zero, the number of the first entry selected in the DATALIST is stored in {data}. When {item} is one, the total number of entries in the DATALIST is stored in {data}. When {item} is two, the number of entries currently selected in the DATALIST is stored in {data}. If {item} is three and MULTISELECT was specified, the next entry selected in the DATALIST is stored in {data}. If {item} is four, {data} contains the number of a list entry that is checked as being selected or not. If the given list entry is currently selected, the ZERO flag is set. If the given list item is invalid, the OVER flag is set.
DIALOG	The {dialog-no} operand contains the dialog item number. The action performed on the dialog item follows the same rules as an object variable of the same type.
EDITTEXT	When {item} is zero, the current size of all the text in the object is stored in {data}. When {item} is one, the starting position of the selected text is stored in {data}. When {item} is two, the ending position of the selected text is stored in {data}. If no text is selected, an {item} value of one or two will return the current cursor position.
HSCROLLBAR, SLIDER or VSCROLLBAR	When {item} is zero, the current position of the slide button is returned. An {item} value of one returns the minimum value. An {item} value of two returns the maximum value. When {item} is three, the page shift value is returned. When a value of four is used with a SLIDER under the web server, the 'step' option valuie is returned. The jQuery Slider 'step' option is described as follows: "Determines the size or amount of each interval or step the slider takes between the min and max. The full specified value range of the slider (max - min) should be evenly divisible by the step." Note: The behaviors for the jQuery Slider 'step' prevents simulation of a Windows Slider object SHIFT property behaviors.
MOVIE	{item} must be one. The current status is returned in {data} and may be one of the following: Zero means the movie is stopped at the beginning. One means the movie is running Two means the movie is currently paused.
COMBOBOX or POPUPMENU	The value of the currently selected item is stored in {data}. If {item} is invalid, a value of zero is returned.
RADIOGRP	The value of the item specified by {item} is stored in {data}. If {item} is zero, the number of the item currently on is stored in {data}.
TIMER	The timeout value is stored in {data}. The value is in tenths of a second.
PROGRESS	When {item} is zero, the percentage value of the progress is stored in {data}.
TABCONTROL	When {item} is zero, the currently selected tab number (one-based) is stored in {data}.

For character variable output, an item number of negative one (-1) returns the current selection.
If {item} is not valid and if {data} is a character variable, {data} is cleared.
If {item} is not valid and {data} is a numeric variable, {data} is set to zero.
If {data} is a character variable and the character variable is too small to receive all of the information available, the EOS flag is set.
If {data} is a numeric variable and the variable is too small to contain the item's value, the OVER flag is set.
If {data} is a numeric variable and the value stored is zero (0), the ZERO flag is set.
An object must be CREATEd before using GETITEM. If this is not done, a runtime error of O105 is generated.
If insufficient memory is available to perform the operation, a runtime error of O106 is generated.
International users should refer to the PLB_LOCALE runtime keyword for additional information.