/* gsound-attr.h
 * 
 * Copyright (C) 2014 Tristan Brindle <t.c.brindle@gmail.com>
 * 
 * Adapted from canberra.h,
 * 
 * Copyright 2008 Lennart Poettering 
 *
 * This file is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of the
 * License, or (at your option) any later version.
 *
 * This file is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef GSOUND_ATTR_H
#define GSOUND_ATTR_H

#include <glib.h>

G_BEGIN_DECLS

/**
 * SECTION:gsound-attr
 * @title: GSound Attributes
 * @short_description: Attributes recognized by GSound
 * @see_also: #GSoundContext
 * 
 * Attributes which can be applied to a #GSoundContext or passed to one of
 * the `play()` or `cache()` methods.
 */

/**
 * GSOUND_ATTR_MEDIA_NAME:
 *
 * A name describing the media being played. Localized if possible and applicable.
 */
#define GSOUND_ATTR_MEDIA_NAME                         "media.name"

/**
 * GSOUND_ATTR_MEDIA_TITLE:
 *
 * A (song) title describing the media being played. Localized if possible and applicable.
 */
#define GSOUND_ATTR_MEDIA_TITLE                        "media.title"

/**
 * GSOUND_ATTR_MEDIA_ARTIST:
 *
 * The artist of this media. Localized if possible and applicable.
 */
#define GSOUND_ATTR_MEDIA_ARTIST                       "media.artist"

/**
 * GSOUND_ATTR_MEDIA_LANGUAGE:
 *
 * The language this media is in, in some standard POSIX locale string, such as "de_DE".
 */
#define GSOUND_ATTR_MEDIA_LANGUAGE                     "media.language"

/**
 * GSOUND_ATTR_MEDIA_FILENAME:
 *
 * The file name this media was or can be loaded from.
 */
#define GSOUND_ATTR_MEDIA_FILENAME                     "media.filename"

/**
 * GSOUND_ATTR_MEDIA_ICON:
 *
 * An icon for this media in binary PNG format.
 */
#define GSOUND_ATTR_MEDIA_ICON                         "media.icon"

/**
 * GSOUND_ATTR_MEDIA_ICON_NAME:
 *
 * An icon name as defined in the XDG icon naming specifcation.
 */
#define GSOUND_ATTR_MEDIA_ICON_NAME                    "media.icon_name"

/**
 * GSOUND_ATTR_MEDIA_ROLE:
 *
 * The "role" this media is played in. For event sounds the string
 * "event". For other cases strings like "music", "video", "game", ...
 */
#define GSOUND_ATTR_MEDIA_ROLE                         "media.role"

/**
 * GSOUND_ATTR_EVENT_ID:
 *
 * A textual id for an event sound, as mandated by the XDG sound naming specification.
 */
#define GSOUND_ATTR_EVENT_ID                           "event.id"

/**
 * GSOUND_ATTR_EVENT_DESCRIPTION:
 *
 * A descriptive string for the sound event. Localized if possible and applicable.
 */
#define GSOUND_ATTR_EVENT_DESCRIPTION                  "event.description"

/**
 * GSOUND_ATTR_EVENT_MOUSE_X:
 *
 * If this sound event was triggered by a mouse input event, the X
 * position of the mouse cursor on the screen, formatted as string.
 */
#define GSOUND_ATTR_EVENT_MOUSE_X                      "event.mouse.x"

/**
 * GSOUND_ATTR_EVENT_MOUSE_Y:
 *
 * If this sound event was triggered by a mouse input event, the Y
 * position of the mouse cursor on the screen, formatted as string.
 */
#define GSOUND_ATTR_EVENT_MOUSE_Y                      "event.mouse.y"

/**
 * GSOUND_ATTR_EVENT_MOUSE_HPOS:
 *
 * If this sound event was triggered by a mouse input event, the X
 * position of the mouse cursor as fractional value between 0 and 1,
 * formatted as string, 0 reflecting the left side of the screen, 1
 * the right side.
 */
#define GSOUND_ATTR_EVENT_MOUSE_HPOS                   "event.mouse.hpos"

