easygui | index c:\pydev\easygui\current_version\easygui.py

`@version: 0.96(2010-06-25)
@note:
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. All GUI interactions are
invoked by simple function calls that return results.
@note:
WARNING about using EasyGui with IDLE
You may encounter problems using IDLE to run programs that use EasyGui. Try it
and find out. EasyGui is a collection of Tkinter routines that run their own
event loops. IDLE is also a Tkinter application, with its own event loop. The
two may conflict, with unpredictable results. If you find that you have
problems, try running your EasyGui program outside of IDLE.
Note that EasyGui requires Tk release 8.0 or greater.`

Modules

``

FixTk os pickle | pprint string sys | tkFileDialog _tkinter traceback | types

Classes

``

EgStore

class EgStore

``

`A class to support persistent storage.
You can use EgStore to support the storage and retrieval
of user settings for an EasyGui application.
# Example A
#-----------------------------------------------------------------------
# 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
restore() # restore values from the storage file if possible
# Example B
#-----------------------------------------------------------------------
# create settings, a persistent Settings object
#-----------------------------------------------------------------------
settingsFile = "myApp_settings.txt"
settings = Settings(settingsFile)
user = "obama_barak"
server = "whitehouse1"
settings.userId = user
settings.targetServer = server
settings.store() # persist the settings
# run code that gets a new value for userId, and persist the settings
user = "biden_joe"
settings.userId = user
settings.store()
# Example C
#-----------------------------------------------------------------------
# recover the Settings instance, change an attribute, and store it again.
#-----------------------------------------------------------------------
settings = Settings(settingsFile)
settings.userId = "vanrossum_g"
settings.store()
`

Methods defined here:

__init__(self, filename)

__str__(self)
  `return my contents as a string in an easy-to-read format.`

kill(self)
  `Delete my persistent file (i.e. pickle file), if it exists.`

restore(self)
  `Set the values of whatever attributes are recoverable
  from the pickle file.
  Populate the attributes (the __dict__) of the EgStore object
  from the attributes (the __dict__) of the pickled object.
  If the pickled object has attributes that have been initialized
  in the EgStore object, then those attributes of the EgStore object
  will be replaced by the values of the corresponding attributes
  in the pickled object.
  If the pickled object is missing some attributes that have
  been initialized in the EgStore object, then those attributes
  of the EgStore object will retain the values that they were
  initialized with.
  If the pickled object has some attributes that were not
  initialized in the EgStore object, then those attributes
  will be ignored.
  IN SUMMARY:
  After the recover() operation, the EgStore object will have all,
  and only, the attributes that it had when it was initialized.
  Where possible, those attributes will have values recovered
  from the pickled object.`

store(self)
  `Save the attributes of the EgStore object to a pickle file.
  Note that if the directory for the pickle file does not already exist,
  the store operation will fail.`

Functions

``

abouteasygui()
  `shows the easygui revision history`

boolbox(msg='Shall I continue?', title=' ', choices=('Yes', 'No'), image=None)
  `Display a boolean msgbox.
  The default is the first choice.
  The returned value is calculated this way::
  if the first choice is chosen, or if the dialog is cancelled:
  returns 1
  else:
  returns 0`

buttonbox(msg='', title=' ', choices=('Button1', 'Button2', 'Button3'), image=None, root=None)
  `Display a msg, a title, and a set of buttons.
  The buttons are defined by the members of the choices list.
  Return the text of the button that the user selected.
  @arg msg: the msg to be displayed.
  @arg title: the window title
  @arg choices: a list or tuple of the choices to be displayed`

ccbox(msg='Shall I continue?', title=' ', choices=('Continue', 'Cancel'), image=None)
  `Display a msgbox with choices of Continue and Cancel.
  The default is "Continue".
  The returned value is calculated this way::
  if the first choice ("Continue") is chosen, or if the dialog is cancelled:
  return 1
  else:
  return 0
  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
  @arg msg: the msg to be displayed.
  @arg title: the window title
  @arg choices: a list or tuple of the choices to be displayed`

