Diff for "SystemIndicatorMockups" - Ayatana Indicators Wiki

Differences between revisions 1 and 3 (spanning 2 versions)

Introduction

The System Components are a set of widgets that are usable in both the indicators and system settings to ensure a consistent semantics exist between both Unity 7 and Unity 8.

Contents

Introduction
Base Attributes
Types and Profiles
Indicator Positions
1. Desktop
2. Phone
Widget Definitions

Base Attributes

Name	Type
label	string
action	string	Name of the action to activate when the menuitem is clicked
target	string	Parameter to send with the action invocation
icon	bytearray	Use g_icon_deserialize()
render-as-switch	boolean	Show a switch instead of a check mark for boolean actions

Types and Profiles

Widget	Desktop	Phone	Tablet	TV
Slider	☑	☑	☐	☐
Progress	☐	☑	☐	☐
Button	☐	☑	☐	☐
User Session	☑	☐	☐	☐
Calendar	☑	☐	☐	☐
Media Player	☑	☐	☐	☐
Time Zone	☑	☐	☐	☐
Appointment	☑	☑	☐	☐
Alarm	☑	☑	☐	☐
Access Point	☒	☑	☐	☐
Message	☑	☑	☐	☐

Indicator Positions

Each indicator may have a Position field in its indicator file, which determines the order in which indicators appear in the panel. The lower the position, the further towards the edge of the panel (right in LTR-layouts, left in RTL-layouts) an indicator appears.

Desktop

These are the positions for the standard indicators [1]:

Keyboard	80
Sync	70
Location	60
Messages	50
Power	40
Bluetooth	36
Network	35
Sound	30
Datetime	20
Session	10

[1] https://wiki.ubuntu.com/MenuBar#system-status

Phone

Messages	100
Display	90
Transfer	71
Location	60
Bluetooth	36
Network	35
Sound	30
Power	25
Datetime	20

Widget Definitions

Root Item

The base item implemented by all indicators.

Property Name	Type	Description
x-canonical-type	s	com.canonical.indicator.root
action	a{sv}	Name of an action action whose state contains the props bellow
x-canonical-secondary-action	s	Name of an action that is activated when the middle mouse button is pressed on an indicator
x-canonical-scroll-action	s	Name of an action that is activated when scrolling the mouse wheel on an indicator. That action must take an int32 parameter signifying strength and direction of the scroll

The action that the root item points to is an a{sv}.

Action Prop	Type	Description
label	s	String with label
accessible-desc	s	String used to describe the state for disabled users
icon	v	Serialized GIcon
visible	b	Whether to show the icon
pre-label	s	Label to be shown before the icon (LTR on left side, RTL on right)
icons	av	If there is more than one icon shown, this should be an array of serialized GIcons in the order they should appear. This item should take precedence over 'icon'.
title	s	User visible string to show at the head of the menu for the items in it

Progress

A menu item that contains a progress bar.

Property Name	Type	Description
x-canonical-type	s	com.canonical.indicator.progress
label	s	String with label
action	s	Name of an action action whose state contains the progress (uint32 in [0, 100])

Appointment

Sample implementation (for GTK+ in Unity 7): http://bazaar.launchpad.net/~charlesk/ido/add-progress-menu-item/view/head:/src/idoappointmentmenuitem.c#L72

Property Name	Type	Description
x-canonical-type	s	com.canonical.indicator.appointment
label	s	String with label
action	s	String with an action name
x-canonical-color	s	String specifying a color that can be used as a visual hint for the appointment's type. On the desktop this is set by the user when adding the appointment.
x-canonical-time-format	s	A strftime(3) format string specifying how to display the appointment's time.
x-canonical-time	x	A time_t specifying the appointment's localtime

Alarm

Alarm's properties are nearly identical to Appointment except for the added icon. Its has its own x-canonical-type to preserve the semantic difference.

Sample implementation (for GTK+ in Unity 7): http://bazaar.launchpad.net/~charlesk/ido/add-progress-menu-item/view/head:/src/idoalarmmenuitem.c

Property Name	Type	Description
x-canonical-type	s	com.canonical.indicator.alarm
label	s	String with label
icon	s	Serialized GIcon
action	s	String with an action name
x-canonical-color	s	String specifying a color that can be used as a visual hint for the appointment's type.
x-canonical-time-format	s	A strftime(3) format string specifying how to display the alarm's time.
x-canonical-time	x	A time_t specifying the alarm's localtime

Time Zone