/**
 * GSOUND_ATTR_EVENT_MOUSE_VPOS:
 *
 * If this sound event was triggered by a mouse input event, the Y
 * position of the mouse cursor as fractional value between 0 and 1,
 * formatted as string, 0 reflecting the top end of the screen, 1
 * the bottom end.
 */
#define GSOUND_ATTR_EVENT_MOUSE_VPOS                   "event.mouse.vpos"

/**
 * GSOUND_ATTR_EVENT_MOUSE_BUTTON:
 *
 * If this sound event was triggered by a mouse input event, the
 * number of the mouse button that triggered it, formatted as string. 1
 * for left mouse button, 3 for right, 2 for middle.
 */
#define GSOUND_ATTR_EVENT_MOUSE_BUTTON                 "event.mouse.button"

/**
 * GSOUND_ATTR_WINDOW_NAME:
 *
 * If this sound event was triggered by a window on the screen, the
 * name of this window as human readable string.
 */
#define GSOUND_ATTR_WINDOW_NAME                        "window.name"

/**
 * GSOUND_ATTR_WINDOW_ID:
 *
 * If this sound event was triggered by a window on the screen, some
 * identification string for this window, so that the sound system can
 * recognize specific windows.
 */
#define GSOUND_ATTR_WINDOW_ID                          "window.id"

/**
 * GSOUND_ATTR_WINDOW_ICON:
 *
 * If this sound event was triggered by a window on the screen, binary
 * icon data in PNG format for this window.
 */
#define GSOUND_ATTR_WINDOW_ICON                        "window.icon"

/**
 * GSOUND_ATTR_WINDOW_ICON_NAME:
 *
 * If this sound event was triggered by a window on the screen, an
 * icon name for this window, as defined in the XDG icon naming
 * specification.
 */
#define GSOUND_ATTR_WINDOW_ICON_NAME                   "window.icon_name"

/**
 * GSOUND_ATTR_WINDOW_X:
 *
 * If this sound event was triggered by a window on the screen, the X
 * position of the window measured from the top left corner of the
 * screen to the top left corner of the window.
 */
#define GSOUND_ATTR_WINDOW_X                           "window.x"

/**
 * GSOUND_ATTR_WINDOW_Y:
 *
 * If this sound event was triggered by a window on the screen, the y
 * position of the window measured from the top left corner of the
 * screen to the top left corner of the window.
 */
#define GSOUND_ATTR_WINDOW_Y                           "window.y"

/**
 * GSOUND_ATTR_WINDOW_WIDTH:
 *
 * If this sound event was triggered by a window on the screen, the
 * pixel width of the window.
 */
#define GSOUND_ATTR_WINDOW_WIDTH                       "window.width"

/**
 * GSOUND_ATTR_WINDOW_HEIGHT:
 *
 * If this sound event was triggered by a window on the screen, the
 * pixel height of the window.
 */
#define GSOUND_ATTR_WINDOW_HEIGHT                      "window.height"

/**
 * GSOUND_ATTR_WINDOW_HPOS:
 *
 * If this sound event was triggered by a window on the screen, the X
 * position of the center of the window as fractional value between 0
 * and 1, formatted as string, 0 reflecting the left side of the
 * screen, 1 the right side.
 */
#define GSOUND_ATTR_WINDOW_HPOS                        "window.hpos"

/**
 * GSOUND_ATTR_WINDOW_VPOS:
 *
 * If this sound event was triggered by a window on the screen, the Y
 * position of the center of the window as fractional value between 0
 * and 1, formatted as string, 0 reflecting the top side of the
 * screen, 1 the bottom side.
 */
#define GSOUND_ATTR_WINDOW_VPOS                        "window.vpos"

/**
 * GSOUND_ATTR_WINDOW_DESKTOP:
 *
 * If this sound event was triggered by a window on the screen and the
 * windowing system supports multiple desktops, a comma seperated list
 * of indexes of the desktops this window is visible on. If this
 * attribute is an empty string, it is visible on all desktops
 * (i.e. 'sticky'). The first desktop is 0. (e.g. "0,2,3")
 */
