This is guile-gnome-gtk.info, produced by makeinfo version 4.8 from
guile-gnome-gtk.texi.

   This manual is for `(gnome gtk)' (version 2.15.93, updated 2
September 2007)

   Copyright 1997-2007 Damon Chaplin and others

     This work may be reproduced and distributed in whole or in part, in
     any medium, physical or electronic, so as long as this copyright
     notice remains intact and unchanged on all copies.  Commercial
     redistribution is permitted and encouraged, but you may not
     redistribute, in whole or in part, under terms more restrictive
     than those under which you received it. If you redistribute a
     modified or translated version of this work, you must also make
     the source code to the modified or translated version available in
     electronic form without charge.  However, mere aggregation as part
     of a larger work shall not count as a modification for this
     purpose.

     All code examples in this work are placed into the public domain,
     and may be used, modified and redistributed without restriction.

     BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
     FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT
     WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
     OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY
     KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
     THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
     PARTICULAR PURPOSE.  SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME
     THE COST OF ALL NECESSARY REPAIR OR CORRECTION.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE
     TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
     CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
     THE WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
     THE POSSIBILITY OF SUCH DAMAGES.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* Guile-Gtk: (guile-gnome-gtk.info).  The GIMP ToolKit.
END-INFO-DIR-ENTRY


File: guile-gnome-gtk.info,  Node: Top,  Next: Overview,  Up: (dir)

Guile-Gtk
*********

This manual is for `(gnome gtk)' (version 2.15.93, updated 2 September
2007)

   Copyright 1997-2007 Damon Chaplin and others

     This work may be reproduced and distributed in whole or in part, in
     any medium, physical or electronic, so as long as this copyright
     notice remains intact and unchanged on all copies.  Commercial
     redistribution is permitted and encouraged, but you may not
     redistribute, in whole or in part, under terms more restrictive
     than those under which you received it. If you redistribute a
     modified or translated version of this work, you must also make
     the source code to the modified or translated version available in
     electronic form without charge.  However, mere aggregation as part
     of a larger work shall not count as a modification for this
     purpose.

     All code examples in this work are placed into the public domain,
     and may be used, modified and redistributed without restriction.

     BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
     FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT
     WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
     OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY
     KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
     THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
     PARTICULAR PURPOSE.  SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME
     THE COST OF ALL NECESSARY REPAIR OR CORRECTION.

     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE
     TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
     CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
     THE WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
     THE POSSIBILITY OF SUCH DAMAGES.

* Menu:


* Overview:: Overview

Windows
* GtkDialog:: Create popup windows
* GtkInvisible:: A widget which is not displayed
* GtkMessageDialog:: A convenient message window
* GtkWindow:: Toplevel which can contain other widgets
* GtkWindowGroup:: Limit the effect of grabs
* GtkAboutDialog:: Display information about an application
* GtkAssistant:: A widget used to guide users through multi-step operations

Display Widgets
* GtkAccelLabel:: A label which displays an accelerator key on the right of the text
* GtkImage:: A widget displaying an image
* GtkLabel:: A widget that displays a small to medium amount of text
* GtkProgressBar:: A widget which indicates progress visually
* GtkStatusbar:: Report messages of minor importance to the user
* GtkStatusIcon:: Display an icon in the system tray

Buttons and Toggles
* GtkButton:: A widget that creates a signal when clicked on
* GtkCheckButton:: Create widgets with a discrete toggle button
* GtkRadioButton:: A choice from multiple check buttons
* GtkToggleButton:: Create buttons which retain their state
* GtkLinkButton:: Create buttons bound to a URL

Numeric/Text Data Entry
* GtkEntry:: A single line text entry field
* GtkEntryCompletion:: Completion functionality for GtkEntry
* GtkHScale:: A horizontal slider widget for selecting a value from a range
* GtkVScale:: A vertical slider widget for selecting a value from a range
* GtkSpinButton:: Retrieve an integer or floating-point number from the user
* GtkEditable:: Interface for text-editing widgets

Multiline Text Editor
* GtkTextIter:: Text buffer iterator
* GtkTextMark:: A position in the buffer preserved across buffer modifications
* GtkTextBuffer:: Stores attributed text for display in a GtkTextView
* GtkTextTag:: A tag that can be applied to text in a <a href="GtkTextBuffer.html" title="GtkTextBuffer">GtkTextBuffer</a>
* GtkTextTagTable:: Collection of tags that can be used together
* GtkTextView:: Widget that displays a <a href="GtkTextBuffer.html" title="GtkTextBuffer">GtkTextBuffer</a>

Tree, List and Icon Grid Widgets
* GtkTreeModel:: The tree interface used by <a href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</a>
* GtkTreeSelection:: The selection object for <a href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</a>
* GtkTreeViewColumn:: A visible column in a <a href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</a> widget
* GtkTreeView:: A widget for displaying both trees and lists
* GtkTreeView drag-and-drop:: Interfaces for drag-and-drop support in GtkTreeView
* GtkCellView:: A widget displaying a single row of a GtkTreeModel
* GtkIconView:: A widget which displays a list of icons in a grid
* GtkTreeSortable:: The interface for sortable models used by GtkTreeView
* GtkTreeModelSort:: A GtkTreeModel which makes an underlying tree model sortable
* GtkTreeModelFilter:: A GtkTreeModel which hides parts of an underlying tree model
* GtkCellLayout:: An interface for packing cells
* GtkCellRenderer:: An object for rendering a single cell on a <GTKDOCLINK HREF="GdkDrawable"><span class="type">GdkDrawable</GTKDOCLINK>
* GtkCellEditable:: Interface for widgets which can are used for editing cells
* GtkCellRendererAccel:: Renders a keyboard accelerator in a cell
* GtkCellRendererCombo:: Renders a combobox in a cell
* GtkCellRendererPixbuf:: Renders a pixbuf in a cell
* GtkCellRendererProgress:: Renders numbers as progress bars
* GtkCellRendererSpin:: Renders a spin button in a cell
* GtkCellRendererText:: Renders text in a cell
* GtkCellRendererToggle:: Renders a toggle button in a cell
* GtkListStore:: A list-like data structure that can be used with the <a href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</a>
* GtkTreeStore:: A tree-like data structure that can be used with the <a href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</a>

Menus, Combo Box, Toolbar
* GtkComboBox:: A widget used to choose from a list of items
* GtkComboBoxEntry:: A text entry field with a dropdown list
* GtkMenu:: A menu widget
* GtkMenuBar:: A subclass widget for <a href="GtkMenuShell.html" title="GtkMenuShell"><span class="type">GtkMenuShell</a> which holds <a href="GtkMenuItem.html" title="GtkMenuItem"><span class="type">GtkMenuItem</a> widgets
* GtkMenuItem:: The widget used for item in menus
* GtkMenuShell:: A base class for menu objects
* GtkImageMenuItem:: A menu item with an icon
* GtkRadioMenuItem:: A choice from multiple check menu items
* GtkCheckMenuItem:: A menu item with a check box
* GtkSeparatorMenuItem:: A separator used in menus
* GtkTearoffMenuItem:: A menu item used to tear off and reattach its menu
* GtkToolbar:: Create bars of buttons and other widgets
* GtkToolItem:: The base class of widgets that can be added to GtkToolbar
* GtkSeparatorToolItem:: A toolbar item that separates groups of other toolbar items
* GtkToolButton:: A GtkToolItem subclass that displays buttons
* GtkMenuToolButton:: A GtkToolItem containing a button with an additional dropdown menu
* GtkToggleToolButton:: A GtkToolItem containing a toggle button
* GtkRadioToolButton:: A toolbar item that contains a radio button

Action-based menus and toolbars
* GtkUIManager:: Constructing menus and toolbars from an XML description
* GtkActionGroup:: A group of actions
* GtkAction:: An action which can be triggered by a menu or toolbar item
* GtkToggleAction:: An action which can be toggled between two states
* GtkRadioAction:: An action of which only one in a group can be active

Selectors (File/Font/Color/Input Devices)
* GtkColorButton:: A button to launch a color selection dialog
* GtkColorSelection:: A widget used to select a color
* GtkColorSelectionDialog:: A standard dialog box for selecting a color
* GtkFileSelection:: Prompt the user for a file or directory name
* GtkFileChooser:: File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog
* GtkFileChooserButton:: A button to launch a file selection dialog
* GtkFileChooserDialog:: A file chooser dialog, suitable for "File/Open" or "File/Save" commands
* GtkFileChooserWidget:: File chooser widget that can be embedded in other widgets
* GtkFileFilter:: A filter for selecting a file subset
* GtkFontButton:: A button to launch a font selection dialog
* GtkFontSelection:: A widget for selecting fonts
* GtkFontSelectionDialog:: A dialog box for selecting fonts
* GtkInputDialog:: Configure devices for the XInput extension

Layout Containers
* GtkAlignment:: A widget which controls the alignment and size of its child
* GtkAspectFrame:: A frame that constrains its child to a particular aspect ratio
* GtkHBox:: A horizontal container box
* GtkVBox:: A vertical container box
* GtkHButtonBox:: A container for arranging buttons horizontally
* GtkVButtonBox:: A container for arranging buttons vertically
* GtkFixed:: A container which allows you to position widgets at fixed coordinates
* GtkHPaned:: A container with two panes arranged horizontally
* GtkVPaned:: A container with two panes arranged vertically
* GtkLayout:: Infinite scrollable area containing child widgets and/or custom drawing
* GtkNotebook:: A tabbed notebook container
* GtkTable:: Pack widgets in regular patterns
* GtkExpander:: A container which can hide its child

Ornaments
* GtkFrame:: A bin with a decorative frame and optional label
* GtkHSeparator:: A horizontal separator
* GtkVSeparator:: A vertical separator

Scrolling
* GtkHScrollbar:: A horizontal scrollbar
* GtkVScrollbar:: A vertical scrollbar
* GtkScrolledWindow:: Adds scrollbars to its child widget

Printing
* GtkPrintOperation:: High-level Printing API
* GtkPrintContext:: Encapsulates context for drawing pages
* GtkPrintSettings:: Stores print settings
* GtkPageSetup:: Stores page setup information
* GtkPaperSize:: Support for named paper sizes
* GtkPrinter:: Represents a printer
* GtkPrintJob:: Represents a print job
* GtkPrintUnixDialog:: A print dialog
* GtkPageSetupUnixDialog:: A page setup dialog

Miscellaneous
* GtkAdjustment:: A GtkObject representing an adjustable bounded value
* GtkArrow:: Displays an arrow
* GtkCalendar:: Displays a calendar and allows the user to select a date
* GtkDrawingArea:: A widget for custom user interface elements
* GtkEventBox:: A widget used to catch events for widgets which do not have their own window
* GtkHandleBox:: a widget for detachable window portions
* GtkIMContextSimple:: An input method context supporting table-based input methods
* GtkIMMulticontext:: An input method context supporting multiple, loadable input methods
* GtkSizeGroup:: Grouping widgets so they request the same size
* GtkTooltips:: Add tips to your widgets
* GtkViewport:: An adapter which makes widgets scrollable
* GtkAccessible:: Accessibility support for widgets

Abstract Base Classes
* GtkBin:: A container with just one child
* GtkBox:: Base class for box containers
* GtkButtonBox:: Base class for <a href="GtkHButtonBox.html" title="GtkHButtonBox"><span class="type">GtkHButtonBox</a> and <a href="GtkVButtonBox.html" title="GtkVButtonBox"><span class="type">GtkVButtonBox</a>
* GtkContainer:: Base class for widgets which contain other widgets
* GtkItem:: Abstract base class for GtkMenuItem, GtkListItem and GtkTreeItem
* GtkMisc:: Base class for widgets with alignments and padding
* GtkObject:: The base class of the GTK+ type hierarchy
* GtkPaned:: Base class for widgets with two adjustable panes
* GtkRange:: Base class for widgets which visualize an adjustment
* GtkScale:: Base class for GtkHScale and GtkVScale
* GtkScrollbar:: Base class for GtkHScrollbar and GtkVScrollbar
* GtkSeparator:: Base class for <a href="GtkHSeparator.html" title="GtkHSeparator"><span class="type">GtkHSeparator</a> and <a href="GtkVSeparator.html" title="GtkVSeparator"><span class="type">GtkVSeparator</a>
* GtkWidget:: Base class for all widgets
* GtkIMContext:: Base class for input method contexts

Cross-process Embedding
* GtkPlug:: Toplevel for embedding into other processes
* GtkSocket:: Container for widgets from other processes

Special-purpose features
* GtkCurve:: Allows direct editing of a curve
* GtkGammaCurve:: a subclass of <a href="GtkCurve.html" title="GtkCurve"><span class="type">GtkCurve</a> for editing gamma curves.
* GtkRuler:: Base class for horizontal or vertical rulers
* GtkHRuler:: A horizontal ruler.
* GtkVRuler:: A vertical ruler.

Recently Used Documents
* GtkRecentManager:: Managing Recently Used Files
* GtkRecentChooser:: Interface implemented by GtkRecentChooserWidget, GtkRecentChooserMenu and GtkRecentChooserDialog
* GtkRecentChooserDialog:: Displays recently used files in a dialog
* GtkRecentChooserMenu:: Displays recently used files in a menu
* GtkRecentChooserWidget:: Displays recently used files
* GtkRecentFilter:: A filter for selecting a subset of recently used files

* Undocumented::    Undocumented functions.

* Type Index::
* Function Index::


File: guile-gnome-gtk.info,  Node: Overview,  Next: GtkDialog,  Prev: Top,  Up: Top

1 Overview
**********

The GTK+ wrapper for Guile is a part of Guile-GNOME. Maybe write more
here at some point.


File: guile-gnome-gtk.info,  Node: GtkDialog,  Next: GtkInvisible,  Prev: Overview,  Up: Top

2 GtkDialog
***********

Create popup windows

2.1 Overview
============

Dialog boxes are a convenient way to prompt the user for a small amount
of input, e.g. to display a message, ask a question, or anything else
that does not require extensive effort on the user's part.

   GTK+ treats a dialog as a window split vertically. The top section
is a `<gtk-vbox>', and is where widgets such as a `<gtk-label>' or a
`<gtk-entry>' should be packed. The bottom area is known as the . This
is generally used for packing buttons into the dialog which may perform
functions such as cancel, ok, or apply. The two areas are separated by a
`<gtk-hseparator>'.

   `<gtk-dialog>' boxes are created with a call to `gtk-dialog-new' or
`gtk-dialog-new-with-buttons'. `gtk-dialog-new-with-buttons' is
recommended; it allows you to set the dialog title, some convenient
flags, and add simple buttons.

   If 'dialog' is a newly created dialog, the two primary areas of the
window can be accessed as `GTK_DIALOG(dialog)->vbox' and
`GTK_DIALOG(dialog)->action_area', as can be seen from the example,
below.

   A 'modal' dialog (that is, one which freezes the rest of the
application from user input), can be created by calling
`gtk-window-set-modal' on the dialog. Use the `gtk-window' macro to
cast the widget returned from `gtk-dialog-new' into a `<gtk-window>'.
When using `gtk-dialog-new-with-buttons' you can also pass the
`<gtk-dialog-modal>' flag to make a dialog modal.

   If you add buttons to `<gtk-dialog>' using
`gtk-dialog-new-with-buttons', `gtk-dialog-add-button',
`gtk-dialog-add-buttons', or `gtk-dialog-add-action-widget', clicking
the button will emit a signal called "response" with a response ID that
you specified. GTK+ will never assign a meaning to positive response
IDs; these are entirely user-defined. But for convenience, you can use
the response IDs in the `<gtk-response-type>' enumeration (these all
have values less than zero).  If a dialog receives a delete event, the
"response" signal will be emitted with a response ID of
`<gtk-response-delete-event>'.

   If you want to block waiting for a dialog to return before returning
control flow to your code, you can call `gtk-dialog-run'. This function
enters a recursive main loop and waits for the user to respond to the
dialog, returning the response ID corresponding to the button the user
clicked.

   For the simple dialog in the following example, in reality you'd
probably use `<gtk-message-dialog>' to save yourself some effort. But
you'd need to create the dialog contents manually if you had more than
a simple message in the dialog.



     /* Function to open a dialog box displaying the message provided. */

     void quick_message (gchar *message) {

        GtkWidget *dialog, *label;

        /* Create the widgets */

        dialog = gtk_dialog_new_with_buttons ("Message",
                                              main_application_window,
                                              GTK_DIALOG_DESTROY_WITH_PARENT,
                                              GTK_STOCK_OK,
                                              GTK_RESPONSE_NONE,
                                              NULL);
        label = gtk_label_new (message);

        /* Ensure that the dialog box is destroyed when the user responds. */

        g_signal_connect_swapped (dialog,
                                  "response",
                                  G_CALLBACK (gtk_widget_destroy),
                                  dialog);

        /* Add the label, and show everything we've added to the dialog. */

        gtk_container_add (GTK_CONTAINER (GTK_DIALOG(dialog)->vbox),
                           label);
        gtk_widget_show_all (dialog);
     }