By having properties for the location's timezone and time format string, the renderer has all the information it needs to periodically update its display of the current time. This way the refresh logic can be on the renderer's side and the service doesn't have to continually ship out new menuitems over the bus when the current time changes.

Sample implementation (for GTK+ in Unity7): http://bazaar.launchpad.net/~charlesk/ido/add-progress-menu-item/view/head:/src/idolocationmenuitem.c#L295

Property Name	Type	Description
x-canonical-type	s	com.canonical.indicator.location
label	s	String with label
x-canonical-time-format	s	A strftime(3) format string specifying how to display the location's current time.
x-canonical-timezone	s	timezone that the location is in.

Calendar

Property Name	Type	Description
x-canonical-type	s	com.canonical.indicator.progress
action	s	name of an action containing the calendar's state as an "a{sv}". Possible keys are: calendar-day (t), show-week-numbers (b), appointment-days (ai).

Calendar's Action

Key	Value Type	Description
calendar-day	t	a time_t denoting which year & month should be visible in the calendard and which day currently has focus/selection.
show-week-numbers	b	Whether or not to show the week numbers in the calendar.
appointment-days	ai	array of int32 day-of-months showing days with appointments in the month specified by calendar-day

Slider

Property Name	Type	Description
x-canonical-type	s	com.canonical.unity.slider
action	s	name of an action with state "d", the position of the slider
min-value	d	minimum value
max-value	d	maximum value
step	d	step increment
min-icon	v	an icon representing the minimum value
max-icon	v	an icon representing the maximum value

Media Player

A menu item representing a media player. Its state includes metadata about the currently playing track.

Property Name	Type	Description
x-canonical-type	s	com.canonical.unity.media-player
label	s	name of the player
action	s	name of an action containing the state of the player as an "a{sv}". Possible keys are : running (b), title (s), artist (s), album(s), art-url (s).
icon	v	app icon of the player

Playback

A menu item with playback controls.

Property Name	Type	Description
x-canonical-type	s	com.canonical.unity.playback-item
x-canonical-play-action	s	name of a play/pause action with string state ("Playing", "Stopped", "Launching")
x-canonical-previous-action	s	name of a stateless action for going to the previous track
x-canonical-next-action	s	name of a stateless action for going to the previous track

-  ⇤ ← Revision 1 as of 2020-12-01 15:32:24 → 
  Size: 8717
  Editor: MeritBusch
  Comment:
+   ← Revision 3 as of 2020-12-05 15:50:23 → ⇥
  Size: 10919
  Editor: MeritBusch
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-Introduction
+== Introduction ==
 Line 5:
-Inhaltsverzeichnis
+<<TableOfContents()>>
 Line 7:
-    Introduction
    Base Attributes
    Types and Profiles
    Indicator Positions
        Desktop
        Phone
    Widget Definitions
        Root Item
        Progress
        Appointment
        Alarm
        Time Zone
        Calendar
            Calendar's Action
        Slider
        Media Player
        Playback
+== Base Attributes ==
-Line 25:
+Line 9:
-Base Attributes
+|| '''Name'''                || '''Type'''    || ||
|| label                     || string        || ||
|| action                    || string        || Name of the action to activate when the menuitem is clicked ||
|| target                    || string        || Parameter to send with the action invocation ||
|| icon                      || bytearray     || Use g_icon_deserialize() ||
|| render-as-switch          || boolean       || Show a switch instead of a check mark for boolean actions ||
-Line 27:
+Line 16:
-Name
+== Types and Profiles ==
-Line 30:
+Line 18:
-Type
+|| '''Widget''' || '''Desktop''' || '''Phone''' || '''Tablet''' || '''TV''' ||
|| Slider       || ☑             || ☑           || ☐            || ☐        ||
|| Progress     || ☐             || ☑           || ☐            || ☐        ||
|| Button       || ☐             || ☑           || ☐            || ☐        ||
|| User Session || ☑             || ☐           || ☐            || ☐        ||
|| Calendar     || ☑             || ☐           || ☐            || ☐        ||
|| Media Player || ☑             || ☐           || ☐            || ☐        ||
|| Time Zone    || ☑             || ☐           || ☐            || ☐        ||
|| Appointment  || ☑             || ☑           || ☐            || ☐        ||
|| Alarm        || ☑             || ☑           || ☐            || ☐        ||
|| Access Point || ☒             || ☑           || ☐            || ☐        ||
|| Message      || ☑             || ☑           || ☐            || ☐        ||
-Line 33:
+Line 31:
-label
+== Indicator Positions ==
-Line 36:
+Line 33:
-string
+Each indicator may have a `Position` field in its indicator file, which determines the order in which indicators appear in the panel. The lower the position, the further towards the edge of the panel (right in LTR-layouts, left in RTL-layouts) an indicator appears.
-Line 39:
+Line 35:
-action
 

