AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

docs on GdkKeymap

Browse Source 
2001-03-22  Havoc Pennington  <hp@redhat.com>

	* gdk/tmpl/keys.sgml: docs on GdkKeymap
This commit is contained in:
Havoc Pennington 2001-03-22 22:41:05 +00:00 committed by Havoc Pennington
parent 23b98cc1ec
commit 18b5348b48
5 changed files with 200 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/reference/ChangeLog
View File

@ -1,3 +1,7 @@
2001-03-22 Havoc Pennington <hp@redhat.com>
* gdk/tmpl/keys.sgml: docs on GdkKeymap
2001-03-16 Havoc Pennington <hp@redhat.com>
* gtk/gtk-docs.sgml: remove GtkData entity usage

52
docs/reference/gdk/tmpl/keys.sgml
View File

@ -11,7 +11,8 @@ They appear in the <structfield>keyval</structfield> field of the
#GdkEventKey structure, which is passed to signal handlers for the
"key-press-event" and "key-release-event" signals.
The complete list of key values can be found in the &lt;gdk/gdkkeysyms.h&gt;
header file.
header file. &lt;gdk/gdkkeysyms.h&gt; is not included in &lt;gtk/gtk.h&gt;,
it must be included independently, because the file is quite large.
</para>
<para>
Key values can be converted into a string representation using
@ -22,6 +23,55 @@ is provided by gdk_keyval_from_name().
The case of key values can be determined using gdk_keyval_is_upper() and
gdk_keyval_is_lower(). Key values can be converted to upper or lower case
using gdk_keyval_to_upper() and gdk_keyval_to_lower().
</para>
<para>
When it makes sense, key values can be converted to and from
Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
</para>
<para>
One #GdkKeymap object exists for each user display. GTK 2 supports only one
display, so gdk_keymap_get_default() returns the singleton #GdkKeymap. A keymap
is a mapping from #GdkKeymapKey to key values. You can think of a #GdkKeymapKey
as a representation of a symbol printed on a physical keyboard key. That is, it
contains three pieces of information. First, it contains the hardware keycode;
this is an identifying number for a physical key. Second, it contains the
<firstterm>level</firstterm> of the key. The level indicates which symbol on the
key will be used, in a vertical direction. So on a standard US keyboard, the key
with the number "1" on it also has the exclamation point ("!") character on
it. The level indicates whether to use the "1" or the "!" symbol. The letter
keys are considered to have a lowercase letter at level 0, and an uppercase
letter at level 1, though only the uppercase letter is printed. Third, the
#GdkKeymapKey contains a group; groups are not used on standard US keyboards,
but are used in many other countries. On a keyboard with groups, there can be 3
or 4 symbols printed on a single key. The group indicates movement in a
horizontal direction. Usually groups are used for two different languages. In
group 0, a key might have two English characters, and in group 1 it might have
two Hebrew characters. The Hebrew characters will be printed on the key next to
the English characters.
</para>
<para>
In order to use a keymap to interpret a key event, it's necessary to first
convert the keyboard state into an effective group and level. This is done via a
set of rules that varies widely according to type of keyboard and user
configuration. The function gdk_keymap_translate_keyboard_state() accepts a
keyboard state -- consisting of hardware keycode pressed, active modifiers, and
active group -- applies the appropriate rules, and returns the group/level to be
used to index the keymap, along with the modifiers which did not affect the
group and level. i.e. it returns "unconsumed modifiers." The keyboard group may
differ from the effective group used for keymap lookups because some keys don't
have multiple groups - e.g. the Enter key is always in group 0 regardless of
keyboard state.
</para>
<para>
Note that gdk_keymap_translate_keyboard_state() also returns the keyval, i.e. it
goes ahead and performs the keymap lookup in addition to telling you which
effective group/level values were used for the lookup. #GdkEventKey already
contains this keyval, however, so you don't normally need to call
gdk_keymap_translate_keyboard_state() just to get the keyval.
</para>
<!-- ##### SECTION See_Also ##### -->

48
docs/reference/gtk/tmpl/gtk-unused.sgml
View File

