Commit 002d2b73 authored by Havoc Pennington's avatar Havoc Pennington Committed by Havoc Pennington

move some of the accel group functions into a Private subsection

2001-09-08  Havoc Pennington  <hp@pobox.com>

	* gtk/gtk-sections.txt: move some of the accel group functions
	into a Private subsection

2001-09-08  Havoc Pennington  <hp@pobox.com>

	* gtk/gtkaccelgroup.c: add docs to functions that I can imagine
	people might want to use
parent 9ddcb3e0
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkaccelgroup.c: add docs to functions that I can imagine
people might want to use
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkalignment.c (gtk_alignment_class_init): default
......
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkaccelgroup.c: add docs to functions that I can imagine
people might want to use
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkalignment.c (gtk_alignment_class_init): default
......
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkaccelgroup.c: add docs to functions that I can imagine
people might want to use
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkalignment.c (gtk_alignment_class_init): default
......
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkaccelgroup.c: add docs to functions that I can imagine
people might want to use
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkalignment.c (gtk_alignment_class_init): default
......
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkaccelgroup.c: add docs to functions that I can imagine
people might want to use
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkalignment.c (gtk_alignment_class_init): default
......
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkaccelgroup.c: add docs to functions that I can imagine
people might want to use
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkalignment.c (gtk_alignment_class_init): default
......
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkaccelgroup.c: add docs to functions that I can imagine
people might want to use
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtkalignment.c (gtk_alignment_class_init): default
......
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/gtk-sections.txt: move some of the accel group functions
into a Private subsection
2001-09-08 Havoc Pennington <hp@pobox.com>
* gtk/tmpl/gtklayout.sgml: docs
......
......@@ -3554,6 +3554,10 @@ gtk_accel_group_ref
gtk_accel_group_unref
gtk_accel_group_activate
gtk_accel_groups_activate
gtk_accel_group_attach
gtk_accel_group_detach
gtk_accel_group_add
gtk_accel_group_remove
gtk_accel_group_lock
gtk_accel_group_unlock
gtk_accelerator_valid
......@@ -3561,13 +3565,10 @@ gtk_accelerator_parse
gtk_accelerator_name
gtk_accelerator_set_default_mod_mask
gtk_accelerator_get_default_mod_mask
gtk_accel_group_attach
gtk_accel_group_detach
<SUBSECTION Private>
gtk_accel_group_get_entry
gtk_accel_group_lock_entry
gtk_accel_group_unlock_entry
gtk_accel_group_add
gtk_accel_group_remove
gtk_accel_group_handle_add
gtk_accel_group_handle_remove
gtk_accel_group_create_add
......
......@@ -225,12 +225,6 @@ has the focus.
@clist: The #GtkCList widget to check.
<!-- ##### MACRO GTK_HAVE_CONTAINER_FOCUS_ADJUSTMENTS ##### -->
<para>
</para>
<!-- ##### MACRO GTK_ICON_SIZE_BUTTON ##### -->
<para>
......@@ -1102,6 +1096,92 @@ If the window shrinks automatically when widgets within it shrink.
</para>
<!-- ##### FUNCTION gtk_accel_group_create_add ##### -->
<para>
</para>
@class_type:
@signal_flags:
@handler_offset:
@Returns:
<!-- ##### FUNCTION gtk_accel_group_create_remove ##### -->
<para>
</para>
@class_type:
@signal_flags:
@handler_offset:
@Returns:
<!-- ##### FUNCTION gtk_accel_group_entries_from_object ##### -->
<para>
</para>
@object:
@Returns:
<!-- ##### FUNCTION gtk_accel_group_get_entry ##### -->
<para>
</para>
@accel_group:
@accel_key:
@accel_mods:
@Returns:
<!-- ##### FUNCTION gtk_accel_group_handle_add ##### -->
<para>
</para>
@object:
@accel_signal_id:
@accel_group:
@accel_key:
@accel_mods:
@accel_flags:
<!-- ##### FUNCTION gtk_accel_group_handle_remove ##### -->
<para>
</para>
@object:
@accel_group:
@accel_key:
@accel_mods:
<!-- ##### FUNCTION gtk_accel_group_lock_entry ##### -->
<para>
</para>
@accel_group:
@accel_key:
@accel_mods:
<!-- ##### FUNCTION gtk_accel_group_unlock_entry ##### -->
<para>
</para>
@accel_group:
@accel_key:
@accel_mods:
<!-- ##### FUNCTION gtk_accel_groups_from_object ##### -->
<para>
</para>
@object:
@Returns:
<!-- ##### FUNCTION gtk_arg_copy ##### -->
<para>
It will either copy data into an existing argument or allocate a new argument
......
......@@ -7,11 +7,11 @@ global keyboard accelerators (for an entire #GtkWindow)
<!-- ##### SECTION Long_Description ##### -->
<para>
A #GtkAccelGroup represents a group of keyboard accelerators, attached
to a toplevel #GtkWindow (with gtk_window_add_accel_group()). Usually
you won't need to create a #GtkAccelGroup directly; instead, when
using #GtkItemFactory, GTK+ automatically sets up the accelerators for
your menus.
A #GtkAccelGroup represents a group of keyboard accelerators,
typically attached to a toplevel #GtkWindow (with
gtk_window_add_accel_group()). Usually you won't need to create a
#GtkAccelGroup directly; instead, when using #GtkItemFactory, GTK+
automatically sets up the accelerators for your menus.
</para>
<para>
......@@ -91,68 +91,6 @@ On opaque data type representing a group of accelerators.
@Returns:
<!-- ##### FUNCTION gtk_accel_group_lock ##### -->
<para>
</para>
@accel_group:
<!-- ##### FUNCTION gtk_accel_group_unlock ##### -->
<para>
</para>
@accel_group:
<!-- ##### FUNCTION gtk_accelerator_valid ##### -->
<para>
</para>
@keyval:
@modifiers:
@Returns:
<!-- ##### FUNCTION gtk_accelerator_parse ##### -->
<para>
</para>
@accelerator:
@accelerator_key:
@accelerator_mods:
<!-- ##### FUNCTION gtk_accelerator_name ##### -->
<para>
</para>
@accelerator_key:
@accelerator_mods:
@Returns:
<!-- ##### FUNCTION gtk_accelerator_set_default_mod_mask ##### -->
<para>
</para>
@default_mod_mask:
<!-- ##### FUNCTION gtk_accelerator_get_default_mod_mask ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION gtk_accel_group_attach ##### -->
<para>
......@@ -171,37 +109,6 @@ On opaque data type representing a group of accelerators.
@object:
<!-- ##### FUNCTION gtk_accel_group_get_entry ##### -->
<para>
</para>
@accel_group:
@accel_key:
@accel_mods:
@Returns:
<!-- ##### FUNCTION gtk_accel_group_lock_entry ##### -->
<para>
</para>
@accel_group:
@accel_key:
@accel_mods:
<!-- ##### FUNCTION gtk_accel_group_unlock_entry ##### -->
<para>
</para>
@accel_group:
@accel_key:
@accel_mods:
<!-- ##### FUNCTION gtk_accel_group_add ##### -->
<para>
......@@ -226,67 +133,65 @@ On opaque data type representing a group of accelerators.
@object:
<!-- ##### FUNCTION gtk_accel_group_handle_add ##### -->
<!-- ##### FUNCTION gtk_accel_group_lock ##### -->
<para>
</para>
@object:
@accel_signal_id:
@accel_group:
@accel_key:
@accel_mods:
@accel_flags:
<!-- ##### FUNCTION gtk_accel_group_handle_remove ##### -->
<!-- ##### FUNCTION gtk_accel_group_unlock ##### -->
<para>
</para>
@object:
@accel_group:
@accel_key:
@accel_mods:
<!-- ##### FUNCTION gtk_accel_group_create_add ##### -->
<!-- ##### FUNCTION gtk_accelerator_valid ##### -->
<para>
</para>
@class_type:
@signal_flags:
@handler_offset:
@keyval:
@modifiers:
@Returns:
<!-- ##### FUNCTION gtk_accel_group_create_remove ##### -->
<!-- ##### FUNCTION gtk_accelerator_parse ##### -->
<para>
</para>
@class_type:
@signal_flags:
@handler_offset:
@Returns:
@accelerator:
@accelerator_key:
@accelerator_mods:
<!-- ##### FUNCTION gtk_accel_groups_from_object ##### -->
<!-- ##### FUNCTION gtk_accelerator_name ##### -->
<para>
</para>
@object:
@accelerator_key:
@accelerator_mods:
@Returns:
<!-- ##### FUNCTION gtk_accel_group_entries_from_object ##### -->
<!-- ##### FUNCTION gtk_accelerator_set_default_mod_mask ##### -->
<para>
</para>
@default_mod_mask:
<!-- ##### FUNCTION gtk_accelerator_get_default_mod_mask ##### -->
<para>
</para>
@object:
@Returns:
......@@ -38,6 +38,13 @@ GtkContainer
@pspec:
<!-- ##### MACRO GTK_HAVE_CONTAINER_FOCUS_ADJUSTMENTS ##### -->
<para>
</para>
<!-- ##### MACRO gtk_container_border_width ##### -->
<para>
......
......@@ -165,6 +165,13 @@ gtk_accel_group_init (GtkAccelGroup *accel_group)
accel_group->attach_objects = NULL;
}
/**
* gtk_accel_group_new:
*
* Creates a new #GtkAccelGroup.
*
* Return value: a new #GtkAccelGroup
**/
GtkAccelGroup*
gtk_accel_group_new (void)
{
......@@ -175,6 +182,20 @@ gtk_accel_group_new (void)
return accel_group;
}
/**
* gtk_accel_group_get_default:
*
* Gets the global default accelerator group; this is a fallback
* used for all objects when gtk_accel_groups_activate() is called
* on them. As such it's probably not appropriate for most uses.
* (Accelerators are normally specific to a document window or the
* like, rather than global to an application.)
*
* The returned value does not have its reference count incremented,
* and should not be unreferenced.
*
* Return value: the default accelerator group
**/
GtkAccelGroup*
gtk_accel_group_get_default (void)
{
......@@ -184,6 +205,15 @@ gtk_accel_group_get_default (void)
return default_accel_group;
}
/**
* gtk_accel_group_ref:
* @accel_group: a #GtkAccelGroup
*
* This is simply equivalent to g_object_ref (G_OBJECT (@accel_group)),
* and exists for historical reasons only.
*
* Return value: @accel_group
**/
GtkAccelGroup*
gtk_accel_group_ref (GtkAccelGroup *accel_group)
{
......@@ -192,6 +222,14 @@ gtk_accel_group_ref (GtkAccelGroup *accel_group)
return (GtkAccelGroup *)g_object_ref(accel_group);
}
/**
* gtk_accel_group_unref:
* @accel_group: a #GtkAccelGroup
*
* This is simply equivalent to g_object_unref (G_OBJECT (@accel_group)),
* and exists for historical reasons only.
*
**/
void
gtk_accel_group_unref (GtkAccelGroup *accel_group)
{
......@@ -217,6 +255,20 @@ gtk_accel_group_object_destroy (GSList *free_list,
g_slist_free (free_list);
}
/**
* gtk_accel_group_attach:
* @accel_group: a #GtkAccelGroup
* @object: object to attach accelerators to
*
* Associate @accel_group with @object, such that calling
* gtk_accel_groups_activate() on @object will activate accelerators
* in @accel_group.
*
* After calling this function, you still own a reference to both
* @accel_group and @object; gtk_accel_group_attach() will not
* "adopt" a reference to either one.
*
**/
void
gtk_accel_group_attach (GtkAccelGroup *accel_group,
GObject *object)
......@@ -241,6 +293,14 @@ gtk_accel_group_attach (GtkAccelGroup *accel_group,
slist);
}
/**
* gtk_accel_group_detach:
* @accel_group: a #GtkAccelGroup
* @object: a #GObject
*
* Reverses the effects of gtk_accel_group_attach().
*
**/
void
gtk_accel_group_detach (GtkAccelGroup *accel_group,
GObject *object)
......@@ -265,6 +325,19 @@ gtk_accel_group_detach (GtkAccelGroup *accel_group,
slist);
}
/**
* gtk_accel_group_lock:
* @accel_group: a #GtkAccelGroup
*
* Prevents the addition of new accelerators to @accel_group.
* Primarily used to avoid the "dynamic accelerator editing" feature
* of #GtkMenu.
*
* If called more than once, @accel_group remains locked until
* gtk_accel_group_unlock() has been called an equivalent number
* of times.
*
**/
void
gtk_accel_group_lock (GtkAccelGroup *accel_group)
{
......@@ -273,6 +346,15 @@ gtk_accel_group_lock (GtkAccelGroup *accel_group)
accel_group->lock_count += 1;
}
/**
* gtk_accel_group_unlock:
* @accel_group: a #GtkAccelGroup
*
* Allows the addition of new accelerators to @accel_group.
* Primarily used to enable the "dynamic accelerator editing" feature
* of #GtkMenu.
*
**/
void
gtk_accel_group_unlock (GtkAccelGroup *accel_group)
{
......@@ -296,6 +378,21 @@ gtk_accel_group_lookup (GtkAccelGroup *accel_group,
return g_hash_table_lookup (accel_entry_hash_table, &key_entry);
}
/**
* gtk_accel_group_activate:
* @accel_group: a #GtkAccelGroup
* @accel_key: keyval from a key event
* @accel_mods: modifier mask from a key event
*
* Checks whether a key event matches an accelerator in @accel_group;
* if so, activates the accelerator, and returns %TRUE. Returns
* %FALSE if no match.
*
* gtk_accel_groups_activate() should normally be used instead of
* this function.
*
* Return value: %TRUE if an accelerator was activated
**/
gboolean
gtk_accel_group_activate (GtkAccelGroup *accel_group,
guint accel_key,
......@@ -315,6 +412,22 @@ gtk_accel_group_activate (GtkAccelGroup *accel_group,
return FALSE;
}
/**
* gtk_accel_groups_activate:
* @object: a #GObject
* @accel_key: accelerator keyval from a key event
* @accel_mods: keyboard state mask from a key event
*
* Finds the first accelerator in any #GtkAccelGroup attached
* to @object that matches @accel_key and @accel_mods, and
* activates that accelerator. If no accelerators are found
* in groups attached to @object, this function also tries
* the default #GtkAccelGroup (see gtk_accel_group_get_default()).
* If an accelerator is activated, returns %TRUE, otherwise
* %FALSE.
*
* Return value: %TRUE if an accelerator was activated
**/
gboolean
gtk_accel_groups_activate (GObject *object,
guint accel_key,
......@@ -373,6 +486,28 @@ gtk_accel_group_get_entry (GtkAccelGroup *accel_group,
return gtk_accel_group_lookup (accel_group, accel_key, accel_mods);
}
/**
* gtk_accel_group_add:
* @accel_group: a #GtkAccelGroup
* @accel_key: accelerator keyval
* @accel_mods: accelerator modifiers
* @accel_flags: accelerator flags
* @object: object that @accel_signal will be emitted on
* @accel_signal: name of a #G_SIGNAL_ACTION signal to emit
*
* Adds an accelerator to @accel_group. When the accelerator is
* activated, the @accel_signal signal will be emitted on @object.
*
* So for example, to click a button when Ctrl+a is pressed, you would
* write: gtk_accel_group_add (accel_group, GDK_a, GDK_CONTROL_MASK,
* 0, G_OBJECT (button), "clicked").
*
* @accel_flags is not particularly useful, always pass 0 for
* normal applications.
*
* @object must be an object that specifically supports accelerators,
* such as #GtkWidget.
**/
void
gtk_accel_group_add (GtkAccelGroup *accel_group,
guint accel_key,
......@@ -578,6 +713,18 @@ gtk_accel_group_handle_add (GObject *object,
}
}
/**
* gtk_accel_group_remove:
* @accel_group: a #GtkAccelGroup
* @accel_key: accelerator keyval
* @accel_mods: accelerator modifiers
* @object: object the accelerator activates
*
* Removes an accelerator. The @accel_key, @accel_mods, and @object
* arguments are the same ones used to add the accelerator
* with gtk_accel_group_add().
*
**/
void
gtk_accel_group_remove (GtkAccelGroup *accel_group,
guint accel_key,
......@@ -730,6 +877,18 @@ gtk_accel_group_entries_from_object (GObject *object)
return g_object_get_qdata (object, accel_entries_key_id);
}
/**
* gtk_accelerator_valid:
* @keyval: a GDK keyval
* @modifiers: modifier mask
*
* Determines whether a given keyval and modifier mask constitute
* a valid keyboard accelerator. For example, the GDK_a keyval
* plus GDK_CONTROL_MASK is valid - this is a "Ctrl+a" accelerator.
* But you can't use the NumLock key as an accelerator.
*
* Return value: %TRUE if the accelerator is valid
**/
gboolean