NAME

CQCC::IOPerlTK - PerlTk based subclass of IOBase for user interaction


CLASS DESCRIPTION

This class is an IOBase subclass which provides an set of user interaction dialog methods (IOPrompt, IOMessage, IOListSelect, and IOListTreeSelect) using the PerkTK widget toolkit instead of a text menu.

It also provides access to a small set of wrapper objects based on the IOPtkWidget class that encapsulate Perl/TK code to provide building blocks for the CQCC Graphical User Interface. These building blocks provide data interactors (IOPtkManip), menu support (IOPtkMenu), and panels (IOPtkPanel) such as IOFrames or dialogs to build the GUI.

Isolating the Perl/TK code within these wrappers isolates the Trigger class from Perl/TK dependencies, standardizes GUI components, hides implementation details, and provides basic services such as message catalog translations needed by the integration.

The IOPerlTK object provides methods to build and manage named instances of the IOPtkWidget classes without needing to save the pointers in the Trigger methods.

See the TriggerCQCC::GUIBuild method for an extended example of how this intermediate layer works. A small example shows the basic features:

    # Get a handle to the IOPerlTK instance. 
    my $IO = &IOstd();
    # The Panel method creates a panel of a given subtype such as 
    # an IOMainWindow, IOFrame, or IODialogBox. Attributes such as 
    # TITLE are passed in to modify the instance. All IOPerlTK 
    # attributes are in CAPS without dashes; Perl/Tk attributes are 
    # lower case with dashes. 
    #
    # The TK attribute is a general pass through mechanism to pass 
    # in any attributes the internal Perl/TK widget will recognize. 
    #
    # The PACK attribute will be passed through to the Perl/Tk pack
    # operation.
    $IO->Panel("Main", "", "IOMainWindow");
    $IO->Panel("Frame1", "Main", "IOFrame",
               TITLE=>"Frame1",
               TK=>[-borderwidth => 2, -relief => 'groove'],
               PACK=>[-side => "left", -fill => 'y']);
    # The Menu method creates a menu of command buttons and
    # sets up their callbacks. The MenuManageButtons method allows
    # access to disabling buttons as needed.
    $IO->Menu("MyMenu", "Frame1", "IOCommandMenu", 
               TITLE=>"Menu Demo", 
               MENULIST => ["OK "    => 'print "OK\n";',
                            "Cancel" => 'print "Cancel\n";']);
    # Manipulators manage labels or buttons associated with Parm
    # objects or values. The ManipManageValues method is used to 
    # get or set ranges and values.
    $IO->Manipulator("Label1", "Frame1", "IOLabel",
               TITLE=>"Label1", PARM=>"CQCC_CTRL_C");
    $IO->Manipulator("List1", "Frame1", "IOListbox",
               TITLE=>"List", 
               RANGE => ["a","b","c"],
               PACK=>[-side => "left", -fill => 'both']);

The IOPerlTK package was written to suit the immediate needs of the integration GUI and is not very general. Extensions can be made as needed by subclassing the IOPerlTK class to modify the existing Manipulator, Menu, or Panel methods to use subclasses of the original IOPtk* classes if needed and adding additional subtype initializer methods.

Direct access to the underlying Perl/Tk widgets can be obtained using the CQCC::IOPtkWidget::SubWidget method but this should be used very carefully.

SUPPORT POLICY: See TriggerCQCC.pm for the Rational Support Policy.


METHODS

ClassTest(@args)
This class function sets IOBaseInterface to make an instance of this subclass then runs the class test for IOBase.

IOPtkPanel::ClassTest is a local test of the IOPtkWidget based widgets.

ExitHandler(status)
This method will hide the main windows before calling the main exit handler.

GetMainWindow()
This method returns a pointer to the Perk/Tk MainWindow widget; if it has not been created yet, it is created with default properties and returned.

ListSelect(multiChoice, titleMsgTag, choiceMsgTagList...)
This method presents a menu with a title described by ``titleMsgTag'' and one or more options to select from described by the remaining arguments. If multiChoice is 1 then multiple choices are allowed, otherwise only one choice is provided.

