Change graphics.alert docs to work well with Sphinx
This commit is contained in:
Sam Parkinson
Gonzalo Odiard
parent
b9f19521fe
commit
0bed21ccc8
@ -7,14 +7,13 @@ 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.
|
||||
Example:
|
||||
Create a simple alert message.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from sugar3.graphics.alert import Alert
|
||||
...
|
||||
|
||||
# Create a new simple alert
|
||||
alert = Alert()
|
||||
# Populate the title and text body of the alert.
|
||||
@ -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
|
||||
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
|
||||
|
||||
icon :
|
||||
this can be a SugarIcon or a Gtk.Image
|
||||
|
||||
postion :
|
||||
the position of the button in the box (optional)
|
||||
|
||||
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
|
||||
-------
|
||||
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
|
||||
@ -245,18 +217,19 @@ class ConfirmationAlert(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.
|
||||
|
||||
# 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,11 +237,9 @@ 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
|
||||
# Remove the alert from the screen, since either a response button
|
||||
# was clicked or there was a timeout
|
||||
self.remove_alert(alert)
|
||||
|
||||
@ -277,7 +248,6 @@ class ConfirmationAlert(Alert):
|
||||
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)
|
||||
|
||||
# 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
|
||||
# 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.
|
||||
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,33 +348,34 @@ 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.
|
||||
|
||||
|
||||
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 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.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
|
||||
# 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)
|
||||
|
||||
@ -417,7 +386,6 @@ class TimeoutAlert(Alert):
|
||||
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.
|
||||
|
||||
# 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 = 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):
|
||||
|
||||
Loading…
Reference in New Issue
Block a user