MessagingMenu.App¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` (desktop_id)
	`append_message` (msg, source_id, notify)
	`append_source` (id, icon, label)
	`append_source_with_count` (id, icon, label, count)
	`append_source_with_string` (id, icon, label, str)
	`append_source_with_time` (id, icon, label, time)
	`draw_attention` (source_id)
	`get_message` (id)
	`has_source` (source_id)
	`insert_source` (position, id, icon, label)
	`insert_source_with_count` (position, id, icon, label, count)
	`insert_source_with_string` (position, id, icon, label, str)
	`insert_source_with_time` (position, id, icon, label, time)
	`register` ()
	`remove_attention` (source_id)
	`remove_message` (msg)
	`remove_message_by_id` (id)
	`remove_source` (source_id)
	`set_source_count` (source_id, count)
	`set_source_icon` (source_id, icon)
	`set_source_label` (source_id, label)
	`set_source_string` (source_id, str)
	`set_source_time` (source_id, time)
	`set_status` (status)
	`unregister` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`desktop-id`	`str`	w/co	The desktop id of the associated application

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`activate-source`	Emitted when the user has activated the message source with id source_id.
`status-changed`	Emitted when the chat status is changed through the messaging menu.

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class MessagingMenu.App(**kwargs)¶

Bases:: GObject.Object
Abstract:: No

MessagingMenu.App is an opaque structure.

classmethod new(desktop_id)¶

Parameters:: desktop_id (str) –
Return type:: MessagingMenu.App

append_message(msg, source_id, notify)¶

Parameters:

msg (MessagingMenu.Message) – the MessagingMenu.Message to append
source_id (str or None) – the source id to which msg is added, or None
notify (bool) – whether a notification bubble should be shown for this message

Appends msg to the source with id source_id of self. The messaging menu might not display this message immediately if other messages are queued before this one.

If source_id has a count associated with it, that count will be increased by one.

If source_id is None, msg won’t be associated with a source.

append_source(id, icon, label)¶

Parameters:

id (str) – a unique identifier for the source to be added
icon (Gio.Icon or None) – the icon associated with the source
label (str) – a user-visible string best describing the source

Appends a new message source to the end of the section representing self. Equivalent to calling MessagingMenu.App.append_source_with_time() with the current time.

It is an error to add a source with an id which already exists. Use MessagingMenu.App.has_source() to find out whether there is such a source.

append_source_with_count(id, icon, label, count)¶

Parameters:

id (str) – a unique identifier for the source to be added
icon (Gio.Icon or None) – the icon associated with the source
label (str) – a user-visible string best describing the source
count (int) – the count for the source

Appends a new message source to the end of the section representing self and initializes it with count.

To update the count, use MessagingMenu.App.set_source_count().

It is an error to add a source with an id which already exists. Use MessagingMenu.App.has_source() to find out whether there is such a source.

append_source_with_string(id, icon, label, str)¶

Parameters:

id (str) – a unique identifier for the source to be added
icon (Gio.Icon or None) – the icon associated with the source
label (str) – a user-visible string best describing the source
str (str) – a string associated with the source

Appends a new message source to the end of the section representing self and initializes it with str.

To update the string, use MessagingMenu.App.set_source_string().

It is an error to insert a source with an id which already exists. Use MessagingMenu.App.has_source() to find out whether there is such a source.

append_source_with_time(id, icon, label, time)¶

Parameters:

id (str) – a unique identifier for the source to be added
icon (Gio.Icon or None) – the icon associated with the source
label (str) – a user-visible string best describing the source
time (int) – the time when the source was created, in microseconds

Appends a new message source to the end of the section representing self and initializes it with time. Use MessagingMenu.App.append_source() to append a source with the current time.

To change the time, use MessagingMenu.App.set_source_time().

It is an error to insert a source with an id which already exists. Use MessagingMenu.App.has_source() to find out whether there is such a source.

draw_attention(source_id)¶

Parameters:: source_id (str) – a source id

Indicates that source_id has important unread messages. Currently, this means that the messaging menu’s envelope icon will turn blue.

Use MessagingMenu.App.remove_attention() to stop indicating that the source needs attention.

get_message(id)¶

Parameters:: id (str) – id of the message to retrieve
Returns:: the MessagingMenu.App with id, or None
Return type:: MessagingMenu.Message or None

Retrieves the message with id, that was added with MessagingMenu.App.append_message().

has_source(source_id)¶

Parameters:: source_id (str) – a source id
Returns:: True if there is a source associated with source_id
Return type:: bool

insert_source(position, id, icon, label)¶

Parameters:

position (int) – the position at which to insert the source
id (str) – a unique identifier for the source to be added
icon (Gio.Icon) – the icon associated with the source
label (str) – a user-visible string best describing the source

Inserts a new message source into the section representing self. Equivalent to calling MessagingMenu.App.insert_source_with_time() with the current time.

It is an error to insert a source with an id which already exists. Use MessagingMenu.App.has_source() to find out whether there is such a source.

insert_source_with_count(position, id, icon, label, count)¶

Parameters:

position (int) – the position at which to insert the source
id (str) – a unique identifier for the source to be added
icon (Gio.Icon or None) – the icon associated with the source
label (str) – a user-visible string best describing the source
count (int) – the count for the source

Inserts a new message source into the section representing self and initializes it with count.

To update the count, use MessagingMenu.App.set_source_count().

It is an error to insert a source with an id which already exists. Use MessagingMenu.App.has_source() to find out whether there is such a source.

insert_source_with_string(position, id, icon, label, str)¶

Parameters:

position (int) – the position at which to insert the source
id (str) – a unique identifier for the source to be added
icon (Gio.Icon or None) – the icon associated with the source
label (str) – a user-visible string best describing the source
str (str) – a string associated with the source

Inserts a new message source into the section representing self and initializes it with str.

To update the string, use MessagingMenu.App.set_source_string().

It is an error to insert a source with an id which already exists. Use MessagingMenu.App.has_source() to find out whether there is such a source.

insert_source_with_time(position, id, icon, label, time)¶

Parameters:

position (int) – the position at which to insert the source
id (str) – a unique identifier for the source to be added
icon (Gio.Icon or None) – the icon associated with the source
label (str) – a user-visible string best describing the source
time (int) – the time when the source was created, in microseconds

Inserts a new message source into the section representing self and initializes it with time. Use MessagingMenu.App.insert_source() to insert a source with the current time.

To change the time, use MessagingMenu.App.set_source_time().

It is an error to insert a source with an id which already exists. Use MessagingMenu.App.has_source() to find out whether there is such a source.

register()¶

Registers self with the Messaging Menu.

If the application doesn’t already have a section in the Messaging Menu, one will be created for it. The application will also be marked as “running”.

The application will be marked as “not running” as soon as self is destroyed. The application launcher as well as shortcut actions will remain in the menu. To completely remove the application section from the Messaging Menu, call MessagingMenu.App.unregister().

remove_attention(source_id)¶

Parameters:: source_id (str) – a source id

Stop indicating that source_id needs attention.

This function does not need to be called when the source is removed with MessagingMenu.App.remove_source() or the user has activated the source.

Use MessagingMenu.App.draw_attention() to make source_id draw attention again.

remove_message(msg)¶

Parameters:: msg (MessagingMenu.Message) – the MessagingMenu.Message to remove

Removes msg from self.

If source_id has a count associated with it, that count will be decreased by one.

remove_message_by_id(id)¶

Parameters:: id (str) – the unique id of msg

Removes the message with the id id from self.

If source_id has a count associated with it, that count will be decreased by one.

remove_source(source_id)¶

Parameters:: source_id (str) – the id of the source to remove

Removes the source corresponding to source_id from the menu.

set_source_count(source_id, count)¶

Parameters:

source_id (str) – a source id
count (int) – the new count for the source

Updates the count of source_id to count.

set_source_icon(source_id, icon)¶

Parameters:

source_id (str) – a source id
icon (Gio.Icon or None) – the new icon for the source

Changes the icon of source_id to icon.

set_source_label(source_id, label)¶

Parameters:

source_id (str) – a source id
label (str) – the new label for the source

Changes the label of source_id to label.

set_source_string(source_id, str)¶

Parameters:

source_id (str) – a source id
str (str) – the new string for the source

Updates the string displayed next to source_id to str.

set_source_time(source_id, time)¶

Parameters:

source_id (str) – a source id
time (int) – the new time for the source, in microseconds

Updates the time of source_id to time.

set_status(status)¶

Parameters:: status (MessagingMenu.Status) – a MessagingMenu.Status

Notify the Messaging Menu that the chat status of self has changed to status.

Connect to the ::status-changed signal to receive notification about the user changing their global chat status through the Messaging Menu.

This function does nothing for applications whose desktop file does not include X-MessagingMenu-UsesChatSection.

unregister()¶

Completely removes the self from the Messaging Menu. If the application’s launcher and shortcut actions should remain in the menu, destroying self with GObject.Object.unref() suffices.

Note: self will remain valid and usable after this call.

Signal Details¶

MessagingMenu.App.signals.activate_source(app, source_id)¶

Signal Name:

activate-source

Flags:

RUN_FIRST, DETAILED

Parameters:

app (MessagingMenu.App) – The object which received the signal
source_id (str) – the source id that was activated

Emitted when the user has activated the message source with id source_id. The source is immediately removed from the menu, handlers of this signal do not need to call MessagingMenu.App.remove_source().

MessagingMenu.App.signals.status_changed(app, status)¶

Signal Name:

status-changed

Flags:

RUN_FIRST

Parameters:

app (MessagingMenu.App) – The object which received the signal
status (int) – a MessagingMenu.Status

Emitted when the chat status is changed through the messaging menu.

Applications which are registered to use the chat status should change their status to status upon receiving this signal. Call MessagingMenu.App.set_status() to acknowledge that the application changed its status.

Property Details¶

MessagingMenu.App.props.desktop_id¶

Name:: desktop-id
Type:: str
Default Value:: None
Flags:: WRITABLE, CONSTRUCT_ONLY

The desktop id of the application associated with this application section. Must be given when the MessagingMenu.App is created.