sugar3.graphics.alert module

Alerts appear at the top of the body of your activity.

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.

Example

Create a simple alert message.

from sugar3.graphics.alert import 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.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.
self.add_alert(alert)
alert.show()

STABLE.

class sugar3.graphics.alert.Alert(**kwargs)

Bases: gi.repository.Gtk.EventBox

UI interface for Alerts

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.

Parameters:

• title (str) – the title of the alert
• message (str) – the message of the alert
• icon (str) – the icon that appears at the far left

add_button(response_id, label, icon=None, position=-1)

Add a button to the alert

Parameters:

• 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 (sugar3.graphics.icon.Icon or Gtk.Image, optional) – icon for the button, placed before the text
• postion (int, optional) – the position of the button in the box

Returns:

Gtk.Button: the button added to the alert

do_get_property(pspec)

Get alert property, GObject internal method. Use the alert.props object, eg:

title = alert.props.title

do_set_property(pspec, value)

Set alert property, GObject internal method. Use the alert.props object, eg:

alert.props.title = 'Are you happy?'

remove_button(response_id)

Remove a button from the alert by the given response id

Parameters:response_id (int) – the same response id passed to add_button Returns:None

class sugar3.graphics.alert.ConfirmationAlert(**kwargs)

Bases: sugar3.graphics.alert.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.

Parameters:**kwargs – options for sugar3.graphics.alert.Alert

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')
    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
    self.remove_alert(alert)

    # 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.'

class sugar3.graphics.alert.ErrorAlert(**kwargs)

Bases: sugar3.graphics.alert.Alert

This is a ready-made one button (Ok) 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.

Parameters:**kwargs – options for sugar3.graphics.alert.Alert

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()
    alert.props.title=_('Title of 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
    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'

class sugar3.graphics.alert.NotifyAlert(timeout=5, **kwargs)

Bases: sugar3.graphics.alert._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 sugar3.graphics.alert.TimeoutAlert.

Parameters:

• timeout (int, optional) – the length in seconds for the timeout to last, defaults to 5 seconds
• **kwargs – options for sugar3.graphics.alert.Alert

from sugar3.graphics.alert import NotifyAlert

# create a Notify alert (with only an 'OK' button) 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.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

class sugar3.graphics.alert.TimeoutAlert(timeout=5, **kwargs)

Bases: sugar3.graphics.alert._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.

Parameters:

• timeout (int, optional) – the length in seconds for the timeout to last, defaults to 5 seconds
• **kwargs – options for sugar3.graphics.alert.Alert

from sugar3.graphics.alert import TimeoutAlert

# 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.
    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)
    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
    self.remove_alert(alert)

    # 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 'Timeout occurred'