sugarlabs/sugar-toolkit-gtk3
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Change graphics.alert docs to work well with Sphinx

Browse Source
This commit is contained in:
Sam Parkinson 2015-08-02 08:47:22 +10:00 committed by Gonzalo Odiard
parent b9f19521fe
commit 0bed21ccc8
1 changed files with 102 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

230
src/sugar3/graphics/alert.py
View File

@ -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 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:
Create a simple alert message.
Examples .. code-block:: python
--------
create a simple alert message.
.. 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.
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') alert.props.msg = _('Text message of alert goes here')
# Call the add_alert() method (inherited via the sugar3.graphics.Window # Call the add_alert() method (inherited via the sugar3.graphics.Window
# superclass of Activity) to add this alert to the activity 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 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
@ -241,22 +213,23 @@ class Alert(Gtk.EventBox):
class ConfirmationAlert(Alert): 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 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
and cancel buttons standard) # Create a Confirmation alert (with ok and cancel buttons standard)
# and add it to the UI. # then 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,20 +237,17 @@ 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)
#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: 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 ...'
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
button standard) # Create a Error alert (with ok 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,44 +348,44 @@ 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
buttons standard) # Create a Timeout alert (with ok and cancel buttons standard) then
# and add it to the UI. # 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)
#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: 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 ...'
elif response_id is Gtk.ResponseType.CANCEL: elif response_id is Gtk.ResponseType.CANCEL:
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'
button) # create a Notify alert (with only an 'OK' button) then show it
# 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.props.title = _('Title of Alert Goes Here')
alert = NotifyAlert(10)
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):