string
 

Name of the action to activate when the menuitem is clicked

target
 

string
 

Parameter to send with the action invocation

icon
 

bytearray
 

Use g_icon_deserialize()

render-as-switch
 

boolean
 

Show a switch instead of a check mark for boolean actions

Types and Profiles

Widget
 

Desktop
 

Phone
 

Tablet
 

TV

Slider
 

☑
 

☑
 

☐
 

☐

Progress
 

☐
 

☑
 

☐
 

☐

Button
 

☐
 

☑
 

☐
 

☐

User Session
 

☑
 

☐
 

☐
 

☐

Calendar
 

☑
 

☐
 

☐
 

☐

Media Player
 

☑
 

☐
 

☐
 

☐

Time Zone
 

☑
 

☐
 

☐
 

☐

Appointment
 

☑
 

☑
 

☐
 

☐

Alarm
 

☑
 

☑
 

☐
 

☐

Access Point
 

☒
 

☑
 

☐
 

☐

Message
 

☑
 

☑
 

☐
 

☐

Indicator Positions

Each indicator may have a Position field in its indicator file, which determines the order in which indicators appear in the panel. The lower the position, the further towards the edge of the panel (right in LTR-layouts, left in RTL-layouts) an indicator appears.

Desktop
+=== Desktop ===
-Line 249:
+Line 39:
-Keyboard
 

80

Sync
 

70

Location
 

60

Messages
 

50

Power
 

40

Bluetooth
 

36

Network
 

35

Sound
 

30

Datetime
 

20

Session
 

10
+|| Keyboard  || 80 ||
|| Sync      || 70 ||
|| Location  || 60 ||
|| Messages  || 50 ||
|| Power     || 40 ||
|| Bluetooth || 36 ||
|| Network   || 35 ||
|| Sound     || 30 ||
|| Datetime  || 20 ||
|| Session   || 10 ||
-Line 301:
+Line 52:
-Phone
+=== Phone ===
-Line 303:
+Line 54:
-Messages
+|| Messages  || 100 ||
|| Display   || 90 ||
|| Transfer  || 71 ||
|| Location  || 60 ||
|| Bluetooth || 36 ||
|| Network   || 35 ||
|| Sound     || 30 ||
|| Power     || 25 ||
|| Datetime  || 20 ||
-Line 306:
+Line 64:
-Line 308:
+Line 65:
-Display
 

90

Transfer
 

71

Location
 

60

Bluetooth
 

36

Network
 

35

Sound
 

30

Power
 

25

Datetime
 

20

Widget Definitions

Root Item
+== Widget Definitions ==
=== Root Item ===
-Line 354:
+Line 70:
-Property Name
   Type
 

Description

x-canonical-type
 

s
 

com.canonical.indicator.root

action
 

a{sv}
   Name of an action action whose state contains the props bellow

x-canonical-secondary-action
   s
 

Name of an action that is activated when the middle mouse button is pressed on an indicator

x-canonical-scroll-action
   s
 

Name of an action that is activated when scrolling the mouse wheel on an indicator. That action must take an int32 parameter signifying strength and direction of the scroll
+|| '''Property Name''' || '''Type''' || '''Description'''                        ||
|| x-canonical-type    || s          || com.canonical.indicator.root             ||
|| action              || a{sv}      || Name of an action action whose state contains the props bellow ||
|| x-canonical-secondary-action || s || Name of an action that is activated when the middle mouse button is pressed on an indicator ||
|| x-canonical-scroll-action    || s || Name of an action that is activated when scrolling the mouse wheel on an indicator. That action must take an int32 parameter signifying strength and direction of the scroll ||
-Line 396:
+Line 78:
-Action Prop
+|| '''Action Prop'''   || '''Type''' || '''Description'''                        ||
|| label               || s          || String with label                        ||
|| accessible-desc     || s          || String used to describe the state for disabled users ||
|| icon                || v          || Serialized GIcon                         ||
|| visible             || b          || Whether to show the icon                 ||
|| pre-label           || s          || Label to be shown before the icon (LTR on left side, RTL on right) ||
|| icons               || av         || If there is more than one icon shown, this should be an array of serialized GIcons in the order they should appear.  This item should take precedence over 'icon'. ||
|| title               || s          || User visible string to show at the head of the menu for the items in it ||
-Line 399:
+Line 87:
-Type
-Line 402:
+Line 88:
-Description
-Line 404:
+Line 89:
-label
 

