1 <!-- ##### SECTION ./tmpl/gtkdebug.sgml:Title ##### -->
5 <!-- ##### SECTION ./tmpl/gtkenums.sgml.sgml:Title ##### -->
9 <!-- ##### SECTION ./tmpl/gtkimcontextsimple.sgml:Title ##### -->
13 <!-- ##### SECTION ./tmpl/gtkmarshal.sgml:Long_Description ##### -->
15 <title>What are Signal Marshallers?</title>
17 Marshals are functions which all have the same prototype:
18 they take a #GtkObject, a #GtkSignalFunc, a #gpointer,
19 and an array of argument values.
20 The functions are names gtk_marshall_RETURNTYPE__PARAMTYPE1_PARAMTYPE2....
23 They then call a native function: the GtkObject is the first
24 parameter passed in. The arguments are passed in the native
25 calling convention: chars, shorts, ints, longs may be packed
26 on the stack, or tucked in registers: it doesn't matter
27 because the same calling convention will be generated
28 inside the gtkmarshal code as is expected where you define
32 So the function named:
34 gtk_marshal_BOOL__POINTER_INT_INT_UINT(GtkObject*, GtkSignalFunc, gpointer, GtkArg*);
36 will call the #GtkSignalFunc assuming it was a function with signature:
38 gboolean sigfunc(gpointer,gint,gint,guint);
43 <title>Writing Custom Marshals</title>
45 Marshals are primarily used as arguments to gtk_signal_new().
46 Sometimes, you may find that a marshaller you need isn't available
47 in the standard list. Then you have to write your own.
50 If you wish to define a signal with a new type of argument list.
51 Suppose you want 2 pointers and 2 integers.
54 typedef int (*GtkSignal_INT__POINTER_POINTER_INT_INT)(
55 gpointer, gpointer, gint, gint
58 void marshal_INT__POINTER_POINTER_INT_INT(GtkObject* object,
63 GtkSignal_NONE__POINTER_POINTER_INT_INT rfunc;
65 return_val = GTK_RETLOC_INT(args[4]);
66 rfunc = (GtkSignal_INT__POINTER_POINTER_INT_INT)func;
67 *return_val = (*rfunc)(object,
68 GTK_VALUE_POINTER(args[0]),
69 GTK_VALUE_POINTER(args[1]),
70 GTK_VALUE_INT(args[2]),
71 GTK_VALUE_INT(args[3]),
79 <!-- ##### SECTION ./tmpl/gtkmarshal.sgml:See_Also ##### -->
84 <term>#GtkSignal</term>
85 <listitem><para>The signal handling functions (of which marshallers are
86 really an implementation detail).</para></listitem>
93 <!-- ##### SECTION ./tmpl/gtkmarshal.sgml:Short_Description ##### -->
94 Functions to adapt C structures to native calling convention.
97 <!-- ##### SECTION ./tmpl/gtkmarshal.sgml:Title ##### -->
101 <!-- ##### SECTION ./tmpl/gtkprivate.sgml:Title ##### -->
105 <!-- ##### MACRO GTK_CLIST_CHILD_HAS_FOCUS ##### -->
107 A macro to check whether a child widget of the CList
111 @clist: The #GtkCList widget to check.
113 <!-- ##### MACRO GTK_ICON_SIZE_BUTTON ##### -->
119 <!-- ##### MACRO GTK_ICON_SIZE_DIALOG ##### -->
125 <!-- ##### MACRO GTK_ICON_SIZE_LARGE_TOOLBAR ##### -->
131 <!-- ##### MACRO GTK_ICON_SIZE_MENU ##### -->
137 <!-- ##### MACRO GTK_ICON_SIZE_SMALL_TOOLBAR ##### -->
143 <!-- ##### MACRO GTK_OBJECT_CONSTRUCTED ##### -->
145 Test whether a GtkObject's arguments have been prepared.
148 @obj: the object to examine.
150 <!-- ##### MACRO GTK_OBJECT_NSIGNALS ##### -->
152 Get the number of signals defined by this object.
155 @obj: the object to query.
157 <!-- ##### MACRO GTK_OBJECT_SIGNALS ##### -->
159 Get the array of signals defined for this object.
162 @obj: the object to fetch the signals from.
164 <!-- ##### MACRO GTK_TREE_SELECTION ##### -->
166 A macro that returns a GList that contains the selection of the root tree of @obj.
169 @obj: A pointer to the #GtkTree. @obj will accept any pointer, but it the pointer does not point to a #GtkTree, the results are undefined.
171 <!-- ##### MACRO GTK_TYPE_FLAT_FIRST ##### -->
173 The first "flat" (no struct) enumerated type value.
177 <!-- ##### MACRO GTK_TYPE_FLAT_LAST ##### -->
179 The last "flat" (no struct) enumerated type value.
183 <!-- ##### MACRO GTK_TYPE_IDENTIFIER ##### -->
185 Hide the name of gtk_identifier_get_type
189 <!-- ##### MACRO GTK_TYPE_MAKE ##### -->
191 Combine a fundemantal type and a sequence number to create a gtk type.
197 <!-- ##### MACRO GTK_TYPE_NUM_BUILTINS ##### -->
203 <!-- ##### MACRO GTK_TYPE_SEQNO ##### -->
205 Convert a gtk type into its sequence number
210 <!-- ##### MACRO GTK_TYPE_STRUCTURED_FIRST ##### -->
212 The first structured enumerated type value.
216 <!-- ##### MACRO GTK_TYPE_STRUCTURED_LAST ##### -->
218 The last structured enumerated type value.
222 <!-- ##### MACRO GTK_TYPE_TREE_COLUMN ##### -->
228 <!-- ##### MACRO GTK_VALUE_ARGS ##### -->
230 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_ARGS
235 <!-- ##### MACRO GTK_VALUE_CALLBACK ##### -->
237 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_CALLBACK
242 <!-- ##### MACRO GTK_VALUE_C_CALLBACK ##### -->
244 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_CALLBACK
249 <!-- ##### MACRO GTK_VALUE_FOREIGN ##### -->
251 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_FOREIGN
256 <!-- ##### STRUCT GtkData ##### -->
258 The #GtkData-struct struct contains no public fields.
262 <!-- ##### SIGNAL GtkData::disconnect ##### -->
264 Emitted to notify any views on the #GtkData object to disconnect from it,
265 possibly because the #GtkData object is about to be destroyed.
268 @data: the object which received the signal.
270 <!-- ##### SIGNAL GtkEditable::activate ##### -->
272 Indicates that the user has activated the widget
273 in some fashion. Generally, this will be done
274 with a keystroke. (The default binding for this
275 action is Return for #GtkEntry and
276 Control-Return for #GtkText.)
279 @editable: the object which received the signal.
281 <!-- ##### SIGNAL GtkEditable::changed ##### -->
283 Indicates that the user has changed the contents
287 @editable: the object which received the signal.
289 <!-- ##### SIGNAL GtkEditable::copy-clipboard ##### -->
291 An action signal. Causes the characters in the current selection to
292 be copied to the clipboard.
295 @editable: the object which received the signal.
297 <!-- ##### SIGNAL GtkEditable::cut-clipboard ##### -->
299 An action signal. Causes the characters in the current
300 selection to be copied to the clipboard and then deleted from
304 @editable: the object which received the signal.
306 <!-- ##### SIGNAL GtkEditable::delete-text ##### -->
308 This signal is emitted when text is deleted from
309 the widget by the user. The default handler for
310 this signal will normally be responsible for inserting
311 the text, so by connecting to this signal and then
312 stopping the signal with gtk_signal_emit_stop(), it
313 is possible to modify the inserted text, or prevent
314 it from being inserted entirely. The @start_pos
315 and @end_pos parameters are interpreted as for
316 gtk_editable_delete_text()
319 @editable: the object which received the signal.
320 @start_pos: the starting position.
321 @end_pos: the end position.
323 <!-- ##### SIGNAL GtkEditable::insert-text ##### -->
325 This signal is emitted when text is inserted into
326 the widget by the user. The default handler for
327 this signal will normally be responsible for inserting
328 the text, so by connecting to this signal and then
329 stopping the signal with gtk_signal_emit_stop(), it
330 is possible to modify the inserted text, or prevent
331 it from being inserted entirely.
334 @editable: the object which received the signal.
335 @new_text: the new text to insert.
336 @new_text_length: the length of the new text.
337 @position: the position at which to insert the new text.
338 this is an in-out paramter. After the signal
339 emission is finished, it should point after
340 the newly inserted text.
342 <!-- ##### SIGNAL GtkEditable::kill-char ##### -->
344 An action signal. Delete a single character.
347 @editable: the object which received the signal.
348 @direction: the direction in which to delete. Positive
349 indicates forward deletion, negative, backwards deletion.
351 <!-- ##### SIGNAL GtkEditable::kill-line ##### -->
353 An action signal. Delete a single line.
356 @editable: the object which received the signal.
357 @direction: the direction in which to delete. Positive
358 indicates forward deletion, negative, backwards deletion.
360 <!-- ##### SIGNAL GtkEditable::kill-word ##### -->
362 An action signal. Delete a single word.
365 @editable: the object which received the signal.
366 @direction: the direction in which to delete. Positive
367 indicates forward deletion, negative, backwards deletion.
369 <!-- ##### SIGNAL GtkEditable::move-cursor ##### -->
371 An action signal. Move the cursor position.
374 @editable: the object which received the signal.
375 @x: horizontal distance to move the cursor.
376 @y: vertical distance to move the cursor.
378 <!-- ##### SIGNAL GtkEditable::move-page ##### -->
380 An action signal. Move the cursor by pages.
383 @editable: the object which received the signal.
384 @x: Number of pages to move the cursor horizontally.
385 @y: Number of pages to move the cursor vertically.
387 <!-- ##### SIGNAL GtkEditable::move-to-column ##### -->
389 An action signal. Move the cursor to the given column.
392 @editable: the object which received the signal.
393 @column: the column to move to. (A negative value indicates
396 <!-- ##### SIGNAL GtkEditable::move-to-row ##### -->
398 An action signal. Move the cursor to the given row.
401 @editable: the object which received the signal.
402 @row: the row to move to. (A negative value indicates
405 <!-- ##### SIGNAL GtkEditable::move-word ##### -->
407 An action signal. Move the cursor by words.
410 @editable: the object which received the signal.
411 @num_words: The number of words to move the
412 cursor. (Can be negative).
414 <!-- ##### SIGNAL GtkEditable::paste-clipboard ##### -->
416 An action signal. Causes the contents of the clipboard to
417 be pasted into the editable widget at the current cursor
421 @editable: the object which received the signal.
423 <!-- ##### SIGNAL GtkEditable::set-editable ##### -->
425 Determines if the user can edit the text in the editable
426 widget or not. This is meant to be overriden by
427 child classes and should not generally useful to
431 @editable: the object which received the signal.
432 @is_editable: %TRUE if the user is allowed to edit the text
435 <!-- ##### ARG GtkEditable:editable ##### -->
437 A boolean indicating whether the widget is editable by
442 <!-- ##### ARG GtkEditable:text-position ##### -->
444 The position of the cursor.
448 <!-- ##### USER_FUNCTION GtkEmissionHook ##### -->
450 A simple function pointer to get invoked when the
451 signal is emitted. This allows you tie a hook to the signal type,
452 so that it will trap all emissions of that signal, from any object.
455 You may not attach these to signals created with the
456 #GTK_RUN_NO_HOOKS flag.
466 <!-- ##### ENUM GtkFontFilterType ##### -->
468 A set of bit flags used to specify the filter being set
469 when calling gtk_font_selection_dialog_set_filter() or
470 gtk_font_selection_set_filter().
473 @GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user.
474 @GTK_FONT_FILTER_USER: the user filter, which can be changed from within the
475 'Filter' page of the #GtkFontSelection widget.
477 <!-- ##### ENUM GtkFontType ##### -->
479 A set of bit flags used to specify the type of fonts shown
480 when calling gtk_font_selection_dialog_set_filter() or
481 gtk_font_selection_set_filter().
484 @GTK_FONT_BITMAP: bitmap fonts.
485 @GTK_FONT_SCALABLE: scalable fonts.
486 @GTK_FONT_SCALABLE_BITMAP: scaled bitmap fonts.
487 @GTK_FONT_ALL: a bitwise combination of all of the above.
489 <!-- ##### STRUCT GtkIMContextSimple ##### -->
498 @tentative_match_len:
500 <!-- ##### ARG GtkLabel:accel-keyval ##### -->
506 <!-- ##### ARG GtkObject:object-signal ##### -->
508 Setting this with a GtkType of GTK_TYPE_SIGNAL connects
509 the signal to the object, so that the user data and objects
510 and swapped when the signal handler is invoked.
513 This is useful for handlers that are primarily notifying
514 other objects and could just invoke an already existing function
515 if the parameters were swapped.
516 See gtk_signal_connect_object() for more details.
520 <!-- ##### ARG GtkObject:object-signal-after ##### -->
522 Setting this with a GtkType of GTK_TYPE_SIGNAL connects
523 the signal to the object, so that the user data and objects
524 and swapped when the signal handler is invoked,
525 and so that the handler is invoked after all others.
528 See gtk_signal_connect_object_after() for more details.
532 <!-- ##### ARG GtkObject:signal ##### -->
534 Setting this with a GtkType of GTK_TYPE_SIGNAL connects
535 the signal to the object.
539 <!-- ##### ARG GtkObject:signal-after ##### -->
541 Setting this with a GtkType of GTK_TYPE_SIGNAL connects
542 the signal to the object, so that the signal is always run
543 after other user handlers and the default handler.
547 <!-- ##### ENUM GtkPrivateFlags ##### -->
552 @PRIVATE_GTK_USER_STYLE:
553 @PRIVATE_GTK_RESIZE_PENDING:
554 @PRIVATE_GTK_RESIZE_NEEDED:
555 @PRIVATE_GTK_LEAVE_PENDING:
556 @PRIVATE_GTK_HAS_SHAPE_MASK:
557 @PRIVATE_GTK_IN_REPARENT:
558 @PRIVATE_GTK_DIRECTION_SET:
559 @PRIVATE_GTK_DIRECTION_LTR:
561 <!-- ##### USER_FUNCTION GtkSignalDestroy ##### -->
563 A function which you can use to clean up when the
564 signal handler is destroyed.
567 For example, if your handler requires a few variables
568 that you made into a struct and allocated (using g_new()
569 or something), then you will probably want to free
570 it as soon as the hook is destroyed. This will
571 allow you to do that. (For this in particular
572 it is convenient to pass g_free() as a #GtkSignalDestroy
576 @data: The user data associated with the hook that is being
579 <!-- ##### USER_FUNCTION GtkSignalMarshal ##### -->
581 This is currently a hack left in for a scheme wrapper library.
588 @object: The object which emits the signal.
589 @data: The user data associated with the hook.
590 @nparams: The number of parameters to the function.
591 @args: The actual values of the arguments.
592 @arg_types: The types of the arguments.
593 @return_type: The type of the return value from the function
594 or #GTK_TYPE_NONE for no return value.
596 <!-- ##### STRUCT GtkSignalQuery ##### -->
598 This structure contains all the information about a particular
599 signal: its name, the type it affects, the signature of the handlers,
600 and its unique identifying integer.
612 <!-- ##### ARG GtkSpinButton:shadow-type ##### -->
614 the type of border that surrounds the arrows of a spin button.
618 <!-- ##### STRUCT GtkStatusbarMsg ##### -->
620 Holds the data for a statusbar message. <structfield>text</structfield> holds the actual text string. <structfield>context_id</structfield> is the context that this message is associated with, and <structfield>message_id</structfield> is this particular message's identifier. However, these fields should not be modified directly.
627 <!-- ##### ARG GtkTextTag:justify ##### -->
629 A #GtkJustification for the text. This is only used when the tag is
630 applied to the first character in a paragraph.
634 <!-- ##### ARG GtkTextTag:left-wrapped-line-margin ##### -->
636 Pixel width of the left margin of the text for lines after the first
637 line in a wrapped paragraph.
641 <!-- ##### ARG GtkTextTag:left-wrapped-line-margin-set ##### -->
647 <!-- ##### ARG GtkTextTag:offset ##### -->
649 Pixels to offset the text horizontally or vertically, useful to
650 produce superscript and subscript.
654 <!-- ##### ARG GtkTextView:justify ##### -->
660 <!-- ##### ARG GtkTextView:wrap-mode ##### -->
666 <!-- ##### SIGNAL GtkWidget::debug-msg ##### -->
671 @widget: the object which received the signal.
674 <!-- ##### SIGNAL GtkWidget::draw ##### -->
679 @widget: the object which received the signal.
682 <!-- ##### SIGNAL GtkWidget::draw-default ##### -->
687 @widget: the object which received the signal.
689 <!-- ##### SIGNAL GtkWidget::draw-focus ##### -->
694 @widget: the object which received the signal.
696 <!-- ##### FUNCTION gtk_button_box_child_requisition ##### -->
698 This is an internally used function and should never be called from an
\r
707 <!-- ##### FUNCTION gtk_button_box_get_child_ipadding_default ##### -->
709 The internal padding of a button is the amount of space between the outside
\r
710 of the button and the widget it contains. This function gets the default
\r
711 amount of horizontal and vertical padding, placing the results in @ipad_x
\r
712 and @ipad_y, respectively.
\r
715 @ipad_x: the default horizontal internal button padding.
716 @ipad_y: the default vertical internal button padding.
718 <!-- ##### FUNCTION gtk_button_box_get_child_size_default ##### -->
720 Retrieves the default minimum width and height for all button boxes, and
\r
721 places the values in @min_width and @min_height, respectively.
\r
724 @min_width: the default minimum width of a child widget.
725 @min_height: the default minimum height of a child widget.
727 <!-- ##### FUNCTION gtk_button_box_set_child_ipadding_default ##### -->
729 Sets the default number of pixels that pad each button in every button box.
\r
732 @ipad_x: new default horizontal padding.
733 @ipad_y: new default vertical padding.
735 <!-- ##### FUNCTION gtk_button_box_set_child_size_default ##### -->
737 Sets the default size of child buttons.
\r
740 @min_width: minimum default width for child buttons.
741 @min_height: minimum default height for child buttons.
743 <!-- ##### FUNCTION gtk_button_new_accel ##### -->
752 <!-- ##### FUNCTION gtk_button_new_stock ##### -->
761 <!-- ##### FUNCTION gtk_clist_construct ##### -->
763 Initializes a previously allocated #GtkCList widget for use. This should not
764 normally be used to create a #GtkCList widget. Use gtk_clist_new() instead.
767 @clist: A pointer to an uninitialized #GtkCList widget.
768 @columns: The number of columns the #GtkCList should have.
769 @titles: An array of strings that should be used as the titles i
770 of the columns. There should be enough strings in the array for
771 the number of columns specified.
773 <!-- ##### FUNCTION gtk_color_selection_set_opacity ##### -->
775 Controls whether opacity can be set with the #GtkColorSelection.
776 If this functionality is enabled, the necessary additional widgets
777 are added to the #GtkColorSelection and the opacity value can be
778 retrieved via the fourth value in the color array returned by
779 the gtk_color_selection_get_color() function.
782 @colorsel: a #GtkColorSelection.
783 @use_opacity: a boolean indicating whether the opacity selection
786 <!-- ##### FUNCTION gtk_ctree_construct ##### -->
788 This function is not usually used by users.
796 <!-- ##### FUNCTION gtk_editable_changed ##### -->
798 Causes the "changed" signal to be emitted.
801 @editable: a #GtkEditable widget.
803 <!-- ##### FUNCTION gtk_editable_claim_selection ##### -->
805 Claim or disclaim ownership of the PRIMARY X selection.
808 @editable: a #GtkEditable widget.
809 @claim: if %TRUE, claim the selection, otherwise, disclaim it.
810 @time: the timestamp for claiming the selection.
812 <!-- ##### FUNCTION gtk_font_selection_dialog_set_filter ##### -->
814 Sets one of the two font filters, to limit the fonts shown.
817 @fsd: a #GtkFontSelectionDialog.
818 @filter_type: which of the two font filters to set, either
819 #GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter
820 can be changed by the user, but the base filter is permanent.
821 @font_type: the types of font to be shown. This is a bitwise combination of
822 #GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP,
823 or #GTK_FONT_ALL to show all three font types.
824 @foundries: a NULL-terminated array of strings containing foundry names which
825 will be shown, or NULL to show all foundries.
826 @weights: a NULL-terminated array of strings containing weight names which
827 will be shown, or NULL to show all weights.
828 @slants: a NULL-terminated array of strings containing slant names which
829 will be shown, or NULL to show all slants.
830 @setwidths: a NULL-terminated array of strings containing setwidth names which
831 will be shown, or NULL to show all setwidths.
832 @spacings: a NULL-terminated array of strings containing spacings which
833 will be shown, or NULL to show all spacings.
834 @charsets: a NULL-terminated array of strings containing charset names which
835 will be shown, or NULL to show all charsets.
837 <!-- ##### FUNCTION gtk_font_selection_set_filter ##### -->
839 Sets one of the two font filters, to limit the fonts shown.
842 @fontsel: a #GtkFontSelection.
843 @filter_type: which of the two font filters to set, either
844 #GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter
845 can be changed by the user, but the base filter is permanent.
846 @font_type: the types of font to be shown. This is a bitwise combination of
847 #GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP,
848 or #GTK_FONT_ALL to show all three font types.
849 @foundries: a NULL-terminated array of strings containing foundry names which
850 will be shown, or NULL to show all foundries.
851 @weights: a NULL-terminated array of strings containing weight names which
852 will be shown, or NULL to show all weights.
853 @slants: a NULL-terminated array of strings containing slant names which
854 will be shown, or NULL to show all slants.
855 @setwidths: a NULL-terminated array of strings containing setwidth names which
856 will be shown, or NULL to show all setwidths.
857 @spacings: a NULL-terminated array of strings containing spacings which
858 will be shown, or NULL to show all spacings.
859 @charsets: a NULL-terminated array of strings containing charset names which
860 will be shown, or NULL to show all charsets.
862 <!-- ##### FUNCTION gtk_identifier_get_type ##### -->
864 Get the type of GtkIdentifier.
867 @Returns: GtkType -- the enumerated type of something.
869 <!-- ##### FUNCTION gtk_label_set_markup_with_accel ##### -->
878 <!-- ##### FUNCTION gtk_menu_ensure_uline_accel_group ##### -->
886 <!-- ##### FUNCTION gtk_menu_get_uline_accel_group ##### -->
894 <!-- ##### FUNCTION gtk_object_arg_get ##### -->
896 Private function to get an argument and argument info from an object.
899 @object: the object whose argument should be retrieved.
900 @arg: the argument, for the name on input, the rest is filled on output.
901 @info: a #GtkArgInfo structure to optionally fill in.
903 <!-- ##### FUNCTION gtk_object_arg_get_info ##### -->
905 Query information about an argument type.
908 @object_type: type of object to query about.
909 @arg_name: name of the argument.
910 @info_p: pointer to be filled in with a pointer to the GtkArgInfo.
911 @Returns: an error message, or NULL on success.
912 It is the caller's responsibility to call g_free() in the event of error.
914 <!-- ##### FUNCTION gtk_object_arg_set ##### -->
916 Private function to set an argument and argument info to an object.
919 @object: the object whose argument should be set.
921 @info: infomation about this type of argument in general.
923 <!-- ##### FUNCTION gtk_object_args_collect ##### -->
925 Private: Gets an array of #GtkArgs from a va_list C structure.
928 @object_type: the type of object to collect arguments for.
929 @arg_list_p: pointer to be filled in with a list of parsed arguments.
930 @info_list_p: optional pointer for a returned list #GtkArgInfos.
931 @first_arg_name: name of first argument.
932 @var_args: value of first argument, followed by more key/value pairs,
934 @Returns: an error message, or NULL on success.
935 It is the caller's responsibility to call g_free() in the event of error.
937 <!-- ##### FUNCTION gtk_object_class_add_signals ##### -->
939 Add an array of signals to a #GtkObjectClass.
940 Usually this is called when registering a new type of object.
943 @klass: the object class to append signals to.
944 @signals: the signals to append.
945 @nsignals: the number of signals being appended.
947 <!-- ##### FUNCTION gtk_object_class_user_signal_new ##### -->
949 Define a signal-handler for a new signal on an already defined
953 See the signal documentation for more general information.
956 @klass: the object class to define the signal for.
957 @name: the name of the signal.
958 @signal_flags: the default emission behavior for the signal.
959 See gtk_signal_new().
960 @marshaller: a function that will take an array of GtkArgs
961 and invoke the appropriate handler with the normal calling
963 @return_val: specify the return-value type for the signal
964 (or GTK_TYPE_NONE for no return-value).
965 @nparams: specify the number of parameters the signal
966 receives from the caller of gtk_signal_emit().
967 @Varargs: list of nparams #GtkTypes to pass to the signal handlers.
968 @Returns: the signal id. (See #GtkSignals)
970 <!-- ##### FUNCTION gtk_object_class_user_signal_newv ##### -->
972 Define a signal-handler for a new signal on an already defined
976 @klass: the object class to define the signal for.
977 @name: the name of the signal.
978 @signal_flags: the default emission behavior for the signal.
979 See gtk_signal_new().
980 @marshaller: takes a GtkObject, a #GtkSignalFunc, and an array
981 of arguments, and invokes the function using the appropriate
982 calling conventions. Usually just select a function
984 @return_val: specify the return-value type for the signal (possibly
986 @nparams: specify the number of parameters the signal
987 receives from the caller of gtk_signal_emit().
988 @params: array of #GtkTypes the signal handlers for this signal
989 should have in their prototype (of length nparams).
990 @Returns: the signal id. (See #GtkSignals)
992 <!-- ##### FUNCTION gtk_object_constructed ##### -->
994 Mark an allocated object as constructed.
995 This is used for situations
996 that require precise control of the construction process.
999 This is done when gtk_object_default_construct() is inadequate.
1000 In #GtkCList the need arises because #GtkCList does construction work that
1001 must happen <emphasis>after</emphasis> its derivers. This work
1002 cannot be done in an initializer function, so an alternate
1003 constructor is mandatory. It calls gtk_object_constructed() to
1004 indicate it has done its job, so that no other constructor will
1008 Normally this function is just automatically run from
1009 gtk_object_default_construct().
1012 @object: object which has been constructed. This is usually
1013 done automatically by gtk_object_new() and gtk_object_newv().
1015 <!-- ##### FUNCTION gtk_object_default_construct ##### -->
1017 This function is called to construct arguments that haven't been initialized
1018 but have the #GTK_ARG_CONSTRUCT flag set.
1021 All number arguments are set to 0. All pointers and strings
1025 Normally invoked by gtk_object_new() automatically; gtk_type_new() can
1026 be used to bypass it.
1029 @object: the object to initialize.
1031 <!-- ##### FUNCTION gtk_object_getv ##### -->
1033 Gets an array of argument values from an object.
1036 @object: the object to get arguments from.
1037 @n_args: the number of arguments to query.
1038 @args: the arguments to fill in.
1040 <!-- ##### FUNCTION gtk_object_newv ##### -->
1042 Construct an object with an array of arguments.
1045 @object_type: the type of the object to create.
1046 @n_args: the number of arguments to set.
1047 @args: an array of n_args arguments (which are name and value pairs).
1048 @Returns: the new GtkObject.
1050 <!-- ##### FUNCTION gtk_object_query_args ##### -->
1052 Get all the arguments that may be used for a given type.
1055 In Java, this type of mechanism is called
1056 <wordasword>introspection</wordasword>. It is used by applications
1057 like Glade, that have to determine what can be done to an object
1061 @class_type: the GtkType of the ObjectClass
1062 (returned from GTK_OBJECT_CLASS(class)->type for example).
1063 @arg_flags: if non-NULL, obtains the #GtkArgFlags that apply to
1064 each argument. You must g_free() this if you request it.
1065 @n_args: the number of arguments is returned in this field.
1066 @Returns: an array of arguments, that you must deallocate with g_free().
1068 <!-- ##### FUNCTION gtk_object_setv ##### -->
1070 Set an array of arguments.
1073 @object: the object whose arguments should be set.
1074 @n_args: the number of arguments to set.
1075 @args: the desired values, as an array of #GtkArgs (which contain
1076 the names, types, and values of the arguments).
1078 <!-- ##### FUNCTION gtk_paned_compute_position ##### -->
1080 Internal function used by #GtkHPaned and #GtkVPaned
1088 <!-- ##### FUNCTION gtk_rc_init ##### -->
1094 <!-- ##### FUNCTION gtk_ruler_draw_pos ##### -->
1099 @ruler: the gtkruler
1101 <!-- ##### FUNCTION gtk_ruler_draw_ticks ##### -->
1106 @ruler: the gtkruler
1108 <!-- ##### FUNCTION gtk_signal_add_emission_hook ##### -->
1110 Add an emission hook for a type of signal, for any object.
1113 @signal_id: the type of signal to hook for.
1114 @hook_func: the function to invoke to handle the emission hook.
1115 @data: the user data passed in to hook_func.
1116 @Returns: the id (that you may pass as a parameter
1117 to gtk_signal_remove_emission_hook()).
1122 <!-- ##### FUNCTION gtk_signal_add_emission_hook_full ##### -->
1124 Add an emission hook for a type of signal, for any object.
1125 (with control of what happens when the hook is
1129 @signal_id: the type of signal add the hook for.
1130 @hook_func: the function to invoke to handle the hook.
1131 @data: the user data passed in to hook_func.
1132 @destroy: a function to invoke when the hook is destroyed,
1133 to clean up any allocation done just for this
1135 @Returns: the id (that you may pass as a parameter
1136 to gtk_signal_remove_emission_hook()).
1138 <!-- ##### FUNCTION gtk_signal_handler_pending_by_id ##### -->
1140 Returns whether a connection id is valid (and optionally not blocked).
1143 @object: the object to search for the desired handler.
1144 @handler_id: the connection id.
1145 @may_be_blocked: whether it is acceptable to return a blocked
1147 @Returns: TRUE if the signal exists and wasn't blocked,
1148 unless #may_be_blocked was specified. FALSE otherwise.
1150 <!-- ##### FUNCTION gtk_signal_handlers_destroy ##### -->
1152 Destroy all the signal handlers connected to an object.
1153 This is done automatically when the object is destroyed.
1156 This function is labeled private.
1159 @object: the object whose signal handlers should be destroyed.
1161 <!-- ##### FUNCTION gtk_signal_init ##### -->
1167 <!-- ##### FUNCTION gtk_signal_n_emissions ##### -->
1169 Find out the recursion depth of emissions for a particular type
1170 of signal and object. (So it will
1171 always return 0 or 1 if #GTK_RUN_NO_RECURSE is specified)
1172 This is a way to avoid recursion: you can see if
1173 you are currently running in that signal handler and emit it only
1176 <para>Another way to look at it is that this number increases
1177 by one when #gtk_signal_emit(), et al, are called,
1178 and decreases by one when #gtk_signal_emit() returns.
1181 @object: the object with the signal handler.
1182 @signal_id: the signal id.
1183 @Returns: the recursion depth of emissions of this signal for this
1186 <!-- ##### FUNCTION gtk_signal_n_emissions_by_name ##### -->
1188 Find out the recursion depth of emissions for a particular type
1189 of signal and object. Just like gtk_signal_n_emissions()
1190 except it will lookup the signal id for you.
1193 @object: the object with the signal handler.
1194 @name: the signal name.
1195 @Returns: the recursion depth of emissions of this signal for this
1198 <!-- ##### FUNCTION gtk_signal_query ##### -->
1200 Obtain information about a signal.
1203 @signal_id: the signal type identifier.
1204 @Returns: a pointer to a GtkSignalQuery structure
1205 which contains all the information, or NULL.
1206 The pointer is allocated just for you: you must g_free() it.
1208 <!-- ##### FUNCTION gtk_signal_remove_emission_hook ##### -->
1210 Delete an emission hook. (see gtk_signal_add_emission_hook())
1213 @signal_id: the id of the signal type.
1214 @hook_id: the id of the emission handler, returned by add_emission_hook().
1218 <!-- ##### FUNCTION gtk_signal_set_funcs ##### -->
1220 These set default functions to call when the user didn't
1221 supply a function when connecting. (These are rarely
1222 used, and probably only for language bindings)
1225 By default, there are no such functions.
1228 @marshal_func: the function to invoke on every handlers for which there
1229 isn't a function pointer. May be NULL.
1230 @destroy_func: the function to invoke when each hook is destroyed.
1233 <!-- ##### FUNCTION gtk_spin_button_set_shadow_type ##### -->
1235 Creates a border around the arrows of a #GtkSpinButton. The type of border is determined by @shadow_type.
1238 @spin_button: a #GtkSpinButton
1239 @shadow_type: the new border type.
1241 <!-- ##### FUNCTION gtk_trace_referencing ##### -->
1243 Private: print debugging information while doing a gtk_object_ref() or
1244 a gtk_object_unref().
1247 @object: object to reference or unreference.
1248 @func: name of caller's function to print (used within macros).
1250 @line: line number (used within macros).
1251 @do_ref: whether to reference or unreference.
1253 <!-- ##### FUNCTION gtk_tree_model_ref_iter ##### -->
1261 <!-- ##### FUNCTION gtk_tree_model_unref_iter ##### -->
1269 <!-- ##### FUNCTION gtk_type_check_class_cast ##### -->
1271 Given a GtkTypeClass pointer @klass, and a GtkType @cast_type, make
1272 sure that it's okay to cast something of that @klass into a @cast_type.
1275 @klass: GtkTypeClass*
1277 @Returns: Always return @klass.
1279 <!-- ##### FUNCTION gtk_type_check_object_cast ##### -->
1281 Given a pointer to a GtkTypeObject @type_object, and a GtkType @cast_type,
1282 make sure that it's okay to cast @type_object into a @cast_type.
1285 @type_object: GtkTypeObject*
1287 @Returns: the same GtkTypeObject* as @type_object
1289 <!-- ##### FUNCTION gtk_type_children_types ##### -->
1291 Return the pointer to the type's children's types.
1295 @Returns: pointer to a GList
1297 <!-- ##### FUNCTION gtk_type_describe_heritage ##### -->
1299 Print the types @type inherits from.
1304 <!-- ##### FUNCTION gtk_type_describe_tree ##### -->
1306 Given a @type, describe all of its children, and their children. Only
1307 show the size if @show_size is true.
1311 @show_size: gboolean
1313 <!-- ##### FUNCTION gtk_type_free ##### -->
1315 Given the type of an object and a pointer to it, the object is freed.
1319 @mem: gpointer to the object
1321 <!-- ##### FUNCTION gtk_type_get_varargs_type ##### -->
1323 Get the varargs type associated with @foreign_type
1326 @foreign_type: GtkType
1329 <!-- ##### FUNCTION gtk_type_parent_class ##### -->
1331 Return the class of the parent. Initialize the class if necessary.
1332 Return NULL if anything goes wrong.
1336 @Returns: gpointer to the klass.
1338 <!-- ##### FUNCTION gtk_type_query ##### -->
1340 Given a type, return various interesting parameters of the type.
1344 @Returns: GtkTypeQuery*
1346 <!-- ##### FUNCTION gtk_type_register_enum ##### -->
1348 Register a new set of enum @values and give them the name in
1352 @type_name: must not be null.
1353 @values: GtkEnumValue*
1356 <!-- ##### FUNCTION gtk_type_register_flags ##### -->
1358 Register a new set of flags @values and give them the name in
1362 @type_name: must not be null.
1363 @values: GtkFlagValue*
1366 <!-- ##### FUNCTION gtk_type_set_chunk_alloc ##### -->
1368 Set the mem_chunk size so it will hold @n_chunks of the objects of that @type.
1371 @type: There must be an unlocked TypeNode associated with this type otherwise nothing happens.
1374 <!-- ##### FUNCTION gtk_type_set_varargs_type ##### -->
1376 Set the varargs type for a fundamental type @foreign_type.
1379 @foreign_type: Must be a GtkType with a sequence number of zero. Must not be a
1381 @varargs_type: Must be a GtkType which is either structured or flag, or NONE.
1383 <!-- ##### FUNCTION gtk_window_get_default_accel_group ##### -->