choicebox(msg='Pick something.', title=' ', choices=())
  `Present the user with a list of choices.
  return the choice that he selects.
  return None if he cancels the selection selection.
  @arg msg: the msg to be displayed.
  @arg title: the window title
  @arg choices: a list or tuple of the choices to be displayed`

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.`

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.`

egdemo()
  `Run the EasyGui demo.`

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.
  Returns the text that the user entered, or None if he cancels the operation.
  By default, enterbox strips its result (i.e. removes leading and trailing
  whitespace). (If you want it not to strip, use keyword argument: strip=False.)
  This makes it easier to test the results of the call::
  reply = enterbox(....)
  if reply:
  ...
  else:
  ...`

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.`

fileopenbox(msg=None, title=None, default='*', filetypes=None)
  `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:\myjunk\ and show all Python files.
  WINDOWS EXAMPLE::
  ...default="c:/myjunk/test*.py"
  will open in directory c:\myjunk\ and 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 THAT
  =========
  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.
  @rtype: string or None
  @return: the name of a file, or None if user chose to cancel
  @arg msg: the msg to be displayed.
  @arg title: the window title
  @arg default: filepath with wildcards
  @arg filetypes: filemasks that a user can choose, e.g. "*.txt"`

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.`

indexbox(msg='Shall I continue?', title=' ', choices=('Yes', 'No'), image=None)
  `Display a buttonbox with the specified choices.
  Return the index of the choice selected.`

integerbox(msg='', title=' ', default='', lowerbound=0, upperbound=99, image=None, root=None, **invalidKeywordArguments)
  `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 argument 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.
  NOTE that the "argLowerBound" and "argUpperBound" arguments are no longer
  supported. They have been replaced by "upperbound" and "lowerbound".`

msgbox(msg='(Your message goes here)', title=' ', ok_button='OK', image=None, root=None)
  `Display a messagebox`

multchoicebox(msg='Pick as many items as you like.', title=' ', choices=(), **kwargs)
  `Present the user with a list of choices.
  allow him to select multiple items and return them in a list.
  if the user doesn't choose anything from the list, return the empty list.
  return None if he cancelled selection.
  @arg msg: the msg to be displayed.
  @arg title: the window title
  @arg choices: a list or tuple of the choices to be displayed`

multenterbox(msg='Fill in values for the fields.', title=' ', fields=(), values=())
  `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 == 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)
  writeln("Reply was: %s" % str(fieldValues))
  ----------------------------------------------------------------------
  @arg msg: the msg to be displayed.
  @arg title: the window title
  @arg fields: a list of fieldnames.
  @arg values: a list of field values`

multpasswordbox(msg='Fill in values for the fields.', title=' ', fields=(), values=())
  `Same interface as multenterbox. But in multpassword box,
  the last of the fields is assumed to be a password, and
  is masked with asterisks.
  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 == 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)
  writeln("Reply was: %s" % str(fieldValues))`

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.
  Returns the text that the user entered, or None if he cancels the operation.`

textbox(msg='', title=' ', text='', codebox=0)
  `Display some text in a proportional font with line wrapping at word breaks.
  This function is suitable for displaying general written text.
  The text parameter should be a string, or a list or tuple of lines to be
  displayed in the textbox.`

ynbox(msg='Shall I continue?', title=' ', choices=('Yes', 'No'), image=None)
  `Display a msgbox with choices of Yes and No.
  The default is "Yes".
  The returned value is calculated this way::
  if the first choice ("Yes") is chosen, or if the dialog is cancelled:
  return 1
  else:
  return 0
  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
  @arg msg: the msg to be displayed.
  @arg title: the window title
  @arg choices: a list or tuple of the choices to be displayed`

Data
`` |  | __all__ = ['ynbox', 'ccbox', 'boolbox', 'indexbox', 'msgbox', 'buttonbox', 'integerbox', 'multenterbox', 'enterbox', 'exceptionbox', 'choicebox', 'codebox', 'textbox', 'diropenbox', 'fileopenbox', 'filesavebox', 'passwordbox', 'multpasswordbox', 'multchoicebox', 'abouteasygui', ...] egversion = '0.96(2010-06-25)'