glib/gio/gaction.h

101 lines
4.6 KiB
C
Raw Normal View History

2010-08-18 07:45:15 +02:00
/*
* Copyright © 2010 Codethink Limited
*
* This program 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 of the licence 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., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*
* Authors: Ryan Lortie <desrt@desrt.ca>
*/
#ifndef __G_ACTION_H__
#define __G_ACTION_H__
2010-08-18 07:45:15 +02:00
#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
#error "Only <gio/gio.h> can be included directly."
#endif
#include <gio/giotypes.h>
G_BEGIN_DECLS
#define G_TYPE_ACTION (g_action_get_type ())
#define G_ACTION(inst) (G_TYPE_CHECK_INSTANCE_CAST ((inst), \
G_TYPE_ACTION, GAction))
#define G_IS_ACTION(inst) (G_TYPE_CHECK_INSTANCE_TYPE ((inst), G_TYPE_ACTION))
#define G_ACTION_GET_IFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), \
G_TYPE_ACTION, GActionInterface))
2010-08-18 07:45:15 +02:00
typedef struct _GActionInterface GActionInterface;
2010-08-18 07:45:15 +02:00
struct _GActionInterface
2010-08-18 07:45:15 +02:00
{
GTypeInterface g_iface;
2010-08-18 07:45:15 +02:00
/* virtual functions */
const gchar * (* get_name) (GAction *action);
const GVariantType * (* get_parameter_type) (GAction *action);
const GVariantType * (* get_state_type) (GAction *action);
2010-08-18 07:45:15 +02:00
GVariant * (* get_state_hint) (GAction *action);
gboolean (* get_enabled) (GAction *action);
GVariant * (* get_state) (GAction *action);
2010-08-18 07:45:15 +02:00
Make 4 incompatible changes to the GAction API This commit represents an API break to GAction in the following ways: - the 'set_state' entry in the GActionInterface vtable has been renamed to 'change_state'. The number and order of vtable items has not otherwise changed. - g_action_set_state() has been renamed to g_action_change_state() to match the updated vtable entry. - the "state" property of the GAction interface has been changed to read-only to reflect the fact that g_action_set_state() no longer exists. - GSimpleActionClass has been hidden. GSimpleAction can no longer be subclassed. >> Rationale g_action_set_state() has never been a true setter in the sense that calling it will update the value of the "state" property. It has always been closer to "request 'state' to be changed to this value" with semantics defined by the implementor of the interface. This is why the equivalent method in GActionGroup had its name changed from 'set' to 'change'. This change makes the two interfaces more consistent and removes any implication about the effect that calling set_state() should have on the 'state' property. >> Impact This incompatible API break was undertaken only because I strongly suspect that it will go entirely unnoticed. If the break actually affects anybody, then we will accommodate them (possibly going as far as to revert this commit entirely). The virtual table change only impacts implementors of GAction. I strongly suspect that this is nobody (except for GSimpleAction). The hiding of GSimpleActionClass only impacts impacts subclasses of GSimpleAction. I strongly suspect that none of these exist. The changing of the property to be read-only only affects people who were trying to change the state by using GObject properties. I strongly suspect that this is nobody at all. The removal of the g_action_set_state() call is the most dangerous, but I still suspect that it will impact nobody outside of GLib. If anybody is impacted by this change then, at their request, I will reintroduce the API as a deprecated alias for g_action_change_state().
2011-06-29 11:11:59 +02:00
void (* change_state) (GAction *action,
GVariant *value);
2010-08-18 07:45:15 +02:00
void (* activate) (GAction *action,
GVariant *parameter);
};
GLIB_AVAILABLE_IN_2_30
2010-08-18 07:45:15 +02:00
GType g_action_get_type (void) G_GNUC_CONST;
GLIB_AVAILABLE_IN_ALL
2010-08-18 07:45:15 +02:00
const gchar * g_action_get_name (GAction *action);
GLIB_AVAILABLE_IN_ALL
2010-08-18 07:45:15 +02:00
const GVariantType * g_action_get_parameter_type (GAction *action);
GLIB_AVAILABLE_IN_ALL
2010-08-18 07:45:15 +02:00
const GVariantType * g_action_get_state_type (GAction *action);
GLIB_AVAILABLE_IN_ALL
2010-08-18 07:45:15 +02:00
GVariant * g_action_get_state_hint (GAction *action);
GLIB_AVAILABLE_IN_ALL
2010-08-18 07:45:15 +02:00
gboolean g_action_get_enabled (GAction *action);
GLIB_AVAILABLE_IN_ALL
2010-08-18 07:45:15 +02:00
GVariant * g_action_get_state (GAction *action);
GLIB_AVAILABLE_IN_ALL
Make 4 incompatible changes to the GAction API This commit represents an API break to GAction in the following ways: - the 'set_state' entry in the GActionInterface vtable has been renamed to 'change_state'. The number and order of vtable items has not otherwise changed. - g_action_set_state() has been renamed to g_action_change_state() to match the updated vtable entry. - the "state" property of the GAction interface has been changed to read-only to reflect the fact that g_action_set_state() no longer exists. - GSimpleActionClass has been hidden. GSimpleAction can no longer be subclassed. >> Rationale g_action_set_state() has never been a true setter in the sense that calling it will update the value of the "state" property. It has always been closer to "request 'state' to be changed to this value" with semantics defined by the implementor of the interface. This is why the equivalent method in GActionGroup had its name changed from 'set' to 'change'. This change makes the two interfaces more consistent and removes any implication about the effect that calling set_state() should have on the 'state' property. >> Impact This incompatible API break was undertaken only because I strongly suspect that it will go entirely unnoticed. If the break actually affects anybody, then we will accommodate them (possibly going as far as to revert this commit entirely). The virtual table change only impacts implementors of GAction. I strongly suspect that this is nobody (except for GSimpleAction). The hiding of GSimpleActionClass only impacts impacts subclasses of GSimpleAction. I strongly suspect that none of these exist. The changing of the property to be read-only only affects people who were trying to change the state by using GObject properties. I strongly suspect that this is nobody at all. The removal of the g_action_set_state() call is the most dangerous, but I still suspect that it will impact nobody outside of GLib. If anybody is impacted by this change then, at their request, I will reintroduce the API as a deprecated alias for g_action_change_state().
2011-06-29 11:11:59 +02:00
void g_action_change_state (GAction *action,
GVariant *value);
GLIB_AVAILABLE_IN_ALL
2010-08-18 07:45:15 +02:00
void g_action_activate (GAction *action,
GVariant *parameter);
GLIB_AVAILABLE_IN_2_28
gboolean g_action_name_is_valid (const gchar *action_name);
GLIB_AVAILABLE_IN_2_38
gboolean g_action_parse_detailed_name (const gchar *detailed_name,
gchar **action_name,
GVariant **target_value,
GError **error);
GLIB_AVAILABLE_IN_2_38
gchar * g_action_print_detailed_name (const gchar *action_name,
GVariant *parameter);
2010-08-18 07:45:15 +02:00
G_END_DECLS
#endif /* __G_ACTION_H__ */