# HG changeset patch # User paulb # Date 1197922537 0 # Node ID fbb8e6877c7ad24ca552fcd9a4bfd3017f3cd2cb # Parent 8e64df19342bf3adfb922ddfab9ebac6bf06c52c [project @ 2007-12-17 20:15:37 by paulb] Added/improved docstrings/comments, and introduced a supported desktops attribute to the module. diff -r 8e64df19342b -r fbb8e6877c7a desktop/dialog.py --- a/desktop/dialog.py Sat Dec 15 18:52:23 2007 +0000 +++ b/desktop/dialog.py Mon Dec 17 20:15:37 2007 +0000 @@ -29,7 +29,7 @@ class: question = desktop.dialog.Question("Are you sure?") -question.open() +result = question.open() To override the detected desktop, specify the desktop parameter to the open function as follows: @@ -41,6 +41,9 @@ Available dialogue box classes are listed in the desktop.dialog.available attribute. + +Supported desktop environments are listed in the desktop.dialog.supported +attribute. """ from desktop import use_desktop, _run, _readfrom, _status @@ -239,6 +242,7 @@ commands = { "KDE" : "kdialog", "GNOME" : "zenity", + "XFCE" : "zenity", # NOTE: Based on observations with Xubuntu. "X11" : "Xdialog" } @@ -248,17 +252,18 @@ Open a dialogue box (dialog) using a program appropriate to the desktop environment in use. - If the optional 'desktop' parameter is specified then attempt to use that - particular desktop environment's mechanisms to open the dialog instead of - guessing or detecting which environment is being used. + If the optional 'desktop' parameter is specified then attempt to use + that particular desktop environment's mechanisms to open the dialog + instead of guessing or detecting which environment is being used. - Suggested values for 'desktop' are "standard", "KDE", "GNOME", "Mac OS X", - "Windows". + Suggested values for 'desktop' are "standard", "KDE", "GNOME", + "Mac OS X", "Windows". The result of the dialogue interaction may be a string indicating user - input (for input, password, menu, radiolist, pulldown), a list of strings - indicating selections of one or more items (for checklist), or a value - indicating true or false (for question). + input (for Input, Password, Menu, Pulldown), a list of strings + indicating selections of one or more items (for RadioList, CheckList), + or a value indicating true or false (for Question, Warning, Message, + Error). """ # Decide on the desktop environment in use. @@ -272,6 +277,9 @@ except KeyError: raise OSError, "Desktop '%s' not supported (no known dialogue box command could be suggested)" % desktop_in_use + # The handler is one of the functions communicating with the subprocess. + # Some handlers return boolean values, others strings. + handler, options = self.info[program] cmd = [program] @@ -295,6 +303,8 @@ """ A dialogue asking a question and showing response buttons. Options: text, width (in characters), height (in characters) + Response: a boolean value indicating an affirmative response (true) or a + negative response """ name = "question" @@ -309,6 +319,8 @@ """ A dialogue asking a question and showing response buttons. Options: text, width (in characters), height (in characters) + Response: a boolean value indicating an affirmative response (true) or a + negative response """ name = "warning" @@ -323,6 +335,8 @@ """ A message dialogue. Options: text, width (in characters), height (in characters) + Response: a boolean value indicating an affirmative response (true) or a + negative response """ name = "message" @@ -337,6 +351,8 @@ """ An error dialogue. Options: text, width (in characters), height (in characters) + Response: a boolean value indicating an affirmative response (true) or a + negative response """ name = "error" @@ -351,7 +367,8 @@ """ A menu of options, one of which being selectable. Options: text, width (in characters), height (in characters), - list_height (in items), items (MenuItem objects) + list_height (in items), items (MenuItem objects) + Response: a value corresponding to the chosen item """ name = "menu" @@ -393,7 +410,10 @@ """ A list of radio buttons, one of which being selectable. Options: text, width (in characters), height (in characters), - list_height (in items), items (MenuItem objects), titles + list_height (in items), items (MenuItem objects), titles + Response: a list of values corresponding to chosen items (since some + programs, eg. zenity, appear to support multiple default + selections) """ name = "radiolist" @@ -414,7 +434,8 @@ """ A list of checkboxes, many being selectable. Options: text, width (in characters), height (in characters), - list_height (in items), items (MenuItem objects), titles + list_height (in items), items (MenuItem objects), titles + Response: a list of values corresponding to chosen items """ name = "checklist" @@ -435,7 +456,8 @@ """ A pull-down menu of options, one of which being selectable. Options: text, width (in characters), height (in characters), - entries (list of values) + items (list of values) + Response: a value corresponding to the chosen item """ name = "pulldown" @@ -456,6 +478,7 @@ """ An input dialogue, consisting of an input field. Options: text, input, width (in characters), height (in characters) + Response: the text entered into the dialogue by the user """ name = "input" @@ -477,6 +500,7 @@ """ A password dialogue, consisting of a password entry field. Options: text, width (in characters), height (in characters) + Response: the text entered into the dialogue by the user """ name = "password" @@ -494,6 +518,7 @@ """ A text file input box. Options: filename, text, width (in characters), height (in characters) + Response: any text returned by the dialogue program """ name = "textfile" @@ -513,4 +538,8 @@ available = [Question, Warning, Message, Error, Menu, CheckList, RadioList, Input, Password, Pulldown, TextFile] +# Supported desktop environments. + +supported = Dialogue.commands.keys() + # vim: tabstop=4 expandtab shiftwidth=4