diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index c80a0e7545..c2a4ca35ac 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2001-03-22 Havoc Pennington + + * gdk/tmpl/keys.sgml: docs on GdkKeymap + 2001-03-16 Havoc Pennington * gtk/gtk-docs.sgml: remove GtkData entity usage diff --git a/docs/reference/gdk/tmpl/keys.sgml b/docs/reference/gdk/tmpl/keys.sgml index 006d562a48..8dfab2a9ee 100644 --- a/docs/reference/gdk/tmpl/keys.sgml +++ b/docs/reference/gdk/tmpl/keys.sgml @@ -11,7 +11,8 @@ They appear in the keyval 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 <gdk/gdkkeysyms.h> -header file. +header file. <gdk/gdkkeysyms.h> is not included in <gtk/gtk.h>, +it must be included independently, because the file is quite large. 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(). + + +When it makes sense, key values can be converted to and from +Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval(). + + + +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 +level 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. + + + +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. + + + +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. + diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml index 420f3b311c..9903f1f0ca 100644 --- a/docs/reference/gtk/tmpl/gtk-unused.sgml +++ b/docs/reference/gtk/tmpl/gtk-unused.sgml @@ -445,6 +445,24 @@ The position of the cursor. + + +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. + + +You may not attach these to signals created with the +#GTK_RUN_NO_HOOKS flag. + + +@object: +@signal_id: +@n_params: +@params: +@data: +@Returns: + A set of bit flags used to specify the filter being set @@ -1087,6 +1105,20 @@ Internal function. @ruler: the gtkruler + + +Add an emission hook for a type of signal, for any object. + + +@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: + 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. + + + + + + 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. + + +Delete an emission hook. (see gtk_signal_add_emission_hook()) + + +@signal_id: the id of the signal type. +@hook_id: the id of the emission handler, returned by add_emission_hook(). +@i: +@h: + These set default functions to call when the user didn't diff --git a/docs/reference/gtk/tmpl/gtksignal.sgml b/docs/reference/gtk/tmpl/gtksignal.sgml index 11705206fd..1bb805c8ba 100644 --- a/docs/reference/gtk/tmpl/gtksignal.sgml +++ b/docs/reference/gtk/tmpl/gtksignal.sgml @@ -157,25 +157,6 @@ you might have to write a marshaller. @field: - - -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. - - -You may not attach these to signals created with the -#GTK_RUN_NO_HOOKS flag. - - -@object: -@signal_id: -@n_params: -@params: -@data: -@Returns: - - These configure the signal's emission. They control @@ -251,13 +232,6 @@ to the signal. @GTK_RUN_ACTION: @GTK_RUN_NO_HOOKS: - - - - - - - Create a new signal type. (This is usually done in the @@ -315,7 +289,7 @@ you don't want a return value. the callbacks. - + 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. +@Returns: the signal's identifying number, or 0 if no signal was found. + @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. - + Given the signal's identifier, find its name. @@ -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. -@signal_id: the signal's identifying number. @Returns: the signal name, or NULL if the signal number was invalid. + +@signal_id: the signal's identifying number. @@ -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. - + This function aborts a signal's current emission. @@ -421,11 +397,11 @@ It will print a warning if used on a signal which isn't being emitted. -@object: the object whose signal handlers you wish to stop. -@signal_id: the signal identifier, as returned by gtk_signal_lookup(). - @i: @s: + +@object: the object whose signal handlers you wish to stop. +@signal_id: the signal identifier, as returned by gtk_signal_lookup(). @@ -441,7 +417,7 @@ except it will lookup the signal id for you. @name: the name of the signal you wish to stop. - + 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) +@o: +@s: +@f: +@d: +@Returns: the connection id. + @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. - -@o: -@s: -@f: -@d: - + Attach a function pointer and user data to a signal so that this handler will be called after the other handlers. -@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. - @o: @s: @f: @d: +@Returns: the unique identifier for this attachment: the connection id. + +@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). - + 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); +@o: +@s: +@f: +@d: +@Returns: the connection id. + @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. - -@o: -@s: -@f: -@d: - + 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. -@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. - @o: @s: @f: @d: +@Returns: the connection id. + +@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. @@ -652,95 +628,98 @@ should signal the removal of this signal. @name: name of the signal. - + Destroy a user-defined handler connection. + @object: the object which the handler pertains to. @handler_id: the connection id. - + Destroy all connections for a particular object, with the given function-pointer and user-data. -@object: the object which emits the signal. -@func: the function pointer to search for. -@data: the user data to search for. - @o: @f: @d: + +@object: the object which emits the signal. +@func: the function pointer to search for. +@data: the user data to search for. - + Destroy all connections for a particular object, with the given user-data. -@object: the object which emits the signal. -@data: the user data to search for. - @o: @d: + +@object: the object which emits the signal. +@data: the user data to search for. - + Prevent an user-defined handler from being invoked. All other signal processing will go on as normal, but this particular handler will ignore it. + @object: the object which emits the signal to block. @handler_id: the connection id. - + 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.) -@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. - @o: @f: @d: + +@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. - + Prevent all user-defined handlers with a certain user data from being invoked. -@object: the object which emits the signal we want to block. -@data: the user data of the handlers to block. - @o: @d: + +@object: the object which emits the signal we want to block. +@data: the user data of the handlers to block. - + 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. + @object: the object which emits the signal we want to unblock. @handler_id: the emission handler identifier, as returned by gtk_signal_connect(), etc. - + 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. -@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. - @o: @f: @d: + +@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. - + Undo block(s), to all signals for a particular object with a particular user-data pointer -@object: the object which emits the signal we want to unblock. -@data: the user data to search for. - @o: @d: + +@object: the object which emits the signal we want to unblock. +@data: the user data to search for. - + Returns a connection id corresponding to a given signal id and object. @@ -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. +@i: +@s: +@b: +@Returns: the connection id, if a connection was found. 0 otherwise. + @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. - -@i: -@s: -@b: - + Returns a connection id corresponding to a given signal id, object, function pointer and user data. +@o: +@s: +@b: +@f: +@d: +@Returns: the connection id, if a handler was found. 0 otherwise. + @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. - -@o: -@s: -@b: -@f: -@d: - - - - -Add an emission hook for a type of signal, for any object. - - -@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: - - - - -Delete an emission hook. (see gtk_signal_add_emission_hook()) - - -@signal_id: the id of the signal type. -@hook_id: the id of the emission handler, returned by add_emission_hook(). - -@i: -@h: diff --git a/docs/reference/gtk/tmpl/gtktypeutils.sgml b/docs/reference/gtk/tmpl/gtktypeutils.sgml index 6295e2dfa1..16a7e543fe 100644 --- a/docs/reference/gtk/tmpl/gtktypeutils.sgml +++ b/docs/reference/gtk/tmpl/gtktypeutils.sgml @@ -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. - + -@type: a GtkType @Returns: a pointer to the name of a type, or NULL if it has none. + +@type: a GtkType - + Get the internal representation of a type given its name. -@name: the name of a gtk type @Returns: a GtkType + +@name: the name of a gtk type - + -@type: a GtkType @Returns: the GtkType of the parent + +@type: a GtkType @@ -608,15 +611,16 @@ has all the proper initializers called. @Returns: gpointer to a GtkTypeObject - + 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. +@Returns: + @type: GtkType @is_a_type: GtkType -@Returns: