/* Copyright (C) 2003 The gtkmm Development Team
 *
 * This library 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 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

_CONFIGINCLUDE(gtkmmconfig.h)

#include <vector>

#include <gtkmm/widget.h>
#include <gtkmm/accelgroup.h>
#include <gtkmm/stockid.h>
#include <giomm/icon.h>

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

#m4 _PUSH(SECTION_CC_PRE_INCLUDES)
#undef GTK_DISABLE_DEPRECATED
#define GDK_DISABLE_DEPRECATION_WARNINGS 1
#m4 _POP()

//TODO: Deprecate this when we are ready. It is already deprecated in GTK+.
//_IS_DEPRECATED // This whole file is deprecated.

namespace Gtk
{

class ActionGroup;
class Menu;
class MenuItem;
class ToolItem;
class Image;

/** An action which can be triggered by a menu or toolbar item.
 *
 * Actions represent operations that the user can perform, along with
 * some information about how it should be presented in the user interface.
 * Each action provides methods to create icons, menu items and toolbar
 * items representing itself.
 *
 * As well as the callback that is called when the action is activated,
 * the following is also associated with the action:
 *
 *  - a name (not translated, for path lookup)
 *  - a label (translated, for display)
 *  - an accelerator
 *  - whether the label indicates a stock id
 *  - a tooltip (optional, translated)
 *  - a toolbar label (optional, shorter than label)
 *
 * The action will also have some state information:
 *
 *  - visible (shown/hidden)
 *  - sensitive (enabled/disabled)
 *
 * Apart from regular actions, there are toggle actions,
 * which can be toggled between two states and radio actions,
 * of which only one in a group can be in the "active" state.
 * Other actions can be implemented as Gtk::Action subclasses.
 *
 * Each action can have one or more proxy menu item, toolbar button or other proxy widgets.
 * Proxies mirror the state of the action (text label, tooltip, icon, visible, sensitive, etc), and should change when the action's state changes. When the proxy is activated, it should activate its action.
 */
