Provided by: python3-easygui_0.98.1-2_all bug

NAME

       easygui - easygui Documentation

       EasyGUI  is  a  module  for  very  simple, very easy GUI programming in Python. EasyGUI is
       different from other GUI generators in that EasyGUI is NOT event-driven. Instead, all  GUI
       interactions are invoked by simple function calls.

       EasyGui provides an easy-to-use interface for simple GUI interaction with a user.  It does
       not require the programmer to know anything about tkinter, frames, widgets,  callbacks  or
       lambda.

       EasyGUI runs on Python 2 and 3, and does not have any dependencies.

EXAMPLE USAGE

       >>> import easygui
       >>> easygui.ynbox('Shall I continue?', 'Title', ('Yes', 'No'))
       True
       >>> easygui.msgbox('This is a basic message box.', 'Title Goes Here')
       'OK'
       >>> easygui.buttonbox('Click on your favorite flavor.', 'Favorite Flavor', ('Chocolate', 'Vanilla', 'Strawberry'))
       'Chocolate'

HOW TO GET EASYGUI

       The best method to get easygui on your system is to type:

          pip install --upgrade easygui

       ,  which  will  install  the  latest  easygui.  You may also download the file yourself by
       looking for the latest release in sourceforge:

       sourceforge download

TABLE OF CONTENTS

   EasyGui Support and Contacts
   Getting easygui and getting help
       The easygui project is developed on Github: https://github.com/robertlugg/easygui

       Releases     are     typically     put     in     both     sourceforge      and      pypi:
       http://sourceforge.net/projects/easygui

       You  can  use  either place to download the latest version, submit bugs, and make requests
       for improvements.

       We welcome any and all feedback!

   Help develop easygui
       If you want to delve into the inner workings of easygui, wish to preview the next release,
       or if you want to contribute to develop easygui, feel free to explore our GitHub site

       You  very  welcome  to fork and please let us know when you come up with cool stuff others
       might use!

   Thanks
       The following people (as well as many others) have contributed to easygui.  Thank you  for
       your work!
          Alex Zawadzki - Project Management, Design, Testing

          Horst JENS - Design, Documentation, Testing

          Juan Jose Corrales - Development (Active)

          Robert Lugg - Development (Active)

          Stephen Ferg - (retired) Created and developed easygui through 0.96

          Andreas Noteng - Debian Package Manager

   easygui API
       class easygui.EgStore(filename)
              Bases: object

              A class to support persistent storage.

              You  can  use  EgStore to support the storage and retrieval of user settings for an
              EasyGui application.

              First: define a class named Settings as a subclass of EgStore

                 class Settings(EgStore):
                     def __init__(self, filename):  # filename is required
                         # specify default values for variables that this application wants to remember
                         self.user_id = ''
                         self.target_server = ''
                         settings.restore()

              Second: create a persistent Settings object*

                 settings = Settings('app_settings.txt')
                 settings.user_id = 'obama_barak'
                 settings.targetServer = 'whitehouse1'
                 settings.store()

                 # run code that gets a new value for user_id, and persist the settings
                 settings.user_id = 'biden_joe'
                 settings.store()

              Example C: recover the Settings instance, change an attribute, and store it again.

                 settings = Settings('app_settings.txt')
                 settings.restore()
                 print settings
                 settings.user_id = 'vanrossum_g'
                 settings.store()

              kill() Delete this store's file if it exists.

              restore()

              store()
                     Save this store to a pickle file.  All directories in filename must  already
                     exist.

       easygui.abouteasygui()
              shows the easygui revision history

       easygui.boolbox(msg='Shall I continue?', title=' ', choices=('[Y]es', '[N]o'), image=None,
       default_choice='Yes', cancel_choice='No')
              Display a boolean msgbox.

              The returned value is calculated this way:

                 if the first choice is chosen, or if the dialog is cancelled:
                     returns True
                 else:
                     returns False

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

                     • choices (list) -- a list or tuple of the choices to be displayed

                     • image (str) -- Filename of image to display

                     • default_choice (str) -- The choice  you  want  highlighted  when  the  gui
                       appears

                     • cancel_choice  (str)  --  If  the user presses the 'X' close, which button
                       should be pressed

              Returns
                     True if first button pressed or dialog is cancelled, False if second  button
                     is pressed

       easygui.buttonbox(msg='',  title='  ',  choices=('Button[1]',  'Button[2]',  'Button[3]'),
       image=None, images=None, default_choice=None, cancel_choice=None, callback=None, run=True)
              Display a msg, a title, an image, and a set of buttons.  The buttons are defined by
              the members of the choices global_state.

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

                     • choices (list) -- a list or tuple of the choices to be displayed

                     • image (str) -- (Only here for backward compatibility)

                     • images (str) -- Filename of image or iterable or iteratable of iterable to
                       display

                     • default_choice (str) -- The choice  you  want  highlighted  when  the  gui
                       appears

              Returns
                     the text of the button that the user selected

       easygui.ccbox(msg='Shall  I  continue?',  title='  ',  choices=('C[o]ntinue', 'C[a]ncel'),
       image=None, default_choice='Continue', cancel_choice='Cancel')
              Display a msgbox with choices of Continue and Cancel.

              The returned value is calculated this way:

                 if the first choice ("Continue") is chosen,
                   or if the dialog is cancelled:
                     return True
                 else:
                     return False

              If invoked without a msg argument, displays a generic request  for  a  confirmation
              that the user wishes to continue.  So it can be used this way:

                 if ccbox():
                     pass # continue
                 else:
                     sys.exit(0)  # exit the program

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

                     • choices (list) -- a list or tuple of the choices to be displayed

                     • image (str) -- Filename of image to display

                     • default_choice  (str)  --  The  choice  you  want highlighted when the gui
                       appears

                     • cancel_choice (str) -- If the user presses the  'X'  close,  which  button
                       should be pressed

              Returns
                     True if 'Continue' or dialog is cancelled, False if 'Cancel'

       easygui.choicebox(msg='Pick  an  item',  title='', choices=[], preselect=0, callback=None,
       run=True)
              Present the user with a list of choices.  return the choice that he selects.

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

                     • choices (list) -- a list or tuple of the choices to be displayed

                     • preselect -- Which item, if any are preselected when dialog appears

              Returns
                     List containing choice selected or None if cancelled

       easygui.codebox(msg='', title=' ', text='')
              Display some text in a monospaced font, with no line wrapping.   This  function  is
              suitable for displaying code and text that is formatted using spaces.

              The  text parameter should be a string, or a list or tuple of lines to be displayed
              in the textbox.

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

                     • text (str) -- what to display in the textbox

       easygui.diropenbox(msg=None, title=None, default=None)
              A dialog to get a directory name.  Note that the msg  argument,  if  specified,  is
              ignored.

              Returns the name of a directory, or None if user chose to cancel.

              If  the  "default"  argument specifies a directory name, and that directory exists,
              then the dialog box will start with that directory.

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

                     • default (str) -- starting directory when dialog opens

              Returns
                     Normalized path selected by user

       easygui.egdemo()
              Run the EasyGui demo.

       easygui.enterbox(msg='Enter something.', title=' ',  default='',  strip=True,  image=None,
       root=None)
              Show a box in which a user can enter some text.

              You  may  optionally  specify  some default text, which will appear in the enterbox
              when it is displayed.

              Example:

                 reply = enterbox(....)
                 if reply:
                     ...
                 else:
                     ...

              Parametersmsg (str) -- the msg to be displayed.

                     • title (str) -- the window title

                     • default (str) -- value returned if user does not change it

                     • strip (bool) -- If  True,  the  return  value  will  have  its  whitespace
                       stripped before being returned

              Returns
                     the text that the user entered, or None if he cancels the operation.

       easygui.exceptionbox(msg=None, title=None)
              Display a box that gives information about an exception that has just been raised.

              The caller may optionally pass in a title for the window, or a msg to accompany the
              error information.

              Note that you do not need to (and cannot) pass an exception object as an  argument.
              The latest exception will automatically be used.

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

              Returns
                     None

       easygui.fileopenbox(msg=None, title=None, default='*', filetypes=None, multiple=False)
              A dialog to get a file name.

              About the "default" argument

              The  "default"  argument  specifies a filepath that (normally) contains one or more
              wildcards.  fileopenbox will display only files that match  the  default  filepath.
              If omitted, defaults to "*" (all files in the current directory).

              WINDOWS EXAMPLE:

                 ...default="c:/myjunk/*.py"

              will open in directory c:myjunkand show all Python files.

              WINDOWS EXAMPLE:

                 ...default="c:/myjunk/test*.py"

              will  open  in  directory  c:myjunkand show all Python files whose names begin with
              "test".

              Note that on Windows, fileopenbox automatically changes the path separator  to  the
              Windows path separator (backslash).

              About the "filetypes" argument

              If specified, it should contain a list of items, where each item is either:

              • a string containing a filemask          # e.g. "*.txt"

              • a  list  of  strings,  where all of the strings except the last one are filemasks
                (each beginning with "*.", such as "*.txt" for  text  files,  "*.py"  for  Python
                files, etc.).  and the last string contains a filetype description

              EXAMPLE:

                 filetypes = ["*.css", ["*.htm", "*.html", "HTML files"]  ]

              NOTE:
                 If the filetypes list does not contain ("All files","*"), it will be added.

              If  the  filetypes  list does not contain a filemask that includes the extension of
              the "default" argument, it will be added.  For example, if default="*abc.py" and no
              filetypes  argument  was  specified, then "*.py" will automatically be added to the
              filetypes argument.

              Parametersmsg (str) -- the msg to be displayed.

                     • title (str) -- the window title

                     • default (str) -- filepath with wildcards

                     • filetypes (object) -- filemasks that a user can choose, e.g. "*.txt"

                     • multiple (bool) -- If true, more than one file can be selected

              Returns
                     the name of a file, or None if user chose to cancel

       easygui.filesavebox(msg=None, title=None, default='', filetypes=None)
              A file to get the name of a file to save.  Returns the name of a file, or  None  if
              user chose to cancel.

              The "default" argument should contain a filename (i.e. the current name of the file
              to be saved).  It may also be empty, or contain a filemask that includes wildcards.

              The "filetypes" argument works like the "filetypes" argument to fileopenbox.

              Parametersmsg (str) -- the msg to be displayed.

                     • title (str) -- the window title

                     • default (str) -- default filename to return

                     • filetypes (object) -- filemasks that a user can choose, e.g. " *.txt"

              Returns
                     the name of a file, or None if user chose to cancel

       easygui.indexbox(msg='Shall I continue?', title=' ',  choices=('Yes',  'No'),  image=None,
       default_choice='Yes', cancel_choice='No')
              Display a buttonbox with the specified choices.

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

                     • choices (list) -- a list or tuple of the choices to be displayed

                     • image (str) -- Filename of image to display

                     • default_choice  (str)  --  The  choice  you  want highlighted when the gui
                       appears

                     • cancel_choice (str) -- If the user presses the  'X'  close,  which  button
                       should be pressed

              Returns
                     the index of the choice selected, starting from 0

       easygui.integerbox(msg='',   title='   ',   default=None,   lowerbound=0,   upperbound=99,
       image=None, root=None)
              Show a box in which a user can enter an integer.

              In addition to arguments for msg and title, this function accepts integer arguments
              for "default", "lowerbound", and "upperbound".

              The default, lowerbound, or upperbound may be None.

              When  the  user  enters  some  text,  the  text is checked to verify that it can be
              converted to an integer between the lowerbound and upperbound.

              If it can be, the integer (not the text) is returned.

              If it cannot, then an error msg is displayed, and the integerbox is redisplayed.

              If the user cancels the operation, None is returned.

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

                     • default (int) -- The default value to return

                     • lowerbound (int) -- The lower-most value allowed

                     • upperbound (int) -- The upper-most value allowed

                     • image (str) -- Filename of image to display

                     • root (tk_widget) -- Top-level Tk widget

              Returns
                     the integer value entered by the user

       easygui.msgbox(msg='(Your message goes  here)',  title='  ',  ok_button='OK',  image=None,
       root=None)
              Display a message box

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

                     • ok_button (str) -- text to show in the button

                     • image (str) -- Filename of image to display

                     • root (tk_widget) -- Top-level Tk widget

              Returns
                     the text of the ok_button

       easygui.multchoicebox(msg='Pick    an    item',    title='',    choices=[],   preselect=0,
       callback=None, run=True)
              Same as choicebox, but the user can select many items.

       easygui.multenterbox(msg='Fill  in  values  for  the  fields.',  title='   ',   fields=[],
       values=[], callback=None, run=True)
              Show screen with multiple data entry fields.

              If  there  are  fewer  values  than  names, the list of values is padded with empty
              strings until the number of values is the same as the number of names.

              If there are more values than names, the list of values is truncated so that  there
              are as many values as names.

              Returns  a  list  of  the  values  of  the  fields, or None if the user cancels the
              operation.

              Here is some example code, that shows how values returned from multenterbox can  be
              checked for validity before they are accepted:

                 msg = "Enter your personal information"
                 title = "Credit Card Application"
                 fieldNames = ["Name","Street Address","City","State","ZipCode"]
                 fieldValues = []  # we start with blanks for the values
                 fieldValues = multenterbox(msg,title, fieldNames)

                 # make sure that none of the fields was left blank
                 while 1:
                     if fieldValues is None: break
                     errmsg = ""
                     for i in range(len(fieldNames)):
                         if fieldValues[i].strip() == "":
                             errmsg += ('"%s" is a required field.\n\n' % fieldNames[i])
                     if errmsg == "":
                         break # no problems found
                     fieldValues = multenterbox(errmsg, title, fieldNames, fieldValues)

                 print("Reply was: %s" % str(fieldValues))

              Parametersmsg (str) -- the msg to be displayed.

                     • title (str) -- the window title

                     • fields (list) -- a list of fieldnames.

                     • values (list) -- a list of field values

              Returns
                     String

       easygui.multpasswordbox(msg='Fill  in  values  for  the  fields.',  title='  ', fields=(),
       values=(), callback=None, run=True)
              Same interface as multenterbox.  But in multpassword box, the last of the fields is
              assumed to be a password, and is masked with asterisks.

              Parametersmsg (str) -- the msg to be displayed.

                     • title (str) -- the window title

                     • fields (list) -- a list of fieldnames.

                     • values (list) -- a list of field values

              Returns
                     String

              Example

              Here  is some example code, that shows how values returned from multpasswordbox can
              be checked for validity before they are accepted:

                 msg = "Enter logon information"
                 title = "Demo of multpasswordbox"
                 fieldNames = ["Server ID", "User ID", "Password"]
                 fieldValues = []  # we start with blanks for the values
                 fieldValues = multpasswordbox(msg,title, fieldNames)

                 # make sure that none of the fields was left blank
                 while 1:
                     if fieldValues is None: break
                     errmsg = ""
                     for i in range(len(fieldNames)):
                         if fieldValues[i].strip() == "":
                             errmsg = errmsg + ('"%s" is a required field.\n\n' %
                              fieldNames[i])
                         if errmsg == "": break # no problems found
                     fieldValues = multpasswordbox(errmsg, title,
                       fieldNames, fieldValues)

                 print("Reply was: %s" % str(fieldValues))

       easygui.passwordbox(msg='Enter  your  password.',  title='  ',   default='',   image=None,
       root=None)
              Show  a  box  in  which  a  user  can  enter  a  password.  The text is masked with
              asterisks, so the password is not displayed.

              Parametersmsg (str) -- the msg to be displayed.

                     • title (str) -- the window title

                     • default (str) -- value returned if user does not change it

              Returns
                     the text that the user entered, or None if he cancels the operation.

       easygui.textbox(msg='', title=' ', text='', codebox=False, callback=None, run=True)
              Display a message and a text to edit

              msg    string text displayed in the message area (instructions...)

              title  str the window title

              text: str, list or tuple
                     text displayed in textAreas (editable)

              codebox: bool
                     if True, don't wrap and width is set to 80 chars

              callback: function
                     if set, this function will be called when OK is pressed

              run: bool
                     if True, a box object will be created and returned, but not run

              None   If cancel is pressed

              str    If OK is pressed returns the contents of textArea

       easygui.ynbox(msg='Shall  I  continue?',  title='  ',  choices=('[<F1>]Yes',  '[<F2>]No'),
       image=None, default_choice='[<F1>]Yes', cancel_choice='[<F2>]No')
              Display a msgbox with choices of Yes and No.

              The returned value is calculated this way:

                 if the first choice ("Yes") is chosen, or if the dialog is cancelled:
                     return True
                 else:
                     return False

              If  invoked  without  a msg argument, displays a generic request for a confirmation
              that the user wishes to continue.  So it can be used this way:

                 if ynbox():
                     pass # continue
                 else:
                     sys.exit(0)  # exit the program

              Parametersmsg (str) -- the msg to be displayed

                     • title (str) -- the window title

                     • choices (list) -- a list or tuple of the choices to be displayed

                     • image (str) -- Filename of image to display

                     • default_choice (str) -- The choice  you  want  highlighted  when  the  gui
                       appears

                     • cancel_choice  (str)  --  If  the user presses the 'X' close, which button
                       should be pressed

              Returns
                     True if 'Yes' or dialog is cancelled, False if 'No'

   EasyGui Tutorial
   Introduction
       In easygui, all GUI interactions are invoked by simple function calls.

       Here is a simple demo program using easygui.

          from easygui import *
          import sys

          # A nice welcome message
          ret_val = msgbox("Hello, World!")
          if ret_val is None: # User closed msgbox
              sys.exit(0)

          msg ="What is your favorite flavor?\nOr Press <cancel> to exit."
          title = "Ice Cream Survey"
          choices = ["Vanilla", "Chocolate", "Strawberry", "Rocky Road"]
          while 1:
              choice = choicebox(msg, title, choices)
              if choice is None:
                  sys.exit(0)
              msgbox("You chose: {}".format(choice), "Survey Result")

   EasyGui's demonstration routine
       To run EasyGui's demonstration routine, invoke EasyGui from the command line this way:

          python easygui.py

       or from an IDE (such as IDLE, PythonWin, Wing, etc.) this way:

          from easygui import *
          egdemo()

       This will allow you to try out the various EasyGui functions, and will print  the  results
       of your choices to the console.

   Importing EasyGui
       In order to use EasyGui, you must import it. The simplest import statement is:

          import easygui

       If  you use this form, then to access the EasyGui functions, you must prefix them with the
       name "easygui", this way:

          easygui.msgbox(...)

       One alternative is to import EasyGui this way:

          from easygui import *

       This makes it easier to invoke the  EasyGui  functions;  you  won't  have  to  prefix  the
       function names with "easygui". You can just code something like this:

          msgbox(...)

       A third alternative is to use something like the following import statement:

          import easygui as g

       This  allows  you  to keep the EasyGui namespace separate with a minimal amount of typing.
       You can access easgui functions like this:

          g.msgbox(...)

       This third alterative is actually the best way to do it once you get used  to  python  and
       easygui.

   Using EasyGui
       Once  your  module  has imported EasyGui, GUI operations are a simple a matter of invoking
       EasyGui functions with a few parameters. For example, using EasyGui,  the  famous  "Hello,
       world!" program looks like this:

          from easygui import *
          msgbox("Hello, world!")

       To  see  a  demo  of what EasyGui output looks like, invoke easyGui from the command line,
       this way:

          python easygui.py

       To see examples of code that invokes the EasyGui functions, look at the demonstration code
       at the end of easygui.py.

   Default arguments for EasyGui functions
       For all of the boxes, the first two arguments are for message and title, in that order. In
       some cases, this might not be the most user-friendly arrangement (for example, the dialogs
       for  getting directory and filenames ignore the message argument), but I felt that keeping
       this consistent across all widgets was a consideration that is more important.

       Most arguments to EasyGui functions have defaults.  Almost all  of  the  boxes  display  a
       message and a title. The title defaults to the empty string, and the message usually has a
       simple default.

       This makes it is possible to specify as few arguments as you need  in  order  to  get  the
       result  that  you want. For instance, the title argument to msgbox is optional, so you can
       call msgbox specifying only a message, this way:

          msgbox("Danger, Will Robinson!")

       or specifying a message and a title, this way:

          msgbox("Danger, Will Robinson!", "Warning!")

       On the various types of buttonbox, the default message is "Shall I continue?", so you  can
       (if you wish) invoke them without arguments at all. Here we invoke ccbox (the close/cancel
       box, which returns a boolean value) without any arguments at all:

          if ccbox():
              pass  # user chose to continue
          else:
              return      # user chose to cancel

   Using keyword arguments when calling EasyGui functions
       It is possible to use keyword arguments when calling EasyGui functions.

       Suppose for instance that you wanted to use a buttonbox, but (for whatever reason) did not
       want  to  specify  the  title  (second)  positional  argument. You could still specify the
       choices argument (the third argument) using a keyword, this way:

          choices = ["Yes","No","Only on Friday"]
          reply = choicebox("Do you like to eat fish?", choices=choices)

   Using buttonboxes
       There are a number of functions built on top of buttonbox() for common needs.

   msgbox
       msgbox displays a message and offers an OK button. You can send whatever message you want,
       along with whatever title you want. You can even over-ride the default text of "OK" on the
       button if you wish. Here is the signature of the msgbox function:

          def msgbox(msg="(Your message goes here)", title="", ok_button="OK"):
              ....

       The clearest way to over-ride the button text is to do it with a  keyword  argument,  like
       this:

          msgbox("Backup complete!", ok_button="Good job!")

       Here are a couple of examples:

          msgbox("Hello, world!")
       [image]

          msg = "Do you want to continue?"
          title = "Please Confirm"
          if ccbox(msg, title):     # show a Continue/Cancel dialog
              pass  # user chose Continue
          else:  # user chose Cancel
              sys.exit(0)
       [image]

   ccbox
       ccbox  offers  a  choice of Continue and Cancel, and returns either True (for continue) or
       False (for cancel).

   ynbox
       ynbox offers a choice of Yes and No, and returns either True of False.

   buttonbox
       To specify your own set of buttons in a buttonbox, use the buttonbox() function.

       The buttonbox can be used to display a set of buttons of your choice. When the user clicks
       on a button, buttonbox() returns the text of the choice. If the user cancels or closes the
       buttonbox, the default choice (the first choice) is returned.

       buttonbox displays a message, a title, and a set of  buttons.  Returns  the  text  of  the
       button that the user selected.

   indexbox
       indexbox  displays  a  message,  a  title,  and a set of buttons. Returns the index of the
       user's choice. For example, if you invoked  index  box  with  three  choices  (A,  B,  C),
       indexbox would return 0 if the user picked A, 1 if he picked B, and 2 if he picked C.

   boolbox
       boolbox (boolean box) displays a message, a title, and a set of buttons. Returns returns 1
       if the first button is chosen. Otherwise returns 0.

       Here is a simple example of a boolbox():

          message = "What does she say?"
          title = ""
          if boolbox(message, title, ["She loves me", "She loves me not"]):
              sendher("Flowers") # This is just a sample function that you might write.
          else:
              pass

   How to show an image in a buttonbox
       When you invoke the buttonbox function (or other functions that display a button box, such
       as msgbox, indexbox, ynbox,
              etc.),  you can specify the keyword argument image=xxx where xxx is the filename of
              an image.  The file can be .gif.

       Usually, you can use other image formats such as .png.

       NOTE:
          The types of files supported depends on how you installed  python.   If  other  formats
          don't work, you may need to install the PIL library.

       If an image argument is specified, the image file will be displayed after the message.

       Here is some sample code from EasyGui's demonstration routine:

          image = "python_and_check_logo.gif"
          msg = "Do you like this picture?"
          choices = ["Yes","No","No opinion"]
          reply = buttonbox(msg, image=image, choices=choices)

       If  you  click on one of the buttons on the bottom, its value will be returned in 'reply'.
       You may also click on the image.  In that case, the image filename is returned.  [image]

   Letting the user select from a list of choices
   choicebox
       Buttonboxes are good for offering the user a small selection  of  short  choices.  But  if
       there  are  many choices, or the text of the choices is long, then a better strategy is to
       present them as a list.

       choicebox provides a way for a user to select from a list  of  choices.  The  choices  are
       specified  in a sequence (a tuple or a list). The choices will be given a case-insensitive
       sort before they are presented.

       The keyboard can be used to select an element of the list.

       Pressing "g" on the keyboard, for example, will jump the selection to  the  first  element
       beginning with "g". Pressing "g" again, will jump the cursor to the next element beginning
       with "g". At the end of the elements beginning with "g", pressing "g" again will cause the
       selection  to  wrap  around  to  the  beginning  of the list and jump to the first element
       beginning with "g".

       If there is no element beginning with "g", then the last element that  occurs  before  the
       position  where  "g"  would occur is selected. If there is no element before "g", then the
       first element in the list is selected:

          msg ="What is your favorite flavor?"
          title = "Ice Cream Survey"
          choices = ["Vanilla", "Chocolate", "Strawberry", "Rocky Road"]
          choice = choicebox(msg, title, choices)
       [image]

       Another example of a choicebox: [image]

   multchoicebox
       The multchoicebox() function provides a way for a user to select from a list  of  choices.
       The  interface  looks  just  like  the  choicebox,  but  the user may select zero, one, or
       multiple choices.

       The choices are specified in a sequence (a tuple or a list). The choices will be  given  a
       case-insensitive sort before they are presented.  [image]

   Letting the user enter information
   enterbox
       enterbox is a simple way of getting a string from the user

   integerbox
       integerbox is a simple way of getting an integer from the user.

   multenterbox
       multenterbox is a simple way of showing multiple enterboxes on a single screen.  [image]

       In the multenterbox:

          • If there are fewer values than names, the list of values is padded with empty strings
            until the number of values is the same as the number of names.

          • If there are more values than names, the list of values is truncated  so  that  there
            are as many values as names.

       Returns a list of the values of the fields, or None if the user cancels the operation.

       Here is some example code, that shows how values returned from multenterbox can be checked
       for validity before they are accepted:

          from __future__ import print_function
          msg = "Enter your personal information"
          title = "Credit Card Application"
          fieldNames = ["Name", "Street Address", "City", "State", "ZipCode"]
          fieldValues = multenterbox(msg, title, fieldNames)
          if fieldValues is None:
              sys.exit(0)
          # make sure that none of the fields were left blank
          while 1:
              errmsg = ""
              for i, name in enumerate(fieldNames):
                  if fieldValues[i].strip() == "":
                    errmsg += "{} is a required field.\n\n".format(name)
              if errmsg == "":
                  break # no problems found
              fieldValues = multenterbox(errmsg, title, fieldNames, fieldValues)
              if fieldValues is None:
                  break
          print("Reply was:{}".format(fieldValues))

       NOTE:
          The first line 'from __future__' is only necessary if you are using Python 2.*, and  is
          only needed for this demo.

   Letting the user enter password information
   passwordbox
       A passwordbox box is like an enterbox, but used for entering passwords. The text is masked
       as it is typed in.

   multpasswordbox
       multpasswordbox has the same interface as multenterbox, but when it is displayed, the last
       of the fields is assumed to be a password, and is masked with asterisks.  [image]

   Displaying text
       EasyGui provides functions for displaying text.

   textbox
       The textbox() function displays text in a proportional font. The text will word-wrap.

   codebox
       The codebox() function displays text in a monospaced font and does not wrap.  [image]

       Note  that  you  can  pass codebox() and textbox() either a string or a list of strings. A
       list of strings will be converted to text before being displayed. This means that you  can
       use these functions to display the contents of a file this way:

          import os
          filename = os.path.normcase("c:/autoexec.bat")
          f = open(filename, "r")
          text = f.readlines()
          f.close()
          codebox("Contents of file " + filename, "Show File Contents", text)

   Working with files
       A common need is to ask the user for a filename or for a directory. EasyGui provides a few
       basic functions for allowing a user to navigate through  the  file  system  and  choose  a
       directory or a file. (These functions are wrappers around widgets and classes in lib-tk.)

       Note that in the current version of EasyGui, the startpos argument is not supported.

   diropenbox
       diropenbox returns the name of a directory

   fileopenbox
       fileopenbox returns the name of a file [image]

   filesavebox
       filesavebox returns the name of a file

   Remembering User Settings
   EgStore
       A  common  need is to ask the user for some setting, and then to "persist it", or store it
       on disk, so that the next time the user  uses  your  application,  you  can  remember  his
       previous setting.

       In  order  to  make the process of storing and restoring user settings, EasyGui provides a
       class called EgStore. In order to remember some settings, your application must  define  a
       class  (let's  call it Settings, although you can call it anything you want) that inherits
       from EgStore.

       Your application must also  create  an  object  of  that  class  (let's  call  the  object
       settings).

       The  constructor  (the  __init__  method)  of the Settings class can initialize all of the
       values that you wish to remember.

       Once you have done this, you can remember the  settings  simply  by  assigning  values  to
       instance  variables in the settings object, and use the settings.store() method to persist
       the settings object to disk.

       Here is an example of code using the Settings class:

          from easygui import EgStore

          # -----------------------------------------------------------------------
          # define a class named Settings as a subclass of EgStore
          # -----------------------------------------------------------------------
          class Settings(EgStore):

              def __init__(self, filename):  # filename is required
                  # -------------------------------------------------
                  # Specify default/initial values for variables that
                  # this particular application wants to remember.
                  # -------------------------------------------------
                  self.userId = ""
                  self.targetServer = ""

                  # -------------------------------------------------
                  # For subclasses of EgStore, these must be
                  # the last two statements in  __init__
                  # -------------------------------------------------
                  self.filename = filename  # this is required
                  self.restore()

          # Create the settings object.
          # If the settingsFile exists, this will restore its values
          # from the settingsFile.
          # create "settings", a persistent Settings object
          # Note that the "filename" argument is required.
          # The directory for the persistent file must already exist.

          settingsFilename = "settings.txt"
          settings = Settings(settingsFilename)

          # Now use the settings object.
          # Initialize the "user" and "server" variables
          # In a real application, we'd probably have the user enter them via enterbox
          user    = "obama_barak"
          server  = "whitehouse1"

          # Save the variables as attributes of the "settings" object
          settings.userId = user
          settings.targetServer = server
          settings.store()    # persist the settings
          print("\nInitial settings")
          print settings

          # Run code that gets a new value for userId
          # then persist the settings with the new value
          user    = "biden_joe"
          settings.userId = user
          settings.store()
          print("\nSettings after modification")
          print settings

          # Delete setting variable
          del settings.userId
          print("\nSettings after deletion of userId")
          print settings

       Here is an example of code using a dedicated function to create the Settings class:

          from easygui import read_or_create_settings

          # Create the settings object.
          settings = read_or_create_settings('settings1.txt')

          # Save the variables as attributes of the "settings" object
          settings.userId = "obama_barak"
          settings.targetServer = "whitehouse1"
          settings.store()    # persist the settings
          print("\nInitial settings")
          print settings

          # Run code that gets a new value for userId
          # then persist the settings with the new value
          user    = "biden_joe"
          settings.userId = user
          settings.store()
          print("\nSettings after modification")
          print settings

          # Delete setting variable
          del settings.userId
          print("\nSettings after deletion of userId")
          print settings

   Trapping Exceptions
   exceptionbox
       Sometimes exceptions are raised... even in EasyGui applications. Depending on how you  run
       your  application,  the  stack trace might be thrown away, or written to stdout while your
       application crashes.

       EasyGui provides a better  way  of  handling  exceptions  via  exceptionbox.  Exceptionbox
       displays the stack trace in a codebox and may allow you to continue processing.

       Exceptionbox is easy to use. Here is a code example:

          try:
              someFunction()  # this may raise an exception
          except:
              exceptionbox()
       [image]

   EasyGui FAQ
   An FAQ consisting of far too few questions. Help please :)
   General Questions
       1. What other gui libraries can I use?

          There are several.  The two most popular as of 2014-12 are TkInter and PyQt.

          TkInter  is  a  library shipped with Python and it is the de-facto standard for Python.
          You can find more about it at https://wiki.python.org/moin/TkInter

          PyQt   is   a   very   popular   library.    More   information    on    it    is    at
          https://wiki.python.org/moin/PyQt

          A     library     inspired    by    easygui    is    the    EasyGUI_qt    project    at
          http://easygui-qt.readthedocs.org/en/latest/ "Under  the  hood"  easygui  uses  Tkinter
          while EasyGUI_qt uses pyQt

       2. Why should I use easygui instead of some other library?

          Well,  sometimes  you should start with those other (excellent) libraries.  However, we
          hope that you find easygui useful.  Some of the cases for using easygui are:

          • You are starting to program and are tired of the command line  >>>.   easygui  allows
            you to quickly create GUIs without worrying about all the details of Tk or Qt.

          • You already have a program and want to make it easier for people to use by building a
            GUI for it.

          • Its easy!  You can try it out in a couple of hours and decide for yourself

          Don't worry.  With easygui you are learning the basics.  We take only a  few  shortcuts
          to make things easier.  If you decide to move to a library with more functionality, you
          will already understand some of the GUI basics.

   Specifics
       1. Can I specify a custom sort order for the items in a choicebox?

          No, there is no way to specify a custom order. The reason is  that  the  data  must  be
          sorted in order for the "jump to" feature (namely, to jump down in the list by pressing
          keyboard keys) to work.

          For some tips on how to control the order of items in a choicebox, see this recipe from
          the Easygui Cookbook.

       2. Button box images don't appear and I get an error such as:
             Cannot    load   C:UsersRobertSkyDriveGitHubeasyguieasyguipython_and_check_logo.jpg.
             Check to make sure it is an image file.  PIL library isn't installed.  If  it  isn't
             installed, only .gif files can be used.

          Possibly  you  are  trying  to  load  files  other than .gif.  Unfortunately, the 'PIL'
          library must be installed for this to work.

   Cookbook
   A section to hold code snippets and recipes
       1. Simple demo program

          Here is a simple demo program using easygui. The screens that it produces are shown  on
          the easygui home page.

             from easygui import *
             import sys

             while 1:
                 msgbox("Hello, world!")

                 msg ="What is your favorite flavor?"
                 title = "Ice Cream Survey"
                 choices = ["Vanilla", "Chocolate", "Strawberry", "Rocky Road"]
                 choice = choicebox(msg, title, choices)

                 # note that we convert choice to string, in case
                 # the user cancelled the choice, and we got None.
                 msgbox("You chose: " + str(choice), "Survey Result")

                 msg = "Do you want to continue?"
                 title = "Please Confirm"
                 if ccbox(msg, title):     # show a Continue/Cancel dialog
                     pass  # user chose Continue
                 else:
                     sys.exit(0)           # user chose Cancel

       2. Controlling the order of items in choicebox

          In  a  choicebox,  the  choices  must  be  in sort order so that the keyboard "jump to"
          feature (jump down in the list by pressing keyboard keys)  will  work.   But  it  often
          happens  that  a  sort  of first-cut listing of choices doesn't sort in a user-friendly
          order. So what can you do to control the order of the items displayed in a choicebox?

          A useful technique is to specify keys for the items in  the  choicebox.   For  example,
          suppose  you  want a choicebox to display View, Update, Delete, Exit.  If you specified
          your choices this way:

             choices = ["View", "Update", "Delete", "Exit"]

          you'd get this:

          • Delete

          • Exit

          • Update

          • View

          It is definitely in alphabetic order, but not very user-friendly.  But if you specified
          keys for your choices this way:

             choices = ["V View", "U Update", "D elete", "X Exit"]

          you'd get this (with "X" appearing at the bottom):

          • D Delete

          • U Update

          • V View

          • X Exit

          Suppose  you  wanted  to  force View to the top, so it is the easiest choice to select.
          You could change its key from "V" to "A":

             choices = ["A View", "U Update", "D elete", "X Exit"]

          and you'd get this:

          • A View

          • D Delete

          • U Update

          • X Exit

          Another technique is to prepend a space to the choice.  Since space  characters  always
          sorts  before  a non-space character, you can use this trick to force something like "V
          View" to the top of the list:

             choices = [" V View", "U Update", "D Delete", "X Exit"]

          produces this:

          • V View

          • D Delete

          • U Update

          • X Exit

          In the proportional font used  by  choicebox,  the  space  before  the  "V"  is  almost
          imperceptible.

          Personally,  I  prefer  to  use  alphabetic keys rather than numeric keys for choicebox
          items.  It is easier to navigate the choices using alpha keys on the keyboard  than  by
          using the number keys.

          And it is possible to use multi-character keys, like this:

          • L1  Log old version

          • L2  Log new version

          Using keys for choices also makes it relatively easy to check for the user's selection:

             choices = [" V View", "U Update", "D elete", "X Exit"]
             choice = choicebox(msg,title,choices)

             if choice == None:
                 return
             reply = choice.split()[0] # reply = the first word of the choice

             if reply == "X":
                 return
             elif reply == "V":
                 processView()
             elif reply == "L1":
                 saveLog(version="old")
             elif reply == "L2":
                 saveLog(version="new")

       3. Registration System demo

          The Registration System demo application is a simple database application to maintain a
          list of courses, and students who are registered for the courses.

          It is not completely implemented -- its purpose is to give  you  a  feel  for  what  is
          possible  with  EasyGui  and  how  you  might  do  it,  not  to  be  a complete working
          application.

          File:  registration zip file

          Screenshots: [image] [image]

   EasyGui Links
       _

   YouTube videos by Marcus Adams
       A nice series of tutorials were created to show off Message Box, Button Box, Continue  Box
       and Choice:

       Part 1 of many

   easygui for Students
       Austrian game-programming-for-children teacher Horst JENS  says:

       "I can proudly report that EasyGui is very popular with my students of all ages and one of
       the best ways to introduce young students to python in a short time."

       Horst and his students have made several videos showing their use of EasyGui:

          • Lexi shows msgboxLeo shows buttonboxMira and Teresa show a simple graphic adventure game

   Previous Versions and website
       In December 2014, this website was converted to a new format.  A  snapshot  of  the  older
       website  is  still  available, but is static as it won't be updated: easygui website up to
       version 0.96

   Stephen Ferg
       Stephen developed easygui up through version  0.96.   We  are  forever  greatful  for  his
       insight and vision.  He can be contacted at his website at: http://www.ferg.org/index.html

       You   might   also   visit   his   blog   where   much   of   easygui   is  discussed  at:
       https://easygui.wordpress.com

       Thank you Stephen.

       • genindex

       • search

       Background

       easygui was started several years ago by Stephen Ferg and was developed and  supported  by
       him  through  2013.   From  there,  work  was restarted circa 2014.  The first goal was to
       update the then four year old release and address some bugs and minor enhancements.   That
       first release was 0.97

       EasyGui version 0.98.0

       Copyright (c) -2016, Stephen Raymond Ferg

       All rights reserved.

       Redistribution  and  use  in  source  and  binary forms, with or without modification, are
       permitted provided that the following conditions are met:

          1. Redistributions of source code must retain the above copyright notice, this list  of
             conditions and the following disclaimer.

          2. Redistributions  in binary form must reproduce the above copyright notice, this list
             of conditions and  the  following  disclaimer  in  the  documentation  and/or  other
             materials provided with the distribution.

          3. The  name  of the author may not be used to endorse or promote products derived from
             this software without specific prior written permission.

       THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY  EXPRESS  OR  IMPLIED  WARRANTIES,
       INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
       PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY  DIRECT,
       INDIRECT,  INCIDENTAL,  SPECIAL,  EXEMPLARY,  OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
       LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
       STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY  WAY  OUT  OF
       THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ABOUT THE EASYGUI LICENSE

       This license is what is generally known as the "modified BSD license",
       aka "revised BSD", "new BSD", "3-clause BSD".
       See http://opensource.org/licenses/bsd-license.php

       This license is GPL-compatible.
       See http://en.wikipedia.org/wiki/License_compatibility
       See http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses

       The BSD License is less restrictive than GPL.
       It allows software released under the license to be incorporated into proprietary products.
       Works based on the software may be released under a proprietary license or as closed source software.
       http://en.wikipedia.org/wiki/BSD_licenses#3-clause_license_.28.22Revised_BSD_License.22.2C_.22New_BSD_License.22.2C_or_.22Modified_BSD_License.22.29

AUTHOR

       easygui dev team

COPYRIGHT

       2021, easygui dev team