1 # dialog.cif

     2 # 

     3 # Copyright (c) 2010 Accenture. All rights reserved.

     4 # This component and the accompanying materials are made available

     5 # under the terms of the "Eclipse Public License v1.0"

     6 # which accompanies this distribution, and is available

     7 # at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 # 

     9 # Initial Contributors:

    10 # Accenture - Initial contribution

    11 #

    12 

    13 ==name dialog

    14 

    15 ==short-description

    16 

    17 Displays a UI dialog.

    18 

    19 ==long-description

    20 

    21 Up to two buttons are supported. By default the first is labelled C<OK> and the second C<Cancel>. The button the user selected can be determined by the return code of the command. The first button will produce a return code of zero (0), and the second a code of one (1). If there was an error displaying the dialog, the error code will be returned (always a negative number). The return code makes it possible to write scripts like:

    22 

    23   dialog --body 'Do you want to proceed?' && do_something

    24 

    25 This will result in F<do_something> only being executed if the user presses the first button. An error or the user pressing the second button with NOT result in F<do_something> being executed. Note though that the text window server's notifier implementation appears to assign the first button one (1) and the second, zero (0). Also, on the 3rd edition of S60 killing a dialog command while it is running will result in the handset resetting itself when the actual dialog is dismissed.

    26 

    27 The environment variable C<DIALOG_IMPL> can be used to control the way in which the user is interacted with. The following values of C<DIALOG_IMPL> are supported:

    28 

    29 =over 5

    30 

    31 =item C<notifier>

    32 

    33 The C<RNotifier> API will be used. This is the default if C<DIALOG_IMPL> is not defined The behaviour of C<RNotifier> depends on the handset configuration, but normally it will result in graphical dialogs being displayed.

    34 

    35 =item C<console>

    36 

    37 The user will be interacted with via the console that the dialog command is connected to. In this mode, pressing the enter (or on some platforms, select) key corresponds to pressing the first button and any other corresponds to pressing the second button.

    38 

    39 =item C<null>

    40 

    41 No attempt is made to interact with the user and it is assumed that the first button is always pressed. This mode allows all user interaction to be disabled.

    42 

    43 =back

    44 

    45 ==argument string body optional

    46 

    47 The body of the dialog. If not specified, the body is read from C<stdin>.

    48 

    49 ==option string t title

    50 

    51 The title of the dialog.

    52 

    53 ==option string f first-button

    54 

    55 The text for the first button.

    56 

    57 ==option string s second-button

    58 

    59 The text for the first button.

    60 

    61 ==copyright

    62 

    63 Copyright (c) 2006-2010 Accenture. All rights reserved.

    64