@ -445,6 +445,24 @@ The position of the cursor.
</para>
<!-- ##### USER_FUNCTION GtkEmissionHook ##### -->
<para>
A simple function pointer to get invoked when the
signal is emitted. This allows you tie a hook to the signal type,
so that it will trap all emissions of that signal, from any object.
</para>
<para>
You may not attach these to signals created with the
#GTK_RUN_NO_HOOKS flag.
</para>
@object:
@signal_id:
@n_params:
@params:
@data:
@Returns:
<!-- ##### ENUM GtkFontFilterType ##### -->
<para>
A set of bit flags used to specify the filter being set
@ -1087,6 +1105,20 @@ Internal function.
@ruler: the gtkruler
<!-- ##### FUNCTION gtk_signal_add_emission_hook ##### -->
<para>
Add an emission hook for a type of signal, for any object.
</para>
@signal_id: the type of signal to hook for.
@hook_func: the function to invoke to handle the emission hook.
@data: the user data passed in to hook_func.
@Returns: the id (that you may pass as a parameter
to gtk_signal_remove_emission_hook()).
@i:
@h:
@d:
<!-- ##### FUNCTION gtk_signal_add_emission_hook_full ##### -->
<para>
Add an emission hook for a type of signal, for any object.
@ -1126,6 +1158,12 @@ This function is labeled private.
@object: the object whose signal handlers should be destroyed.
<!-- ##### FUNCTION gtk_signal_init ##### -->
<para>
</para>
<!-- ##### FUNCTION gtk_signal_n_emissions ##### -->
<para>
Find out the recursion depth of emissions for a particular type
@ -1167,6 +1205,16 @@ Obtain information about a signal.
which contains all the information, or NULL.
The pointer is allocated just for you: you must g_free() it.
<!-- ##### FUNCTION gtk_signal_remove_emission_hook ##### -->
<para>
Delete an emission hook. (see gtk_signal_add_emission_hook())
</para>
@signal_id: the id of the signal type.
@hook_id: the id of the emission handler, returned by add_emission_hook().
@i:
@h:
<!-- ##### FUNCTION gtk_signal_set_funcs ##### -->
<para>
These set default functions to call when the user didn't

219
docs/reference/gtk/tmpl/gtksignal.sgml
View File

