[Molby Document Home] [Contents]

Class: | DialogItem
Parent: | Object

### Description

#### Overview

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.

#### Item types

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).

- text: A static text.
- textfield: A text box that accepts user input.
- textview: Similar to the text field, but accepts multiline inputs and has a vertical scroll bar.
- view: An empty placeholder.
- line: A separator line. May be vertical or horizontal.
- button: A standard push button with a short text inside.
- popup: A button with a popup menu.
- checkbox: A checkbox with a text.
- radio: A radio button. This is a single button, and a radio group can be defined by Dialog#radio_group.

#### Item attributes

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.

#### Actions

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.

### Public Instance methods

append_string(string) → self

Only usable for `:textview` items. Append the given string at the end.

attr(attribute_name) → value
self[attribute_name] → value

Get the attribute value. The attribute name should be given as a symbol.

set_attr(attribute_name, value) → value
self[attribute_name] = value → value

Set the attribute value. The attribute name should be given as a symbol.