diff --git a/src/sugar3/graphics/alert.py b/src/sugar3/graphics/alert.py index bdc272b7..4cd4c128 100644 --- a/src/sugar3/graphics/alert.py +++ b/src/sugar3/graphics/alert.py @@ -7,18 +7,17 @@ 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. +Example: + Create a simple alert message. -Examples --------- -create a simple alert message. + .. code-block:: python + + from sugar3.graphics.alert import Alert -.. code-block:: python - from sugar3.graphics.alert import Alert - ... - # Create a new simple 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.title = _('Title of Alert Goes Here') alert.props.msg = _('Text message of alert goes here') # Call the add_alert() method (inherited via the sugar3.graphics.Window # superclass of Activity) to add this alert to the activity window. @@ -65,19 +64,15 @@ class Alert(Gtk.EventBox): Alerts are used inside the activity window instead of being a separate popup window. They do not hide canvas content. You can - use add_alert(widget) and remove_alert(widget) inside your activity + use `add_alert()` and `remove_alert()` inside your activity to add and remove the alert. The position of the alert is below the toolbox or top in fullscreen mode. - Properties: - 'title': the title of the alert, - 'message': the message of the alert, - 'icon': the icon that appears at the far left - - See __gproperties__ - + Args: + title (str): the title of the alert + message (str): the message of the alert + icon (str): the icon that appears at the far left """ - __gtype_name__ = 'SugarAlert' __gsignals__ = { @@ -91,7 +86,6 @@ class Alert(Gtk.EventBox): } def __init__(self, **kwargs): - self._title = None self._msg = None self._icon = None @@ -129,18 +123,10 @@ class Alert(Gtk.EventBox): def do_set_property(self, pspec, value): """ - Set alert property - - Parameters - ---------- - pspec : - - value : - - Returns - ------- - None + Set alert property, GObject internal method. + Use the `alert.props` object, eg:: + alert.props.title = 'Are you happy?' """ if pspec.name == 'title': if self._title != value: @@ -159,17 +145,10 @@ class Alert(Gtk.EventBox): def do_get_property(self, pspec): """ - Get alert property - - Parameters - ---------- - pspec : - property for which the value will be returned - - Returns - ------- - value of the property specified + Set alert property, GObject internal method. + Use the `alert.props` object, eg:: + title = alert.props.title """ if pspec.name == 'title': return self._title @@ -180,23 +159,17 @@ class Alert(Gtk.EventBox): """ Add a button to the alert - Parameters - ---------- - response_id : - will be emitted with the response signal a response ID should one - of the pre-defined GTK Response Type Constants or a positive number - label : - that will occure right to the buttom - - icon : - this can be a SugarIcon or a Gtk.Image - - postion : - the position of the button in the box (optional) + Args: + response_id (int): will be emitted with the response signal a + response ID should one of the pre-defined GTK Response Type + Constants or a positive number + label (str): that will occure right to the buttom + icon (:class:`sugar3.graphics.icon.Icon` or :class:`Gtk.Image`, optional): + icon for the button, placed before the text + postion (int, optional): the position of the button in the box - Returns - ------- - button :Gtk.Button + Returns: + Gtk.Button: the button added to the alert """ button = Gtk.Button() @@ -215,19 +188,18 @@ class Alert(Gtk.EventBox): """ Remove a button from the alert by the given response id - Parameters - ---------- - response_id : + Args: + response_id (int): the same response id passed to add_button - Returns - ------- - None + Returns: + None """ self._buttons_box.remove(self._buttons[response_id]) def _response(self, response_id): - """Emitting response when we have a result + """ + Emitting response when we have a result A result can be that a user has clicked a button or a timeout has occured, the id identifies the button @@ -241,22 +213,23 @@ 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.ResponseType.OK, - while the 'Cancel' button will emit Gtk.ResponseType.CANCEL. + 'OK' button will emit a response with a response_id of + :class:`Gtk.ResponseType.OK`, while the 'Cancel' button will emit + :class:`Gtk.ResponseType.CANCEL`. - Examples - -------- + Args: + **kwargs: options for :class:`sugar3.graphics.alert.Alert` .. code-block:: python - from sugar3.graphics.alert import ConfirmationAlert - ... - #### Method: _alert_confirmation, create a Confirmation alert (with ok - and cancel buttons standard) - # and add it to the UI. + + from sugar3.graphics.alert import ConfirmationAlert + + # Create a Confirmation alert (with ok and cancel buttons standard) + # then add it to the UI. def _alert_confirmation(self): alert = ConfirmationAlert() alert.props.title=_('Title of Alert Goes Here') @@ -264,20 +237,17 @@ class ConfirmationAlert(Alert): alert.connect('response', self._alert_response_cb) self.add_alert(alert) - - #### Method: _alert_response_cb, called when an alert object throws a - response event. + # 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 + # 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. + # Do any work that is specific to the type of button clicked. if response_id is Gtk.ResponseType.OK: print 'Ok Button was clicked. Do any work upon ok here ...' elif response_id is Gtk.ResponseType.CANCEL: print 'Cancel Button was clicked.' - """ def __init__(self, **kwargs): @@ -298,16 +268,17 @@ class ErrorAlert(Alert): An error alert is a nice shortcut from a standard Alert because it comes with the 'OK' button already built-in. When clicked, the - 'OK' button will emit a response with a response_id of Gtk.ResponseType.OK. + 'OK' button will emit a response with a response_id of + :class:`Gtk.ResponseType.OK`. - Examples - -------- + Args: + **kwargs: options for :class:`sugar3.graphics.alert.Alert` .. code-block:: python - from sugar3.graphics.alert import ErrorAlert - ... - #### Method: _alert_error, create a Error alert (with ok - button standard) + + from sugar3.graphics.alert import ErrorAlert + + # Create a Error alert (with ok button standard) # and add it to the UI. def _alert_error(self): alert = ErrorAlert() @@ -316,18 +287,15 @@ class ErrorAlert(Alert): alert.connect('response', self._alert_response_cb) self.add_alert(alert) - - #### Method: _alert_response_cb, called when an alert object throws a - response event. + # 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 + # 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 response_id. + # Do any work that is specific to the response_id. if response_id is Gtk.ResponseType.OK: - print 'Ok Button was clicked. Do any work upon ok here ...' - + print 'Ok Button was clicked. Do any work upon ok here' """ def __init__(self, **kwargs): @@ -380,44 +348,44 @@ class _TimeoutIcon(Gtk.Alignment): class TimeoutAlert(Alert): """ - This is a ready-made two button (Cancel,Continue) alert + This is a ready-made two button (Cancel, Continue) alert. The continue + button contains a visual countdown indicating the time remaining to the + user. If the user does not select a button before the timeout, the + response callback is called and the alert is usually removed. - It times out with a positive response after the given amount of seconds. + Args: + timeout (int, optional): the length in seconds for the timeout to + last, defaults to 5 seconds + **kwargs: options for :class:`sugar3.graphics.alert.Alert` + .. code-block:: python - Examples - -------- + from sugar3.graphics.alert import TimeoutAlert - .. code-block:: python - from sugar3.graphics.alert import TimeoutAlert - ... - #### Method: _alert_timeout, create a Timeout alert (with ok and cancel - buttons standard) - # and add it to the UI. + # Create a Timeout alert (with ok and cancel buttons standard) then + # add it to the UI def _alert_timeout(self): - #Notice that for a TimeoutAlert, you pass the number of seconds in - #which to timeout. By default, this is 5. + # Notice that for a TimeoutAlert, you pass the number of seconds + # in which to timeout. By default, this is 5. alert = TimeoutAlert(10) - alert.props.title=_('Title of Alert Goes Here') + alert.props.title = _('Title of Alert Goes Here') alert.props.msg = _('Text message of timeout alert goes here') - alert.connect('response', self._alert_response_cb) + 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 + # 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. + # Do any work that is specific to the type of button clicked. if response_id is Gtk.ResponseType.OK: print 'Ok Button was clicked. Do any work upon ok here ...' elif response_id is Gtk.ResponseType.CANCEL: print 'Cancel Button was clicked.' elif response_id == -1: print 'Timout occurred' - """ def __init__(self, timeout=5, **kwargs): @@ -447,26 +415,32 @@ class TimeoutAlert(Alert): class NotifyAlert(Alert): """ - Timeout alert with only an "OK" button - just for notifications + Timeout alert with only an "OK" button. This should be used just for + notifications and not for user interaction. The alert will timeout after + a given length, simmilar to a :class:`sugar3.graphics.alert.TimeoutAlert`. - Examples - -------- + Args: + timeout (int, optional): the length in seconds for the timeout to + last, defaults to 5 seconds + **kwargs: options for :class:`sugar3.graphics.alert.Alert` .. code-block:: python - from sugar3.graphics.alert import NotifyAlert - ... - #### Method: _alert_notify, create a Notify alert (with only an 'OK' - button) - # and add it to the UI. + + from sugar3.graphics.alert import NotifyAlert + + # create a Notify alert (with only an 'OK' button) then show it def _alert_notify(self): - #Notice that for a NotifyAlert, you pass the number of seconds in - #which to notify. By default, this is 5. - alert = NotifyAlert(10) - alert.props.title=_('Title of Alert Goes Here') + alert = NotifyAlert() + alert.props.title = _('Title of Alert Goes Here') alert.props.msg = _('Text message of notify alert goes here') alert.connect('response', self._alert_response_cb) self.add_alert(alert) + def __alert_response_cb(self, alert, response_id): + # Hide the alert from the user + self.remove_alert(alert) + + assert response_id == Gtk.ResponseType.OK """ def __init__(self, timeout=5, **kwargs):