Description

UI::UserInput() waits for the user to do some input. Normally this means it waits until the user clicks on a push button.

Widgets that have the notify option set can also cause UserInput() to return - i.e. to resume the control flow in the YCP code with the next statement after UserInput().

As long as the user does not do any such action, UserInput() waits, i.e. execution of the YCP code stops in UserInput(). In particular, entering text in input fields (TextEntry widgets) or selecting an entry in a list (SelectionBox widget) does not make UserInput() continue unless the respective widget has the notify option set.

UserInput() returns the ID of the widget that caused it to return. This is usually a button ID. It does not return any text entered etc.; use UI::QueryWidget() to retrieve the contents of the dialog's widgets.

Such a widget ID can be of any valid YCP type, but using simple types like symbol, string or maybe integer is strongly recommended.

Although it is technically still possible, using complex data types like map, list or even term (which might even contain YCP code to be executed with eval()) is discouraged. Support for this may be dropped without notice in future versions.

Since it depends on exactly what types the YCP application developer choses for his widgets, UserInput()'s return type is any. You may safely use a variable of the actual type you are using (usually symbol or string).

Usage:

any widget_id = UI::UserInput();

Example:

// UserInput.ycp
//
// Example for common usage of UI::UserInput()

{
    // Build dialog with two input fields and three buttons.
    //
    // Output goes to the log file: ~/.y2log for normal users
    // or /var/log/YaST2/y2log for root.

    string name = "Tux";
    string addr = "Antarctica";

    UI::OpenDialog(
                   `VBox(
                         `TextEntry(`id(`name), "&Name:",    name ),
                         `TextEntry(`id(`addr), "&Address:", addr ),
                         `HBox(
                               `PushButton(`id(`ok     ), "&OK" ),
                               `PushButton(`id(`cancel ), "&Cancel" ),
                               `PushButton(`id(`help   ), "&Help"   )
                               )
                         )
                   );

    symbol widget_id = nil; // All widget IDs used here are symbols

    // Event loop

    repeat
    {
        widget_id = UI::UserInput();

        if ( widget_id == `ok )
        {
            // process "OK" button

            y2milestone( "OK button activated" );


            // Retrieve widget contents

            name = UI::QueryWidget(`id(`name ), `Value );
            addr = UI::QueryWidget(`id(`addr ), `Value );
        }
        else if ( widget_id == `cancel )
        {
            // process "Cancel" buttton
            // or window manager close button (this also returns `cancel)

            y2milestone( "Cancel button activated" );
        }
        else if ( widget_id == `help )
        {
            // process "Help" button

            y2milestone( "Help button activated" );
        }

        // No other "else" branch necessary: None of the TextEntry widget has
        // the `notify option set, so none of them can make UserInput() return.

    } until ( widget_id == `ok || widget_id == `cancel );



    // Close the dialog - but only after retrieving all information that may
    // still be stored only in its widgets: QueryWidget() works only for
    // widgets that are still on the screen!

    UI::CloseDialog();


    // Dump the values entered into the log file

    y2milestone( "Name: %1 Address: %2", name, addr );
}