2.2 Usage
=========

 -- Class: <gtk-dialog>
     Derives from `<gtk-window>'.

     This class defines the following properties:

    `has-separator'
          The dialog has a separator bar above its buttons



 -- Signal on <gtk-dialog>: response (arg0 `<gint>')
     Emitted when an action widget is clicked, the dialog receives a
     delete event, or the application programmer calls
     `gtk-dialog-response'. On a delete event, the response ID is
     `<gtk-response-none>'. Otherwise, it depends on which action
     widget was clicked.


 -- Signal on <gtk-dialog>: close

 -- Function: gtk-dialog-run (self `<gtk-dialog>') =>  (ret `int')
 -- Method: run
     Blocks in a recursive main loop until the DIALOG either emits the
     response signal, or is destroyed. If the dialog is destroyed
     during the call to `gtk-dialog-run', gtk_dialog_returns
     `<gtk-response-none>'. Otherwise, it returns the response ID from
     the "response" signal emission. Before entering the recursive main
     loop, `gtk-dialog-run' calls `gtk-widget-show' on the dialog for
     you. Note that you still need to show any children of the dialog
     yourself.

     During `gtk-dialog-run', the default behavior of "delete_event" is
     disabled; if the dialog receives "delete_event", it will not be
     destroyed as windows usually are, and `gtk-dialog-run' will return
     `<gtk-response-delete-event>'. Also, during `gtk-dialog-run' the
     dialog will be modal. You can force `gtk-dialog-run' to return at
     any time by calling `gtk-dialog-response' to emit the "response"
     signal. Destroying the dialog during `gtk-dialog-run' is a very
     bad idea, because your post-run code won't know whether the dialog
     was destroyed or not.

     After `gtk-dialog-run' returns, you are responsible for hiding or
     destroying the dialog if you wish to do so.

     Typical usage of this function might be:


            gint result = gtk_dialog_run (GTK_DIALOG (dialog));
            switch (result)
              {
                case GTK_RESPONSE_ACCEPT:
                   do_application_specific_something ();
                   break;
                default:
                   do_nothing_since_dialog_was_cancelled ();
                   break;
              }
            gtk_widget_destroy (dialog);

     Note that even though the recursive main loop gives the effect of
     a modal dialog (it prevents the user from interacting with other
     windows in the same window group while the dialog is run),
     callbacks such as timeouts, IO channel watches, DND drops, etc,
     _will_ be triggered during a `gtk-dialog-run' call.

    DIALOG
          a `<gtk-dialog>'

    RET
          response ID



 -- Function: gtk-dialog-response (self `<gtk-dialog>')
          (response_id `int')
 -- Method: response
     Emits the "response" signal with the given response ID. Used to
     indicate that the user has responded to the dialog in some way;
     typically either you or `gtk-dialog-run' will be monitoring the
     "response" signal and take appropriate action.

    DIALOG
          a `<gtk-dialog>'

    RESPONSE-ID
          response ID



 -- Function: gtk-dialog-add-button (self `<gtk-dialog>')
          (button_text `mchars') (response_id `int') => 
          (ret `<gtk-widget>')
 -- Method: add-button
     Adds a button with the given text (or a stock button, if
     BUTTON-TEXT is a stock ID) and sets things up so that clicking the
     button will emit the "response" signal with the given RESPONSE-ID.
     The button is appended to the end of the dialog's action area. The
     button widget is returned, but usually you don't need it.

    DIALOG
          a `<gtk-dialog>'

    BUTTON-TEXT
          text of button, or stock ID

    RESPONSE-ID
          response ID for the button

    RET
          the button widget that was added



 -- Function: gtk-dialog-add-action-widget (self `<gtk-dialog>')
          (child `<gtk-widget>') (response_id `int')
 -- Method: add-action-widget
     Adds an activatable widget to the action area of a `<gtk-dialog>',
     connecting a signal handler that will emit the "response" signal
     on the dialog when the widget is activated. The widget is appended
     to the end of the dialog's action area. If you want to add a
     non-activatable widget, simply pack it into the `action_area'
     field of the `<gtk-dialog>' struct.

    DIALOG
          a `<gtk-dialog>'

    CHILD
          an activatable widget

    RESPONSE-ID
          response ID for CHILD



 -- Function: gtk-dialog-get-has-separator (self `<gtk-dialog>') => 
          (ret `bool')
 -- Method: get-has-separator
     Accessor for whether the dialog has a separator.

    DIALOG
          a `<gtk-dialog>'

    RET
          ``#t'' if the dialog has a separator



 -- Function: gtk-dialog-set-default-response (self `<gtk-dialog>')
          (response_id `int')
 -- Method: set-default-response
     Sets the last widget in the dialog's action area with the given
     RESPONSE-ID as the default widget for the dialog. Pressing "Enter"
     normally activates the default widget.

    DIALOG
          a `<gtk-dialog>'

    RESPONSE-ID
          a response ID



 -- Function: gtk-dialog-set-has-separator (self `<gtk-dialog>')
          (setting `bool')
 -- Method: set-has-separator
     Sets whether the dialog has a separator above the buttons. ``#t''
     by default.

    DIALOG
          a `<gtk-dialog>'

    SETTING
          ``#t'' to have a separator



 -- Function: gtk-dialog-set-response-sensitive (self `<gtk-dialog>')
          (response_id `int') (setting `bool')
 -- Method: set-response-sensitive
     Calls `gtk_widget_set_sensitive (widget, SETTING)' for each widget
     in the dialog's action area with the given RESPONSE-ID. A
     convenient way to sensitize/desensitize dialog buttons.

    DIALOG
          a `<gtk-dialog>'

    RESPONSE-ID
          a response ID

    SETTING
          ``#t'' for sensitive



 -- Function: gtk-dialog-get-response-for-widget (self `<gtk-dialog>')
          (widget `<gtk-widget>') =>  (ret `int')
 -- Method: get-response-for-widget
     Gets the response id of a widget in the action area of a dialog.

    DIALOG
          a `<gtk-dialog>'

    WIDGET
          a widget in the action area of DIALOG

    RET
          the response id of WIDGET, or `GTK_RESPONSE_NONE' if WIDGET
          doesn't have a response id set.


     Since 2.8


 -- Function: gtk-alternative-dialog-button-order
          (screen `<gdk-screen>') =>  (ret `bool')
     Returns ``#t'' if dialogs are expected to use an alternative button
     order on the screen SCREEN. See
     `gtk-dialog-set-alternative-button-order' for more details about
     alternative button order.

     If you need to use this function, you should probably connect to
     the ::notify:gtk-alternative-button-order signal on the
     `<gtk-settings>' object associated to SCREEN, in order to be
     notified if the button order setting changes.

    SCREEN
          a `<gdk-screen>', or ``#f'' to use the default screen

    RET
          Whether the alternative button order should be used


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkInvisible,  Next: GtkMessageDialog,  Prev: GtkDialog,  Up: Top

3 GtkInvisible
**************

A widget which is not displayed

3.1 Overview
============

The `<gtk-invisible>' widget is used internally in GTK+, and is probably
not very useful for application developers.

   It is used for reliable pointer grabs and selection handling in the
code for drag-and-drop.

3.2 Usage
=========

 -- Class: <gtk-invisible>
     Derives from `<gtk-widget>'.

     This class defines the following properties:

    `screen'
          The screen where this window will be displayed



 -- Function: gtk-invisible-new =>  (ret `<gtk-widget>')
     Creates a new `<gtk-invisible>'.

    RET
          a new `<gtk-invisible>'.



 -- Function: gtk-invisible-new-for-screen (screen `<gdk-screen>') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-invisible>' object for a specified screen

    SCREEN
          a `<gdk-screen>' which identifies on which the new
          `<gtk-invisible>' will be created.

    RET
          a newly created `<gtk-invisible>' object


     Since 2.2


 -- Function: gtk-invisible-set-screen (self `<gtk-invisible>')
          (screen `<gdk-screen>')
 -- Method: set-screen
     Sets the `<gdk-screen>' where the `<gtk-invisible>' object will be
     displayed.

    INVISIBLE
          a `<gtk-invisible>'.

    SCREEN
          a `<gdk-screen>'.


     Since 2.2


 -- Function: gtk-invisible-get-screen (self `<gtk-invisible>') => 
          (ret `<gdk-screen>')
 -- Method: get-screen
     Returns the `<gdk-screen>' object associated with INVISIBLE

    INVISIBLE
          a `<gtk-invisible>'.

    RET
          the associated `<gdk-screen>'.


     Since 2.2



File: guile-gnome-gtk.info,  Node: GtkMessageDialog,  Next: GtkWindow,  Prev: GtkInvisible,  Up: Top

4 GtkMessageDialog
******************

A convenient message window

4.1 Overview
============

`<gtk-message-dialog>' presents a dialog with an image representing the
type of message (Error, Question, etc.) alongside some message text.
It's simply a convenience widget; you could construct the equivalent of
`<gtk-message-dialog>' from `<gtk-dialog>' without too much effort, but
`<gtk-message-dialog>' saves typing.

   The easiest way to do a modal message dialog is to use
`gtk-dialog-run', though you can also pass in the `GTK_DIALOG_MODAL'
flag, `gtk-dialog-run' automatically makes the dialog modal and waits
for the user to respond to it. `gtk-dialog-run' returns when any dialog
button is clicked.


      dialog = gtk_message_dialog_new (main_application_window,
                                       GTK_DIALOG_DESTROY_WITH_PARENT,
                                       GTK_MESSAGE_ERROR,
                                       GTK_BUTTONS_CLOSE,
                                       "Error loading file '%s': %s",
                                       filename, g_strerror (errno));
      gtk_dialog_run (GTK_DIALOG (dialog));
      gtk_widget_destroy (dialog);

   You might do a non-modal `<gtk-message-dialog>' as follows:


      dialog = gtk_message_dialog_new (main_application_window,
                                       GTK_DIALOG_DESTROY_WITH_PARENT,
                                       GTK_MESSAGE_ERROR,
                                       GTK_BUTTONS_CLOSE,
                                       "Error loading file '%s': %s",
                                       filename, g_strerror (errno));

      /* Destroy the dialog when the user responds to it (e.g. clicks a button) */
      g_signal_connect_swapped (dialog, "response",
                                G_CALLBACK (gtk_widget_destroy),
                                dialog);

4.2 Usage
=========

 -- Class: <gtk-message-dialog>
     Derives from `<gtk-dialog>'.

     This class defines the following properties:

    `message-type'
          The type of message

    `buttons'
          The buttons shown in the message dialog

    `text'
          The primary text of the message dialog

    `use-markup'
          The primary text of the title includes Pango markup.

    `secondary-text'
          The secondary text of the message dialog

    `secondary-use-markup'
          The secondary text includes Pango markup.

    `image'
          The image



 -- Function: gtk-message-dialog-set-markup
          (self `<gtk-message-dialog>') (str `mchars')
 -- Method: set-markup
     Sets the text of the message dialog to be STR, which is marked up
     with the Pango text markup language.

    MESSAGE-DIALOG
          a `<gtk-message-dialog>'

    STR
          markup string (see Pango markup format)


     Since 2.4


 -- Function: gtk-message-dialog-set-image
          (self `<gtk-message-dialog>') (image `<gtk-widget>')
 -- Method: set-image
     Sets the dialog's image to IMAGE.

    DIALOG
          a `<gtk-message-dialog>'

    IMAGE
          the image


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkWindow,  Next: GtkWindowGroup,  Prev: GtkMessageDialog,  Up: Top

5 GtkWindow
***********

Toplevel which can contain other widgets

5.1 Overview
============

5.2 Usage
=========

 -- Class: <gtk-window>
     Derives from `<gtk-bin>'.

     This class defines the following properties:

    `type'
          The type of the window

    `title'
          The title of the window

    `startup-id'
          Unique startup identifier for the window used by
          startup-notification

    `role'
          Unique identifier for the window to be used when restoring a
          session

    `allow-shrink'
          If TRUE, the window has no mimimum size. Setting this to TRUE
          is 99% of the time a bad idea

    `allow-grow'
          If TRUE, users can expand the window beyond its minimum size

    `resizable'
          If TRUE, users can resize the window

    `modal'
          If TRUE, the window is modal (other windows are not usable
          while this one is up)

    `window-position'
          The initial position of the window

    `default-width'
          The default width of the window, used when initially showing
          the window

    `default-height'
          The default height of the window, used when initially showing
          the window

    `destroy-with-parent'
          If this window should be destroyed when the parent is
          destroyed

    `icon'
          Icon for this window

    `icon-name'
          Name of the themed icon for this window

    `screen'
          The screen where this window will be displayed

    `type-hint'
          Hint to help the desktop environment understand what kind of
          window this is and how to treat it.

    `skip-taskbar-hint'
          TRUE if the window should not be in the task bar.

    `skip-pager-hint'
          TRUE if the window should not be in the pager.

    `urgency-hint'
          TRUE if the window should be brought to the user's attention.

    `accept-focus'
          TRUE if the window should receive the input focus.

    `focus-on-map'
          TRUE if the window should receive the input focus when mapped.

    `decorated'
          Whether the window should be decorated by the window manager

    `deletable'
          Whether the window frame should have a close button

    `gravity'
          The window gravity of the window

    `transient-for'
          The transient parent of the dialog

    `opacity'
          The opacity of the window, from 0 to 1

    `is-active'
          Whether the toplevel is the current active window

    `has-toplevel-focus'
          Whether the input focus is within this GtkWindow



 -- Signal on <gtk-window>: set-focus (arg0 `<gtk-widget>')

 -- Signal on <gtk-window>: frame-event (arg0 `<gdk-event>')
          => `<gboolean>'

 -- Signal on <gtk-window>: activate-focus

 -- Signal on <gtk-window>: activate-default

 -- Signal on <gtk-window>: keys-changed

 -- Function: gtk-window-new (type `<gtk-window-type>') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-window>', which is a toplevel window that can
     contain other widgets. Nearly always, the type of the window
     should be `<gtk-window-toplevel>'. If you're implementing
     something like a popup menu from scratch (which is a bad idea,
     just use `<gtk-menu>'), you might use `<gtk-window-popup>'.
     `<gtk-window-popup>' is not for dialogs, though in some other
     toolkits dialogs are called "popups". In GTK+,
     `<gtk-window-popup>' means a pop-up menu or pop-up tooltip. On
     X11, popup windows are not controlled by the window manager.

     If you simply want an undecorated window (no window borders), use
     `gtk-window-set-decorated', don't use `<gtk-window-popup>'.

    TYPE
          type of window

    RET
          a new `<gtk-window>'.



 -- Function: gtk-window-set-title (self `<gtk-window>')
          (title `mchars')
 -- Method: set-title
     Sets the title of the `<gtk-window>'. The title of a window will be
     displayed in its title bar; on the X Window System, the title bar
     is rendered by the window manager, so exactly how the title
     appears to users may vary according to a user's exact
     configuration. The title should help a user distinguish this
     window from other windows they may have open. A good title might
     include the application name and current document filename, for
     example.

    WINDOW
          a `<gtk-window>'

    TITLE
          title of the window



 -- Function: gtk-window-set-wmclass (self `<gtk-window>')
          (wmclass_name `mchars') (wmclass_class `mchars')
 -- Method: set-wmclass
     Don't use this function. It sets the X Window System "class" and
     "name" hints for a window. According to the ICCCM, you should
     always set these to the same value for all windows in an
     application, and GTK+ sets them to that value by default, so
     calling this function is sort of pointless. However, you may want
     to call `gtk-window-set-role' on each window in your application,
     for the benefit of the session manager. Setting the role allows
     the window manager to restore window positions when loading a
     saved session.

    WINDOW
          a `<gtk-window>'

    WMCLASS-NAME
          window name hint

    WMCLASS-CLASS
          window class hint



 -- Function: gtk-window-set-resizable (self `<gtk-window>')
          (resizable `bool')
 -- Method: set-resizable
     Sets whether the user can resize a window. Windows are user
     resizable by default.

    WINDOW
          a `<gtk-window>'

    RESIZABLE
          ``#t'' if the user can resize this window



 -- Function: gtk-window-get-resizable (self `<gtk-window>') => 
          (ret `bool')
 -- Method: get-resizable
     Gets the value set by `gtk-window-set-resizable'.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if the user can resize the window



 -- Function: gtk-window-add-accel-group (self `<gtk-window>')
          (accel_group `<gtk-accel-group>')
 -- Method: add-accel-group
     Associate ACCEL-GROUP with WINDOW, such that calling
     `gtk-accel-groups-activate' on WINDOW will activate accelerators in
     ACCEL-GROUP.

    WINDOW
          window to attach accelerator group to

    ACCEL-GROUP
          a `<gtk-accel-group>'



 -- Function: gtk-window-remove-accel-group (self `<gtk-window>')
          (accel_group `<gtk-accel-group>')
 -- Method: remove-accel-group
     Reverses the effects of `gtk-window-add-accel-group'.

    WINDOW
          a `<gtk-window>'

    ACCEL-GROUP
          a `<gtk-accel-group>'



 -- Function: gtk-window-activate-focus (self `<gtk-window>') => 
          (ret `bool')
 -- Method: activate-focus
     Activates the current focused widget within the window.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if a widget got activated.



 -- Function: gtk-window-activate-default (self `<gtk-window>') => 
          (ret `bool')
 -- Method: activate-default
     Activates the default widget for the window, unless the current
     focused widget has been configured to receive the default action
     (see `<gtk-receives-default>' in `<gtk-widget-flags>'), in which
     case the focused widget is activated.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if a widget got activated.



 -- Function: gtk-window-set-modal (self `<gtk-window>') (modal `bool')
 -- Method: set-modal
     Sets a window modal or non-modal. Modal windows prevent
     interaction with other windows in the same application. To keep
     modal dialogs on top of main application windows, use
     `gtk-window-set-transient-for' to make the dialog transient for
     the parent; most window managers will then disallow lowering the
     dialog below the parent.

    WINDOW
          a `<gtk-window>'

    MODAL
          whether the window is modal



 -- Function: gtk-window-set-default-size (self `<gtk-window>')
          (width `int') (height `int')
 -- Method: set-default-size
     Sets the default size of a window. If the window's "natural" size
     (its size request) is larger than the default, the default will be
     ignored. More generally, if the default size does not obey the
     geometry hints for the window (`gtk-window-set-geometry-hints' can
     be used to set these explicitly), the default size will be clamped
     to the nearest permitted size.

     Unlike `gtk-widget-set-size-request', which sets a size request
     for a widget and thus would keep users from shrinking the window,
     this function only sets the initial size, just as if the user had
     resized the window themselves.  Users can still shrink the window
     again as they normally would. Setting a default size of -1 means
     to use the "natural" default size (the size request of the window).

     For more control over a window's initial size and how resizing
     works, investigate `gtk-window-set-geometry-hints'.

     For some uses, `gtk-window-resize' is a more appropriate function.
     `gtk-window-resize' changes the current size of the window, rather
     than the size to be used on initial display. `gtk-window-resize'
     always affects the window itself, not the geometry widget.

     The default size of a window only affects the first time a window
     is shown; if a window is hidden and re-shown, it will remember the
     size it had prior to hiding, rather than using the default size.

     Windows can't actually be 0x0 in size, they must be at least 1x1,
     but passing 0 for WIDTH and HEIGHT is OK, resulting in a 1x1
     default size.

    WINDOW
          a `<gtk-window>'

    WIDTH
          width in pixels, or -1 to unset the default width

    HEIGHT
          height in pixels, or -1 to unset the default height



 -- Function: gtk-window-set-gravity (self `<gtk-window>')
          (gravity `<gdk-gravity>')
 -- Method: set-gravity
     Window gravity defines the meaning of coordinates passed to
     `gtk-window-move'. See `gtk-window-move' and `<gdk-gravity>' for
     more details.

     The default window gravity is `<gdk-gravity-north-west>' which will
     typically "do what you mean."

    WINDOW
          a `<gtk-window>'

    GRAVITY
          window gravity



 -- Function: gtk-window-get-gravity (self `<gtk-window>') => 
          (ret `<gdk-gravity>')
 -- Method: get-gravity
     Gets the value set by `gtk-window-set-gravity'.

    WINDOW
          a `<gtk-window>'

    RET
          window gravity



 -- Function: gtk-window-set-position (self `<gtk-window>')
          (position `<gtk-window-position>')
 -- Method: set-position
     Sets a position constraint for this window. If the old or new
     constraint is `GTK_WIN_POS_CENTER_ALWAYS', this will also cause
     the window to be repositioned to satisfy the new constraint.

    WINDOW
          a `<gtk-window>'.

    POSITION
          a position constraint.



 -- Function: gtk-window-set-transient-for (self `<gtk-window>')
          (parent `<gtk-window>')
 -- Method: set-transient-for
     Dialog windows should be set transient for the main application
     window they were spawned from. This allows window managers to e.g.
     keep the dialog on top of the main window, or center the dialog
     over the main window.  `gtk-dialog-new-with-buttons' and other
     convenience functions in GTK+ will sometimes call
     `gtk-window-set-transient-for' on your behalf.

     On Windows, this function will and put the child window on top of
     the parent, much as the window manager would have done on X.

    WINDOW
          a `<gtk-window>'

    PARENT
          parent window



 -- Function: gtk-window-set-destroy-with-parent (self `<gtk-window>')
          (setting `bool')
 -- Method: set-destroy-with-parent
     If SETTING is ``#t'', then destroying the transient parent of
     WINDOW will also destroy WINDOW itself. This is useful for dialogs
     that shouldn't persist beyond the lifetime of the main window
     they're associated with, for example.

    WINDOW
          a `<gtk-window>'

    SETTING
          whether to destroy WINDOW with its transient parent



 -- Function: gtk-window-set-screen (self `<gtk-window>')
          (screen `<gdk-screen>')
 -- Method: set-screen
     Sets the `<gdk-screen>' where the WINDOW is displayed; if the
     window is already mapped, it will be unmapped, and then remapped
     on the new screen.

    WINDOW
          a `<gtk-window>'.

    SCREEN
          a `<gdk-screen>'.


     Since 2.2


 -- Function: gtk-window-get-screen (self `<gtk-window>') => 
          (ret `<gdk-screen>')
 -- Method: get-screen
     Returns the `<gdk-screen>' associated with WINDOW.

    WINDOW
          a `<gtk-window>'.

    RET
          a `<gdk-screen>'.


     Since 2.2


 -- Function: gtk-window-is-active (self `<gtk-window>') => 
          (ret `bool')
 -- Method: is-active
     Returns whether the window is part of the current active toplevel.
     (That is, the toplevel window receiving keystrokes.) The return
     value is ``#t'' if the window is active toplevel itself, but also
     if it is, say, a `<gtk-plug>' embedded in the active toplevel. You
     might use this function if you wanted to draw a widget differently
     in an active window from a widget in an inactive window. See
     `gtk-window-has-toplevel-focus'

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if the window part of the current active window.


     Since 2.4


 -- Function: gtk-window-has-toplevel-focus (self `<gtk-window>') => 
          (ret `bool')
 -- Method: has-toplevel-focus
     Returns whether the input focus is within this GtkWindow. For real
     toplevel windows, this is identical to `gtk-window-is-active', but
     for embedded windows, like `<gtk-plug>', the results will differ.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if the input focus is within this GtkWindow


     Since 2.4


 -- Function: gtk-window-list-toplevels =>  (ret `glist-of')
     Returns a list of all existing toplevel windows. The widgets in
     the list are not individually referenced. If you want to iterate
     through the list and perform actions involving callbacks that
     might destroy the widgets, you _must_ call `g_list_foreach
     (result, (GFunc)g_object_ref, NULL)' first, and then unref all the
     widgets afterwards.

    RET
          list of toplevel widgets



 -- Function: gtk-window-add-mnemonic (self `<gtk-window>')
          (keyval `unsigned-int') (target `<gtk-widget>')
 -- Method: add-mnemonic
     Adds a mnemonic to this window.

    WINDOW
          a `<gtk-window>'

    KEYVAL
          the mnemonic

    TARGET
          the widget that gets activated by the mnemonic



 -- Function: gtk-window-remove-mnemonic (self `<gtk-window>')
          (keyval `unsigned-int') (target `<gtk-widget>')
 -- Method: remove-mnemonic
     Removes a mnemonic from this window.

    WINDOW
          a `<gtk-window>'

    KEYVAL
          the mnemonic

    TARGET
          the widget that gets activated by the mnemonic



 -- Function: gtk-window-mnemonic-activate (self `<gtk-window>')
          (keyval `unsigned-int') (modifier `<gdk-modifier-type>') => 
          (ret `bool')
 -- Method: mnemonic-activate
     Activates the targets associated with the mnemonic.

    WINDOW
          a `<gtk-window>'

    KEYVAL
          the mnemonic

    MODIFIER
          the modifiers

    RET
          ``#t'' if the activation is done.



 -- Function: gtk-window-activate-key (self `<gtk-window>')
          (event `<gdk-event-key>') =>  (ret `bool')
 -- Method: activate-key
     Activates mnemonics and accelerators for this `<gtk-window>'. This
     is normally called by the default ::key_press_event handler for
     toplevel windows, however in some cases it may be useful to call
     this directly when overriding the standard key handling for a
     toplevel window.

    WINDOW
          a `<gtk-window>'

    EVENT
          a `<gdk-event-key>'

    RET
          ``#t'' if a mnemonic or accelerator was found and activated.



 -- Function: gtk-window-propagate-key-event (self `<gtk-window>')
          (event `<gdk-event-key>') =>  (ret `bool')
 -- Method: propagate-key-event
     Propagate a key press or release event to the focus widget and up
     the focus container chain until a widget handles EVENT. This is
     normally called by the default ::key_press_event and
     ::key_release_event handlers for toplevel windows, however in some
     cases it may be useful to call this directly when overriding the
     standard key handling for a toplevel window.

    WINDOW
          a `<gtk-window>'

    EVENT
          a `<gdk-event-key>'

    RET
          ``#t'' if a widget in the focus chain handled the event.



 -- Function: gtk-window-get-focus (self `<gtk-window>') => 
          (ret `<gtk-widget>')
 -- Method: get-focus
     Retrieves the current focused widget within the window. Note that
     this is the widget that would have the focus if the toplevel
     window focused; if the toplevel window is not focused then
     `GTK_WIDGET_HAS_FOCUS (widget)' will not be ``#t'' for the widget.

    WINDOW
          a `<gtk-window>'

    RET
          the currently focused widget, or ``#f'' if there is none.



 -- Function: gtk-window-set-focus (self `<gtk-window>')
          (focus `<gtk-widget>')
 -- Method: set-focus
     If FOCUS is not the current focus widget, and is focusable, sets
     it as the focus widget for the window. If FOCUS is ``#f'', unsets
     the focus widget for this window. To set the focus to a particular
     widget in the toplevel, it is usually more convenient to use
     `gtk-widget-grab-focus' instead of this function.

    WINDOW
          a `<gtk-window>'

    FOCUS
          widget to be the new focus widget, or ``#f'' to unset any
          focus widget for the toplevel window.



 -- Function: gtk-window-set-default (self `<gtk-window>')
          (default_widget `<gtk-widget>')
 -- Method: set-default
     The default widget is the widget that's activated when the user
     presses Enter in a dialog (for example). This function sets or
     unsets the default widget for a `<gtk-window>' about. When setting
     (rather than unsetting) the default widget it's generally easier
     to call `gtk-widget-grab-focus' on the widget.  Before making a
     widget the default widget, you must set the `<gtk-can-default>'
     flag on the widget you'd like to make the default using
     `gtk-widget-set-flags'.

    WINDOW
          a `<gtk-window>'

    DEFAULT-WIDGET
          widget to be the default, or ``#f'' to unset the default
          widget for the toplevel.



 -- Function: gtk-window-present (self `<gtk-window>')
 -- Method: present
     Presents a window to the user. This may mean raising the window in
     the stacking order, deiconifying it, moving it to the current
     desktop, and/or giving it the keyboard focus, possibly dependent
     on the user's platform, window manager, and preferences.

     If WINDOW is hidden, this function calls `gtk-widget-show' as well.

     This function should be used when the user tries to open a window
     that's already open. Say for example the preferences dialog is
     currently open, and the user chooses Preferences from the menu a
     second time; use `gtk-window-present' to move the already-open
     dialog where the user can see it.

     If you are calling this function in response to a user
     interaction, it is preferable to use
     `gtk-window-present-with-time'.

    WINDOW
          a `<gtk-window>'



 -- Function: gtk-window-present-with-time (self `<gtk-window>')
          (timestamp `unsigned-int32')
 -- Method: present-with-time
     Presents a window to the user in response to a user interaction.
     If you need to present a window without a timestamp, use
     `gtk-window-present'. See `gtk-window-present' for details.

    WINDOW
          a `<gtk-window>'

    TIMESTAMP
          the timestamp of the user interaction (typically a button or
          key press event) which triggered this call


     Since 2.8


 -- Function: gtk-window-iconify (self `<gtk-window>')
 -- Method: iconify
     Asks to iconify (i.e. minimize) the specified WINDOW. Note that you
     shouldn't assume the window is definitely iconified afterward,
     because other entities (e.g. the user or window manager) could
     deiconify it again, or there may not be a window manager in which
     case iconification isn't possible, etc. But normally the window
     will end up iconified. Just don't write code that crashes if not.

     It's permitted to call this function before showing a window, in
     which case the window will be iconified before it ever appears
     onscreen.

     You can track iconification via the "window_state_event" signal on
     `<gtk-widget>'.

    WINDOW
          a `<gtk-window>'



 -- Function: gtk-window-deiconify (self `<gtk-window>')
 -- Method: deiconify
     Asks to deiconify (i.e. unminimize) the specified WINDOW. Note
     that you shouldn't assume the window is definitely deiconified
     afterward, because other entities (e.g. the user or window
     manager) could iconify it again before your code which assumes
     deiconification gets to run.

     You can track iconification via the "window_state_event" signal on
     `<gtk-widget>'.

    WINDOW
          a `<gtk-window>'



 -- Function: gtk-window-stick (self `<gtk-window>')
 -- Method: stick
     Asks to stick WINDOW, which means that it will appear on all user
     desktops. Note that you shouldn't assume the window is definitely
     stuck afterward, because other entities (e.g. the user or window
     manager) could unstick it again, and some window managers do not
     support sticking windows. But normally the window will end up
     stuck. Just don't write code that crashes if not.

     It's permitted to call this function before showing a window.

     You can track stickiness via the "window_state_event" signal on
     `<gtk-widget>'.

    WINDOW
          a `<gtk-window>'



 -- Function: gtk-window-unstick (self `<gtk-window>')
 -- Method: unstick
     Asks to unstick WINDOW, which means that it will appear on only
     one of the user's desktops. Note that you shouldn't assume the
     window is definitely unstuck afterward, because other entities
     (e.g. the user or window manager) could stick it again. But
     normally the window will end up stuck. Just don't write code that
     crashes if not.

     You can track stickiness via the "window_state_event" signal on
     `<gtk-widget>'.

    WINDOW
          a `<gtk-window>'



 -- Function: gtk-window-maximize (self `<gtk-window>')
 -- Method: maximize
     Asks to maximize WINDOW, so that it becomes full-screen. Note that
     you shouldn't assume the window is definitely maximized afterward,
     because other entities (e.g. the user or window manager) could
     unmaximize it again, and not all window managers support
     maximization. But normally the window will end up maximized. Just
     don't write code that crashes if not.

     It's permitted to call this function before showing a window, in
     which case the window will be maximized when it appears onscreen
     initially.

     You can track maximization via the "window_state_event" signal on
     `<gtk-widget>'.

    WINDOW
          a `<gtk-window>'



 -- Function: gtk-window-unmaximize (self `<gtk-window>')
 -- Method: unmaximize
     Asks to unmaximize WINDOW. Note that you shouldn't assume the
     window is definitely unmaximized afterward, because other entities
     (e.g. the user or window manager) could maximize it again, and not
     all window managers honor requests to unmaximize. But normally the
     window will end up unmaximized. Just don't write code that crashes
     if not.

     You can track maximization via the "window_state_event" signal on
     `<gtk-widget>'.

    WINDOW
          a `<gtk-window>'



 -- Function: gtk-window-fullscreen (self `<gtk-window>')
 -- Method: fullscreen
     Asks to place WINDOW in the fullscreen state. Note that you
     shouldn't assume the window is definitely full screen afterward,
     because other entities (e.g. the user or window manager) could
     unfullscreen it again, and not all window managers honor requests
     to fullscreen windows. But normally the window will end up
     fullscreen. Just don't write code that crashes if not.

     You can track the fullscreen state via the "window_state_event"
     signal on `<gtk-widget>'.

    WINDOW
          a `<gtk-window>'


     Since 2.2


 -- Function: gtk-window-unfullscreen (self `<gtk-window>')
 -- Method: unfullscreen
     Asks to toggle off the fullscreen state for WINDOW. Note that you
     shouldn't assume the window is definitely not full screen
     afterward, because other entities (e.g. the user or window
     manager) could fullscreen it again, and not all window managers
     honor requests to unfullscreen windows. But normally the window
     will end up restored to its normal state. Just don't write code
     that crashes if not.

     You can track the fullscreen state via the "window_state_event"
     signal on `<gtk-widget>'.

    WINDOW
          a `<gtk-window>'


     Since 2.2


 -- Function: gtk-window-set-keep-above (self `<gtk-window>')
          (setting `bool')
 -- Method: set-keep-above
     Asks to keep WINDOW above, so that it stays on top. Note that you
     shouldn't assume the window is definitely above afterward, because
     other entities (e.g. the user or window manager) could not keep it
     above, and not all window managers support keeping windows above.
     But normally the window will end kept above. Just don't write code
     that crashes if not.

     It's permitted to call this function before showing a window, in
     which case the window will be kept above when it appears onscreen
     initially.

     You can track the above state via the "window_state_event" signal
     on `<gtk-widget>'.

     Note that, according to the Extended Window Manager Hints
     (http://www.freedesktop.org/Standards/wm-spec) specification, the
     above state is mainly meant for user preferences and should not be
     used by applications e.g. for drawing attention to their dialogs.

    WINDOW
          a `<gtk-window>'

    SETTING
          whether to keep WINDOW above other windows


     Since 2.4


 -- Function: gtk-window-set-keep-below (self `<gtk-window>')
          (setting `bool')
 -- Method: set-keep-below
     Asks to keep WINDOW below, so that it stays in bottom. Note that
     you shouldn't assume the window is definitely below afterward,
     because other entities (e.g. the user or window manager) could not
     keep it below, and not all window managers support putting windows
     below. But normally the window will be kept below. Just don't
     write code that crashes if not.

     It's permitted to call this function before showing a window, in
     which case the window will be kept below when it appears onscreen
     initially.

     You can track the below state via the "window_state_event" signal
     on `<gtk-widget>'.

     Note that, according to the Extended Window Manager Hints
     (http://www.freedesktop.org/Standards/wm-spec) specification, the
     above state is mainly meant for user preferences and should not be
     used by applications e.g. for drawing attention to their dialogs.

    WINDOW
          a `<gtk-window>'

    SETTING
          whether to keep WINDOW below other windows


     Since 2.4


 -- Function: gtk-window-begin-resize-drag (self `<gtk-window>')
          (edge `<gdk-window-edge>') (button `int') (root_x `int')
          (root_y `int') (timestamp `unsigned-int32')
 -- Method: begin-resize-drag
     Starts resizing a window. This function is used if an application
     has window resizing controls. When GDK can support it, the resize
     will be done using the standard mechanism for the window manager
     or windowing system. Otherwise, GDK will try to emulate window
     resizing, potentially not all that well, depending on the
     windowing system.

    WINDOW
          a `<gtk-window>'

    EDGE
          position of the resize control

    BUTTON
          mouse button that initiated the drag

    ROOT-X
          X position where the user clicked to initiate the drag, in
          root window coordinates

    ROOT-Y
          Y position where the user clicked to initiate the drag

    TIMESTAMP
          timestamp from the click event that initiated the drag



 -- Function: gtk-window-begin-move-drag (self `<gtk-window>')
          (button `int') (root_x `int') (root_y `int')
          (timestamp `unsigned-int32')
 -- Method: begin-move-drag
     Starts moving a window. This function is used if an application
     has window movement grips. When GDK can support it, the window
     movement will be done using the standard mechanism for the window
     manager or windowing system. Otherwise, GDK will try to emulate
     window movement, potentially not all that well, depending on the
     windowing system.

    WINDOW
          a `<gtk-window>'

    BUTTON
          mouse button that initiated the drag

    ROOT-X
          X position where the user clicked to initiate the drag, in
          root window coordinates

    ROOT-Y
          Y position where the user clicked to initiate the drag

    TIMESTAMP
          timestamp from the click event that initiated the drag



 -- Function: gtk-window-set-decorated (self `<gtk-window>')
          (setting `bool')
 -- Method: set-decorated
     By default, windows are decorated with a title bar, resize
     controls, etc. Some window managers allow GTK+ to disable these
     decorations, creating a borderless window. If you set the
     decorated property to ``#f'' using this function, GTK+ will do its
     best to convince the window manager not to decorate the window.
     Depending on the system, this function may not have any effect when
     called on a window that is already visible, so you should call it
     before calling `gtk-window-show'.

     On Windows, this function always works, since there's no window
     manager policy involved.

    WINDOW
          a `<gtk-window>'

    SETTING
          ``#t'' to decorate the window



 -- Function: gtk-window-set-deletable (self `<gtk-window>')
          (setting `bool')
 -- Method: set-deletable
     By default, windows have a close button in the window frame. Some
     window managers allow GTK+ to disable this button. If you set the
     deletable property to ``#f'' using this function, GTK+ will do its
     best to convince the window manager not to show a close button.
     Depending on the system, this function may not have any effect
     when called on a window that is already visible, so you should
     call it before calling `gtk-window-show'.

     On Windows, this function always works, since there's no window
     manager policy involved.

    WINDOW
          a `<gtk-window>'

    SETTING
          ``#t'' to decorate the window as deletable


     Since 2.10


 -- Function: gtk-window-set-frame-dimensions (self `<gtk-window>')
          (left `int') (top `int') (right `int') (bottom `int')
 -- Method: set-frame-dimensions
     (Note: this is a special-purpose function intended for the
     framebuffer port; see `gtk-window-set-has-frame'. It will have no
     effect on the window border drawn by the window manager, which is
     the normal case when using the X Window system.)

     For windows with frames (see `gtk-window-set-has-frame') this
     function can be used to change the size of the frame border.

    WINDOW
          a `<gtk-window>' that has a frame

    LEFT
          The width of the left border

    TOP
          The height of the top border

    RIGHT
          The width of the right border

    BOTTOM
          The height of the bottom border



 -- Function: gtk-window-set-has-frame (self `<gtk-window>')
          (setting `bool')
 -- Method: set-has-frame
     (Note: this is a special-purpose function for the framebuffer
     port, that causes GTK+ to draw its own window border. For most
     applications, you want `gtk-window-set-decorated' instead, which
     tells the window manager whether to draw the window border.)

     If this function is called on a window with setting of ``#t'',
     before it is realized or showed, it will have a "frame" window
     around WINDOW->WINDOW, accessible in WINDOW->FRAME. Using the
     signal frame_event you can receive all events targeted at the
     frame.

     This function is used by the linux-fb port to implement managed
     windows, but it could conceivably be used by X-programs that want
     to do their own window decorations.

    WINDOW
          a `<gtk-window>'

    SETTING
          a boolean



 -- Function: gtk-window-set-mnemonic-modifier (self `<gtk-window>')
          (modifier `<gdk-modifier-type>')
 -- Method: set-mnemonic-modifier
     Sets the mnemonic modifier for this window.

    WINDOW
          a `<gtk-window>'

    MODIFIER
          the modifier mask used to activate mnemonics on this window.



 -- Function: gtk-window-set-role (self `<gtk-window>') (role `mchars')
 -- Method: set-role
     This function is only useful on X11, not with other GTK+ targets.

     In combination with the window title, the window role allows a
     window manager to identify "the same" window when an application
     is restarted. So for example you might set the "toolbox" role on
     your app's toolbox window, so that when the user restarts their
     session, the window manager can put the toolbox back in the same
     place.

     If a window already has a unique title, you don't need to set the
     role, since the WM can use the title to identify the window when
     restoring the session.

    WINDOW
          a `<gtk-window>'

    ROLE
          unique identifier for the window to be used when restoring a
          session



 -- Function: gtk-window-set-type-hint (self `<gtk-window>')
          (hint `<gdk-window-type-hint>')
 -- Method: set-type-hint
     By setting the type hint for the window, you allow the window
     manager to decorate and handle the window in a way which is
     suitable to the function of the window in your application.

     This function should be called before the window becomes visible.

     `gtk-dialog-new-with-buttons' and other convenience functions in
     GTK+ will sometimes call `gtk-window-set-type-hint' on your behalf.

    WINDOW
          a `<gtk-window>'

    HINT
          the window type



 -- Function: gtk-window-set-skip-taskbar-hint (self `<gtk-window>')
          (setting `bool')
 -- Method: set-skip-taskbar-hint
     Windows may set a hint asking the desktop environment not to
     display the window in the task bar. This function sets this hint.

    WINDOW
          a `<gtk-window>'

    SETTING
          ``#t'' to keep this window from appearing in the task bar


     Since 2.2


 -- Function: gtk-window-set-skip-pager-hint (self `<gtk-window>')
          (setting `bool')
 -- Method: set-skip-pager-hint
     Windows may set a hint asking the desktop environment not to
     display the window in the pager. This function sets this hint. (A
     "pager" is any desktop navigation tool such as a workspace
     switcher that displays a thumbnail representation of the windows
     on the screen.)

    WINDOW
          a `<gtk-window>'

    SETTING
          ``#t'' to keep this window from appearing in the pager


     Since 2.2


 -- Function: gtk-window-set-urgency-hint (self `<gtk-window>')
          (setting `bool')
 -- Method: set-urgency-hint
     Windows may set a hint asking the desktop environment to draw the
     users attention to the window. This function sets this hint.

    WINDOW
          a `<gtk-window>'

    SETTING
          ``#t'' to mark this window as urgent


     Since 2.8


 -- Function: gtk-window-set-accept-focus (self `<gtk-window>')
          (setting `bool')
 -- Method: set-accept-focus
     Windows may set a hint asking the desktop environment not to
     receive the input focus. This function sets this hint.

    WINDOW
          a `<gtk-window>'

    SETTING
          ``#t'' to let this window receive input focus


     Since 2.4


 -- Function: gtk-window-set-focus-on-map (self `<gtk-window>')
          (setting `bool')
 -- Method: set-focus-on-map
     Windows may set a hint asking the desktop environment not to
     receive the input focus when the window is mapped. This function
     sets this hint.

    WINDOW
          a `<gtk-window>'

    SETTING
          ``#t'' to let this window receive input focus on map


     Since 2.6


 -- Function: gtk-window-get-decorated (self `<gtk-window>') => 
          (ret `bool')
 -- Method: get-decorated
     Returns whether the window has been set to have decorations such
     as a title bar via `gtk-window-set-decorated'.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if the window has been set to have decorations



 -- Function: gtk-window-get-deletable (self `<gtk-window>') => 
          (ret `bool')
 -- Method: get-deletable
     Returns whether the window has been set to have a close button via
     `gtk-window-set-deletable'.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if the window has been set to have a close button


     Since 2.10


 -- Function: gtk-window-get-default-icon-list =>  (ret `glist-of')
     Gets the value set by `gtk-window-set-default-icon-list'. The list
     is a copy and should be freed with `g-list-free', but the pixbufs
     in the list have not had their reference count incremented.

    RET
          copy of default icon list



 -- Function: gtk-window-get-default-size (self `<gtk-window>') => 
          (width `int') (height `int')
 -- Method: get-default-size
     Gets the default size of the window. A value of -1 for the width
     or height indicates that a default size has not been explicitly
     set for that dimension, so the "natural" size of the window will
     be used.

    WINDOW
          a `<gtk-window>'

    WIDTH
          location to store the default width, or ``#f''

    HEIGHT
          location to store the default height, or ``#f''



 -- Function: gtk-window-get-destroy-with-parent (self `<gtk-window>')
          =>  (ret `bool')
 -- Method: get-destroy-with-parent
     Returns whether the window will be destroyed with its transient
     parent. See `gtk-window-set-destroy-with-parent'.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if the window will be destroyed with its transient
          parent.



 -- Function: gtk-window-get-frame-dimensions (self `<gtk-window>') => 
          (left `int') (top `int') (right `int') (bottom `int')
 -- Method: get-frame-dimensions
     (Note: this is a special-purpose function intended for the
     framebuffer port; see `gtk-window-set-has-frame'. It will not
     return the size of the window border drawn by the window manager,
     which is the normal case when using a windowing system. See
     `gdk-window-get-frame-extents' to get the standard window border
     extents.)

     Retrieves the dimensions of the frame window for this toplevel. See
     `gtk-window-set-has-frame', `gtk-window-set-frame-dimensions'.

    WINDOW
          a `<gtk-window>'

    LEFT
          location to store the width of the frame at the left, or
          ``#f''

    TOP
          location to store the height of the frame at the top, or
          ``#f''

    RIGHT
          location to store the width of the frame at the returns, or
          ``#f''

    BOTTOM
          location to store the height of the frame at the bottom, or
          ``#f''



 -- Function: gtk-window-get-has-frame (self `<gtk-window>') => 
          (ret `bool')
 -- Method: get-has-frame
     Accessor for whether the window has a frame window exterior to
     WINDOW->WINDOW. Gets the value set by `gtk-window-set-has-frame'.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if a frame has been added to the window via
          `gtk-window-set-has-frame'.



 -- Function: gtk-window-get-icon (self `<gtk-window>') => 
          (ret `<gdk-pixbuf>')
 -- Method: get-icon
     Gets the value set by `gtk-window-set-icon' (or if you've called
     `gtk-window-set-icon-list', gets the first icon in the icon list).

    WINDOW
          a `<gtk-window>'

    RET
          icon for window



 -- Function: gtk-window-get-icon-list (self `<gtk-window>') => 
          (ret `glist-of')
 -- Method: get-icon-list
     Retrieves the list of icons set by `gtk-window-set-icon-list'. The
     list is copied, but the reference count on each member won't be
     incremented.

    WINDOW
          a `<gtk-window>'

    RET
          copy of window's icon list



 -- Function: gtk-window-get-icon-name (self `<gtk-window>') => 
          (ret `mchars')
 -- Method: get-icon-name
     Returns the name of the themed icon for the window, see
     `gtk-window-set-icon-name'.

    WINDOW
          a `<gtk-window>'

    RET
          the icon name or ``#f'' if the window has no themed icon


     Since 2.6


 -- Function: gtk-window-get-mnemonic-modifier (self `<gtk-window>')
          =>  (ret `<gdk-modifier-type>')
 -- Method: get-mnemonic-modifier
     Returns the mnemonic modifier for this window. See
     `gtk-window-set-mnemonic-modifier'.

    WINDOW
          a `<gtk-window>'

    RET
          the modifier mask used to activate mnemonics on this window.



 -- Function: gtk-window-get-modal (self `<gtk-window>') => 
          (ret `bool')
 -- Method: get-modal
     Returns whether the window is modal. See `gtk-window-set-modal'.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if the window is set to be modal and establishes a
          grab when shown



 -- Function: gtk-window-get-position (self `<gtk-window>') => 
          (root_x `int') (root_y `int')
 -- Method: get-position
     This function returns the position you need to pass to
     `gtk-window-move' to keep WINDOW in its current position. This
     means that the meaning of the returned value varies with window
     gravity. See `gtk-window-move' for more details.

     If you haven't changed the window gravity, its gravity will be
     `<gdk-gravity-north-west>'. This means that
     `gtk-window-get-position' gets the position of the top-left corner
     of the window manager frame for the window. `gtk-window-move' sets
     the position of this same top-left corner.

     `gtk-window-get-position' is not 100% reliable because the X
     Window System does not specify a way to obtain the geometry of the
     decorations placed on a window by the window manager. Thus GTK+ is
     using a "best guess" that works with most window managers.

     Moreover, nearly all window managers are historically broken with
     respect to their handling of window gravity. So moving a window to
     its current position as returned by `gtk-window-get-position'
     tends to result in moving the window slightly. Window managers are
     slowly getting better over time.

     If a window has gravity `<gdk-gravity-static>' the window manager
     frame is not relevant, and thus `gtk-window-get-position' will
     always produce accurate results. However you can't use static
     gravity to do things like place a window in a corner of the
     screen, because static gravity ignores the window manager
     decorations.

     If you are saving and restoring your application's window
     positions, you should know that it's impossible for applications
     to do this without getting it somewhat wrong because applications
     do not have sufficient knowledge of window manager state. The
     Correct Mechanism is to support the session management protocol
     (see the "GnomeClient" object in the GNOME libraries for example)
     and allow the window manager to save your window sizes and
     positions.

    WINDOW
          a `<gtk-window>'

    ROOT-X
          return location for X coordinate of gravity-determined
          reference p\oint

    ROOT-Y
          return location for Y coordinate of gravity-determined
          reference p\oint



 -- Function: gtk-window-get-role (self `<gtk-window>') => 
          (ret `mchars')
 -- Method: get-role
     Returns the role of the window. See `gtk-window-set-role' for
     further explanation.

    WINDOW
          a `<gtk-window>'

    RET
          the role of the window if set, or ``#f''. The returned is
          owned by the widget and must not be modified or freed.



 -- Function: gtk-window-get-size (self `<gtk-window>') => 
          (width `int') (height `int')
 -- Method: get-size
     Obtains the current size of WINDOW. If WINDOW is not onscreen, it
     returns the size GTK+ will suggest to the window manager for the
     initial window size (but this is not reliably the same as the size
     the window manager will actually select). The size obtained by
     `gtk-window-get-size' is the last size received in a
     `<gdk-event-configure>', that is, GTK+ uses its locally-stored
     size, rather than querying the X server for the size. As a result,
     if you call `gtk-window-resize' then immediately call
     `gtk-window-get-size', the size won't have taken effect yet. After
     the window manager processes the resize request, GTK+ receives
     notification that the size has changed via a configure event, and
     the size of the window gets updated.

     Note 1: Nearly any use of this function creates a race condition,
     because the size of the window may change between the time that
     you get the size and the time that you perform some action
     assuming that size is the current size. To avoid race conditions,
     connect to "configure_event" on the window and adjust your
     size-dependent state to match the size delivered in the
     `<gdk-event-configure>'.

     Note 2: The returned size does _not_ include the size of the
     window manager decorations (aka the window frame or border). Those
     are not drawn by GTK+ and GTK+ has no reliable method of
     determining their size.

     Note 3: If you are getting a window size in order to position the
     window onscreen, there may be a better way. The preferred way is
     to simply set the window's semantic type with
     `gtk-window-set-type-hint', which allows the window manager to
     e.g. center dialogs. Also, if you set the transient parent of
     dialogs with `gtk-window-set-transient-for' window managers will
     often center the dialog over its parent window. It's much
     preferred to let the window manager handle these things rather
     than doing it yourself, because all apps will behave consistently
     and according to user prefs if the window manager handles it.
     Also, the window manager can take the size of the window
     decorations/border into account, while your application cannot.

     In any case, if you insist on application-specified window
     positioning, there's _still_ a better way than doing it yourself -
     `gtk-window-set-position' will frequently handle the details for
     you.

    WINDOW
          a `<gtk-window>'

    WIDTH
          return location for width, or ``#f''

    HEIGHT
          return location for height, or ``#f''



 -- Function: gtk-window-get-title (self `<gtk-window>') => 
          (ret `mchars')
 -- Method: get-title
     Retrieves the title of the window. See `gtk-window-set-title'.

    WINDOW
          a `<gtk-window>'

    RET
          the title of the window, or ``#f'' if none has been set
          explicitely.  The returned string is owned by the widget and
          must not be modified or freed.



 -- Function: gtk-window-get-transient-for (self `<gtk-window>') => 
          (ret `<gtk-window>')
 -- Method: get-transient-for
     Fetches the transient parent for this window. See
     `gtk-window-set-transient-for'.

    WINDOW
          a `<gtk-window>'

    RET
          the transient parent for this window, or ``#f'' if no
          transient parent has been set.



 -- Function: gtk-window-get-type-hint (self `<gtk-window>') => 
          (ret `<gdk-window-type-hint>')
 -- Method: get-type-hint
     Gets the type hint for this window. See `gtk-window-set-type-hint'.

    WINDOW
          a `<gtk-window>'

    RET
          the type hint for WINDOW.



 -- Function: gtk-window-get-skip-taskbar-hint (self `<gtk-window>')
          =>  (ret `bool')
 -- Method: get-skip-taskbar-hint
     Gets the value set by `gtk-window-set-skip-taskbar-hint'

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if window shouldn't be in taskbar


     Since 2.2


 -- Function: gtk-window-get-skip-pager-hint (self `<gtk-window>') => 
          (ret `bool')
 -- Method: get-skip-pager-hint
     Gets the value set by `gtk-window-set-skip-pager-hint'.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if window shouldn't be in pager


     Since 2.2


 -- Function: gtk-window-get-urgency-hint (self `<gtk-window>') => 
          (ret `bool')
 -- Method: get-urgency-hint
     Gets the value set by `gtk-window-set-urgency-hint'

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if window is urgent


     Since 2.8


 -- Function: gtk-window-get-accept-focus (self `<gtk-window>') => 
          (ret `bool')
 -- Method: get-accept-focus
     Gets the value set by `gtk-window-set-accept-focus'.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if window should receive the input focus


     Since 2.4


 -- Function: gtk-window-get-focus-on-map (self `<gtk-window>') => 
          (ret `bool')
 -- Method: get-focus-on-map
     Gets the value set by `gtk-window-set-focus-on-map'.

    WINDOW
          a `<gtk-window>'

    RET
          ``#t'' if window should receive the input focus when mapped.


     Since 2.6


 -- Function: gtk-window-get-group (self `<gtk-window>') => 
          (ret `<gtk-window-group>')
 -- Method: get-group
     Returns the group for WINDOW or the default group, if WINDOW is
     ``#f'' or if WINDOW does not have an explicit window group.

    WINDOW
          a `<gtk-window>', or ``#f''

    RET
          the `<gtk-window-group>' for a window or the default group


     Since 2.10


 -- Function: gtk-window-move (self `<gtk-window>') (x `int') (y `int')
 -- Method: move
     Asks the window manager to move WINDOW to the given position.
     Window managers are free to ignore this; most window managers
     ignore requests for initial window positions (instead using a
     user-defined placement algorithm) and honor requests after the
     window has already been shown.

     Note: the position is the position of the gravity-determined
     reference point for the window. The gravity determines two things:
     first, the location of the reference point in root window
     coordinates; and second, which point on the window is positioned
     at the reference point.

     By default the gravity is `<gdk-gravity-north-west>', so the
     reference point is simply the X, Y supplied to `gtk-window-move'.
     The top-left corner of the window decorations (aka window frame or
     border) will be placed at X, Y. Therefore, to position a window at
     the top left of the screen, you want to use the default gravity
     (which is `<gdk-gravity-north-west>') and move the window to 0,0.

     To position a window at the bottom right corner of the screen, you
     would set `<gdk-gravity-south-east>', which means that the
     reference point is at X + the window width and Y + the window
     height, and the bottom-right corner of the window border will be
     placed at that reference point. So, to place a window in the
     bottom right corner you would first set gravity to south east,
     then write: `gtk_window_move (window, `gdk-screen-width' -
     window_width, `gdk-screen-height' - window_height)' (note that
     this example does not take multi-head scenarios into account).

     The Extended Window Manager Hints specification at
     http://www.freedesktop.org/Standards/wm-spec
     (http://www.freedesktop.org/Standards/wm-spec) has a nice table of
     gravities in the "implementation notes" section.

     The `gtk-window-get-position' documentation may also be relevant.

    WINDOW
          a `<gtk-window>'

    X
          X coordinate to move window to

    Y
          Y coordinate to move window to



 -- Function: gtk-window-parse-geometry (self `<gtk-window>')
          (geometry `mchars') =>  (ret `bool')
 -- Method: parse-geometry
     Parses a standard X Window System geometry string - see the manual
     page for X (type 'man X') for details on this.
     `gtk-window-parse-geometry' does work on all GTK+ ports including
     Win32 but is primarily intended for an X environment.

     If either a size or a position can be extracted from the geometry
     string, `gtk-window-parse-geometry' returns ``#t'' and calls
     `gtk-window-set-default-size' and/or `gtk-window-move' to
     resize/move the window.

     If `gtk-window-parse-geometry' returns ``#t'', it will also set
     the `<gdk-hint-user-pos>' and/or `<gdk-hint-user-size>' hints
     indicating to the window manager that the size/position of the
     window was user-specified. This causes most window managers to
     honor the geometry.

     Note that for `gtk-window-parse-geometry' to work as expected, it
     has to be called when the window has its "final" size, i.e. after
     calling `gtk-widget-show-all' on the contents and
     `gtk-window-set-geometry-hints' on the window.


          #include <gtk/gtk.h>

          static void
          fill_with_content (GtkWidget *vbox)
          {
            /* fill with content... */
          }

          int
          main (int argc, char *argv[])
          {
            GtkWidget *window, *vbox;
            GdkGeometry size_hints = {
              100, 50, 0, 0, 100, 50, 10, 10, 0.0, 0.0, GDK_GRAVITY_NORTH_WEST
            };

            gtk_init (&argc, &argv);

            window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
            vbox = gtk_vbox_new (FALSE, 0);

            gtk_container_add (GTK_CONTAINER (window), vbox);
            fill_with_content (vbox);
            gtk_widget_show_all (vbox);

            gtk_window_set_geometry_hints (GTK_WINDOW (window),
          	  			    window,
          				    &size_hints,
          				    GDK_HINT_MIN_SIZE |
          				    GDK_HINT_BASE_SIZE |
          				    GDK_HINT_RESIZE_INC);

            if (argc > 1)
              {
                if (!gtk_window_parse_geometry (GTK_WINDOW (window), argv[1]))
                  fprintf (stderr, "Failed to parse '%s'\n", argv[1]);
              }

            gtk_widget_show_all (window);
            gtk_main ();

            return 0;
          }

    WINDOW
          a `<gtk-window>'

    GEOMETRY
          geometry string

    RET
          ``#t'' if string was parsed successfully



 -- Function: gtk-window-reshow-with-initial-size (self `<gtk-window>')
 -- Method: reshow-with-initial-size
     Hides WINDOW, then reshows it, resetting the default size and
     position of the window. Used by GUI builders only.

    WINDOW
          a `<gtk-window>'



 -- Function: gtk-window-resize (self `<gtk-window>') (width `int')
          (height `int')
 -- Method: resize
     Resizes the window as if the user had done so, obeying geometry
     constraints. The default geometry constraint is that windows may
     not be smaller than their size request; to override this
     constraint, call `gtk-widget-set-size-request' to set the window's
     request to a smaller value.

     If `gtk-window-resize' is called before showing a window for the
     first time, it overrides any default size set with
     `gtk-window-set-default-size'.

     Windows may not be resized smaller than 1 by 1 pixels.

    WINDOW
          a `<gtk-window>'

    WIDTH
          width in pixels to resize the window to

    HEIGHT
          height in pixels to resize the window to



 -- Function: gtk-window-set-default-icon-list (list `glist-of')
     Sets an icon list to be used as fallback for windows that haven't
     had `gtk-window-set-icon-list' called on them to set up a
     window-specific icon list. This function allows you to set up the
     icon for all windows in your app at once.

     See `gtk-window-set-icon-list' for more details.

    LIST
          a list of `<gdk-pixbuf>'



 -- Function: gtk-window-set-default-icon (icon `<gdk-pixbuf>')
     Sets an icon to be used as fallback for windows that haven't had
     `gtk-window-set-icon' called on them from a pixbuf.

    ICON
          the icon


     Since 2.4


 -- Function: gtk-window-set-default-icon-name (name `mchars')
     Sets an icon to be used as fallback for windows that haven't had
     `gtk-window-set-icon-list' called on them from a named themed
     icon, see `gtk-window-set-icon-name'.

    NAME
          the name of the themed icon


     Since 2.6


 -- Function: gtk-window-set-icon (self `<gtk-window>')
          (icon `<gdk-pixbuf>')
 -- Method: set-icon
     Sets up the icon representing a `<gtk-window>'. This icon is used
     when the window is minimized (also known as iconified). Some
     window managers or desktop environments may also place it in the
     window frame, or display it in other contexts.

     The icon should be provided in whatever size it was naturally
     drawn; that is, don't scale the image before passing it to GTK+.
     Scaling is postponed until the last minute, when the desired final
     size is known, to allow best quality.

     If you have your icon hand-drawn in multiple sizes, use
     `gtk-window-set-icon-list'. Then the best size will be used.

     This function is equivalent to calling `gtk-window-set-icon-list'
     with a 1-element list.

     See also `gtk-window-set-default-icon-list' to set the icon for
     all windows in your application in one go.

    WINDOW
          a `<gtk-window>'

    ICON
          icon image, or ``#f''



 -- Function: gtk-window-set-icon-list (self `<gtk-window>')
          (list `glist-of')
 -- Method: set-icon-list
     Sets up the icon representing a `<gtk-window>'. The icon is used
     when the window is minimized (also known as iconified). Some
     window managers or desktop environments may also place it in the
     window frame, or display it in other contexts.

     `gtk-window-set-icon-list' allows you to pass in the same icon in
     several hand-drawn sizes. The list should contain the natural
     sizes your icon is available in; that is, don't scale the image
     before passing it to GTK+. Scaling is postponed until the last
     minute, when the desired final size is known, to allow best
     quality.

     By passing several sizes, you may improve the final image quality
     of the icon, by reducing or eliminating automatic image scaling.

     Recommended sizes to provide: 16x16, 32x32, 48x48 at minimum, and
     larger images (64x64, 128x128) if you have them.

     See also `gtk-window-set-default-icon-list' to set the icon for
     all windows in your application in one go.

     Note that transient windows (those who have been set transient for
     another window using `gtk-window-set-transient-for') will inherit
     their icon from their transient parent. So there's no need to
     explicitly set the icon on transient windows.

    WINDOW
          a `<gtk-window>'

    LIST
          list of `<gdk-pixbuf>'



 -- Function: gtk-window-set-icon-from-file (self `<gtk-window>')
          (filename `mchars') =>  (ret `bool')
 -- Method: set-icon-from-file
     Sets the icon for WINDOW. Warns on failure if ERR is ``#f''.

     This function is equivalent to calling `gtk-window-set-icon' with
     a pixbuf created by loading the image from FILENAME.

    WINDOW
          a `<gtk-window>'

    FILENAME
          location of icon file

    ERR
          location to store error, or ``#f''.

    RET
          ``#t'' if setting the icon succeeded.


     Since 2.2


 -- Function: gtk-window-set-icon-name (self `<gtk-window>')
          (name `mchars')
 -- Method: set-icon-name
     Sets the icon for the window from a named themed icon. See the
     docs for `<gtk-icon-theme>' for more details.

     Note that this has nothing to do with the WM_ICON_NAME property
     which is mentioned in the ICCCM.

    WINDOW
          a `<gtk-window>'

    NAME
          the name of the themed icon


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkWindowGroup,  Next: GtkAboutDialog,  Prev: GtkWindow,  Up: Top

6 GtkWindowGroup
****************

Limit the effect of grabs

6.1 Overview
============

6.2 Usage
=========

 -- Class: <gtk-window-group>
     Derives from `<gobject>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gtk-window-group-new =>  (ret `<gtk-window-group>')
     Creates a new `<gtk-window-group>' object. Grabs added with
     `gtk-grab-add' only affect windows within the same
     `<gtk-window-group>'.

    RET
          a new `<gtk-window-group>'.



 -- Function: gtk-window-group-add-window (self `<gtk-window-group>')
          (window `<gtk-window>')
 -- Method: add-window
     Adds a window to a `<gtk-window-group>'.

    WINDOW-GROUP
          a `<gtk-window-group>'

    WINDOW
          the `<gtk-window>' to add



 -- Function: gtk-window-group-remove-window
          (self `<gtk-window-group>') (window `<gtk-window>')
 -- Method: remove-window
     Removes a window from a `<gtk-window-group>'.

    WINDOW-GROUP
          a `<gtk-window-group>'

    WINDOW
          the `<gtk-window>' to remove




File: guile-gnome-gtk.info,  Node: GtkAboutDialog,  Next: GtkAssistant,  Prev: GtkWindowGroup,  Up: Top

7 GtkAboutDialog
****************

Display information about an application

7.1 Overview
============

The `<gtk-about-dialog>' offers a simple way to display information
about a program like its logo, name, copyright, website and license. It
is also possible to give credits to the authors, documenters,
translators and artists who have worked on the program. An about dialog
is typically opened when the user selects the `About' option from the
`Help' menu. All parts of the dialog are optional.

   About dialog often contain links and email addresses.
`<gtk-about-dialog>' supports this by offering global hooks, which are
called when the user clicks on a link or email address, see
`gtk-about-dialog-set-email-hook' and `gtk-about-dialog-set-url-hook'.
Email addresses in the authors, documenters and artists properties are
recognized by looking for `<user@host>', URLs are recognized by looking
for `http://url', with `url' extending to the next space, tab or line
break.

   To make constructing a `<gtk-about-dialog>' as convenient as
possible, you can use the function `gtk-show-about-dialog' which
constructs and shows a dialog and keeps it around so that it can be
shown again.

7.2 Usage
=========

 -- Class: <gtk-about-dialog>
     Derives from `<gtk-dialog>'.

     This class defines the following properties:

    `program-name'
          The name of the program. If this is not set, it defaults to
          g_get_application_name()

    `version'
          The version of the program

    `copyright'
          Copyright information for the program

    `comments'
          Comments about the program

    `website'
          The URL for the link to the website of the program

    `website-label'
          The label for the link to the website of the program. If this
          is not set, it defaults to the URL

    `license'
          The license of the program

    `authors'
          List of authors of the program

    `documenters'
          List of people documenting the program

    `translator-credits'
          Credits to the translators. This string should be marked as
          translatable

    `artists'
          List of people who have contributed artwork to the program

    `logo'
          A logo for the about box. If this is not set, it defaults to
          gtk_window_get_default_icon_list()

    `logo-icon-name'
          A named icon to use as the logo for the about box.

    `wrap-license'
          Whether to wrap the license text.



 -- Function: gtk-about-dialog-new =>  (ret `<gtk-widget>')
     Creates a new `<gtk-about-dialog>'.

    RET
          a newly created `<gtk-about-dialog>'


     Since 2.6


 -- Function: gtk-about-dialog-get-name (self `<gtk-about-dialog>') => 
          (ret `mchars')
 -- Method: get-name
     Returns the program name displayed in the about dialog.

    ABOUT
          a `<gtk-about-dialog>'

    RET
          The program name. The string is owned by the about dialog and
          must not be modified.


     Since 2.6


 -- Function: gtk-about-dialog-set-name (self `<gtk-about-dialog>')
          (name `mchars')
 -- Method: set-name
     Sets the name to display in the about dialog. If this is not set,
     it defaults to `g-get-application-name'.

    ABOUT
          a `<gtk-about-dialog>'

    NAME
          the program name


     Since 2.6


 -- Function: gtk-about-dialog-get-version (self `<gtk-about-dialog>')
          =>  (ret `mchars')
 -- Method: get-version
     Returns the version string.

    ABOUT
          a `<gtk-about-dialog>'

    RET
          The version string. The string is owned by the about dialog
          and must not be modified.


     Since 2.6


 -- Function: gtk-about-dialog-set-version (self `<gtk-about-dialog>')
          (version `mchars')
 -- Method: set-version
     Sets the version string to display in the about dialog.

    ABOUT
          a `<gtk-about-dialog>'

    VERSION
          the version string


     Since 2.6


 -- Function: gtk-about-dialog-get-copyright
          (self `<gtk-about-dialog>') =>  (ret `mchars')
 -- Method: get-copyright
     Returns the copyright string.

    ABOUT
          a `<gtk-about-dialog>'

    RET
          The copyright string. The string is owned by the about dialog
          and must not be modified.


     Since 2.6


 -- Function: gtk-about-dialog-set-copyright
          (self `<gtk-about-dialog>') (copyright `mchars')
 -- Method: set-copyright
     Sets the copyright string to display in the about dialog. This
     should be a short string of one or two lines.

    ABOUT
          a `<gtk-about-dialog>'

    COPYRIGHT
          the copyright string


     Since 2.6


 -- Function: gtk-about-dialog-get-license (self `<gtk-about-dialog>')
          =>  (ret `mchars')
 -- Method: get-license
     Returns the license information.

    ABOUT
          a `<gtk-about-dialog>'

    RET
          The license information. The string is owned by the about
          dialog and must not be modified.


     Since 2.6


 -- Function: gtk-about-dialog-set-license (self `<gtk-about-dialog>')
          (license `mchars')
 -- Method: set-license
     Sets the license information to be displayed in the secondary
     license dialog. If LICENSE is ``#f'', the license button is hidden.

    ABOUT
          a `<gtk-about-dialog>'

    LICENSE
          the license information or ``#f''


     Since 2.6


 -- Function: gtk-about-dialog-get-wrap-license
          (self `<gtk-about-dialog>') =>  (ret `bool')
 -- Method: get-wrap-license
     Returns whether the license text in ABOUT is automatically wrapped.

    ABOUT
          a `<gtk-about-dialog>'

    RET
          ``#t'' if the license text is wrapped


     Since 2.8


 -- Function: gtk-about-dialog-set-wrap-license
          (self `<gtk-about-dialog>') (wrap_license `bool')
 -- Method: set-wrap-license
     Sets whether the license text in ABOUT is automatically wrapped.

    ABOUT
          a `<gtk-about-dialog>'

    WRAP-LICENSE
          whether to wrap the license


     Since 2.8


 -- Function: gtk-about-dialog-get-website (self `<gtk-about-dialog>')
          =>  (ret `mchars')
 -- Method: get-website
     Returns the website URL.

    ABOUT
          a `<gtk-about-dialog>'

    RET
          The website URL. The string is owned by the about dialog and
          must not be modified.


     Since 2.6


 -- Function: gtk-about-dialog-set-website (self `<gtk-about-dialog>')
          (website `mchars')
 -- Method: set-website
     Sets the URL to use for the website link.

    ABOUT
          a `<gtk-about-dialog>'

    WEBSITE
          a URL string starting with "http://"


     Since 2.6


 -- Function: gtk-about-dialog-get-website-label
          (self `<gtk-about-dialog>') =>  (ret `mchars')
 -- Method: get-website-label
     Returns the label used for the website link.

    ABOUT
          a `<gtk-about-dialog>'

    RET
          The label used for the website link. The string is owned by
          the about dialog and must not be modified.


     Since 2.6


 -- Function: gtk-about-dialog-set-website-label
          (self `<gtk-about-dialog>') (website_label `mchars')
 -- Method: set-website-label
     Sets the label to be used for the website link. It defaults to the
     website URL.

    ABOUT
          a `<gtk-about-dialog>'

    WEBSITE-LABEL
          the label used for the website link


     Since 2.6


 -- Function: gtk-about-dialog-get-logo (self `<gtk-about-dialog>') => 
          (ret `<gdk-pixbuf>')
 -- Method: get-logo
     Returns the pixbuf displayed as logo in the about dialog.

    ABOUT
          a `<gtk-about-dialog>'

    RET
          the pixbuf displayed as logo. The pixbuf is owned by the
          about dialog. If you want to keep a reference to it, you have
          to call `g-object-ref' on it.


     Since 2.6


 -- Function: gtk-about-dialog-set-logo (self `<gtk-about-dialog>')
          (logo `<gdk-pixbuf>')
 -- Method: set-logo
     Sets the pixbuf to be displayed as logo in the about dialog. If it
     is ``#f'', the default window icon set with
     `gtk-window-set-default-icon' will be used.

    ABOUT
          a `<gtk-about-dialog>'

    LOGO
          a `<gdk-pixbuf>', or ``#f''


     Since 2.6


 -- Function: gtk-about-dialog-get-logo-icon-name
          (self `<gtk-about-dialog>') =>  (ret `mchars')
 -- Method: get-logo-icon-name
     Returns the icon name displayed as logo in the about dialog.

    ABOUT
          a `<gtk-about-dialog>'

    RET
          the icon name displayed as logo. The string is owned by the
          dialog. If you want to keep a reference to it, you have to
          call `g-strdup' on it.


     Since 2.6


 -- Function: gtk-about-dialog-set-logo-icon-name
          (self `<gtk-about-dialog>') (icon_name `mchars')
 -- Method: set-logo-icon-name
     Sets the pixbuf to be displayed as logo in the about dialog. If it
     is ``#f'', the default window icon set with
     `gtk-window-set-default-icon' will be used.

    ABOUT
          a `<gtk-about-dialog>'

    ICON-NAME
          an icon name, or ``#f''


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkAssistant,  Next: GtkAccelLabel,  Prev: GtkAboutDialog,  Up: Top

8 GtkAssistant
**************

A widget used to guide users through multi-step operations

8.1 Overview
============

A `<gtk-assistant>' is a widget used to represent a generally complex
operation splitted in several steps, guiding the user through its pages
and controlling the page flow to collect the necessary data.

8.2 Usage
=========

 -- Class: <gtk-assistant>
     Derives from `<gtk-window>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Signal on <gtk-assistant>: close
     The ::close signal is emitted either when the close button of a
     summary page is clicked, or when the apply button in the last page
     in the flow (of type GTK_ASSISTANT_PAGE_CONFIRM) is clicked.

     Since 2.10


 -- Signal on <gtk-assistant>: cancel
     The ::cancel signal is emitted when then the cancel button is
     clicked.

     Since 2.10


 -- Signal on <gtk-assistant>: prepare (arg0 `<gtk-widget>')
     The ::prepared signal is emitted when a new page is set as the
     assistant's current page, before making the new page visible. A
     handler for this signal can do any preparation which are necessary
     before showing PAGE.

     Since 2.10


 -- Signal on <gtk-assistant>: apply
     The ::apply signal is emitted when the apply button is clicked.
     The default behavior of the `<gtk-assistant>' is to switch to the
     page after the current page, unless the current page is the last
     one.

     A handler for the ::apply signal should carry out the actions for
     which the wizard has collected data. If the action takes a long
     time to complete, you might consider to put a page of type
     GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle
     this operation within the ::prepare signal of the progress page.

     Since 2.10


 -- Function: gtk-assistant-new =>  (ret `<gtk-widget>')
     Creates a new `<gtk-assistant>'.

    RET
          a newly created `<gtk-assistant>'


     Since 2.10


 -- Function: gtk-assistant-get-current-page (self `<gtk-assistant>')
          =>  (ret `int')
 -- Method: get-current-page
     Returns the page number of the current page

    ASSISTANT
          a `<gtk-assistant>'

    RET
          The index (starting from 0) of the current page in the
          ASSISTANT, if the ASSISTANT has no pages, -1 will be returned


     Since 2.10


 -- Function: gtk-assistant-set-current-page (self `<gtk-assistant>')
          (page_num `int')
 -- Method: set-current-page
     Switches the page to PAGE-NUM. Note that this will only be
     necessary in custom buttons, as the ASSISTANT flow can be set with
     `gtk-assistant-set-forward-page-func'.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE-NUM
          index of the page to switch to, starting from 0. If negative,
          the last page will be used. If greater than the number of
          pages in the ASSISTANT, nothing will be done.


     Since 2.10


 -- Function: gtk-assistant-get-n-pages (self `<gtk-assistant>') => 
          (ret `int')
 -- Method: get-n-pages
     Returns the number of pages in the ASSISTANT

    ASSISTANT
          a `<gtk-assistant>'

    RET
          The number of pages in the ASSISTANT.


     Since 2.10


 -- Function: gtk-assistant-get-nth-page (self `<gtk-assistant>')
          (page_num `int') =>  (ret `<gtk-widget>')
 -- Method: get-nth-page
     Returns the child widget contained in page number PAGE-NUM.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE-NUM
          The index of a page in the ASSISTANT, or -1 to get the last
          page;

    RET
          The child widget, or ``#f'' if PAGE-NUM is out of bounds.


     Since 2.10


 -- Function: gtk-assistant-prepend-page (self `<gtk-assistant>')
          (page `<gtk-widget>') =>  (ret `int')
 -- Method: prepend-page
     Prepends a page to the ASSISTANT.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a `<gtk-widget>'

    RET
          the index (starting at 0) of the inserted page


     Since 2.10


 -- Function: gtk-assistant-append-page (self `<gtk-assistant>')
          (page `<gtk-widget>') =>  (ret `int')
 -- Method: append-page
     Appends a page to the ASSISTANT.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a `<gtk-widget>'

    RET
          the index (starting at 0) of the inserted page


     Since 2.10


 -- Function: gtk-assistant-insert-page (self `<gtk-assistant>')
          (page `<gtk-widget>') (position `int') =>  (ret `int')
 -- Method: insert-page
     Inserts a page in the ASSISTANT at a given position.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a `<gtk-widget>'

    POSITION
          the index (starting at 0) at which to insert the page, or -1
          to append the page to the ASSISTANT

    RET
          the index (starting from 0) of the inserted page


     Since 2.10


 -- Function: gtk-assistant-set-page-type (self `<gtk-assistant>')
          (page `<gtk-widget>') (type `<gtk-assistant-page-type>')
 -- Method: set-page-type
     Sets the page type for PAGE. The page type determines the page
     behavior in the ASSISTANT.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a page of ASSISTANT

    TYPE
          the new type for PAGE


     Since 2.10


 -- Function: gtk-assistant-get-page-type (self `<gtk-assistant>')
          (page `<gtk-widget>') =>  (ret `<gtk-assistant-page-type>')
 -- Method: get-page-type
     Gets the page type of PAGE.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a page of ASSISTANT

    RET
          the page type of PAGE.


     Since 2.10


 -- Function: gtk-assistant-set-page-title (self `<gtk-assistant>')
          (page `<gtk-widget>') (title `mchars')
 -- Method: set-page-title
     Sets a title for PAGE. The title is displayed in the header area
     of the assistant when PAGE is the current page.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a page of ASSISTANT

    TITLE
          the new title for PAGE


     Since 2.10


 -- Function: gtk-assistant-get-page-title (self `<gtk-assistant>')
          (page `<gtk-widget>') =>  (ret `mchars')
 -- Method: get-page-title
     Gets the title for PAGE.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a page of ASSISTANT

    RET
          the title for PAGE.


     Since 2.10


 -- Function: gtk-assistant-set-page-header-image
          (self `<gtk-assistant>') (page `<gtk-widget>')
          (pixbuf `<gdk-pixbuf>')
 -- Method: set-page-header-image
     Sets a header image for PAGE. This image is displayed in the
     header area of the assistant when PAGE is the current page.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a page of ASSISTANT

    PIXBUF
          the new header image PAGE


     Since 2.10


 -- Function: gtk-assistant-get-page-header-image
          (self `<gtk-assistant>') (page `<gtk-widget>') => 
          (ret `<gdk-pixbuf>')
 -- Method: get-page-header-image
     Gets the header image for PAGE.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a page of ASSISTANT

    RET
          the header image for PAGE, or ``#f'' if there's no header
          image for the page.


     Since 2.10


 -- Function: gtk-assistant-set-page-side-image
          (self `<gtk-assistant>') (page `<gtk-widget>')
          (pixbuf `<gdk-pixbuf>')
 -- Method: set-page-side-image
     Sets a header image for PAGE. This image is displayed in the side
     area of the assistant when PAGE is the current page.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a page of ASSISTANT

    PIXBUF
          the new header image PAGE


     Since 2.10


 -- Function: gtk-assistant-get-page-side-image
          (self `<gtk-assistant>') (page `<gtk-widget>') => 
          (ret `<gdk-pixbuf>')
 -- Method: get-page-side-image
     Gets the header image for PAGE.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a page of ASSISTANT

    RET
          the side image for PAGE, or ``#f'' if there's no side image
          for the page.


     Since 2.10


 -- Function: gtk-assistant-set-page-complete (self `<gtk-assistant>')
          (page `<gtk-widget>') (complete `bool')
 -- Method: set-page-complete
     Sets whether PAGE contents are complete. This will make ASSISTANT
     update the buttons state to be able to continue the task.

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a page of ASSISTANT

    COMPLETE
          the completeness status of the page


     Since 2.10


 -- Function: gtk-assistant-get-page-complete (self `<gtk-assistant>')
          (page `<gtk-widget>') =>  (ret `bool')
 -- Method: get-page-complete
     Gets whether PAGE is complete..

    ASSISTANT
          a `<gtk-assistant>'

    PAGE
          a page of ASSISTANT

    RET
          ``#t'' if PAGE is complete.


     Since 2.10


 -- Function: gtk-assistant-add-action-widget (self `<gtk-assistant>')
          (child `<gtk-widget>')
 -- Method: add-action-widget
     Adds a widget to the action area of a `<gtk-assistant>'.

    ASSISTANT
          a `<gtk-assistant>'

    CHILD
          a `<gtk-widget>'


     Since 2.10


 -- Function: gtk-assistant-remove-action-widget
          (self `<gtk-assistant>') (child `<gtk-widget>')
 -- Method: remove-action-widget
     Removes a widget from the action area of a `<gtk-assistant>'.

    ASSISTANT
          a `<gtk-assistant>'

    CHILD
          a `<gtk-widget>'


     Since 2.10


 -- Function: gtk-assistant-update-buttons-state
          (self `<gtk-assistant>')
 -- Method: update-buttons-state
     Forces ASSISTANT to recompute the buttons state.

     GTK+ automatically takes care of this in most situations, e.g.
     when the user goes to a different page, or when the visibility or
     completeness of a page changes.

     One situation where it can be necessary to call this function is
     when changing a value on the current page affects the future page
     flow of the assistant.

    ASSISTANT
          a `<gtk-assistant>'


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkAccelLabel,  Next: GtkImage,  Prev: GtkAssistant,  Up: Top

9 GtkAccelLabel
***************

A label which displays an accelerator key on the right of the text

9.1 Overview
============

The `<gtk-accel-label>' widget is a subclass of `<gtk-label>' that also
displays an accelerator key on the right of the label text, e.g.
'Ctl+S'.  It is commonly used in menus to show the keyboard short-cuts
for commands.

   The accelerator key to display is not set explicitly. Instead, the
`<gtk-accel-label>' displays the accelerators which have been added to a
particular widget. This widget is set by calling
`gtk-accel-label-set-accel-widget'.

   For example, a `<gtk-menu-item>' widget may have an accelerator
added to emit the "activate" signal when the 'Ctl+S' key combination is
pressed. A `<gtk-accel-label>' is created and added to the
`<gtk-menu-item>', and `gtk-accel-label-set-accel-widget' is called
with the `<gtk-menu-item>' as the second argument. The
`<gtk-accel-label>' will now display 'Ctl+S' after its label.

   Note that creating a `<gtk-menu-item>' with
`gtk-menu-item-new-with-label' (or one of the similar functions for
`<gtk-check-menu-item>' and `<gtk-radio-menu-item>') automatically adds
a `<gtk-accel-label>' to the `<gtk-menu-item>' and calls
`gtk-accel-label-set-accel-widget' to set it up for you.

   A `<gtk-accel-label>' will only display accelerators which have
`GTK_ACCEL_VISIBLE' set (see `<gtk-accel-flags>'). A
`<gtk-accel-label>' can display multiple accelerators and even signal
names, though it is almost always used to display just one accelerator
key.


       GtkWidget *save_item;
       GtkAccelGroup *accel_group;

       /* Create a GtkAccelGroup and add it to the window. */
       accel_group = gtk_accel_group_new ();
       gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);

       /* Create the menu item using the convenience function. */
       save_item = gtk_menu_item_new_with_label ("Save");
       gtk_widget_show (save_item);
       gtk_container_add (GTK_CONTAINER (menu), save_item);

       /* Now add the accelerator to the GtkMenuItem. Note that since we called
          gtk_menu_item_new_with_label() to create the GtkMenuItem the
          GtkAccelLabel is automatically set up to display the GtkMenuItem
          accelerators. We just need to make sure we use GTK_ACCEL_VISIBLE here. */
       gtk_widget_add_accelerator (save_item, "activate", accel_group,
                                   GDK_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);

9.2 Usage
=========

 -- Class: <gtk-accel-label>
     Derives from `<gtk-label>'.

     This class defines the following properties:

    `accel-closure'
          The closure to be monitored for accelerator changes

    `accel-widget'
          The widget to be monitored for accelerator changes



 -- Function: gtk-accel-label-new (string `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-accel-label>'.

    STRING
          the label string. Must be non-``#f''.

    RET
          a new `<gtk-accel-label>'.



 -- Function: gtk-accel-label-set-accel-closure
          (self `<gtk-accel-label>') (accel_closure `<gclosure>')
 -- Method: set-accel-closure
     Sets the closure to be monitored by this accelerator label. The
     closure must be connected to an accelerator group; see
     `gtk-accel-group-connect'.

    ACCEL-LABEL
          a `<gtk-accel-label>'

    ACCEL-CLOSURE
          the closure to monitor for accelerator changes.



 -- Function: gtk-accel-label-get-accel-widget
          (self `<gtk-accel-label>') =>  (ret `<gtk-widget>')
 -- Method: get-accel-widget
     Fetches the widget monitored by this accelerator label. See
     `gtk-accel-label-set-accel-widget'.

    ACCEL-LABEL
          a `<gtk-accel-label>'

    RET
          the object monitored by the accelerator label, or ``#f''.



 -- Function: gtk-accel-label-set-accel-widget
          (self `<gtk-accel-label>') (accel_widget `<gtk-widget>')
 -- Method: set-accel-widget
     Sets the widget to be monitored by this accelerator label.

    ACCEL-LABEL
          a `<gtk-accel-label>'

    ACCEL-WIDGET
          the widget to be monitored.



 -- Function: gtk-accel-label-get-accel-width
          (self `<gtk-accel-label>') =>  (ret `unsigned-int')
 -- Method: get-accel-width
     Returns the width needed to display the accelerator key(s). This
     is used by menus to align all of the `<gtk-menu-item>' widgets,
     and shouldn't be needed by applications.

    ACCEL-LABEL
          a `<gtk-accel-label>'.

    RET
          the width needed to display the accelerator key(s).



 -- Function: gtk-accel-label-refetch (self `<gtk-accel-label>') => 
          (ret `bool')
 -- Method: refetch
     Recreates the string representing the accelerator keys. This
     should not be needed since the string is automatically updated
     whenever accelerators are added or removed from the associated
     widget.

    ACCEL-LABEL
          a `<gtk-accel-label>'.

    RET
          always returns ``#f''.




File: guile-gnome-gtk.info,  Node: GtkImage,  Next: GtkLabel,  Prev: GtkAccelLabel,  Up: Top

10 GtkImage
***********

A widget displaying an image

10.1 Overview
=============

The `<gtk-image>' widget displays an image. Various kinds of object can
be displayed as an image; most typically, you would load a
`<gdk-pixbuf>' ("pixel buffer") from a file, and then display that.
There's a convenience function to do this, `gtk-image-new-from-file',
used as follows: If the file isn't loaded successfully, the image will
contain a "broken image" icon similar to that used in many web
browsers. If you want to handle errors in loading the file yourself,
for example by displaying an error message, then load the image with
`gdk-pixbuf-new-from-file', then create the `<gtk-image>' with
`gtk-image-new-from-pixbuf'.


       GtkWidget *image;
       image = gtk_image_new_from_file ("myfile.png");

   The image file may contain an animation, if so the `<gtk-image>' will
display an animation (`<gdk-pixbuf-animation>') instead of a static
image.

   `<gtk-image>' is a subclass of `<gtk-misc>', which implies that you
can align it (center, left, right) and add padding to it, using
`<gtk-misc>' methods.

   `<gtk-image>' is a "no window" widget (has no `<gdk-window>' of its
own), so by default does not receive events. If you want to receive
events on the image, such as button clicks, place the image inside a
`<gtk-event-box>', then connect to the event signals on the event box.


       static gboolean
       button_press_callback (GtkWidget      *event_box,
                              GdkEventButton *event,
                              gpointer        data)
       {
         g_print ("Event box clicked at coordinates %f,%f\n",
                  event->x, event->y);

         /* Returning TRUE means we handled the event, so the signal
          * emission should be stopped (don't call any further
          * callbacks that may be connected). Return FALSE
          * to continue invoking callbacks.
          */
         return TRUE;
       }

       static GtkWidget*
       create_image (void)
       {
         GtkWidget *image;
         GtkWidget *event_box;

         image = gtk_image_new_from_file ("myfile.png");

         event_box = gtk_event_box_new ();

         gtk_container_add (GTK_CONTAINER (event_box), image);

         g_signal_connect (G_OBJECT (event_box),
                           "button_press_event",
                           G_CALLBACK (button_press_callback),
                           image);

         return image;
       }

   When handling events on the event box, keep in mind that coordinates
in the image may be different from event box coordinates due to the
alignment and padding settings on the image (see `<gtk-misc>'). The
simplest way to solve this is to set the alignment to 0.0 (left/top),
and set the padding to zero.  Then the origin of the image will be the
same as the origin of the event box.

   Sometimes an application will want to avoid depending on external
data files, such as image files. GTK+ comes with a program to avoid
this, called . This program allows you to convert an image into a C
variable declaration, which can then be loaded into a `<gdk-pixbuf>'
using `gdk-pixbuf-new-from-inline'.

10.2 Usage
==========

 -- Class: <gtk-image>
     Derives from `<gtk-misc>'.

     This class defines the following properties:

    `pixbuf'
          A GdkPixbuf to display

    `pixmap'
          A GdkPixmap to display

    `image'
          A GdkImage to display

    `mask'
          Mask bitmap to use with GdkImage or GdkPixmap

    `file'
          Filename to load and display

    `stock'
          Stock ID for a stock image to display

    `icon-set'
          Icon set to display

    `icon-size'
          Symbolic size to use for stock icon, icon set or named icon

    `pixel-size'
          Pixel size to use for named icon

    `pixbuf-animation'
          GdkPixbufAnimation to display

    `icon-name'
          The name of the icon from the icon theme

    `storage-type'
          The representation being used for image data



 -- Function: gtk-image-get-pixbuf (self `<gtk-image>') => 
          (ret `<gdk-pixbuf>')
 -- Method: get-pixbuf
     Gets the `<gdk-pixbuf>' being displayed by the `<gtk-image>'. The
     storage type of the image must be `GTK_IMAGE_EMPTY' or
     `GTK_IMAGE_PIXBUF' (see `gtk-image-get-storage-type'). The caller
     of this function does not own a reference to the returned pixbuf.

    IMAGE
          a `<gtk-image>'

    RET
          the displayed pixbuf, or ``#f'' if the image is empty



 -- Function: gtk-image-get-animation (self `<gtk-image>') => 
          (ret `<gdk-pixbuf-animation>')
 -- Method: get-animation
     Gets the `<gdk-pixbuf-animation>' being displayed by the
     `<gtk-image>'. The storage type of the image must be
     `GTK_IMAGE_EMPTY' or `GTK_IMAGE_ANIMATION' (see
     `gtk-image-get-storage-type'). The caller of this function does
     not own a reference to the returned animation.

    IMAGE
          a `<gtk-image>'

    RET
          the displayed animation, or ``#f'' if the image is empty



 -- Function: gtk-image-get-storage-type (self `<gtk-image>') => 
          (ret `<gtk-image-type>')
 -- Method: get-storage-type
     Gets the type of representation being used by the `<gtk-image>' to
     store image data. If the `<gtk-image>' has no image data, the
     return value will be `GTK_IMAGE_EMPTY'.

    IMAGE
          a `<gtk-image>'

    RET
          image representation being used



 -- Function: gtk-image-new-from-file (filename `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-image>' displaying the file FILENAME. If the
     file isn't found or can't be loaded, the resulting `<gtk-image>'
     will display a "broken image" icon. This function never returns
     ``#f'', it always returns a valid `<gtk-image>' widget.

     If the file contains an animation, the image will contain an
     animation.

     If you need to detect failures to load the file, use
     `gdk-pixbuf-new-from-file' to load the file yourself, then create
     the `<gtk-image>' from the pixbuf. (Or for animations, use
     `gdk-pixbuf-animation-new-from-file').

     The storage type (`gtk-image-get-storage-type') of the returned
     image is not defined, it will be whatever is appropriate for
     displaying the file.

    FILENAME
          a filename

    RET
          a new `<gtk-image>'



 -- Function: gtk-image-new-from-icon-set (icon_set `<gtk-icon-set>')
          (size `<gtk-icon-size>') =>  (ret `<gtk-widget>')
     Creates a `<gtk-image>' displaying an icon set. Sample stock sizes
     are `<gtk-icon-size-menu>', `<gtk-icon-size-small-toolbar>'.
     Instead of using this function, usually it's better to create a
     `<gtk-icon-factory>', put your icon sets in the icon factory, add
     the icon factory to the list of default factories with
     `gtk-icon-factory-add-default', and then use
     `gtk-image-new-from-stock'. This will allow themes to override the
     icon you ship with your application.

     The `<gtk-image>' does not assume a reference to the icon set; you
     still need to unref it if you own references. `<gtk-image>' will
     add its own reference rather than adopting yours.

    ICON-SET
          a `<gtk-icon-set>'

    SIZE
          a stock icon size

    RET
          a new `<gtk-image>'



 -- Function: gtk-image-new-from-image (image `<gdk-image>')
          (mask `<gdk-drawable>') =>  (ret `<gtk-widget>')
     Creates a `<gtk-image>' widget displaying a IMAGE with a MASK.  A
     `<gdk-image>' is a client-side image buffer in the pixel format of
     the current display. The `<gtk-image>' does not assume a reference
     to the image or mask; you still need to unref them if you own
     references. `<gtk-image>' will add its own reference rather than
     adopting yours.

    IMAGE
          a `<gdk-image>', or ``#f''

    MASK
          a `<gdk-bitmap>', or ``#f''

    RET
          a new `<gtk-image>'



 -- Function: gtk-image-new-from-pixbuf (pixbuf `<gdk-pixbuf>') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-image>' displaying PIXBUF. The `<gtk-image>'
     does not assume a reference to the pixbuf; you still need to unref
     it if you own references. `<gtk-image>' will add its own reference
     rather than adopting yours.

     Note that this function just creates an `<gtk-image>' from the
     pixbuf. The `<gtk-image>' created will not react to state changes.
     Should you want that, you should use `gtk-image-new-from-icon-set'.

    PIXBUF
          a `<gdk-pixbuf>', or ``#f''

    RET
          a new `<gtk-image>'



 -- Function: gtk-image-new-from-pixmap (pixmap `<gdk-pixmap>')
          (mask `<gdk-drawable>') =>  (ret `<gtk-widget>')
     Creates a `<gtk-image>' widget displaying PIXMAP with a MASK. A
     `<gdk-pixmap>' is a server-side image buffer in the pixel format
     of the current display. The `<gtk-image>' does not assume a
     reference to the pixmap or mask; you still need to unref them if
     you own references.  `<gtk-image>' will add its own reference
     rather than adopting yours.

    PIXMAP
          a `<gdk-pixmap>', or ``#f''

    MASK
          a `<gdk-bitmap>', or ``#f''

    RET
          a new `<gtk-image>'



 -- Function: gtk-image-new-from-stock (stock_id `mchars')
          (size `<gtk-icon-size>') =>  (ret `<gtk-widget>')
     Creates a `<gtk-image>' displaying a stock icon. Sample stock icon
     names are `<gtk-stock-open>', `<gtk-stock-quit>'. Sample stock
     sizes are `<gtk-icon-size-menu>', `<gtk-icon-size-small-toolbar>'.
     If the stock icon name isn't known, the image will be empty. You
     can register your own stock icon names, see
     `gtk-icon-factory-add-default' and `gtk-icon-factory-add'.

    STOCK-ID
          a stock icon name

    SIZE
          a stock icon size

    RET
          a new `<gtk-image>' displaying the stock icon



 -- Function: gtk-image-new-from-animation
          (animation `<gdk-pixbuf-animation>') =>  (ret `<gtk-widget>')
     Creates a `<gtk-image>' displaying the given animation. The
     `<gtk-image>' does not assume a reference to the animation; you
     still need to unref it if you own references. `<gtk-image>' will
     add its own reference rather than adopting yours.

     Note that the animation frames are shown using a timeout with
     `<g-priority-default>'. When using animations to indicate
     busyness, keep in mind that the animation will only be shown if
     the main loop is not busy with something that has a higher
     priority.

    ANIMATION
          an animation

    RET
          a new `<gtk-image>' widget



 -- Function: gtk-image-new-from-icon-name (icon_name `mchars')
          (size `<gtk-icon-size>') =>  (ret `<gtk-widget>')
     Creates a `<gtk-image>' displaying an icon from the current icon
     theme. If the icon name isn't known, a "broken image" icon will be
     displayed instead. If the current icon theme is changed, the icon
     will be updated appropriately.

    ICON-NAME
          an icon name

    SIZE
          a stock icon size

    RET
          a new `<gtk-image>' displaying the themed icon


     Since 2.6


 -- Function: gtk-image-set-from-file (self `<gtk-image>')
          (filename `mchars')
 -- Method: set-from-file
     See `gtk-image-new-from-file' for details.

    IMAGE
          a `<gtk-image>'

    FILENAME
          a filename or ``#f''



 -- Function: gtk-image-set-from-icon-set (self `<gtk-image>')
          (icon_set `<gtk-icon-set>') (size `<gtk-icon-size>')
 -- Method: set-from-icon-set
     See `gtk-image-new-from-icon-set' for details.

    IMAGE
          a `<gtk-image>'

    ICON-SET
          a `<gtk-icon-set>'

    SIZE
          a stock icon size



 -- Function: gtk-image-set-from-image (self `<gtk-image>')
          (gdk_image `<gdk-image>') (mask `<gdk-drawable>')
 -- Method: set-from-image
     See `gtk-image-new-from-image' for details.

    IMAGE
          a `<gtk-image>'

    GDK-IMAGE
          a `<gdk-image>' or ``#f''

    MASK
          a `<gdk-bitmap>' or ``#f''



 -- Function: gtk-image-set-from-pixbuf (self `<gtk-image>')
          (pixbuf `<gdk-pixbuf>')
 -- Method: set-from-pixbuf
     See `gtk-image-new-from-pixbuf' for details.

    IMAGE
          a `<gtk-image>'

    PIXBUF
          a `<gdk-pixbuf>' or ``#f''



 -- Function: gtk-image-set-from-pixmap (self `<gtk-image>')
          (pixmap `<gdk-pixmap>') (mask `<gdk-drawable>')
 -- Method: set-from-pixmap
     See `gtk-image-new-from-pixmap' for details.

    IMAGE
          a `<gtk-image>'

    PIXMAP
          a `<gdk-pixmap>' or ``#f''

    MASK
          a `<gdk-bitmap>' or ``#f''



 -- Function: gtk-image-set-from-stock (self `<gtk-image>')
          (stock_id `mchars') (size `<gtk-icon-size>')
 -- Method: set-from-stock
     See `gtk-image-new-from-stock' for details.

    IMAGE
          a `<gtk-image>'

    STOCK-ID
          a stock icon name

    SIZE
          a stock icon size



 -- Function: gtk-image-set-from-animation (self `<gtk-image>')
          (animation `<gdk-pixbuf-animation>')
 -- Method: set-from-animation
     Causes the `<gtk-image>' to display the given animation (or display
     nothing, if you set the animation to ``#f'').

    IMAGE
          a `<gtk-image>'

    ANIMATION
          the `<gdk-pixbuf-animation>'



 -- Function: gtk-image-set-from-icon-name (self `<gtk-image>')
          (icon_name `mchars') (size `<gtk-icon-size>')
 -- Method: set-from-icon-name
     See `gtk-image-new-from-icon-name' for details.

    IMAGE
          a `<gtk-image>'

    ICON-NAME
          an icon name

    SIZE
          an icon size


     Since 2.6


 -- Function: gtk-image-clear (self `<gtk-image>')
 -- Method: clear
     Resets the image to be empty.

    IMAGE
          a `<gtk-image>'


     Since 2.8


 -- Function: gtk-image-new =>  (ret `<gtk-widget>')
     Creates a new empty `<gtk-image>' widget.

    RET
          a newly created `<gtk-image>' widget.



 -- Function: gtk-image-set-pixel-size (self `<gtk-image>')
          (pixel_size `int')
 -- Method: set-pixel-size
     Sets the pixel size to use for named icons. If the pixel size is
     set to a value != -1, it is used instead of the icon size set by
     `gtk-image-set-from-icon-name'.

    IMAGE
          a `<gtk-image>'

    PIXEL-SIZE
          the new pixel size


     Since 2.6


 -- Function: gtk-image-get-pixel-size (self `<gtk-image>') => 
          (ret `int')
 -- Method: get-pixel-size
     Gets the pixel size used for named icons.

    IMAGE
          a `<gtk-image>'

    RET
          the pixel size used for named icons.


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkLabel,  Next: GtkProgressBar,  Prev: GtkImage,  Up: Top

11 GtkLabel
***********

A widget that displays a small to medium amount of text

11.1 Overview
=============

The `<gtk-label>' widget displays a small amount of text. As the name
implies, most labels are used to label another widget such as a
`<gtk-button>', a `<gtk-menu-item>', or a `<gtk-option-menu>'.

11.2 Mnemonics
==============

Labels may contain "mnemonics". Mnemonics are underlined characters in
the label, used for keyboard navigation. Mnemonics are created by
providing a string with an underscore before the mnemonic character,
such as `"_File"', to the functions `gtk-label-new-with-mnemonic' or
`gtk-label-set-text-with-mnemonic'.

   Mnemonics automatically activate any activatable widget the label is
inside, such as a `<gtk-button>'; if the label is not inside the
mnemonic's target widget, you have to tell the label about the target
using `gtk-label-set-mnemonic-widget'. Here's a simple example where
the label is inside a button: There's a convenience function to create
buttons with a mnemonic label already inside: To create a mnemonic for
a widget alongside the label, such as a `<gtk-entry>', you have to
point the label at the entry with `gtk-label-set-mnemonic-widget':


       /* Pressing Alt+H will activate this button */
       button = gtk_button_new ();
       label = gtk_label_new_with_mnemonic ("_Hello");
       gtk_container_add (GTK_CONTAINER (button), label);


       /* Pressing Alt+H will activate this button */
       button = gtk_button_new_with_mnemonic ("_Hello");


       /* Pressing Alt+H will focus the entry */
       entry = gtk_entry_new ();
       label = gtk_label_new_with_mnemonic ("_Hello");
       gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);

11.3 Markup (styled text)
=========================

To make it easy to format text in a label (changing colors, fonts,
etc.), label text can be provided in a simple markup format. Here's how
to create a label with a small font: (See complete documentation of
available tags in the Pango manual.)


       label = gtk_label_new (NULL);
       gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");

   The markup passed to `gtk-label-set-markup' must be valid; for
example, literal </>/& characters must be escaped as &lt;, &gt;, and
&amp;. If you pass text obtained from the user, file, or a network to
`gtk-label-set-markup', you'll want to escape it with
`g-markup-escape-text' or `g-markup-printf-escaped'.

   Markup strings are just a convenient way to set the
`<pango-attr-list>' on a label; `gtk-label-set-attributes' may be a
simpler way to set attributes in some cases. Be careful though;
`<pango-attr-list>' tends to cause internationalization problems,
unless you're applying attributes to the entire string (i.e. unless you
set the range of each attribute to [0, G_MAXINT)). The reason is that
specifying the start_index and end_index for a `<pango-attribute>'
requires knowledge of the exact string being displayed, so translations
will cause problems.

11.4 Selectable labels
======================

Labels can be made selectable with `gtk-label-set-selectable'.
Selectable labels allow the user to copy the label contents to the
clipboard. Only labels that contain useful-to-copy information &#x2014;
such as error messages &#x2014; should be made selectable.

11.5 Text layout
================

A label can contain any number of paragraphs, but will have performance
problems if it contains more than a small number. Paragraphs are
separated by newlines or other paragraph separators understood by Pango.

   Labels can automatically wrap text if you call
`gtk-label-set-line-wrap'.

   `gtk-label-set-justify' sets how the lines in a label align with one
another. If you want to set how the label as a whole aligns in its
available space, see `gtk-misc-set-alignment'.

11.6 Usage
==========

 -- Class: <gtk-label>
     Derives from `<gtk-misc>'.

     This class defines the following properties:

    `label'
          The text of the label

    `attributes'
          A list of style attributes to apply to the text of the label

    `use-markup'
          The text of the label includes XML markup. See
          pango_parse_markup()

    `use-underline'
          If set, an underline in the text indicates the next character
          should be used for the mnemonic accelerator key

    `justify'
          The alignment of the lines in the text of the label relative
          to each other. This does NOT affect the alignment of the
          label within its allocation. See GtkMisc::xalign for that

    `pattern'
          A string with _ characters in positions correspond to
          characters in the text to underline

    `wrap'
          If set, wrap lines if the text becomes too wide

    `wrap-mode'
          If wrap is set, controls how linewrapping is done

    `selectable'
          Whether the label text can be selected with the mouse

    `mnemonic-keyval'
          The mnemonic accelerator key for this label

    `mnemonic-widget'
          The widget to be activated when the label's mnemonic key is
          pressed

    `cursor-position'
          The current position of the insertion cursor in chars

    `selection-bound'
          The position of the opposite end of the selection from the
          cursor in chars

    `ellipsize'
          The preferred place to ellipsize the string, if the label
          does not have enough room to display the entire string

    `width-chars'
          The desired width of the label, in characters

    `single-line-mode'
          Whether the label is in single line mode

    `angle'
          Angle at which the label is rotated

    `max-width-chars'
          The desired maximum width of the label, in characters



 -- Signal on <gtk-label>: move-cursor (arg0 `<gtk-movement-step>')
          (arg1 `<gint>') (arg2 `<gboolean>')

 -- Signal on <gtk-label>: copy-clipboard

 -- Signal on <gtk-label>: populate-popup (arg0 `<gtk-menu>')

 -- Function: gtk-label-new (str `mchars') =>  (ret `<gtk-widget>')
     Creates a new label with the given text inside it. You can pass
     ``#f'' to get an empty label widget.

    STR
          The text of the label

    RET
          the new `<gtk-label>'



 -- Function: gtk-label-set-text (self `<gtk-label>') (str `mchars')
 -- Method: set-text
     Sets the text within the `<gtk-label>' widget. It overwrites any
     text that was there before.

     This will also clear any previously set mnemonic accelerators.

    LABEL
          a `<gtk-label>'

    STR
          The text you want to set.



 -- Function: gtk-label-set-attributes (self `<gtk-label>')
          (attrs `<pango-attr-list>')
 -- Method: set-attributes
     Sets a `<pango-attr-list>'; the attributes in the list are applied
     to the label text. The attributes set with this function will be
     ignored if the "use_underline" property or the "use_markup"
     property is ``#t''.

    LABEL
          a `<gtk-label>'

    ATTRS
          a `<pango-attr-list>'



 -- Function: gtk-label-set-markup (self `<gtk-label>') (str `mchars')
 -- Method: set-markup
     Parses STR which is marked up with the Pango text markup language,
     setting the label's text and attribute list based on the parse
     results. If the STR is external data, you may need to escape it
     with `g-markup-escape-text' or `g-markup-printf-escaped':


          char *markup;

          markup = g_markup_printf_escaped ("<span style=\"italic\">%s</span>", str);
          gtk_label_set_markup (GTK_LABEL (label), markup);
          g_free (markup);

    LABEL
          a `<gtk-label>'

    STR
          a markup string (see Pango markup format)



 -- Function: gtk-label-set-markup-with-mnemonic (self `<gtk-label>')
          (str `mchars')
 -- Method: set-markup-with-mnemonic
     Parses STR which is marked up with the Pango text markup language,
     setting the label's text and attribute list based on the parse
     results. If characters in STR are preceded by an underscore, they
     are underlined indicating that they represent a keyboard
     accelerator called a mnemonic.

     The mnemonic key can be used to activate another widget, chosen
     automatically, or explicitly using `gtk-label-set-mnemonic-widget'.

    LABEL
          a `<gtk-label>'

    STR
          a markup string (see Pango markup format)



 -- Function: gtk-label-set-pattern (self `<gtk-label>')
          (pattern `mchars')
 -- Method: set-pattern
     The pattern of underlines you want under the existing text within
     the `<gtk-label>' widget. For example if the current text of the
     label says "FooBarBaz" passing a pattern of "___ ___" will
     underline "Foo" and "Baz" but not "Bar".

    LABEL
          The `<gtk-label>' you want to set the pattern to.

    PATTERN
          The pattern as described above.



 -- Function: gtk-label-set-justify (self `<gtk-label>')
          (jtype `<gtk-justification>')
 -- Method: set-justify
     Sets the alignment of the lines in the text of the label relative
     to each other.  `GTK_JUSTIFY_LEFT' is the default value when the
     widget is first created with `gtk-label-new'. If you instead want
     to set the alignment of the label as a whole, use
     `gtk-misc-set-alignment' instead.  `gtk-label-set-justify' has no
     effect on labels containing only a single line.

    LABEL
          a `<gtk-label>'

    JTYPE
          a `<gtk-justification>'



 -- Function: gtk-label-set-ellipsize (self `<gtk-label>')
          (mode `<pango-ellipsize-mode>')
 -- Method: set-ellipsize
     Sets the mode used to ellipsize (add an ellipsis: "...") to the
     text if there is not enough space to render the entire string.

    LABEL
          a `<gtk-label>'

    MODE
          a `<pango-ellipsize-mode>'


     Since 2.6


 -- Function: gtk-label-set-width-chars (self `<gtk-label>')
          (n_chars `int')
 -- Method: set-width-chars
     Sets the desired width in characters of LABEL to N-CHARS.

    LABEL
          a `<gtk-label>'

    N-CHARS
          the new desired width, in characters.


     Since 2.6


 -- Function: gtk-label-set-max-width-chars (self `<gtk-label>')
          (n_chars `int')
 -- Method: set-max-width-chars
     Sets the desired maximum width in characters of LABEL to N-CHARS.

    LABEL
          a `<gtk-label>'

    N-CHARS
          the new desired maximum width, in characters.


     Since 2.6


 -- Function: gtk-label-set-line-wrap (self `<gtk-label>') (wrap `bool')
 -- Method: set-line-wrap
     Toggles line wrapping within the `<gtk-label>' widget. ``#t''
     makes it break lines if text exceeds the widget's size. ``#f'' lets
     the text get cut off by the edge of the widget if it exceeds the
     widget size.

     Note that setting line wrapping to ``#t'' does not make the label
     wrap at its parent container's width, because GTK+ widgets
     conceptually can't make their requisition depend on the parent
     container's size. For a label that wraps at a specific position,
     set the label's width using `gtk-widget-set-size-request'.

    LABEL
          a `<gtk-label>'

    WRAP
          the setting



 -- Function: gtk-label-set-line-wrap-mode (self `<gtk-label>')
          (wrap_mode `<pango-wrap-mode>')
 -- Method: set-line-wrap-mode
     If line wrapping is on (see `gtk-label-set-line-wrap') this
     controls how the line wrapping is done. The default is
     `PANGO_WRAP_WORD' which means wrap on word boundaries.

    LABEL
          a `<gtk-label>'

    WRAP-MODE
          the line wrapping mode


     Since 2.10


 -- Function: gtk-label-get-layout-offsets (self `<gtk-label>') => 
          (x `int') (y `int')
 -- Method: get-layout-offsets
     Obtains the coordinates where the label will draw the
     `<pango-layout>' representing the text in the label; useful to
     convert mouse events into coordinates inside the `<pango-layout>',
     e.g. to take some action if some part of the label is clicked. Of
     course you will need to create a `<gtk-event-box>' to receive the
     events, and pack the label inside it, since labels are a
     `<gtk-no-window>' widget. Remember when using the `<pango-layout>'
     functions you need to convert to and from pixels using
     `pango-pixels' or `<pango-scale>'.

    LABEL
          a `<gtk-label>'

    X
          location to store X offset of layout, or ``#f''

    Y
          location to store Y offset of layout, or ``#f''



 -- Function: gtk-label-get-mnemonic-keyval (self `<gtk-label>') => 
          (ret `unsigned-int')
 -- Method: get-mnemonic-keyval
     If the label has been set so that it has an mnemonic key this
     function returns the keyval used for the mnemonic accelerator. If
     there is no mnemonic set up it returns `<gdk--void-symbol>'.

    LABEL
          a `<gtk-label>'

    RET
          GDK keyval usable for accelerators, or `<gdk--void-symbol>'



 -- Function: gtk-label-get-selectable (self `<gtk-label>') => 
          (ret `bool')
 -- Method: get-selectable
     Gets the value set by `gtk-label-set-selectable'.

    LABEL
          a `<gtk-label>'

    RET
          ``#t'' if the user can copy text from the label



 -- Function: gtk-label-get-text (self `<gtk-label>') =>  (ret `mchars')
 -- Method: get-text
     Fetches the text from a label widget, as displayed on the screen.
     This does not include any embedded underlines indicating mnemonics
     or Pango markup. (See `gtk-label-get-label')

    LABEL
          a `<gtk-label>'

    RET
          the text in the label widget. This is the internal string
          used by the label, and must not be modified.



 -- Function: gtk-label-new-with-mnemonic (str `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-label>', containing the text in STR.

     If characters in STR are preceded by an underscore, they are
     underlined.  If you need a literal underscore character in a
     label, use '__' (two underscores). The first underlined character
     represents a keyboard accelerator called a mnemonic. The mnemonic
     key can be used to activate another widget, chosen automatically,
     or explicitly using `gtk-label-set-mnemonic-widget'.

     If `gtk-label-set-mnemonic-widget' is not called, then the first
     activatable ancestor of the `<gtk-label>' will be chosen as the
     mnemonic widget. For instance, if the label is inside a button or
     menu item, the button or menu item will automatically become the
     mnemonic widget and be activated by the mnemonic.

    STR
          The text of the label, with an underscore in front of the
          mnemonic character

    RET
          the new `<gtk-label>'



 -- Function: gtk-label-select-region (self `<gtk-label>')
          (start_offset `int') (end_offset `int')
 -- Method: select-region
     Selects a range of characters in the label, if the label is
     selectable. See `gtk-label-set-selectable'. If the label is not
     selectable, this function has no effect. If START-OFFSET or
     END-OFFSET are -1, then the end of the label will be substituted.

    LABEL
          a `<gtk-label>'

    START-OFFSET
          start offset (in characters not bytes)

    END-OFFSET
          end offset (in characters not bytes)



 -- Function: gtk-label-set-mnemonic-widget (self `<gtk-label>')
          (widget `<gtk-widget>')
 -- Method: set-mnemonic-widget
     If the label has been set so that it has an mnemonic key (using
     i.e.  `gtk-label-set-markup-with-mnemonic',
     `gtk-label-set-text-with-mnemonic', `gtk-label-new-with-mnemonic'
     or the "use_underline" property) the label can be associated with
     a widget that is the target of the mnemonic. When the label is
     inside a widget (like a `<gtk-button>' or a `<gtk-notebook>' tab)
     it is automatically associated with the correct widget, but
     sometimes (i.e. when the target is a `<gtk-entry>' next to the
     label) you need to set it explicitly using this function.

     The target widget will be accelerated by emitting
     "mnemonic_activate" on it. The default handler for this signal
     will activate the widget if there are no mnemonic collisions and
     toggle focus between the colliding widgets otherwise.

    LABEL
          a `<gtk-label>'

    WIDGET
          the target `<gtk-widget>'



 -- Function: gtk-label-set-selectable (self `<gtk-label>')
          (setting `bool')
 -- Method: set-selectable
     Selectable labels allow the user to select text from the label, for
     copy-and-paste.

    LABEL
          a `<gtk-label>'

    SETTING
          ``#t'' to allow selecting text in the label



 -- Function: gtk-label-set-text-with-mnemonic (self `<gtk-label>')
          (str `mchars')
 -- Method: set-text-with-mnemonic
     Sets the label's text from the string STR. If characters in STR are
     preceded by an underscore, they are underlined indicating that
     they represent a keyboard accelerator called a mnemonic. The
     mnemonic key can be used to activate another widget, chosen
     automatically, or explicitly using `gtk-label-set-mnemonic-widget'.

    LABEL
          a `<gtk-label>'

    STR
          a string



 -- Function: gtk-label-get-attributes (self `<gtk-label>') => 
          (ret `<pango-attr-list>')
 -- Method: get-attributes
     Gets the attribute list that was set on the label using
     `gtk-label-set-attributes', if any. This function does not reflect
     attributes that come from the labels markup (see
     `gtk-label-set-markup').  If you want to get the effective
     attributes for the label, use pango_layout_get_attribute
     (gtk_label_get_layout (label)).

    LABEL
          a `<gtk-label>'

    RET
          the attribute list, or ``#f'' if none was set.



 -- Function: gtk-label-get-justify (self `<gtk-label>') => 
          (ret `<gtk-justification>')
 -- Method: get-justify
     Returns the justification of the label. See
     `gtk-label-set-justify'.

    LABEL
          a `<gtk-label>'

    RET
          `<gtk-justification>'



 -- Function: gtk-label-get-ellipsize (self `<gtk-label>') => 
          (ret `<pango-ellipsize-mode>')
 -- Method: get-ellipsize
     Returns the ellipsizing position of the label. See
     `gtk-label-set-ellipsize'.

    LABEL
          a `<gtk-label>'

    RET
          `<pango-ellipsize-mode>'


     Since 2.6


 -- Function: gtk-label-get-width-chars (self `<gtk-label>') => 
          (ret `int')
 -- Method: get-width-chars
     Retrieves the desired width of LABEL, in characters. See
     `gtk-label-set-width-chars'.

    LABEL
          a `<gtk-label>'

    RET
          the width of the label in characters.


     Since 2.6


 -- Function: gtk-label-get-max-width-chars (self `<gtk-label>') => 
          (ret `int')
 -- Method: get-max-width-chars
     Retrieves the desired maximum width of LABEL, in characters. See
     `gtk-label-set-width-chars'.

    LABEL
          a `<gtk-label>'

    RET
          the maximum width of the label in characters.


     Since 2.6


 -- Function: gtk-label-get-label (self `<gtk-label>') => 
          (ret `mchars')
 -- Method: get-label
     Fetches the text from a label widget including any embedded
     underlines indicating mnemonics and Pango markup. (See
     `gtk-label-get-text').

    LABEL
          a `<gtk-label>'

    RET
          the text of the label widget. This string is owned by the
          widget and must not be modified or freed.



 -- Function: gtk-label-get-layout (self `<gtk-label>') => 
          (ret `<pango-layout>')
 -- Method: get-layout
     Gets the `<pango-layout>' used to display the label. The layout is
     useful to e.g. convert text positions to pixel positions, in
     combination with `gtk-label-get-layout-offsets'. The returned
     layout is owned by the label so need not be freed by the caller.

    LABEL
          a `<gtk-label>'

    RET
          the `<pango-layout>' for this label



 -- Function: gtk-label-get-line-wrap (self `<gtk-label>') => 
          (ret `bool')
 -- Method: get-line-wrap
     Returns whether lines in the label are automatically wrapped. See
     `gtk-label-set-line-wrap'.

    LABEL
          a `<gtk-label>'

    RET
          ``#t'' if the lines of the label are automatically wrapped.



 -- Function: gtk-label-get-line-wrap-mode (self `<gtk-label>') => 
          (ret `<pango-wrap-mode>')
 -- Method: get-line-wrap-mode
     Returns line wrap mode used by the label. See
     `gtk-label-set-line-wrap-mode'.

    LABEL
          a `<gtk-label>'

    RET
          ``#t'' if the lines of the label are automatically wrapped.


     Since 2.10


 -- Function: gtk-label-get-mnemonic-widget (self `<gtk-label>') => 
          (ret `<gtk-widget>')
 -- Method: get-mnemonic-widget
     Retrieves the target of the mnemonic (keyboard shortcut) of this
     label. See `gtk-label-set-mnemonic-widget'.

    LABEL
          a `<gtk-label>'

    RET
          the target of the label's mnemonic, or ``#f'' if none has
          been set and the default algorithm will be used.



 -- Function: gtk-label-get-selection-bounds (self `<gtk-label>') => 
          (ret `bool') (start `int') (end `int')
 -- Method: get-selection-bounds
     Gets the selected range of characters in the label, returning
     ``#t'' if there's a selection.

    LABEL
          a `<gtk-label>'

    START
          return location for start of selection, as a character offset

    END
          return location for end of selection, as a character offset

    RET
          ``#t'' if selection is non-empty



 -- Function: gtk-label-get-use-markup (self `<gtk-label>') => 
          (ret `bool')
 -- Method: get-use-markup
     Returns whether the label's text is interpreted as marked up with
     the Pango text markup language. See `gtk-label-set-use-markup'.

    LABEL
          a `<gtk-label>'

    RET
          ``#t'' if the label's text will be parsed for markup.



 -- Function: gtk-label-get-use-underline (self `<gtk-label>') => 
          (ret `bool')
 -- Method: get-use-underline
     Returns whether an embedded underline in the label indicates a
     mnemonic. See `gtk-label-set-use-underline'.

    LABEL
          a `<gtk-label>'

    RET
          ``#t'' whether an embedded underline in the label indicates
          the mnemonic accelerator keys.



 -- Function: gtk-label-get-single-line-mode (self `<gtk-label>') => 
          (ret `bool')
 -- Method: get-single-line-mode
     Returns whether the label is in single line mode.

    LABEL
          a `<gtk-label>'

    RET
          ``#t'' when the label is in single line mode.


     Since 2.6


 -- Function: gtk-label-get-angle (self `<gtk-label>') => 
          (ret `double')
 -- Method: get-angle
     Gets the angle of rotation for the label. See gtk_label_set_angle.

    LABEL
          a `<gtk-label>'

    RET
          the angle of rotation for the label


     Since 2.6


 -- Function: gtk-label-set-label (self `<gtk-label>') (str `mchars')
 -- Method: set-label
     Sets the text of the label. The label is interpreted as including
     embedded underlines and/or Pango markup depending on the values of
     label->use_underline and label->use_markup.

    LABEL
          a `<gtk-label>'

    STR
          the new text to set for the label



 -- Function: gtk-label-set-use-markup (self `<gtk-label>')
          (setting `bool')
 -- Method: set-use-markup
     Sets whether the text of the label contains markup in Pango's text
     markup language. See `gtk-label-set-markup'.

    LABEL
          a `<gtk-label>'

    SETTING
          ``#t'' if the label's text should be parsed for markup.



 -- Function: gtk-label-set-use-underline (self `<gtk-label>')
          (setting `bool')
 -- Method: set-use-underline
     If true, an underline in the text indicates the next character
     should be used for the mnemonic accelerator key.

    LABEL
          a `<gtk-label>'

    SETTING
          ``#t'' if underlines in the text indicate mnemonics



 -- Function: gtk-label-set-single-line-mode (self `<gtk-label>')
          (single_line_mode `bool')
 -- Method: set-single-line-mode
     Sets whether the label is in single line mode.

    LABEL
          a `<gtk-label>'

    SINGLE-LINE-MODE
          ``#t'' if the label should be in single line mode


     Since 2.6


 -- Function: gtk-label-set-angle (self `<gtk-label>') (angle `double')
 -- Method: set-angle
     Sets the angle of rotation for the label. An angle of 90 reads
     from from bottom to top, an angle of 270, from top to bottom. The
     angle setting for the label is ignored if the label is selectable,
     wrapped, or ellipsized.

    LABEL
          a `<gtk-label>'

    ANGLE
          the angle that the baseline of the label makes with the
          horizontal, in degrees, measured counterclockwise


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkProgressBar,  Next: GtkStatusbar,  Prev: GtkLabel,  Up: Top

12 GtkProgressBar
*****************

A widget which indicates progress visually

12.1 Overview
=============

The `<gtk-progress-bar>' is typically used to display the progress of a
long running operation. It provides a visual clue that processing is
underway.  The `<gtk-progress-bar>' can be used in two different modes:
percentage mode and activity mode.

   When an application can determine how much work needs to take place
(e.g. read a fixed number of bytes from a file) and can monitor its
progress, it can use the `<gtk-progress-bar>' in percentage mode and
the user sees a growing bar indicating the percentage of the work that
has been completed. In this mode, the application is required to call
`gtk-progress-bar-set-fraction' periodically to update the progress bar.

   When an application has no accurate way of knowing the amount of
work to do, it can use the `<gtk-progress-bar>' in activity mode, which
shows activity by a block moving back and forth within the progress
area. In this mode, the application is required to call
`gtk-progress-bar-pulse' perodically to update the progress bar.

   There is quite a bit of flexibility provided to control the
appearance of the `<gtk-progress-bar>'. Functions are provided to
control the orientation of the bar, optional text can be displayed
along with the bar, and the step size used in activity mode can be set.

   The `<gtk-progress-bar>'/`<gtk-progress>' API in GTK 1.2 was bloated,
needlessly complex and hard to use properly. Therefore `<gtk-progress>'
has been deprecated completely and the `<gtk-progress-bar>' API has been
reduced to the following 10 functions: `gtk-progress-bar-new',
`gtk-progress-bar-pulse', `gtk-progress-bar-set-text',
`gtk-progress-bar-set-fraction', `gtk-progress-bar-set-pulse-step',
`gtk-progress-bar-set-orientation', `gtk-progress-bar-get-text',
`gtk-progress-bar-get-fraction', `gtk-progress-bar-get-pulse-step',
`gtk-progress-bar-get-orientation'. These have been grouped at the
beginning of this section, followed by a large chunk of deprecated 1.2
compatibility functions.

12.2 Usage
==========

 -- Class: <gtk-progress-bar>
     Derives from `<gtk-progress>'.

     This class defines the following properties:

    `fraction'
          The fraction of total work that has been completed

    `pulse-step'
          The fraction of total progress to move the bouncing block
          when pulsed

    `orientation'
          Orientation and growth direction of the progress bar

    `text'
          Text to be displayed in the progress bar

    `ellipsize'
          The preferred place to ellipsize the string, if the progress
          bar does not have enough room to display the entire string,
          if at all.

    `adjustment'
          The GtkAdjustment connected to the progress bar (Deprecated)

    `bar-style'
          Specifies the visual style of the bar in percentage mode
          (Deprecated)

    `activity-step'
          The increment used for each iteration in activity mode
          (Deprecated)

    `activity-blocks'
          The number of blocks which can fit in the progress bar area
          in activity mode (Deprecated)

    `discrete-blocks'
          The number of discrete blocks in a progress bar (when shown
          in the discrete style)



 -- Function: gtk-progress-bar-new =>  (ret `<gtk-widget>')
     Creates a new `<gtk-progress-bar>'.

    RET
          a `<gtk-progress-bar>'.



 -- Function: gtk-progress-bar-pulse (self `<gtk-progress-bar>')
 -- Method: pulse
     Indicates that some progress is made, but you don't know how much.
     Causes the progress bar to enter "activity mode," where a block
     bounces back and forth.  Each call to `gtk-progress-bar-pulse'
     causes the block to move by a little bit (the amount of movement
     per pulse is determined by `gtk-progress-bar-set-pulse-step').

    PBAR
          a `<gtk-progress-bar>'



 -- Function: gtk-progress-bar-set-text (self `<gtk-progress-bar>')
          (text `mchars')
 -- Method: set-text
     Causes the given TEXT to appear superimposed on the progress bar.

    PBAR
          a `<gtk-progress-bar>'

    TEXT
          a UTF-8 string, or ``#f''



 -- Function: gtk-progress-bar-set-fraction (self `<gtk-progress-bar>')
          (fraction `double')
 -- Method: set-fraction
     Causes the progress bar to "fill in" the given fraction of the
     bar. The fraction should be between 0.0 and 1.0, inclusive.

    PBAR
          a `<gtk-progress-bar>'

    FRACTION
          fraction of the task that's been completed



 -- Function: gtk-progress-bar-set-pulse-step
          (self `<gtk-progress-bar>') (fraction `double')
 -- Method: set-pulse-step
     Sets the fraction of total progress bar length to move the
     bouncing block for each call to `gtk-progress-bar-pulse'.

    PBAR
          a `<gtk-progress-bar>'

    FRACTION
          fraction between 0.0 and 1.0



 -- Function: gtk-progress-bar-set-orientation
          (self `<gtk-progress-bar>')
          (orientation `<gtk-progress-bar-orientation>')
 -- Method: set-orientation
     Causes the progress bar to switch to a different orientation
     (left-to-right, right-to-left, top-to-bottom, or bottom-to-top).

    PBAR
          a `<gtk-progress-bar>'

    ORIENTATION
          orientation of the progress bar



 -- Function: gtk-progress-bar-set-ellipsize
          (self `<gtk-progress-bar>') (mode `<pango-ellipsize-mode>')
 -- Method: set-ellipsize
     Sets the mode used to ellipsize (add an ellipsis: "...") the text
     if there is not enough space to render the entire string.

    PBAR
          a `<gtk-progress-bar>'

    MODE
          a `<pango-ellipsize-mode>'


     Since 2.6


 -- Function: gtk-progress-bar-get-text (self `<gtk-progress-bar>') => 
          (ret `mchars')
 -- Method: get-text
     Retrieves the text displayed superimposed on the progress bar, if
     any, otherwise ``#f''. The return value is a reference to the
     text, not a copy of it, so will become invalid if you change the
     text in the progress bar.

    PBAR
          a `<gtk-progress-bar>'

    RET
          text, or ``#f''; this string is owned by the widget and
          should not be modified or freed.



 -- Function: gtk-progress-bar-get-fraction (self `<gtk-progress-bar>')
          =>  (ret `double')
 -- Method: get-fraction
     Returns the current fraction of the task that's been completed.

    PBAR
          a `<gtk-progress-bar>'

    RET
          a fraction from 0.0 to 1.0



 -- Function: gtk-progress-bar-get-pulse-step
          (self `<gtk-progress-bar>') =>  (ret `double')
 -- Method: get-pulse-step
     Retrieves the pulse step set with `gtk-progress-bar-set-pulse-step'

    PBAR
          a `<gtk-progress-bar>'

    RET
          a fraction from 0.0 to 1.0



 -- Function: gtk-progress-bar-get-ellipsize
          (self `<gtk-progress-bar>') =>  (ret `<pango-ellipsize-mode>')
 -- Method: get-ellipsize
     Returns the ellipsizing position of the progressbar. See
     `gtk-progress-bar-set-ellipsize'.

    PBAR
          a `<gtk-progress-bar>'

    RET
          `<pango-ellipsize-mode>'


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkStatusbar,  Next: GtkStatusIcon,  Prev: GtkProgressBar,  Up: Top

13 GtkStatusbar
***************

Report messages of minor importance to the user

13.1 Overview
=============

A `<gtk-statusbar>' is usually placed along the bottom of an
application's main `<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.
This context_id can be generated by `gtk-statusbar-get-context-id',
given a message and the statusbar that it will be added to. 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
identifier of a message.

   Status bars are created using `gtk-statusbar-new'.

   Messages are added to the bar's stack with `gtk-statusbar-push'.

   The message at the top of the stack can be removed using
`gtk-statusbar-pop'. A message can be removed from anywhere in the
stack if its message_id was recorded at the time it was added. This is
done using `gtk-statusbar-remove'.

13.2 Usage
==========

 -- Class: <gtk-statusbar>
     Derives from `<gtk-hbox>'.

     This class defines the following properties:

    `has-resize-grip'
          Whether the statusbar has a grip for resizing the toplevel



 -- Signal on <gtk-statusbar>: text-pushed (arg0 `<guint>')
          (arg1 `<gchararray>')
     Is emitted whenever a new message gets pushed onto a statusbar's
     stack.


 -- Signal on <gtk-statusbar>: text-popped (arg0 `<guint>')
          (arg1 `<gchararray>')
     Is emitted whenever a new message is popped off a statusbar's
     stack.


 -- Function: gtk-statusbar-new =>  (ret `<gtk-widget>')
     Creates a new `<gtk-statusbar>' ready for messages.

    RET
          the new `<gtk-statusbar>'.



 -- Function: gtk-statusbar-get-context-id (self `<gtk-statusbar>')
          (context_description `mchars') =>  (ret `unsigned-int')
 -- Method: get-context-id
     Returns a new context identifier, given a description of the
     actual context.

    STATUSBAR
          a `<gtk-statusbar>'.

    CONTEXT-DESCRIPTION
          textual description of what context the new message is being
          used in.

    RET
          an integer id.



 -- Function: gtk-statusbar-push (self `<gtk-statusbar>')
          (context_id `unsigned-int') (text `mchars') => 
          (ret `unsigned-int')
 -- Method: push
     Pushes a new message onto a statusbar's stack.

    STATUSBAR
          a `<gtk-statusbar>'.

    CONTEXT-ID
          the message's context id, as returned by
          `gtk-statusbar-get-context-id'.

    TEXT
          the message to add to the statusbar.

    RET
          the message's new message id for use with
          `gtk-statusbar-remove'.



 -- Function: gtk-statusbar-pop (self `<gtk-statusbar>')
          (context_id `unsigned-int')
 -- Method: pop
     Removes the message at the top of a `<gtk-status-bar>''s stack.

    STATUSBAR
          a `<gtk-status-bar>'.

    CONTEXT-ID
          a context identifier.



 -- Function: gtk-statusbar-remove (self `<gtk-statusbar>')
          (context_id `unsigned-int') (message_id `unsigned-int')
 -- Method: remove
     Forces the removal of a message from a statusbar's stack. The exact
     CONTEXT-ID and MESSAGE-ID must be specified.

    STATUSBAR
          a `<gtk-status-bar>'.

    CONTEXT-ID
          a context identifier.

    MESSAGE-ID
          a message identifier, as returned by `gtk-statusbar-push'.



 -- Function: gtk-statusbar-set-has-resize-grip
          (self `<gtk-statusbar>') (setting `bool')
 -- Method: set-has-resize-grip
     Sets whether the statusbar has a resize grip. ``#t'' by default.

    STATUSBAR
          a `<gtk-status-bar>'.

    SETTING
          ``#t'' to have a resize grip.



 -- Function: gtk-statusbar-get-has-resize-grip
          (self `<gtk-statusbar>') =>  (ret `bool')
 -- Method: get-has-resize-grip
     Returns whether the statusbar has a resize grip.

    STATUSBAR
          a `<gtk-status-bar>'.

    RET
          ``#t'' if the statusbar has a resize grip.




File: guile-gnome-gtk.info,  Node: GtkStatusIcon,  Next: GtkButton,  Prev: GtkStatusbar,  Up: Top

14 GtkStatusIcon
****************

Display an icon in the system tray

14.1 Overview
=============

The "system tray" or notification area is normally used for transient
icons that indicate some special state. For example, a system tray icon
might appear to tell the user that they have new mail, or have an
incoming instant message, or something along those lines. The basic
idea is that creating an icon in the notification area is less annoying
than popping up a dialog.

   A `<gtk-status-icon>' object can be used to display an icon in a
"system tray". The icon can have a tooltip, and the user can interact
with it by activating it or popping up a context menu. Critical
information should not solely be displayed in a `<gtk-status-icon>',
since it may not be visible (e.g. when the user doesn't have a
notification area on his panel). This can be checked with
`gtk-status-icon-is-embedded'.

   On X11, the implementation follows the freedesktop.org "System Tray"
specification
(http://www.freedesktop.org/wiki/Standards/systemtray-spec).
Implementations of the "tray" side of this specification can be found
e.g. in the GNOME and KDE panel applications.

   Note that a GtkStatusIcon is _not_ a widget, but just a `<gobject>'.
Making it a widget would be impractical, since the system tray on Win32
doesn't allow to embed arbitrary widgets.

14.2 Usage
==========

 -- Class: <gtk-status-icon>
     Derives from `<gobject>'.

     This class defines the following properties:

    `pixbuf'
          A GdkPixbuf to display

    `file'
          Filename to load and display

    `stock'
          Stock ID for a stock image to display

    `icon-name'
          The name of the icon from the icon theme

    `storage-type'
          The representation being used for image data

    `size'
          The size of the icon

    `screen'
          The screen where this status icon will be displayed

    `visible'
          Whether or not the status icon is visible

    `orientation'
          The orientation of the tray

    `embedded'
          Whether or not the status icon is embedded

    `blinking'
          Whether or not the status icon is blinking



 -- Signal on <gtk-status-icon>: size-changed (arg0 `<gint>')
          => `<gboolean>'
     Gets emitted when the size available for the image changes, e.g.
     because the notification area got resized.

     Since 2.10


 -- Signal on <gtk-status-icon>: popup-menu (arg0 `<guint>')
          (arg1 `<guint>')
     Gets emitted when the user brings up the context menu of the
     status icon.  Whether status icons can have context menus and how
     these are activated is platform-dependent.

     The BUTTON and ACTIVATE-TIMEOUT parameters should be passed as the
     last to arguments to `gtk-menu-popup'.

     Since 2.10


 -- Signal on <gtk-status-icon>: activate
     Gets emitted when the user activates the status icon. If and how
     status icons can activated is platform-dependent.

     Since 2.10


 -- Function: gtk-status-icon-new =>  (ret `<gtk-status-icon>')
     Creates an empty status icon object.

    RET
          a new `<gtk-status-icon>'


     Since 2.10


 -- Function: gtk-status-icon-new-from-pixbuf (pixbuf `<gdk-pixbuf>')
          =>  (ret `<gtk-status-icon>')
     Creates a status icon displaying PIXBUF.

     The image will be scaled down to fit in the available space in the
     notification area, if necessary.

    PIXBUF
          a `<gdk-pixbuf>'

    RET
          a new `<gtk-status-icon>'


     Since 2.10


 -- Function: gtk-status-icon-new-from-file (filename `mchars') => 
          (ret `<gtk-status-icon>')
     Creates a status icon displaying the file FILENAME.

     The image will be scaled down to fit in the available space in the
     notification area, if necessary.

    FILENAME
          a filename

    RET
          a new `<gtk-status-icon>'


     Since 2.10


 -- Function: gtk-status-icon-new-from-stock (stock_id `mchars') => 
          (ret `<gtk-status-icon>')
     Creates a status icon displaying a stock icon. Sample stock icon
     names are `<gtk-stock-open>', `<gtk-stock-quit>'. You can register
     your own stock icon names, see `gtk-icon-factory-add-default' and
     `gtk-icon-factory-add'.

    STOCK-ID
          a stock icon id

    RET
          a new `<gtk-status-icon>'


     Since 2.10


 -- Function: gtk-status-icon-new-from-icon-name (icon_name `mchars')
          =>  (ret `<gtk-status-icon>')
     Creates a status icon displaying an icon from the current icon
     theme. If the current icon theme is changed, the icon will be
     updated appropriately.

    ICON-NAME
          an icon name

    RET
          a new `<gtk-status-icon>'


     Since 2.10


 -- Function: gtk-status-icon-set-from-pixbuf
          (self `<gtk-status-icon>') (pixbuf `<gdk-pixbuf>')
 -- Method: set-from-pixbuf
     Makes STATUS-ICON display PIXBUF. See
     `gtk-status-icon-new-from-pixbuf' for details.

    STATUS-ICON
          a `<gtk-status-icon>'

    PIXBUF
          a `<gdk-pixbuf>' or ``#f''


     Since 2.10


 -- Function: gtk-status-icon-set-from-file (self `<gtk-status-icon>')
          (filename `mchars')
 -- Method: set-from-file
     Makes STATUS-ICON display the file FILENAME. See
     `gtk-status-icon-new-from-file' for details.

    STATUS-ICON
          a `<gtk-status-icon>'

    FILENAME
          a filename


     Since 2.10


 -- Function: gtk-status-icon-set-from-stock (self `<gtk-status-icon>')
          (stock_id `mchars')
 -- Method: set-from-stock
     Makes STATUS-ICON display the stock icon with the id STOCK-ID. See
     `gtk-status-icon-new-from-stock' for details.

    STATUS-ICON
          a `<gtk-status-icon>'

    STOCK-ID
          a stock icon id


     Since 2.10


 -- Function: gtk-status-icon-set-from-icon-name
          (self `<gtk-status-icon>') (icon_name `mchars')
 -- Method: set-from-icon-name
     Makes STATUS-ICON display the icon named ICON-NAME from the current
     icon theme. See `gtk-status-icon-new-from-icon-name' for details.

    STATUS-ICON
          a `<gtk-status-icon>'

    ICON-NAME
          an icon name


     Since 2.10


 -- Function: gtk-status-icon-get-storage-type
          (self `<gtk-status-icon>') =>  (ret `<gtk-image-type>')
 -- Method: get-storage-type
     Gets the type of representation being used by the
     `<gtk-status-icon>' to store image data. If the
     `<gtk-status-icon>' has no image data, the return value will be
     `GTK_IMAGE_EMPTY'.

    STATUS-ICON
          a `<gtk-status-icon>'

    RET
          the image representation being used


     Since 2.10


 -- Function: gtk-status-icon-get-pixbuf (self `<gtk-status-icon>') => 
          (ret `<gdk-pixbuf>')
 -- Method: get-pixbuf
     Gets the `<gdk-pixbuf>' being displayed by the `<gtk-status-icon>'.
     The storage type of the status icon must be `GTK_IMAGE_EMPTY' or
     `GTK_IMAGE_PIXBUF' (see `gtk-status-icon-get-storage-type'). The
     caller of this function does not own a reference to the returned
     pixbuf.

    STATUS-ICON
          a `<gtk-status-icon>'

    RET
          the displayed pixbuf, or ``#f'' if the image is empty.


     Since 2.10


 -- Function: gtk-status-icon-get-stock (self `<gtk-status-icon>') => 
          (ret `mchars')
 -- Method: get-stock
     Gets the id of the stock icon being displayed by the
     `<gtk-status-icon>'.  The storage type of the status icon must be
     `GTK_IMAGE_EMPTY' or `GTK_IMAGE_STOCK' (see
     `gtk-status-icon-get-storage-type'). The returned string is owned
     by the `<gtk-status-icon>' and should not be freed or modified.

    STATUS-ICON
          a `<gtk-status-icon>'

    RET
          stock id of the displayed stock icon, or ``#f'' if the image
          is empty.


     Since 2.10


 -- Function: gtk-status-icon-get-icon-name (self `<gtk-status-icon>')
          =>  (ret `mchars')
 -- Method: get-icon-name
     Gets the name of the icon being displayed by the
     `<gtk-status-icon>'. The storage type of the status icon must be
     `GTK_IMAGE_EMPTY' or `GTK_IMAGE_ICON_NAME' (see
     `gtk-status-icon-get-storage-type'). The returned string is owned
     by the `<gtk-status-icon>' and should not be freed or modified.

    STATUS-ICON
          a `<gtk-status-icon>'

    RET
          name of the displayed icon, or ``#f'' if the image is empty.


     Since 2.10


 -- Function: gtk-status-icon-get-size (self `<gtk-status-icon>') => 
          (ret `int')
 -- Method: get-size
     Gets the size in pixels that is available for the image. Stock
     icons and named icons adapt their size automatically if the size
     of the notification area changes. For other storage types, the
     size-changed signal can be used to react to size changes.

    STATUS-ICON
          a `<gtk-status-icon>'

    RET
          the size that is available for the image


     Since 2.10


 -- Function: gtk-status-icon-set-tooltip (self `<gtk-status-icon>')
          (tooltip_text `mchars')
 -- Method: set-tooltip
     Sets the tooltip of the status icon.

    STATUS-ICON
          a `<gtk-status-icon>'

    TOOLTIP-TEXT
          the tooltip text, or ``#f''


     Since 2.10


 -- Function: gtk-status-icon-set-visible (self `<gtk-status-icon>')
          (visible `bool')
 -- Method: set-visible
     Shows or hides a status icon.

    STATUS-ICON
          a `<gtk-status-icon>'

    VISIBLE
          ``#t'' to show the status icon, ``#f'' to hide it


     Since 2.10


 -- Function: gtk-status-icon-get-visible (self `<gtk-status-icon>')
          =>  (ret `bool')
 -- Method: get-visible
     Returns whether the status icon is visible or not. Note that being
     visible does not guarantee that the user can actually see the
     icon, see also `gtk-status-icon-is-embedded'.

    STATUS-ICON
          a `<gtk-status-icon>'

    RET
          ``#t'' if the status icon is visible


     Since 2.10


 -- Function: gtk-status-icon-set-blinking (self `<gtk-status-icon>')
          (blinking `bool')
 -- Method: set-blinking
     Makes the status icon start or stop blinking. Note that blinking
     user interface elements may be problematic for some users, and
     thus may be turned off, in which case this setting has no effect.

    STATUS-ICON
          a `<gtk-status-icon>'

    BLINKING
          ``#t'' to turn blinking on, ``#f'' to turn it off


     Since 2.10


 -- Function: gtk-status-icon-get-blinking (self `<gtk-status-icon>')
          =>  (ret `bool')
 -- Method: get-blinking
     Returns whether the icon is blinking, see
     `gtk-status-icon-set-blinking'.

    STATUS-ICON
          a `<gtk-status-icon>'

    RET
          ``#t'' if the icon is blinking


     Since 2.10


 -- Function: gtk-status-icon-is-embedded (self `<gtk-status-icon>')
          =>  (ret `bool')
 -- Method: is-embedded
     Returns whether the status icon is embedded in a notification area.

    STATUS-ICON
          a `<gtk-status-icon>'

    RET
          ``#t'' if the status icon is embedded in a notification area.


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkButton,  Next: GtkCheckButton,  Prev: GtkStatusIcon,  Up: Top

15 GtkButton
************

A widget that creates a signal when clicked on

15.1 Overview
=============

The `<gtk-button>' widget is generally used to attach a function to
that is called when the button is pressed. The various signals and how
to use them are outlined below.

   The `<gtk-button>' widget can hold any valid child widget. That is
it can hold most any other standard `<gtk-widget>'. The most commonly
used child is the `<gtk-label>'.

15.2 Usage
==========

 -- Class: <gtk-button>
     Derives from `<gtk-bin>'.

     This class defines the following properties:

    `label'
          Text of the label widget inside the button, if the button
          contains a label widget

    `image'
          Child widget to appear next to the button text

    `relief'
          The border relief style

    `use-underline'
          If set, an underline in the text indicates the next character
          should be used for the mnemonic accelerator key

    `use-stock'
          If set, the label is used to pick a stock item instead of
          being displayed

    `focus-on-click'
          Whether the button grabs focus when it is clicked with the
          mouse

    `xalign'
          Horizontal position of child in available space. 0.0 is left
          aligned, 1.0 is right aligned

    `yalign'
          Vertical position of child in available space. 0.0 is top
          aligned, 1.0 is bottom aligned

    `image-position'
          The position of the image relative to the text



 -- Signal on <gtk-button>: activate
     The "activate" signal on GtkButton is an action signal and
     emitting it causes the button to animate press then release.
     Applications should never connect to this signal, but use the
     "clicked" signal.


 -- Signal on <gtk-button>: pressed
     Emitted when the button is pressed.

     DEPRECATED: Use the GtkWidget::button-press-event signal.


 -- Signal on <gtk-button>: released
     Emitted when the button is released.

     DEPRECATED: Use the GtkWidget::button-release-event signal.


 -- Signal on <gtk-button>: clicked
     Emitted when the button has been activated (pressed and released).


 -- Signal on <gtk-button>: enter
     Emitted when the pointer enters the button.

     DEPRECATED: Use the GtkWidget::enter-notify-event signal.


 -- Signal on <gtk-button>: leave
     Emitted when the pointer leaves the button.

     DEPRECATED: Use the GtkWidget::leave-notify-event signal.


 -- Function: gtk-button-new =>  (ret `<gtk-widget>')
     Creates a new `<gtk-button>' widget. To add a child widget to the
     button, use `gtk-container-add'.

    RET
          The newly created `<gtk-button>' widget.



 -- Function: gtk-button-new-with-label (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a `<gtk-button>' widget with a `<gtk-label>' child
     containing the given text.

    LABEL
          The text you want the `<gtk-label>' to hold.

    RET
          The newly created `<gtk-button>' widget.



 -- Function: gtk-button-new-with-mnemonic (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-button>' containing a label. If characters in
     LABEL are preceded by an underscore, they are underlined. If you
     need a literal underscore character in a label, use '__' (two
     underscores). The first underlined character represents a keyboard
     accelerator called a mnemonic.  Pressing Alt and that key
     activates the button.

    LABEL
          The text of the button, with an underscore in front of the
          mnemonic character

    RET
          a new `<gtk-button>'



 -- Function: gtk-button-new-from-stock (stock_id `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-button>' containing the image and text from a
     stock item. Some stock ids have preprocessor macros like
     `<gtk-stock-ok>' and `<gtk-stock-apply>'.

     If STOCK-ID is unknown, then it will be treated as a mnemonic
     label (as for `gtk-button-new-with-mnemonic').

    STOCK-ID
          the name of the stock item

    RET
          a new `<gtk-button>'



 -- Function: gtk-button-pressed (self `<gtk-button>')
 -- Method: pressed
     Emits a `<gtk-button::pressed>' signal to the given `<gtk-button>'.

    BUTTON
          The `<gtk-button>' you want to send the signal to.



 -- Function: gtk-button-released (self `<gtk-button>')
 -- Method: released
     Emits a `<gtk-button::released>' signal to the given
     `<gtk-button>'.

    BUTTON
          The `<gtk-button>' you want to send the signal to.



 -- Function: gtk-button-clicked (self `<gtk-button>')
 -- Method: clicked
     Emits a `<gtk-button::clicked>' signal to the given `<gtk-button>'.

    BUTTON
          The `<gtk-button>' you want to send the signal to.



 -- Function: gtk-button-enter (self `<gtk-button>')
 -- Method: enter
     Emits a `<gtk-button::enter>' signal to the given `<gtk-button>'.

    BUTTON
          The `<gtk-button>' you want to send the signal to.



 -- Function: gtk-button-leave (self `<gtk-button>')
 -- Method: leave
     Emits a `<gtk-button::leave>' signal to the given `<gtk-button>'.

    BUTTON
          The `<gtk-button>' you want to send the signal to.



 -- Function: gtk-button-set-relief (self `<gtk-button>')
          (newstyle `<gtk-relief-style>')
 -- Method: set-relief
     Sets the relief style of the edges of the given `<gtk-button>'
     widget.  Three styles exist, GTK_RELIEF_NORMAL, GTK_RELIEF_HALF,
     GTK_RELIEF_NONE. The default style is, as one can guess,
     GTK_RELIEF_NORMAL.

    BUTTON
          The `<gtk-button>' you want to set relief styles of.

    NEWSTYLE
          The GtkReliefStyle as described above.



 -- Function: gtk-button-get-relief (self `<gtk-button>') => 
          (ret `<gtk-relief-style>')
 -- Method: get-relief
     Returns the current relief style of the given `<gtk-button>'.

    BUTTON
          The `<gtk-button>' you want the `<gtk-relief-style>' from.

    RET
          The current `<gtk-relief-style>'



 -- Function: gtk-button-get-label (self `<gtk-button>') => 
          (ret `mchars')
 -- Method: get-label
     Fetches the text from the label of the button, as set by
     `gtk-button-set-label'. If the label text has not been set the
     return value will be ``#f''. This will be the case if you create
     an empty button with `gtk-button-new' to use as a container.

    BUTTON
          a `<gtk-button>'

    RET
          The text of the label widget. This string is owned by the
          widget and must not be modified or freed.



 -- Function: gtk-button-set-label (self `<gtk-button>')
          (label `mchars')
 -- Method: set-label
     Sets the text of the label of the button to STR. This text is also
     used to select the stock item if `gtk-button-set-use-stock' is
     used.

     This will also clear any previously set labels.

    BUTTON
          a `<gtk-button>'

    LABEL
          a string



 -- Function: gtk-button-get-use-stock (self `<gtk-button>') => 
          (ret `bool')
 -- Method: get-use-stock
     Returns whether the button label is a stock item.

    BUTTON
          a `<gtk-button>'

    RET
          ``#t'' if the button label is used to select a stock item
          instead of being used directly as the label text.



 -- Function: gtk-button-set-use-stock (self `<gtk-button>')
          (use_stock `bool')
 -- Method: set-use-stock
     If true, the label set on the button is used as a stock id to
     select the stock item for the button.

    BUTTON
          a `<gtk-button>'

    USE-STOCK
          ``#t'' if the button should use a stock item



 -- Function: gtk-button-get-use-underline (self `<gtk-button>') => 
          (ret `bool')
 -- Method: get-use-underline
     Returns whether an embedded underline in the button label
     indicates a mnemonic.  See `gtk-button-set-use-underline'.

    BUTTON
          a `<gtk-button>'

    RET
          ``#t'' if an embedded underline in the button label indicates
          the mnemonic accelerator keys.



 -- Function: gtk-button-set-use-underline (self `<gtk-button>')
          (use_underline `bool')
 -- Method: set-use-underline
     If true, an underline in the text of the button label indicates
     the next character should be used for the mnemonic accelerator key.

    BUTTON
          a `<gtk-button>'

    USE-UNDERLINE
          ``#t'' if underlines in the text indicate mnemonics



 -- Function: gtk-button-set-focus-on-click (self `<gtk-button>')
          (focus_on_click `bool')
 -- Method: set-focus-on-click
     Sets whether the button will grab focus when it is clicked with
     the mouse.  Making mouse clicks not grab focus is useful in places
     like toolbars where you don't want the keyboard focus removed from
     the main area of the application.

    BUTTON
          a `<gtk-button>'

    FOCUS-ON-CLICK
          whether the button grabs focus when clicked with the mouse


     Since 2.4


 -- Function: gtk-button-get-focus-on-click (self `<gtk-button>') => 
          (ret `bool')
 -- Method: get-focus-on-click
     Returns whether the button grabs focus when it is clicked with the
     mouse. See `gtk-button-set-focus-on-click'.

    BUTTON
          a `<gtk-button>'

    RET
          ``#t'' if the button grabs focus when it is clicked with the
          mouse.


     Since 2.4


 -- Function: gtk-button-set-alignment (self `<gtk-button>')
          (xalign `float') (yalign `float')
 -- Method: set-alignment
     Sets the alignment of the child. This property has no effect
     unless the child is a `<gtk-misc>' or a `<gtk-aligment>'.

    BUTTON
          a `<gtk-button>'

    XALIGN
          the horizontal position of the child, 0.0 is left aligned,
          1.0 is right aligned

    YALIGN
          the vertical position of the child, 0.0 is top aligned, 1.0
          is bottom aligned


     Since 2.4


 -- Function: gtk-button-get-alignment (self `<gtk-button>') => 
          (xalign `float') (yalign `float')
 -- Method: get-alignment
     Gets the alignment of the child in the button.

    BUTTON
          a `<gtk-button>'

    XALIGN
          return location for horizontal alignment

    YALIGN
          return location for vertical alignment


     Since 2.4


 -- Function: gtk-button-set-image (self `<gtk-button>')
          (image `<gtk-widget>')
 -- Method: set-image
     Set the image of BUTTON to the given widget. Note that it depends
     on the gtk-button-images setting whether the image will be
     displayed or not, you don't have to call `gtk-widget-show' on
     IMAGE yourself.

    BUTTON
          a `<gtk-button>'

    IMAGE
          a widget to set as the image for the button


     Since 2.6


 -- Function: gtk-button-get-image (self `<gtk-button>') => 
          (ret `<gtk-widget>')
 -- Method: get-image
     Gets the widget that is currenty set as the image of BUTTON. This
     may have been explicitly set by `gtk-button-set-image' or
     constructed by `gtk-button-new-from-stock'.

    BUTTON
          a `<gtk-button>'

    RET
          a `<gtk-widget>' or ``#f'' in case there is no image


     Since 2.6


 -- Function: gtk-button-set-image-position (self `<gtk-button>')
          (position `<gtk-position-type>')
 -- Method: set-image-position
     Sets the position of the image relative to the text inside the
     button.

    BUTTON
          a `<gtk-button>'

    POSITION
          the position


     Since 2.10


 -- Function: gtk-button-get-image-position (self `<gtk-button>') => 
          (ret `<gtk-position-type>')
 -- Method: get-image-position
     Gets the position of the image relative to the text inside the
     button.

    BUTTON
          a `<gtk-button>'

    RET
          the position


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkCheckButton,  Next: GtkRadioButton,  Prev: GtkButton,  Up: Top

16 GtkCheckButton
*****************

Create widgets with a discrete toggle button

16.1 Overview
=============

A `<gtk-check-button>' places a discrete `<gtk-toggle-button>' next to
a widget, (usually a `<gtk-label>'). See the section on
`<gtk-toggle-button>' widgets for more information about toggle/check
buttons.

   The important signal ('toggled') is also inherited from
`<gtk-toggle-button>'.

16.2 Usage
==========

 -- Class: <gtk-check-button>
     Derives from `<gtk-toggle-button>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gtk-check-button-new =>  (ret `<gtk-widget>')
     Creates a new `<gtk-check-button>'.

    RET
          a `<gtk-widget>'.



 -- Function: gtk-check-button-new-with-label (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-check-button>' with a `<gtk-label>' to the
     right of it.

    LABEL
          the text for the check button.

    RET
          a `<gtk-widget>'.



 -- Function: gtk-check-button-new-with-mnemonic (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-check-button>' containing a label. The label
     will be created using `gtk-label-new-with-mnemonic', so
     underscores in LABEL indicate the mnemonic for the check button.

    LABEL
          The text of the button, with an underscore in front of the
          mnemonic character

    RET
          a new `<gtk-check-button>'




File: guile-gnome-gtk.info,  Node: GtkRadioButton,  Next: GtkToggleButton,  Prev: GtkCheckButton,  Up: Top

17 GtkRadioButton
*****************

A choice from multiple check buttons

17.1 Overview
=============

A single radio button performs the same basic function as a
`<gtk-check-button>', as its position in the object hierarchy reflects.
It is only when multiple radio buttons are grouped together that they
become a different user interface component in their own right.

   Every radio button is a member of some group of radio buttons. When
one is selected, all other radio buttons in the same group are
deselected. A `<gtk-radio-button>' is one way of giving the user a
choice from many options.

   Radio button widgets are created with `gtk-radio-button-new',
passing NULL as the argument if this is the first radio button in a
group. In subsequent calls, the group you wish to add this button to
should be passed as an argument.  Optionally,
`gtk-radio-button-new-with-label' can be used if you want a text label
on the radio button.

   Alternatively, when adding widgets to an existing group of radio
buttons, use `gtk-radio-button-new-from-widget' with a
`<gtk-radio-button>' that already has a group assigned to it. The
convenience function `gtk-radio-button-new-with-label-from-widget' is
also provided.

   To retrieve the group a `<gtk-radio-button>' is assigned to, use
`gtk-radio-button-get-group'.

   To remove a `<gtk-radio-button>' from one group and make it part of
a new one, use `gtk-radio-button-set-group'.

   The group list does not need to be freed, as each
`<gtk-radio-button>' will remove itself and its list item when it is
destroyed.



     void create_radio_buttons (void) {

        GtkWidget *window, *radio1, *radio2, *box, *entry;
        window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
        box = gtk_vbox_new (TRUE, 2);

        /* Create a radio button with a GtkEntry widget */
        radio1 = gtk_radio_button_new (NULL);
        entry = gtk_entry_new ();
        gtk_container_add (GTK_CONTAINER (radio1), entry);


        /* Create a radio button with a label */
        radio2 = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON (radio1),
     							"I'm the second radio button.");

        /* Pack them into a box, then show all the widgets */
        gtk_box_pack_start (GTK_BOX (box), radio1, TRUE, TRUE, 2);
        gtk_box_pack_start (GTK_BOX (box), radio2, TRUE, TRUE, 2);
        gtk_container_add (GTK_CONTAINER (window), box);
        gtk_widget_show_all (window);
        return;
     }

   When an unselected button in the group is clicked the clicked button
receives the "toggled" signal, as does the previously selected button.
Inside the "toggled" handler, `gtk-toggle-button-get-active' can be
used to determine if the button has been selected or deselected.

17.2 Usage
==========

 -- Class: <gtk-radio-button>
     Derives from `<gtk-check-button>'.

     This class defines the following properties:

    `group'
          The radio button whose group this widget belongs to.



 -- Signal on <gtk-radio-button>: group-changed
     Emitted when the group of radio buttons that a radio button
     belongs to changes.  This is emitted when a radio button switches
     from being alone to being part of a group of 2 or more buttons, or
     vice-versa, and when a buttton is moved from one group of 2 or
     more buttons to a different one, but not when the composition of
     the group that a button belongs to changes.

     Since 2.4


 -- Function: gtk-radio-button-new (group `<gtk-radio-group*>') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-radio-button>'. To be of any practical value,
     a widget should then be packed into the radio button.

    GROUP
          an existing radio button group, or ``#f'' if you are creating
          a new group.

    RET
          a new radio button.



 -- Function: gtk-radio-button-new-from-widget
          (group `<gtk-radio-button>') =>  (ret `<gtk-widget>')
     Creates a new `<gtk-radio-button>', adding it to the same group as
     GROUP. As with `gtk-radio-button-new', a widget should be packed
     into the radio button.

    GROUP
          an existing `<gtk-radio-button>'.

    RET
          a new radio button.



 -- Function: gtk-radio-button-new-with-label
          (group `<gtk-radio-group*>') (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-radio-button>' with a text label.

    GROUP
          an existing radio button group, or ``#f'' if you are creating
          a new group.

    LABEL
          the text label to display next to the radio button.

    RET
          a new radio button.



 -- Function: gtk-radio-button-new-with-mnemonic
          (group `<gtk-radio-group*>') (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-radio-button>' containing a label, adding it
     to the same group as GROUP. The label will be created using
     `gtk-label-new-with-mnemonic', so underscores in LABEL indicate the
     mnemonic for the button.

    GROUP
          the radio button group

    LABEL
          the text of the button, with an underscore in front of the
          mnemonic character

    RET
          a new `<gtk-radio-button>'



 -- Function: gtk-radio-button-set-group (self `<gtk-radio-button>')
          (group `<gtk-radio-group*>')
 -- Method: set-group
     Sets a `<gtk-radio-button>''s group. It should be noted that this
     does not change the layout of your interface in any way, so if you
     are changing the group, it is likely you will need to re-arrange
     the user interface to reflect these changes.

    RADIO-BUTTON
          a `<gtk-radio-button>'.

    GROUP
          an existing radio button group, such as one returned from
          `gtk-radio-button-get-group'.



 -- Function: gtk-radio-button-get-group (self `<gtk-radio-button>')
          =>  (ret `<gtk-radio-group*>')
 -- Method: get-group
     Retrieves the group assigned to a radio button.

    RADIO-BUTTON
          a `<gtk-radio-button>'.

    RET
          a linked list containing all the radio buttons in the same
          group as RADIO-BUTTON.




File: guile-gnome-gtk.info,  Node: GtkToggleButton,  Next: GtkLinkButton,  Prev: GtkRadioButton,  Up: Top

18 GtkToggleButton
******************

Create buttons which retain their state

18.1 Overview
=============

A `<gtk-toggle-button>' is a `<gtk-button>' which will remain
'pressed-in' when clicked. Clicking again will cause the toggle button
to return to its normal state.

   A toggle button is created by calling either `gtk-toggle-button-new'
or `gtk-toggle-button-new-with-label'. If using the former, it is
advisable to pack a widget, (such as a `<gtk-label>' and/or a
`<gtk-pixmap>'), into the toggle button's container. (See
`<gtk-button>' for more information).

   The state of a `<gtk-toggle-button>' can be set specifically using
`gtk-toggle-button-set-active', and retrieved using
`gtk-toggle-button-get-active'.

   To simply switch the state of a toggle button, use
gtk_toggle_button_toggled.



     void make_toggles (void) {
        GtkWidget *dialog, *toggle1, *toggle2;

        dialog = gtk_dialog_new ();
        toggle1 = gtk_toggle_button_new_with_label ("Hi, i'm a toggle button.");

        /* Makes this toggle button invisible */
        gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1), TRUE);

        g_signal_connect (toggle1, "toggled",
                          G_CALLBACK (output_state), NULL);
        gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area),
                            toggle1, FALSE, FALSE, 2);

        toggle2 = gtk_toggle_button_new_with_label ("Hi, i'm another toggle button.");
        gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2), FALSE);
        g_signal_connect (toggle2, "toggled",
                          G_CALLBACK (output_state), NULL);
        gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area),
                            toggle2, FALSE, FALSE, 2);

        gtk_widget_show_all (dialog);
     }

18.2 Usage
==========

 -- Class: <gtk-toggle-button>
     Derives from `<gtk-button>'.

     This class defines the following properties:

    `active'
          If the toggle button should be pressed in or not

    `inconsistent'
          If the toggle button is in an "in between" state

    `draw-indicator'
          If the toggle part of the button is displayed



 -- Signal on <gtk-toggle-button>: toggled
     Should be connected if you wish to perform an action whenever the
     `<gtk-toggle-button>''s state is changed.


 -- Function: gtk-toggle-button-new =>  (ret `<gtk-widget>')
     Creates a new toggle button. A widget should be packed into the
     button, as in `gtk-button-new'.

    RET
          a new toggle button.



 -- Function: gtk-toggle-button-new-with-label (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new toggle button with a text label.

    LABEL
          a string containing the message to be placed in the toggle
          button.

    RET
          a new toggle button.



 -- Function: gtk-toggle-button-new-with-mnemonic (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-toggle-button>' containing a label. The label
     will be created using `gtk-label-new-with-mnemonic', so
     underscores in LABEL indicate the mnemonic for the button.

    LABEL
          the text of the button, with an underscore in front of the
          mnemonic character

    RET
          a new `<gtk-toggle-button>'



 -- Function: gtk-toggle-button-set-mode (self `<gtk-toggle-button>')
          (draw_indicator `bool')
 -- Method: set-mode
     Sets whether the button is displayed as a separate indicator and
     label. You can call this function on a checkbutton or a
     radiobutton with DRAW-INDICATOR = ``#f'' to make the button look
     like a normal button

     This function only affects instances of classes like
     `<gtk-check-button>' and `<gtk-radio-button>' that derive from
     `<gtk-toggle-button>', not instances of `<gtk-toggle-button>'
     itself.

    TOGGLE-BUTTON
          a `<gtk-toggle-button>'

    DRAW-INDICATOR
          if ``#t'', draw the button as a separate indicator and label;
          if ``#f'', draw the button like a normal button



 -- Function: gtk-toggle-button-get-mode (self `<gtk-toggle-button>')
          =>  (ret `bool')
 -- Method: get-mode
     Retrieves whether the button is displayed as a separate indicator
     and label. See `gtk-toggle-button-set-mode'.

    TOGGLE-BUTTON
          a `<gtk-toggle-button>'

    RET
          ``#t'' if the togglebutton is drawn as a separate indicator
          and label.



 -- Function: gtk-toggle-button-toggled (self `<gtk-toggle-button>')
 -- Method: toggled
     Emits the toggled signal on the `<gtk-toggle-button>'. There is no
     good reason for an application ever to call this function.

    TOGGLE-BUTTON
          a `<gtk-toggle-button>'.



 -- Function: gtk-toggle-button-get-active (self `<gtk-toggle-button>')
          =>  (ret `bool')
 -- Method: get-active
     Queries a `<gtk-toggle-button>' and returns its current state.
     Returns ``#t'' if the toggle button is pressed in and ``#f'' if it
     is raised.

    TOGGLE-BUTTON
          a `<gtk-toggle-button>'.

    RET
          a `<gboolean>' value.



 -- Function: gtk-toggle-button-set-active (self `<gtk-toggle-button>')
          (is_active `bool')
 -- Method: set-active
     Sets the status of the toggle button. Set to ``#t'' if you want the
     GtkToggleButton to be 'pressed in', and ``#f'' to raise it. This
     action causes the toggled signal to be emitted.

    TOGGLE-BUTTON
          a `<gtk-toggle-button>'.

    IS-ACTIVE
          ``#t'' or ``#f''.



 -- Function: gtk-toggle-button-get-inconsistent
          (self `<gtk-toggle-button>') =>  (ret `bool')
 -- Method: get-inconsistent
     Gets the value set by `gtk-toggle-button-set-inconsistent'.

    TOGGLE-BUTTON
          a `<gtk-toggle-button>'

    RET
          ``#t'' if the button is displayed as inconsistent, ``#f''
          otherwise



 -- Function: gtk-toggle-button-set-inconsistent
          (self `<gtk-toggle-button>') (setting `bool')
 -- Method: set-inconsistent
     If the user has selected a range of elements (such as some text or
     spreadsheet cells) that are affected by a toggle button, and the
     current values in that range are inconsistent, you may want to
     display the toggle in an "in between" state. This function turns
     on "in between" display. Normally you would turn off the
     inconsistent state again if the user toggles the toggle button.
     This has to be done manually, `gtk-toggle-button-set-inconsistent'
     only affects visual appearance, it doesn't affect the semantics of
     the button.

    TOGGLE-BUTTON
          a `<gtk-toggle-button>'

    SETTING
          ``#t'' if state is inconsistent




File: guile-gnome-gtk.info,  Node: GtkLinkButton,  Next: GtkEntry,  Prev: GtkToggleButton,  Up: Top

19 GtkLinkButton
****************

Create buttons bound to a URL

19.1 Overview
=============

A `<gtk-link-button>' is a `<gtk-button>' with a hyperlink, similar to
the one used by web browsers, which triggers an action when clicked. It
is useful to show quick links to resources.

   A link button is created by calling either `gtk-link-button-new' or
`gtk-link-button-new-with-label'. If using the former, the URI you pass
to the constructor is used as a label for the widget.

   The URI bound to a `<gtk-link-button>' can be set specifically using
`gtk-link-button-set-uri', and retrieved using
`gtk-link-button-get-uri'.

   `<gtk-link-button>' offers a global hook, which is called when the
used clicks on it: see `gtk-link-button-set-uri-hook'.

   `<gtk-link-button>' was added in GTK+ 2.10.

19.2 Usage
==========

 -- Class: <gtk-link-button>
     Derives from `<gtk-button>'.

     This class defines the following properties:

    `uri'
          The URI bound to this button



 -- Function: gtk-link-button-new (uri `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-link-button>' with the URI as its text.

    URI
          a valid URI

    RET
          a new link button widget.


     Since 2.10


 -- Function: gtk-link-button-new-with-label (uri `mchars')
          (label `mchars') =>  (ret `<gtk-widget>')
     Creates a new `<gtk-link-button>' containing a label.

    URI
          a valid URI

    LABEL
          the text of the button

    RET
          a new link button widget.


     Since 2.10


 -- Function: gtk-link-button-get-uri (self `<gtk-link-button>') => 
          (ret `mchars')
 -- Method: get-uri
     Retrieves the URI set using `gtk-link-button-set-uri'.

    LINK-BUTTON
          a `<gtk-link-button>'

    RET
          a valid URI. The returned string is owned by the link button
          and should not be modified or freed.


     Since 2.10


 -- Function: gtk-link-button-set-uri (self `<gtk-link-button>')
          (uri `mchars')
 -- Method: set-uri
     Sets URI as the URI where the `<gtk-link-button>' points.

    LINK-BUTTON
          a `<gtk-link-button>'

    URI
          a valid URI


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkEntry,  Next: GtkEntryCompletion,  Prev: GtkLinkButton,  Up: Top

20 GtkEntry
***********

A single line text entry field

20.1 Overview
=============

The `<gtk-entry>' widget is a single line text entry widget. A fairly
large set of key bindings are supported by default. If the entered text
is longer than the allocation of the widget, the widget will scroll so
that the cursor position is visible.

20.2 Usage
==========

 -- Class: <gtk-entry>
     Derives from `<gtk-editable>', `<gtk-cell-editable>',
     `<gtk-widget>'.

     This class defines the following properties:

    `cursor-position'
          The current position of the insertion cursor in chars

    `selection-bound'
          The position of the opposite end of the selection from the
          cursor in chars

    `editable'
          Whether the entry contents can be edited

    `max-length'
          Maximum number of characters for this entry. Zero if no
          maximum

    `visibility'
          FALSE displays the "invisible char" instead of the actual
          text (password mode)

    `has-frame'
          FALSE removes outside bevel from entry

    `inner-border'
          Border between text and frame. Overrides the inner-border
          style property

    `invisible-char'
          The character to use when masking entry contents (in
          "password mode")

    `activates-default'
          Whether to activate the default widget (such as the default
          button in a dialog) when Enter is pressed

    `width-chars'
          Number of characters to leave space for in the entry

    `scroll-offset'
          Number of pixels of the entry scrolled off the screen to the
          left

    `text'
          The contents of the entry

    `xalign'
          The horizontal alignment, from 0 (left) to 1 (right).
          Reversed for RTL layouts.

    `truncate-multiline'
          Whether to truncate multiline pastes to one line.

    `shadow-type'
          Which kind of shadow to draw around the entry when has-frame
          is set



 -- Signal on <gtk-entry>: move-cursor (arg0 `<gtk-movement-step>')
          (arg1 `<gint>') (arg2 `<gboolean>')

 -- Signal on <gtk-entry>: copy-clipboard

 -- Signal on <gtk-entry>: populate-popup (arg0 `<gtk-menu>')

 -- Signal on <gtk-entry>: activate

 -- Signal on <gtk-entry>: insert-at-cursor (arg0 `<gchararray>')

 -- Signal on <gtk-entry>: delete-from-cursor
          (arg0 `<gtk-delete-type>') (arg1 `<gint>')

 -- Signal on <gtk-entry>: backspace

 -- Signal on <gtk-entry>: cut-clipboard

 -- Signal on <gtk-entry>: paste-clipboard

 -- Signal on <gtk-entry>: toggle-overwrite

 -- Function: gtk-entry-set-text (self `<gtk-entry>') (text `mchars')
 -- Method: set-text
     Sets the text in the widget to the given value, replacing the
     current contents.

    ENTRY
          a `<gtk-entry>'.

    TEXT
          the new text.



 -- Function: gtk-entry-get-text (self `<gtk-entry>') =>  (ret `mchars')
 -- Method: get-text
     Retrieves the contents of the entry widget. See also
     `gtk-editable-get-chars'.

    ENTRY
          a `<gtk-entry>'

    RET
          a pointer to the contents of the widget as a string. This
          string points to internally allocated storage in the widget
          and must not be freed, modified or stored.



 -- Function: gtk-entry-set-visibility (self `<gtk-entry>')
          (visible `bool')
 -- Method: set-visibility
     Sets whether the contents of the entry are visible or not. When
     visibility is set to ``#f'', characters are displayed as the
     invisible char, and will also appear that way when the text in the
     entry widget is copied elsewhere.

     The default invisible char is the asterisk '*', but it can be
     changed with `gtk-entry-set-invisible-char'.

    ENTRY
          a `<gtk-entry>'.

    VISIBLE
          ``#t'' if the contents of the entry are displayed as
          plaintext.



 -- Function: gtk-entry-set-invisible-char (self `<gtk-entry>')
          (ch `unsigned-int32')
 -- Method: set-invisible-char
     Sets the character to use in place of the actual text when
     `gtk-entry-set-visibility' has been called to set text visibility
     to ``#f''. i.e. this is the character used in "password mode" to
     show the user how many characters have been typed. The default
     invisible char is an asterisk ('*'). If you set the invisible char
     to 0, then the user will get no feedback at all; there will be no
     text on the screen as they type.

    ENTRY
          a `<gtk-entry>'

    CH
          a Unicode character



 -- Function: gtk-entry-set-max-length (self `<gtk-entry>') (max `int')
 -- Method: set-max-length
     Sets the maximum allowed length of the contents of the widget. If
     the current contents are longer than the given length, then they
     will be truncated to fit.

    ENTRY
          a `<gtk-entry>'.

    MAX
          the maximum length of the entry, or 0 for no maximum. (other
          than the maximum length of entries.) The value passed in will
          be clamped to the range 0-65536.



 -- Function: gtk-entry-get-activates-default (self `<gtk-entry>') => 
          (ret `bool')
 -- Method: get-activates-default
     Retrieves the value set by `gtk-entry-set-activates-default'.

    ENTRY
          a `<gtk-entry>'

    RET
          ``#t'' if the entry will activate the default widget



 -- Function: gtk-entry-get-has-frame (self `<gtk-entry>') => 
          (ret `bool')
 -- Method: get-has-frame
     Gets the value set by `gtk-entry-set-has-frame'.

    ENTRY
          a `<gtk-entry>'

    RET
          whether the entry has a beveled frame



 -- Function: gtk-entry-get-inner-border (self `<gtk-entry>') => 
          (ret `<gtk-border>')
 -- Method: get-inner-border
     This function returns the entry's inner-border property. See
     `gtk-entry-set-inner-border' for more information.

    ENTRY
          a `<gtk-entry>'

    RET
          the entry's `<gtk-border>', or ``#f'' if none was set.


     Since 2.10


 -- Function: gtk-entry-get-width-chars (self `<gtk-entry>') => 
          (ret `int')
 -- Method: get-width-chars
     Gets the value set by `gtk-entry-set-width-chars'.

    ENTRY
          a `<gtk-entry>'

    RET
          number of chars to request space for, or negative if unset



 -- Function: gtk-entry-set-activates-default (self `<gtk-entry>')
          (setting `bool')
 -- Method: set-activates-default
     If SETTING is ``#t'', pressing Enter in the ENTRY will activate
     the default widget for the window containing the entry. This
     usually means that the dialog box containing the entry will be
     closed, since the default widget is usually one of the dialog
     buttons.

     (For experts: if SETTING is ``#t'', the entry calls
     `gtk-window-activate-default' on the window containing the entry,
     in the default handler for the "activate" signal.)

    ENTRY
          a `<gtk-entry>'

    SETTING
          ``#t'' to activate window's default widget on Enter keypress



 -- Function: gtk-entry-set-has-frame (self `<gtk-entry>')
          (setting `bool')
 -- Method: set-has-frame
     Sets whether the entry has a beveled frame around it.

    ENTRY
          a `<gtk-entry>'

    SETTING
          new value



 -- Function: gtk-entry-set-inner-border (self `<gtk-entry>')
          (border `<gtk-border>')
 -- Method: set-inner-border
     Sets `entry''s inner-border property to `border', or clears it if
     ``#f'' is passed. The inner-border is the area around the entry's
     text, but inside its frame.

     If set, this property overrides the inner-border style property.
     Overriding the style-provided border is useful when you want to do
     in-place editing of some text in a canvas or list widget, where
     pixel-exact positioning of the entry is important.

    ENTRY
          a `<gtk-entry>'

    BORDER
          a `<gtk-border>', or ``#f''


     Since 2.10


 -- Function: gtk-entry-set-width-chars (self `<gtk-entry>')
          (n_chars `int')
 -- Method: set-width-chars
     Changes the size request of the entry to be about the right size
     for N-CHARS characters. Note that it changes the size _request_,
     the size can still be affected by how you pack the widget into
     containers. If N-CHARS is -1, the size reverts to the default
     entry size.

    ENTRY
          a `<gtk-entry>'

    N-CHARS
          width in chars



 -- Function: gtk-entry-get-invisible-char (self `<gtk-entry>') => 
          (ret `unsigned-int32')
 -- Method: get-invisible-char
     Retrieves the character displayed in place of the real characters
     for entries with visisbility set to false. See
     `gtk-entry-set-invisible-char'.

    ENTRY
          a `<gtk-entry>'

    RET
          the current invisible char, or 0, if the entry does not show
          invisible text at all.



 -- Function: gtk-entry-set-alignment (self `<gtk-entry>')
          (xalign `float')
 -- Method: set-alignment
     Sets the alignment for the contents of the entry. This controls
     the horizontal positioning of the contents when the displayed text
     is shorter than the width of the entry.

    ENTRY
          a `<gtk-entry>'

    XALIGN
          The horizontal alignment, from 0 (left) to 1 (right).
          Reversed for RTL layouts


     Since 2.4


 -- Function: gtk-entry-get-alignment (self `<gtk-entry>') => 
          (ret `float')
 -- Method: get-alignment
     Gets the value set by `gtk-entry-set-alignment'.

    ENTRY
          a `<gtk-entry>'

    RET
          the alignment


     Since 2.4


 -- Function: gtk-entry-get-layout (self `<gtk-entry>') => 
          (ret `<pango-layout>')
 -- Method: get-layout
     Gets the `<pango-layout>' used to display the entry. The layout is
     useful to e.g. convert text positions to pixel positions, in
     combination with `gtk-entry-get-layout-offsets'. The returned
     layout is owned by the entry and must not be modified or freed by
     the caller.

     Keep in mind that the layout text may contain a preedit string, so
     `gtk-entry-layout-index-to-text-index' and
     `gtk-entry-text-index-to-layout-index' are needed to convert byte
     indices in the layout to byte indices in the entry contents.

    ENTRY
          a `<gtk-entry>'

    RET
          the `<pango-layout>' for this entry



 -- Function: gtk-entry-get-layout-offsets (self `<gtk-entry>') => 
          (x `int') (y `int')
 -- Method: get-layout-offsets
     Obtains the position of the `<pango-layout>' used to render text
     in the entry, in widget coordinates. Useful if you want to line up
     the text in an entry with some other text, e.g. when using the
     entry to implement editable cells in a sheet widget.

     Also useful to convert mouse events into coordinates inside the
     `<pango-layout>', e.g. to take some action if some part of the
     entry text is clicked.

     Note that as the user scrolls around in the entry the offsets will
     change; you'll need to connect to the "notify::scroll-offset"
     signal to track this.  Remember when using the `<pango-layout>'
     functions you need to convert to and from pixels using
     `pango-pixels' or `<pango-scale>'.

     Keep in mind that the layout text may contain a preedit string, so
     `gtk-entry-layout-index-to-text-index' and
     `gtk-entry-text-index-to-layout-index' are needed to convert byte
     indices in the layout to byte indices in the entry contents.

    ENTRY
          a `<gtk-entry>'

    X
          location to store X offset of layout, or ``#f''

    Y
          location to store Y offset of layout, or ``#f''



 -- Function: gtk-entry-get-max-length (self `<gtk-entry>') => 
          (ret `int')
 -- Method: get-max-length
     Retrieves the maximum allowed length of the text in ENTRY. See
     `gtk-entry-set-max-length'.

    ENTRY
          a `<gtk-entry>'

    RET
          the maximum allowed number of characters in `<gtk-entry>', or
          0 if there is no maximum.



 -- Function: gtk-entry-get-visibility (self `<gtk-entry>') => 
          (ret `bool')
 -- Method: get-visibility
     Retrieves whether the text in ENTRY is visible. See
     `gtk-entry-set-visibility'.

    ENTRY
          a `<gtk-entry>'

    RET
          ``#t'' if the text is currently visible



 -- Function: gtk-entry-set-completion (self `<gtk-entry>')
          (completion `<gtk-entry-completion>')
 -- Method: set-completion
     Sets COMPLETION to be the auxiliary completion object to use with
     ENTRY. All further configuration of the completion mechanism is
     done on COMPLETION using the `<gtk-entry-completion>' API.
     Completion is disabled if COMPLETION is set to ``#f''.

    ENTRY
          A `<gtk-entry>'.

    COMPLETION
          The `<gtk-entry-completion>' or ``#f''.


     Since 2.4


 -- Function: gtk-entry-get-completion (self `<gtk-entry>') => 
          (ret `<gtk-entry-completion>')
 -- Method: get-completion
     Returns the auxiliary completion object currently in use by ENTRY.

    ENTRY
          A `<gtk-entry>'.

    RET
          The auxiliary completion object currently in use by ENTRY.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkEntryCompletion,  Next: GtkHScale,  Prev: GtkEntry,  Up: Top

21 GtkEntryCompletion
*********************

Completion functionality for GtkEntry

21.1 Overview
=============

`<gtk-entry-completion>' is an auxiliary object to be used in
conjunction with `<gtk-entry>' to provide the completion functionality.
It implements the `<gtk-cell-layout>' interface, to allow the user to
add extra cells to the `<gtk-tree-view>' with completion matches.

   "Completion functionality" means that when the user modifies the
text in the entry, `<gtk-entry-completion>' checks which rows in the
model match the current content of the entry, and displays a list of
matches. By default, the matching is done by comparing the entry text
case-insensitively against the text column of the model (see
`gtk-entry-completion-set-text-column'), but this can be overridden
with a custom match function (see
`gtk-entry-completion-set-match-func').

   When the user selects a completion, the content of the entry is
updated. By default, the content of the entry is replaced by the text
column of the model, but this can be overridden by connecting to the
::match-selected signal and updating the entry in the signal handler.
Note that you should return ``#t'' from the signal handler to suppress
the default behaviour.

   To add completion functionality to an entry, use
`gtk-entry-set-completion'.

   In addition to regular completion matches, which will be inserted
into the entry when they are selected, `<gtk-entry-completion>' also
allows to display "actions" in the popup window. Their appearance is
similar to menuitems, to differentiate them clearly from completion
strings. When an action is selected, the ::action-activated signal is
emitted.

21.2 Usage
==========

 -- Class: <gtk-entry-completion>
     Derives from `<gtk-buildable>', `<gtk-cell-layout>', `<gobject>'.

     This class defines the following properties:

    `model'
          The model to find matches in

    `minimum-key-length'
          Minimum length of the search key in order to look up matches

    `text-column'
          The column of the model containing the strings.

    `inline-completion'
          Whether the common prefix should be inserted automatically

    `popup-completion'
          Whether the completions should be shown in a popup window

    `popup-set-width'
          If TRUE, the popup window will have the same size as the entry

    `popup-single-match'
          If TRUE, the popup window will appear for a single match.

    `inline-selection'
          Your description here



 -- Signal on <gtk-entry-completion>: insert-prefix
          (arg0 `<gchararray>') => `<gboolean>'
     Gets emitted when the inline autocompletion is triggered. The
     default behaviour is to make the entry display the whole prefix
     and select the newly inserted part.

     Applications may connect to this signal in order to insert only a
     smaller part of the PREFIX into the entry - e.g. the entry used in
     the `<gtk-file-chooser>' inserts only the part of the prefix up to
     the next '/'.

     Since 2.6


 -- Signal on <gtk-entry-completion>: match-selected
          (arg0 `<gtk-tree-model>') (arg1 `<gtk-tree-iter>')
          => `<gboolean>'
     Gets emitted when a match from the list is selected. The default
     behaviour is to replace the contents of the entry with the
     contents of the text column in the row pointed to by ITER.

     Since 2.4


 -- Signal on <gtk-entry-completion>: cursor-on-match
          (arg0 `<gtk-tree-model>') (arg1 `<gtk-tree-iter>')
          => `<gboolean>'
     undocumented

 -- Signal on <gtk-entry-completion>: action-activated (arg0 `<gint>')
     Gets emitted when an action is activated.

     Since 2.4


 -- Function: gtk-entry-completion-new => 
          (ret `<gtk-entry-completion>')
     Creates a new `<gtk-entry-completion>' object.

    RET
          A newly created `<gtk-entry-completion>' object.


     Since 2.4


 -- Function: gtk-entry-completion-get-entry
          (self `<gtk-entry-completion>') =>  (ret `<gtk-widget>')
 -- Method: get-entry
     Gets the entry COMPLETION has been attached to.

    COMPLETION
          A `<gtk-entry-completion>'.

    RET
          The entry COMPLETION has been attached to.


     Since 2.4


 -- Function: gtk-entry-completion-set-model
          (self `<gtk-entry-completion>') (model `<gtk-tree-model>')
 -- Method: set-model
     Sets the model for a `<gtk-entry-completion>'. If COMPLETION
     already has a model set, it will remove it before setting the new
     model. If model is ``#f'', then it will unset the model.

    COMPLETION
          A `<gtk-entry-completion>'.

    MODEL
          The `<gtk-tree-model>'.


     Since 2.4


 -- Function: gtk-entry-completion-get-model
          (self `<gtk-entry-completion>') =>  (ret `<gtk-tree-model>')
 -- Method: get-model
     Returns the model the `<gtk-entry-completion>' is using as data
     source.  Returns ``#f'' if the model is unset.

    COMPLETION
          A `<gtk-entry-completion>'.

    RET
          A `<gtk-tree-model>', or ``#f'' if none is currently being
          used.


     Since 2.4


 -- Function: gtk-entry-completion-complete
          (self `<gtk-entry-completion>')
 -- Method: complete
     Requests a completion operation, or in other words a refiltering
     of the current list with completions, using the current key. The
     completion list view will be updated accordingly.

    COMPLETION
          A `<gtk-entry-completion>'.


     Since 2.4


 -- Function: gtk-entry-completion-insert-prefix
          (self `<gtk-entry-completion>')
 -- Method: insert-prefix
     Requests a prefix insertion.

    COMPLETION
          a `<gtk-entry-completion>'


     Since 2.6


 -- Function: gtk-entry-completion-delete-action
          (self `<gtk-entry-completion>') (index `int')
 -- Method: delete-action
     Deletes the action at INDEX from COMPLETION's action list.

    COMPLETION
          A `<gtk-entry-completion>'.

    INDEX
          The index of the item to Delete.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkHScale,  Next: GtkVScale,  Prev: GtkEntryCompletion,  Up: Top

22 GtkHScale
************

A horizontal slider widget for selecting a value from a range

22.1 Overview
=============

The `<gtk-hscale>' widget is used to allow the user to select a value
using a horizontal slider. To create one, use
`gtk-hscale-new-with-range'.

   The position to show the current value, and the number of decimal
places shown can be set using the parent `<gtk-scale>' class's
functions.

22.2 Usage
==========

 -- Class: <gtk-hscale>
     Derives from `<gtk-scale>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gtk-hscale-new (adjustment `<gtk-adjustment>') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-hscale>'.

    ADJUSTMENT
          the `<gtk-adjustment>' which sets the range of the scale.

    RET
          a new `<gtk-hscale>'.



 -- Function: gtk-hscale-new-with-range (min `double') (max `double')
          (step `double') =>  (ret `<gtk-widget>')
     Creates a new horizontal scale widget that lets the user input a
     number between MIN and MAX (including MIN and MAX) with the
     increment STEP. STEP must be nonzero; it's the distance the slider
     moves when using the arrow keys to adjust the scale value.

     Note that the way in which the precision is derived works best if
     STEP is a power of ten. If the resulting precision is not suitable
     for your needs, use `gtk-scale-set-digits' to correct it.

    MIN
          minimum value

    MAX
          maximum value

    STEP
          step increment (tick size) used with keyboard shortcuts

    RET
          a new `<gtk-hscale>'




File: guile-gnome-gtk.info,  Node: GtkVScale,  Next: GtkSpinButton,  Prev: GtkHScale,  Up: Top

23 GtkVScale
************

A vertical slider widget for selecting a value from a range

23.1 Overview
=============

The `<gtk-vscale>' widget is used to allow the user to select a value
using a vertical slider. To create one, use `gtk-hscale-new-with-range'.

   The position to show the current value, and the number of decimal
places shown can be set using the parent `<gtk-scale>' class's
functions.

23.2 Usage
==========

 -- Class: <gtk-vscale>
     Derives from `<gtk-scale>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Function: gtk-vscale-new (adjustment `<gtk-adjustment>') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-vscale>'.

    ADJUSTMENT
          the `<gtk-adjustment>' which sets the range of the scale.

    RET
          a new `<gtk-vscale>'.



 -- Function: gtk-vscale-new-with-range (min `double') (max `double')
          (step `double') =>  (ret `<gtk-widget>')
     Creates a new vertical scale widget that lets the user input a
     number between MIN and MAX (including MIN and MAX) with the
     increment STEP. STEP must be nonzero; it's the distance the slider
     moves when using the arrow keys to adjust the scale value.

     Note that the way in which the precision is derived works best if
     STEP is a power of ten. If the resulting precision is not suitable
     for your needs, use `gtk-scale-set-digits' to correct it.

    MIN
          minimum value

    MAX
          maximum value

    STEP
          step increment (tick size) used with keyboard shortcuts

    RET
          a new `<gtk-vscale>'




File: guile-gnome-gtk.info,  Node: GtkSpinButton,  Next: GtkEditable,  Prev: GtkVScale,  Up: Top

24 GtkSpinButton
****************

Retrieve an integer or floating-point number from the user

24.1 Overview
=============

A `<gtk-spin-button>' is an ideal way to allow the user to set the
value of some attribute. Rather than having to directly type a number
into a `<gtk-entry>', `<gtk-spin-button>' allows the user to click on
one of two arrows to increment or decrement the displayed value. A
value can still be typed in, with the bonus that it can be checked to
ensure it is in a given range.

   The main properties of a `<gtk-spin-button>' are through a
`<gtk-adjustment>'. See the `<gtk-adjustment>' section for more details
about an adjustment's properties.



     /* Provides a function to retrieve an integer value from a GtkSpinButton
      * and creates a spin button to model percentage values.
      */

     gint grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
        return gtk_spin_button_get_value_as_int (a_spinner);
     }

     void create_integer_spin_button (void) {

        GtkWidget *window, *spinner;
        GtkAdjustment *spinner_adj;

        spinner_adj = (GtkAdjustment *) gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 5.0);

        window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
        gtk_container_set_border_width (GTK_CONTAINER (window), 5);

        /* creates the spinner, with no decimal places */
        spinner = gtk_spin_button_new (spinner_adj, 1.0, 0);
        gtk_container_add (GTK_CONTAINER (window), spinner);

        gtk_widget_show_all (window);
        return;
     }



     /* Provides a function to retrieve a floating point value from a
      * GtkSpinButton, and creates a high precision spin button.
      */

     gfloat grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
        return gtk_spin_button_get_value (a_spinner);
     }

     void create_floating_spin_button (void) {

        GtkWidget *window, *spinner;
        GtkAdjustment *spinner_adj;

        spinner_adj = (GtkAdjustment *) gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.1);

        window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
        gtk_container_set_border_width (GTK_CONTAINER (window), 5);

        /* creates the spinner, with three decimal places */
        spinner = gtk_spin_button_new (spinner_adj, 0.001, 3);
        gtk_container_add (GTK_CONTAINER (window), spinner);

        gtk_widget_show_all (window);
        return;
     }

24.2 Usage
==========

 -- Class: <gtk-spin-button>
     Derives from `<gtk-entry>'.

     This class defines the following properties:

    `adjustment'
          The adjustment that holds the value of the spinbutton

    `climb-rate'
          The acceleration rate when you hold down a button

    `digits'
          The number of decimal places to display

    `snap-to-ticks'
          Whether erroneous values are automatically changed to a spin
          button's nearest step increment

    `numeric'
          Whether non-numeric characters should be ignored

    `wrap'
          Whether a spin button should wrap upon reaching its limits

    `update-policy'
          Whether the spin button should update always, or only when
          the value is legal

    `value'
          Reads the current value, or sets a new value



 -- Signal on <gtk-spin-button>: value-changed

 -- Signal on <gtk-spin-button>: change-value (arg0 `<gtk-scroll-type>')

 -- Signal on <gtk-spin-button>: input (arg0 `<gpointer>') => `<gint>'

 -- Signal on <gtk-spin-button>: output => `<gboolean>'

 -- Signal on <gtk-spin-button>: wrapped
     The wrapped signal is emitted right after the spinbutton wraps
     from its maximum to minimum value or vice-versa.

     Since 2.10


 -- Function: gtk-spin-button-configure (self `<gtk-spin-button>')
          (adjustment `<gtk-adjustment>') (climb_rate `double')
          (digits `unsigned-int')
 -- Method: configure
     Changes the properties of an existing spin button. The adjustment,
     climb rate, and number of decimal places are all changed
     accordingly, after this function call.

    SPIN-BUTTON
          a `<gtk-spin-button>'.

    ADJUSTMENT
          a `<gtk-adjustment>'.

    CLIMB-RATE
          the new climb rate.

    DIGITS
          the number of decimal places to display in the spin button.



 -- Function: gtk-spin-button-new (adjustment `<gtk-adjustment>')
          (climb_rate `double') (digits `unsigned-int') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-spin-button>'.

    ADJUSTMENT
          the `<gtk-adjustment>' object that this spin button should
          use.

    CLIMB-RATE
          specifies how much the spin button changes when an arrow is
          clicked on.

    DIGITS
          the number of decimal places to display.

    RET
          The new spin button as a `<gtk-widget>'.



 -- Function: gtk-spin-button-new-with-range (min `double')
          (max `double') (step `double') =>  (ret `<gtk-widget>')
     This is a convenience constructor that allows creation of a numeric
     `<gtk-spin-button>' without manually creating an adjustment. The
     value is initially set to the minimum value and a page increment
     of 10 * STEP is the default. The precision of the spin button is
     equivalent to the precision of STEP.

     Note that the way in which the precision is derived works best if
     STEP is a power of ten. If the resulting precision is not suitable
     for your needs, use `gtk-spin-button-set-digits' to correct it.

    MIN
          Minimum allowable value

    MAX
          Maximum allowable value

    STEP
          Increment added or subtracted by spinning the widget

    RET
          The new spin button as a `<gtk-widget>'.



 -- Function: gtk-spin-button-set-adjustment (self `<gtk-spin-button>')
          (adjustment `<gtk-adjustment>')
 -- Method: set-adjustment
     Replaces the `<gtk-adjustment>' associated with SPIN-BUTTON.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    ADJUSTMENT
          a `<gtk-adjustment>' to replace the existing adjustment



 -- Function: gtk-spin-button-get-adjustment (self `<gtk-spin-button>')
          =>  (ret `<gtk-adjustment>')
 -- Method: get-adjustment
     Get the adjustment associated with a `<gtk-spin-button>'

    SPIN-BUTTON
          a `<gtk-spin-button>'

    RET
          the `<gtk-adjustment>' of SPIN-BUTTON



 -- Function: gtk-spin-button-set-digits (self `<gtk-spin-button>')
          (digits `unsigned-int')
 -- Method: set-digits
     Set the precision to be displayed by SPIN-BUTTON. Up to 20 digit
     precision is allowed.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    DIGITS
          the number of digits after the decimal point to be displayed
          for the spin button's value



 -- Function: gtk-spin-button-set-increments (self `<gtk-spin-button>')
          (step `double') (page `double')
 -- Method: set-increments
     Sets the step and page increments for spin_button. This affects
     how quickly the value changes when the spin button's arrows are
     activated.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    STEP
          increment applied for a button 1 press.

    PAGE
          increment applied for a button 2 press.



 -- Function: gtk-spin-button-set-range (self `<gtk-spin-button>')
          (min `double') (max `double')
 -- Method: set-range
     Sets the minimum and maximum allowable values for SPIN-BUTTON

    SPIN-BUTTON
          a `<gtk-spin-button>'

    MIN
          minimum allowable value

    MAX
          maximum allowable value



 -- Function: gtk-spin-button-get-value-as-int
          (self `<gtk-spin-button>') =>  (ret `int')
 -- Method: get-value-as-int
     Get the value SPIN-BUTTON represented as an integer.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    RET
          the value of SPIN-BUTTON



 -- Function: gtk-spin-button-set-value (self `<gtk-spin-button>')
          (value `double')
 -- Method: set-value
     Set the value of SPIN-BUTTON.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    VALUE
          the new value



 -- Function: gtk-spin-button-set-update-policy
          (self `<gtk-spin-button>')
          (policy `<gtk-spin-button-update-policy>')
 -- Method: set-update-policy
     Sets the update behavior of a spin button. This determines whether
     the spin button is always updated or only when a valid value is
     set.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    POLICY
          a `<gtk-spin-button-update-policy>' value



 -- Function: gtk-spin-button-set-numeric (self `<gtk-spin-button>')
          (numeric `bool')
 -- Method: set-numeric
     Sets the flag that determines if non-numeric text can be typed
     into the spin button.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    NUMERIC
          flag indicating if only numeric entry is allowed.



 -- Function: gtk-spin-button-spin (self `<gtk-spin-button>')
          (direction `<gtk-spin-type>') (increment `double')
 -- Method: spin
     Increment or decrement a spin button's value in a specified
     direction by a specified amount.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    DIRECTION
          a `<gtk-spin-type>' indicating the direction to spin.

    INCREMENT
          step increment to apply in the specified direction.



 -- Function: gtk-spin-button-set-wrap (self `<gtk-spin-button>')
          (wrap `bool')
 -- Method: set-wrap
     Sets the flag that determines if a spin button value wraps around
     to the opposite limit when the upper or lower limit of the range
     is exceeded.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    WRAP
          a flag indicating if wrapping behavior is performed.



 -- Function: gtk-spin-button-set-snap-to-ticks
          (self `<gtk-spin-button>') (snap_to_ticks `bool')
 -- Method: set-snap-to-ticks
     Sets the policy as to whether values are corrected to the nearest
     step increment when a spin button is activated after providing an
     invalid value.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    SNAP-TO-TICKS
          a flag indicating if invalid values should be corrected.



 -- Function: gtk-spin-button-update (self `<gtk-spin-button>')
 -- Method: update
     Manually force an update of the spin button.

    SPIN-BUTTON
          a `<gtk-spin-button>'



 -- Function: gtk-spin-button-get-digits (self `<gtk-spin-button>') => 
          (ret `unsigned-int')
 -- Method: get-digits
     Fetches the precision of SPIN-BUTTON. See
     `gtk-spin-button-set-digits'.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    RET
          the current precision



 -- Function: gtk-spin-button-get-increments (self `<gtk-spin-button>')
          =>  (step `double') (page `double')
 -- Method: get-increments
     Gets the current step and page the increments used by SPIN-BUTTON.
     See `gtk-spin-button-set-increments'.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    STEP
          location to store step increment, or ``#f''

    PAGE
          location to store page increment, or ``#f''



 -- Function: gtk-spin-button-get-numeric (self `<gtk-spin-button>')
          =>  (ret `bool')
 -- Method: get-numeric
     Returns whether non-numeric text can be typed into the spin
     button. See `gtk-spin-button-set-numeric'.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    RET
          ``#t'' if only numeric text can be entered



 -- Function: gtk-spin-button-get-range (self `<gtk-spin-button>') => 
          (min `double') (max `double')
 -- Method: get-range
     Gets the range allowed for SPIN-BUTTON. See
     `gtk-spin-button-set-range'.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    MIN
          location to store minimum allowed value, or ``#f''

    MAX
          location to store maximum allowed value, or ``#f''



 -- Function: gtk-spin-button-get-snap-to-ticks
          (self `<gtk-spin-button>') =>  (ret `bool')
 -- Method: get-snap-to-ticks
     Returns whether the values are corrected to the nearest step. See
     `gtk-spin-button-set-snap-to-ticks'.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    RET
          ``#t'' if values are snapped to the nearest step.



 -- Function: gtk-spin-button-get-value (self `<gtk-spin-button>') => 
          (ret `double')
 -- Method: get-value
     Get the value in the SPIN-BUTTON.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    RET
          the value of SPIN-BUTTON



 -- Function: gtk-spin-button-get-wrap (self `<gtk-spin-button>') => 
          (ret `bool')
 -- Method: get-wrap
     Returns whether the spin button's value wraps around to the
     opposite limit when the upper or lower limit of the range is
     exceeded. See `gtk-spin-button-set-wrap'.

    SPIN-BUTTON
          a `<gtk-spin-button>'

    RET
          ``#t'' if the spin button wraps around




File: guile-gnome-gtk.info,  Node: GtkEditable,  Next: GtkTextIter,  Prev: GtkSpinButton,  Up: Top

25 GtkEditable
**************

Interface for text-editing widgets

25.1 Overview
=============

The `<gtk-editable>' interface is an interface which should be
implemented by text editing widgets, such as `<gtk-entry>' and
`<gtk-text>'. It contains functions for generically manipulating an
editable widget, a large number of action signals used for key
bindings, and several signals that an application can connect to to
modify the behavior of a widget.

   As an example of the latter usage, by connecting the following
handler to "insert_text", an application can convert all entry into a
widget into uppercase.


     #include <ctype.h>

     void
     insert_text_handler (GtkEditable *editable,
                          const gchar *text,
                          gint         length,
                          gint        *position,
                          gpointer     data)
     {
       int i;
       gchar *result = g_utf8_strup (text, length);

       g_signal_handlers_block_by_func (editable,
     				   (gpointer) insert_text_handler, data);
       gtk_editable_insert_text (editable, result, length, position);
       g_signal_handlers_unblock_by_func (editable,
                                          (gpointer) insert_text_handler, data);

       g_signal_stop_emission_by_name (editable, "insert_text");

       g_free (result);
     }

25.2 Usage
==========

 -- Class: <gtk-editable>
     Derives from `<ginterface>'.

     This class defines no properties, other than those defined by its
     superclasses.


 -- Signal on <gtk-editable>: changed
     Indicates that the user has changed the contents of the widget.


 -- Signal on <gtk-editable>: insert-text (arg0 `<gchararray>')
          (arg1 `<gint>') (arg2 `<gpointer>')
     This signal is emitted when text is inserted into the widget by
     the user. The default handler for this signal will normally be
     responsible for inserting the text, so by connecting to this
     signal and then stopping the signal with `gtk-signal-emit-stop',
     it is possible to modify the inserted text, or prevent it from
     being inserted entirely.


 -- Signal on <gtk-editable>: delete-text (arg0 `<gint>')
          (arg1 `<gint>')
     This signal is emitted when text is deleted from the widget by the
     user. The default handler for this signal will normally be
     responsible for inserting the text, so by connecting to this
     signal and then stopping the signal with `gtk-signal-emit-stop',
     it is possible to modify the inserted text, or prevent it from
     being inserted entirely. The START-POS and END-POS parameters are
     interpreted as for `gtk-editable-delete-text'


 -- Function: gtk-editable-select-region (self `<gtk-editable>')
          (start `int') (end `int')
 -- Method: select-region
     Selects a region of text. The characters that are selected are
     those characters at positions from START-POS up to, but not
     including END-POS. If END-POS is negative, then the the characters
     selected will be those characters from START-POS to the end of the
     text.

    EDITABLE
          a `<gtk-editable>' widget.

    START
          the starting position.

    END
          the end position.



 -- Function: gtk-editable-get-selection-bounds (self `<gtk-editable>')
          =>  (ret `bool') (start `int') (end `int')
 -- Method: get-selection-bounds
     Gets the current selection bounds, if there is a selection.

    EDITABLE
          a `<gtk-editable>' widget.

    START
          location to store the starting position, or ``#f''.

    END
          location to store the end position, or ``#f''.

    RET
          ``#t'' if there is a selection.



 -- Function: gtk-editable-insert-text (self `<gtk-editable>')
          (new_text `mchars') (position `int') =>  (ret `int')
 -- Method: insert-text
     Inserts text at a given position.

    EDITABLE
          a `<gtk-editable>' widget.

    NEW-TEXT
          the text to insert.

    NEW-TEXT-LENGTH
          the length of the text to insert, in bytes

    POSITION
          an inout parameter. The caller initializes it to the position
          at which to insert the text. After the call it points at the
          position after the newly inserted text.



 -- Function: gtk-editable-delete-text (self `<gtk-editable>')
          (start_pos `int') (end_pos `int')
 -- Method: delete-text
     Deletes a sequence of characters. The characters that are deleted
     are those characters at positions from START-POS up to, but not
     including END-POS. If END-POS is negative, then the the characters
     deleted will be those characters from START-POS to the end of the
     text.

    EDITABLE
          a `<gtk-editable>' widget.

    START-POS
          the starting position.

    END-POS
          the end position.



 -- Function: gtk-editable-get-chars (self `<gtk-editable>')
          (start_pos `int') (end_pos `int') =>  (ret `mchars')
 -- Method: get-chars
     Retrieves a sequence of characters. The characters that are
     retrieved are those characters at positions from START-POS up to,
     but not including END-POS. If END-POS is negative, then the the
     characters retrieved will be those characters from START-POS to
     the end of the text.

    EDITABLE
          a `<gtk-editable>' widget.

    START-POS
          the starting position.

    END-POS
          the end position.

    RET
          the characters in the indicated region. The result must be
          freed with `g-free' when the application is finished with it.



 -- Function: gtk-editable-cut-clipboard (self `<gtk-editable>')
 -- Method: cut-clipboard
     Causes the characters in the current selection to be copied to the
     clipboard and then deleted from the widget.

    EDITABLE
          a `<gtk-editable>' widget.



 -- Function: gtk-editable-copy-clipboard (self `<gtk-editable>')
 -- Method: copy-clipboard
     Causes the characters in the current selection to be copied to the
     clipboard.

    EDITABLE
          a `<gtk-editable>' widget.



 -- Function: gtk-editable-paste-clipboard (self `<gtk-editable>')
 -- Method: paste-clipboard
     Causes the contents of the clipboard to be pasted into the given
     widget at the current cursor position.

    EDITABLE
          a `<gtk-editable>' widget.



 -- Function: gtk-editable-delete-selection (self `<gtk-editable>')
 -- Method: delete-selection
     Deletes the current contents of the widgets selection and
     disclaims the selection.

    EDITABLE
          a `<gtk-editable>' widget.



 -- Function: gtk-editable-set-position (self `<gtk-editable>')
          (position `int')
 -- Method: set-position
     Sets the cursor position.

    EDITABLE
          a `<gtk-editable>' widget.

    POSITION
          the position of the cursor. The cursor is displayed before
          the character with the given (base 0) index in the widget.
          The value must be less than or equal to the number of
          characters in the widget. A value of -1 indicates that the
          position should be set after the last character in the entry.
          Note that this position is in characters, not in bytes.



 -- Function: gtk-editable-get-position (self `<gtk-editable>') => 
          (ret `int')
 -- Method: get-position
     Retrieves the current cursor position.

    EDITABLE
          a `<gtk-editable>' widget.

    RET
          the position of the cursor. The cursor is displayed before
          the character with the given (base 0) index in the widget.
          The value will be less than or equal to the number of
          characters in the widget. Note that this position is in
          characters, not in bytes.



 -- Function: gtk-editable-set-editable (self `<gtk-editable>')
          (is_editable `bool')
 -- Method: set-editable
     Determines if the user can edit the text in the editable widget or
     not.

    EDITABLE
          a `<gtk-editable>' widget.

    IS-EDITABLE
          ``#t'' if the user is allowed to edit the text in the widget.



 -- Function: gtk-editable-get-editable (self `<gtk-editable>') => 
          (ret `bool')
 -- Method: get-editable
     Retrieves whether EDITABLE is editable. See
     `gtk-editable-set-editable'.

    EDITABLE
          a `<gtk-editable>'

    RET
          ``#t'' if EDITABLE is editable.




File: guile-gnome-gtk.info,  Node: GtkTextIter,  Next: GtkTextMark,  Prev: GtkEditable,  Up: Top

26 GtkTextIter
**************

Text buffer iterator

26.1 Overview
=============

You may wish to begin by reading the text widget conceptual overview
which gives an overview of all the objects and data types related to
the text widget and how they work together.

26.2 Usage
==========

 -- Class: <gtk-text-iter>
     Derives from `<gboxed>'.


 -- Function: gtk-text-iter-get-buffer (self `<gtk-text-iter>') => 
          (ret `<gtk-text-buffer>')
     Returns the `<gtk-text-buffer>' this iterator is associated with.

    ITER
          an iterator

    RET
          the buffer



 -- Function: gtk-text-iter-copy (self `<gtk-text-iter>') => 
          (ret `<gtk-text-iter>')
     Creates a dynamically-allocated copy of an iterator. This function
     is not useful in applications, because iterators can be copied
     with a simple assignment (`GtkTextIter i = j;'). The function is
     used by language bindings.

    ITER
          an iterator

    RET
          a copy of the ITER, free with `gtk-text-iter-free'



 -- Function: gtk-text-iter-get-offset (self `<gtk-text-iter>') => 
          (ret `int')
     Returns the character offset of an iterator. Each character in a
     `<gtk-text-buffer>' has an offset, starting with 0 for the first
     character in the buffer. Use `gtk-text-buffer-get-iter-at-offset'
     to convert an offset back into an iterator.

    ITER
          an iterator

    RET
          a character offset



 -- Function: gtk-text-iter-get-line (self `<gtk-text-iter>') => 
          (ret `int')
     Returns the line number containing the iterator. Lines in a
     `<gtk-text-buffer>' are numbered beginning with 0 for the first
     line in the buffer.

    ITER
          an iterator

    RET
          a line number



 -- Function: gtk-text-iter-get-line-offset (self `<gtk-text-iter>')
          =>  (ret `int')
     Returns the character offset of the iterator, counting from the
     start of a newline-terminated line. The first character on the
     line has offset 0.

    ITER
          an iterator

    RET
          offset from start of line



 -- Function: gtk-text-iter-get-line-index (self `<gtk-text-iter>') => 
          (ret `int')
     Returns the byte index of the iterator, counting from the start of
     a newline-terminated line. Remember that `<gtk-text-buffer>'
     encodes text in UTF-8, and that characters can require a variable
     number of bytes to represent.

    ITER
          an iterator

    RET
          distance from start of line, in bytes



 -- Function: gtk-text-iter-get-char (self `<gtk-text-iter>') => 
          (ret `unsigned-int32')
     Returns the Unicode character at this iterator. (Equivalent to
     operator* on a C++ iterator.) If the element at this iterator is a
     non-character element, such as an image embedded in the buffer,
     the Unicode "unknown" character 0xFFFC is returned. If invoked on
     the end iterator, zero is returned; zero is not a valid Unicode
     character. So you can write a loop which ends when
     `gtk-text-iter-get-char' returns 0.

    ITER
          an iterator

    RET
          a Unicode character, or 0 if ITER is not dereferenceable



 -- Function: gtk-text-iter-get-slice (self `<gtk-text-iter>')
          (end `<gtk-text-iter>') =>  (ret `mchars')
     Returns the text in the given range. A "slice" is an array of
     characters encoded in UTF-8 format, including the Unicode
     "unknown" character 0xFFFC for iterable non-character elements in
     the buffer, such as images. Because images are encoded in the
     slice, byte and character offsets in the returned array will
     correspond to byte offsets in the text buffer. Note that 0xFFFC
     can occur in normal text as well, so it is not a reliable
     indicator that a pixbuf or widget is in the buffer.

    START
          iterator at start of a range

    END
          iterator at end of a range

    RET
          slice of text from the buffer



 -- Function: gtk-text-iter-get-text (self `<gtk-text-iter>')
          (end `<gtk-text-iter>') =>  (ret `mchars')
     Returns _text_ in the given range. If the range contains non-text
     elements such as images, the character and byte offsets in the
     returned string will not correspond to character and byte offsets
     in the buffer. If you want offsets to correspond, see
     `gtk-text-iter-get-slice'.

    START
          iterator at start of a range

    END
          iterator at end of a range

    RET
          array of characters from the buffer



 -- Function: gtk-text-iter-get-visible-slice (self `<gtk-text-iter>')
          (end `<gtk-text-iter>') =>  (ret `mchars')
     Like `gtk-text-iter-get-slice', but invisible text is not included.
     Invisible text is usually invisible because a `<gtk-text-tag>'
     with the "invisible" attribute turned on has been applied to it.

    START
          iterator at start of range

    END
          iterator at end of range

    RET
          slice of text from the buffer



 -- Function: gtk-text-iter-get-visible-text (self `<gtk-text-iter>')
          (end `<gtk-text-iter>') =>  (ret `mchars')
     Like `gtk-text-iter-get-text', but invisible text is not included.
     Invisible text is usually invisible because a `<gtk-text-tag>'
     with the "invisible" attribute turned on has been applied to it.

    START
          iterator at start of range

    END
          iterator at end of range

    RET
          string containing visible text in the range



 -- Function: gtk-text-iter-get-pixbuf (self `<gtk-text-iter>') => 
          (ret `<gdk-pixbuf>')
     If the element at ITER is a pixbuf, the pixbuf is returned (with
     no new reference count added). Otherwise, ``#f'' is returned.

    ITER
          an iterator

    RET
          the pixbuf at ITER



 -- Function: gtk-text-iter-get-marks (self `<gtk-text-iter>') => 
          (ret `gslist-of')
     Returns a list of all `<gtk-text-mark>' at this location. Because
     marks are not iterable (they don't take up any "space" in the
     buffer, they are just marks in between iterable locations),
     multiple marks can exist in the same place. The returned list is
     not in any meaningful order.

    ITER
          an iterator

    RET
          list of `<gtk-text-mark>'



 -- Function: gtk-text-iter-get-toggled-tags (self `<gtk-text-iter>')
          (toggled_on `bool') =>  (ret `gslist-of')
     Returns a list of `<gtk-text-tag>' that are toggled on or off at
     this point. (If TOGGLED-ON is ``#t'', the list contains tags that
     are toggled on.) If a tag is toggled on at ITER, then some
     non-empty range of characters following ITER has that tag applied
     to it. If a tag is toggled off, then some non-empty range
     following ITER does _not_ have the tag applied to it.

    ITER
          an iterator

    TOGGLED-ON
          ``#t'' to get toggled-on tags

    RET
          tags toggled at this point



 -- Function: gtk-text-iter-get-child-anchor (self `<gtk-text-iter>')
          =>  (ret `<gtk-text-child-anchor>')
     If the location at ITER contains a child anchor, the anchor is
     returned (with no new reference count added). Otherwise, ``#f'' is
     returned.

    ITER
          an iterator

    RET
          the anchor at ITER



 -- Function: gtk-text-iter-begins-tag (self `<gtk-text-iter>')
          (tag `<gtk-text-tag>') =>  (ret `bool')
     Returns ``#t'' if TAG is toggled on at exactly this point. If TAG
     is ``#f'', returns ``#t'' if any tag is toggled on at this point.
     Note that the `gtk-text-iter-begins-tag' returns ``#t'' if ITER is
     the _start_ of the tagged range; `gtk-text-iter-has-tag' tells you
     whether an iterator is _within_ a tagged range.

    ITER
          an iterator

    TAG
          a `<gtk-text-tag>', or ``#f''

    RET
          whether ITER is the start of a range tagged with TAG



 -- Function: gtk-text-iter-ends-tag (self `<gtk-text-iter>')
          (tag `<gtk-text-tag>') =>  (ret `bool')
     Returns ``#t'' if TAG is toggled off at exactly this point. If TAG
     is ``#f'', returns ``#t'' if any tag is toggled off at this point.
     Note that the `gtk-text-iter-ends-tag' returns ``#t'' if ITER is
     the _end_ of the tagged range; `gtk-text-iter-has-tag' tells you
     whether an iterator is _within_ a tagged range.

    ITER
          an iterator

    TAG
          a `<gtk-text-tag>', or ``#f''

    RET
          whether ITER is the end of a range tagged with TAG



 -- Function: gtk-text-iter-toggles-tag (self `<gtk-text-iter>')
          (tag `<gtk-text-tag>') =>  (ret `bool')
     This is equivalent to (`gtk-text-iter-begins-tag' ||
     `gtk-text-iter-ends-tag'), i.e. it tells you whether a range with
     TAG applied to it begins _or_ ends at ITER.

    ITER
          an iterator

    TAG
          a `<gtk-text-tag>', or ``#f''

    RET
          whether TAG is toggled on or off at ITER



 -- Function: gtk-text-iter-has-tag (self `<gtk-text-iter>')
          (tag `<gtk-text-tag>') =>  (ret `bool')
     Returns ``#t'' if ITER is within a range tagged with TAG.

    ITER
          an iterator

    TAG
          a `<gtk-text-tag>'

    RET
          whether ITER is tagged with TAG



 -- Function: gtk-text-iter-get-tags (self `<gtk-text-iter>') => 
          (ret `gslist-of')
     Returns a list of tags that apply to ITER, in ascending order of
     priority (highest-priority tags are last). The `<gtk-text-tag>' in
     the list don't have a reference added, but you have to free the
     list itself.

    ITER
          a `<gtk-text-iter>'

    RET
          list of `<gtk-text-tag>'



 -- Function: gtk-text-iter-editable (self `<gtk-text-iter>')
          (default_setting `bool') =>  (ret `bool')
     Returns whether the character at ITER is within an editable region
     of text. Non-editable text is "locked" and can't be changed by the
     user via `<gtk-text-view>'. This function is simply a convenience
     wrapper around `gtk-text-iter-get-attributes'. If no tags applied
     to this text affect editability, DEFAULT-SETTING will be returned.

     You don't want to use this function to decide whether text can be
     inserted at ITER, because for insertion you don't want to know
     whether the char at ITER is inside an editable range, you want to
     know whether a new character inserted at ITER would be inside an
     editable range. Use `gtk-text-iter-can-insert' to handle this case.

    ITER
          an iterator

    DEFAULT-SETTING
          ``#t'' if text is editable by default

    RET
          whether ITER is inside an editable range



 -- Function: gtk-text-iter-can-insert (self `<gtk-text-iter>')
          (default_editability `bool') =>  (ret `bool')
     Considering the default editability of the buffer, and tags that
     affect editability, determines whether text inserted at ITER would
     be editable.  If text inserted at ITER would be editable then the
     user should be allowed to insert text at ITER.
     `gtk-text-buffer-insert-interactive' uses this function to decide
     whether insertions are allowed at a given position.

    ITER
          an iterator

    DEFAULT-EDITABILITY
          ``#t'' if text is editable by default

    RET
          whether text inserted at ITER would be editable



 -- Function: gtk-text-iter-starts-word (self `<gtk-text-iter>') => 
          (ret `bool')
     Determines whether ITER begins a natural-language word. Word
     breaks are determined by Pango and should be correct for nearly
     any language (if not, the correct fix would be to the Pango word
     break algorithms).

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER is at the start of a word



 -- Function: gtk-text-iter-ends-word (self `<gtk-text-iter>') => 
          (ret `bool')
     Determines whether ITER ends a natural-language word. Word breaks
     are determined by Pango and should be correct for nearly any
     language (if not, the correct fix would be to the Pango word break
     algorithms).

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER is at the end of a word



 -- Function: gtk-text-iter-inside-word (self `<gtk-text-iter>') => 
          (ret `bool')
     Determines whether ITER is inside a natural-language word (as
     opposed to say inside some whitespace). Word breaks are determined
     by Pango and should be correct for nearly any language (if not,
     the correct fix would be to the Pango word break algorithms).

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER is inside a word



 -- Function: gtk-text-iter-starts-line (self `<gtk-text-iter>') => 
          (ret `bool')
     Returns ``#t'' if ITER begins a paragraph, i.e. if
     `gtk-text-iter-get-line-offset' would return 0. However this
     function is potentially more efficient than
     `gtk-text-iter-get-line-offset' because it doesn't have to compute
     the offset, it just has to see whether it's 0.

    ITER
          an iterator

    RET
          whether ITER begins a line



 -- Function: gtk-text-iter-ends-line (self `<gtk-text-iter>') => 
          (ret `bool')
     Returns ``#t'' if ITER points to the start of the paragraph
     delimiter characters for a line (delimiters will be either a
     newline, a carriage return, a carriage return followed by a
     newline, or a Unicode paragraph separator character). Note that an
     iterator pointing to the \n of a \r\n pair will not be counted as
     the end of a line, the line ends before the \r. The end iterator
     is considered to be at the end of a line, even though there are no
     paragraph delimiter chars there.

    ITER
          an iterator

    RET
          whether ITER is at the end of a line



 -- Function: gtk-text-iter-starts-sentence (self `<gtk-text-iter>')
          =>  (ret `bool')
     Determines whether ITER begins a sentence. Sentence boundaries are
     determined by Pango and should be correct for nearly any language
     (if not, the correct fix would be to the Pango text boundary
     algorithms).

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER is at the start of a sentence.



 -- Function: gtk-text-iter-ends-sentence (self `<gtk-text-iter>') => 
          (ret `bool')
     Determines whether ITER ends a sentence. Sentence boundaries are
     determined by Pango and should be correct for nearly any language
     (if not, the correct fix would be to the Pango text boundary
     algorithms).

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER is at the end of a sentence.



 -- Function: gtk-text-iter-inside-sentence (self `<gtk-text-iter>')
          =>  (ret `bool')
     Determines whether ITER is inside a sentence (as opposed to in
     between two sentences, e.g. after a period and before the first
     letter of the next sentence). Sentence boundaries are determined
     by Pango and should be correct for nearly any language (if not,
     the correct fix would be to the Pango text boundary algorithms).

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER is inside a sentence.



 -- Function: gtk-text-iter-is-cursor-position (self `<gtk-text-iter>')
          =>  (ret `bool')
     See `gtk-text-iter-forward-cursor-position' or `<pango-log-attr>'
     or `pango-break' for details on what a cursor position is.

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if the cursor can be placed at ITER



 -- Function: gtk-text-iter-get-chars-in-line (self `<gtk-text-iter>')
          =>  (ret `int')
     Returns the number of characters in the line containing ITER,
     including the paragraph delimiters.

    ITER
          an iterator

    RET
          number of characters in the line



 -- Function: gtk-text-iter-get-bytes-in-line (self `<gtk-text-iter>')
          =>  (ret `int')
     Returns the number of bytes in the line containing ITER, including
     the paragraph delimiters.

    ITER
          an iterator

    RET
          number of bytes in the line



 -- Function: gtk-text-iter-get-attributes (self `<gtk-text-iter>')
          (values `<gtk-text-attributes>') =>  (ret `bool')
     Computes the effect of any tags applied to this spot in the text.
     The VALUES parameter should be initialized to the default settings
     you wish to use if no tags are in effect. You'd typically obtain
     the defaults from `gtk-text-view-get-default-attributes'.

     `gtk-text-iter-get-attributes' will modify VALUES, applying the
     effects of any tags present at ITER. If any tags affected VALUES,
     the function returns ``#t''.

    ITER
          an iterator

    VALUES
          a `<gtk-text-attributes>' to be filled in

    RET
          ``#t'' if VALUES was modified



 -- Function: gtk-text-iter-get-language (self `<gtk-text-iter>') => 
          (ret `<pango-language>')
     A convenience wrapper around `gtk-text-iter-get-attributes', which
     returns the language in effect at ITER. If no tags affecting
     language apply to ITER, the return value is identical to that of
     `gtk-get-default-language'.

    ITER
          an iterator

    RET
          language in effect at ITER



 -- Function: gtk-text-iter-is-end (self `<gtk-text-iter>') => 
          (ret `bool')
     Returns ``#t'' if ITER is the end iterator, i.e. one past the last
     dereferenceable iterator in the buffer. `gtk-text-iter-is-end' is
     the most efficient way to check whether an iterator is the end
     iterator.

    ITER
          an iterator

    RET
          whether ITER is the end iterator



 -- Function: gtk-text-iter-is-start (self `<gtk-text-iter>') => 
          (ret `bool')
     Returns ``#t'' if ITER is the first iterator in the buffer, that
     is if ITER has a character offset of 0.

    ITER
          an iterator

    RET
          whether ITER is the first in the buffer



 -- Function: gtk-text-iter-forward-char (self `<gtk-text-iter>') => 
          (ret `bool')
     Moves ITER forward by one character offset. Note that images
     embedded in the buffer occupy 1 character slot, so
     `gtk-text-iter-forward-char' may actually move onto an image
     instead of a character, if you have images in your buffer. If ITER
     is the end iterator or one character before it, ITER will now
     point at the end iterator, and `gtk-text-iter-forward-char'
     returns ``#f'' for convenience when writing loops.

    ITER
          an iterator

    RET
          whether ITER moved and is dereferenceable



 -- Function: gtk-text-iter-backward-char (self `<gtk-text-iter>') => 
          (ret `bool')
     Moves backward by one character offset. Returns ``#t'' if movement
     was possible; if ITER was the first in the buffer (character
     offset 0), `gtk-text-iter-backward-char' returns ``#f'' for
     convenience when writing loops.

    ITER
          an iterator

    RET
          whether movement was possible



 -- Function: gtk-text-iter-forward-chars (self `<gtk-text-iter>')
          (count `int') =>  (ret `bool')
     Moves COUNT characters if possible (if COUNT would move past the
     start or end of the buffer, moves to the start or end of the
     buffer). The return value indicates whether the new position of
     ITER is different from its original position, and dereferenceable
     (the last iterator in the buffer is not dereferenceable). If COUNT
     is 0, the function does nothing and returns ``#f''.

    ITER
          an iterator

    COUNT
          number of characters to move, may be negative

    RET
          whether ITER moved and is dereferenceable



 -- Function: gtk-text-iter-backward-chars (self `<gtk-text-iter>')
          (count `int') =>  (ret `bool')
     Moves COUNT characters backward, if possible (if COUNT would move
     past the start or end of the buffer, moves to the start or end of
     the buffer).  The return value indicates whether the iterator
     moved onto a dereferenceable position; if the iterator didn't
     move, or moved onto the end iterator, then ``#f'' is returned. If
     COUNT is 0, the function does nothing and returns ``#f''.

    ITER
          an iterator

    COUNT
          number of characters to move

    RET
          whether ITER moved and is dereferenceable



 -- Function: gtk-text-iter-forward-line (self `<gtk-text-iter>') => 
          (ret `bool')
     Moves ITER to the start of the next line. Returns ``#t'' if there
     was a next line to move to, and ``#f'' if ITER was simply moved to
     the end of the buffer and is now not dereferenceable, or if ITER
     was already at the end of the buffer.

    ITER
          an iterator

    RET
          whether ITER can be dereferenced



 -- Function: gtk-text-iter-backward-line (self `<gtk-text-iter>') => 
          (ret `bool')
     Moves ITER to the start of the previous line. Returns ``#t'' if
     ITER could be moved; i.e. if ITER was at character offset 0, this
     function returns ``#f''. Therefore if ITER was already on line 0,
     but not at the start of the line, ITER is snapped to the start of
     the line and the function returns ``#t''. (Note that this implies
     that in a loop calling this function, the line number may not
     change on every iteration, if your first iteration is on line 0.)

    ITER
          an iterator

    RET
          whether ITER moved



 -- Function: gtk-text-iter-forward-lines (self `<gtk-text-iter>')
          (count `int') =>  (ret `bool')
     Moves COUNT lines forward, if possible (if COUNT would move past
     the start or end of the buffer, moves to the start or end of the
     buffer). The return value indicates whether the iterator moved
     onto a dereferenceable position; if the iterator didn't move, or
     moved onto the end iterator, then ``#f'' is returned. If COUNT is
     0, the function does nothing and returns ``#f''. If COUNT is
     negative, moves backward by 0 - COUNT lines.

    ITER
          a `<gtk-text-iter>'

    COUNT
          number of lines to move forward

    RET
          whether ITER moved and is dereferenceable



 -- Function: gtk-text-iter-backward-lines (self `<gtk-text-iter>')
          (count `int') =>  (ret `bool')
     Moves COUNT lines backward, if possible (if COUNT would move past
     the start or end of the buffer, moves to the start or end of the
     buffer). The return value indicates whether the iterator moved
     onto a dereferenceable position; if the iterator didn't move, or
     moved onto the end iterator, then ``#f'' is returned. If COUNT is
     0, the function does nothing and returns ``#f''. If COUNT is
     negative, moves forward by 0 - COUNT lines.

    ITER
          a `<gtk-text-iter>'

    COUNT
          number of lines to move backward

    RET
          whether ITER moved and is dereferenceable



 -- Function: gtk-text-iter-forward-word-ends (self `<gtk-text-iter>')
          (count `int') =>  (ret `bool')
     Calls `gtk-text-iter-forward-word-end' up to COUNT times.

    ITER
          a `<gtk-text-iter>'

    COUNT
          number of times to move

    RET
          ``#t'' if ITER moved and is not the end iterator



 -- Function: gtk-text-iter-backward-word-starts
          (self `<gtk-text-iter>') (count `int') =>  (ret `bool')
     Calls `gtk-text-iter-backward-word-start' up to COUNT times.

    ITER
          a `<gtk-text-iter>'

    COUNT
          number of times to move

    RET
          ``#t'' if ITER moved and is not the end iterator



 -- Function: gtk-text-iter-forward-word-end (self `<gtk-text-iter>')
          =>  (ret `bool')
     Moves forward to the next word end. (If ITER is currently on a
     word end, moves forward to the next one after that.) Word breaks
     are determined by Pango and should be correct for nearly any
     language (if not, the correct fix would be to the Pango word break
     algorithms).

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER moved and is not the end iterator



 -- Function: gtk-text-iter-backward-word-start
          (self `<gtk-text-iter>') =>  (ret `bool')
     Moves backward to the previous word start. (If ITER is currently
     on a word start, moves backward to the next one after that.) Word
     breaks are determined by Pango and should be correct for nearly
     any language (if not, the correct fix would be to the Pango word
     break algorithms).

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER moved and is not the end iterator



 -- Function: gtk-text-iter-forward-sentence-end
          (self `<gtk-text-iter>') =>  (ret `bool')
     Moves forward to the next sentence end. (If ITER is at the end of a
     sentence, moves to the next end of sentence.) Sentence boundaries
     are determined by Pango and should be correct for nearly any
     language (if not, the correct fix would be to the Pango text
     boundary algorithms).

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER moved and is not the end iterator



 -- Function: gtk-text-iter-forward-sentence-ends
          (self `<gtk-text-iter>') (count `int') =>  (ret `bool')
     Calls `gtk-text-iter-forward-sentence-end'COUNT times (or until
     `gtk-text-iter-forward-sentence-end' returns ``#f''). If COUNT is
     negative, moves backward instead of forward.

    ITER
          a `<gtk-text-iter>'

    COUNT
          number of sentences to move

    RET
          ``#t'' if ITER moved and is not the end iterator



 -- Function: gtk-text-iter-forward-visible-line
          (self `<gtk-text-iter>') =>  (ret `bool')
     Moves ITER to the start of the next visible line. Returns ``#t''
     if there was a next line to move to, and ``#f'' if ITER was simply
     moved to the end of the buffer and is now not dereferenceable, or
     if ITER was already at the end of the buffer.

    ITER
          an iterator

    RET
          whether ITER can be dereferenced


     Since 2.8


 -- Function: gtk-text-iter-backward-visible-line
          (self `<gtk-text-iter>') =>  (ret `bool')
     Moves ITER to the start of the previous visible line. Returns
     ``#t'' if ITER could be moved; i.e. if ITER was at character
     offset 0, this function returns ``#f''. Therefore if ITER was
     already on line 0, but not at the start of the line, ITER is
     snapped to the start of the line and the function returns ``#t''.
     (Note that this implies that in a loop calling this function, the
     line number may not change on every iteration, if your first
     iteration is on line 0.)

    ITER
          an iterator

    RET
          whether ITER moved


     Since 2.8


 -- Function: gtk-text-iter-forward-visible-lines
          (self `<gtk-text-iter>') (count `int') =>  (ret `bool')
     Moves COUNT visible lines forward, if possible (if COUNT would move
     past the start or end of the buffer, moves to the start or end of
     the buffer).  The return value indicates whether the iterator
     moved onto a dereferenceable position; if the iterator didn't
     move, or moved onto the end iterator, then ``#f'' is returned. If
     COUNT is 0, the function does nothing and returns ``#f''. If COUNT
     is negative, moves backward by 0 - COUNT lines.

    ITER
          a `<gtk-text-iter>'

    COUNT
          number of lines to move forward

    RET
          whether ITER moved and is dereferenceable


     Since 2.8


 -- Function: gtk-text-iter-set-offset (self `<gtk-text-iter>')
          (char_offset `int')
     Sets ITER to point to CHAR-OFFSET. CHAR-OFFSET counts from the
     start of the entire text buffer, starting with 0.

    ITER
          a `<gtk-text-iter>'

    CHAR-OFFSET
          a character number



 -- Function: gtk-text-iter-set-line (self `<gtk-text-iter>')
          (line_number `int')
     Moves iterator ITER to the start of the line LINE-NUMBER. If
     LINE-NUMBER is negative or larger than the number of lines in the
     buffer, moves ITER to the start of the last line in the buffer.

    ITER
          a `<gtk-text-iter>'

    LINE-NUMBER
          line number (counted from 0)



 -- Function: gtk-text-iter-set-line-offset (self `<gtk-text-iter>')
          (char_on_line `int')
     Moves ITER within a line, to a new _character_ (not byte) offset.
     The given character offset must be less than or equal to the
     number of characters in the line; if equal, ITER moves to the
     start of the next line. See `gtk-text-iter-set-line-index' if you
     have a byte index rather than a character offset.

    ITER
          a `<gtk-text-iter>'

    CHAR-ON-LINE
          a character offset relative to the start of ITER's current
          line



 -- Function: gtk-text-iter-set-line-index (self `<gtk-text-iter>')
          (byte_on_line `int')
     Same as `gtk-text-iter-set-line-offset', but works with a _byte_
     index. The given byte index must be at the start of a character,
     it can't be in the middle of a UTF-8 encoded character.

    ITER
          a `<gtk-text-iter>'

    BYTE-ON-LINE
          a byte index relative to the start of ITER's current line



 -- Function: gtk-text-iter-forward-to-end (self `<gtk-text-iter>')
     Moves ITER forward to the "end iterator," which points one past
     the last valid character in the buffer. `gtk-text-iter-get-char'
     called on the end iterator returns 0, which is convenient for
     writing loops.

    ITER
          a `<gtk-text-iter>'



 -- Function: gtk-text-iter-forward-to-line-end
          (self `<gtk-text-iter>') =>  (ret `bool')
     Moves the iterator to point to the paragraph delimiter characters,
     which will be either a newline, a carriage return, a carriage
     return/newline in sequence, or the Unicode paragraph separator
     character. If the iterator is already at the paragraph delimiter
     characters, moves to the paragraph delimiter characters for the
     next line. If ITER is on the last line in the buffer, which does
     not end in paragraph delimiters, moves to the end iterator (end of
     the last line), and returns ``#f''.

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if we moved and the new location is not the end
          iterator



 -- Function: gtk-text-iter-forward-to-tag-toggle
          (self `<gtk-text-iter>') (tag `<gtk-text-tag>') => 
          (ret `bool')
     Moves forward to the next toggle (on or off) of the
     `<gtk-text-tag>'TAG, or to the next toggle of any tag if TAG is
     ``#f''. If no matching tag toggles are found, returns ``#f'',
     otherwise ``#t''. Does not return toggles located at ITER, only
     toggles after ITER. Sets ITER to the location of the toggle, or to
     the end of the buffer if no toggle is found.

    ITER
          a `<gtk-text-iter>'

    TAG
          a `<gtk-text-tag>', or ``#f''

    RET
          whether we found a tag toggle after ITER



 -- Function: gtk-text-iter-forward-search (self `<gtk-text-iter>')
          (str `mchars') (flags `<gtk-text-search-flags>')
          (match_start `<gtk-text-iter>') (match_end `<gtk-text-iter>')
          (limit `<gtk-text-iter>') =>  (ret `bool')
     Searches forward for STR. Any match is returned by setting
     MATCH-START to the first character of the match and MATCH-END to
     the first character after the match. The search will not continue
     past LIMIT.  Note that a search is a linear or O(n) operation, so
     you may wish to use LIMIT to avoid locking up your UI on large
     buffers.

     If the `<gtk-text-search-visible-only>' flag is present, the match
     may have invisible text interspersed in STR. i.e. STR will be a
     possibly-noncontiguous subsequence of the matched range.
     similarly, if you specify `<gtk-text-search-text-only>', the match
     may have pixbufs or child widgets mixed inside the matched range.
     If these flags are not given, the match must be exact; the special
     0xFFFC character in STR will match embedded pixbufs or child
     widgets.

    ITER
          start of search

    STR
          a search string

    FLAGS
          flags affecting how the search is done

    MATCH-START
          return location for start of match, or ``#f''

    MATCH-END
          return location for end of match, or ``#f''

    LIMIT
          bound for the search, or ``#f'' for the end of the buffer

    RET
          whether a match was found



 -- Function: gtk-text-iter-backward-search (self `<gtk-text-iter>')
          (str `mchars') (flags `<gtk-text-search-flags>')
          (match_start `<gtk-text-iter>') (match_end `<gtk-text-iter>')
          (limit `<gtk-text-iter>') =>  (ret `bool')
     Same as `gtk-text-iter-forward-search', but moves backward.

    ITER
          a `<gtk-text-iter>' where the search begins

    STR
          search string

    FLAGS
          bitmask of flags affecting the search

    MATCH-START
          return location for start of match, or ``#f''

    MATCH-END
          return location for end of match, or ``#f''

    LIMIT
          location of last possible MATCH-START, or ``#f'' for start of
          buffer

    RET
          whether a match was found



 -- Function: gtk-text-iter-equal (self `<gtk-text-iter>')
          (rhs `<gtk-text-iter>') =>  (ret `bool')
     Tests whether two iterators are equal, using the fastest possible
     mechanism.  This function is very fast; you can expect it to
     perform better than e.g.  getting the character offset for each
     iterator and comparing the offsets yourself. Also, it's a bit
     faster than `gtk-text-iter-compare'.

    LHS
          a `<gtk-text-iter>'

    RHS
          another `<gtk-text-iter>'

    RET
          ``#t'' if the iterators point to the same place in the buffer



 -- Function: gtk-text-iter-compare (self `<gtk-text-iter>')
          (rhs `<gtk-text-iter>') =>  (ret `int')
     A `qsort'-style function that returns negative if LHS is less than
     RHS, positive if LHS is greater than RHS, and 0 if they're equal.
     Ordering is in character offset order, i.e. the first character in
     the buffer is less than the second character in the buffer.

    LHS
          a `<gtk-text-iter>'

    RHS
          another `<gtk-text-iter>'

    RET
          -1 if LHS is less than RHS, 1 if LHS is greater, 0 if they are
          equal



 -- Function: gtk-text-iter-in-range (self `<gtk-text-iter>')
          (start `<gtk-text-iter>') (end `<gtk-text-iter>') => 
          (ret `bool')
     Checks whether ITER falls in the range [START, END).  START and
     END must be in ascending order.

    ITER
          a `<gtk-text-iter>'

    START
          start of range

    END
          end of range

    RET
          ``#t'' if ITER is in the range



 -- Function: gtk-text-iter-order (self `<gtk-text-iter>')
          (second `<gtk-text-iter>')
     Swaps the value of FIRST and SECOND if SECOND comes before FIRST
     in the buffer. That is, ensures that FIRST and SECOND are in
     sequence. Most text buffer functions that take a range call this
     automatically on your behalf, so there's no real reason to call it
     yourself in those cases. There are some exceptions, such as
     `gtk-text-iter-in-range', that expect a pre-sorted range.

    FIRST
          a `<gtk-text-iter>'

    SECOND
          another `<gtk-text-iter>'




File: guile-gnome-gtk.info,  Node: GtkTextMark,  Next: GtkTextBuffer,  Prev: GtkTextIter,  Up: Top

27 GtkTextMark
**************

A position in the buffer preserved across buffer modifications

27.1 Overview
=============

You may wish to begin by reading the text widget conceptual overview
which gives an overview of all the objects and data types related to
the text widget and how they work together.

   A `<gtk-text-mark>' is like a bookmark in a text buffer; it
preserves a position in the text. You can convert the mark to an
iterator using `gtk-text-buffer-get-iter-at-mark'. Unlike iterators,
marks remain valid across buffer mutations, because their behavior is
defined when text is inserted or deleted. When text containing a mark
is deleted, the mark remains in the position originally occupied by the
deleted text. When text is inserted at a mark, a mark with "left
gravity" will be moved to the beginning of the newly-inserted text, and
a mark with "right gravity" will be moved to the end.

   "left" and "right" here refer to logical direction (left is the
toward the start of the buffer); in some languages such as Hebrew the
logically-leftmost text is not actually on the left when displayed.

   Marks are reference counted, but the reference count only controls
the validity of the memory; marks can be deleted from the buffer at any
time with `gtk-text-buffer-delete-mark'. Once deleted from the buffer,
a mark is essentially useless.

   Marks optionally have names; these can be convenient to avoid
passing the `<gtk-text-mark>' object around.

   Marks are typically created using the `gtk-text-buffer-create-mark'
function.

27.2 Usage
==========

 -- Class: <gtk-text-mark>
     Derives from `<gobject>'.

     This class defines the following properties:

    `name'
          Mark name

    `left-gravity'
          Whether the mark has left gravity



 -- Function: gtk-text-mark-set-visible (self `<gtk-text-mark>')
          (setting `bool')
 -- Method: set-visible
     Sets the visibility of MARK; the insertion point is normally
     visible, i.e.  you can see it as a vertical bar. Also, the text
     widget uses a visible mark to indicate where a drop will occur
     when dragging-and-dropping text. Most other marks are not visible.
     Marks are not visible by default.

    MARK
          a `<gtk-text-mark>'

    SETTING
          visibility of mark



 -- Function: gtk-text-mark-get-visible (self `<gtk-text-mark>') => 
          (ret `bool')
 -- Method: get-visible
     Returns ``#t'' if the mark is visible (i.e. a cursor is displayed
     for it)

    MARK
          a `<gtk-text-mark>'

    RET
          ``#t'' if visible



 -- Function: gtk-text-mark-get-deleted (self `<gtk-text-mark>') => 
          (ret `bool')
 -- Method: get-deleted
     Returns ``#t'' if the mark has been removed from its buffer with
     `gtk-text-buffer-delete-mark'. Marks can't be used once deleted.

    MARK
          a `<gtk-text-mark>'

    RET
          whether the mark is deleted



 -- Function: gtk-text-mark-get-name (self `<gtk-text-mark>') => 
          (ret `mchars')
 -- Method: get-name
     Returns the mark name; returns NULL for anonymous marks.

    MARK
          a `<gtk-text-mark>'

    RET
          mark name



 -- Function: gtk-text-mark-get-buffer (self `<gtk-text-mark>') => 
          (ret `<gtk-text-buffer>')
 -- Method: get-buffer
     Gets the buffer this mark is located inside, or NULL if the mark
     is deleted.

    MARK
          a `<gtk-text-mark>'

    RET
          the mark's `<gtk-text-buffer>'



 -- Function: gtk-text-mark-get-left-gravity (self `<gtk-text-mark>')
          =>  (ret `bool')
 -- Method: get-left-gravity
     Determines whether the mark has left gravity.

    MARK
          a `<gtk-text-mark>'

    RET
          ``#t'' if the mark has left gravity, ``#f'' otherwise