#define GSOUND_ATTR_WINDOW_DESKTOP                    "window.desktop"

/**
 * GSOUND_ATTR_WINDOW_X11_DISPLAY:
 *
 * If this sound event was triggered by a window on the screen and the
 * windowing system is X11, the X display name of the window (e.g. ":0").
 */
#define GSOUND_ATTR_WINDOW_X11_DISPLAY                 "window.x11.display"

/**
 * GSOUND_ATTR_WINDOW_X11_SCREEN:
 *
 * If this sound event was triggered by a window on the screen and the
 * windowing system is X11, the X screen id of the window formatted as
 * string (e.g. "0").
 */
#define GSOUND_ATTR_WINDOW_X11_SCREEN                  "window.x11.screen"

/**
 * GSOUND_ATTR_WINDOW_X11_MONITOR:
 *
 * If this sound event was triggered by a window on the screen and the
 * windowing system is X11, the X monitor id of the window formatted as
 * string (e.g. "0").
 */
#define GSOUND_ATTR_WINDOW_X11_MONITOR                 "window.x11.monitor"

/**
 * GSOUND_ATTR_WINDOW_X11_XID:
 *
 * If this sound event was triggered by a window on the screen and the
 * windowing system is X11, the XID of the window formatted as string.
 */
#define GSOUND_ATTR_WINDOW_X11_XID                     "window.x11.xid"

/**
 * GSOUND_ATTR_APPLICATION_NAME:
 *
 * The name of the application this sound event was triggered by as
 * human readable string. (e.g. "GNU Emacs") Localized if possible and
 * applicable.
 * 
 * > This attribute will automatically be added to the #GSoundContext if
 * > it has previously been set with g_set_application_name(), so you normally
 * > do not need to supply this yourself.
 */
#define GSOUND_ATTR_APPLICATION_NAME                   "application.name"

/**
 * GSOUND_ATTR_APPLICATION_ID:
 *
 * An identifier for the program this sound event was triggered
 * by. (e.g. "org.gnu.emacs").
 * 
 * > This attribute will automatically be added to the #GSoundContext with
 * > the #GApplication:application-id if you are using #GApplication, so you
 * > normally do not need to supply this yourself.
 */
#define GSOUND_ATTR_APPLICATION_ID                     "application.id"

/**
 * GSOUND_ATTR_APPLICATION_VERSION:
 *
 * A version number for the program this sound event was triggered
 * by. (e.g. "22.2")
 */
#define GSOUND_ATTR_APPLICATION_VERSION                "application.version"

/**
 * GSOUND_ATTR_APPLICATION_ICON:
 *
 * Binary icon data in PNG format for the application this sound event
 * is triggered by.
 */
#define GSOUND_ATTR_APPLICATION_ICON                   "application.icon"

/**
 * GSOUND_ATTR_APPLICATION_ICON_NAME:
 *
 * An icon name for the application this sound event is triggered by,
 * as defined in the XDG icon naming specification.
 */
#define GSOUND_ATTR_APPLICATION_ICON_NAME              "application.icon_name"

/**
 * GSOUND_ATTR_APPLICATION_LANGUAGE:
 *
 * The locale string the application that is triggering this sound
 * event is running in. A POSIX locale string such as de_DE@euro.
 */
#define GSOUND_ATTR_APPLICATION_LANGUAGE               "application.language"

/**
 * GSOUND_ATTR_APPLICATION_PROCESS_ID:
 *
 * The unix PID of the process that is triggering this sound event, formatted as string.
 */
#define GSOUND_ATTR_APPLICATION_PROCESS_ID             "application.process.id"

/**
 * GSOUND_ATTR_APPLICATION_PROCESS_BINARY:
 *
 * The path to the process binary of the process that is triggering this sound event.
 */
#define GSOUND_ATTR_APPLICATION_PROCESS_BINARY         "application.process.binary"

/**
 * GSOUND_ATTR_APPLICATION_PROCESS_USER:
 *
 * The user that owns the process that is triggering this sound event.
 */
