/* $Id: menushell.hg,v 1.9 2006/06/21 20:04:25 murrayc Exp $ */

/* Copyright (C) 1998-2002 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.
 */
 
#include <gdk/gdkkeysyms.h>
_DEFS(gtkmm,gtk)
_PINCLUDE(gtkmm/private/container_p.h)
_PINCLUDE(gtkmm/menu.h)
_PINCLUDE(gtkmm/menubar.h)
_PINCLUDE(gtkmm/window.h)

#include <gtkmm/container.h>
#include <gtkmm/menu_elems.h>
#include <glibmm/helperlist.h>

namespace Gtk
{

class Menu;
class MenuShell;
class Window;

namespace Menu_Helpers
{

/*********************************************************************
***** List properties
*********************************************************************/

#m4 include(list.m4)
  GP_LIST(MenuList,MenuShell,GtkMenuShell,MenuItem,children)
  GP_LIST_HELPER_NAMESPACE(Menu_Helpers)
  GP_LIST_ITER(Glib::List_Cpp_Iterator<GtkMenuItem, MenuItem>)
  virtual void remove(Widget& widget); //custom
  GP_LIST_END()

} // namespace Menu_Helpers


/** The abstract base class for Gtk::Menu and Gtk::MenuBar.
 * It is a container of Gtk::MenuItem objects arranged in a list which can be navigated, selected, and activated by the user to perform application functions.
 * It can have a submenu associated with it, allowing for nested hierarchical menus.
 * You can use append(), prepend() and insert() to add Gtk::MenuItem widgets,
 * but you will probably find it more convenient to use the STL-style items() interface with the Gtk::Menu_Helpers::MenuElem() class.
 * @ingroup Widgets
 * @ingroup Containers
 * @ingroup Menus
 */
class MenuShell : public Container 
{
  _CLASS_GTKOBJECT(MenuShell,GtkMenuShell,GTK_MENU_SHELL,Gtk::Container,GtkContainer)

public:
  _CUSTOM_DTOR()

  typedef Menu_Helpers::MenuList MenuList;
  friend class Menu_Helpers::MenuList;

  _WRAP_METHOD(void append(MenuItem& menu_item), gtk_menu_shell_append)
  _WRAP_METHOD(void prepend(MenuItem& menu_item), gtk_menu_shell_prepend)
  _WRAP_METHOD(void insert(MenuItem& menu_item, int position), gtk_menu_shell_insert)

  _WRAP_METHOD(void select_item(MenuItem& menu_item), gtk_menu_shell_select_item)
  _WRAP_METHOD(void deselect(), gtk_menu_shell_deselect)

  //TODO: Is force_deactivate = false a good default?
  _WRAP_METHOD(void activate_item(MenuItem& menu_item, bool force_deactivate = false), gtk_menu_shell_activate_item)
  _WRAP_METHOD(void select_first(bool search_sensitive = true), gtk_menu_shell_select_first)
  _WRAP_METHOD(void deactivate(), gtk_menu_shell_deactivate)
  _WRAP_METHOD(void cancel(), gtk_menu_shell_cancel)

  _WRAP_SIGNAL(void deactivate(), "deactivate")
  _WRAP_SIGNAL(void selection_done(), "selection_done")
  _WRAP_SIGNAL(gboolean move_selected(int  distance), "move-selected", no_default_handler)

  //Keybinding signals:
  _IGNORE_SIGNAL("move_current")
  _IGNORE_SIGNAL("activate_current")
  _IGNORE_SIGNAL("cancel")
  _IGNORE_SIGNAL("cycle-focus")

  MenuList& items();
  const MenuList& items() const;

  /**
   * Initializes menu accelerators.
   * This method initializes the menu accelerators. Therefore an
   * AccelGroup object is needed which is stored in each Window object
   * in the Gtkmm library implementation.
   *
   * When using MenuBar and OptionMenu objects this method is called
   * automatically when the menus are realized. Because most likely the
   * MenuBar and OptionMenu is attached to a window at this time and
   * the window object can be found automatically.
   *
   * Important note when using popup menus: 
   * If you are using accelerated menu entries inside a popup
   * menu you have to call the accelerate() method manually. This is
   * because the popup menu is not connected to any window and the
   * accelerators should be initialized even before the popup menu is
   * shown. The right place to call the accelerate() method is right
   * after the popup menu has been build.
   *
   * @param window Window where the menu is shown. Inside this window
   *   the AccelGroup object is stored that will be used to initialize
   *   the accelerators.
   */
  void accelerate(Window& window);

  /**
   * Initializes menu accelerators.
   * Does the same as the accelerate(Window& window) method. But you can
   * use any parent widget where the menu is used. This method then gets
   * the toplevel window using Widget::get_toplevel() and uses this
   * window for registering the menu accelerators.
   *
   * @param parent Parent widget used as starting point for searching
   *   the toplevel window.
   */
  void accelerate(Widget& parent);

  _WRAP_METHOD(bool get_take_focus() const, gtk_menu_shell_get_take_focus)
  _WRAP_METHOD(void set_take_focus(bool take_focus = true), gtk_menu_shell_set_take_focus)
  
  _WRAP_PROPERTY("take-focus", bool)

protected:
  MenuShell();
  _CUSTOM_CTOR_CAST()

private:

#m4begin
dnl // Override GtkMenuItem::insert, in order to accelerate all menu items automagically.
  _PUSH(SECTION_PCC_CLASS_INIT_VFUNCS)
    klass->insert = &insert_vfunc_callback;
  _SECTION(SECTION_PH_VFUNCS)
#endif //GLIBMM_VFUNCS_ENABLED //We always need insert_vfunc_callback
    static void insert_vfunc_callback(GtkMenuShell* self, GtkWidget* child, int position);
#ifdef GLIBMM_VFUNCS_ENABLED
  _POP()
#m4end

  MenuList      items_proxy_;
  Gtk::Window*  accel_window_;
};

} // namespace Gtk