| Class: | DialogItem |
| Parent: | Object |
The class DialogItem represents an item in a Dialog. There are two default dialog items ("OK" and "Cancel" buttons); other items are created by Dialog#item.
A DialogItem object belongs to one of the following types. The type should be designated when an item is created (as the first argument to Dialog#item).
Dialog items have various attributes. Some attributes are common to all items, and others are specific to some item types. Available attributes are listed below:
| Name | Item Type | Description |
|---|---|---|
| action | textfield, textview, button, popup, checkbox, radio | The action procedure. See Actions for how this attribute is used. |
| dialog | all | The Dialog object which this item belongs to. |
| editable | textfield, textview | A boolean value indicating whether the text in this item is editable. |
| enabled | all except line | A boolean value indicating whether the item is enabled. |
| hidden | all | A boolean value indicating whether the item is hidden. |
| index | all | The non-negative integer to identify the item in the parent dialog. The indices 0 and 1 always correspond to the "OK" and "Cancel" buttons (either or both of which may be hidden). |
| range | textfield | An array of two numerics, which indicates that the value must be a numeric within the specified range. |
| subitems | popup | An array of strings representing the subitems included in this item. |
| tag | all | The identification tag. The value must not be an integer. |
| title | text, button, checkbox, radio | The title string. |
| type | all | The item type. The value is a symbol like :button. |
| value | textfield, textview, popup, checkbox, radio | The value of the control. For the textfield and textview, the value is a string. For the popup, the value is an integer indicating the selected item (0-based). For the checkbox and radio, the value is 0/1 for off/on state. |
| x, y, width, height, origin, size, frame | all | The item position and size. The values are represented in the local coordinates of the dialog (or the superview if the item is a child of another view) in pixel unit. The frame is represented as [origin_x, origin_y, size_width, size_height]. The origin of the coordinate system is the top-left position of the dialog (or the superview). |
| font | textfield, textview | [size, family, style, weight]. Size is the font size in points. Other elements are symbols. Family is one of :default, :roman (a serif font), :swiss (a sans-serif font), fixed (a fixed-pitch font). Style is one of :normal, :slanted, :italic. Weight is one of :medium, :bold, :light.On setting, these items can appear in an arbitrary order. If any attribute is missing, then the missing attribute will not change. |
If the "action" attribute is defined, it is called when the dialog items are clicked and/or their values are changed. If the attribute value is a symbol, it is considered as the method name of the parent Dialog. Otherwise, the value must be a callable object, most likely a Proc object. In either case, the DialogItem object is passed as the single argument.
If the Dialog is to be closed as a result of the action procedure, Dialog#end_modal(n) is used. This method cause termination of the modal session started by Dialog#run, and the argument n will be available in the return value from Dialog#run, which is a hash containing (among other things) a :status=>n entry.