@ -157,25 +157,6 @@ you might have to write a marshaller.
@field:
<!-- ##### USER_FUNCTION GtkEmissionHook ##### -->
<para>
A simple function pointer to get invoked when the
signal is emitted. This allows you tie a hook to the signal type,
so that it will trap all emissions of that signal, from any object.
</para>
<para>
You may not attach these to signals created with the
#GTK_RUN_NO_HOOKS flag.
</para>
@object:
@signal_id:
@n_params:
@params:
@data:
@Returns:
<!-- ##### ENUM GtkSignalRunType ##### -->
<para>
These configure the signal's emission. They control
@ -251,13 +232,6 @@ to the signal.
@GTK_RUN_ACTION:
@GTK_RUN_NO_HOOKS:
<!-- ##### FUNCTION gtk_signal_init ##### -->
<para>
</para>
<!-- ##### FUNCTION gtk_signal_new ##### -->
<para>
Create a new signal type. (This is usually done in the
@ -315,7 +289,7 @@ you don't want a return value.
the callbacks.
<!-- ##### FUNCTION gtk_signal_lookup ##### -->
<!-- ##### MACRO gtk_signal_lookup ##### -->
<para>
Given the name of the signal and the type of object it connects
to, get the signal's identifying integer. Emitting the signal
@ -325,12 +299,13 @@ by number is somewhat faster than using the name each time.
It also tries the ancestors of the given type.
</para>
@Returns: the signal's identifying number, or 0 if no signal was found.
<!-- # Unused Parameters # -->
@name: the signal's name, e.g. clicked.
@object_type: the type that the signal operates on, e.g. #GTK_TYPE_BUTTON.
@Returns: the signal's identifying number, or 0 if no signal was found.
<!-- ##### FUNCTION gtk_signal_name ##### -->
<!-- ##### MACRO gtk_signal_name ##### -->
<para>
Given the signal's identifier, find its name.
</para>
@ -338,8 +313,9 @@ Given the signal's identifier, find its name.
Two different signals may have the same name, if they have differing types.
</para>
@signal_id: the signal's identifying number.
@Returns: the signal name, or NULL if the signal number was invalid.
<!-- # Unused Parameters # -->
@signal_id: the signal's identifying number.
<!-- ##### FUNCTION gtk_signal_emit ##### -->
@ -407,7 +383,7 @@ an array of GtkArgs instead of using C's varargs mechanism.
followed by one which is a pointer to the return type.
<!-- ##### FUNCTION gtk_signal_emit_stop ##### -->
<!-- ##### MACRO gtk_signal_emit_stop ##### -->
<para>
This function aborts a signal's current emission.
</para>
@ -421,11 +397,11 @@ It will print a warning if used on a signal which
isn't being emitted.
</para>
@object: the object whose signal handlers you wish to stop.
@signal_id: the signal identifier, as returned by gtk_signal_lookup().
<!-- # Unused Parameters # -->
@i:
@s:
<!-- # Unused Parameters # -->
@object: the object whose signal handlers you wish to stop.
@signal_id: the signal identifier, as returned by gtk_signal_lookup().
<!-- ##### FUNCTION gtk_signal_emit_stop_by_name ##### -->
@ -441,7 +417,7 @@ except it will lookup the signal id for you.
@name: the name of the signal you wish to stop.
<!-- ##### FUNCTION gtk_signal_connect ##### -->
<!-- ##### MACRO gtk_signal_connect ##### -->
<para>
Attach a function pointer and user data to a signal for
a particular object.
@ -480,38 +456,38 @@ static void attach_print_signal(GtkButton* button, gint to_print)
</programlisting>
</informalexample>
@o:
@s:
@f:
@d:
@Returns: the connection id.
<!-- # Unused Parameters # -->
@object: the object associated with the signal, e.g. if a button
is getting pressed, this is that button.
@name: name of the signal.
@func: function pointer to attach to the signal.
@func_data: value to pass as to your function (through the marshaller).
@Returns: the connection id.
<!-- # Unused Parameters # -->
@o:
@s:
@f:
@d:
<!-- ##### FUNCTION gtk_signal_connect_after ##### -->
<!-- ##### MACRO gtk_signal_connect_after ##### -->
<para>
Attach a function pointer and user data to a signal
so that this handler will be called after the other handlers.
</para>
@object: the object associated with the signal.
@name: name of the signal.
@func: function pointer to attach to the signal.
@func_data: value to pass as to your function (through the marshaller).
@Returns: the unique identifier for this attachment: the connection id.
<!-- # Unused Parameters # -->
@o:
@s:
@f:
@d:
@Returns: the unique identifier for this attachment: the connection id.
<!-- # Unused Parameters # -->
@object: the object associated with the signal.
@name: name of the signal.
@func: function pointer to attach to the signal.
@func_data: value to pass as to your function (through the marshaller).
<!-- ##### FUNCTION gtk_signal_connect_object ##### -->
<!-- ##### MACRO gtk_signal_connect_object ##### -->
<para>
This function is for registering a callback that will
call another object's callback. That is,
@ -532,21 +508,21 @@ gtk_signal_connect_object(button, "clicked", gtk_widget_show, window);
</programlisting>
</informalexample>
@o:
@s:
@f:
@d:
@Returns: the connection id.
<!-- # Unused Parameters # -->
@object: the object which emits the signal.
@name: the name of the signal.
@func: the function to callback.
@slot_object: the object to pass as the first parameter to func.
(Though it pretends to take an object, you can
really pass any gpointer as the #slot_object .)
@Returns: the connection id.
<!-- # Unused Parameters # -->
@o:
@s:
@f:
@d:
<!-- ##### FUNCTION gtk_signal_connect_object_after ##### -->
<!-- ##### MACRO gtk_signal_connect_object_after ##### -->
<para>
Attach a signal hook to a signal, passing in an alternate
object as the first parameter, and guaranteeing
@ -554,16 +530,16 @@ that the default handler and all normal
handlers are called first.
</para>
@object: the object associated with the signal.
@name: name of the signal.
@func: function pointer to attach to the signal.
@slot_object: the object to pass as the first parameter to #func.
@Returns: the connection id.
<!-- # Unused Parameters # -->
@o:
@s:
@f:
@d:
@Returns: the connection id.
<!-- # Unused Parameters # -->
@object: the object associated with the signal.
@name: name of the signal.
@func: function pointer to attach to the signal.
@slot_object: the object to pass as the first parameter to #func.
<!-- ##### FUNCTION gtk_signal_connect_full ##### -->
@ -652,95 +628,98 @@ should signal the removal of this signal.
@name: name of the signal.
<!-- ##### FUNCTION gtk_signal_disconnect ##### -->
<!-- ##### MACRO gtk_signal_disconnect ##### -->
<para>
Destroy a user-defined handler connection.
</para>
<!-- # Unused Parameters # -->
@object: the object which the handler pertains to.
@handler_id: the connection id.
<!-- ##### FUNCTION gtk_signal_disconnect_by_func ##### -->
<!-- ##### MACRO gtk_signal_disconnect_by_func ##### -->
<para>
Destroy all connections for a particular object, with
the given function-pointer and user-data.
</para>
@object: the object which emits the signal.
@func: the function pointer to search for.
@data: the user data to search for.
<!-- # Unused Parameters # -->
@o:
@f:
@d:
<!-- # Unused Parameters # -->
@object: the object which emits the signal.
@func: the function pointer to search for.
@data: the user data to search for.
<!-- ##### FUNCTION gtk_signal_disconnect_by_data ##### -->
<!-- ##### MACRO gtk_signal_disconnect_by_data ##### -->
<para>
Destroy all connections for a particular object, with
the given user-data.
</para>
@object: the object which emits the signal.
@data: the user data to search for.
<!-- # Unused Parameters # -->
@o:
@d:
<!-- # Unused Parameters # -->
@object: the object which emits the signal.
@data: the user data to search for.
<!-- ##### FUNCTION gtk_signal_handler_block ##### -->
<!-- ##### MACRO gtk_signal_handler_block ##### -->
<para>
Prevent an user-defined handler from being invoked. All other
signal processing will go on as normal, but this particular
handler will ignore it.
</para>
<!-- # Unused Parameters # -->
@object: the object which emits the signal to block.
@handler_id: the connection id.
<!-- ##### FUNCTION gtk_signal_handler_block_by_func ##### -->
<!-- ##### MACRO gtk_signal_handler_block_by_func ##### -->
<para>
Prevent a user-defined handler from being invoked, by reference to
the user-defined handler's function pointer and user data. (It may result in
multiple hooks being blocked, if you've called connect multiple times.)
</para>
@object: the object which emits the signal to block.
@func: the function pointer of the handler to block.
@data: the user data of the handler to block.
<!-- # Unused Parameters # -->
@o:
@f:
@d:
<!-- # Unused Parameters # -->
@object: the object which emits the signal to block.
@func: the function pointer of the handler to block.
@data: the user data of the handler to block.
<!-- ##### FUNCTION gtk_signal_handler_block_by_data ##### -->
<!-- ##### MACRO gtk_signal_handler_block_by_data ##### -->
<para>
Prevent all user-defined handlers with a certain user data from being invoked.
</para>
@object: the object which emits the signal we want to block.
@data: the user data of the handlers to block.
<!-- # Unused Parameters # -->
@o:
@d:
<!-- # Unused Parameters # -->
@object: the object which emits the signal we want to block.
@data: the user data of the handlers to block.
<!-- ##### FUNCTION gtk_signal_handler_unblock ##### -->
<!-- ##### MACRO gtk_signal_handler_unblock ##### -->
<para>
Undo a block, by connection id. Note that undoing a block doesn't
necessarily make the hook callable, because if you block a
hook twice, you must unblock it twice.
</para>
<!-- # Unused Parameters # -->
@object: the object which emits the signal we want to unblock.
@handler_id: the emission handler identifier, as returned by
gtk_signal_connect(), etc.
<!-- ##### FUNCTION gtk_signal_handler_unblock_by_func ##### -->
<!-- ##### MACRO gtk_signal_handler_unblock_by_func ##### -->
<para>
Undo a block, by function pointer and data.
Note that undoing a block doesn't
@ -748,29 +727,29 @@ necessarily make the hook callable, because if you block a
hook twice, you must unblock it twice.
</para>
@object: the object which emits the signal we want to unblock.
@func: the function pointer to search for.
@data: the user data to search for.
<!-- # Unused Parameters # -->
@o:
@f:
@d:
<!-- # Unused Parameters # -->
@object: the object which emits the signal we want to unblock.
@func: the function pointer to search for.
@data: the user data to search for.
<!-- ##### FUNCTION gtk_signal_handler_unblock_by_data ##### -->
<!-- ##### MACRO gtk_signal_handler_unblock_by_data ##### -->
<para>
Undo block(s), to all signals for a particular object
with a particular user-data pointer
</para>
@object: the object which emits the signal we want to unblock.
@data: the user data to search for.
<!-- # Unused Parameters # -->
@o:
@d:
<!-- # Unused Parameters # -->
@object: the object which emits the signal we want to unblock.
@data: the user data to search for.
<!-- ##### FUNCTION gtk_signal_handler_pending ##### -->
<!-- ##### MACRO gtk_signal_handler_pending ##### -->
<para>
Returns a connection id corresponding to a given signal id and object.
</para>
@ -781,64 +760,36 @@ may opt to not emit the signal if no one is attached anyway,
thus saving the cost of building the arguments.
</para>
@i:
@s:
@b:
@Returns: the connection id, if a connection was found. 0 otherwise.
<!-- # Unused Parameters # -->
@object: the object to search for the desired user-defined handler.
@signal_id: the number of the signal to search for.
@may_be_blocked: whether it is acceptable to return a blocked
handler.
@Returns: the connection id, if a connection was found. 0 otherwise.
<!-- # Unused Parameters # -->
@i:
@s:
@b:
<!-- ##### FUNCTION gtk_signal_handler_pending_by_func ##### -->
<!-- ##### MACRO gtk_signal_handler_pending_by_func ##### -->
<para>
Returns a connection id corresponding to a given signal id, object, function
pointer and user data.
</para>
@o:
@s:
@b:
@f:
@d:
@Returns: the connection id, if a handler was found. 0 otherwise.
<!-- # Unused Parameters # -->
@object: the object to search for the desired handler.
@signal_id: the number of the signal to search for.
@may_be_blocked: whether it is acceptable to return a blocked
handler.
@func: the function pointer to search for.
@data: the user data to search for.
@Returns: the connection id, if a handler was found. 0 otherwise.
<!-- # Unused Parameters # -->
@o:
@s:
@b:
@f:
@d:
<!-- ##### FUNCTION gtk_signal_add_emission_hook ##### -->
<para>
Add an emission hook for a type of signal, for any object.
</para>
@signal_id: the type of signal to hook for.
@hook_func: the function to invoke to handle the emission hook.
@data: the user data passed in to hook_func.
@Returns: the id (that you may pass as a parameter
to gtk_signal_remove_emission_hook()).
<!-- # Unused Parameters # -->
@i:
@h:
@d:
<!-- ##### FUNCTION gtk_signal_remove_emission_hook ##### -->
<para>
Delete an emission hook. (see gtk_signal_add_emission_hook())
</para>
@signal_id: the id of the signal type.
@hook_id: the id of the emission handler, returned by add_emission_hook().
<!-- # Unused Parameters # -->
@i:
@h:
<!-- ##### MACRO gtk_signal_default_marshaller ##### -->

20
docs/reference/gtk/tmpl/gtktypeutils.sgml
View File

@ -560,30 +560,33 @@ Create a new, unique type.
@type_info: must not be null, and @type_info->type_name must also not be null.
<!-- ##### FUNCTION gtk_type_name ##### -->
<!-- ##### MACRO gtk_type_name ##### -->
<para>
</para>
@type: a GtkType
@Returns: a pointer to the name of a type, or NULL if it has none.
<!-- # Unused Parameters # -->
@type: a GtkType
<!-- ##### FUNCTION gtk_type_from_name ##### -->
<!-- ##### MACRO gtk_type_from_name ##### -->
<para>
Get the internal representation of a type given its name.
</para>
@name: the name of a gtk type
@Returns: a GtkType
<!-- # Unused Parameters # -->
@name: the name of a gtk type
<!-- ##### FUNCTION gtk_type_parent ##### -->
<!-- ##### MACRO gtk_type_parent ##### -->
<para>
</para>
@type: a GtkType
@Returns: the GtkType of the parent
<!-- # Unused Parameters # -->
@type: a GtkType
<!-- ##### FUNCTION gtk_type_class ##### -->
@ -608,15 +611,16 @@ has all the proper initializers called.
@Returns: gpointer to a GtkTypeObject
<!-- ##### FUNCTION gtk_type_is_a ##### -->
<!-- ##### MACRO gtk_type_is_a ##### -->
<para>
Look in the type hierarchy to see if @type has @is_a_type among its
ancestors. Do so with a simple lookup, not a loop.
</para>
@Returns:
<!-- # Unused Parameters # -->
@type: GtkType
@is_a_type: GtkType
@Returns:
<!-- ##### FUNCTION gtk_type_enum_get_values ##### -->