diff options
| -rw-r--r-- | docs/reference/ChangeLog | 7 | ||||
| -rw-r--r-- | docs/reference/gtk/gtk-docs.sgml | 1 | ||||
| -rw-r--r-- | docs/reference/gtk/tmpl/gtkmain.sgml | 154 | ||||
| -rw-r--r-- | gtk/gtkcontainer.c | 74 |
4 files changed, 155 insertions, 81 deletions
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 94c1ed28a..74771db94 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,10 @@ +2001-12-09 Matthias Clasen <matthiasc@poet.de> + + * gtk/tmpl/gtkmain.sgml: Markup fixes. + + * gtk/gtk-docs.sgml: Add an empty entity to suppress + crossreferencing in programlistings. + 2001-12-08 Matthias Clasen <matthiasc@poet.de> * gtk/tmpl/gtkclipboard.sgml: Fix references to diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 04c4d0cba..f957c96b3 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -3,6 +3,7 @@ <!entity % local.notation.class "| PNG"> <!entity hash "#"> +<!entity empty ""> <!entity GtkAccelLabel SYSTEM "sgml/gtkaccellabel.sgml"> <!entity GtkAdjustment SYSTEM "sgml/gtkadjustment.sgml"> <!entity GtkAlignment SYSTEM "sgml/gtkalignment.sgml"> diff --git a/docs/reference/gtk/tmpl/gtkmain.sgml b/docs/reference/gtk/tmpl/gtkmain.sgml index e234c487e..01d20aca1 100644 --- a/docs/reference/gtk/tmpl/gtkmain.sgml +++ b/docs/reference/gtk/tmpl/gtkmain.sgml @@ -45,13 +45,13 @@ to the main loop and await more user input. </para> <example> -<title> Typical <function>main</function> function for a GTK application</title> +<title>Typical <function>main</function> function for a GTK application</title> <programlisting> int main (int argc, char **argv) { /* Initialize i18n support */ - gtk_set_locale (); + gtk_set_locale (∅); /* Initialize the widget set */ gtk_init (&argc, &argv); @@ -66,7 +66,7 @@ main (int argc, char **argv) gtk_widget_show_all (mainwin); /* Enter the main event loop, and wait for user interaction */ - gtk_main (); + gtk_main (∅); /* The user lost interest */ return 0; @@ -131,13 +131,13 @@ instead. <function>main</function> function. Changed if any arguments were handled. @argv: Address of the <parameter>argv</parameter> parameter of -<function>main</function>. Any parameters understood by <function> -gtk_init</function> are stripped before return. +<function>main()</function>. Any parameters understood by gtk_init() +are stripped before return. <!-- ##### FUNCTION gtk_init_check ##### --> <para> -This function does the same work as <function>gtk_init</function> with only +This function does the same work as gtk_init() with only a single change: It does not terminate the program if the GUI can't be initialized. Instead it returns %FALSE on failure. </para> @@ -146,17 +146,17 @@ This way the application can fall back to some other means of communication with the user - for example a curses or command line interface. </para> -@argc: A reference to the <parameter>argc</parameter> of the <function>main -</function> function. -@argv: A reference to the <parameter>argv</parameter> of the <function>main -</function> function. -@Returns: %TRUE if the GUI has been successful initialized, +@argc: A reference to the <parameter>argc</parameter> of the +<function>main()</function> function. +@argv: A reference to the <parameter>argv</parameter> of the +<function>main()</function> function. +@Returns: %TRUE if the GUI has been successfully initialized, %FALSE otherwise. <!-- ##### FUNCTION gtk_exit ##### --> <para> -Terminate the program and return the given exit code to the caller. +Terminates the program and returns the given exit code to the caller. This function will shut down the GUI and free all resources allocated for GTK. </para> @@ -168,17 +168,17 @@ success. <!-- ##### FUNCTION gtk_events_pending ##### --> <para> -Check if any events are pending. This can be used to update the GUI +Checks if any events are pending. This can be used to update the GUI and invoke timeouts etc. while doing some time intensive computation. </para> <example> -<title> Updating the GUI during a long computation</title> +<title>Updating the GUI during a long computation</title> <programlisting> /* computation going on */ ... - while (gtk_events_pending ()) - gtk_main_iteration (); + while (gtk_events_pending (∅)) + gtk_main_iteration (∅); ... /* computation continued */ </programlisting> @@ -190,7 +190,7 @@ and invoke timeouts etc. while doing some time intensive computation. <!-- ##### FUNCTION gtk_main ##### --> <para> Runs the main loop until gtk_main_quit() is called. You can nest calls to -gtk_main. In that case gtk_main_quit() will make the innerst invocation +gtk_main(). In that case gtk_main_quit() will make the innermost invocation of the main loop return. </para> @@ -198,8 +198,8 @@ of the main loop return. <!-- ##### FUNCTION gtk_main_level ##### --> <para> -Ask for the current nesting level of the main loop. This can be useful -when calling gtk_quit_add. +Asks for the current nesting level of the main loop. This can be useful +when calling gtk_quit_add(). </para> @Returns: the nesting level of the current invocation of the main loop. @@ -217,27 +217,27 @@ control. <para> Runs a single iteration of the mainloop. If no events are waiting to be processed GTK+ will block until the next event is noticed. If you don't -want to block look at gtk_main_iteration_do or check if any events are -pending with gtk_events_pending first. +want to block look at gtk_main_iteration_do() or check if any events are +pending with gtk_events_pending() first. </para> -@Returns: %TRUE if gtk_main_quit has been called for the innermost mainloop. +@Returns: %TRUE if gtk_main_quit() has been called for the innermost mainloop. <!-- ##### FUNCTION gtk_main_iteration_do ##### --> <para> -Run a single iteration of the mainloop. If no events are available either -return or block dependend on the value of @blocking. +Runs a single iteration of the mainloop. If no events are available either +return or block dependent on the value of @blocking. </para> @blocking: %TRUE if you want GTK+ to block if no events are pending. -@Returns: %TRUE if gtk_main_quit has been called for the innermost mainloop. +@Returns: %TRUE if gtk_main_quit() has been called for the innermost mainloop. <!-- ##### FUNCTION gtk_main_do_event ##### --> <para> -Process a single GDK event. This is public only to allow filtering of events -between GDK and GTK. You will not usually need to call this function directly. +Processes a single GDK event. This is public only to allow filtering of events +between GDK and GTK+. You will not usually need to call this function directly. </para> <para> While you should not call this function directly, you might want to know @@ -248,18 +248,18 @@ the event: <orderedlist> <listitem><para> Compress enter/leave notify events. If the event passed build an - enter/leave pair together with the next event (peeked from Gdk) + enter/leave pair together with the next event (peeked from GDK) both events are thrown away. This is to avoid a backlog of (de-)highlighting widgets crossed by the pointer. </para></listitem> <listitem><para> Find the widget which got the event. If the widget can't be determined the event is thrown away unless it belongs to a INCR transaction. In that - case it is passed to gtk_selection_incr_event. + case it is passed to gtk_selection_incr_event(). </para></listitem> <listitem><para> Then the event is passed on a stack so you can query the currently handled - event with gtk_get_current_event. + event with gtk_get_current_event(). </para></listitem> <listitem><para> The event is sent to a widget. If a grab is active all events for @@ -294,30 +294,30 @@ the event: </para></listitem> </orderedlist> -@event: An event to process (normally) passed by Gdk. +@event: An event to process (normally) passed by GDK. <!-- ##### USER_FUNCTION GtkModuleInitFunc ##### --> <para> -Each GTK+ module must have a function gtk_module_init with this prototype. -This function is called after loading the module with the argc and argv +Each GTK+ module must have a function gtk_module_init() with this prototype. +This function is called after loading the module with the @argc and @argv cleaned from any arguments that GTK+ handles itself. </para> -@argc: Pointer to the number of arguments remaining after gtk_init. +@argc: Pointer to the number of arguments remaining after gtk_init(). @argv: Points to the argument vector. <!-- ##### FUNCTION gtk_true ##### --> <para> -All this function does it to return TRUE. This can be useful for example +All this function does it to return %TRUE. This can be useful for example if you want to inhibit the deletion of a window. Of course you should not do this as the user expects a reaction from clicking the close icon of the window... </para> <example> -<title> A persistent window</title> +<title>A persistent window</title> <programlisting> ##include <gtk/gtk.h> @@ -341,7 +341,7 @@ main (int argc, char **argv) gtk_container_add (GTK_CONTAINER (win), but); gtk_widget_show_all (win); - gtk_main (); + gtk_main (∅); return 0; } </programlisting> @@ -352,7 +352,7 @@ main (int argc, char **argv) <!-- ##### FUNCTION gtk_false ##### --> <para> -Analogical to <function>gtk_true</function> this function does nothing +Analogical to gtk_true() this function does nothing but always returns %FALSE. </para> @@ -361,9 +361,9 @@ but always returns %FALSE. <!-- ##### FUNCTION gtk_grab_add ##### --> <para> -Makes %widget the current grabbed widget. This means that interaction with +Makes @widget the current grabbed widget. This means that interaction with other widgets in the same application is blocked and mouse as well as -keyboard events are delivered to this %widget. +keyboard events are delivered to this widget. </para> @widget: The widget that grabs keyboard and pointer events. @@ -379,8 +379,8 @@ Queries the current grab. <!-- ##### FUNCTION gtk_grab_remove ##### --> <para> -Remove the grab from the given widget. You have to pair calls to gtk_grab_add -and gtk_grab_remove. +Removes the grab from the given widget. You have to pair calls to gtk_grab_add() +and gtk_grab_remove(). </para> @widget: The widget which gives up the grab. @@ -388,16 +388,16 @@ and gtk_grab_remove. <!-- ##### FUNCTION gtk_init_add ##### --> <para> -Register a function to be called when the mainloop is started. +Registers a function to be called when the mainloop is started. </para> -@function: Function to invoke when gtk_main is called next. +@function: Function to invoke when gtk_main() is called next. @data: Data to pass to that function. <!-- ##### FUNCTION gtk_quit_add_destroy ##### --> <para> -Trigger destruction of %object in case the mainloop at level %main_level +Trigger destruction of @object in case the mainloop at level @main_level is quit. </para> @@ -415,9 +415,9 @@ Registers a function to be called when an instance of the mainloop is left. mainloop. @function: The function to call. This should return 0 to be removed from the list of quit handlers. Otherwise the function might be called again. -@data: Pointer to pass when calling %function. +@data: Pointer to pass when calling @function. @Returns: A handle for this quit handler (you need this for gtk_quit_remove()) - or 0 if you passed a NULL pointer in %function. + or 0 if you passed a %NULL pointer in @function. <!-- ##### FUNCTION gtk_quit_add_full ##### --> @@ -428,8 +428,8 @@ pass a marshaller and a function to be called when the quit handler is freed. </para> <para> The former can be used to run interpreted code instead of a compiled function -while the latter can be used to free the information stored in %data (while -you can do this in %function as well)... So this function will mostly be +while the latter can be used to free the information stored in @data (while +you can do this in @function as well)... So this function will mostly be used by GTK+ wrappers for languages other than C. </para> @@ -438,17 +438,17 @@ used by GTK+ wrappers for languages other than C. mainloop. @function: The function to call. This should return 0 to be removed from the list of quit handlers. Otherwise the function might be called again. -@marshal: The marshaller to be used. If this is non-NULL, %function is +@marshal: The marshaller to be used. If this is non-%NULL, @function is ignored. -@data: Pointer to pass when calling %function. -@destroy: Function to call to destruct %data. Gets %data as argument. +@data: Pointer to pass when calling @function. +@destroy: Function to call to destruct @data. Gets @data as argument. @Returns: A handle for this quit handler (you need this for gtk_quit_remove()) - or 0 if you passed a NULL pointer in %function. + or 0 if you passed a %NULL pointer in @function. <!-- ##### FUNCTION gtk_quit_remove ##### --> <para> -Remove a quit handler by it's identifier. +Removes a quit handler by it's identifier. </para> @quit_handler_id: Identifier for the handler returned when installing it. @@ -456,32 +456,32 @@ Remove a quit handler by it's identifier. <!-- ##### FUNCTION gtk_quit_remove_by_data ##### --> <para> -Remove a quit handler identified by it's %data field. +Removes a quit handler identified by it's @data field. </para> -@data: The pointer passed as %data to gtk_quit_add() or gtk_quit_add_full(). +@data: The pointer passed as @data to gtk_quit_add() or gtk_quit_add_full(). <!-- ##### FUNCTION gtk_timeout_add_full ##### --> <para> Registers a function to be called periodically. The function will be called -repeatedly after %interval milliseconds until it returns %FALSE at which +repeatedly after @interval milliseconds until it returns %FALSE at which point the timeout is destroyed and will not be called again. </para> @interval: The time between calls to the function, in milliseconds (1/1000ths of a second.) @function: The function to call periodically. -@marshal: The marshaller to use instead of the function (if non-NULL). +@marshal: The marshaller to use instead of the function (if non-%NULL). @data: The data to pass to the function. -@destroy: Function to call when the timeout is destroyed or NULL. +@destroy: Function to call when the timeout is destroyed or %NULL. @Returns: A unique id for the event source. <!-- ##### FUNCTION gtk_timeout_add ##### --> <para> Registers a function to be called periodically. The function will be called -repeatedly after %interval milliseconds until it returns %FALSE at which +repeatedly after @interval milliseconds until it returns %FALSE at which point the timeout is destroyed and will not be called again. </para> @@ -504,7 +504,7 @@ Removes the given timeout destroying all information about it. <para> Causes the mainloop to call the given function whenever no events with higher priority are to be processed. The default priority is -GTK_PRIORITY_DEFAULT, which is rather low. +%GTK_PRIORITY_DEFAULT, which is rather low. </para> @function: The function to call. @@ -516,12 +516,12 @@ GTK_PRIORITY_DEFAULT, which is rather low. <para> Like gtk_idle_add() this function allows you to have a function called when the event loop is idle. The difference is that you can give a -priority different from GTK_PRIORITY_DEFAULT to the idle function. +priority different from %GTK_PRIORITY_DEFAULT to the idle function. </para> -@priority: The priority which should not be above G_PRIORITY_HIGH_IDLE. -Note that you will interfere with GTK if you use a priority above -GTK_PRIORITY_RESIZE. +@priority: The priority which should not be above %G_PRIORITY_HIGH_IDLE. +Note that you will interfere with GTK+ if you use a priority above +%GTK_PRIORITY_RESIZE. @function: The function to call. @data: Data to pass to that function. @Returns: A unique id for the event source. @@ -529,15 +529,19 @@ GTK_PRIORITY_RESIZE. <!-- ##### FUNCTION gtk_idle_add_full ##### --> <para> - +Like gtk_idle_add() this function allows you to have a function called +when the event loop is idle. The difference is that you can give a +priority different from %GTK_PRIORITY_DEFAULT to the idle function. </para> -@priority: -@function: -@marshal: -@data: -@destroy: -@Returns: +@priority: The priority which should not be above %G_PRIORITY_HIGH_IDLE. +Note that you will interfere with GTK+ if you use a priority above +%GTK_PRIORITY_RESIZE. +@function: The function to call. +@marshal: The marshaller to use instead of the function (if non-%NULL). +@data: Data to pass to that function. +@destroy: Function to call when the timeout is destroyed or %NULL. +@Returns: A unique id for the event source. <!-- ##### FUNCTION gtk_idle_remove ##### --> @@ -603,7 +607,7 @@ Use this for high priority timeouts. This priority is never used inside GTK+ so everything running at this priority will be running before anything inside the toolkit. <note><para> -This macro is deprecated. You should use G_PRIORITY_HIGH instead. +This macro is deprecated. You should use %G_PRIORITY_HIGH instead. </para></note> </para> @@ -620,7 +624,7 @@ This priority is for GTK+ internal stuff. Don't use it in your applications. <para> Default priority for idle functions. <note><para> -This macro is deprecated. You should use G_PRIORITY_DEFAULT_IDLE instead. +This macro is deprecated. You should use %G_PRIORITY_DEFAULT_IDLE instead. </para></note> </para> @@ -630,7 +634,7 @@ This macro is deprecated. You should use G_PRIORITY_DEFAULT_IDLE instead. <para> Priority for very unimportant background tasks. <note><para> -This macro is deprecated. You should use G_PRIORITY_LOW instead. +This macro is deprecated. You should use %G_PRIORITY_LOW instead. </para></note> </para> diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c index b4d128b1b..f509a51bc 100644 --- a/gtk/gtkcontainer.c +++ b/gtk/gtkcontainer.c @@ -254,6 +254,17 @@ gtk_container_class_init (GtkContainerClass *class) GTK_TYPE_WIDGET); } +/** + * gtk_container_child_type: + * @container: a #GtkContainer. + * + * Returns the type of the children supported by the container. + * + * Note that this may return %GTK_TYPE_NONE to indicate that no more + * children can be added, e.g. for a #GtkPaned which already has two + * children. + * + * Return value: a #GtkType. GtkType gtk_container_child_type (GtkContainer *container) { @@ -783,6 +794,8 @@ gtk_container_get_property (GObject *object, * @border_width: amount of blank space to leave <emphasis>outside</emphasis> the container. * Valid values are in the range 0-65535 pixels. * + * Sets the border width of the container. + * * The border width of a container is the amount of space to leave * around the outside of the container. The only exception to this is * #GtkWindow; because toplevel windows can't leave space outside, @@ -897,6 +910,17 @@ _gtk_container_dequeue_resize_handler (GtkContainer *container) GTK_PRIVATE_UNSET_FLAG (container, GTK_RESIZE_PENDING); } +/** + * gtk_container_set_resize_mode: + * @container: a #GtkContainer. + * @resize_mode: the new resize mode. + * + * Sets the resize mode for the container. + * + * The resize mode of a container determines whether a resize request + * will be passed to the container's parent, queued for later execution + * or executed immediately. + **/ void gtk_container_set_resize_mode (GtkContainer *container, GtkResizeMode resize_mode) @@ -938,6 +962,16 @@ gtk_container_get_resize_mode (GtkContainer *container) return container->resize_mode; } +/** + * gtk_container_set_reallocate_redraws: + * @container: a #GtkContainer. + * @needs_redraws: the new value for the container's @reallocate_redraws flag. + * + * Sets the @reallocate_redraws flag of the container to the given value. + * + * Containers requesting reallocation redraws get automatically + * redrawn if any of their children changed allocation. + **/ void gtk_container_set_reallocate_redraws (GtkContainer *container, gboolean needs_redraws) @@ -1246,6 +1280,15 @@ gtk_container_set_focus_child (GtkContainer *container, gtk_signal_emit (GTK_OBJECT (container), container_signals[SET_FOCUS_CHILD], widget); } +/** + * gtk_container_get_children: + * @container: a #GtkContainer. + * + * Returns the the container's non-internal children. See + * gtk_container_forall() for details on what constitutes an "internal" child. + * + * Return value: a newly-allocated list of the container's non-internal children. + **/ GList* gtk_container_get_children (GtkContainer *container) { @@ -1909,6 +1952,19 @@ chain_widget_destroyed (GtkWidget *widget, chain); } +/** + * gtk_container_set_focus_chain: + * @container: a #GtkContainer. + * @focusable_widgets: the new focus chain. + * + * Sets a focus chain, overriding the one computed automatically by GTK+. + * + * In principle each widget in the chain should be a descendant of the + * container, but this is not enforced by this method, since it's allowed + * to set the focus chain before you pack the widgets, or have a widget + * in the chain that isn't always packed. The necessary checks are done + * when the focus chain is actually traversed. + **/ void gtk_container_set_focus_chain (GtkContainer *container, GList *focusable_widgets) @@ -1962,14 +2018,14 @@ gtk_container_set_focus_chain (GtkContainer *container, * no additional reference count is added to the * individual widgets in the focus chain. * - * Retrieve the focus chain of the container, if one has been - * set explicitely. If no focus chain has been explicitely + * Retrieves the focus chain of the container, if one has been + * set explicitly. If no focus chain has been explicitly * set, GTK+ computes the focus chain based on the positions * of the children. In that case, GTK+ stores %NULL in * @focusable_widgets and returns %FALSE. * - * Return value: %TRUE if the focus chain of the container, - * has been set explicitely. + * Return value: %TRUE if the focus chain of the container + * has been set explicitly. **/ gboolean gtk_container_get_focus_chain (GtkContainer *container, @@ -1988,6 +2044,12 @@ gtk_container_get_focus_chain (GtkContainer *container, return container->has_focus_chain; } +/** + * gtk_container_unset_focus_chain: + * @container: a #GtkContainer. + * + * Removes a focus chain explicitly set with gtk_container_set_focus_chain(). + **/ void gtk_container_unset_focus_chain (GtkContainer *container) { @@ -2210,7 +2272,7 @@ gtk_container_unmap (GtkWidget *widget) * @child: a child of @container * @event: a expose event sent to container * - * When a container receives an expose event, it must send synthetic + * When a container receives an expose event, it must send synthetic * expose events to all children that don't have their own #GdkWindows. * This function provides a convenient way of doing this. A container, * when it receives an expose event, calls gtk_container_propagate_expose() @@ -2222,7 +2284,7 @@ gtk_container_unmap (GtkWidget *widget) * * In most cases, a container can simply either simply inherit the * ::expose implementation from #GtkContainer, or, do some drawing - * and then chain to the ::expose implementation from GtkContainer. + * and then chain to the ::expose implementation from #GtkContainer. **/ void gtk_container_propagate_expose (GtkContainer *container, |