Change graphics.alert docs to work well with Sphinx
This commit is contained in:
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
|
to your activity when any of these buttons are clicked, along with a
|
||||||
response_id to help you identify what button was clicked.
|
response_id to help you identify what button was clicked.
|
||||||
|
|
||||||
|
Example:
|
||||||
Examples
|
Create a simple alert message.
|
||||||
--------
|
|
||||||
create a simple alert message.
|
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
from sugar3.graphics.alert import Alert
|
from sugar3.graphics.alert import Alert
|
||||||
...
|
|
||||||
# Create a new simple alert
|
# Create a new simple alert
|
||||||
alert = Alert()
|
alert = Alert()
|
||||||
# Populate the title and text body of the 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
|
Alerts are used inside the activity window instead of being a
|
||||||
separate popup window. They do not hide canvas content. You can
|
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
|
to add and remove the alert. The position of the alert is below the
|
||||||
toolbox or top in fullscreen mode.
|
toolbox or top in fullscreen mode.
|
||||||
|
|
||||||
Properties:
|
Args:
|
||||||
'title': the title of the alert,
|
title (str): the title of the alert
|
||||||
'message': the message of the alert,
|
message (str): the message of the alert
|
||||||
'icon': the icon that appears at the far left
|
icon (str): the icon that appears at the far left
|
||||||
|
|
||||||
See __gproperties__
|
|
||||||
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
__gtype_name__ = 'SugarAlert'
|
__gtype_name__ = 'SugarAlert'
|
||||||
|
|
||||||
__gsignals__ = {
|
__gsignals__ = {
|
||||||
@ -91,7 +86,6 @@ class Alert(Gtk.EventBox):
|
|||||||
}
|
}
|
||||||
|
|
||||||
def __init__(self, **kwargs):
|
def __init__(self, **kwargs):
|
||||||
|
|
||||||
self._title = None
|
self._title = None
|
||||||
self._msg = None
|
self._msg = None
|
||||||
self._icon = None
|
self._icon = None
|
||||||
@ -129,18 +123,10 @@ class Alert(Gtk.EventBox):
|
|||||||
|
|
||||||
def do_set_property(self, pspec, value):
|
def do_set_property(self, pspec, value):
|
||||||
"""
|
"""
|
||||||
Set alert property
|
Set alert property, GObject internal method.
|
||||||
|
Use the `alert.props` object, eg::
|
||||||
Parameters
|
|
||||||
----------
|
|
||||||
pspec :
|
|
||||||
|
|
||||||
value :
|
|
||||||
|
|
||||||
Returns
|
|
||||||
-------
|
|
||||||
None
|
|
||||||
|
|
||||||
|
alert.props.title = 'Are you happy?'
|
||||||
"""
|
"""
|
||||||
if pspec.name == 'title':
|
if pspec.name == 'title':
|
||||||
if self._title != value:
|
if self._title != value:
|
||||||
@ -159,17 +145,10 @@ class Alert(Gtk.EventBox):
|
|||||||
|
|
||||||
def do_get_property(self, pspec):
|
def do_get_property(self, pspec):
|
||||||
"""
|
"""
|
||||||
Get alert property
|
Set alert property, GObject internal method.
|
||||||
|
Use the `alert.props` object, eg::
|
||||||
Parameters
|
|
||||||
----------
|
|
||||||
pspec :
|
|
||||||
property for which the value will be returned
|
|
||||||
|
|
||||||
Returns
|
|
||||||
-------
|
|
||||||
value of the property specified
|
|
||||||
|
|
||||||
|
title = alert.props.title
|
||||||
"""
|
"""
|
||||||
if pspec.name == 'title':
|
if pspec.name == 'title':
|
||||||
return self._title
|
return self._title
|
||||||
@ -180,23 +159,17 @@ class Alert(Gtk.EventBox):
|
|||||||
"""
|
"""
|
||||||
Add a button to the alert
|
Add a button to the alert
|
||||||
|
|
||||||
Parameters
|
Args:
|
||||||
----------
|
response_id (int): will be emitted with the response signal a
|
||||||
response_id :
|
response ID should one of the pre-defined GTK Response Type
|
||||||
will be emitted with the response signal a response ID should one
|
Constants or a positive number
|
||||||
of the pre-defined GTK Response Type Constants or a positive number
|
label (str): that will occure right to the buttom
|
||||||
label :
|
icon (:class:`sugar3.graphics.icon.Icon` or :class:`Gtk.Image`, optional):
|
||||||
that will occure right to the buttom
|
icon for the button, placed before the text
|
||||||
|
postion (int, optional): the position of the button in the box
|
||||||
|
|
||||||
icon :
|
Returns:
|
||||||
this can be a SugarIcon or a Gtk.Image
|
Gtk.Button: the button added to the alert
|
||||||
|
|
||||||
postion :
|
|
||||||
the position of the button in the box (optional)
|
|
||||||
|
|
||||||
Returns
|
|
||||||
-------
|
|
||||||
button :Gtk.Button
|
|
||||||
|
|
||||||
"""
|
"""
|
||||||
button = Gtk.Button()
|
button = Gtk.Button()
|
||||||
@ -215,19 +188,18 @@ class Alert(Gtk.EventBox):
|
|||||||
"""
|
"""
|
||||||
Remove a button from the alert by the given response id
|
Remove a button from the alert by the given response id
|
||||||
|
|
||||||
Parameters
|
Args:
|
||||||
----------
|
response_id (int): the same response id passed to add_button
|
||||||
response_id :
|
|
||||||
|
|
||||||
Returns
|
Returns:
|
||||||
-------
|
|
||||||
None
|
None
|
||||||
|
|
||||||
"""
|
"""
|
||||||
self._buttons_box.remove(self._buttons[response_id])
|
self._buttons_box.remove(self._buttons[response_id])
|
||||||
|
|
||||||
def _response(self, 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 result can be that a user has clicked a button or
|
||||||
a timeout has occured, the id identifies the button
|
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
|
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
|
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,
|
'OK' button will emit a response with a response_id of
|
||||||
while the 'Cancel' button will emit Gtk.ResponseType.CANCEL.
|
: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
|
.. code-block:: python
|
||||||
|
|
||||||
from sugar3.graphics.alert import ConfirmationAlert
|
from sugar3.graphics.alert import ConfirmationAlert
|
||||||
...
|
|
||||||
#### Method: _alert_confirmation, create a Confirmation alert (with ok
|
# Create a Confirmation alert (with ok and cancel buttons standard)
|
||||||
and cancel buttons standard)
|
# then add it to the UI.
|
||||||
# and add it to the UI.
|
|
||||||
def _alert_confirmation(self):
|
def _alert_confirmation(self):
|
||||||
alert = ConfirmationAlert()
|
alert = ConfirmationAlert()
|
||||||
alert.props.title=_('Title of Alert Goes Here')
|
alert.props.title=_('Title of Alert Goes Here')
|
||||||
@ -264,11 +237,9 @@ class ConfirmationAlert(Alert):
|
|||||||
alert.connect('response', self._alert_response_cb)
|
alert.connect('response', self._alert_response_cb)
|
||||||
self.add_alert(alert)
|
self.add_alert(alert)
|
||||||
|
|
||||||
|
# Called when an alert object throws a response event.
|
||||||
#### Method: _alert_response_cb, called when an alert object throws a
|
|
||||||
response event.
|
|
||||||
def _alert_response_cb(self, alert, response_id):
|
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
|
# was clicked or there was a timeout
|
||||||
self.remove_alert(alert)
|
self.remove_alert(alert)
|
||||||
|
|
||||||
@ -277,7 +248,6 @@ class ConfirmationAlert(Alert):
|
|||||||
print 'Ok Button was clicked. Do any work upon ok here ...'
|
print 'Ok Button was clicked. Do any work upon ok here ...'
|
||||||
elif response_id is Gtk.ResponseType.CANCEL:
|
elif response_id is Gtk.ResponseType.CANCEL:
|
||||||
print 'Cancel Button was clicked.'
|
print 'Cancel Button was clicked.'
|
||||||
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
def __init__(self, **kwargs):
|
def __init__(self, **kwargs):
|
||||||
@ -298,16 +268,17 @@ class ErrorAlert(Alert):
|
|||||||
|
|
||||||
An error alert is a nice shortcut from a standard Alert because it
|
An error alert is a nice shortcut from a standard Alert because it
|
||||||
comes with the 'OK' button already built-in. When clicked, the
|
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
|
.. code-block:: python
|
||||||
|
|
||||||
from sugar3.graphics.alert import ErrorAlert
|
from sugar3.graphics.alert import ErrorAlert
|
||||||
...
|
|
||||||
#### Method: _alert_error, create a Error alert (with ok
|
# Create a Error alert (with ok button standard)
|
||||||
button standard)
|
|
||||||
# and add it to the UI.
|
# and add it to the UI.
|
||||||
def _alert_error(self):
|
def _alert_error(self):
|
||||||
alert = ErrorAlert()
|
alert = ErrorAlert()
|
||||||
@ -316,18 +287,15 @@ class ErrorAlert(Alert):
|
|||||||
alert.connect('response', self._alert_response_cb)
|
alert.connect('response', self._alert_response_cb)
|
||||||
self.add_alert(alert)
|
self.add_alert(alert)
|
||||||
|
|
||||||
|
# called when an alert object throws a response event.
|
||||||
#### Method: _alert_response_cb, called when an alert object throws a
|
|
||||||
response event.
|
|
||||||
def _alert_response_cb(self, alert, response_id):
|
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
|
# was clicked or there was a timeout
|
||||||
self.remove_alert(alert)
|
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:
|
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):
|
def __init__(self, **kwargs):
|
||||||
@ -380,33 +348,34 @@ class _TimeoutIcon(Gtk.Alignment):
|
|||||||
|
|
||||||
class TimeoutAlert(Alert):
|
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
|
||||||
Examples
|
**kwargs: options for :class:`sugar3.graphics.alert.Alert`
|
||||||
--------
|
|
||||||
|
|
||||||
.. code-block:: python
|
.. code-block:: python
|
||||||
|
|
||||||
from sugar3.graphics.alert import TimeoutAlert
|
from sugar3.graphics.alert import TimeoutAlert
|
||||||
...
|
|
||||||
#### Method: _alert_timeout, create a Timeout alert (with ok and cancel
|
# Create a Timeout alert (with ok and cancel buttons standard) then
|
||||||
buttons standard)
|
# add it to the UI
|
||||||
# and add it to the UI.
|
|
||||||
def _alert_timeout(self):
|
def _alert_timeout(self):
|
||||||
#Notice that for a TimeoutAlert, you pass the number of seconds in
|
# Notice that for a TimeoutAlert, you pass the number of seconds
|
||||||
#which to timeout. By default, this is 5.
|
# in which to timeout. By default, this is 5.
|
||||||
alert = TimeoutAlert(10)
|
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.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)
|
self.add_alert(alert)
|
||||||
|
|
||||||
#### Method: _alert_response_cb, called when an alert object throws a
|
# Called when an alert object throws a response event.
|
||||||
response event.
|
def __alert_response_cb(self, alert, response_id):
|
||||||
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
|
# was clicked or there was a timeout
|
||||||
self.remove_alert(alert)
|
self.remove_alert(alert)
|
||||||
|
|
||||||
@ -417,7 +386,6 @@ class TimeoutAlert(Alert):
|
|||||||
print 'Cancel Button was clicked.'
|
print 'Cancel Button was clicked.'
|
||||||
elif response_id == -1:
|
elif response_id == -1:
|
||||||
print 'Timout occurred'
|
print 'Timout occurred'
|
||||||
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
def __init__(self, timeout=5, **kwargs):
|
def __init__(self, timeout=5, **kwargs):
|
||||||
@ -447,26 +415,32 @@ class TimeoutAlert(Alert):
|
|||||||
|
|
||||||
class NotifyAlert(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
|
.. code-block:: python
|
||||||
|
|
||||||
from sugar3.graphics.alert import NotifyAlert
|
from sugar3.graphics.alert import NotifyAlert
|
||||||
...
|
|
||||||
#### Method: _alert_notify, create a Notify alert (with only an 'OK'
|
# create a Notify alert (with only an 'OK' button) then show it
|
||||||
button)
|
|
||||||
# and add it to the UI.
|
|
||||||
def _alert_notify(self):
|
def _alert_notify(self):
|
||||||
#Notice that for a NotifyAlert, you pass the number of seconds in
|
alert = NotifyAlert()
|
||||||
#which to notify. By default, this is 5.
|
|
||||||
alert = NotifyAlert(10)
|
|
||||||
alert.props.title = _('Title of Alert Goes Here')
|
alert.props.title = _('Title of Alert Goes Here')
|
||||||
alert.props.msg = _('Text message of notify alert goes here')
|
alert.props.msg = _('Text message of notify alert goes here')
|
||||||
alert.connect('response', self._alert_response_cb)
|
alert.connect('response', self._alert_response_cb)
|
||||||
self.add_alert(alert)
|
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):
|
def __init__(self, timeout=5, **kwargs):
|
||||||
|
Loading…
Reference in New Issue
Block a user