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 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.
The steps for using Dialog are as follows:
: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) }
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.
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
.
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.