Metadata-Version: 2.1
Name: limitedinteraction
Version: 0.1.1
Summary: Provides simple, backend-independant GUI tools for simple user interaction.
Home-page: https://github.com/felixchenier/limitedinteraction
Author: Félix Chénier
Author-email: chenier.felix@uqam.ca
License: Apache
Project-URL: Source, https://github.com/felixchenier/limitedinteraction/
Project-URL: Tracker, https://github.com/felixchenier/limitedinteraction/issues
Description: # Limited Interaction
        
        Provides simple, backend-independant GUI tools for limited user interaction.
        
        This module provides simple GUI tools that run in their own separate process,
        which proves to be useful in interactive IPython sessions. It has no external
        dependency and updates the matplotlib event loop in background (if matplotlib
        is installed) while waiting for user action.
        
        
        ## Why another GUI module ##
        
        This module may interest people transitionning from Matlab to python, who miss
        Matlab's no-brainer ui functions such as msgbox, menu, etc. I could not find
        equivalent functions in the vast python ecosystem that are:
        
            - blocking when needed;
            - but still continue to refresh matplotlib when launched in an interactive
              IPython session;
            - independent of the currently running IPython event loop.
        
        This module is designed to be a limited but extra-easy option to interact with
        a user without even thinking about what is a GUI. It has no dependencies and
        should work out of the box in any situation where the python interpreter is run
        locally. It is based on tkinter, but since it starts its own processes, it can
        be run conjointly with any other backend (Qt, wxwindows, etc.).
        
        
        ## Usage ##
        
        ### Importing ###
        
        ```python
        import limitedinteraction as li
        ```
        
        ### Creating a persistent message window ###
        
        ```python
        li.message('Please wait a few moments.',
                   title='Calculating...',
                   icon='clock')
        ```
        
        ![message_calculating_macOS](https://raw.githubusercontent.com/felixchenier/limitedinteraction/main/doc/message_calculating.png)
        
        
        This is a non-blocking function. Any code after this call is executed
        immediately, while this message window stays in foreground.
        
        ```python
        # Close the message window
        li.message('')
        ```
        
        ### Asking for user input ###
        
        ```python
        name = li.input_dialog('What is your name?', icon='question')
        ```
        
        ![input_dialog_name_macOS](https://raw.githubusercontent.com/felixchenier/limitedinteraction/main/doc/input_dialog_name.png)
        
        This is a blocking function. We wait for user input before continuing.
        Meanwhile, Matplotlib's event loop is refreshed so that the user can
        interact with figures.
        
        This same function can have several inputs and some inputs can be masked:
        
        ```python
        credentials = li.input_dialog('Please enter your credentials',
                                      descriptions=['Username:', 'Password:'],
                                      initial_values=['username', 'password'],
                                      masked=[False, True],
                                      icon='lock')
        ```
        ![input_dialog_credentials_macOS](https://raw.githubusercontent.com/felixchenier/limitedinteraction/main/doc/input_dialog_credentials.png)
        
        
        ```python
        choice_index = li.button_dialog('Please zoom on the figure and click Next.',
                                        choices=['Next', 'Cancel'],
                                        title='User interaction',
                                        icon='gear')
        ```
        
        ![button_dialog_user_interaction_macOS](https://raw.githubusercontent.com/felixchenier/limitedinteraction/main/doc/button_dialog_user_interaction.png)
        
        This is a blocking function. We wait for a choice before continuing. Meanwhile,
        Matplotlib's event loop is refreshed so that the user can interact with
        figures.
        
        
        ### Other functions ###
        
        Get a file name using the operating system's standard file selection window:
        
        ```python
        filename = li.get_filename()
        ````
        
        Get a folder name using the operating system's standard folder selection
        window:
        
        ```python
        folder = li.get_folder()
        ```
        
        ## Known issues ##
        
        If you are using *macOS Mojave* or *Anaconda python on Linux*, you may have these
        problems:
        
        - On macOS Mojave, tkinter is known to be seriously broken. If you use a Mac, please use
          any other OS version than Mojave.
        
        - On Anaconda python on Linux, tkinter fonts are very ugly. It still works, but it looks
          ancient.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Description-Content-Type: text/markdown
