livetrax/libs/gtkmm2/gtk/src/statusicon.hg

/* $Id: statusicon.hg,v 1.6 2006/07/05 16:59:28 murrayc Exp $ */

/* Copyright (C) 2005 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library 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
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */


_DEFS(gtkmm,gtk)
_PINCLUDE(glibmm/private/object_p.h)

#include <gtkmm/image.h> //For ImageType.
#include <gtkmm/stockid.h>
#include <gtkmm/menu.h>
#include <gdkmm/pixbuf.h>
#include <gdkmm/types.h>
#include <gtkmm/object.h>


namespace Gtk
{

/** The "system tray" or notification area is normally used for transient icons that indicate some 
 * special state. For example, a system tray icon might appear to tell the user that they have new 
 * mail, or have an incoming instant message, or something along those lines. The basic idea is 
 * that creating an icon in the notification area is less annoying than popping up a dialog.
 *
 * A StatusIcon object can be used to display an icon in a "system tray". The icon can have a 
 * tooltip, and the user can interact with it by activating it or popping up a context menu. 
 * Critical information should not solely be displayed in a StatusIcon, since it may not be 
 * visible (e.g. when the user doesn't have a notification area on his panel). This can be checked 
 * with is_embedded().
 *
 * On X11, the implementation follows the freedesktop.org "System Tray" specification.  
 * Implementations of the "tray" side of this specification can be found e.g. in the GNOME and KDE 
 * panel applications. 
 *
 * @newin2p10
 */
class StatusIcon : public Glib::Object
{
   _CLASS_GOBJECT(StatusIcon, GtkStatusIcon, GTK_STATUS_ICON, Glib::Object, GObject)
protected:
  _CTOR_DEFAULT
  _IGNORE(gtk_status_icon_new)
  _WRAP_CTOR(StatusIcon(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf), gtk_status_icon_new_from_pixbuf)
  _WRAP_CTOR(StatusIcon(const StockID& stock), gtk_status_icon_new_from_stock)
  _WRAP_CTOR(StatusIcon(const Glib::ustring& icon_name), gtk_status_icon_new_from_icon_name)

public:
  /** Creates a new Gtk::StatusIcon object.
   * @return A Glib::RefPtr<> to a newly created Gtk::StatusIcon object.
   */
  _WRAP_CREATE(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf)
  _WRAP_CREATE(const StockID& stock_id)
  _WRAP_CREATE(const Glib::ustring& icon_name)

 /** Creates a status icon displaying the file @a filename. 
  * The image will be scaled down to fit in the available 
  * space in the notification area, if necessary.
  * 
  * @param filename A filename.
  * @result A new StatusIcon
  *
  * @newin2p10
  */
  static Glib::RefPtr<StatusIcon> create_from_file(const std::string& filename);
  _IGNORE(gtk_status_icon_new_from_file)

  _WRAP_METHOD(void set(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf), gtk_status_icon_set_from_pixbuf)
  _WRAP_METHOD(void set_from_file(const Glib::ustring& filename), gtk_status_icon_set_from_file)
  _WRAP_METHOD(void set(const StockID& stock_id), gtk_status_icon_set_from_stock)
  _WRAP_METHOD(void set(const Glib::ustring& icon_name), gtk_status_icon_set_from_icon_name)

  _WRAP_METHOD(ImageType get_storage_type() const, gtk_status_icon_get_storage_type)

  _WRAP_METHOD(Glib::RefPtr<Gdk::Pixbuf> get_pixbuf(), gtk_status_icon_get_pixbuf)
  _WRAP_METHOD(Glib::RefPtr<const Gdk::Pixbuf> get_pixbuf() const, gtk_status_icon_get_pixbuf, constversion)

  _WRAP_METHOD(StockID get_stock() const, gtk_status_icon_get_stock)
  _WRAP_METHOD(Glib::ustring get_icon_name() const, gtk_status_icon_get_icon_name)

  _WRAP_METHOD(int get_size() const, gtk_status_icon_get_size)

