1----------------------------------------------------------------------- 2-- GtkAda - Ada95 binding for Gtk+/Gnome -- 3-- -- 4-- Copyright (C) 2010-2013, AdaCore -- 5-- -- 6-- This library is free software; you can redistribute it and/or -- 7-- modify it under the terms of the GNU General Public -- 8-- License as published by the Free Software Foundation; either -- 9-- version 2 of the License, or (at your option) any later version. -- 10-- -- 11-- This library is distributed in the hope that it will be useful, -- 12-- but WITHOUT ANY WARRANTY; without even the implied warranty of -- 13-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -- 14-- General Public License for more details. -- 15-- -- 16-- You should have received a copy of the GNU General Public -- 17-- License along with this library; if not, write to the -- 18-- Free Software Foundation, Inc., 59 Temple Place - Suite 330, -- 19-- Boston, MA 02111-1307, USA. -- 20-- -- 21-- As a special exception, if other files instantiate generics from -- 22-- this unit, or you link this unit with other files to produce an -- 23-- executable, this unit does not by itself cause the resulting -- 24-- executable to be covered by the GNU General Public License. This -- 25-- exception does not however invalidate any other reasons why the -- 26-- executable file might be covered by the GNU Public License. -- 27----------------------------------------------------------------------- 28 29-- <description> 30-- The "system tray" or notification area is normally used for transient icons 31-- that indicate some special state. For example, a system tray icon might 32-- appear to tell the user that they have new mail, or have an incoming 33-- instant message, or something along those lines. The basic idea is that 34-- creating an icon in the notification area is less annoying than popping up 35-- a dialog. 36-- 37-- A Gtk_Status_Icon object can be used to display an icon in a "system tray". 38-- The icon can have a tooltip, and the user can interact with it by 39-- activating it or popping up a context menu. Critical information should not 40-- solely be displayed in a Gtk_Status_Icon, since it may not be visible 41-- (e.g. when the user doesn't have a notification area on his panel). This 42-- can be checked with Is_Embedded. 43-- 44-- On X11, the implementation follows the freedesktop.org "System Tray" 45-- specification. Implementations of the "tray" side of this specification can 46-- be found e.g. in the GNOME and KDE panel applications. 47-- 48-- Note that a Gtk_Status_Icon is not a widget, but just a GObject. Making it 49-- a widget would be impractical, since the system tray on Win32 doesn't allow 50-- to embed arbitrary widgets. 51-- </description> 52-- <c_version>2.16.6</c_version> 53 54with Glib.G_Icon; 55with Glib.Object; 56with Glib.Properties; 57with Gdk.Pixbuf; 58with Gdk.Rectangle; 59with Gdk.Screen; 60with Gtk.Enums; 61with Gtk.Image; 62 63package Gtk.Status_Icon is 64 65 type Gtk_Status_Icon_Record is new Glib.Object.GObject_Record with private; 66 type Gtk_Status_Icon is access all Gtk_Status_Icon_Record'Class; 67 68 function Get_Type return GType; 69 70 procedure Gtk_New (Widget : out Gtk_Status_Icon); 71 procedure Initialize (Widget : access Gtk_Status_Icon_Record'Class); 72 -- Creates an empty status icon object. 73 74 function Get_Storage_Type 75 (Status_Icon : access Gtk_Status_Icon_Record) 76 return Gtk.Image.Gtk_Image_Type; 77 -- Gets the type of representation being used by the Gtk_Status_Icon 78 -- to store image data. If the Gtk_Status_Icon has no image data, 79 -- the return value will be Image_Empty. 80 81 function Is_Embedded 82 (Status_Icon : access Gtk_Status_Icon_Record) return Boolean; 83 -- Returns whether the status icon is embedded in a notification 84 -- area. 85 86 ---------- 87 -- File -- 88 ---------- 89 90 procedure Gtk_New_From_File 91 (Widget : out Gtk_Status_Icon; 92 Filename : String); 93 procedure Initialize_From_File 94 (Widget : access Gtk_Status_Icon_Record'Class; 95 Filename : String); 96 -- Creates a status icon displaying the file Filename. 97 -- 98 -- The image will be scaled down to fit in the available 99 -- space in the notification area, if necessary. 100 101 procedure Set_From_File 102 (Status_Icon : access Gtk_Status_Icon_Record; 103 Filename : String); 104 -- Makes Status_Icon display the file Filename. 105 -- See Gtk_New_From_File for details. 106 107 ------------ 108 -- G_Icon -- 109 ------------ 110 111 procedure Gtk_New_From_Gicon 112 (Widget : out Gtk_Status_Icon; 113 Icon : Glib.G_Icon.G_Icon); 114 procedure Initialize_From_Gicon 115 (Widget : access Gtk_Status_Icon_Record'Class; 116 Icon : Glib.G_Icon.G_Icon); 117 -- Creates a status icon displaying a G_Icon. If the icon is a 118 -- themed icon, it will be updated when the theme changes. 119 120 function Get_Gicon 121 (Status_Icon : access Gtk_Status_Icon_Record) return Glib.G_Icon.G_Icon; 122 -- Retrieves the G_Icon being displayed by the Gtk_Status_Icon. 123 -- The storage type of the status icon must be Image_Empty or 124 -- Image_Gicon (see Get_Storage_Type). 125 -- The caller of this function does not own a reference to the 126 -- returned G_Icon. 127 -- 128 -- Status_Icon is left unchanged if this function fails. Returns 129 -- null if the image is empty. 130 131 procedure Set_From_Gicon 132 (Status_Icon : access Gtk_Status_Icon_Record; 133 Icon : Glib.G_Icon.G_Icon); 134 -- Makes Status_Icon display the G_Icon. 135 -- See Gtk_New_From_G_Icon for details. 136 137 --------------- 138 -- Icon_Name -- 139 --------------- 140 141 procedure Gtk_New_From_Icon_Name 142 (Widget : out Gtk_Status_Icon; 143 Icon_Name : String); 144 procedure Initialize_From_Icon_Name 145 (Widget : access Gtk_Status_Icon_Record'Class; 146 Icon_Name : String); 147 -- Creates a status icon displaying an icon from the current icon theme. 148 -- If the current icon theme is changed, the icon will be updated 149 -- appropriately. 150 151 function Get_Icon_Name 152 (Status_Icon : access Gtk_Status_Icon_Record) return String; 153 -- Gets the name of the icon being displayed by the Gtk_Status_Icon. 154 -- The storage type of the status icon must be Image_Empty or 155 -- Image_Icon_Name (see Get_Storage_Type). Returns "" if the image 156 -- is empty. 157 158 procedure Set_From_Icon_Name 159 (Status_Icon : access Gtk_Status_Icon_Record; 160 Icon_Name : String); 161 -- Makes Status_Icon display the icon named Icon_Name from the 162 -- current icon theme. 163 -- See Gtk_New_From_Icon_Name for details. 164 165 ------------ 166 -- Pixbuf -- 167 ------------ 168 169 procedure Gtk_New_From_Pixbuf 170 (Widget : out Gtk_Status_Icon; 171 Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf); 172 procedure Initialize_From_Pixbuf 173 (Widget : access Gtk_Status_Icon_Record'Class; 174 Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf); 175 -- Creates a status icon displaying Pixbuf. 176 -- 177 -- The image will be scaled down to fit in the available 178 -- space in the notification area, if necessary. 179 180 function Get_Pixbuf 181 (Status_Icon : access Gtk_Status_Icon_Record) 182 return Gdk.Pixbuf.Gdk_Pixbuf; 183 -- Gets the Gdk_Pixbuf being displayed by the Gtk_Status_Icon. 184 -- The storage type of the status icon must be Gtk_Image_Empty 185 -- (in which case this function will return null) or Gtk_Image_Pixbuf 186 -- (see Get_Storage_Type). The caller of this function does not own 187 -- a reference to the returned pixbuf. 188 189 procedure Set_From_Pixbuf 190 (Status_Icon : access Gtk_Status_Icon_Record; 191 Pixbuf : Gdk.Pixbuf.Gdk_Pixbuf); 192 -- Makes Status_Icon display Pixbuf. 193 -- See Gtk_New_From_Pixbuf for details. 194 195 ----------- 196 -- Stock -- 197 ----------- 198 199 procedure Gtk_New_From_Stock 200 (Widget : out Gtk_Status_Icon; 201 Stock_Id : String); 202 procedure Initialize_From_Stock 203 (Widget : access Gtk_Status_Icon_Record'Class; 204 Stock_Id : String); 205 -- Creates a status icon displaying a stock icon. Sample stock icon 206 -- names are "GTK_STOCK_OPEN", "GTK_STOCK_QUIT". You can register your 207 -- own stock icon names, see Gtk.Icon_Factory.Add_Default and 208 -- Gtk.Icon_Factory.Add. 209 210 function Get_Stock 211 (Status_Icon : access Gtk_Status_Icon_Record) return String; 212 -- Gets the id of the stock icon being displayed by the Gtk_Status_Icon. 213 -- The storage type of the status icon must be Image_Empty or 214 -- Image_Stock (see Get_Storage_Type). Returns "" if the image is empty. 215 216 procedure Set_From_Stock 217 (Status_Icon : access Gtk_Status_Icon_Record; 218 Stock_Id : String); 219 -- Makes Status_Icon display the stock icon with the id Stock_Id. 220 -- See Gtk_New_From_Stock for details. 221 222 -------------- 223 -- Tooltips -- 224 -------------- 225 226 function Get_Has_Tooltip 227 (Status_Icon : access Gtk_Status_Icon_Record) return Boolean; 228 procedure Set_Has_Tooltip 229 (Status_Icon : access Gtk_Status_Icon_Record; 230 Has_Tooltip : Boolean); 231 -- Gets/Sets the has-tooltip property on Status_Icon. 232 -- See has-tooltip for more information. 233 234 function Get_Tooltip_Markup 235 (Status_Icon : access Gtk_Status_Icon_Record) return String; 236 procedure Set_Tooltip_Markup 237 (Status_Icon : access Gtk_Status_Icon_Record; 238 Markup : String); 239 -- Gets/Sets Markup as the contents of the tooltip, which is marked up with 240 -- the Pango text markup language. "" means no tooltip. 241 -- 242 -- Set_Tooltip_Markup function will take care of setting has-tooltip to 243 -- True and of the default handler for the query-tooltip signal. 244 -- 245 -- See also the tooltip-markup property. 246 247 function Get_Tooltip_Text 248 (Status_Icon : access Gtk_Status_Icon_Record) return String; 249 procedure Set_Tooltip_Text 250 (Status_Icon : access Gtk_Status_Icon_Record; 251 Text : String); 252 -- Gets/Sets the contents of the tooltip. "" means no tooltip. 253 -- 254 -- This function will take care of setting has-tooltip to 255 -- True and of the default handler for the query-tooltip 256 -- signal. 257 -- 258 -- See also the tooltip-text property. 259 260 ------------- 261 -- Display -- 262 ------------- 263 264 procedure Get_Geometry 265 (Status_Icon : access Gtk_Status_Icon_Record; 266 Screen : in out Gdk.Screen.Gdk_Screen; 267 Area : out Gdk.Rectangle.Gdk_Rectangle; 268 Orientation : out Gtk.Enums.Gtk_Orientation; 269 Success : out Boolean); 270 -- Status_Icon: a Gtk_Status_Icon 271 -- Screen: a valid Gdk_Screen or null if the information is not needed 272 -- Area: area occupied by the status icon 273 -- Orientation: the orientation of the panel in which the status icon is 274 -- embedded. A panel at the top or bottom of the screen is 275 -- horizontal, a panel at the left or right is vertical. 276 -- Success: True if the location information has been filled in. 277 -- 278 -- Obtains information about the location of the status icon 279 -- on screen. This information can be used to e.g. position 280 -- popups like notification bubbles. 281 -- 282 -- See Position_Menu for a more convenient alternative for positioning 283 -- menus. 284 -- 285 -- Note that some platforms do not allow GTK+ to provide 286 -- this information, and even on platforms that do allow it, 287 -- the information is not reliable unless the status icon 288 -- is embedded in a notification area, see Is_Embedded. 289 290 function Get_Blinking 291 (Status_Icon : access Gtk_Status_Icon_Record) return Boolean; 292 procedure Set_Blinking 293 (Status_Icon : access Gtk_Status_Icon_Record; 294 Blinking : Boolean); 295 -- Makes the status icon start or stop blinking. 296 -- Note that blinking user interface elements may be problematic 297 -- for some users, and thus may be turned off, in which case 298 -- this setting has no effect. 299 300 function Get_Screen 301 (Status_Icon : access Gtk_Status_Icon_Record) 302 return Gdk.Screen.Gdk_Screen; 303 procedure Set_Screen 304 (Status_Icon : access Gtk_Status_Icon_Record; 305 Screen : access Gdk.Screen.Gdk_Screen_Record'Class); 306 -- Gets/Sets the Gdk_Screen where Status_Icon is displayed. When invoking 307 -- Set_Screen, if the icon is already mapped, it will be unmapped, and then 308 -- remapped on the new screen. 309 310 function Get_Size (Status_Icon : access Gtk_Status_Icon_Record) return Gint; 311 -- Gets the size in pixels that is available for the image. 312 -- Stock icons and named icons adapt their size automatically 313 -- if the size of the notification area changes. For other 314 -- storage types, the size-changed signal can be used to 315 -- react to size changes. 316 -- 317 -- Note that the returned size is only meaningful while the 318 -- status icon is embedded (see Is_Embedded). 319 320 function Get_Visible 321 (Status_Icon : access Gtk_Status_Icon_Record) return Boolean; 322 procedure Set_Visible 323 (Status_Icon : access Gtk_Status_Icon_Record; 324 Visible : Boolean); 325 -- Whether the status icon is visible or not. 326 -- Note that being visible does not guarantee that 327 -- the user can actually see the icon, see also 328 -- Is_Embedded. 329 330 function Get_X11_Window_Id 331 (Status_Icon : access Gtk_Status_Icon_Record) return Guint32; 332 -- This function is only useful on the X11/freedesktop.org platform. 333 -- It returns a window ID for the widget in the underlying 334 -- status icon implementation. This is useful for the Galago 335 -- notification service, which can send a window ID in the protocol 336 -- in order for the server to position notification windows 337 -- pointing to a status icon reliably. 338 -- 339 -- This function is not intended for other use cases which are 340 -- more likely to be met by one of the non-X11 specific methods, such 341 -- as Position_Menu. 342 343 procedure Position_Menu 344 (Menu : System.Address; 345 X : out Gint; 346 Y : out Gint; 347 Push_In : out Gboolean; 348 Status_Icon : System.Address); 349 -- Menu positioning function to use with Gtk.Menu.Popup to position 350 -- Menu aligned to Status_Icon. Pass Get_Object (Your_Status_Icon) as 351 -- User_Data when calling Gtk.Menu.Popup. 352 353 ----------------- 354 -- Obsolescent -- 355 ----------------- 356 357 procedure Set_Tooltip 358 (Status_Icon : access Gtk_Status_Icon_Record; 359 Tooltip_Text : String); 360 pragma Obsolescent; -- Set_Tooltip 361 -- Sets the tooltip of the status icon. 362 -- 363 -- Deprecated: 2.16: Use Set_Tooltip_Text instead. 364 365 ---------------- 366 -- Properties -- 367 ---------------- 368 369 -- <properties> 370 -- Name: Blinking_Property 371 -- Type: Boolean 372 -- Descr: Whether or not the status icon is blinking 373 -- 374 -- Name: Embedded_Property 375 -- Type: Boolean 376 -- Descr: Whether or not the status icon is embedded 377 -- 378 -- Name: File_Property 379 -- Type: String 380 -- Descr: Filename to load and display 381 -- 382 -- Name: Gicon_Property 383 -- Type: Object 384 -- Descr: The GIcon being displayed 385 -- 386 -- Name: Has_Tooltip_Property 387 -- Type: Boolean 388 -- Descr: Whether this tray icon has a tooltip 389 -- 390 -- Name: Icon_Name_Property 391 -- Type: String 392 -- Descr: The name of the icon from the icon theme 393 -- 394 -- Name: Orientation_Property 395 -- Type: Enum 396 -- Descr: The orientation of the tray 397 -- 398 -- Name: Pixbuf_Property 399 -- Type: Object 400 -- Descr: A Gdk_Pixbuf to display 401 -- 402 -- Name: Screen_Property 403 -- Type: Object 404 -- Descr: The screen where this status icon will be displayed 405 -- 406 -- Name: Size_Property 407 -- Type: Int 408 -- Descr: The size of the icon 409 -- 410 -- Name: Stock_Property 411 -- Type: String 412 -- Descr: Stock ID for a stock image to display 413 -- 414 -- Name: Storage_Type_Property 415 -- Type: Enum 416 -- Descr: The representation being used for image data 417 -- 418 -- Name: Tooltip_Markup_Property 419 -- Type: String 420 -- Descr: The contents of the tooltip for this tray icon 421 -- 422 -- Name: Tooltip_Text_Property 423 -- Type: String 424 -- Descr: The contents of the tooltip for this widget 425 -- 426 -- Name: Visible_Property 427 -- Type: Boolean 428 -- Descr: Whether or not the status icon is visible 429 -- 430 -- </properties> 431 432 Blinking_Property : constant Glib.Properties.Property_Boolean; 433 Embedded_Property : constant Glib.Properties.Property_Boolean; 434 File_Property : constant Glib.Properties.Property_String; 435 Gicon_Property : constant Glib.Properties.Property_Object; 436 Has_Tooltip_Property : constant Glib.Properties.Property_Boolean; 437 Icon_Name_Property : constant Glib.Properties.Property_String; 438 Orientation_Property : constant Glib.Properties.Property_Enum; 439 Pixbuf_Property : constant Glib.Properties.Property_Object; 440 Screen_Property : constant Glib.Properties.Property_Object; 441 Size_Property : constant Glib.Properties.Property_Int; 442 Stock_Property : constant Glib.Properties.Property_String; 443 Storage_Type_Property : constant Glib.Properties.Property_Enum; 444 Tooltip_Markup_Property : constant Glib.Properties.Property_String; 445 Tooltip_Text_Property : constant Glib.Properties.Property_String; 446 Visible_Property : constant Glib.Properties.Property_Boolean; 447 448private 449 450 type Gtk_Status_Icon_Record is 451 new Glib.Object.GObject_Record with null record; 452 453 Blinking_Property : constant Glib.Properties.Property_Boolean := 454 Glib.Properties.Build ("blinking"); 455 Embedded_Property : constant Glib.Properties.Property_Boolean := 456 Glib.Properties.Build ("embedded"); 457 File_Property : constant Glib.Properties.Property_String := 458 Glib.Properties.Build ("file"); 459 Gicon_Property : constant Glib.Properties.Property_Object := 460 Glib.Properties.Build ("gicon"); 461 Has_Tooltip_Property : constant Glib.Properties.Property_Boolean := 462 Glib.Properties.Build ("has-tooltip"); 463 Icon_Name_Property : constant Glib.Properties.Property_String := 464 Glib.Properties.Build ("icon-name"); 465 Orientation_Property : constant Glib.Properties.Property_Enum := 466 Glib.Properties.Build ("orientation"); 467 Pixbuf_Property : constant Glib.Properties.Property_Object := 468 Glib.Properties.Build ("pixbuf"); 469 Screen_Property : constant Glib.Properties.Property_Object := 470 Glib.Properties.Build ("screen"); 471 Size_Property : constant Glib.Properties.Property_Int := 472 Glib.Properties.Build ("size"); 473 Stock_Property : constant Glib.Properties.Property_String := 474 Glib.Properties.Build ("stock"); 475 Storage_Type_Property : constant Glib.Properties.Property_Enum := 476 Glib.Properties.Build ("storage-type"); 477 Tooltip_Markup_Property : constant Glib.Properties.Property_String := 478 Glib.Properties.Build ("tooltip-markup"); 479 Tooltip_Text_Property : constant Glib.Properties.Property_String := 480 Glib.Properties.Build ("tooltip-text"); 481 Visible_Property : constant Glib.Properties.Property_Boolean := 482 Glib.Properties.Build ("visible"); 483 484 pragma Import (C, Get_Type, "gtk_status_icon_get_type"); 485 pragma Import (C, Position_Menu, "gtk_status_icon_position_menu"); 486 487end Gtk.Status_Icon; 488