[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 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 or Dialog#show. In 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). In Dialog#show, the dialog becomes modeless, and stays on screen until Dialog#hide is invoked.

Dialog also implements run as a class method, which allows the creation of dialog items within a block. 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 or Array

Display the "open" dialog and returns the fullpath filename (if `multiple_selection` is false) or an array of the fullpath filenames (if `multiple_selection` is true). Note: `multiple_selection` can only be specified when `for_directories` is false.

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

hide → self

Hide the modeless dialog. This is to be used with Dialog#show in pairs. Mixing Dialog#hide and Dialog#run will lead to unpredictable results, including crash.

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.

show → self

Show the dialog modelessly. This is intended to be used with Dialog#hide in pairs.

To avoid garbage collection by Ruby interpreter, the dialog being shown is registered in a global variable, and unregistered when it is hidden.

Mixing Dialog#show and Dialog#run will lead to unpredictable results, including crash.

start_timer(interval, action = nil) → self

Start dialog-specific interval timer. The timer interval is described in seconds (floating point is allowed, however the resolution is not better than milliseconds on wxWidgets). If the timer is already running, it is stopped before new timer is run.

The action is either a symbol (method name) or a Proc object. If no action is given, then the last set value is used.

See Also: Dialog#stop_timer

stop_timer → self

Stop dialog-specific interval timer. Do nothing if no timer is running.

See Also: Dialog#start_timer

value(tag) → value

Equivalent to attr(tag, :value).