diff --git a/docs/source/messages.rst b/docs/source/messages.rst index c4aede6..d1a29a1 100644 --- a/docs/source/messages.rst +++ b/docs/source/messages.rst @@ -6,30 +6,36 @@ The following functions allow you to display a brief message or choice to the us .. py:function:: notify(message, title="Message", form_color='STANDOUT', wrap=True, wide=False,) This function displays a message on the screen. It does not block and the user cannot interact with it - use it to display messages like "Please Wait" while other things are happening. - + .. py:function:: notify_wait(message, title="Message", form_color='STANDOUT', wrap=True, wide=False,) - + This function displays a message on the screen, and blocks for a brief amount of time. The user cannot interact with it. - + .. py:function:: notify_confirm(message, title="Message", form_color='STANDOUT', wrap=True, wide=False, editw=0) - + Display a message and an OK button. The user can scroll the message if needed. editw controls which widget is selected when the dialog is first displayed; set to 1 to have the OK button active immediately. - + .. py:function:: notify_ok_cancel(message, title="Message", form_color='STANDOUT', wrap=True, editw = 0,) Display a message and return True if the user selected 'OK' and False if the user selected 'Cancel'. - + .. py:function:: notify_yes_no(message, title="Message", form_color='STANDOUT', wrap=True, editw = 0) Similar to *notify_ok_cancel* except the names of the buttons are 'Yes' and 'No'. Returns True or False. - The following function will display a dialog box for the user to select a filename. .. py:function:: selectFile(select_dir=False, must_exist=False, confirm_if_exists=True,sort_by_extension=True,) This form is currently experimental. The return value is the name of the file. - + +The following function will display a dialog box for the user to provide a single line of textual input + +.. py:function:: single_line_input(default_value="Input Text", title="Message", form_color='STANDOUT') + + Similar to *notify_ok_cancel* except the return value will be the entered string if the user presses "Ok" and None + if the user presses "Cancel". + Blanking the Screen =================== diff --git a/npyscreen/utilNotify.py b/npyscreen/utilNotify.py index b6166d1..6cf8aae 100644 --- a/npyscreen/utilNotify.py +++ b/npyscreen/utilNotify.py @@ -93,4 +93,26 @@ def notify_yes_no(message, title="Message", form_color='STANDOUT', wrap=True, ed F.edit() return F.value - \ No newline at end of file +def single_line_input(default_value="Input Text", title="Message", form_color='STANDOUT'): + ''' Convenience function for requesting a single line of user input + + Args: + default_value (str): The default value for the input textfield + title (str): Title for the popup + form_color (str): Color scheme used (as defined by the theme used) + + Returns: + str: - None if the user pressed "Cancel" + - Value of the text input field if the user pressed "OK" + ''' + + F = ConfirmCancelPopup(name=title, color=form_color) + F.preserve_selected_widget = True + tf = F.add(npyscreen.Textfield) + tf.width = tf.width - 1 + tf.value = default_value + F.edit() + if F.value is True: + return tf.value + else: + return None \ No newline at end of file