#define GSOUND_ATTR_APPLICATION_PROCESS_USER           "application.process.user"

/**
 * GSOUND_ATTR_APPLICATION_PROCESS_HOST:
 *
 * The host name of the host the process that is triggering this sound event runs on.
 */
#define GSOUND_ATTR_APPLICATION_PROCESS_HOST           "application.process.host"

/**
 * GSOUND_ATTR_CANBERRA_CACHE_CONTROL:
 *
 * A special attribute that can be used to control the automatic sound
 * caching of sounds in the sound server. One of "permanent",
 * "volatile", "never". "permanent" will cause this sample to be
 * cached in the server permanently. This is useful for very
 * frequently used sound events such as those used for input
 * feedback. "volatile" may be used for cacheing sounds in the sound
 * server temporarily. They will expire after some time or on cache
 * pressure. Finally, "never" may be used for sounds that should never
 * be cached, because they are only generated very seldomly or even
 * only once at most (such as desktop login sounds).
 *
 * If this attribute is not explicitly passed to gsound_context_play_simple() 
 * or gsound_context_play_full() it will default to "never". If it is not
 * explicitly passed to gsound_context_cache() it will default to "permanent".
 *
 * If the list of attributes is handed on to the sound server this
 * attribute is stripped from it.
 */
#define GSOUND_ATTR_CANBERRA_CACHE_CONTROL             "canberra.cache-control"

/**
 * GSOUND_ATTR_CANBERRA_VOLUME:
 *
 * A special attribute that can be used to control the volume this
 * sound event is played in if the backend supports it. A floating
 * point value for the decibel multiplier for the sound. 0 dB relates
 * to zero gain, and is the default volume these sounds are played in.
 *
 * If the list of attributes is handed on to the sound server this
 * attribute is stripped from it.
 */
#define GSOUND_ATTR_CANBERRA_VOLUME                    "canberra.volume"

/**
 * GSOUND_ATTR_CANBERRA_XDG_THEME_NAME:
 *
 * A special attribute that can be used to control the XDG sound theme that
 * is used for this sample.
 *
 * If the list of attributes is handed on to the sound server this
 * attribute is stripped from it.
 */
#define GSOUND_ATTR_CANBERRA_XDG_THEME_NAME            "canberra.xdg-theme.name"

/**
 * GSOUND_ATTR_CANBERRA_XDG_THEME_OUTPUT_PROFILE:
 *
 * A special attribute that can be used to control the XDG sound theme
 * output profile that is used for this sample.
 *
 * If the list of attributes is handed on to the sound server this
 * attribute is stripped from it.
 */
#define GSOUND_ATTR_CANBERRA_XDG_THEME_OUTPUT_PROFILE  "canberra.xdg-theme.output-profile"

/**
 * GSOUND_ATTR_CANBERRA_ENABLE:
 *
 * A special attribute that can be used to control whether any sounds
 * are played at all. If this attribute is "1" or unset sounds are
 * played as normal. However, if it is "0" all calls to
 * gsound_context_play_simple() or `play_full()` will fail with
 * GSOUND_ERROR_DISABLED.
 *
 * If the list of attributes is handed on to the sound server this
 * attribute is stripped from it.
 */
#define GSOUND_ATTR_CANBERRA_ENABLE                    "canberra.enable"

/**
 * GSOUND_ATTR_CANBERRA_FORCE_CHANNEL:
 *
 * A special attribute that can be used to control on which channel a
 * sound is played. The value should be one of mono, front-left,
 * front-right, front-center, rear-left, rear-right, rear-center, lfe,
 * front-left-of-center, front-right-of-center, side-left, side-right,
 * top-center, top-front-left, top-front-right, top-front-center,
 * top-rear-left, top-rear-right, top-rear-center. This attribute is
 * only honoured by some backends, other backends may choose to ignore
 * it completely.
 *
 * If the list of attributes is handed on to the sound server this
 * attribute is stripped from it.
 */
#define GSOUND_ATTR_CANBERRA_FORCE_CHANNEL            "canberra.force_channel"



G_END_DECLS

#endif /* GSOUND_ATTR_H */