s
 

String with label

accessible-desc
 

s
 

String used to describe the state for disabled users

icon
 

v
 

Serialized GIcon

visible
 

b
 

Whether to show the icon

pre-label
 

s
 

Label to be shown before the icon (LTR on left side, RTL on right)

icons
 

av
 

If there is more than one icon shown, this should be an array of serialized GIcons in the order they should appear. This item should take precedence over 'icon'.

title
 

s
 

User visible string to show at the head of the menu for the items in it

Progress
+=== Progress ===
-Line 464:
+Line 93:
-Property Name
+|| '''Property Name''' || '''Type''' || '''Description'''                        ||
|| x-canonical-type    || s          || com.canonical.indicator.progress         ||
|| label               || s          || String with label                        ||
|| action              || s          || Name of an action action whose state contains the progress (uint32 in [0, 100]) ||
-Line 467:
+Line 98:
-Type
 

Description

x-canonical-type
 

s
 

com.canonical.indicator.progress

label
 

s
 

String with label

action
 

s
 

Name of an action action whose state contains the progress (uint32 in [0, 100])

Appointment
+=== Appointment ===
-Line 500:
+Line 102:
-Property Name
+|| '''Property Name'''     || '''Type''' || '''Description'''                        ||
|| x-canonical-type        || s          || com.canonical.indicator.appointment      ||
|| label                   || s          || String with label                        ||
|| action                  || s          || String with an action name               ||
|| x-canonical-color       || s          || String specifying a color that can be used as a visual hint for the appointment's type. On the desktop this is set by the user when adding the appointment. ||
|| x-canonical-time-format || s          || A strftime(3) format string specifying how to display the appointment's time. ||
|| x-canonical-time        || x          || A time_t specifying the appointment's localtime ||
-Line 503:
+Line 110:
-Type
 

Description

x-canonical-type
 

s
 

com.canonical.indicator.appointment

label
 

s
 

String with label

action
 

s
 

String with an action name

x-canonical-color
 

s
 

String specifying a color that can be used as a visual hint for the appointment's type. On the desktop this is set by the user when adding the appointment.

x-canonical-time-format
 

s
 

A strftime(3) format string specifying how to display the appointment's time.

x-canonical-time
 

x
 

A time_t specifying the appointment's localtime

Alarm
+=== Alarm ===
-Line 562:
+Line 116:
-Property Name
+|| '''Property Name'''     || '''Type''' || '''Description'''                        ||
|| x-canonical-type        || s          || com.canonical.indicator.alarm            ||
|| label                   || s          || String with label                        ||
|| icon                    || s          || Serialized GIcon                         ||
|| action                  || s          || String with an action name               ||
|| x-canonical-color       || s          || String specifying a color that can be used as a visual hint for the appointment's type. ||
|| x-canonical-time-format || s          || A strftime(3) format string specifying how to display the alarm's time. ||
|| x-canonical-time        || x          || A time_t specifying the alarm's localtime ||
-Line 565:
+Line 125:
-Type
-Line 568:
+Line 126:
-Description

x-canonical-type
 

s
 

com.canonical.indicator.alarm

label
 

s
 

String with label

icon
 

s
 

Serialized GIcon

action
 

s
 

String with an action name

x-canonical-color
 

s
 

String specifying a color that can be used as a visual hint for the appointment's type.

x-canonical-time-format
 

s
 

A strftime(3) format string specifying how to display the alarm's time.

x-canonical-time
 

x
 

A time_t specifying the alarm's localtime

