From 264ee2b5a325b166cb8b92d6c1908bad9a1d4ed5 Mon Sep 17 00:00:00 2001 From: mandarj7 Date: Wed, 23 Dec 2015 15:31:58 +0530 Subject: [PATCH] Add and improve docs for sugar3.graphics.objectchooser --- src/sugar3/graphics/objectchooser.py | 67 +++++++++++++++++----------- 1 file changed, 42 insertions(+), 25 deletions(-) diff --git a/src/sugar3/graphics/objectchooser.py b/src/sugar3/graphics/objectchooser.py index 9c68661e..02989427 100644 --- a/src/sugar3/graphics/objectchooser.py +++ b/src/sugar3/graphics/objectchooser.py @@ -42,16 +42,19 @@ FILTER_TYPE_ACTIVITY = 'activity' def get_preview_pixbuf(preview_data, width=-1, height=-1): - """Retrive a pixbuf with the content of the preview field + """ + Retrive a pixbuf with the content of the preview field - Keyword arguments: - metadata -- the metadata dictionary. - Can't be None, use metadata.get('preview', '') - width -- the pixbuf width, if is not set, the default width will be used - height -- the pixbuf width, if is not set, the default height will be used + Args: + metadata (dictionary): the metadata dictionary. Can't be None, use metadata.get('preview', '') - Return: a Pixbuf or None if couldn't create it + Keyword Args: + width (int): the pixbuf width, if is not set, the default width will be used + height (int): the pixbuf width, if is not set, the default height will be used + Returns: + Pixbuf, the generated Pixbuf + None, if it could not be created """ if width == -1: width = PREVIEW_SIZE[0] @@ -99,22 +102,20 @@ def get_preview_pixbuf(preview_data, width=-1, height=-1): class ObjectChooser(object): + """ + UI interface for objec choosers. - def __init__(self, parent=None, what_filter=None, filter_type=None, - show_preview=False): - """Initialise the ObjectChoser - - parent -- the widget calling ObjectChooser + Object choosers can be used by acivities to allow the user to select objects + from the file system or from some other similar source. - what_filter -- string + Keyword Args: + parent (:class:`Gtk.Widget`): the widget calling ObjectChooser - string should be an activity bundle_id or a generic mime - type as defined in mime.py used to determine which objects + what_filter (str): an activity bundle_id or a generic mime type as + defined in mime.py used to determine which objects will be presented in the object chooser - - filter_type -- string - - string should be one of [None, FILTER_TYPE_GENERIC_MIME, + + filter_type (str): should be one of [None, FILTER_TYPE_GENERIC_MIME, FILTER_TYPE_ACTIVITY, FILTER_TYPE_MIME_BY_ACTIVITY] If filter_type is None, the default behavior of the @@ -136,13 +137,13 @@ class ObjectChooser(object): field and the mime types defined by the activity in the activity.info file. - show_preview -- boolean - - if True will show the preview image asociated with - the object in the Journal. This option is only available - if filter_type is selected. - """ + show_preview (bool): if True will show the preview image asociated with + the object in the Journal. This option is only available if + filter_type is selected. + """ + def __init__(self, parent=None, what_filter=None, filter_type=None, + show_preview=False): if parent is None: parent_xid = 0 elif hasattr(parent, 'get_window') and hasattr(parent.get_window(), @@ -170,6 +171,13 @@ class ObjectChooser(object): self._filter_type = filter_type def run(self): + """ + Runs the object chooser and displays it. + + Returns: + Gtk.ResponseType constant, the response received from displaying the + object chooser. + """ self._object_id = None self._main_loop = GObject.MainLoop() @@ -211,12 +219,21 @@ class ObjectChooser(object): return self._response_code def get_selected_object(self): + """ + Gets the object selected using the object chooser. + + Returns: + object, the object selected + """ if self._object_id is None: return None else: return datastore.get(self._object_id) def destroy(self): + """ + Destroys and cleans up (disposes) the object chooser. + """ self._cleanup() def _cleanup(self):