Add GtkStatusbar documentation

diff --git a/doc/gtk.widgets.texi b/doc/gtk.widgets.texi
index 33eb6a8..f36d754 100644 (file)
--- 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