In the PerlTK implementation, the choices are displayed in a scrolling ``list'' type menu and the user is expected to pick one or more lines in the list.

The selected items will be returned as a list to the caller, using the original choiceMsgTag items in their entirety for the caller to match to expectations.

The return value consists of a list containing a flag to abort (1 for abort, 0 for continue) and the answer(s).

This method should be called through the IOBase::IOListSelect function.

ListTreeSelect(multiChoice,separator,titleMsgTag, choiceMsgTagList...)
Variant on ListSelect which presents the list as a folding tree structure based on the choice list, assuming that each choice is a pathname separated by the separator character.

If the IOBase class does not provide support for the IOListTreeSelect method, it will default to using the standard IOListSelect method instead and present the information as a normal list.

For more details see the IOListSelect function documentation.

This method should be called through the IOBase::IOListTreeSelect function.

Manipulator(name, parent, subtype, key=value,...)>
This method creates a new IOPtkManip object to provide a GUI component. See the documentation for CQCC::IOPtkManip for more information on the available subtypes and arguments.

Use the CQCC::IOPerlTK::ManipManageValues method to modify properties of the manipulator or to retrieve value or range information.

ManipManageValues(name, operation, @arglist)
This method is called to get or set the value or range of a named manipulator widget. The currently supported operations include the following:
    GETRANGE - retrieves widget's current range as a list reference
    SETRANGE - sets widget range to a list reference value
    GETVALUE - retrieves widget's current range as a list
    SETVALUE - sets widget value to list reference value

The value argument is only expected by the SET* operations.

See the documentation for CQCC::IOPtkManip::ManageValues for the most recent information on the available subtypes and arguments.

Menu(name, parent, subtype, key=value,...)>
This method creates a new IOPtkMenu object to provide a GUI menu component. See the documentation for CQCC::IOPtkMenu for more information on the available subtypes and arguments.

Use the CQCC::IOPerlTK::MenuManageButtons method to modify the state of the menu buttons.

MenuManageButtons(name, buttonName, value)
This method can be called for any IOPtkMenu widget to modify the state of its buttons. Operations currently supported include the following: STATE which changes the buttonName's state to value (normal, disabled, or active).

See the documentation for CQCC::IOPtkMenu::ManageButtons for the most recent information on the available subtypes and arguments.

Message(type, abort, [msgtag, args])
This method (called through IOMessage()) will display its message to the user, after translating the msgtag and its arguments into the corresponding message catalog entry.

The type value may be ``INFO'', ``WARN'', ``ERROR'', or ``FATAL'' and is intended to qualify how the message is to be shown and whether or not the message affects the overall trigger status. If ``FATAL'' the status will be set to failed and the trigger will try to cleanly unwind and report failure back to the original caller, usually ClearCase.

The IOPerlTK implementation provides a resizeable scrolling message box for large messages over SCROLL_THRESHOLD lines.

The abort flag is also used to signal general failure for terminal conditions and will be combined with the type information shortly.

new CQCC::IOPerlTK()
This method initializes the object's attributes.

Panel(name, parent, subtype, key=value,...)>
This method creates a new IOPtkPanel object to provide a GUI geometry component. See the documentation for CQCC::IOPtkPanel for more information on the available subtypes and arguments.

Prompt(keys)
This method (called through IOPrompt()) will display its message to the user, after translating the msgtag and its arguments into the corresponding message catalog entry.

The return value consists of a list containing the a flag to abort (1 for abort, 0 for continue) and the answer(s).

($abort, $answer) = $obj->Prompt(keys);

RunMainLoop()
This method starts the Perl/Tk MainLoop function to begin interaction with the user after the GUI has been defined.

SetMainWindow(window)
This method sets the Perk/Tk MainWindow widget and returns the widget that is current MainWindow.

ShowMainWindow(status)
This method will show the main window if the status is ``SHOW'' and hide it if the status is ``HIDE''. By default the window is shown.