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

Documentation - rewrite activity section

Browse Source 
- rewrite of activity section, bundle section, graphics.alert, and
  graphics.window.
This commit is contained in:
James Cameron
2017-07-19 17:31:09 +10:00
parent 4652b7ca2a
commit 5750773dda
5 changed files with 663 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/sugar3/graphics/alert.py
+113 -79
View File
@@ -1,11 +1,16 @@
"""
Alerts appear at the top of the body of your activity.
Alerts appear in an activity below the toolbox and above the canvas.
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.
:class:`Alert` and the derived :class:`TimeoutAlert`,
:class:`ConfirmationAlert`, :class:`ErrorAlert`, and
:class:`NotifyAlert`, each have a title, a message and optional
buttons.
:class:`Alert` will emit a `response` signal when a button is
clicked.
The :class:`TimeoutAlert` and :class:`NotifyAlert` display a countdown
and will emit a `response` signal when a timeout occurs.
Example:
Create a simple alert message.
@@ -16,11 +21,12 @@ Example:
# Create a new simple alert
alert = Alert()
# Populate the title and text body of the alert.
# Set 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 sugar3.graphics.Window
# superclass of Activity) to add this alert to the activity window.
# Add the alert to the activity
self.add_alert(alert)
alert.show()
@@ -60,13 +66,17 @@ _ = lambda msg: gettext.dgettext('sugar-toolkit-gtk3', msg)
class Alert(Gtk.EventBox):
"""
UI interface for Alerts
Alerts are inside the activity window instead of being a
separate popup window. They do not hide the canvas.
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()` 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.
Use :func:`~sugar3.graphics.window.Window.add_alert` and
:func:`~sugar3.graphics.window.Window.remove_alert` to add and
remove an alert. These methods are inherited by an
:class:`~sugar3.activity.activity.Activity` via superclass
:class:`~sugar3.graphics.window.Window`.
The alert is placed between the canvas and the toolbox, or above
the canvas in fullscreen mode.
Args:
title (str): the title of the alert
@@ -159,10 +169,16 @@ class Alert(Gtk.EventBox):
def add_entry(self):
"""
Add an entry, after the title and before the buttons.
Create an entry and add it to the alert.
The entry is placed after the title and before the buttons.
Caller is responsible for capturing the entry text in the
`response` signal handler or a :class:`Gtk.Entry` signal
handler.
Returns:
Gtk.Entry: the entry added to the alert
:class:`Gtk.Entry`: the entry added to the alert
"""
entry = Gtk.Entry()
self._hbox.pack_start(entry, True, True, 0)
@@ -175,19 +191,26 @@ class Alert(Gtk.EventBox):
def add_button(self, response_id, label, icon=None, position=-1):
"""
Add a button to the alert
Create a button and add it to the alert.
The button is added to the end of the alert.
When the button is clicked, the `response` signal will be
emitted, along with a response identifier.
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
response_id (int): the response identifier, a
:class:`Gtk.ResponseType` constant or any positive
integer,
label (str): a label for the button
icon (:class:`~sugar3.graphics.icon.Icon` or \
:class:`Gtk.Image`, optional):
an icon for the button
position (int, optional): the position of the button in
the box of buttons,
Returns:
Gtk.Button: the button added to the alert
:class:`Gtk.Button`: the button added to the alert
"""
button = Gtk.Button()
@@ -204,10 +227,13 @@ class Alert(Gtk.EventBox):
def remove_button(self, response_id):
"""
Remove a button from the alert by the given response id
Remove a button from the alert.
The button is selected for removal using the response
identifier that was passed to :func:`add_button`.
Args:
response_id (int): the same response id passed to add_button
response_id (int): the response identifier
Returns:
None
@@ -233,23 +259,22 @@ if hasattr(Alert, 'set_css_name'):
class ConfirmationAlert(Alert):
"""
This is a ready-made two button (Cancel, Ok) alert.
An alert with two buttons; Ok and Cancel.
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
:class:`Gtk.ResponseType.OK`, while the 'Cancel' button will emit
When a button is clicked, the :class:`ConfirmationAlert` will emit
a `response` signal with a response identifier. For the Ok
button, the response identifier will be
:class:`Gtk.ResponseType.OK`. For the Cancel button,
:class:`Gtk.ResponseType.CANCEL`.
Args:
**kwargs: options for :class:`sugar3.graphics.alert.Alert`
**kwargs: parameters for :class:`~sugar3.graphics.alert.Alert`
.. code-block:: python
from sugar3.graphics.alert import ConfirmationAlert
# Create a Confirmation alert (with ok and cancel buttons standard)
# then add it to the UI.
# Create a Confirmation alert and add it to the UI.
def _alert_confirmation(self):
alert = ConfirmationAlert()
alert.props.title=_('Title of Alert Goes Here')
@@ -257,15 +282,14 @@ class ConfirmationAlert(Alert):
alert.connect('response', self._alert_response_cb)
self.add_alert(alert)
# Called when an alert object throws a response event.
# Called when an alert object sends a response signal.
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
self.remove_alert(alert)
# Do any work that is specific to the type of button clicked.
# Check the response identifier.
if response_id is Gtk.ResponseType.OK:
print 'Ok Button was clicked. Do any work upon ok here ...'
print 'Ok Button was clicked.'
elif response_id is Gtk.ResponseType.CANCEL:
print 'Cancel Button was clicked.'
"""
@@ -284,22 +308,20 @@ class ConfirmationAlert(Alert):
class ErrorAlert(Alert):
"""
This is a ready-made one button (Ok) alert.
An alert with one button; Ok.
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
When the button is clicked, the :class:`ErrorAlert` will
emit a `response` signal with a response identifier
:class:`Gtk.ResponseType.OK`.
Args:
**kwargs: options for :class:`sugar3.graphics.alert.Alert`
**kwargs: parameters for :class:`~sugar3.graphics.alert.Alert`
.. code-block:: python
from sugar3.graphics.alert import ErrorAlert
# Create a Error alert (with ok button standard)
# and add it to the UI.
# Create a Error alert and add it to the UI.
def _alert_error(self):
alert = ErrorAlert()
alert.props.title=_('Title of Alert Goes Here')
@@ -309,13 +331,12 @@ class ErrorAlert(Alert):
# 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
self.remove_alert(alert)
# Do any work that is specific to the response_id.
# Check the response identifier.
if response_id is Gtk.ResponseType.OK:
print 'Ok Button was clicked. Do any work upon ok here'
print 'Ok Button was clicked.'
"""
def __init__(self, **kwargs):
@@ -396,40 +417,43 @@ class _TimeoutAlert(Alert):
class TimeoutAlert(_TimeoutAlert):
"""
This is a ready-made two button (Continue, Cancel) 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.
A timed alert with two buttons; Continue and Cancel. The Continue
button contains a countdown of seconds remaining.
When a button is clicked, the :class:`TimeoutAlert` will emit
a `response` signal with a response identifier. For the Continue
button, the response identifier will be
:class:`Gtk.ResponseType.OK`. For the Cancel button,
:class:`Gtk.ResponseType.CANCEL`.
If the countdown reaches zero before a button is clicked, the
:class:`TimeoutAlert` will emit a `response` signal with a
response identifier of -1.
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`
timeout (int, optional): time in seconds, default 5
**kwargs: parameters for :class:`~sugar3.graphics.alert.Alert`
.. code-block:: python
from sugar3.graphics.alert import TimeoutAlert
# Create a Timeout alert (with ok and cancel buttons standard) then
# add it to the UI
# Create a Timeout alert and 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.
alert = TimeoutAlert(10)
alert = TimeoutAlert(timeout=10)
alert.props.title = _('Title of Alert Goes Here')
alert.props.msg = _('Text message of timeout alert goes here')
alert.props.msg = _('Text message of alert goes here')
alert.connect('response', self.__alert_response_cb)
self.add_alert(alert)
# 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
self.remove_alert(alert)
# Do any work that is specific to the type of button clicked.
# Check the response identifier.
if response_id is Gtk.ResponseType.OK:
print 'Ok Button was clicked. Do any work upon ok here ...'
print 'Continue Button was clicked.'
elif response_id is Gtk.ResponseType.CANCEL:
print 'Cancel Button was clicked.'
elif response_id == -1:
@@ -446,32 +470,42 @@ class TimeoutAlert(_TimeoutAlert):
class NotifyAlert(_TimeoutAlert):
"""
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, similar to a :class:`sugar3.graphics.alert.TimeoutAlert`.
A timed alert with one button; Ok. The button contains a
countdown of seconds remaining.
When the button is clicked, the :class:`NotifyAlert` will
emit a `response` signal with a response identifier
:class:`Gtk.ResponseType.OK`.
If the countdown reaches zero before the button is clicked, the
:class:`NotifyAlert` will emit a `response` signal with a
response identifier of -1.
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`
timeout (int, optional): time in seconds, default 5
**kwargs: parameters for :class:`~sugar3.graphics.alert.Alert`
.. code-block:: python
from sugar3.graphics.alert import NotifyAlert
# create a Notify alert (with only an 'OK' button) then show it
# create a Notify alert then show it
def _alert_notify(self):
alert = NotifyAlert()
alert.props.title = _('Title of Alert Goes Here')
alert.props.msg = _('Text message of notify alert goes here')
alert.props.msg = _('Text message of 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
# Remove the alert
self.remove_alert(alert)
assert response_id == Gtk.ResponseType.OK
# Check the response identifier.
if response_id is Gtk.ResponseType.OK:
print 'Ok Button was clicked.'
elif response_id == -1:
print 'Timeout occurred'
"""
def __init__(self, timeout=5, **kwargs):