From ebc3eab37c140225a023118ed1315f99e9dd6a1d Mon Sep 17 00:00:00 2001 From: Dmitry Kalyanov Date: Sun, 13 Sep 2009 15:27:40 +0400 Subject: [PATCH] Add GtkStatusbar documentation --- doc/gtk.widgets.texi | 69 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/doc/gtk.widgets.texi b/doc/gtk.widgets.texi index 33eb6a8..f36d754 100644 --- a/doc/gtk.widgets.texi +++ b/doc/gtk.widgets.texi @@ -3208,20 +3208,85 @@ Signals: @Class statusbar Superclass: @ref{h-box} @ref{atk-implementor-iface} @ref{buildable} @ref{orientable} +A @ref{statusbar} is usually placed along the bottom of an application's main @ref{gtk-window}. It may provide a regular commentary of the application's status (as is usually the case in a web browser, for example), or may be used to simply output a message when the status changes, (when an upload is complete in an FTP client, for example). It may also have a resize grip (a triangular area in the lower right corner) which can be clicked on to resize the window containing the statusbar. + +Status bars in GTK+ maintain a stack of messages. The message at the top of the each bar's stack is the one that will currently be displayed. + +Any messages added to a statusbar's stack must specify a context id that is used to uniquely identify the source of a message. Context ids may be specified by context descriptions (as string) or by numeric identifiers obtained by @ref{statusbar-context-id}. Note that messages are stored in a stack, and when choosing which message to display, the stack structure is adhered to, regardless of the context description of a message. + +One could say that a statusbar maintains one stack of messages for display purposes, but allows multiple message producers to maintain sub-stacks of the messages they produced (via context descriptions). + +Messages are added to the bar's stack with @ref{statusbar-push}. + +The message at the top of the stack can be removed using @ref{statusbar-pop}. A message can be removed from anywhere in the stack if its @var{message-id} was recorded at the time it was added. This is done using @ref{statusbar-remove}. + Slots: @itemize @item @anchor{slot.statusbar.has-resize-grip}has-resize-grip. Type: @code{boolean}. Accessor: @anchor{fn.statusbar-has-resize-grip}@code{statusbar-has-resize-grip}. + +Whether the statusbar has a grip for resizing the toplevel window. + +Default value: True @end itemize Signals: @itemize -@item @anchor{signal.statusbar.text-popped}"text-popped". Signature: (instance @ref{statusbar}), (arg-1 @code{integer}), (arg-2 @code{string}) @result{} void. Options: run-last. -@item @anchor{signal.statusbar.text-pushed}"text-pushed". Signature: (instance @ref{statusbar}), (arg-1 @code{integer}), (arg-2 @code{string}) @result{} void. Options: run-last. +@item @anchor{signal.statusbar.text-popped}"text-popped". Signature: (instance @ref{statusbar}), (context-id @code{integer}), (text @code{string}) @result{} void. Options: run-last. + +Is emitted whenever a new message is popped off a statusbar's stack. + +@var{context-id} is a numeric identifier of a context. +@item @anchor{signal.statusbar.text-pushed}"text-pushed". Signature: (instance @ref{statusbar}), (context-id @code{integer}), (text @code{string}) @result{} void. Options: run-last. + +Is emitted whenever a new message gets pushed onto a statusbar's stack. + +@var{context-id} is a numeric identifier of a context. @end itemize +@RMethod statusbar-context-id +@lisp +(statusbar-context-id statusbar context-description) @result{} context-id +@end lisp + +Returns a context identifier, given a description of the actual context. Note that the description is not shown in the UI. + +@var{context-description} is a string - textual description of what context the new message is being used in + +@RMethod statusbar-push +@lisp +(statusbar-push statusbar context text) @result{} message-id +@end lisp + +Pushes a new message onto a statusbar's stack. + +@var{context}: a string (context description) or a number obtained by @ref{statusbar-context-id} + +@var{text}: the message to add to the statusbar + +@var{message-id}: a message id that can be used with @ref{statusbar-remove}. + +@RMethod statusbar-pop +@lisp +(statusbar-pop statusbar context) +@end lisp + +Removes the first message in the @ref{statusbar}'s stack with the given context. + +Note that this may not change the displayed message, if the message at the top of the stack has a different context. + +@var{context}: a string (context description) or a number obtained by @ref{statusbar-context-id} + +@RMethod statusbar-remove +@lisp +(statusbar-remove statusbar context message-id) +@end lisp + +Forces the removal of a message from a statusbar's stack. The exact @var{context} and @var{message-id} must be specified. +@var{context}: a string (context description) or a number obtained by @ref{statusbar-context-id} +@var{message-id}: a message identifier returned by @ref{statusbar-push} @node table @section table -- 1.7.10.4