class Action
  : public Glib::Object,
    public Buildable
{
  _CLASS_GOBJECT(Action, GtkAction, GTK_ACTION, Glib::Object, GObject)
  _IMPLEMENTS_INTERFACE(Buildable)

protected:
  /** Creates an empty action.
   * @deprecated See the description of class Action.
   */
  _CTOR_DEFAULT

#ifndef GTKMM_DISABLE_DEPRECATED
  /** Creates an action with a stock ID.
   * The stock ID is used to set a default icon, text and accelerator for the
   * action.
   *
   * @param name     A unique name for the action.
   * @param stock_id The stock icon to display in widgets representing the
   *                 action.
   * @param label    The label displayed in menu items and on buttons.
   * @param tooltip  A tooltip for the action.
   * @deprecated See the description of class Action.
   */
  explicit Action(const Glib::ustring& name, const StockID& stock_id = StockID(), const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
#endif //GTKMM_DISABLE_DEPRECATED

#ifndef GTKMM_DISABLE_DEPRECATED
  /** Creates an action with an icon name.
   * The action's icon will reflect the specified icon name in the user's
   * icon theme.
   *
   * @param name      A unique name for the action.
   * @param icon_name An IconTheme icon name used for widgets representing the
   *                  action.
   * @param label     The label displayed in menu items and on buttons.
   * @param tooltip   A tooltip for the action.
   * @deprecated See the description of class Action.
   */
  explicit Action(const Glib::ustring& name, const Glib::ustring& icon_name, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
#endif //GTKMM_DISABLE_DEPRECATED

public:
  //Note that gtk_action_new() does not allow name to be NULL, which suggests that we should not have a default constructor,
  //but it's OK to set the name later:
  /** @deprecated See the description of class Action.
   */
  _WRAP_CREATE()

#ifndef GTKMM_DISABLE_DEPRECATED
  /** Creates an action.
   *
   * @param name    A unique name for the action.
   * @param label   The label displayed in menu items and on buttons.
   * @param tooltip A tooltip for the action.
   *
   * @return A new Action.
   * @deprecated See the description of class Action.
   */
  static Glib::RefPtr<Action> create(const Glib::ustring& name, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
#endif //GTKMM_DISABLE_DEPRECATED

#ifndef GTKMM_DISABLE_DEPRECATED
  /** Creates an action with a stock ID.
   * The stock ID is used to set a default icon, text and accelerator for the
   * action.
   *
   * @param name     A unique name for the action.
   * @param stock_id The stock icon to display in widgets representing the
   *                 action.
   * @param label    The label displayed in menu items and on buttons.
   * @param tooltip  A tooltip for the action.
   *
   * @return A new Action.
   * @deprecated See the description of class Action.
   */
  static Glib::RefPtr<Action> create(const Glib::ustring& name, const Gtk::StockID& stock_id, const Glib::ustring& label = Glib::ustring(), const Glib::ustring& tooltip = Glib::ustring());
#endif //GTKMM_DISABLE_DEPRECATED

#ifndef GTKMM_DISABLE_DEPRECATED
  /** Create an action with an icon name.
   * The action's icon will reflect the specified icon name in the user's
   * icon theme.
   *
   * @param name      A unique name for the action.
   * @param icon_name An IconTheme icon name used for widgets representing the
   *                  action.
   * @param label     The label displayed in menu items and on buttons.
   * @param tooltip   A tooltip for the action.
   *
   * @return A new Action.
   * @deprecated See the description of class Action.
   */
  static Glib::RefPtr<Action> create_with_icon_name(const Glib::ustring& name, const Glib::ustring& icon_name, const Glib::ustring& label, const Glib::ustring& tooltip);
#endif //GTKMM_DISABLE_DEPRECATED

  _WRAP_METHOD(Glib::ustring get_name() const, gtk_action_get_name, deprecated "See the description of class Action.")

  _WRAP_METHOD(bool is_sensitive() const, gtk_action_is_sensitive, deprecated "See the description of class Action.")
  _WRAP_METHOD(bool get_sensitive() const, gtk_action_get_sensitive, deprecated "See the description of class Action.")

  _WRAP_METHOD(void set_sensitive(bool sensitive = true), gtk_action_set_sensitive, deprecated "See the description of class Action.")

  _WRAP_METHOD(bool is_visible() const, gtk_action_is_visible, deprecated "See the description of class Action.")
  _WRAP_METHOD(bool get_visible() const, gtk_action_get_visible, deprecated "See the description of class Action.")
  _WRAP_METHOD(void set_visible(bool visible = true), gtk_action_set_visible, deprecated "See the description of class Action.")

  _WRAP_METHOD(void activate(), gtk_action_activate, deprecated "See the description of class Action.")
  _WRAP_METHOD(Image* create_icon(IconSize icon_size), gtk_action_create_icon, deprecated "See the description of class Action.")
  _WRAP_METHOD(MenuItem* create_menu_item(), gtk_action_create_menu_item, deprecated "See the description of class Action.")
  _WRAP_METHOD(ToolItem* create_tool_item(), gtk_action_create_tool_item, deprecated "See the description of class Action.")
  _WRAP_METHOD(Menu* create_menu(), gtk_action_create_menu, deprecated "See the description of class Action.")

  _IGNORE(gtk_action_connect_proxy, gtk_action_disconnect_proxy) // deprecated

#m4 dnl // This isn't in convert_gtk.m4, and the default behaviour is wrong.
#m4 _CONVERSION(`GSList*', `std::vector<Widget*>', `Glib::SListHandler<Widget*>::slist_to_vector($3, Glib::OWNERSHIP_NONE)')
#m4 _CONVERSION(`GSList*', `std::vector<const Widget*>', `Glib::SListHandler<const Widget*>::slist_to_vector($3, Glib::OWNERSHIP_NONE)')

  _WRAP_METHOD(std::vector<Widget*> get_proxies(), gtk_action_get_proxies, deprecated "See the description of class Action.")
  _WRAP_METHOD(std::vector<const Widget*> get_proxies() const, gtk_action_get_proxies, deprecated "See the description of class Action.")

  _WRAP_METHOD(void connect_accelerator(), gtk_action_connect_accelerator, deprecated "See the description of class Action.")
  _WRAP_METHOD(void disconnect_accelerator(), gtk_action_disconnect_accelerator, deprecated "See the description of class Action.")

  _WRAP_METHOD(Glib::ustring get_accel_path() const, gtk_action_get_accel_path, deprecated "See the description of class Action.")

  /// For instance, void on_activate();
  typedef sigc::slot<void> SlotActivate;

  _WRAP_SIGNAL(void activate(), "activate", deprecated "See the description of class Action.")

  //Used by AccelGroup:
  _WRAP_METHOD(void set_accel_path(const Glib::ustring& accel_path), gtk_action_set_accel_path, deprecated "See the description of class Action.")
  _WRAP_METHOD(void set_accel_group(const Glib::RefPtr<AccelGroup>& accel_group), gtk_action_set_accel_group, deprecated "See the description of class Action.")

  _WRAP_METHOD(void set_label(const Glib::ustring& label), gtk_action_set_label, deprecated "See the description of class Action.")
  _WRAP_METHOD(Glib::ustring get_label() const, gtk_action_get_label, deprecated "See the description of class Action.")
  _WRAP_METHOD(void set_short_label(const Glib::ustring& short_label), gtk_action_set_short_label, deprecated "See the description of class Action.")
  _WRAP_METHOD(Glib::ustring get_short_label() const, gtk_action_get_short_label, deprecated "See the description of class Action.")
  _WRAP_METHOD(void set_tooltip(const Glib::ustring& tooltip), gtk_action_set_tooltip, deprecated "See the description of class Action.")
  _WRAP_METHOD(Glib::ustring get_tooltip() const, gtk_action_get_tooltip, deprecated "See the description of class Action.")
  _WRAP_METHOD(void set_stock_id(const StockID& stock_id), gtk_action_set_stock_id, deprecated "See the description of class Action.")
  _WRAP_METHOD(StockID get_stock_id() const, gtk_action_get_stock_id, deprecated "See the description of class Action.")
  _WRAP_METHOD(void set_gicon(const Glib::RefPtr<Gio::Icon>& icon), gtk_action_set_gicon, deprecated "See the description of class Action.")
  _WRAP_METHOD(Glib::RefPtr<Gio::Icon> get_gicon(), gtk_action_get_gicon, refreturn, deprecated "See the description of class Action.")
  _WRAP_METHOD(Glib::RefPtr<const Gio::Icon> get_gicon() const, gtk_action_get_gicon, refreturn, constversion, deprecated "See the description of class Action.")
  _WRAP_METHOD(void set_icon_name(const Glib::ustring& icon_name), gtk_action_set_icon_name, deprecated "See the description of class Action.")
  _WRAP_METHOD(Glib::ustring get_icon_name() const, gtk_action_get_icon_name, deprecated "See the description of class Action.")
  _WRAP_METHOD(void set_visible_horizontal(bool visible_horizontal = true), gtk_action_set_visible_horizontal, deprecated "See the description of class Action.")
  _WRAP_METHOD(bool get_visible_horizontal() const, gtk_action_get_visible_horizontal, deprecated "See the description of class Action.")
  _WRAP_METHOD(void set_visible_vertical(bool visible_vertical = true), gtk_action_set_visible_vertical, deprecated "See the description of class Action.")
  _WRAP_METHOD(bool get_visible_vertical() const, gtk_action_get_visible_vertical, deprecated "See the description of class Action.")
  _WRAP_METHOD(void set_is_important(bool is_important = true), gtk_action_set_is_important, deprecated "See the description of class Action.")
  _WRAP_METHOD(bool get_is_important() const, gtk_action_get_is_important, deprecated "See the description of class Action.")

  _WRAP_METHOD(void set_always_show_image(bool always_show = true), gtk_action_set_always_show_image, deprecated "See the description of class Action.")
  _WRAP_METHOD(bool get_always_show_image() const, gtk_action_get_always_show_image, deprecated "See the description of class Action.")

  _WRAP_METHOD(void block_activate(), gtk_action_block_activate, deprecated "See the description of class Action.")
  _WRAP_METHOD(void unblock_activate(), gtk_action_unblock_activate, deprecated "See the description of class Action.")

  //gtk_action_get_accel_closure() is too C-specific:
  _IGNORE(gtk_action_get_accel_closure)

  _WRAP_PROPERTY("name", Glib::ustring, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("label", Glib::ustring, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("short_label", Glib::ustring, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("tooltip", Glib::ustring, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("stock_id", StockID, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("gicon", Glib::RefPtr<Gio::Icon>, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("icon_name", Glib::ustring, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("visible_horizontal", bool, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("visible_vertical", bool, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("visible_overflown", bool, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("is_important", bool, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("hide_if_empty", bool, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("sensitive", bool, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("visible", bool, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("action_group", Glib::RefPtr<ActionGroup>, deprecated "See the description of class Action.")
  _WRAP_PROPERTY("always-show-image", bool, deprecated "See the description of class Action.")

protected:
  _IGNORE(gtk_action_block_activate_from, gtk_action_unblock_activate_from) //deprecated

protected:
  //Widget-creation routines:
  /** @deprecated See the description of class Action.
   */
  _WRAP_VFUNC(Widget* create_menu_item(), "create_menu_item")
  /** @deprecated See the description of class Action.
   */
  _WRAP_VFUNC(Widget* create_tool_item(), "create_tool_item")
  /** @deprecated See the description of class Action.
   */
  _WRAP_VFUNC(void connect_proxy(Widget* proxy), "connect_proxy")
  /** @deprecated See the description of class Action.
   */
  _WRAP_VFUNC(void disconnect_proxy(Widget* proxy), "disconnect_proxy")
};

} // namespace Gtk
