Description

TimeoutUserInput() is very much like UserInput(), but it returns a predefined ID `timeout if no user input is available within the specified (millisecond) timeout.

This is useful if there is a reasonable default action that should be done in case of a timeout - for example, for popup messages that are not important enough to completely halt a longer operation forever.

User interface style hint: Use this with caution. It is perfectly OK to use timeouts for informational messages that are not critical in any way ("Settings are written", "Rebooting the newly installed kernel"), but definitely not if there are several alternatives the user can choose from. As a general rule of thumb, if a dialog contains just an "OK" button and nothing else, TimeoutUserInput() is appropriate. If there are more buttons, chances are that the default action will cause disaster for some users.

Remember, timeouts are nearly always a desperate means. They are always both too short and too long at the same time: Too short for users who know what message will come and too long for users who left to get some coffee while the machine is busy.

Another possible use of TimeoutUserInput() would be to periodically update the screen with data that keep changing (time etc.) while waiting for user input.

Usage:

any widget_id = UI::TimeoutUserInput( integer timeout_millisec );

Example

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

{
    // Build dialog with two labels and an "OK" button.

    integer countdown_sec       = 30;
    integer interval_millisec   = 200;
    integer countdown           = countdown_sec * 1000 / interval_millisec;

    UI::OpenDialog(
                   `VBox(
                         `Label( "Rebooting Planet Earth..." ),
                         `Label(`id(`seconds ), sformat( "%1", countdown_sec ) ),
                         `PushButton(`id(`ok ), `opt(`default ), "&OK" )
                         )
                   );

    any id = nil;

    // Event loop

    repeat
    {
        id = UI::TimeoutUserInput( interval_millisec );

        if ( id == `timeout )
        {
            // Periodic screen update

            countdown = countdown - 1;
            integer seconds_left = countdown * interval_millisec / 1000;
            UI::ChangeWidget(`id(`seconds ), `Value, sformat( "%1", seconds_left ) );
        }

    } until ( id == `ok || countdown <= 0 );

    UI::CloseDialog();
}