dlgitem_add_callback
dlgitem_add_callback (windowdlgitem, callback[, "PREPEND"])
Appends callback to the list of callback functions to be called when the value of dlgitem within window changes. Functions are called in the order that they appear in the list. If successful, the function returns 1 (one).
dlgitem_add_callback has the following parameters:
• window — The window identifier. If window is invalid, $ERROR is set and 0 is returned.
• dlgitem — The value of the control's id attribute. If dlgitem does not exist within window, $ERROR is set and 0 is returned.
• callback — Specifies the actual callback to add. If callback is already on the callback list for the dialog item, the list is reordered to place the callback in the new position. The callback is not added to the list a second time.
• "PREPEND" — Optional. When specified, the callback is added to the beginning of the list of callback functions.
Three different events are associated with dialog items:
• ITEM_CHANGED
• ITEM_FOCUSED
• ITEM_UNFOCUSED
The callback is called if any of these events occurs. For example, clicking on a button may generate two callbacks, once when the button takes focus, and again when clicked (that is, changed). Therefore, it is a good practice for your callback function to execute only if the desired event has occurred. Otherwise, it should simply return.
Example:
$ret = dlgitem_add_callback($win, "TextField",
main::TextFieldCallback);
Callback prototype:
callback(windowId, dialogItem, eventType, eventSubType, detail)
Arguments:
• windowId — The identifier of the window that contains this dialog item.
• dialogItem — The value of the dialog item's ID attribute.
• eventType — One of the following three types.
◦ "ITEM_CHANGED"
◦ "ITEM_FOCUSED"
◦ "ITEM_UNFOCUSED"
• eventSubType — Applies only when eventType is "ITEM_CHANGED". The following controls have the following eventSubType values:
◦ combobox control
▪ "SCROLL" — Dispatched when the text field in the combobox is changed.
▪ "SELECT"
▪ "ACCEPT" — Dispatched when the ENTER key is pressed. The event is sent out for simple and dropdown comboboxes. It is not sent out for the dropdownlist comboboxes.
▪ "OPEN" — (Dropdown combobox only.)
▪ "CLOSE" — (Dropdown combobox only.)
◦ listbox control
▪ "DOUBLE_CLICK"
◦ toolbar list dropdown control
▪ "POPULATE" — Dispatched when the list dropdown is open.
▪ "SELECT"
◦ tree control
▪ "DOUBLE_CLICK"
• detail — Applies only when eventType is "ITEM_CHANGED" and eventSubType is "CLOSED". If the combobox dropdown is closed using the ESC key, the value of detail is CANCEL. If the combobox dropdown is closed by other means, detail is an empty string.