Time Zone
+=== Time Zone ===
-Line 632:
+Line 132:
-Property Name
+|| '''Property Name'''     || '''Type''' || '''Description'''                        ||
|| x-canonical-type        || s          || com.canonical.indicator.location         ||
|| label                   || s          || String with label                        ||
|| x-canonical-time-format || s          || A strftime(3) format string specifying how to display the location's current time. ||
|| x-canonical-timezone    || s          || timezone that the location is in.        ||
-Line 635:
+Line 138:
-Type
-Line 638:
+Line 139:
-Description
+=== Calendar ===
|| '''Property Name''' || '''Type''' || '''Description'''                        ||
|| x-canonical-type    || s          || com.canonical.indicator.progress         ||
|| action              || s          || name of an action containing the calendar's state as an "a{sv}". Possible keys are: calendar-day (t), show-week-numbers (b), appointment-days (ai). ||
-Line 640:
+Line 144:
-x-canonical-type
+==== Calendar's Action ====
|| '''Key''' || '''Value Type''' || '''Description'''                        ||
|| calendar-day || t || a time_t denoting which year & month should be visible in the calendard and which day currently has focus/selection. ||
|| show-week-numbers || b || Whether or not to show the week numbers in the calendar. ||
|| appointment-days || ai || array of int32 day-of-months showing days with appointments in the month specified by calendar-day ||
-Line 643:
+Line 150:
-s
-Line 646:
+Line 151:
-com.canonical.indicator.location
+=== Slider ===
-Line 648:
+Line 153:
-label
+|| '''Property Name''' || '''Type''' || '''Description'''                        ||
|| x-canonical-type    || s          || com.canonical.unity.slider               ||
|| action              || s          || name of an action with state "d", the position of the slider ||
|| min-value           || d          || minimum value                            ||
|| max-value           || d          || maximum value                            ||
|| step                || d          || step increment                           ||
|| min-icon            || v          || an icon representing the minimum value   ||
|| max-icon            || v          || an icon representing the maximum value   ||
-Line 651:
+Line 162:
-s
-Line 654:
+Line 163:
-String with label
+=== Media Player ===
-Line 656:
+Line 165:
-x-canonical-time-format
+A menu item representing a media player. Its state includes metadata about the
currently playing track.
-Line 659:
+Line 168:
-s
+|| '''Property Name''' || '''Type''' || '''Description'''                        ||
|| x-canonical-type    || s          || com.canonical.unity.media-player         ||
|| label               || s          || name of the player                       ||
|| action              || s          || name of an action containing the state of the player as an "a{sv}". Possible keys are : running (b), title (s), artist (s), album(s), art-url (s). ||
|| icon                || v          || app icon of the player                   ||
-Line 662:
+Line 174:
-A strftime(3) format string specifying how to display the location's current time.
-Line 664:
+Line 175:
-x-canonical-timezone
 

s
 

timezone that the location is in.

Calendar

Property Name
 

Type
 

Description

x-canonical-type
 

s
 

com.canonical.indicator.progress

action
 

s
 

name of an action containing the calendar's state as an "a{sv}". Possible keys are: calendar-day (t), show-week-numbers (b), appointment-days (ai).

Calendar's Action

Key
 

Value Type
 

Description

calendar-day
 

t
 

a time_t denoting which year & month should be visible in the calendard and which day currently has focus/selection.

show-week-numbers
 

b
 

Whether or not to show the week numbers in the calendar.

appointment-days
 

ai
 

array of int32 day-of-months showing days with appointments in the month specified by calendar-day

Slider

Property Name
 

Type
 

Description

x-canonical-type
 

s
 

com.canonical.unity.slider

action
 

s
 

name of an action with state "d", the position of the slider

min-value
 

d
 

minimum value

max-value
 

d
 

maximum value

step
 

d
 

step increment

min-icon
 

v
 

an icon representing the minimum value

max-icon
 

v
 

an icon representing the maximum value

Media Player

A menu item representing a media player. Its state includes metadata about the currently playing track.

Property Name
 

Type
 

Description

x-canonical-type
 

s
 

com.canonical.unity.media-player

label
 

s
 

name of the player

action
 

s
 

name of an action containing the state of the player as an "a{sv}". Possible keys are : running (b), title (s), artist (s), album(s), art-url (s).

icon
 

v
 

app icon of the player

Playback
+=== Playback ===
-Line 846:
+Line 179:
-Property Name
 

Type
 

Description

x-canonical-type
 

s
 

com.canonical.unity.playback-item

x-canonical-play-action
 

s
 

name of a play/pause action with string state ("Playing", "Stopped", "Launching")

x-canonical-previous-action
 

s
 

name of a stateless action for going to the previous track

x-canonical-next-action
 

s
 

name of a stateless action for going to the previous track
+|| '''Property Name'''         || '''Type''' || '''Description'''                                                                    ||
|| x-canonical-type            || s          || com.canonical.unity.playback-item                                                    ||
|| x-canonical-play-action     || s          || name of a play/pause action with string state ("Playing", "Stopped", "Launching")    ||
|| x-canonical-previous-action || s          || name of a stateless action for going to the previous track                           ||
|| x-canonical-next-action     || s          || name of a stateless action for going to the previous track                           ||