/*
 * Copyright (C) Birb Developers
 *
 * Birb is the legal property of its developers, whose names are too numerous
 * to list here. Please refer to the AUTHORS file distributed with this source
 * distribution
 *
 * 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, see <https://www.gnu.org/licenses/>.
 */

#if !defined(BIRB_GLOBAL_HEADER_INSIDE) && !defined(BIRB_COMPILATION)
# error "only <birb.h> may be included directly"
#endif

#ifndef BIRB_ACTION_MENU_H
#define BIRB_ACTION_MENU_H

#include <gio/gio.h>

#include "birbversion.h"

G_BEGIN_DECLS

/**
 * BirbActionMenuForeachActionGroupFunc:
 * @prefix: The prefix for the group.
 * @group: The [iface@Gio.ActionGroup].
 * @user_data: User data.
 *
 * A function pointer for iterating through the [iface@Gio.ActionGroup]s in
 * a [class@ActionMenu].
 *
 * Since: 0.1
 */
BIRB_AVAILABLE_TYPE_IN_0_1
typedef void (*BirbActionMenuForeachActionGroupFunc)(const char *prefix, GActionGroup *group, gpointer user_data);

#define BIRB_TYPE_ACTION_MENU (birb_action_menu_get_type())

/**
 * BirbActionMenu:
 *
 * A BirbActionMenu was created to allow interested parties to add items to a
 * menu by listening to a signal.
 *
 * While the primary user interface driving this is GTK, it should be usable
 * for other interfaces.
 *
 * It allows handlers to add menu items and sections by exposing the menu via
 * [method@ActionMenu.get_menu]. Those handlers can then also add an action
 * group by passing a `prefix` and the [iface@Gio.ActionGroup] to
 * [method@ActionMenu.add_action_group].
 *
 * User interfaces can then call [method@ActionMenu.foreach_action_group] to
 * handle the action groups.
 *
 * Since: 0.1
 */
BIRB_AVAILABLE_IN_0_1
G_DECLARE_FINAL_TYPE(BirbActionMenu, birb_action_menu,
                     BIRB, ACTION_MENU, GObject)

/**
 * birb_action_menu_new:
 *
 * Creates a new action menu.
 *
 * Returns: (transfer full): The new instance.
 *
 * Since: 0.1
 */
BIRB_AVAILABLE_IN_0_1
BirbActionMenu *birb_action_menu_new(void);

/**
 * birb_action_menu_get_menu:
 * @menu: The instance.
 *
 * Gets the [class@Gio.Menu] from @menu so that you may add items and sections
 * to it.
 *
 * Returns: (transfer none): The menu.
 *
 * Since: 0.1
 */
BIRB_AVAILABLE_IN_0_1
GMenu *birb_action_menu_get_menu(BirbActionMenu *menu);

/**
 * birb_action_menu_add_action_group:
 * @menu: The instance.
 * @prefix: The prefix for the group.
 * @group: (transfer none): The [iface@Gio.ActionGroup].
 *
 * Adds @group to @menu with @prefix. If @prefix already exists, %FALSE will
 * be returned and @group will not be added to @menu.
 *
 * Returns: %TRUE if the prefix did not exist, otherwise %FALSE.
 *
 * Since: 0.1
 */
BIRB_AVAILABLE_IN_0_1
gboolean birb_action_menu_add_action_group(BirbActionMenu *menu, const char *prefix, GActionGroup *group);

/**
 * birb_action_menu_foreach_action_group:
 * @menu: The instance.
 * @func: (scope call): The function to call on each action group.
 * @user_data: Data to pass to @func.
 *
 * Calls @func with the prefix and action group from each item in @menu as well
 * as @user_data.
 *
 * Since: 0.1
 */
BIRB_AVAILABLE_IN_0_1
void birb_action_menu_foreach_action_group(BirbActionMenu *menu, BirbActionMenuForeachActionGroupFunc func, gpointer user_data);

G_END_DECLS

#endif /* BIRB_ACTION_MENU_H */
