From 3a69d3e777ca1517cbcb5a122c9203e9bb5dc335 Mon Sep 17 00:00:00 2001 From: David Farning Date: Sun, 21 Sep 2008 02:22:56 +0000 Subject: API docstrings from pydocweb --- (limited to 'src/sugar') diff --git a/src/sugar/graphics/alert.py b/src/sugar/graphics/alert.py index 541079f..12e4763 100644 --- a/src/sugar/graphics/alert.py +++ b/src/sugar/graphics/alert.py @@ -1,3 +1,31 @@ +""" +Alerts appear at the top of the body of your activity. + +At a high level, Alert and its different variations (TimeoutAlert, +ConfirmationAlert, etc.) have a title, an alert message and then several +buttons that the user can click. The Alert class will pass "response" events +to your activity when any of these buttons are clicked, along with a +response_id to help you identify what button was clicked. + + +Examples +-------- +create a simple alert message. + +.. code-block:: python + from sugar.graphics.alert import Alert + ... + # Create a new simple alert + alert = Alert() + # Populate the title and text body of the alert. + alert.props.title=_('Title of Alert Goes Here') + alert.props.msg = _('Text message of alert goes here') + # Call the add_alert() method (inherited via the sugar.graphics.Window superclass of Activity) + # to add this alert to the activity window. + self.add_alert(alert) + alert.show() + +""" # Copyright (C) 2007, One Laptop Per Child # # This library is free software; you can redistribute it and/or @@ -28,7 +56,8 @@ from sugar.graphics.icon import Icon _ = lambda msg: gettext.dgettext('sugar-toolkit', msg) class Alert(gtk.EventBox): - """UI interface for Alerts + """ + UI interface for Alerts Alerts are used inside the activity window instead of being a separate popup window. They do not hide canvas content. You can @@ -40,7 +69,9 @@ class Alert(gtk.EventBox): 'title': the title of the alert, 'message': the message of the alert, 'icon': the icon that appears at the far left + See __gproperties__ + """ __gtype_name__ = 'SugarAlert' @@ -209,7 +240,43 @@ class Alert(gtk.EventBox): class ConfirmationAlert(Alert): - """This is a ready-made two button (Cancel,Ok) alert""" + """ + This is a ready-made two button (Cancel,Ok) alert. + + A confirmation alert is a nice shortcut from a standard Alert because it + comes with 'OK' and 'Cancel' buttons already built-in. When clicked, the + 'OK' button will emit a response with a response_id of gtk.RESPONSE_OK, + while the 'Cancel' button will emit gtk.RESPONSE_CANCEL. + + Examples + -------- + + .. code-block:: python + from sugar.graphics.alert import ConfirmationAlert + ... + #### Method: _alert_confirmation, create a Confirmation alert (with ok and cancel buttons standard) + # and add it to the UI. + def _alert_confirmation(self): + alert = ConfirmationAlert() + alert.props.title=_('Title of Alert Goes Here') + alert.props.msg = _('Text message of alert goes here') + alert.connect('response', self._alert_response_cb) + self.add_alert(alert) + + + #### Method: _alert_response_cb, called when an alert object throws a response event. + def _alert_response_cb(self, alert, response_id): + #remove the alert from the screen, since either a response button was clicked or + #there was a timeout + self.remove_alert(alert) + + #Do any work that is specific to the type of button clicked. + if response_id is gtk.RESPONSE_OK: + print 'Ok Button was clicked. Do any work upon ok here ...' + elif response_id is gtk.RESPONSE_CANCEL: + print 'Cancel Button was clicked.' + + """ def __init__(self, **kwargs): Alert.__init__(self, **kwargs) diff --git a/src/sugar/graphics/notebook.py b/src/sugar/graphics/notebook.py index bc6bab5..e159bb3 100644 --- a/src/sugar/graphics/notebook.py +++ b/src/sugar/graphics/notebook.py @@ -49,6 +49,23 @@ class Notebook(gtk.Notebook): self.show() def do_set_property(self, pspec, value): + """ + Set notebook property + + Parameters + ---------- + pspec : + property for which the value will be set + + Returns + ------- + None + + Raises + ------ + AssertionError + + """ if pspec.name == 'can-close-tabs': self._can_close_tabs = value else: @@ -93,6 +110,21 @@ class Notebook(gtk.Notebook): return event_box def add_page(self, text_label, widget): + """ + Adds a page to the notebook. + + Parameters + ---------- + text_label : + + widget : + + Returns + ------- + Boolean + Returns TRUE if the page is successfully added to th notebook. + + """ # Add a new page to the notebook if self._can_close_tabs: eventbox = self._create_custom_tab(text_label, widget) diff --git a/src/sugar/graphics/radiotoolbutton.py b/src/sugar/graphics/radiotoolbutton.py index e2636dc..1fb18cc 100644 --- a/src/sugar/graphics/radiotoolbutton.py +++ b/src/sugar/graphics/radiotoolbutton.py @@ -24,6 +24,10 @@ from sugar.graphics.palette import Palette, ToolInvoker from sugar.graphics import toolbutton class RadioToolButton(gtk.RadioToolButton): + """ + An implementation of a "push" button. + + """ __gtype_name__ = 'SugarRadioToolButton' def __init__(self, **kwargs): @@ -43,7 +47,17 @@ class RadioToolButton(gtk.RadioToolButton): self._palette_invoker.detach() def set_tooltip(self, tooltip): - """ Set a simple palette with just a single label. + """ + Set a simple palette with just a single label. + + Parameters + ---------- + tooltip: + + Returns + ------- + None + """ if self.palette is None or self._tooltip is None: self.palette = Palette(tooltip) @@ -61,10 +75,34 @@ class RadioToolButton(gtk.RadioToolButton): tooltip = gobject.property(type=str, setter=set_tooltip, getter=get_tooltip) def set_accelerator(self, accelerator): + """ + Sets the accelerator. + + Parameters + ---------- + accelerator: + + Returns + ------- + None + + """ self._accelerator = accelerator toolbutton.setup_accelerator(self) def get_accelerator(self): + """ + Returns the accelerator for the button. + + Parameters + ---------- + None + + Returns + ------ + accelerator: + + """ return self._accelerator accelerator = gobject.property(type=str, setter=set_accelerator, -- cgit v0.9.1