github.com/david-imola/snapd@v0.0.0-20210611180407-2de8ddeece6d/desktop/notification/hints.go (about)

     1  // -*- Mode: Go; indent-tabs-mode: t -*-
     2  
     3  /*
     4   * Copyright (C) 2020 Canonical Ltd
     5   *
     6   * This program is free software: you can redistribute it and/or modify
     7   * it under the terms of the GNU General Public License version 3 as
     8   * published by the Free Software Foundation.
     9   *
    10   * This program is distributed in the hope that it will be useful,
    11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
    12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    13   * GNU General Public License for more details.
    14   *
    15   * You should have received a copy of the GNU General Public License
    16   * along with this program.  If not, see <http://www.gnu.org/licenses/>.
    17   *
    18   */
    19  
    20  package notification
    21  
    22  import "fmt"
    23  
    24  // WithActionIcons returns a hint asking the server to use action key as icon names.
    25  //
    26  // A server that has the "action-icons" capability will attempt to interpret any
    27  // action key as a named icon. The localized display name will be used to
    28  // annotate the icon for accessibility purposes. The icon name should be
    29  // compliant with the Freedesktop.org Icon Naming Specification.
    30  //
    31  // Requires server version >= 1.2
    32  func WithActionIcons() Hint {
    33  	t := true
    34  	return Hint{Name: "action-icons", Value: &t}
    35  }
    36  
    37  // Urgency describes the importance of a notification message.
    38  //
    39  // Specification: https://developer.gnome.org/notification-spec/#urgency-levels
    40  type Urgency byte
    41  
    42  const (
    43  	// LowUrgency indicates that a notification message is below normal priority.
    44  	LowUrgency Urgency = 0
    45  	// NormalUrgency indicates that a notification message has the regular priority.
    46  	NormalUrgency Urgency = 1
    47  	// CriticalUrgency indicates that a notification message is above normal priority.
    48  	CriticalUrgency Urgency = 2
    49  )
    50  
    51  // String implements the Stringer interface.
    52  func (u Urgency) String() string {
    53  	switch u {
    54  	case LowUrgency:
    55  		return "low"
    56  	case NormalUrgency:
    57  		return "normal"
    58  	case CriticalUrgency:
    59  		return "critical"
    60  	default:
    61  		return fmt.Sprintf("Urgency(%d)", byte(u))
    62  	}
    63  }
    64  
    65  // WithUrgency returns a hint asking the server to set message urgency.
    66  //
    67  // Notification servers may show messages with higher urgency before messages
    68  // with lower urgency. In addition some urgency levels may not be shown when the
    69  // user has enabled a do-not-distrub mode.
    70  func WithUrgency(u Urgency) Hint {
    71  	return Hint{Name: "urgency", Value: &u}
    72  }
    73  
    74  // Category is a string indicating the category of a notification message.
    75  //
    76  // Specification: https://developer.gnome.org/notification-spec/#categories
    77  type Category string
    78  
    79  const (
    80  	// DeviceCategory is a generic notification category related to hardware devices.
    81  	DeviceCategory Category = "device"
    82  	// DeviceAddedCategory indicates that a device was added to the system.
    83  	DeviceAddedCategory Category = "device.added"
    84  	// DeviceErrorCategory indicates that a device error occurred.
    85  	DeviceErrorCategory Category = "device.error"
    86  	// DeviceRemovedCategory indicates that a device was removed from the system.
    87  	DeviceRemovedCategory Category = "device.removed"
    88  
    89  	// EmailCategory is a generic notification category related to electronic mail.
    90  	EmailCategory Category = "email"
    91  	//EmailArrivedCategory indicates that an e-mail has arrived.
    92  	EmailArrivedCategory Category = "email.arrived"
    93  	// EmailBouncedCategory indicates that an e-mail message has bounced.
    94  	EmailBouncedCategory Category = "email.bounced"
    95  
    96  	// InstantMessageCategory is a generic notification category related to instant messages.
    97  	InstantMessageCategory Category = "im"
    98  	// InstantMessageErrorCategory indicates that an instant message error occurred.
    99  	InstantMessageErrorCategory Category = "im.error"
   100  	// InstantMessageReceivedCategory indicates that an instant mesage has been received.
   101  	InstantMessageReceivedCategory Category = "im.received"
   102  
   103  	// NetworkCategory is a generic notification category related to network.
   104  	NetworkCategory Category = "network"
   105  	// NetworkConnectedCategory indicates that a network connection has been established.
   106  	NetworkConnectedCategory Category = "network.connected"
   107  	// NetworkDisconnectedCategory indicates that a network connection has been lost.
   108  	NetworkDisconnectedCategory Category = "network.disconnected"
   109  	// NetworkErrorCategory indicates that a network error occurred.
   110  	NetworkErrorCategory Category = "network.error"
   111  
   112  	// PresenceCategory is a generic notification category related to on-line presence.
   113  	PresenceCategory Category = "presence"
   114  	// PresenceOfflineCategory indicates that a contact disconnected from the network.
   115  	PresenceOfflineCategory Category = "presence.offline"
   116  	// PresenceOnlineCategory indicates that a contact connected to the network.
   117  	PresenceOnlineCategory Category = "presence.online"
   118  
   119  	// TransferCategory is a generic notification category for file transfers or downloads.
   120  	TransferCategory Category = "transfer"
   121  	// TransferCompleteCategory indicates that a file transfer has completed.
   122  	TransferCompleteCategory Category = "transfer.complete"
   123  	// TransferErrorCategory indicates that a file transfer error occurred.
   124  	TransferErrorCategory Category = "transfer.error"
   125  )
   126  
   127  // WithCategory returns a hint asking the server to set message category.
   128  func WithCategory(c Category) Hint {
   129  	return Hint{Name: "category", Value: &c}
   130  }
   131  
   132  // WithDesktopEntry returns a hint asking the server to associate a desktop file with a message.
   133  //
   134  // The desktopEntryName is the name of the desktop file without the ".desktop"
   135  // extension. The server may use this information to derive correct icon, for
   136  // logging, etc.
   137  func WithDesktopEntry(desktopEntryName string) Hint {
   138  	return Hint{Name: "desktop-entry", Value: &desktopEntryName}
   139  }
   140  
   141  // WithTransient returns a hint asking the server to bypass message persistence.
   142  //
   143  // When set the server will treat the notification as transient and by-pass the
   144  // server's persistence capability, if it should exist.
   145  //
   146  // Requires server version >= 1.2
   147  func WithTransient() Hint {
   148  	t := true
   149  	return Hint{Name: "transient", Value: &t}
   150  }
   151  
   152  // WithResident returns a hint asking the server to keep the message after an action is invoked.
   153  //
   154  // When set the server will not automatically remove the notification when an
   155  // action has been invoked. The notification will remain resident in the server
   156  // until it is explicitly removed by the user or by the sender. This hint is
   157  // likely only useful when the server has the "persistence" capability.
   158  //
   159  // Requires server version >= 1.2
   160  func WithResident() Hint {
   161  	t := true
   162  	return Hint{Name: "resident", Value: &t}
   163  }
   164  
   165  // WithPointToX returns a hint asking the server to point the notification at a specific X coordinate.
   166  //
   167  // The coordinate is in desktop pixel units. Both X and Y hints must be included in the message.
   168  func WithPointToX(x int) Hint {
   169  	return Hint{Name: "x", Value: &x}
   170  }
   171  
   172  // WithPointToY returns a hint asking the server to point the notification at a specific Y coordinate.
   173  //
   174  // The coordinate is in desktop pixel units. Both X and Y hints must be included in the message.
   175  func WithPointToY(y int) Hint {
   176  	return Hint{Name: "y", Value: &y}
   177  }
   178  
   179  // WithImageFile returns a hint asking the server display an image loaded from file.
   180  //
   181  // When multiple hits related to images are used, the following priority list applies:
   182  // 1) "image-data" (not implemented in Go).
   183  // 2) "image-path", as provided by WithImageFile.
   184  // 3) Message.Icon field.
   185  func WithImageFile(path string) Hint {
   186  	// The hint name is image-path but the function is called WithImageFile for consistency with WithSoundFile.
   187  	return Hint{Name: "image-path", Value: &path}
   188  }
   189  
   190  // TODO: add WithImageData
   191  
   192  // WithSoundFile returns a hint asking the server to play a sound loaded from file.
   193  func WithSoundFile(path string) Hint {
   194  	return Hint{Name: "sound-file", Value: &path}
   195  }
   196  
   197  // WithSoundName returns a hint asking the server to play a sound from the sound theme.
   198  func WithSoundName(name string) Hint {
   199  	return Hint{Name: "sound-name", Value: &name}
   200  }
   201  
   202  // WithSuppressSound returns a hint asking the server not to play any notification sounds.
   203  func WithSuppressSound() Hint {
   204  	t := true
   205  	return Hint{Name: "suppress-sound", Value: &t}
   206  }