libglibmm-2.4-dev 2.32.1-1 / usr / include / giomm-2.4 / giomm / menuitem.h

// -*- c++ -*-
// Generated by gtkmmproc -- DO NOT MODIFY!
#ifndef _GIOMM_MENUITEM_H
#define _GIOMM_MENUITEM_H


#include <glibmm/ustring.h>
#include <sigc++/sigc++.h>

/* Copyright (C) 2012 The giomm 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., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <glibmm/object.h>
#include <giomm/menumodel.h>


#ifndef DOXYGEN_SHOULD_SKIP_THIS
typedef struct _GMenuItem GMenuItem;
typedef struct _GMenuItemClass GMenuItemClass;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */


namespace Gio
{ class MenuItem_Class; } // namespace Gio
namespace Gio
{

/** TODO
 *
 * @newin{2,32}
 */

class MenuItem : public Glib::Object
{
  
#ifndef DOXYGEN_SHOULD_SKIP_THIS

public:
  typedef MenuItem CppObjectType;
  typedef MenuItem_Class CppClassType;
  typedef GMenuItem BaseObjectType;
  typedef GMenuItemClass BaseClassType;

private:  friend class MenuItem_Class;
  static CppClassType menuitem_class_;

private:
  // noncopyable
  MenuItem(const MenuItem&);
  MenuItem& operator=(const MenuItem&);

protected:
  explicit MenuItem(const Glib::ConstructParams& construct_params);
  explicit MenuItem(GMenuItem* castitem);

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

public:
  virtual ~MenuItem();

#ifndef DOXYGEN_SHOULD_SKIP_THIS
  static GType get_type()      G_GNUC_CONST;


  static GType get_base_type() G_GNUC_CONST;
#endif

  ///Provides access to the underlying C GObject.
  GMenuItem*       gobj()       { return reinterpret_cast<GMenuItem*>(gobject_); }

  ///Provides access to the underlying C GObject.
  const GMenuItem* gobj() const { return reinterpret_cast<GMenuItem*>(gobject_); }

  ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
  GMenuItem* gobj_copy();

private:


protected:
    explicit MenuItem(const Glib::ustring& label =  Glib::ustring(), const Glib::ustring& detailed_action =  Glib::ustring());


  //TODO: label can be empty, so reorder these parameters?
    explicit MenuItem(const Glib::ustring& label, const Glib::RefPtr<MenuModel>& submenu);


public:
  
  static Glib::RefPtr<MenuItem> create(const Glib::ustring& label, const Glib::ustring& detailed_action);


  static Glib::RefPtr<MenuItem> create(const Glib::ustring& label, const Glib::RefPtr<MenuModel>& submenu);


//TODO: GMenuItem * g_menu_item_new_section                 (const Glib::ustring& label,
//                                                     const Glib::RefPtr<MenuModel>& section);

  
  /** Sets or unsets an attribute on @a menu_item.
   * 
   * The attribute to set or unset is specified by @a attribute. This
   * can be one of the standard attribute names MENU_ATTRIBUTE_LABEL,
   * MENU_ATTRIBUTE_ACTION, MENU_ATTRIBUTE_TARGET, or a custom
   * attribute name.
   * Attribute names are restricted to lowercase characters, numbers
   * and '-'. Furthermore, the names must begin with a lowercase character,
   * must not end with a '-', and must not contain consecutive dashes.
   * 
   * must consist only of lowercase
   * ASCII characters, digits and '-'.
   * 
   * If @a value is non-<tt>0</tt> then it is used as the new value for the
   * attribute.  If @a value is <tt>0</tt> then the attribute is unset. If
   * the @a value Variant is floating, it is consumed.
   * 
   * See also g_menu_item_set_attribute() for a more convenient way to do
   * the same.
   * 
   * @newin{2,32}
   * @param attribute The attribute to set.
   * @param value A Variant to use as the value, or <tt>0</tt>.
   */
  void set_attribute_value(const Glib::ustring& attribute, const Glib::VariantBase& value);
  

  /** Creates a link from @a menu_item to @a model if non-<tt>0</tt>, or unsets it.
   * 
   * Links are used to establish a relationship between a particular menu
   * item and another menu.  For example, MENU_LINK_SUBMENU is used to
   * associate a submenu with a particular menu item, and MENU_LINK_SECTION
   * is used to create a section. Other types of link can be used, but there
   * is no guarantee that clients will be able to make sense of them.
   * Link types are restricted to lowercase characters, numbers
   * and '-'. Furthermore, the names must begin with a lowercase character,
   * must not end with a '-', and must not contain consecutive dashes.
   * 
   * @newin{2,32}
   * @param link Type of link to establish or unset.
   * @param model The MenuModel to link to (or <tt>0</tt> to unset).
   */
  void set_link(const Glib::ustring& link, const Glib::RefPtr<MenuModel>& model);
  