  _WRAP_METHOD(void set_screen(const Glib::RefPtr<Gdk::Screen>& screen), gtk_status_icon_set_screen)
  _WRAP_METHOD(Glib::RefPtr<Gdk::Screen> get_screen(), gtk_status_icon_get_screen, refreturn)
  _WRAP_METHOD(Glib::RefPtr<const Gdk::Screen> get_screen() const, gtk_status_icon_get_screen, refreturn, constversion)

  _WRAP_METHOD(void set_tooltip(const Glib::ustring& tooltip_text), gtk_status_icon_set_tooltip)

  _WRAP_METHOD(void set_visible(bool visible = true), gtk_status_icon_set_visible)
  _WRAP_METHOD(bool get_visible() const, gtk_status_icon_get_visible)
  _WRAP_METHOD(void set_blinking(bool blinking = true), gtk_status_icon_set_blinking)
  _WRAP_METHOD(bool get_blinking() const, gtk_status_icon_get_blinking)

  _WRAP_METHOD(bool is_embedded() const, gtk_status_icon_is_embedded)

  /** Displays a menu aligned to the status icon, and makes it available for selection. 
   * Applications can use this function to display context-sensitive menus.
   *
   * This is equivalent to the gtk_status_icon_position_menu() helper callback in GTK+, 
   * which can be provided to gtk_menu_popup().
   *
   * See Gtk::Menu::popup() for more details.
   *
   * @param menu The menu to popup for the status icon.
   * @param button The mouse button which was pressed to initiate the event.
   * @param activate_time The time at which the activation event occurred.
   *
   * @newin2p12
   */
  void popup_menu_at_position(Menu& menu, guint button, guint32 activate_time);
  _IGNORE(gtk_status_icon_position_menu)
   //Note that gtk_status_icon_position_menu() is meant to be used as a helpful callback when calling gtk_menu_popup().
   //We make it easier by just providing a popup method that uses it. 


  //In gtk_status_icon_get_geometry(), any of the parameters may be NULL,
  //but we don't need 6 different overloads, with different parameters.
  //But we can add some if there are common cases.

  /** Obtains information about the location of the status icon
   * on screen. This information can be used to e.g. position 
   * popups like notification bubbles. 
   * See popup_menu_at_position() for a more convenient 
   * alternative for positioning menus.
   *
   * Note that some platforms do not allow GTK+ to provide 
   * this information.
   *
   * @param screen: The screen.
   * @param area The area occupied by the status icon.
   * @param orientation The orientation of the panel  in which the status icon is embedded. A panel 
   * at the top or bottom of the screen is horizontal, a panel at the left or right is vertical.
   * @result true if the location information has been filled in.
   *
   * @newin2p10
   */
  bool get_geometry(Glib::RefPtr<Gdk::Screen>& screen, Gdk::Rectangle& area, Orientation& orientation);
  _IGNORE(gtk_status_icon_get_geometry)

  _WRAP_PROPERTY("pixbuf", Glib::RefPtr<Gdk::Pixbuf>)
  _WRAP_PROPERTY("file", std::string)
  _WRAP_PROPERTY("stock", StockID)
  _WRAP_PROPERTY("icon-name", Glib::ustring)
  _WRAP_PROPERTY("storage-type", ImageType)
  _WRAP_PROPERTY("size", int)
  _WRAP_PROPERTY("blinking", bool)

  _WRAP_SIGNAL(bool size_changed(int size), size_changed)

  //TODO: Remove no_default_handler when we can break ABI.
  /* These are keybinding signals, which should usually not be wrapped, 
     unless there is explicit documentation saying that the should be 
     used by applications. We have asked repeatedly for clarification about these 
     particular signals, but received no clear answer.
     We have decided to take the risk, because they really do seem to be necessary,
     for responding to status icon activation and requests to show their popup menu.
     murrayc.
   */
  _WRAP_SIGNAL(void activate(), activate, no_default_handler)
  _WRAP_SIGNAL(void popup_menu(guint button, guint32 activate_time), popup_menu, no_default_handler)
};

} // namespace Gtk