| Class: | Dialog |
| Parent: | Object |
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.
The steps for using Dialog are as follows:
: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) }
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.
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) }))
}
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).
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.
Create a new dialog by Dialog#new, and call Dialog#run (instance method).
Display the "save as" dialog and returns the fullpath filename.
Look for the dialog item with the tag or at the index, and get the item attribute designated by the key.
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 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.
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.
Retrieve the dialog item which has the tag attribute tval. If such an item does not exist, nil is returned.
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.
Group radio buttons as a mutually exclusive group. The arguments represent the radio buttons, either as DialogItem objects, item indices, or item tags.
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 the attributes of the dialog item designated by the index or the tag. The attribute names and values are given as a hash object.
Equivalent to set_attr(tag, :value=>value), except that value is returned instead of the DialogItem.
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 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 dialog-specific interval timer. Do nothing if no timer is running.
See Also: Dialog#start_timer