  /** Sets or unsets the "label" attribute of @a menu_item.
   * 
   * If @a label is non-<tt>0</tt> it is used as the label for the menu item.  If
   * it is <tt>0</tt> then the label attribute is unset.
   * 
   * @newin{2,32}
   * @param label The label to set, or <tt>0</tt> to unset.
   */
  void set_label(const Glib::ustring& label);
  
  /** Sets or unsets the "submenu" link of @a menu_item to @a submenu.
   * 
   * If @a submenu is non-<tt>0</tt>, it is linked to.  If it is <tt>0</tt> then the
   * link is unset.
   * 
   * The effect of having one menu appear as a submenu of another is
   * exactly as it sounds.
   * 
   * @newin{2,32}
   * @param submenu A MenuModel, or <tt>0</tt>.
   */
  void set_submenu(const Glib::RefPtr<MenuModel>& submenu);
  
  /** Sets or unsets the "section" link of @a menu_item to @a section.
   * 
   * The effect of having one menu appear as a section of another is
   * exactly as it sounds: the items from @a section become a direct part of
   * the menu that @a menu_item is added to.  See g_menu_item_new_section()
   * for more information about what it means for a menu item to be a
   * section.
   * 
   * @newin{2,32}
   * @param section A MenuModel, or <tt>0</tt>.
   */
  void set_section(const Glib::RefPtr<MenuModel>& section);
 
  //TODO: Documentation:
  void set_action_and_target(const Glib::ustring& action);

  
  /** Sets or unsets the "action" and "target" attributes of @a menu_item.
   * 
   * If @a action is <tt>0</tt> then both the "action" and "target" attributes
   * are unset (and @a target_value is ignored).
   * 
   * If @a action is non-<tt>0</tt> then the "action" attribute is set.  The
   * "target" attribute is then set to the value of @a target_value if it is
   * non-<tt>0</tt> or unset otherwise.
   * 
   * Normal menu items (ie: not submenu, section or other custom item
   * types) are expected to have the "action" attribute set to identify
   * the action that they are associated with.  The state type of the
   * action help to determine the disposition of the menu item.  See
   * Action and ActionGroup for an overview of actions.
   * 
   * In general, clicking on the menu item will result in activation of
   * the named action with the "target" attribute given as the parameter
   * to the action invocation.  If the "target" attribute is not set then
   * the action is invoked with no parameter.
   * 
   * If the action has no state then the menu item is usually drawn as a
   * plain menu item (ie: with no additional decoration).
   * 
   * If the action has a boolean state then the menu item is usually drawn
   * as a toggle menu item (ie: with a checkmark or equivalent
   * indication).  The item should be marked as 'toggled' or 'checked'
   * when the boolean state is <tt>true</tt>.
   * 
   * If the action has a string state then the menu item is usually drawn
   * as a radio menu item (ie: with a radio bullet or equivalent
   * indication).  The item should be marked as 'selected' when the string
   * state is equal to the value of the @a target property.
   * 
   * See g_menu_item_set_action_and_target() or
   * g_menu_item_set_detailed_action() for two equivalent calls that are
   * probably more convenient for most uses.
   * 
   * @newin{2,32}
   * @param action The name of the action for this item.
   * @param target_value A Variant to use as the action target.
   */
  void set_action_and_target(const Glib::ustring& action, const Glib::VariantBase& target_value);
  
  
  /** Sets the "action" and possibly the "target" attribute of @a menu_item.
   * 
   * If @a detailed_action contains a double colon ("::") then it is used as
   * a separator between an action name and a target string.  In this
   * case, this call is equivalent to calling
   * g_menu_item_set_action_and_target() with the part before the "::" and
   * with a string-type Variant containing the part following the "::".
   * 
   * If @a detailed_action doesn't contain "::" then the action is set to
   * the given string (verbatim) and the target value is unset.
   * 
   * See g_menu_item_set_action_and_target() or
   * g_menu_item_set_action_and_target_value() for more flexible (but
   * slightly less convenient) alternatives.
   * 
   * See also g_menu_item_set_action_and_target_value() for a description of
   * the semantics of the action and target attributes.
   * 
   * @newin{2,32}
   * @param detailed_action The "detailed" action string.
   */
  void set_detailed_action(const Glib::ustring& detailed_action);


public:

public:
  //C++ methods used to invoke GTK+ virtual functions:

protected:
  //GTK+ Virtual Functions (override these to change behaviour):

  //Default Signal Handlers::


};

} // namespace Gio


namespace Glib
{
  /** A Glib::wrap() method for this object.
   * 
   * @param object The C instance.
   * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
   * @result A C++ instance that wraps this C instance.
   *
   * @relates Gio::MenuItem
   */
  Glib::RefPtr<Gio::MenuItem> wrap(GMenuItem* object, bool take_copy = false);
}


#endif /* _GIOMM_MENUITEM_H */