sugar3.graphics.alert module

Alerts appear in an activity below the toolbox and above the canvas.

Alert and the derived TimeoutAlert, ConfirmationAlert, ErrorAlert, and NotifyAlert, each have a title, a message and optional buttons.

Alert will emit a response signal when a button is clicked.

The TimeoutAlert and NotifyAlert display a countdown and will emit a response signal when a timeout occurs.

Example

Create a simple alert message.

from sugar3.graphics.alert import Alert

# Create a new simple alert
alert = 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')

# Add the alert to the activity
self.add_alert(alert)
alert.show()

STABLE.

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

Bases: gi.repository.Gtk.EventBox

Alerts are inside the activity window instead of being a separate popup window. They do not hide the canvas.

Use add_alert() and remove_alert() to add and remove an alert. These methods are inherited by an Activity via superclass Window.

The alert is placed between the canvas and the toolbox, or above the canvas 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)

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.

Parameters

• response_id (int) – the response identifier, a Gtk.ResponseType constant or any positive integer,

• label (str) – a label for the button

• icon (Icon or Gtk.Image, optional) – an icon for the button

• position (int, optional) – the position of the button in the box of buttons,

Returns

the button added to the alert

Return type

Gtk.Button

add_entry()

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 Gtk.Entry signal handler.

Returns

the entry added to the alert

Return type

Gtk.Entry

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.

The button is selected for removal using the response identifier that was passed to add_button().

Parameters

response_id (int) – the response identifier

Returns

None

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

Bases: sugar3.graphics.alert.Alert

An alert with two buttons; Ok and Cancel.

When a button is clicked, the ConfirmationAlert will emit a response signal with a response identifier. For the Ok button, the response identifier will be Gtk.ResponseType.OK. For the Cancel button, Gtk.ResponseType.CANCEL.

Parameters

**kwargs – parameters for Alert

from sugar3.graphics.alert import ConfirmationAlert

# Create a Confirmation alert and 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 sends a response signal.
def _alert_response_cb(self, alert, response_id):
    # Remove the alert
    self.remove_alert(alert)

    # Check the response identifier.
    if response_id is Gtk.ResponseType.OK:
        print('Ok Button was clicked.')
    elif response_id is Gtk.ResponseType.CANCEL:
        print('Cancel Button was clicked.')

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

Bases: sugar3.graphics.alert.Alert

An alert with one button; Ok.

When the button is clicked, the ErrorAlert will emit a response signal with a response identifier Gtk.ResponseType.OK.

Parameters

**kwargs – parameters for Alert

from sugar3.graphics.alert import ErrorAlert

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

    # Check the response identifier.
    if response_id is Gtk.ResponseType.OK:
        print('Ok Button was clicked.')

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

Bases: 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 NotifyAlert will emit a response signal with a response identifier Gtk.ResponseType.OK.

If the countdown reaches zero before the button is clicked, the NotifyAlert will emit a response signal with a response identifier of -1.

Parameters

• timeout (int, optional) – time in seconds, default 5

• **kwargs – parameters for Alert

from sugar3.graphics.alert import NotifyAlert

# 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 alert goes here')
    alert.connect('response', self._alert_response_cb)
    self.add_alert(alert)

def __alert_response_cb(self, alert, response_id):
    # Remove the alert
    self.remove_alert(alert)

    # Check the response identifier.
    if response_id is Gtk.ResponseType.OK:
        print('Ok Button was clicked.')
    elif response_id == -1:
        print('Timeout occurred')

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

Bases: sugar3.graphics.alert._TimeoutAlert

A timed alert with two buttons; Continue and Cancel. The Continue button contains a countdown of seconds remaining.

When a button is clicked, the TimeoutAlert will emit a response signal with a response identifier. For the Continue button, the response identifier will be Gtk.ResponseType.OK. For the Cancel button, Gtk.ResponseType.CANCEL.

If the countdown reaches zero before a button is clicked, the TimeoutAlert will emit a response signal with a response identifier of -1.

Parameters

• timeout (int, optional) – time in seconds, default 5

• **kwargs – parameters for Alert

from sugar3.graphics.alert import TimeoutAlert

# Create a Timeout alert and add it to the UI
def _alert_timeout(self):
    alert = TimeoutAlert(timeout=10)
    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
    self.remove_alert(alert)

    # Check the response identifier.
    if response_id is Gtk.ResponseType.OK:
        print('Continue Button was clicked.')
    elif response_id is Gtk.ResponseType.CANCEL:
        print('Cancel Button was clicked.')
    elif response_id == -1:
        print('Timeout occurred')