1 /* 2 An object to represent the application as an application indicator 3 in the system panel. 4 5 Copyright 2009 Canonical Ltd. 6 7 Authors: 8 Ted Gould <ted@canonical.com> 9 Cody Russell <cody.russell@canonical.com> 10 11 This program is free software: you can redistribute it and/or modify it 12 under the terms of either or both of the following licenses: 13 14 1) the GNU Lesser General Public License version 3, as published by the 15 Free Software Foundation; and/or 16 2) the GNU Lesser General Public License version 2.1, as published by 17 the Free Software Foundation. 18 19 This program is distributed in the hope that it will be useful, but 20 WITHOUT ANY WARRANTY; without even the implied warranties of 21 MERCHANTABILITY, SATISFACTORY QUALITY or FITNESS FOR A PARTICULAR 22 PURPOSE. See the applicable version of the GNU Lesser General Public 23 License for more details. 24 25 You should have received a copy of both the GNU Lesser General Public 26 License version 3 and version 2.1 along with this program. If not, see 27 <http://www.gnu.org/licenses/> 28 */ 29 30 #ifndef __APP_INDICATOR_H__ 31 #define __APP_INDICATOR_H__ 32 33 #include <gtk/gtk.h> 34 35 G_BEGIN_DECLS 36 37 /** 38 * APP_INDICATOR_TYPE: 39 * 40 * Get the #GType for a #AppIndicator. 41 */ 42 /** 43 * APP_INDICATOR: 44 * @obj: The object to convert 45 * 46 * Safely convert a #GObject into an #AppIndicator. 47 */ 48 /** 49 * APP_INDICATOR_CLASS: 50 * @klass: #GObjectClass based class to convert. 51 * 52 * Safely convert a #GObjectClass into a #AppIndicatorClass. 53 */ 54 /** 55 * IS_APP_INDICATOR: 56 * @obj: An #GObject to check 57 * 58 * Checks to see if @obj is in the object hierarchy of #AppIndicator. 59 */ 60 /** 61 * IS_APP_INDICATOR_CLASS: 62 * @klass: An #GObjectClass to check 63 * 64 * Checks to see if @klass is in the object class hierarchy of #AppIndicatorClass. 65 */ 66 /** 67 * APP_INDICATOR_GET_CLASS: 68 * @obj: A #GObject in the class hierarchy of #AppIndicator. 69 * 70 * Gets a pointer to the #AppIndicatorClass for the object @obj. 71 */ 72 73 #define APP_INDICATOR_TYPE (app_indicator_get_type ()) 74 #define APP_INDICATOR(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), APP_INDICATOR_TYPE, AppIndicator)) 75 #define APP_INDICATOR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), APP_INDICATOR_TYPE, AppIndicatorClass)) 76 #define IS_APP_INDICATOR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), APP_INDICATOR_TYPE)) 77 #define IS_APP_INDICATOR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), APP_INDICATOR_TYPE)) 78 #define APP_INDICATOR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), APP_INDICATOR_TYPE, AppIndicatorClass)) 79 80 /** 81 * APP_INDICATOR_SIGNAL_NEW_ICON: 82 * 83 * String identifier for the #AppIndicator::new-icon signal. 84 */ 85 /** 86 * APP_INDICATOR_SIGNAL_NEW_ATTENTION_ICON: 87 * 88 * String identifier for the #AppIndicator::new-attention-icon signal. 89 */ 90 /** 91 * APP_INDICATOR_SIGNAL_NEW_STATUS: 92 * 93 * String identifier for the #AppIndicator::new-status signal. 94 */ 95 /** 96 * APP_INDICATOR_SIGNAL_NEW_LABEL: 97 * 98 * String identifier for the #AppIndicator::new-label signal. 99 */ 100 /** 101 * APP_INDICATOR_SIGNAL_CONNECTION_CHANGED: 102 * 103 * String identifier for the #AppIndicator::connection-changed signal. 104 */ 105 /** 106 * APP_INDICATOR_SIGNAL_NEW_ICON_THEME_PATH: 107 * 108 * String identifier for the #AppIndicator::new-icon-theme-path signal. 109 */ 110 /** 111 * APP_INDICATOR_SIGNAL_SCROLL_EVENT: 112 * 113 * String identifier for the #AppIndicator::scroll-event signal. 114 */ 115 #define APP_INDICATOR_SIGNAL_NEW_ICON "new-icon" 116 #define APP_INDICATOR_SIGNAL_NEW_ATTENTION_ICON "new-attention-icon" 117 #define APP_INDICATOR_SIGNAL_NEW_STATUS "new-status" 118 #define APP_INDICATOR_SIGNAL_NEW_LABEL "new-label" 119 #define APP_INDICATOR_SIGNAL_CONNECTION_CHANGED "connection-changed" 120 #define APP_INDICATOR_SIGNAL_NEW_ICON_THEME_PATH "new-icon-theme-path" 121 #define APP_INDICATOR_SIGNAL_SCROLL_EVENT "scroll-event" 122 123 /** 124 * AppIndicatorCategory: 125 * @APP_INDICATOR_CATEGORY_APPLICATION_STATUS: The indicator is used to display the status of the application. 126 * @APP_INDICATOR_CATEGORY_COMMUNICATIONS: The application is used for communication with other people. 127 * @APP_INDICATOR_CATEGORY_SYSTEM_SERVICES: A system indicator relating to something in the user's system. 128 * @APP_INDICATOR_CATEGORY_HARDWARE: An indicator relating to the user's hardware. 129 * @APP_INDICATOR_CATEGORY_OTHER: Something not defined in this enum, please don't use unless you really need it. 130 * 131 * The category provides grouping for the indicators so that 132 * users can find indicators that are similar together. 133 */ 134 typedef enum { /*< prefix=APP_INDICATOR_CATEGORY >*/ 135 APP_INDICATOR_CATEGORY_APPLICATION_STATUS, /*< nick=ApplicationStatus >*/ 136 APP_INDICATOR_CATEGORY_COMMUNICATIONS, /*< nick=Communications >*/ 137 APP_INDICATOR_CATEGORY_SYSTEM_SERVICES, /*< nick=SystemServices >*/ 138 APP_INDICATOR_CATEGORY_HARDWARE, /*< nick=Hardware >*/ 139 APP_INDICATOR_CATEGORY_OTHER /*< nick=Other >*/ 140 } AppIndicatorCategory; 141 142 /** 143 * AppIndicatorStatus: 144 * @APP_INDICATOR_STATUS_PASSIVE: The indicator should not be shown to the user. 145 * @APP_INDICATOR_STATUS_ACTIVE: The indicator should be shown in it's default state. 146 * @APP_INDICATOR_STATUS_ATTENTION: The indicator should show it's attention icon. 147 * 148 * These are the states that the indicator can be on in 149 * the user's panel. The indicator by default starts 150 * in the state @APP_INDICATOR_STATUS_PASSIVE and can be 151 * shown by setting it to @APP_INDICATOR_STATUS_ACTIVE. 152 */ 153 typedef enum { /*< prefix=APP_INDICATOR_STATUS >*/ 154 APP_INDICATOR_STATUS_PASSIVE, /*< nick=Passive >*/ 155 APP_INDICATOR_STATUS_ACTIVE, /*< nick=Active >*/ 156 APP_INDICATOR_STATUS_ATTENTION /*< nick=NeedsAttention >*/ 157 } AppIndicatorStatus; 158 159 typedef struct _AppIndicator AppIndicator; 160 typedef struct _AppIndicatorClass AppIndicatorClass; 161 typedef struct _AppIndicatorPrivate AppIndicatorPrivate; 162 163 /** 164 * AppIndicatorClass: 165 * @parent_class: Mia familia 166 * @new_icon: Slot for #AppIndicator::new-icon. 167 * @new_attention_icon: Slot for #AppIndicator::new-attention-icon. 168 * @new_status: Slot for #AppIndicator::new-status. 169 * @new_icon_theme_path: Slot for #AppIndicator::new-icon-theme-path 170 * @new_label: Slot for #AppIndicator::new-label. 171 * @connection_changed: Slot for #AppIndicator::connection-changed. 172 * @scroll_event: Slot for #AppIndicator::scroll-event 173 * @app_indicator_reserved_ats: Reserved for future use. 174 * @fallback: Function that gets called to make a #GtkStatusIcon when 175 * there is no Application Indicator area available. 176 * @unfallback: The function that gets called if an Application 177 * Indicator area appears after the fallback has been created. 178 * @app_indicator_reserved_1: Reserved for future use. 179 * @app_indicator_reserved_2: Reserved for future use. 180 * @app_indicator_reserved_3: Reserved for future use. 181 * @app_indicator_reserved_4: Reserved for future use. 182 * @app_indicator_reserved_5: Reserved for future use. 183 * @app_indicator_reserved_6: Reserved for future use. 184 * 185 * The signals and external functions that make up the #AppIndicator 186 * class object. 187 */ 188 struct _AppIndicatorClass { 189 /* Parent */ 190 GObjectClass parent_class; 191 192 /* DBus Signals */ 193 void (* new_icon) (AppIndicator *indicator, 194 gpointer user_data); 195 void (* new_attention_icon) (AppIndicator *indicator, 196 gpointer user_data); 197 void (* new_status) (AppIndicator *indicator, 198 const gchar *status, 199 gpointer user_data); 200 void (* new_icon_theme_path) (AppIndicator *indicator, 201 const gchar *icon_theme_path, 202 gpointer user_data); 203 void (* new_label) (AppIndicator *indicator, 204 const gchar *label, 205 const gchar *guide, 206 gpointer user_data); 207 208 /* Local Signals */ 209 void (* connection_changed) (AppIndicator * indicator, 210 gboolean connected, 211 gpointer user_data); 212 213 void (* scroll_event) (AppIndicator * indicator, 214 gint delta, 215 GdkScrollDirection direction, 216 gpointer user_data); 217 218 void (*app_indicator_reserved_ats)(void); 219 220 /* Overridable Functions */ 221 GtkStatusIcon * (*fallback) (AppIndicator * indicator); 222 void (*unfallback) (AppIndicator * indicator, 223 GtkStatusIcon * status_icon); 224 225 /* Reserved */ 226 void (*app_indicator_reserved_1)(void); 227 void (*app_indicator_reserved_2)(void); 228 void (*app_indicator_reserved_3)(void); 229 void (*app_indicator_reserved_4)(void); 230 void (*app_indicator_reserved_5)(void); 231 void (*app_indicator_reserved_6)(void); 232 }; 233 234 /** 235 * AppIndicator: 236 * 237 * A application indicator represents the values that are needed to show a 238 * unique status in the panel for an application. In general, applications 239 * should try to fit in the other indicators that are available on the 240 * panel before using this. But, sometimes it is necissary. 241 * 242 * Private fields 243 * @parent: Parent object. 244 * @priv: Internal data. 245 */ 246 struct _AppIndicator { 247 GObject parent; 248 249 /*< Private >*/ 250 AppIndicatorPrivate *priv; 251 }; 252 253 /* GObject Stuff */ 254 GType app_indicator_get_type (void) G_GNUC_CONST; 255 256 AppIndicator *app_indicator_new (const gchar *id, 257 const gchar *icon_name, 258 AppIndicatorCategory category); 259 AppIndicator *app_indicator_new_with_path (const gchar *id, 260 const gchar *icon_name, 261 AppIndicatorCategory category, 262 const gchar *icon_theme_path); 263 264 /* Set properties */ 265 void app_indicator_set_status (AppIndicator *self, 266 AppIndicatorStatus status); 267 void app_indicator_set_attention_icon (AppIndicator *self, 268 const gchar *icon_name); 269 void app_indicator_set_attention_icon_full (AppIndicator *self, 270 const gchar *icon_name, 271 const gchar *icon_desc); 272 void app_indicator_set_menu (AppIndicator *self, 273 GtkMenu *menu); 274 void app_indicator_set_icon (AppIndicator *self, 275 const gchar *icon_name); 276 void app_indicator_set_icon_full (AppIndicator *self, 277 const gchar *icon_name, 278 const gchar *icon_desc); 279 void app_indicator_set_label (AppIndicator *self, 280 const gchar *label, 281 const gchar *guide); 282 void app_indicator_set_icon_theme_path(AppIndicator *self, 283 const gchar *icon_theme_path); 284 void app_indicator_set_ordering_index (AppIndicator *self, 285 guint32 ordering_index); 286 void app_indicator_set_secondary_activate_target (AppIndicator *self, 287 GtkWidget *menuitem); 288 void app_indicator_set_title (AppIndicator *self, 289 const gchar *title); 290 291 /* Get properties */ 292 const gchar * app_indicator_get_id (AppIndicator *self); 293 AppIndicatorCategory app_indicator_get_category (AppIndicator *self); 294 AppIndicatorStatus app_indicator_get_status (AppIndicator *self); 295 const gchar * app_indicator_get_icon (AppIndicator *self); 296 const gchar * app_indicator_get_icon_desc (AppIndicator *self); 297 const gchar * app_indicator_get_icon_theme_path (AppIndicator *self); 298 const gchar * app_indicator_get_attention_icon (AppIndicator *self); 299 const gchar * app_indicator_get_attention_icon_desc (AppIndicator *self); 300 const gchar * app_indicator_get_title (AppIndicator *self); 301 302 GtkMenu * app_indicator_get_menu (AppIndicator *self); 303 const gchar * app_indicator_get_label (AppIndicator *self); 304 const gchar * app_indicator_get_label_guide (AppIndicator *self); 305 guint32 app_indicator_get_ordering_index (AppIndicator *self); 306 GtkWidget * app_indicator_get_secondary_activate_target (AppIndicator *self); 307 308 /* Helpers */ 309 void app_indicator_build_menu_from_desktop (AppIndicator * self, 310 const gchar * desktop_file, 311 const gchar * desktop_profile); 312 313 G_END_DECLS 314 315 /** 316 * SECTION:app-indicator 317 * @short_description: An object to put application information 318 * into the panel. 319 * @stability: Unstable 320 * @include: libappindicator/app-indicator.h 321 * 322 * An application indicator is a way for an application to put 323 * a menu into the panel on the user's screen. This allows the 324 * user to interact with the application even though it might 325 * not be visible to the user at the time. In most cases this 326 * is not a good solution as there are other ways to inform the 327 * user. It should only be use if persistence is a desired 328 * feature for the user (not for your marketing purpose of 329 * having your logo in the panel). 330 */ 331 332 #endif 333