[Molby Document Home] [Contents]

Class: | Dialog
Parent: | Object

### Description

#### Overview

The class Dialog is a utility class, which is independent from the rest of the Ruby functionality of Molby. It provides a simple modal dialog on the screen, and let the user to enter information by use of controls, such as text fields, checkboxes, popup menus, etc. The class also provides system-standard open/save dialogs as class methods Dialog#open_panel and Dialog#save_panel.

#### How Dialog works

The steps for using Dialog are as follows:

- Create a Dialog object by Dialog#new. This accepts up to three arguments; the title of the dialog, the title of the "OK" button (optional), the title of the "Cancel" button (optional).
- Create dialog items by Dialog#item. If necessary, use Dialog#layout to place the items in a table-like arrangement.
- Call Dialog#run. The dialog runs modally, and returns a hash containing the values for the "tagged" items. The returned hash also contains an entry with the key `:status` and the value 0 (OK) or 1 (Cancel).

Dialog also implements run as a class method, which performs these three steps in turn. A typical use of Dialog#run is shown below.

    hash = Dialog.run("Sample Dialog", "OK", "Cancel") {
      layout(2,
        item(:text, :title=>"Text:"),
        item(:textfield, :width=>80, :tag=>"text"))
    }
    p hash  #  { "text"=>"Input text", :status=>0 (for OK), 1 (for Cancel) }

#### Dialog items

A dialog item is an object of class DialogItem. There are two default dialog items ("OK" and "Cancel" buttons). Other items can be created by Dialog#item. The already existing items can be retrived by Dialog#item_at_index and Dialog#item_with_tag.

#### Dialog and item actions

Some dialog items perform actions when they are clicked and/or their values are changed. Such behavior is implemented by the DialogItem attribute `:action`. If the dialog is to be closed from the action, Dialog#end_modal can be used.

    Dialog.run("Action Test", nil, nil) {  #  A dialog with only one button "Close"
      layout(1,
        item(:button, :title=>"Close", :action=>proc { |it| end_modal(0) }))
    }

### Public Class methods

new(title1, title2 = "OK", title3 = "Cancel") { ... }

Create a new dialog. Title1, title2, and title3 are the titles for the dialog, the first button, and the second button, respectively. If nil is explicitly given as title2 and/or title3, the corresponding buttons are hidden.

If a block is given, it is executed in the context of the created Dialog object (i.e. the Dialog object becomes self in the block).

open_panel(message = nil, directory = nil, wildcard = nil, for_directories = false, multiple_selection = false) → String

Display the "open" dialog and returns the fullpath filename.

run(title1, title2 = "OK", title3 = "Cancel") { ... } → Hash

Create a new dialog by Dialog#new, and call Dialog#run (instance method).

save_panel(message = nil, directory = nil, default_filename = nil, wildcard = nil) → String

Display the "save as" dialog and returns the fullpath filename.

### Public Instance methods

attr(tag, key) → value
attr(index, key) → value

Look for the dialog item with the tag or at the index, and get the item attribute designated by the key.

each_item { |it| ...}

Iterate the given block with each DialogItem as the argument.

end_modal(n)

End the modal session (started by Dialog#run). The argument n will be available in the hash returned from Dialog#run, as the value for the key `:status`.

item(type, hash) → DialogItem

Create a dialog item. Type is a symbol representing the item type; for the list of available types, see the "Item types" section of the DialogItem document. Hash is the key/value pairs for the item attributes. Returns the created DialogItem object.

item_at_index(index) → DialogItem

Retrieve the index-th dialog item.

item_with_tag(tval) → DialogItem

Retrieve the dialog item which has the tag attribute tval. If such an item does not exist, nil is returned.

layout(columns, i11, ..., i1c, i21, ..., i2c, ..., ir1, ..., irc [, options]) → DialogItem

Layout items in a table. The first argument is the number of columns, and must be a positive integer. If the last argument is a hash, then it contains the layout options. The ixy arguments are DialogItem objects or the item indices. If nil or a negative integer is given, that slot is made blank. In this case, layout is done so that the left neighboring cell expands to fill the blank slot.

Returns the DialogItem object representing the container view encapsulating the given items.

nitems → Integer

Returns the number of items.

radio_group(i1, i2, ...)

Group radio buttons as a mutually exclusive group. The arguments represent the radio buttons, either as DialogItem objects, item indices, or item tags.

run → Hash

Run the modal session for this dialog. The method does not return until "OK" or "Cancel" button is pressed, or self.end_modal is called from one of the action methods of DialogItem.

The return value is a hash. On exit, all dialog items are scanned for the presence of the "tag" attribute, and if present the tag and the value of the dialog items are stored in the hash. In addition, the hash has an entry `:status=>val`, where val is 0 for "OK" and 1 for "Cancel" or, when self.end_modal is called, the argument passed to end_modal.

set_attr(index, hash) → DialogItem
set_attr(tag, hash) → DialogItem

Set the attributes of the dialog item designated by the index or the tag. The attribute names and values are given as a hash object.

set_value(tag, value) → value

Equivalent to set_attr(tag, :value=>value), except that value is returned instead of the DialogItem.

value(tag) → value

Equivalent to attr(tag, :value).