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: GtkToolbar,  Next: GtkToolItem,  Prev: GtkTearoffMenuItem,  Up: Top

65 GtkToolbar
*************

Create bars of buttons and other widgets

65.1 Overview
=============

A toolbar is created with a call to `gtk-toolbar-new'.

   A toolbar can contain instances of a subclass of `<gtk-tool-item>'.
To add a `<gtk-tool-item>' to the a toolbar, use `gtk-toolbar-insert'.
To remove an item from the toolbar use `gtk-container-remove'. To add a
button to the toolbar, add an instance of `<gtk-tool-button>'.

   Toolbar items can be visually grouped by adding instances of
`<gtk-separator-tool-item>' to the toolbar. If a
`<gtk-separator-tool-item>' has the "expand" property set to ``#t'' and
the "draw" property set to ``#f'' the effect is to force all following
items to the end of the toolbar.

   Creating a context menu for the toolbar can be done by connecting to
the `<gtk-toolbar::popup-context-menu>' signal.

65.2 Usage
==========

 -- Class: <gtk-toolbar>
     Derives from `<gtk-container>'.

     This class defines the following properties:

    `orientation'
          The orientation of the toolbar

    `toolbar-style'
          How to draw the toolbar

    `show-arrow'
          If an arrow should be shown if the toolbar doesn't fit

    `tooltips'
          If the tooltips of the toolbar should be active or not

    `icon-size'
          Size of icons in this toolbar

    `icon-size-set'
          Whether the icon-size property has been set



 -- Signal on <gtk-toolbar>: orientation-changed
          (arg0 `<gtk-orientation>')
     Emitted when the orientation of the toolbar changes.


 -- Signal on <gtk-toolbar>: style-changed (arg0 `<gtk-toolbar-style>')
     Emitted when the style of the toolbar changes.


 -- Signal on <gtk-toolbar>: popup-context-menu (arg0 `<gint>')
          (arg1 `<gint>') (arg2 `<gint>') => `<gboolean>'
     Emitted when the user right-clicks the toolbar or uses the
     keybinding to display a popup menu.

     Application developers should handle this signal if they want to
     display a context menu on the toolbar. The context-menu should
     appear at the coordinates given by X and Y. The mouse button
     number is given by the BUTTON parameter. If the menu was popped up
     using the keybaord, BUTTON is -1.


 -- Signal on <gtk-toolbar>: focus-home-or-end (arg0 `<gboolean>')
          => `<gboolean>'
     A keybinding signal used internally by GTK+. This signal can't be
     used in application code


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

    RET
          the newly-created toolbar.



 -- Function: gtk-toolbar-insert (self `<gtk-toolbar>')
          (item `<gtk-tool-item>') (pos `int')
 -- Method: insert
     Insert a `<gtk-tool-item>' into the toolbar at position POS. If
     POS is 0 the item is prepended to the start of the toolbar. If POS
     is negative, the item is appended to the end of the toolbar.

    TOOLBAR
          a `<gtk-toolbar>'

    ITEM
          a `<gtk-tool-item>'

    POS
          the position of the new item


     Since 2.4


 -- Function: gtk-toolbar-get-item-index (self `<gtk-toolbar>')
          (item `<gtk-tool-item>') =>  (ret `int')
 -- Method: get-item-index
     Returns the position of ITEM on the toolbar, starting from 0. It
     is an error if ITEM is not a child of the toolbar.

    TOOLBAR
          a `<gtk-toolbar>'

    ITEM
          a `<gtk-tool-item>' that is a child of TOOLBAR

    RET
          the position of item on the toolbar.


     Since 2.4


 -- Function: gtk-toolbar-get-n-items (self `<gtk-toolbar>') => 
          (ret `int')
 -- Method: get-n-items
     Returns the number of items on the toolbar.

    TOOLBAR
          a `<gtk-toolbar>'

    RET
          the number of items on the toolbar


     Since 2.4


 -- Function: gtk-toolbar-get-nth-item (self `<gtk-toolbar>') (n `int')
          =>  (ret `<gtk-tool-item>')
 -- Method: get-nth-item
     Returns the N'th item on TOOLBAR, or ``#f'' if the toolbar does
     not contain an N'th item.

    TOOLBAR
          a `<gtk-toolbar>'

    N
          A position on the toolbar

    RET
          The N'th `<gtk-tool-item>' on TOOLBAR, or ``#f'' if there
          isn't an N'th item.


     Since 2.4


 -- Function: gtk-toolbar-get-drop-index (self `<gtk-toolbar>')
          (x `int') (y `int') =>  (ret `int')
 -- Method: get-drop-index
     Returns the position corresponding to the indicated point on
     TOOLBAR. This is useful when dragging items to the toolbar: this
     function returns the position a new item should be inserted.

     X and Y are in TOOLBAR coordinates.

    TOOLBAR
          a `<gtk-toolbar>'

    X
          x coordinate of a point on the toolbar

    Y
          y coordinate of a point on the toolbar

    RET
          The position corresponding to the point (X, Y) on the toolbar.


     Since 2.4


 -- Function: gtk-toolbar-set-drop-highlight-item
          (self `<gtk-toolbar>') (tool_item `<gtk-tool-item>')
          (index_ `int')
 -- Method: set-drop-highlight-item
     Highlights TOOLBAR to give an idea of what it would look like if
     ITEM was added to TOOLBAR at the position indicated by INDEX.  If
     ITEM is ``#f'', highlighting is turned off. In that case INDEX is
     ignored.

     The TOOL-ITEM passed to this function must not be part of any
     widget hierarchy. When an item is set as drop highlight item it
     can not added to any widget hierarchy or used as highlight item
     for another toolbar.

    TOOLBAR
          a `<gtk-toolbar>'

    TOOL-ITEM
          a `<gtk-tool-item>', or ``#f'' to turn of highlighting

    INDEX
          a position on TOOLBAR


     Since 2.4


 -- Function: gtk-toolbar-set-show-arrow (self `<gtk-toolbar>')
          (show_arrow `bool')
 -- Method: set-show-arrow
     Sets whether to show an overflow menu when TOOLBAR doesn't have
     room for all items on it. If ``#t'', items that there are not room
     are available through an overflow menu.

    TOOLBAR
          a `<gtk-toolbar>'

    SHOW-ARROW
          Whether to show an overflow menu


     Since 2.4


 -- Function: gtk-toolbar-set-orientation (self `<gtk-toolbar>')
          (orientation `<gtk-orientation>')
 -- Method: set-orientation
     Sets whether a toolbar should appear horizontally or vertically.

    TOOLBAR
          a `<gtk-toolbar>'.

    ORIENTATION
          a new `<gtk-orientation>'.



 -- Function: gtk-toolbar-set-tooltips (self `<gtk-toolbar>')
          (enable `bool')
 -- Method: set-tooltips
     Sets if the tooltips of a toolbar should be active or not.

    TOOLBAR
          a `<gtk-toolbar>'.

    ENABLE
          set to ``#f'' to disable the tooltips, or ``#t'' to enable
          them.



 -- Function: gtk-toolbar-get-show-arrow (self `<gtk-toolbar>') => 
          (ret `bool')
 -- Method: get-show-arrow
     Returns whether the toolbar has an overflow menu. See
     `gtk-toolbar-set-show-arrow'.

    TOOLBAR
          a `<gtk-toolbar>'

    RET
          ``#t'' if the toolbar has an overflow menu.


     Since 2.4


 -- Function: gtk-toolbar-get-orientation (self `<gtk-toolbar>') => 
          (ret `<gtk-orientation>')
 -- Method: get-orientation
     Retrieves the current orientation of the toolbar. See
     `gtk-toolbar-set-orientation'.

    TOOLBAR
          a `<gtk-toolbar>'

    RET
          the orientation



 -- Function: gtk-toolbar-get-style (self `<gtk-toolbar>') => 
          (ret `<gtk-toolbar-style>')
 -- Method: get-style
     Retrieves whether the toolbar has text, icons, or both . See
     `gtk-toolbar-set-style'.

    TOOLBAR
          a `<gtk-toolbar>'

    RET
          the current style of TOOLBAR



 -- Function: gtk-toolbar-get-icon-size (self `<gtk-toolbar>') => 
          (ret `<gtk-icon-size>')
 -- Method: get-icon-size
     Retrieves the icon size for the toolbar. See
     `gtk-toolbar-set-icon-size'.

    TOOLBAR
          a `<gtk-toolbar>'

    RET
          the current icon size for the icons on the toolbar.



 -- Function: gtk-toolbar-get-tooltips (self `<gtk-toolbar>') => 
          (ret `bool')
 -- Method: get-tooltips
     Retrieves whether tooltips are enabled. See
     `gtk-toolbar-set-tooltips'.

    TOOLBAR
          a `<gtk-toolbar>'

    RET
          ``#t'' if tooltips are enabled



 -- Function: gtk-toolbar-get-relief-style (self `<gtk-toolbar>') => 
          (ret `<gtk-relief-style>')
 -- Method: get-relief-style
     Returns the relief style of buttons on TOOLBAR. See
     `gtk-button-set-relief'.

    TOOLBAR
          a `<gtk-toolbar>'

    RET
          The relief style of buttons on TOOLBAR.


     Since 2.4


 -- Function: gtk-toolbar-set-style (self `<gtk-toolbar>')
          (style `<gtk-toolbar-style>')
 -- Method: set-style
     Alters the view of TOOLBAR to display either icons only, text
     only, or both.

    TOOLBAR
          a `<gtk-toolbar>'.

    STYLE
          the new style for TOOLBAR.



 -- Function: gtk-toolbar-unset-style (self `<gtk-toolbar>')
 -- Method: unset-style
     Unsets a toolbar style set with `gtk-toolbar-set-style', so that
     user preferences will be used to determine the toolbar style.

    TOOLBAR
          a `<gtk-toolbar>'




File: guile-gnome-gtk.info,  Node: GtkToolItem,  Next: GtkSeparatorToolItem,  Prev: GtkToolbar,  Up: Top

66 GtkToolItem
**************

The base class of widgets that can be added to GtkToolbar

66.1 Overview
=============

`<gtk-tool-item>'s are widgets that can appear on a toolbar. To create a
toolbar item that contain something else than a button, use
`gtk-tool-item-new'. Use `gtk-container-add' to add a child widget to
the tool item.

   For toolbar items that contain buttons, see the `<gtk-tool-button>',
`<gtk-toggle-tool-button>' and `<gtk-radio-tool-button>' classes.

66.2 Usage
==========

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

     This class defines the following properties:

    `visible-horizontal'
          Whether the toolbar item is visible when the toolbar is in a
          horizontal orientation.

    `visible-vertical'
          Whether the toolbar item is visible when the toolbar is in a
          vertical orientation.

    `is-important'
          Whether the toolbar item is considered important. When TRUE,
          toolbar buttons show text in GTK_TOOLBAR_BOTH_HORIZ mode



 -- Signal on <gtk-tool-item>: create-menu-proxy => `<gboolean>'
     This signal is emitted when the toolbar needs information from
     TOOL-ITEM about whether the item should appear in the toolbar
     overflow menu. In response the tool item should either

        *  call `gtk-tool-item-set-proxy-menu-item' with a ``#f''
          pointer and return ``#t'' to indicate that the item should
          not appear in the overflow menu

        *  call `gtk-tool-item-set-proxy-menu-item' with a new menu
          item and return ``#t'', or

        *  return ``#f'' to indicate that the signal was not handled by
          the item. This means that the item will not appear in the
          overflow menu unless a later handler installs a menu item.

     The toolbar may cache the result of this signal. When the tool
     item changes how it will respond to this signal it must call
     `gtk-tool-item-rebuild-menu' to invalidate the cache and ensure
     that the toolbar rebuilds its overflow menu.


 -- Signal on <gtk-tool-item>: toolbar-reconfigured
     This signal is emitted when some property of the toolbar that the
     item is a child of changes. For custom subclasses of
     `<gtk-tool-item>', the default handler of this signal use the
     functions to find out what the toolbar should look like and change
     themselves accordingly.

        * `gtk-toolbar-get-orientation'

        * `gtk-toolbar-get-style'

        * `gtk-toolbar-get-icon-size'

        * `gtk-toolbar-get-relief-style'


 -- Signal on <gtk-tool-item>: set-tooltip (arg0 `<gtk-tooltips>')
          (arg1 `<gchararray>') (arg2 `<gchararray>') => `<gboolean>'
     This signal is emitted when the toolitem's tooltip changes.
     Application developers can use `gtk-tool-item-set-tooltip' to set
     the item's tooltip.


 -- Function: gtk-tool-item-new =>  (ret `<gtk-tool-item>')
     Creates a new `<gtk-tool-item>'

    RET
          the new `<gtk-tool-item>'


     Since 2.4


 -- Function: gtk-tool-item-set-homogeneous (self `<gtk-tool-item>')
          (homogeneous `bool')
 -- Method: set-homogeneous
     Sets whether TOOL-ITEM is to be allocated the same size as other
     homogeneous items. The effect is that all homogeneous items will
     have the same width as the widest of the items.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    HOMOGENEOUS
          whether TOOL-ITEM is the same size as other homogeneous items


     Since 2.4


 -- Function: gtk-tool-item-get-homogeneous (self `<gtk-tool-item>')
          =>  (ret `bool')
 -- Method: get-homogeneous
     Returns whether TOOL-ITEM is the same size as other homogeneous
     items. See `gtk-tool-item-set-homogeneous'.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    RET
          ``#t'' if the item is the same size as other homogeneous
          item.s


     Since 2.4


 -- Function: gtk-tool-item-set-expand (self `<gtk-tool-item>')
          (expand `bool')
 -- Method: set-expand
     Sets whether TOOL-ITEM is allocated extra space when there is more
     room on the toolbar then needed for the items. The effect is that
     the item gets bigger when the toolbar gets bigger and smaller when
     the toolbar gets smaller.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    EXPAND
          Whether TOOL-ITEM is allocated extra space


     Since 2.4


 -- Function: gtk-tool-item-get-expand (self `<gtk-tool-item>') => 
          (ret `bool')
 -- Method: get-expand
     Returns whether TOOL-ITEM is allocated extra space. See
     `gtk-tool-item-set-expand'.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    RET
          ``#t'' if TOOL-ITEM is allocated extra space.


     Since 2.4


 -- Function: gtk-tool-item-set-tooltip (self `<gtk-tool-item>')
          (tooltips `<gtk-tooltips>') (tip_text `mchars')
          (tip_private `mchars')
 -- Method: set-tooltip
     Sets the `<gtk-tooltips>' object to be used for TOOL-ITEM, the text
     to be displayed as tooltip on the item and the private text to be
     used. See `gtk-tooltips-set-tip'.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    TOOLTIPS
          The `<gtk-tooltips>' object to be used

    TIP-TEXT
          text to be used as tooltip text for TOOL-ITEM

    TIP-PRIVATE
          text to be used as private tooltip text


     Since 2.4


 -- Function: gtk-tool-item-set-use-drag-window
          (self `<gtk-tool-item>') (use_drag_window `bool')
 -- Method: set-use-drag-window
     Sets whether TOOLITEM has a drag window. When ``#t'' the toolitem
     can be used as a drag source through `gtk-drag-source-set'. When
     TOOLITEM has a drag window it will intercept all events, even
     those that would otherwise be sent to a child of TOOLITEM.

    TOOLITEM
          a `<gtk-tool-item>'

    USE-DRAG-WINDOW
          Whether TOOLITEM has a drag window.


     Since 2.4


 -- Function: gtk-tool-item-get-use-drag-window
          (self `<gtk-tool-item>') =>  (ret `bool')
 -- Method: get-use-drag-window
     Returns whether TOOLITEM has a drag window. See
     `gtk-tool-item-set-use-drag-window'.

    TOOLITEM
          a `<gtk-tool-item>'

    RET
          ``#t'' if TOOLITEM uses a drag window.


     Since 2.4


 -- Function: gtk-tool-item-set-visible-vertical
          (self `<gtk-tool-item>') (visible_vertical `bool')
 -- Method: set-visible-vertical
     Sets whether TOOLITEM is visible when the toolbar is docked
     vertically.  Some tool items, such as text entries, are too wide
     to be useful on a vertically docked toolbar. If VISIBLE-VERTICAL
     is ``#f''TOOLITEM will not appear on toolbars that are docked
     vertically.

    TOOLITEM
          a `<gtk-tool-item>'

    VISIBLE-VERTICAL
          whether TOOLITEM is visible when the toolbar is in vertical
          mode


     Since 2.4


 -- Function: gtk-tool-item-get-visible-vertical
          (self `<gtk-tool-item>') =>  (ret `bool')
 -- Method: get-visible-vertical
     Returns whether TOOLITEM is visible when the toolbar is docked
     vertically.  See `gtk-tool-item-set-visible-vertical'.

    TOOLITEM
          a `<gtk-tool-item>'

    RET
          Whether TOOLITEM is visible when the toolbar is docked
          vertically


     Since 2.4


 -- Function: gtk-tool-item-set-is-important (self `<gtk-tool-item>')
          (is_important `bool')
 -- Method: set-is-important
     Sets whether TOOL-ITEM should be considered important. The
     `<gtk-tool-button>' class uses this property to determine whether
     to show or hide its label when the toolbar style is
     `GTK_TOOLBAR_BOTH_HORIZ'. The result is that only tool buttons
     with the "is_important" property set have labels, an effect known
     as "priority text"

    TOOL-ITEM
          a `<gtk-tool-item>'

    IS-IMPORTANT
          whether the tool item should be considered important


     Since 2.4


 -- Function: gtk-tool-item-get-is-important (self `<gtk-tool-item>')
          =>  (ret `bool')
 -- Method: get-is-important
     Returns whether TOOL-ITEM is considered important. See
     `gtk-tool-item-set-is-important'

    TOOL-ITEM
          a `<gtk-tool-item>'

    RET
          ``#t'' if TOOL-ITEM is considered important.


     Since 2.4


 -- Function: gtk-tool-item-get-icon-size (self `<gtk-tool-item>') => 
          (ret `<gtk-icon-size>')
 -- Method: get-icon-size
     Returns the icon size used for TOOL-ITEM. Custom subclasses of
     `<gtk-tool-item>' should call this function to find out what size
     icons they should use.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    RET
          a `<gtk-icon-size>' indicating the icon size used for
          TOOL-ITEM


     Since 2.4


 -- Function: gtk-tool-item-get-orientation (self `<gtk-tool-item>')
          =>  (ret `<gtk-orientation>')
 -- Method: get-orientation
     Returns the orientation used for TOOL-ITEM. Custom subclasses of
     `<gtk-tool-item>' should call this function to find out what size
     icons they should use.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    RET
          a `<gtk-orientation>' indicating the orientation used for
          TOOL-ITEM


     Since 2.4


 -- Function: gtk-tool-item-get-toolbar-style (self `<gtk-tool-item>')
          =>  (ret `<gtk-toolbar-style>')
 -- Method: get-toolbar-style
     Returns the toolbar style used for TOOL-ITEM. Custom subclasses of
     `<gtk-tool-item>' should call this function in the handler of the
     GtkToolItem::toolbar_reconfigured signal to find out in what style
     the toolbar is displayed and change themselves accordingly

     Possibilities are:

        *  GTK_TOOLBAR_BOTH, meaning the tool item should show both an
          icon and a label, stacked vertically

        *  GTK_TOOLBAR_ICONS, meaning the toolbar shows only icons

        *  GTK_TOOLBAR_TEXT, meaning the tool item should only show text

        *  GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show
          both an icon and a label, arranged horizontally (however,
          note the `<gtk-tool-button::has-text-horizontally>' that
          makes tool buttons not show labels when the toolbar style is
          GTK_TOOLBAR_BOTH_HORIZ.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    RET
          A `<gtk-toolbar-style>' indicating the toolbar style used for
          TOOL-ITEM.


     Since 2.4


 -- Function: gtk-tool-item-get-relief-style (self `<gtk-tool-item>')
          =>  (ret `<gtk-relief-style>')
 -- Method: get-relief-style
     Returns the relief style of TOOL-ITEM. See
     `gtk-button-set-relief-style'. Custom subclasses of
     `<gtk-tool-item>' should call this function in the handler of the
     `<gtk-tool-item::toolbar-reconfigured>' signal to find out the
     relief style of buttons.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    RET
          a `<gtk-relief-style>' indicating the relief style used for
          TOOL-ITEM.


     Since 2.4


 -- Function: gtk-tool-item-get-proxy-menu-item
          (self `<gtk-tool-item>') (menu_item_id `mchars') => 
          (ret `<gtk-widget>')
 -- Method: get-proxy-menu-item
     If MENU-ITEM-ID matches the string passed to
     `gtk-tool-item-set-proxy-menu-item' return the corresponding
     `<gtk-menu-item>'.

     Custom subclasses of `<gtk-tool-item>' should use this function to
     update their menu item when the `<gtk-tool-item>' changes. That the
     MENU-ITEM-IDs must match ensures that a `<gtk-tool-item>' will not
     inadvertently change a menu item that they did not create.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    MENU-ITEM-ID
          a string used to identify the menu item

    RET
          The `<gtk-menu-item>' passed to
          `gtk-tool-item-set-proxy-menu-item', if the MENU-ITEM-IDs
          match.


     Since 2.4


 -- Function: gtk-tool-item-set-proxy-menu-item
          (self `<gtk-tool-item>') (menu_item_id `mchars')
          (menu_item `<gtk-widget>')
 -- Method: set-proxy-menu-item
     Sets the `<gtk-menu-item>' used in the toolbar overflow menu. The
     MENU-ITEM-ID is used to identify the caller of this function and
     should also be used with `gtk-tool-item-get-proxy-menu-item'.

    TOOL-ITEM
          a `<gtk-tool-item:>'

    MENU-ITEM-ID
          a string used to identify MENU-ITEM

    MENU-ITEM
          a `<gtk-menu-item>' to be used in the overflow menu


     Since 2.4


 -- Function: gtk-tool-item-rebuild-menu (self `<gtk-tool-item>')
 -- Method: rebuild-menu
     Calling this function signals to the toolbar that the overflow
     menu item for TOOL-ITEM has changed. If the overflow menu is
     visible when this function it called, the menu will be rebuilt.

     The function must be called when the tool item changes what it
     will do in response to the "create_menu_proxy" signal.

    TOOL-ITEM
          a `<gtk-tool-item>'


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkSeparatorToolItem,  Next: GtkToolButton,  Prev: GtkToolItem,  Up: Top

67 GtkSeparatorToolItem
***********************

A toolbar item that separates groups of other toolbar items

67.1 Overview
=============

A `<gtk-separator-item>' is a `<gtk-tool-item>' that separates groups
of other `<gtk-tool-items>'. Depending on the theme, a
`<gtk-separator-tool-item>' will often look like a vertical line on
horizontally docked toolbars.

   If the property "expand" is ``#t'' and the property "draw" is
``#f'', a `<gtk-separator-tool-item>' will act as a "spring" that
forces other items to the ends of the toolbar.

   Use `gtk-separator-tool-item-new' to create a new
`<gtk-separator-tool-item>'.

67.2 Usage
==========

 -- Class: <gtk-separator-tool-item>
     Derives from `<gtk-tool-item>'.

     This class defines the following properties:

    `draw'
          Whether the separator is drawn, or just blank



 -- Function: gtk-separator-tool-item-new =>  (ret `<gtk-tool-item>')
     Create a new `<gtk-separator-tool-item>'

    RET
          the new `<gtk-separator-tool-item>'


     Since 2.4


 -- Function: gtk-separator-tool-item-set-draw
          (self `<gtk-separator-tool-item>') (draw `bool')
 -- Method: set-draw
     When SEPARATOR-TOOL-ITEMS is drawn as a vertical line, or just
     blank.  Setting this ``#f'' along with `gtk-tool-item-set-expand'
     is useful to create an item that forces following items to the end
     of the toolbar.

    ITEM
          a `<gtk-separator-tool-item>'

    DRAW
          whether SEPARATOR-TOOL-ITEM is drawn as a vertical line


     Since 2.4


 -- Function: gtk-separator-tool-item-get-draw
          (self `<gtk-separator-tool-item>') =>  (ret `bool')
 -- Method: get-draw
     Returns whether SEPARATOR-TOOL-ITEM is drawn as a line, or just
     blank. See `gtk-separator-tool-item-set-draw'.

    ITEM
          a `<gtk-separator-tool-item>'

    RET
          ``#t'' if SEPARATOR-TOOL-ITEM is drawn as a line, or just
          blank.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkToolButton,  Next: GtkMenuToolButton,  Prev: GtkSeparatorToolItem,  Up: Top

68 GtkToolButton
****************

A GtkToolItem subclass that displays buttons

68.1 Overview
=============

`<gtk-tool-button>'s are `<gtk-tool-items>' containing buttons.

   Use `gtk-tool-button-new' to create a new `<gtk-tool-button>'. Use
`gtk-tool-button-new-with-stock' to create a `<gtk-tool-button>'
containing a stock item.

   The label of a `<gtk-tool-button>' is determined by the properties
"label_widget", "label", and "stock_id". If "label_widget" is
non-``#f'', then that widget is used as the label. Otherwise, if
"label" is non-``#f'', that string is used as the label. Otherwise, if
"stock_id" is non-``#f'', the label is determined by the stock item.
Otherwise, the button does not have a label.

   The icon of a `<gtk-tool-button>' is determined by the properties
"icon_widget" and "stock_id". If "icon_widget" is non-``#f'', then that
widget is used as the icon. Otherwise, if "stock_id" is non-``#f'', the
icon is determined by the stock item. Otherwise, the button does not
have a label.

68.2 Usage
==========

 -- Class: <gtk-tool-button>
     Derives from `<gtk-tool-item>'.

     This class defines the following properties:

    `label'
          Text to show in the item.

    `use-underline'
          If set, an underline in the label property indicates that the
          next character should be used for the mnemonic accelerator
          key in the overflow menu

    `label-widget'
          Widget to use as the item label

    `stock-id'
          The stock icon displayed on the item

    `icon-name'
          The name of the themed icon displayed on the item

    `icon-widget'
          Icon widget to display in the item



 -- Signal on <gtk-tool-button>: clicked
     This signal is emitted when the tool button is clicked with the
     mouse or activated with the keyboard.


 -- Function: gtk-tool-button-new (icon_widget `<gtk-widget>')
          (label `mchars') =>  (ret `<gtk-tool-item>')
     Creates a new `GtkToolButton' using ICON-WIDGET as icon and LABEL
     as label.

    ICON-WIDGET
          a widget that will be used as icon widget, or ``#f''

    LABEL
          a string that will be used as label, or ``#f''

    RET
          A new `<gtk-tool-button>'


     Since 2.4


 -- Function: gtk-tool-button-new-from-stock (stock_id `mchars') => 
          (ret `<gtk-tool-item>')
     Creates a new `<gtk-tool-button>' containing the image and text
     from a stock item. Some stock ids have preprocessor macros like
     `<gtk-stock-ok>' and `<gtk-stock-apply>'.

     It is an error if STOCK-ID is not a name of a stock item.

    STOCK-ID
          the name of the stock item

    RET
          A new `<gtk-tool-button>'


     Since 2.4


 -- Function: gtk-tool-button-set-label (self `<gtk-tool-button>')
          (label `mchars')
 -- Method: set-label
     Sets LABEL as the label used for the tool button. The "label"
     property only has an effect if not overridden by a non-``#f''
     "label_widget" property. If both the "label_widget" and "label"
     properties are ``#f'', the label is determined by the "stock_id"
     property. If the "stock_id" property is also ``#f'', BUTTON will
     not have a label.

    BUTTON
          a `<gtk-tool-button>'

    LABEL
          a string that will be used as label, or ``#f''.


     Since 2.4


 -- Function: gtk-tool-button-get-label (self `<gtk-tool-button>') => 
          (ret `mchars')
 -- Method: get-label
     Returns the label used by the tool button, or ``#f'' if the tool
     button doesn't have a label. or uses a the label from a stock
     item. The returned string is owned by GTK+, and must not be
     modified or freed.

    BUTTON
          a `<gtk-tool-button>'

    RET
          The label, or ``#f''


     Since 2.4


 -- Function: gtk-tool-button-set-use-underline
          (self `<gtk-tool-button>') (use_underline `bool')
 -- Method: set-use-underline
     If set, an underline in the label property indicates that the next
     character should be used for the mnemonic accelerator key in the
     overflow menu. For example, if the label property is "_Open" and
     USE-UNDERLINE is ``#t'', the label on the tool button will be
     "Open" and the item on the overflow menu will have an underlined
     'O'.

     Labels shown on tool buttons never have mnemonics on them; this
     property only affects the menu item on the overflow menu.

    BUTTON
          a `<gtk-tool-button>'

    USE-UNDERLINE
          whether the button label has the form "_Open"


     Since 2.4


 -- Function: gtk-tool-button-get-use-underline
          (self `<gtk-tool-button>') =>  (ret `bool')
 -- Method: get-use-underline
     Returns whether underscores in the label property are used as
     mnemonics on menu items on the overflow menu. See
     `gtk-tool-button-set-use-underline'.

    BUTTON
          a `<gtk-tool-button>'

    RET
          ``#t'' if underscores in the label property are used as
          mnemonics on menu items on the overflow menu.


     Since 2.4


 -- Function: gtk-tool-button-set-stock-id (self `<gtk-tool-button>')
          (stock_id `mchars')
 -- Method: set-stock-id
     Sets the name of the stock item. See
     `gtk-tool-button-new-from-stock'. The stock_id property only has
     an effect if not overridden by non-``#f'' "label" and
     "icon_widget" properties.

    BUTTON
          a `<gtk-tool-button>'

    STOCK-ID
          a name of a stock item, or ``#f''


     Since 2.4


 -- Function: gtk-tool-button-get-stock-id (self `<gtk-tool-button>')
          =>  (ret `mchars')
 -- Method: get-stock-id
     Returns the name of the stock item. See
     `gtk-tool-button-set-stock-id'. The returned string is owned by
     GTK+ and must not be freed or modifed.

    BUTTON
          a `<gtk-tool-button>'

    RET
          the name of the stock item for BUTTON.


     Since 2.4


 -- Function: gtk-tool-button-set-icon-name (self `<gtk-tool-button>')
          (icon_name `mchars')
 -- Method: set-icon-name
     Sets the icon for the tool button from a named themed icon. See
     the docs for `<gtk-icon-theme>' for more details. The "icon_name"
     property only has an effect if not overridden by non-``#f''
     "label", "icon_widget" and "stock_id" properties.

    BUTTON
          a `<gtk-tool-button>'

    ICON-NAME
          the name of the themed icon


     Since 2.8


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

    BUTTON
          a `<gtk-tool-button>'

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


     Since 2.8


 -- Function: gtk-tool-button-set-icon-widget
          (self `<gtk-tool-button>') (icon_widget `<gtk-widget>')
 -- Method: set-icon-widget
     Sets ICON as the widget used as icon on BUTTON. If ICON-WIDGET is
     ``#f'' the icon is determined by the "stock_id" property. If the
     "stock_id" property is also ``#f'', BUTTON will not have an icon.

    BUTTON
          a `<gtk-tool-button>'

    ICON-WIDGET
          the widget used as icon, or ``#f''


     Since 2.4


 -- Function: gtk-tool-button-get-icon-widget
          (self `<gtk-tool-button>') =>  (ret `<gtk-widget>')
 -- Method: get-icon-widget
     Return the widget used as icon widget on BUTTON. See
     `gtk-tool-button-set-icon-widget'.

    BUTTON
          a `<gtk-tool-button>'

    RET
          The widget used as icon on BUTTON, or ``#f''.


     Since 2.4


 -- Function: gtk-tool-button-set-label-widget
          (self `<gtk-tool-button>') (label_widget `<gtk-widget>')
 -- Method: set-label-widget
     Sets LABEL-WIDGET as the widget that will be used as the label for
     BUTTON. If LABEL-WIDGET is ``#f'' the "label" property is used as
     label. If "label" is also ``#f'', the label in the stock item
     determined by the "stock_id" property is used as label. If
     "stock_id" is also ``#f'', BUTTON does not have a label.

    BUTTON
          a `<gtk-tool-button>'

    LABEL-WIDGET
          the widget used as label, or ``#f''


     Since 2.4


 -- Function: gtk-tool-button-get-label-widget
          (self `<gtk-tool-button>') =>  (ret `<gtk-widget>')
 -- Method: get-label-widget
     Returns the widget used as label on BUTTON. See
     `gtk-tool-button-set-label-widget'.

    BUTTON
          a `<gtk-tool-button>'

    RET
          The widget used as label on BUTTON, or ``#f''.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkMenuToolButton,  Next: GtkToggleToolButton,  Prev: GtkToolButton,  Up: Top

69 GtkMenuToolButton
********************

A GtkToolItem containing a button with an additional dropdown menu

69.1 Overview
=============

A `<gtk-menu-tool-button>' is a `<gtk-tool-item>' that contains a
button and a small additional button with an arrow. When clicked, the
arrow button pops up a dropdown menu.

   Use `gtk-menu-tool-button-new' to create a new
`<gtk-menu-tool-button>'. Use `gtk-menu-tool-button-new-from-stock' to
create a new `<gtk-menu-tool-button>' containing a stock item.

69.2 Usage
==========

 -- Class: <gtk-menu-tool-button>
     Derives from `<gtk-tool-button>'.

     This class defines the following properties:

    `menu'
          The dropdown menu



 -- Signal on <gtk-menu-tool-button>: show-menu

 -- Function: gtk-menu-tool-button-new (icon_widget `<gtk-widget>')
          (label `mchars') =>  (ret `<gtk-tool-item>')
     Creates a new `<gtk-menu-tool-button>' using ICON-WIDGET as icon
     and LABEL as label.

    ICON-WIDGET
          a widget that will be used as icon widget, or ``#f''

    LABEL
          a string that will be used as label, or ``#f''

    RET
          the new `<gtk-menu-tool-button>'


     Since 2.6


 -- Function: gtk-menu-tool-button-new-from-stock (stock_id `mchars')
          =>  (ret `<gtk-tool-item>')
     Creates a new `<gtk-menu-tool-button>'. The new
     `<gtk-menu-tool-button>' will contain an icon and label from the
     stock item indicated by STOCK-ID.

    STOCK-ID
          the name of a stock item

    RET
          the new `<gtk-menu-tool-button>'


     Since 2.6


 -- Function: gtk-menu-tool-button-set-menu
          (self `<gtk-menu-tool-button>') (menu `<gtk-widget>')
 -- Method: set-menu
     Sets the `<gtk-menu>' that is popped up when the user clicks on
     the arrow.  If MENU is NULL, the arrow button becomes insensitive.

    BUTTON
          a `<gtk-menu-tool-button>'

    MENU
          the `<gtk-menu>' associated with `<gtk-menu-tool-button>'


     Since 2.6


 -- Function: gtk-menu-tool-button-get-menu
          (self `<gtk-menu-tool-button>') =>  (ret `<gtk-widget>')
 -- Method: get-menu
     Gets the `<gtk-menu>' associated with `<gtk-menu-tool-button>'.

    BUTTON
          a `<gtk-menu-tool-button>'

    RET
          the `<gtk-menu>' associated with `<gtk-menu-tool-button>'


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkToggleToolButton,  Next: GtkRadioToolButton,  Prev: GtkMenuToolButton,  Up: Top

70 GtkToggleToolButton
**********************

A GtkToolItem containing a toggle button

70.1 Overview
=============

A `<gtk-toggle-tool-button>' is a `<gtk-tool-item>' that contains a
toggle button.

   Use `gtk-toggle-tool-button-new' to create a new
`<gtk-toggle-tool-button>'. Use `gtk-toggle-tool-button-new-from-stock'
to create a new `<gtk-toggle-tool-button>' containing a stock item.

70.2 Usage
==========

 -- Class: <gtk-toggle-tool-button>
     Derives from `<gtk-tool-button>'.

     This class defines the following properties:

    `active'
          If the toggle button should be pressed in or not



 -- Signal on <gtk-toggle-tool-button>: toggled
     Emitted whenever the toggle tool button changes state.


 -- Function: gtk-toggle-tool-button-new =>  (ret `<gtk-tool-item>')
     Returns a new `<gtk-toggle-tool-button>'

    RET
          a newly created `<gtk-toggle-tool-button>'


     Since 2.4


 -- Function: gtk-toggle-tool-button-set-active
          (self `<gtk-toggle-tool-button>') (is_active `bool')
 -- Method: set-active
     Sets the status of the toggle tool 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.

    BUTTON
          a `<gtk-toggle-tool-button>'

    IS-ACTIVE
          whether BUTTON should be active


     Since 2.4


 -- Function: gtk-toggle-tool-button-get-active
          (self `<gtk-toggle-tool-button>') =>  (ret `bool')
 -- Method: get-active
     Queries a `<gtk-toggle-tool-button>' and returns its current
     state. Returns ``#t'' if the toggle button is pressed in and
     ``#f'' if it is raised.

    BUTTON
          a `<gtk-toggle-tool-button>'

    RET
          ``#t'' if the toggle tool button is pressed in, ``#f'' if not


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkRadioToolButton,  Next: GtkUIManager,  Prev: GtkToggleToolButton,  Up: Top

71 GtkRadioToolButton
*********************

A toolbar item that contains a radio button

71.1 Overview
=============

A `<gtk-radio-tool-button>' is a `<gtk-tool-item>' that contains a
radio button, that is, a button that is part of a group of toggle
buttons where only one button can be active at a time.

   Use `gtk-radio-tool-button-new' to create a new
`<gtk-radio-tool-button>'. use `gtk-radio-tool-button-new-from-widget'
to create a new `<gtk-radio-tool-button>' that is part of the same
group as an existing `<gtk-radio-tool-button>'. Use
`gtk-radio-tool-button-new-from-stock' or
`gtk-radio-tool-button-new-from-widget-with-stock' to create a new
`<gtk-radio-tool-button>' containing a stock item.

71.2 Usage
==========

 -- Class: <gtk-radio-tool-button>
     Derives from `<gtk-toggle-tool-button>'.

     This class defines the following properties:

    `group'
          The radio tool button whose group this button belongs to.



 -- Function: gtk-radio-tool-button-new (group `<gtk-radio-group*>')
          =>  (ret `<gtk-tool-item>')
     Creates a new `<gtk-radio-tool-button>', adding it to GROUP.

    GROUP
          An existing radio button group, or ``#f'' if you are creating
          a new group

    RET
          The new `<gtk-radio-tool-button>'


     Since 2.4


 -- Function: gtk-radio-tool-button-get-group
          (self `<gtk-radio-tool-button>') => 
          (ret `<gtk-radio-group*>')
 -- Method: get-group
     Returns the radio button group BUTTON belongs to.

    BUTTON
          a `<gtk-radio-tool-button>'

    RET
          The group BUTTON belongs to.


     Since 2.4


 -- Function: gtk-radio-tool-button-set-group
          (self `<gtk-radio-tool-button>') (group `<gtk-radio-group*>')
 -- Method: set-group
     Adds BUTTON to GROUP, removing it from the group it belonged to
     before.

    BUTTON
          a `<gtk-radio-tool-button>'

    GROUP
          an existing radio button group


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkUIManager,  Next: GtkActionGroup,  Prev: GtkRadioToolButton,  Up: Top

72 GtkUIManager
***************

Constructing menus and toolbars from an XML description

72.1 Overview
=============

A `<gtk-ui-manager>' constructs a user interface (menus and toolbars)
from one or more UI definitions, which reference actions from one or
more action groups.

72.2 UI Definitions
===================

The UI definitions are specified in an XML format which can be roughly
described by the following DTD. There are some additional restrictions
beyond those specified in the DTD, e.g. every toolitem must have a
toolbar in its anchestry and every menuitem must have a menubar or
popup in its anchestry. Since a `<g-markup>' parser is used to parse
the UI description, it must not only be valid XML, but valid
`<g-markup>'.


     <!ELEMENT ui          (menubar|toolbar|popup|accelerator)* >
     <!ELEMENT menubar     (menuitem|separator|placeholder|menu)* >
     <!ELEMENT menu        (menuitem|separator|placeholder|menu)* >
     <!ELEMENT popup       (menuitem|separator|placeholder|menu)* >
     <!ELEMENT toolbar     (toolitem|separator|placeholder)* >
     <!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
     <!ELEMENT menuitem     EMPTY >
     <!ELEMENT toolitem     (menu?) >
     <!ELEMENT separator    EMPTY >
     <!ELEMENT accelerator  EMPTY >
     <!ATTLIST menubar      name                  &#x0023;IMPLIED
                            action                &#x0023;IMPLIED >
     <!ATTLIST toolbar      name                  &#x0023;IMPLIED
                            action                &#x0023;IMPLIED >
     <!ATTLIST popup        name                  &#x0023;IMPLIED
                            action                &#x0023;IMPLIED >
     <!ATTLIST placeholder  name                  &#x0023;IMPLIED
                            action                &#x0023;IMPLIED >
     <!ATTLIST separator    name                  &#x0023;IMPLIED
                            action                &#x0023;IMPLIED
                            expand   (true|false) &#x0023;IMPLIED >
     <!ATTLIST menu         name                  &#x0023;IMPLIED
                            action                &#x0023;REQUIRED
                            position (top|bot)    &#x0023;IMPLIED >
     <!ATTLIST menuitem     name                  &#x0023;IMPLIED
                            action                &#x0023;REQUIRED
                            position (top|bot)    &#x0023;IMPLIED >
     <!ATTLIST toolitem     name                  &#x0023;IMPLIED
                            action                &#x0023;REQUIRED
                            position (top|bot)    &#x0023;IMPLIED >
     <!ATTLIST accelerator  name                  &#x0023;IMPLIED
                            action                &#x0023;REQUIRED >

   If a name is not specified, it defaults to the action. If an action
is not specified either, the element name is used. The name and action
attributes must not contain '/' characters after parsing (since that
would mess up path lookup) and must be usable as XML attributes when
enclosed in doublequotes, thus they must not '"' characters or
references to the &quot; entity.


     <ui>
       <menubar>
         <menu name="FileMenu" action="FileMenuAction">
           <menuitem name="New" action="New2Action" />
           <placeholder name="FileMenuAdditions" />
         </menu>
         <menu name="JustifyMenu" action="JustifyMenuAction">
           <menuitem name="Left" action="justify-left"/>
           <menuitem name="Centre" action="justify-center"/>
           <menuitem name="Right" action="justify-right"/>
           <menuitem name="Fill" action="justify-fill"/>
         </menu>
       </menubar>
       <toolbar action="toolbar1">
         <placeholder name="JustifyToolItems">
           <separator/>
           <toolitem name="Left" action="justify-left"/>
           <toolitem name="Centre" action="justify-center"/>
           <toolitem name="Right" action="justify-right"/>
           <toolitem name="Fill" action="justify-fill"/>
           <separator/>
         </placeholder>
       </toolbar>
     </ui>

   The constructed widget hierarchy is very similar to the element tree
of the XML, with the exception that placeholders are merged into their
parents. The correspondence of XML elements to widgets should be almost
obvious:

TOOLBAR

POPUP

MENU

MENUITEM

TOOLITEM

SEPARATOR

ACCELERATOR

   a `<gtk-menu-bar>'

   a `<gtk-toolbar>'

   a toplevel `<gtk-menu>'

   a `<gtk-menu>' attached to a menuitem

   a `<gtk-menu-item>' subclass, the exact type depends on the action

   a `<gtk-tool-item>' subclass, the exact type depends on the action.
Note that toolitem elements may contain a menu element, but only if
their associated action specifies a `<gtk-menu-tool-button>' as proxy.

   a `<gtk-separator-menu-item>' or `<gtk-separator-tool-item>'

   a keyboard accelerator

   The "position" attribute determines where a constructed widget is
positioned wrt. to its siblings in the partially constructed tree. If
it is "top", the widget is prepended, otherwise it is appended.

72.3 UI Merging
===============

The most remarkable feature of `<gtk-ui-manager>' is that it can
overlay a set of menuitems and toolitems over another one, and demerge
them later.

   Merging is done based on the names of the XML elements. Each element
is identified by a path which consists of the names of its anchestors,
separated by slashes. For example, the menuitem named "Left" in the
example above has the path `/ui/menubar/JustifyMenu/Left' and the
toolitem with the same name has path
`/ui/toolbar1/JustifyToolItems/Left'.

72.4 Accelerators
=================

Every action has an accelerator path. Accelerators are installed
together with menuitem proxies, but they can also be explicitly added
with <accelerator> elements in the UI definition. This makes it
possible to have accelerators for actions even if they have no visible
proxies.

72.5 Smart Separators
=====================

The separators created by `<gtk-ui-manager>' are "smart", i.e. they do
not show up in the UI unless they end up between two visible menu or
tool items.  Separators which are located at the very beginning or end
of the menu or toolbar containing them, or multiple separators next to
each other, are hidden. This is a useful feature, since the merging of
UI elements from multiple sources can make it hard or impossible to
determine in advance whether a separator will end up in such an
unfortunate position.

   For separators in toolbars, you can set `expand="true"' to turn them
from a small, visible separator to an expanding, invisible one.
Toolitems following an expanding separator are effectively
right-aligned.

72.6 Empty Menus
================

Submenus pose similar problems to separators inconnection with merging.
It is impossible to know in advance whether they will end up empty
after merging.  `<gtk-ui-manager>' offers two ways to treat empty
submenus: The behaviour is chosen based on the "hide_if_empty" property
of the action to which the submenu is associated.

   make them disappear by hiding the menu item they're attached to

   add an insensitive "Empty" item

72.7 Usage
==========

 -- Class: <gtk-ui-manager>
     Derives from `<gtk-buildable>', `<gobject>'.

     This class defines the following properties:

    `add-tearoffs'
          Whether tearoff menu items should be added to menus

    `ui'
          An XML string describing the merged UI



 -- Signal on <gtk-ui-manager>: connect-proxy (arg0 `<gtk-action>')
          (arg1 `<gtk-widget>')
     The connect_proxy signal is emitted after connecting a proxy to an
     action in the group.

     This is intended for simple customizations for which a custom
     action class would be too clumsy, e.g. showing tooltips for
     menuitems in the statusbar.

     Since 2.4


 -- Signal on <gtk-ui-manager>: disconnect-proxy (arg0 `<gtk-action>')
          (arg1 `<gtk-widget>')
     The disconnect_proxy signal is emitted after disconnecting a proxy
     from an action in the group.

     Since 2.4


 -- Signal on <gtk-ui-manager>: pre-activate (arg0 `<gtk-action>')
     The pre_activate signal is emitted just before the ACTION is
     activated.

     This is intended for applications to get notification just before
     any action is activated.

     Since 2.4


 -- Signal on <gtk-ui-manager>: post-activate (arg0 `<gtk-action>')
     The post_activate signal is emitted just after the ACTION is
     activated.

     This is intended for applications to get notification just after
     any action is activated.

     Since 2.4


 -- Signal on <gtk-ui-manager>: add-widget (arg0 `<gtk-widget>')
     The add_widget signal is emitted for each generated menubar and
     toolbar. It is not emitted for generated popup menus, which can be
     obtained by `gtk-ui-manager-get-widget'.

     Since 2.4


 -- Signal on <gtk-ui-manager>: actions-changed
     The "actions-changed" signal is emitted whenever the set of
     actions changes.

     Since 2.4


 -- Function: gtk-ui-manager-new =>  (ret `<gtk-ui-manager>')
     Creates a new ui manager object.

    RET
          a new ui manager object.


     Since 2.4


 -- Function: gtk-ui-manager-set-add-tearoffs (self `<gtk-ui-manager>')
          (add_tearoffs `bool')
 -- Method: set-add-tearoffs
     Sets the "add_tearoffs" property, which controls whether menus
     generated by this `<gtk-ui-manager>' will have tearoff menu items.

     Note that this only affects regular menus. Generated popup menus
     never have tearoff menu items.

    SELF
          a `<gtk-ui-manager>'

    ADD-TEAROFFS
          whether tearoff menu items are added


     Since 2.4


 -- Function: gtk-ui-manager-get-add-tearoffs (self `<gtk-ui-manager>')
          =>  (ret `bool')
 -- Method: get-add-tearoffs
     Returns whether menus generated by this `<gtk-ui-manager>' will
     have tearoff menu items.

    SELF
          a `<gtk-ui-manager>'

    RET
          whether tearoff menu items are added


     Since 2.4


 -- Function: gtk-ui-manager-insert-action-group
          (self `<gtk-ui-manager>') (action_group `<gtk-action-group>')
          (pos `int')
 -- Method: insert-action-group
     Inserts an action group into the list of action groups associated
     with SELF. Actions in earlier groups hide actions with the same
     name in later groups.

    SELF
          a `<gtk-ui-manager>' object

    ACTION-GROUP
          the action group to be inserted

    POS
          the position at which the group will be inserted.


     Since 2.4


 -- Function: gtk-ui-manager-remove-action-group
          (self `<gtk-ui-manager>') (action_group `<gtk-action-group>')
 -- Method: remove-action-group
     Removes an action group from the list of action groups associated
     with SELF.

    SELF
          a `<gtk-ui-manager>' object

    ACTION-GROUP
          the action group to be removed


     Since 2.4


 -- Function: gtk-ui-manager-get-action-groups
          (self `<gtk-ui-manager>') =>  (ret `glist-of')
 -- Method: get-action-groups
     Returns the list of action groups associated with SELF.

    SELF
          a `<gtk-ui-manager>' object

    RET
          a `<g-list>' of action groups. The list is owned by GTK+ and
          should not be modified.


     Since 2.4


 -- Function: gtk-ui-manager-get-accel-group (self `<gtk-ui-manager>')
          =>  (ret `<gtk-accel-group>')
 -- Method: get-accel-group
     Returns the `<gtk-accel-group>' associated with SELF.

    SELF
          a `<gtk-ui-manager>' object

    RET
          the `<gtk-accel-group>'.


     Since 2.4


 -- Function: gtk-ui-manager-get-widget (self `<gtk-ui-manager>')
          (path `mchars') =>  (ret `<gtk-widget>')
 -- Method: get-widget
     Looks up a widget by following a path. The path consists of the
     names specified in the XML description of the UI. separated by
     '/'. Elements which don't have a name or action attribute in the
     XML (e.g. <popup>) can be addressed by their XML element name
     (e.g. "popup"). The root element ("/ui") can be omitted in the
     path.

     Note that the widget found by following a path that ends in a
     <menu> element is the menuitem to which the menu is attached, not
     the menu itself.

     Also note that the widgets constructed by a ui manager are not
     tied to the lifecycle of the ui manager. If you add the widgets
     returned by this function to some container or explicitly ref
     them, they will survive the destruction of the ui manager.

    SELF
          a `<gtk-ui-manager>'

    PATH
          a path

    RET
          the widget found by following the path, or ``#f'' if no
          widget was found.


     Since 2.4


 -- Function: gtk-ui-manager-get-toplevels (self `<gtk-ui-manager>')
          (types `<gtk-ui-manager-item-type>') =>  (ret `gslist-of')
 -- Method: get-toplevels
     Obtains a list of all toplevel widgets of the requested types.

    SELF
          a `<gtk-ui-manager>'

    TYPES
          specifies the types of toplevel widgets to include. Allowed
          types are `<gtk-ui-manager-menubar>',
          `<gtk-ui-manager-toolbar>' and `<gtk-ui-manager-popup>'.

    RET
          a newly-allocated of all toplevel widgets of the requested
          types.


     Since 2.4


 -- Function: gtk-ui-manager-get-action (self `<gtk-ui-manager>')
          (path `mchars') =>  (ret `<gtk-action>')
 -- Method: get-action
     Looks up an action by following a path. See
     `gtk-ui-manager-get-widget' for more information about paths.

    SELF
          a `<gtk-ui-manager>'

    PATH
          a path

    RET
          the action whose proxy widget is found by following the path,
          or ``#f'' if no widget was found.


     Since 2.4


 -- Function: gtk-ui-manager-add-ui-from-file (self `<gtk-ui-manager>')
          (filename `mchars') =>  (ret `unsigned-int')
 -- Method: add-ui-from-file
     Parses a file containing a UI definition and merges it with the
     current contents of SELF.

    SELF
          a `<gtk-ui-manager>' object

    FILENAME
          the name of the file to parse

    ERROR
          return location for an error

    RET
          The merge id for the merged UI. The merge id can be used to
          unmerge the UI with `gtk-ui-manager-remove-ui'. If an error
          occurred, the return value is 0.


     Since 2.4


 -- Function: gtk-ui-manager-new-merge-id (self `<gtk-ui-manager>') => 
          (ret `unsigned-int')
 -- Method: new-merge-id
     Returns an unused merge id, suitable for use with
     `gtk-ui-manager-add-ui'.

    SELF
          a `<gtk-ui-manager>'

    RET
          an unused merge id.


     Since 2.4


 -- Function: gtk-ui-manager-add-ui (self `<gtk-ui-manager>')
          (merge_id `unsigned-int') (path `mchars') (name `mchars')
          (action `mchars') (type `<gtk-ui-manager-item-type>')
          (top `bool')
 -- Method: add-ui
     Adds a UI element to the current contents of SELF.

     If TYPE is `GTK_UI_MANAGER_AUTO', GTK+ inserts a menuitem, toolitem
     or separator if such an element can be inserted at the place
     determined by PATH. Otherwise TYPE must indicate an element that
     can be inserted at the place determined by PATH.

     If PATH points to a menuitem or toolitem, the new element will be
     inserted before or after this item, depending on TOP.

    SELF
          a `<gtk-ui-manager>'

    MERGE-ID
          the merge id for the merged UI, see
          `gtk-ui-manager-new-merge-id'

    PATH
          a path

    NAME
          the name for the added UI element

    ACTION
          the name of the action to be proxied, or ``#f'' to add a
          separator

    TYPE
          the type of UI element to add.

    TOP
          if ``#t'', the UI element is added before its siblings,
          otherwise it is added after its siblings.


     Since 2.4


 -- Function: gtk-ui-manager-remove-ui (self `<gtk-ui-manager>')
          (merge_id `unsigned-int')
 -- Method: remove-ui
     Unmerges the part of SELFs content identified by MERGE-ID.

    SELF
          a `<gtk-ui-manager>' object

    MERGE-ID
          a merge id as returned by `gtk-ui-manager-add-ui-from-string'


     Since 2.4


 -- Function: gtk-ui-manager-get-ui (self `<gtk-ui-manager>') => 
          (ret `mchars')
 -- Method: get-ui
     Creates a UI definition of the merged UI.

    SELF
          a `<gtk-ui-manager>'

    RET
          A newly allocated string containing an XML representation of
          the merged UI.


     Since 2.4


 -- Function: gtk-ui-manager-ensure-update (self `<gtk-ui-manager>')
 -- Method: ensure-update
     Makes sure that all pending updates to the UI have been completed.

     This may occasionally be necessary, since `<gtk-ui-manager>'
     updates the UI in an idle function. A typical example where this
     function is useful is to enforce that the menubar and toolbar have
     been added to the main window before showing it:


          gtk_container_add (GTK_CONTAINER (window), vbox);
          g_signal_connect (merge, "add_widget",
                            G_CALLBACK (add_widget), vbox);
          gtk_ui_manager_add_ui_from_file (merge, "my-menus");
          gtk_ui_manager_add_ui_from_file (merge, "my-toolbars");
          gtk_ui_manager_ensure_update (merge);
          gtk_widget_show (window);

    SELF
          a `<gtk-ui-manager>'


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkActionGroup,  Next: GtkAction,  Prev: GtkUIManager,  Up: Top

73 GtkActionGroup
*****************

A group of actions

73.1 Overview
=============

Actions are organised into groups. An action group is essentially a map
from names to `<gtk-action>' objects.

   All actions that would make sense to use in a particular context
should be in a single group. Multiple action groups may be used for a
particular user interface. In fact, it is expected that most nontrivial
applications will make use of multiple groups. For example, in an
application that can edit multiple documents, one group holding global
actions (e.g. quit, about, new), and one group per document holding
actions that act on that document (eg. save, cut/copy/paste, etc). Each
window's menus would be constructed from a combination of two action
groups.

   Accelerators are handled by the GTK+ accelerator map. All actions
are assigned an accelerator path (which normally has the form
`<Actions>//') and a shortcut is associated with this accelerator path.
All menuitems and toolitems take on this accelerator path. The GTK+
accelerator map code makes sure that the correct shortcut is displayed
next to the menu item.

73.2 Usage
==========

 -- Class: <gtk-action-group>
     Derives from `<gtk-buildable>', `<gobject>'.

     This class defines the following properties:

    `name'
          A name for the action group.

    `sensitive'
          Whether the action group is enabled.

    `visible'
          Whether the action group is visible.



 -- Signal on <gtk-action-group>: connect-proxy (arg0 `<gtk-action>')
          (arg1 `<gtk-widget>')
     The connect_proxy signal is emitted after connecting a proxy to an
     action in the group. Note that the proxy may have been connected
     to a different action before.

     This is intended for simple customizations for which a custom
     action class would be too clumsy, e.g. showing tooltips for
     menuitems in the statusbar.

     `<gtk-ui-manager>' proxies the signal and provides global
     notification just before any action is connected to a proxy, which
     is probably more convenient to use.

     Since 2.4


 -- Signal on <gtk-action-group>: disconnect-proxy
          (arg0 `<gtk-action>') (arg1 `<gtk-widget>')
     The disconnect_proxy signal is emitted after disconnecting a proxy
     from an action in the group.

     `<gtk-ui-manager>' proxies the signal and provides global
     notification just before any action is connected to a proxy, which
     is probably more convenient to use.

     Since 2.4


 -- Signal on <gtk-action-group>: pre-activate (arg0 `<gtk-action>')
     The pre_activate signal is emitted just before the ACTION in the
     ACTION-GROUP is activated

     This is intended for `<gtk-ui-manager>' to proxy the signal and
     provide global notification just before any action is activated.

     Since 2.4


 -- Signal on <gtk-action-group>: post-activate (arg0 `<gtk-action>')
     The post_activate signal is emitted just after the ACTION in the
     ACTION-GROUP is activated

     This is intended for `<gtk-ui-manager>' to proxy the signal and
     provide global notification just after any action is activated.

     Since 2.4


 -- Function: gtk-action-group-new (name `mchars') => 
          (ret `<gtk-action-group>')
     Creates a new `<gtk-action-group>' object. The name of the action
     group is used when associating keybindings with the actions.

    NAME
          the name of the action group.

    RET
          the new `<gtk-action-group>'


     Since 2.4


 -- Function: gtk-action-group-get-name (self `<gtk-action-group>') => 
          (ret `mchars')
 -- Method: get-name
     Gets the name of the action group.

    ACTION-GROUP
          the action group

    RET
          the name of the action group.


     Since 2.4


 -- Function: gtk-action-group-get-sensitive
          (self `<gtk-action-group>') =>  (ret `bool')
 -- Method: get-sensitive
     Returns ``#t'' if the group is sensitive. The constituent actions
     can only be logically sensitive (see `gtk-action-is-sensitive') if
     they are sensitive (see `gtk-action-get-sensitive') and their
     group is sensitive.

    ACTION-GROUP
          the action group

    RET
          ``#t'' if the group is sensitive.


     Since 2.4


 -- Function: gtk-action-group-set-sensitive
          (self `<gtk-action-group>') (sensitive `bool')
 -- Method: set-sensitive
     Changes the sensitivity of ACTION-GROUP

    ACTION-GROUP
          the action group

    SENSITIVE
          new sensitivity


     Since 2.4


 -- Function: gtk-action-group-get-visible (self `<gtk-action-group>')
          =>  (ret `bool')
 -- Method: get-visible
     Returns ``#t'' if the group is visible. The constituent actions can
     only be logically visible (see `gtk-action-is-visible') if they
     are visible (see `gtk-action-get-visible') and their group is
     visible.

    ACTION-GROUP
          the action group

    RET
          ``#t'' if the group is visible.


     Since 2.4


 -- Function: gtk-action-group-set-visible (self `<gtk-action-group>')
          (visible `bool')
 -- Method: set-visible
     Changes the visible of ACTION-GROUP.

    ACTION-GROUP
          the action group

    VISIBLE
          new visiblity


     Since 2.4


 -- Function: gtk-action-group-get-action (self `<gtk-action-group>')
          (action_name `mchars') =>  (ret `<gtk-action>')
 -- Method: get-action
     Looks up an action in the action group by name.

    ACTION-GROUP
          the action group

    ACTION-NAME
          the name of the action

    RET
          the action, or ``#f'' if no action by that name exists


     Since 2.4


 -- Function: gtk-action-group-list-actions (self `<gtk-action-group>')
          =>  (ret `glist-of')
 -- Method: list-actions
     Lists the actions in the action group.

    ACTION-GROUP
          the action group

    RET
          an allocated list of the action objects in the action group


     Since 2.4


 -- Function: gtk-action-group-add-action (self `<gtk-action-group>')
          (action `<gtk-action>')
 -- Method: add-action
     Adds an action object to the action group. Note that this function
     does not set up the accel path of the action, which can lead to
     problems if a user tries to modify the accelerator of a menuitem
     associated with the action. Therefore you must either set the
     accel path yourself with `gtk-action-set-accel-path', or use
     `gtk_action_group_add_action_with_accel (..., NULL)'.

    ACTION-GROUP
          the action group

    ACTION
          an action


     Since 2.4


 -- Function: gtk-action-group-remove-action
          (self `<gtk-action-group>') (action `<gtk-action>')
 -- Method: remove-action
     Removes an action object from the action group.

    ACTION-GROUP
          the action group

    ACTION
          an action


     Since 2.4


 -- Function: gtk-action-group-add-actions (self `<gtk-action-group>')
          (entries `scm')
 -- Method: add-actions
     This is a convenience function to create a number of actions and
     add them to the action group.

     The "activate" signals of the actions are connected to the
     callbacks and their accel paths are set to `<Actions>//'.

    ACTION-GROUP
          The action group

    SCM
          An list of actions. The actions are of the form `(NAME
          STOCK-ID `label' `accelerator' `tooltip' `proc'?)'. All
          values are strings except the PROC, which should be a
          procedure suitable for connecting to the `activate' signal on
          the action. STOCK-ID, LABEL, ACCELERATOR, TOOLTIP, and PROC
          may be `#f'.


     Since 2.4


 -- Function: gtk-action-group-add-toggle-actions
          (self `<gtk-action-group>') (entries `scm')
 -- Method: add-toggle-actions
     This is a convenience function to create a number of toggle
     actions and add them to the action group.

     The "activate" signals of the actions are connected to the
     callbacks and their accel paths are set to
     `<Actions>/GROUP-NAME/ACTION-NAME'.

    ACTION-GROUP
          the action group

    ENTRIES
          an array of toggle action descriptions

    N-ENTRIES
          the number of entries

    USER-DATA
          data to pass to the action callbacks


     Since 2.4


 -- Function: gtk-action-group-add-radio-actions
          (self `<gtk-action-group>') (entries `scm') (value `int')
          (on_change `scm')
 -- Method: add-radio-actions
     This is a convenience routine to create a group of radio actions
     and add them to the action group.

     The "changed" signal of the first radio action is connected to the
     ON-CHANGE callback and the accel paths of the actions are set to
     `<Actions>/GROUP-NAME/ACTION-NAME'.

    ACTION-GROUP
          the action group

    ENTRIES
          an array of radio action descriptions

    N-ENTRIES
          the number of entries

    VALUE
          the value of the action to activate initially, or -1 if no
          action should be activated

    ON-CHANGE
          the callback to connect to the changed signal

    USER-DATA
          data to pass to the action callbacks


     Since 2.4


 -- Function: gtk-action-group-translate-string
          (self `<gtk-action-group>') (string `mchars') => 
          (ret `mchars')
 -- Method: translate-string
     Translates a string using the specified `translate-func'. This is
     mainly intended for language bindings.

    ACTION-GROUP
          a `<gtk-action-group>'

    STRING
          a string

    RET
          the translation of STRING


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkAction,  Next: GtkToggleAction,  Prev: GtkActionGroup,  Up: Top

74 GtkAction
************

An action which can be triggered by a menu or toolbar item

74.1 Overview
=============

Actions represent operations that the user can be perform, along with
some information how it should be presented in the interface. Each
action provides methods to create icons, menu items and toolbar items
representing itself.

   As well as the callback that is called when the action gets
activated, the following also gets associated with the action: The
action will also have some state information:

   a name (not translated, for path lookup)

   a label (translated, for display)

   an accelerator

   whether label indicates a stock id

   a tooltip (optional, translated)

   a toolbar label (optional, shorter than label)

   visible (shown/hidden)

   sensitive (enabled/disabled)

   Apart from regular actions, there are toggle actions, which can be
toggled between two states and radio actions, of which only one in a
group can be in the "active" state. Other actions can be implemented as
`<gtk-action>' subclasses.

   Each action can have one or more proxy menu item, toolbar button or
other proxy widgets. Proxies mirror the state of the action (text
label, tooltip, icon, visible, sensitive, etc), and should change when
the action's state changes.  When the proxy is activated, it should
activate its action.

74.2 Usage
==========

 -- Class: <gtk-action>
     Derives from `<gtk-buildable>', `<gobject>'.

     This class defines the following properties:

    `name'
          A unique name for the action.

    `label'
          The label used for menu items and buttons that activate this
          action.

    `short-label'
          A shorter label that may be used on toolbar buttons.

    `tooltip'
          A tooltip for this action.

    `stock-id'
          The stock icon displayed in widgets representing this action.

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

    `visible-horizontal'
          Whether the toolbar item is visible when the toolbar is in a
          horizontal orientation.

    `visible-vertical'
          Whether the toolbar item is visible when the toolbar is in a
          vertical orientation.

    `visible-overflown'
          When TRUE, toolitem proxies for this action are represented
          in the toolbar overflow menu.

    `is-important'
          Whether the action is considered important. When TRUE,
          toolitem proxies for this action show text in
          GTK_TOOLBAR_BOTH_HORIZ mode.

    `hide-if-empty'
          When TRUE, empty menu proxies for this action are hidden.

    `sensitive'
          Whether the action is enabled.

    `visible'
          Whether the action is visible.

    `action-group'
          The GtkActionGroup this GtkAction is associated with, or NULL
          (for internal use).



 -- Signal on <gtk-action>: activate
     The "activate" signal is emitted when the action is activated.

     Since 2.4


 -- Function: gtk-action-new (name `mchars') (label `mchars')
          (tooltip `mchars') (stock_id `mchars') => 
          (ret `<gtk-action>')
     Creates a new `<gtk-action>' object. To add the action to a
     `<gtk-action-group>' and set the accelerator for the action, call
     `gtk-action-group-add-action-with-accel'. See _(the missing figure,
     XML-UI_ for information on allowed action names.

    NAME
          A unique name for the action

    LABEL
          the label displayed in menu items and on buttons

    TOOLTIP
          a tooltip for the action

    STOCK-ID
          the stock icon to display in widgets representing the action

    RET
          a new `<gtk-action>'


     Since 2.4


 -- Function: gtk-action-get-name (self `<gtk-action>') => 
          (ret `mchars')
 -- Method: get-name
     Returns the name of the action.

    ACTION
          the action object

    RET
          the name of the action. The string belongs to GTK+ and should
          not be freed.


     Since 2.4


 -- Function: gtk-action-is-sensitive (self `<gtk-action>') => 
          (ret `bool')
 -- Method: is-sensitive
     Returns whether the action is effectively sensitive.

    ACTION
          the action object

    RET
          ``#t'' if the action and its associated action group are both
          sensitive.


     Since 2.4


 -- Function: gtk-action-get-sensitive (self `<gtk-action>') => 
          (ret `bool')
 -- Method: get-sensitive
     Returns whether the action itself is sensitive. Note that this
     doesn't necessarily mean effective sensitivity. See
     `gtk-action-is-sensitive' for that.

    ACTION
          the action object

    RET
          ``#t'' if the action itself is sensitive.


     Since 2.4


 -- Function: gtk-action-set-sensitive (self `<gtk-action>')
          (sensitive `bool')
 -- Method: set-sensitive
     Sets the ::sensitive property of the action to SENSITIVE. Note
     that this doesn't necessarily mean effective sensitivity. See
     `gtk-action-is-sensitive' for that.

    ACTION
          the action object

    SENSITIVE
          ``#t'' to make the action sensitive


     Since 2.6


 -- Function: gtk-action-is-visible (self `<gtk-action>') => 
          (ret `bool')
 -- Method: is-visible
     Returns whether the action is effectively visible.

    ACTION
          the action object

    RET
          ``#t'' if the action and its associated action group are both
          visible.


     Since 2.4


 -- Function: gtk-action-get-visible (self `<gtk-action>') => 
          (ret `bool')
 -- Method: get-visible
     Returns whether the action itself is visible. Note that this
     doesn't necessarily mean effective visibility. See
     `gtk-action-is-sensitive' for that.

    ACTION
          the action object

    RET
          ``#t'' if the action itself is visible.


     Since 2.4


 -- Function: gtk-action-set-visible (self `<gtk-action>')
          (visible `bool')
 -- Method: set-visible
     Sets the ::visible property of the action to VISIBLE. Note that
     this doesn't necessarily mean effective visibility. See
     `gtk-action-is-visible' for that.

    ACTION
          the action object

    VISIBLE
          ``#t'' to make the action visible


     Since 2.6


 -- Function: gtk-action-activate (self `<gtk-action>')
 -- Method: activate
     Emits the "activate" signal on the specified action, if it isn't
     insensitive.  This gets called by the proxy widgets when they get
     activated.

     It can also be used to manually activate an action.

    ACTION
          the action object


     Since 2.4


 -- Function: gtk-action-create-icon (self `<gtk-action>')
          (icon_size `<gtk-icon-size>') =>  (ret `<gtk-widget>')
 -- Method: create-icon
     This function is intended for use by action implementations to
     create icons displayed in the proxy widgets.

    ACTION
          the action object

    ICON-SIZE
          the size of the icon that should be created.

    RET
          a widget that displays the icon for this action.


     Since 2.4


 -- Function: gtk-action-create-menu-item (self `<gtk-action>') => 
          (ret `<gtk-widget>')
 -- Method: create-menu-item
     Creates a menu item widget that proxies for the given action.

    ACTION
          the action object

    RET
          a menu item connected to the action.


     Since 2.4


 -- Function: gtk-action-create-tool-item (self `<gtk-action>') => 
          (ret `<gtk-widget>')
 -- Method: create-tool-item
     Creates a toolbar item widget that proxies for the given action.

    ACTION
          the action object

    RET
          a toolbar item connected to the action.


     Since 2.4


 -- Function: gtk-action-connect-proxy (self `<gtk-action>')
          (proxy `<gtk-widget>')
 -- Method: connect-proxy
     Connects a widget to an action object as a proxy. Synchronises
     various properties of the action with the widget (such as label
     text, icon, tooltip, etc), and attaches a callback so that the
     action gets activated when the proxy widget does.

     If the widget is already connected to an action, it is
     disconnected first.

    ACTION
          the action object

    PROXY
          the proxy widget


     Since 2.4


 -- Function: gtk-action-disconnect-proxy (self `<gtk-action>')
          (proxy `<gtk-widget>')
 -- Method: disconnect-proxy
     Disconnects a proxy widget from an action. Does _not_ destroy the
     widget, however.

    ACTION
          the action object

    PROXY
          the proxy widget


     Since 2.4


 -- Function: gtk-action-get-proxies (self `<gtk-action>') => 
          (ret `gslist-of')
 -- Method: get-proxies
     Returns the proxy widgets for an action. See also
     `gtk-widget-get-action'.

    ACTION
          the action object

    RET
          a `<gs-list>' of proxy widgets. The list is owned by GTK+ and
          must not be modified.


     Since 2.4


 -- Function: gtk-action-connect-accelerator (self `<gtk-action>')
 -- Method: connect-accelerator
     Installs the accelerator for ACTION if ACTION has an accel path and
     group. See `gtk-action-set-accel-path' and
     `gtk-action-set-accel-group'

     Since multiple proxies may independently trigger the installation
     of the accelerator, the ACTION counts the number of times this
     function has been called and doesn't remove the accelerator until
     `gtk-action-disconnect-accelerator' has been called as many times.

    ACTION
          a `<gtk-action>'


     Since 2.4


 -- Function: gtk-action-disconnect-accelerator (self `<gtk-action>')
 -- Method: disconnect-accelerator
     Undoes the effect of one call to `gtk-action-connect-accelerator'.

    ACTION
          a `<gtk-action>'


     Since 2.4


 -- Function: gtk-action-block-activate-from (self `<gtk-action>')
          (proxy `<gtk-widget>')
 -- Method: block-activate-from
     Disables calls to the `gtk-action-activate' function by signals on
     the given proxy widget. This is used to break notification loops
     for things like check or radio actions.

     This function is intended for use by action implementations.

    ACTION
          the action object

    PROXY
          a proxy widget


     Since 2.4


 -- Function: gtk-action-unblock-activate-from (self `<gtk-action>')
          (proxy `<gtk-widget>')
 -- Method: unblock-activate-from
     Re-enables calls to the `gtk-action-activate' function by signals
     on the given proxy widget. This undoes the blocking done by
     `gtk-action-block-activate-from'.

     This function is intended for use by action implementations.

    ACTION
          the action object

    PROXY
          a proxy widget


     Since 2.4


 -- Function: gtk-action-get-accel-path (self `<gtk-action>') => 
          (ret `mchars')
 -- Method: get-accel-path
     Returns the accel path for this action.

    ACTION
          the action object

    RET
          the accel path for this action, or ``#f'' if none is set. The
          returned string is owned by GTK+ and must not be freed or
          modified.


     Since 2.6


 -- Function: gtk-action-set-accel-path (self `<gtk-action>')
          (accel_path `mchars')
 -- Method: set-accel-path
     Sets the accel path for this action. All proxy widgets associated
     with the action will have this accel path, so that their
     accelerators are consistent.

    ACTION
          the action object

    ACCEL-PATH
          the accelerator path


     Since 2.4


 -- Function: gtk-action-get-accel-closure (self `<gtk-action>') => 
          (ret `<gclosure>')
 -- Method: get-accel-closure
     Returns the accel closure for this action.

    ACTION
          the action object

    RET
          the accel closure for this action. The returned closure is
          owned by GTK+ and must not be unreffed or modified.


     Since 2.8


 -- Function: gtk-action-set-accel-group (self `<gtk-action>')
          (accel_group `<gtk-accel-group>')
 -- Method: set-accel-group
     Sets the `<gtk-accel-group>' in which the accelerator for this
     action will be installed.

    ACTION
          the action object

    ACCEL-GROUP
          a `<gtk-accel-group>' or ``#f''


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkToggleAction,  Next: GtkRadioAction,  Prev: GtkAction,  Up: Top

75 GtkToggleAction
******************

An action which can be toggled between two states

75.1 Overview
=============

A `<gtk-toggle-action>' corresponds roughly to a
`<gtk-check-menu-item>'. It has an "active" state specifying whether the
action has been checked or not.

75.2 Usage
==========

 -- Class: <gtk-toggle-action>
     Derives from `<gtk-action>'.

     This class defines the following properties:

    `draw-as-radio'
          Whether the proxies for this action look like radio action
          proxies

    `active'
          If the toggle action should be active in or not



 -- Signal on <gtk-toggle-action>: toggled

 -- Function: gtk-toggle-action-new (name `mchars') (label `mchars')
          (tooltip `mchars') (stock_id `mchars') => 
          (ret `<gtk-toggle-action>')
     Creates a new `<gtk-toggle-action>' object. To add the action to a
     `<gtk-action-group>' and set the accelerator for the action, call
     `gtk-action-group-add-action-with-accel'.

    NAME
          A unique name for the action

    LABEL
          The label displayed in menu items and on buttons

    TOOLTIP
          A tooltip for the action

    STOCK-ID
          The stock icon to display in widgets representing the action

    RET
          a new `<gtk-toggle-action>'


     Since 2.4


 -- Function: gtk-toggle-action-toggled (self `<gtk-toggle-action>')
 -- Method: toggled
     Emits the "toggled" signal on the toggle action.

    ACTION
          the action object


     Since 2.4


 -- Function: gtk-toggle-action-set-active (self `<gtk-toggle-action>')
          (is_active `bool')
 -- Method: set-active
     Sets the checked state on the toggle action.

    ACTION
          the action object

    IS-ACTIVE
          whether the action should be checked or not


     Since 2.4


 -- Function: gtk-toggle-action-get-active (self `<gtk-toggle-action>')
          =>  (ret `bool')
 -- Method: get-active
     Returns the checked state of the toggle action.

    ACTION
          the action object

    RET
          the checked state of the toggle action


     Since 2.4


 -- Function: gtk-toggle-action-set-draw-as-radio
          (self `<gtk-toggle-action>') (draw_as_radio `bool')
 -- Method: set-draw-as-radio
     Sets whether the action should have proxies like a radio action.

    ACTION
          the action object

    DRAW-AS-RADIO
          whether the action should have proxies like a radio action


     Since 2.4


 -- Function: gtk-toggle-action-get-draw-as-radio
          (self `<gtk-toggle-action>') =>  (ret `bool')
 -- Method: get-draw-as-radio
     Returns whether the action should have proxies like a radio action.

    ACTION
          the action object

    RET
          whether the action should have proxies like a radio action.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkRadioAction,  Next: GtkColorButton,  Prev: GtkToggleAction,  Up: Top

76 GtkRadioAction
*****************

An action of which only one in a group can be active

76.1 Overview
=============

A `<gtk-radio-action>' is similar to `<gtk-radio-menu-item>'. A number
of radio actions can be linked together so that only one may be active
at any one time.

76.2 Usage
==========

 -- Class: <gtk-radio-action>
     Derives from `<gtk-toggle-action>'.

     This class defines the following properties:

    `value'
          The value returned by gtk_radio_action_get_current_value()
          when this action is the current action of its group.

    `group'
          The radio action whose group this action belongs to.

    `current-value'
          The value property of the currently active member of the
          group to which this action belongs.



 -- Signal on <gtk-radio-action>: changed (arg0 `<gtk-radio-action>')
     The ::changed signal is emitted on every member of a radio group
     when the active member is changed. The signal gets emitted after
     the ::activate signals for the previous and current active members.

     Since 2.4


 -- Function: gtk-radio-action-new (name `mchars') (label `mchars')
          (tooltip `mchars') (stock_id `mchars') (value `int') => 
          (ret `<gtk-radio-action>')
     Creates a new `<gtk-radio-action>' object. To add the action to a
     `<gtk-action-group>' and set the accelerator for the action, call
     `gtk-action-group-add-action-with-accel'.

    NAME
          A unique name for the action

    LABEL
          The label displayed in menu items and on buttons

    TOOLTIP
          A tooltip for this action

    STOCK-ID
          The stock icon to display in widgets representing this action

    VALUE
          The value which `gtk-radio-action-get-current-value' should
          return if this action is selected.

    RET
          a new `<gtk-radio-action>'


     Since 2.4


 -- Function: gtk-radio-action-get-group (self `<gtk-radio-action>')
          =>  (ret `<gtk-radio-group*>')
 -- Method: get-group
     Returns the list representing the radio group for this object.
     Note that the returned list is only valid until the next change to
     the group.

     A common way to set up a group of radio group is the following:


            GSList *group = NULL;
            GtkRadioAction *action;

            while (/* more actions to add */)
              {
                 action = gtk_radio_action_new (...);

                 gtk_radio_action_set_group (action, group);
                 group = gtk_radio_action_get_group (action);
              }

    ACTION
          the action object

    RET
          the list representing the radio group for this object


     Since 2.4


 -- Function: gtk-radio-action-set-group (self `<gtk-radio-action>')
          (group `<gtk-radio-group*>')
 -- Method: set-group
     Sets the radio group for the radio action object.

    ACTION
          the action object

    GROUP
          a list representing a radio group


     Since 2.4


 -- Function: gtk-radio-action-get-current-value
          (self `<gtk-radio-action>') =>  (ret `int')
 -- Method: get-current-value
     Obtains the value property of the currently active member of the
     group to which ACTION belongs.

    ACTION
          a `<gtk-radio-action>'

    RET
          The value of the currently active group member


     Since 2.4


 -- Function: gtk-radio-action-set-current-value
          (self `<gtk-radio-action>') (current_value `int')
 -- Method: set-current-value
     Sets the currently active group member to the member with value
     property CURRENT-VALUE.

    ACTION
          a `<gtk-radio-action>'

    CURRENT-VALUE
          the new value


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkColorButton,  Next: GtkColorSelection,  Prev: GtkRadioAction,  Up: Top

77 GtkColorButton
*****************

A button to launch a color selection dialog

77.1 Overview
=============

The `<gtk-color-button>' is a button which displays the currently
selected color an allows to open a color selection dialog to change the
color. It is suitable widget for selecting a color in a preference
dialog.

77.2 Usage
==========

 -- Class: <gtk-color-button>
     Derives from `<gtk-button>'.

     This class defines the following properties:

    `use-alpha'
          Whether or not to give the color an alpha value

    `title'
          The title of the color selection dialog

    `color'
          The selected color

    `alpha'
          The selected opacity value (0 fully transparent, 65535 fully
          opaque)



 -- Signal on <gtk-color-button>: color-set
     The ::color-set signal is emitted when the user selects a color.
     When handling this signal, use `gtk-color-button-get-color' and
     `gtk-color-button-get-alpha' to find out which color was just
     selected.

     Note that this signal is only emitted when the _user_ changes the
     color. If you need to react to programmatic color changes as well,
     use the notify::color signal.

     Since 2.4


 -- Function: gtk-color-button-new =>  (ret `<gtk-widget>')
     Creates a new color button. This returns a widget in the form of a
     small button containing a swatch representing the current selected
     color. When the button is clicked, a color-selection dialog will
     open, allowing the user to select a color. The swatch will be
     updated to reflect the new color when the user finishes.

    RET
          a new color button.


     Since 2.4


 -- Function: gtk-color-button-new-with-color (color `<gdk-color>') => 
          (ret `<gtk-widget>')
     Creates a new color button.

    COLOR
          A `<gdk-color>' to set the current color with.

    RET
          a new color button.


     Since 2.4


 -- Function: gtk-color-button-set-color (self `<gtk-color-button>')
          (color `<gdk-color>')
 -- Method: set-color
     Sets the current color to be COLOR.

    COLOR-BUTTON
          a `<gtk-color-button>'.

    COLOR
          A `<gdk-color>' to set the current color with.


     Since 2.4


 -- Function: gtk-color-button-get-color (self `<gtk-color-button>')
          (color `<gdk-color>')
 -- Method: get-color
     Sets COLOR to be the current color in the `<gtk-color-button>'
     widget.

    COLOR-BUTTON
          a `<gtk-color-button>'.

    COLOR
          a `<gdk-color>' to fill in with the current color.


     Since 2.4


 -- Function: gtk-color-button-set-alpha (self `<gtk-color-button>')
          (alpha `unsigned-int16')
 -- Method: set-alpha
     Sets the current opacity to be ALPHA.

    COLOR-BUTTON
          a `<gtk-color-button>'.

    ALPHA
          an integer between 0 and 65535.


     Since 2.4


 -- Function: gtk-color-button-get-alpha (self `<gtk-color-button>')
          =>  (ret `unsigned-int16')
 -- Method: get-alpha
     Returns the current alpha value.

    COLOR-BUTTON
          a `<gtk-color-button>'.

    RET
          an integer between 0 and 65535.


     Since 2.4


 -- Function: gtk-color-button-set-use-alpha
          (self `<gtk-color-button>') (use_alpha `bool')
 -- Method: set-use-alpha
     Sets whether or not the color button should use the alpha channel.

    COLOR-BUTTON
          a `<gtk-color-button>'.

    USE-ALPHA
          ``#t'' if color button should use alpha channel, ``#f'' if
          not.


     Since 2.4


 -- Function: gtk-color-button-get-use-alpha
          (self `<gtk-color-button>') =>  (ret `bool')
 -- Method: get-use-alpha
     Does the color selection dialog use the alpha channel?

    COLOR-BUTTON
          a `<gtk-color-button>'.

    RET
          ``#t'' if the color sample uses alpha channel, ``#f'' if not.


     Since 2.4


 -- Function: gtk-color-button-set-title (self `<gtk-color-button>')
          (title `mchars')
 -- Method: set-title
     Sets the title for the color selection dialog.

    COLOR-BUTTON
          a `<gtk-color-button>'

    TITLE
          String containing new window title.


     Since 2.4


 -- Function: gtk-color-button-get-title (self `<gtk-color-button>')
          =>  (ret `mchars')
 -- Method: get-title
     Gets the title of the color selection dialog.

    COLOR-BUTTON
          a `<gtk-color-button>'

    RET
          An internal string, do not free the return value


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkColorSelection,  Next: GtkColorSelectionDialog,  Prev: GtkColorButton,  Up: Top

78 GtkColorSelection
********************

A widget used to select a color

78.1 Overview
=============

The `<gtk-color-selection>' is a widget that is used to select a color.
It consists of a color wheel and number of sliders and entry boxes for
color parameters such as hue, saturation, value, red, green, blue, and
opacity. It is found on the standard color selection dialog box
`<gtk-color-selection-dialog>'.

78.2 Usage
==========

 -- Class: <gtk-color-selection>
     Derives from `<gtk-vbox>'.

     This class defines the following properties:

    `has-palette'
          Whether a palette should be used

    `has-opacity-control'
          Whether the color selector should allow setting opacity

    `current-color'
          The current color

    `current-alpha'
          The current opacity value (0 fully transparent, 65535 fully
          opaque)



 -- Signal on <gtk-color-selection>: color-changed
     This signal is emitted when the color changes in the
     `<gtk-color-selection>' according to its update policy.


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

    RET
          a new `<gtk-color-selection>'



 -- Function: gtk-color-selection-set-has-palette
          (self `<gtk-color-selection>') (has_palette `bool')
 -- Method: set-has-palette
     Shows and hides the palette based upon the value of HAS-PALETTE.

    COLORSEL
          a `<gtk-color-selection>'.

    HAS-PALETTE
          ``#t'' if palette is to be visible, ``#f'' otherwise.



 -- Function: gtk-color-selection-get-has-palette
          (self `<gtk-color-selection>') =>  (ret `bool')
 -- Method: get-has-palette
     Determines whether the color selector has a color palette.

    COLORSEL
          a `<gtk-color-selection>'.

    RET
          ``#t'' if the selector has a palette. ``#f'' if it hasn't.



 -- Function: gtk-color-selection-is-adjusting
          (self `<gtk-color-selection>') =>  (ret `bool')
 -- Method: is-adjusting
     Gets the current state of the COLORSEL.

    COLORSEL
          a `<gtk-color-selection>'.

    RET
          ``#t'' if the user is currently dragging a color around, and
          ``#f'' if the selection has stopped.




File: guile-gnome-gtk.info,  Node: GtkColorSelectionDialog,  Next: GtkFileSelection,  Prev: GtkColorSelection,  Up: Top

79 GtkColorSelectionDialog
**************************

A standard dialog box for selecting a color

79.1 Overview
=============

The `<gtk-color-selection-dialog>' provides a standard dialog which
allows the user to select a color much like the `<gtk-file-selection>'
provides a standard dialog for file selection.

79.2 Usage
==========

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

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


 -- Function: gtk-color-selection-dialog-new (title `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-color-selection-dialog>'.

    TITLE
          a string containing the title text for the dialog.

    RET
          a `<gtk-color-selection-dialog>'.




File: guile-gnome-gtk.info,  Node: GtkFileSelection,  Next: GtkFileChooser,  Prev: GtkColorSelectionDialog,  Up: Top

80 GtkFileSelection
*******************

Prompt the user for a file or directory name

80.1 Overview
=============

`<gtk-file-selection>' should be used to retrieve file or directory
names from the user. It will create a new dialog window containing a
directory list, and a file list corresponding to the current working
directory. The filesystem can be navigated using the directory list or
the drop-down history menu.  Alternatively, the TAB key can be used to
navigate using filename completion - common in text based editors such
as emacs and jed.

   File selection dialogs are created with a call to
`gtk-file-selection-new'.

   The default filename can be set using
`gtk-file-selection-set-filename' and the selected filename retrieved
using `gtk-file-selection-get-filename'.

   Use `gtk-file-selection-complete' to display files and directories
that match a given pattern. This can be used for example, to show only
*.txt files, or only files beginning with gtk*.

   Simple file operations; create directory, delete file, and rename
file, are available from buttons at the top of the dialog. These can be
hidden using `gtk-file-selection-hide-fileop-buttons' and shown again
using `gtk-file-selection-show-fileop-buttons'.



     /* The file selection widget and the string to store the chosen filename */

     void store_filename (GtkWidget *widget, gpointer user_data) {
        GtkWidget *file_selector = GTK_WIDGET (user_data);
        const gchar *selected_filename;

        selected_filename = gtk_file_selection_get_filename (GTK_FILE_SELECTION (file_selector));
        g_print ("Selected filename: %s\n", selected_filename);
     }

     void create_file_selection (void) {

        GtkWidget *file_selector;

        /* Create the selector */

        file_selector = gtk_file_selection_new ("Please select a file for editing.");

        g_signal_connect (GTK_FILE_SELECTION (file_selector)->ok_button,
                          "clicked",
                          G_CALLBACK (store_filename),
                          file_selector);

        /* Ensure that the dialog box is destroyed when the user clicks a button. */

        g_signal_connect_swapped (GTK_FILE_SELECTION (file_selector)->ok_button,
                                  "clicked",
                                  G_CALLBACK (gtk_widget_destroy),
                                  file_selector);

        g_signal_connect_swapped (GTK_FILE_SELECTION (file_selector)->cancel_button,
                                  "clicked",
                                  G_CALLBACK (gtk_widget_destroy),
                                  file_selector);

        /* Display that dialog */

        gtk_widget_show (file_selector);
     }

80.2 Usage
==========

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

     This class defines the following properties:

    `show-fileops'
          Whether buttons for creating/manipulating files should be
          displayed

    `filename'
          The currently selected filename

    `select-multiple'
          Whether to allow multiple files to be selected



 -- Function: gtk-file-selection-new (title `mchars') => 
          (ret `<gtk-widget>')
     Creates a new file selection dialog box. By default it will
     contain a `<gtk-tree-view>' of the application's current working
     directory, and a file listing. Operation buttons that allow the
     user to create a directory, delete files and rename files, are
     also present.

    TITLE
          a message that will be placed in the file requestor's
          titlebar.

    RET
          the new file selection.



 -- Function: gtk-file-selection-set-filename
          (self `<gtk-file-selection>') (filename `mchars')
 -- Method: set-filename
     Sets a default path for the file requestor. If FILENAME includes a
     directory path, then the requestor will open with that path as its
     current working directory.

     This has the consequence that in order to open the requestor with
     a working directory and an empty filename, FILENAME must have a
     trailing directory separator.

     The encoding of FILENAME is preferred GLib file name encoding,
     which may not be UTF-8. See `g-filename-from-utf8'.

    FILESEL
          a `<gtk-file-selection>'.

    FILENAME
          a string to set as the default file name.



 -- Function: gtk-file-selection-get-filename
          (self `<gtk-file-selection>') =>  (ret `mchars')
 -- Method: get-filename
     This function returns the selected filename in the GLib file name
     encoding. To convert to UTF-8, call `g-filename-to-utf8'. The
     returned string points to a statically allocated buffer and should
     be copied if you plan to keep it around.

     If no file is selected then the selected directory path is
     returned.

    FILESEL
          a `<gtk-file-selection>'

    RET
          currently-selected filename in the on-disk encoding.



 -- Function: gtk-file-selection-complete (self `<gtk-file-selection>')
          (pattern `mchars')
 -- Method: complete
     Will attempt to match PATTERN to a valid filenames or
     subdirectories in the current directory. If a match can be made,
     the matched filename will appear in the text entry field of the
     file selection dialog. If a partial match can be made, the "Files"
     list will contain those file names which have been partially
     matched, and the "Folders" list those directories which have been
     partially matched.

    FILESEL
          a `<gtk-file-selection>'.

    PATTERN
          a string of characters which may or may not match any
          filenames in the current directory.




File: guile-gnome-gtk.info,  Node: GtkFileChooser,  Next: GtkFileChooserButton,  Prev: GtkFileSelection,  Up: Top

81 GtkFileChooser
*****************

File chooser interface used by GtkFileChooserWidget and
GtkFileChooserDialog

81.1 Overview
=============

`<gtk-file-chooser>' is an interface that can be implemented by file
selection widgets. In GTK+, the main objects that implement this
interface are `<gtk-file-chooser-widget>', `<gtk-file-chooser-dialog>',
and `<gtk-file-chooser-button>'. You do not need to write an object that
implements the `<gtk-file-chooser>' interface unless you are trying to
adapt an existing file selector to expose a standard programming
interface.

   `<gtk-file-chooser>' allows for shortcuts to various places in the
filesystem. In the default implementation these are displayed in the
left pane.  It may be a bit confusing at first taht these shortcuts
come from various sources and in various flavours, so lets explain the
terminology here:

SHORTCUTS

VOLUMES

   are created by the user, by dragging folders from the right pane to
the left pane, or by using the "Add". Bookmarks can be renamed and
deleted by the user.

   can be provided by the application or by the underlying filesystem
abstraction (e.g. both the gnome-vfs and the Windows filesystems
provide "Desktop" shortcuts). Shortcuts cannot be modified by the user.

   are provided by the underlying filesystem abstraction. They are the
"roots" of the filesystem.

81.2 File Names and Encodings
=============================

When the user is finished selecting files in a `<gtk-file-chooser>',
your program can get the selected names either as filenames or as URIs.
For URIs, the normal escaping rules are applied if the URI contains
non-ASCII characters.  However, filenames are _always_ returned in the
character set specified by the `G_FILENAME_ENCODING' environment
variable. Please see the Glib documentation for more details about this
variable.

   This means that while you can pass the result of
`gtk-file-chooser-get-filename' to `open(2)' or `fopen(3)', you may not
be able to directly set it as the text of a `<gtk-label>' widget unless
you convert it first to UTF-8, which all GTK+ widgets expect. You should
use `g-filename-to-utf8' to convert filenames into strings that can be
passed to GTK+ widgets.

81.3 Adding a Preview Widget
============================

You can add a custom preview widget to a file chooser and then get
notification about when the preview needs to be updated. To install a
preview widget, use `gtk-file-chooser-set-preview-widget'. Then,
connect to the `<gtk-file-chooser::update-preview>' signal to get
notified when you need to update the contents of the preview.

   Your callback should use `gtk-file-chooser-get-preview-filename' to
see what needs previewing. Once you have generated the preview for the
corresponding file, you must call
`gtk-file-chooser-set-preview-widget-active' with a boolean flag that
indicates whether your callback could successfully generate a preview.


     {
       GtkImage *preview;

       ...

       preview = gtk_image_new ();

       gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
       g_signal_connect (my_file_chooser, "update-preview",
     		    G_CALLBACK (update_preview_cb), preview);
     }

     static void
     update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
     {
       GtkWidget *preview;
       char *filename;
       GdkPixbuf *pixbuf;
       gboolean have_preview;

       preview = GTK_WIDGET (data);
       filename = gtk_file_chooser_get_preview_filename (file_chooser);

       pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
       have_preview = (pixbuf != NULL);
       g_free (filename);

       gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
       if (pixbuf)
         gobject_unref (pixbuf);

       gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
     }

81.4 Adding Extra Widgets
=========================

You can add extra widgets to a file chooser to provide options that are
not present in the default design. For example, you can add a toggle
button to give the user the option to open a file in read-only mode.
You can use `gtk-file-chooser-set-extra-widget' to insert additional
widgets in a file chooser.


     {
       GtkWidget *toggle;

       ...

       toggle = gtk_check_button_new_with_label ("Open file read-only");
       gtk_widget_show (toggle);
       gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
     }

   If you want to set more than one extra widget in the file chooser,
you can a container such as a GtkVBox or a GtkTable and include your
widgets in it. Then, set the container as the whole extra widget.

81.5 Key Bindings
=================

Internally, GTK+ implements a file chooser's graphical user interface
with the private . This widget has several key bindings and their
associated signals.  This section describes the available key binding
signals.

   The default keys that activate the key-binding signals in are as
follows:

   Both the individual key and the numeric keypad's "divide" key are
supported.

   Both the individual Up key and the numeric keypad's Up key are
supported.

   You can change these defaults to something else. For example, to add
a modifier to a few of the default bindings, you can include the
following fragment in your `.gtkrc-2.0' file:


     binding "my-own-gtkfilechooser-bindings" {
     	bind "<Alt><Shift>Up" {
     		"up-folder" ()
     	}
     	bind "<Alt><Shift>Down" {
     		"down-folder" ()
     	}
     	bind "<Alt><Shift>Home" {
     		"home-folder" ()
     	}
     }

     class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"

81.5.1 The "GtkFileChooserDefault::location-popup" signal
---------------------------------------------------------


               void user_function (GtkFileChooserDefault *chooser,
                                   const char            *path,
                                   gpointer user_data);

   This is used to make the file chooser show a "Location" dialog which
the user can use to manually type the name of the file he wishes to
select. The PATH argument is a string that gets put in the text entry
for the file name. By default this is bound to with a PATH string of ""
(the empty string). It is also bound to with a PATH string of "`/'" (a
slash): this lets you type and immediately type a path name. On Unix
systems, this is bound to (tilde) with a PATH string of "~" itself for
access to home directories.

CHOOSER
     the object which received the signal.

PATH
     default contents for the text entry for the file name

USER-DATA
     user data set when the signal handler was connected.


   You can create your own bindings for the signal with custom PATH
strings, and have a crude form of easily-to-type bookmarks. For
example, say you access the path `/home/username/misc' very frequently.
You could then create an shortcut by including the following in your
`.gtkrc-2.0':


     binding "misc-shortcut" {
     	bind "<Alt>M" {
     		"location-popup" ("/home/username/misc")
     	}
     }

     class "GtkFileChooserDefault" binding "misc-shortcut"

81.5.2 The "GtkFileChooserDefault::up-folder" signal
----------------------------------------------------


               void user_function (GtkFileChooserDefault *chooser,
                                   gpointer user_data);

   This is used to make the file chooser go to the parent of the
current folder in the file hierarchy. By default this is bound to and
(the Up key in the numeric keypad also works).

CHOOSER
     the object which received the signal.

USER-DATA
     user data set when the signal handler was connected.


81.5.3 The "GtkFileChooserDefault::down-folder" signal
------------------------------------------------------


               void user_function (GtkFileChooserDefault *chooser,
                                   gpointer user_data);

   This is used to make the file chooser go to a child of the current
folder in the file hierarchy. The subfolder that will be used is
displayed in the path bar widget of the file chooser. For example, if
the path bar is showing "/foo/_bar/_baz", then this will cause the file
chooser to switch to the "baz" subfolder. By default this is bound to
(the Down key in the numeric keypad also works).

CHOOSER
     the object which received the signal.

USER-DATA
     user data set when the signal handler was connected.


81.5.4 The "GtkFileChooserDefault::home-folder" signal
------------------------------------------------------


               void user_function (GtkFileChooserDefault *chooser,
                                   gpointer user_data);

   This is used to make the file chooser show the user's home folder in
the file list. By default this is bound to (the Home key in the numeric
keypad also works).

CHOOSER
     the object which received the signal.

USER-DATA
     user data set when the signal handler was connected.


81.5.5 The "GtkFileChooserDefault::desktop-folder" signal
---------------------------------------------------------


               void user_function (GtkFileChooserDefault *chooser,
                                   gpointer user_data);

   This is used to make the file chooser show the user's Desktop folder
in the file list. By default this is bound to .

CHOOSER
     the object which received the signal.

USER-DATA
     user data set when the signal handler was connected.


81.5.6 The "GtkFileChooserDefault::quick-bookmark" signal
---------------------------------------------------------


               void user_function (GtkFileChooserDefault *chooser,
                                   gint bookmark_index,
                                   gpointer user_data);

   This is used to make the file chooser switch to the bookmark
specified in the BOOKMARK-INDEX parameter. For example, if you have
three bookmarks, you can pass 0, 1, 2 to this signal to switch to each
of them, respectively. By default this is bound to , , etc. until .
Note that in the default binding, that is actually defined to switch to
the bookmark at index 0, and so on successively; is defined to switch
to the bookmark at index 10.

CHOOSER
     the object which received the signal.

BOOKMARK-INDES
     index of the bookmark to switch to; the indices start at 0.

USER-DATA
     user data set when the signal handler was connected.


81.6 Usage
==========

 -- Class: <gtk-file-chooser>
     Derives from `<ginterface>'.

     This class defines the following properties:

    `file-system-backend'
          Name of file system backend to use

    `preview-widget-active'
          Whether the application supplied widget for custom previews
          should be shown.

    `do-overwrite-confirmation'
          Whether a file chooser in save mode will present an overwrite
          confirmation dialog if necessary.

    `select-multiple'
          Whether to allow multiple files to be selected

    `action'
          The type of operation that the file selector is performing

    `show-hidden'
          Whether the hidden files and folders should be displayed

    `filter'
          The current filter for selecting which files are displayed

    `extra-widget'
          Application supplied widget for extra options.

    `preview-widget'
          Application supplied widget for custom previews.

    `local-only'
          Whether the selected file(s) should be limited to local file:
          URLs

    `use-preview-label'
          Whether to display a stock label with the name of the
          previewed file.



 -- Signal on <gtk-file-chooser>: current-folder-changed
     This signal is emitted when the current folder in a
     `<gtk-file-chooser>' changes. This can happen due to the user
     performing some action that changes folders, such as selecting a
     bookmark or visiting a folder on the file list. It can also happen
     as a result of calling a function to explicitly change the current
     folder in a file chooser.

     Normally you do not need to connect to this signal, unless you
     need to keep track of which folder a file chooser is showing.

     See also: `gtk-file-chooser-set-current-folder',
     `gtk-file-chooser-get-current-folder',
     `gtk-file-chooser-set-current-folder-uri',
     `gtk-file-chooser-get-current-folder-uri'.


 -- Signal on <gtk-file-chooser>: selection-changed
     This signal is emitted when there is a change in the set of
     selected files in a `<gtk-file-chooser>'. This can happen when the
     user modifies the selection with the mouse or the keyboard, or
     when explicitly calling functions to change the selection.

     Normally you do not need to connect to this signal, as it is
     easier to wait for the file chooser to finish running, and then to
     get the list of selected files using the functions mentioned below.

     See also: `gtk-file-chooser-select-filename',
     `gtk-file-chooser-unselect-filename',
     `gtk-file-chooser-get-filename', `gtk-file-chooser-get-filenames',
     `gtk-file-chooser-select-uri', `gtk-file-chooser-unselect-uri',
     `gtk-file-chooser-get-uri', `gtk-file-chooser-get-uris'.


 -- Signal on <gtk-file-chooser>: update-preview
     This signal is emitted when the preview in a file chooser should
     be regenerated.  For example, this can happen when the currently
     selected file changes. You should use this signal if you want your
     file chooser to have a preview widget.

     Once you have installed a preview widget with
     `gtk-file-chooser-set-preview-widget', you should update it when
     this signal is emitted. You can use the functions
     `gtk-file-chooser-get-preview-filename' or
     `gtk-file-chooser-get-preview-uri' to get the name of the file to
     preview.  Your widget may not be able to preview all kinds of
     files; your callback must call
     `gtk-file-chooser-set-preview-wiget-active' to inform the file
     chooser about whether the preview was generated successfully or
     not.

     Please see the example code in _(the missing figure,
     gtkfilechooser-preview_.

     See also: `gtk-file-chooser-set-preview-widget',
     `gtk-file-chooser-set-preview-widget-active',
     `gtk-file-chooser-set-use-preview-label',
     `gtk-file-chooser-get-preview-filename',
     `gtk-file-chooser-get-preview-uri'.


 -- Signal on <gtk-file-chooser>: file-activated
     This signal is emitted when the user "activates" a file in the
     file chooser.  This can happen by double-clicking on a file in the
     file list, or by pressing (keycap "Enter") .

     Normally you do not need to connect to this signal. It is used
     internally by `<gtk-file-chooser-dialog>' to know when to activate
     the default button in the dialog.

     See also: `gtk-file-chooser-get-filename',
     `gtk-file-chooser-get-filenames', `gtk-file-chooser-get-uri',
     `gtk-file-chooser-get-uris'.


 -- Signal on <gtk-file-chooser>: confirm-overwrite
          => `<gtk-file-chooser-confirmation>'
     This signal gets emitted whenever it is appropriate to present a
     confirmation dialog when the user has selected a file name that
     already exists. The signal only gets emitted when the file chooser
     is in `<gtk-file-chooser-action-save>' mode.

     Most applications just need to turn on the
     do-overwrite-confirmation property (or call the
     `gtk-file-chooser-set-do-overwrite-confirmation' function), and
     they will automatically get a stock confirmation dialog.
     Applications which need to customize this behavior should do that,
     and also connect to the `confirm-overwrite' signal.

     A signal handler for this signal must return a
     `<gtk-file-chooser-confirmation>' value, which indicates the
     action to take. If the handler determines that the user wants to
     select a different filename, it should return
     `<gtk-file-chooser-confirmation-select-again>'.  If it determines
     that the user is satisfied with his choice of file name, it should
     return `<gtk-file-chooser-confirmation-accept-filename>'. On the
     other hand, if it determines that the stock confirmation dialog
     should be used, it should return
     `<gtk-file-chooser-confirmation-confirm>'. The following example
     illustrates this.


 -- Function: gtk-file-chooser-set-action (self `<gtk-file-chooser>')
          (action `<gtk-file-chooser-action>')
 -- Method: set-action
     Sets the type of operation that the chooser is performing; the
     user interface is adapted to suit the selected action. For
     example, an option to create a new folder might be shown if the
     action is `GTK_FILE_CHOOSER_ACTION_SAVE' but not if the action is
     `GTK_FILE_CHOOSER_ACTION_OPEN'.

    CHOOSER
          a `<gtk-file-chooser>'

    ACTION
          the action that the file selector is performing


     Since 2.4


 -- Function: gtk-file-chooser-get-action (self `<gtk-file-chooser>')
          =>  (ret `<gtk-file-chooser-action>')
 -- Method: get-action
     Gets the type of operation that the file chooser is performing; see
     `gtk-file-chooser-set-action'.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          the action that the file selector is performing


     Since 2.4


 -- Function: gtk-file-chooser-set-local-only
          (self `<gtk-file-chooser>') (local_only `bool')
 -- Method: set-local-only
     Sets whether only local files can be selected in the file
     selector. If LOCAL-ONLY is ``#t'' (the default), then the selected
     file are files are guaranteed to be accessible through the
     operating systems native file file system and therefore the
     application only needs to worry about the filename functions in
     `<gtk-file-chooser>', like `gtk-file-chooser-get-filename', rather
     than the URI functions like `gtk-file-chooser-get-uri',

    CHOOSER
          a `<gtk-file-chooser>'

    LOCAL-ONLY
          ``#t'' if only local files can be selected


     Since 2.4


 -- Function: gtk-file-chooser-get-local-only
          (self `<gtk-file-chooser>') =>  (ret `bool')
 -- Method: get-local-only
     Gets whether only local files can be selected in the file
     selector. See `gtk-file-chooser-set-local-only'

    CHOOSER
          a `<gtk-file-choosre>'

    RET
          ``#t'' if only local files can be selected.


     Since 2.4


 -- Function: gtk-file-chooser-set-show-hidden
          (self `<gtk-file-chooser>') (show_hidden `bool')
 -- Method: set-show-hidden
     Sets whether hidden files and folders are displayed in the file
     selector.

    CHOOSER
          a `<gtk-file-chooser>'

    SHOW-HIDDEN
          ``#t'' if hidden files and folders should be displayed.


     Since 2.6


 -- Function: gtk-file-chooser-get-show-hidden
          (self `<gtk-file-chooser>') =>  (ret `bool')
 -- Method: get-show-hidden
     Gets whether hidden files and folders are displayed in the file
     selector. See `gtk-file-chooser-set-show-hidden'.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          ``#t'' if hidden files and folders are displayed.


     Since 2.6


 -- Function: gtk-file-chooser-set-current-name
          (self `<gtk-file-chooser>') (name `mchars')
 -- Method: set-current-name
     Sets the current name in the file selector, as if entered by the
     user. Note that the name passed in here is a UTF-8 string rather
     than a filename. This function is meant for such uses as a
     suggested name in a "Save As..." dialog.

     If you want to preselect a particular existing file, you should use
     `gtk-file-chooser-set-filename' or `gtk-file-chooser-set-uri'
     instead.  Please see the documentation for those functions for an
     example of using `gtk-file-chooser-set-current-name' as well.

    CHOOSER
          a `<gtk-file-chooser>'

    NAME
          the filename to use, as a UTF-8 string


     Since 2.4


 -- Function: gtk-file-chooser-get-filename (self `<gtk-file-chooser>')
          =>  (ret `mchars')
 -- Method: get-filename
     Gets the filename for the currently selected file in the file
     selector. If multiple files are selected, one of the filenames
     will be returned at random.

     If the file chooser is in folder mode, this function returns the
     selected folder.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          The currently selected filename, or ``#f'' if no file is
          selected, or the selected file can't be represented with a
          local filename. Free with `g-free'.


     Since 2.4


 -- Function: gtk-file-chooser-set-filename (self `<gtk-file-chooser>')
          (filename `mchars') =>  (ret `bool')
 -- Method: set-filename
     Sets FILENAME as the current filename for the file chooser, by
     changing to the file's parent folder and actually selecting the
     file in list. If the CHOOSER is in
     `<gtk-file-chooser-action-save>' mode, the file's base name will
     also appear in the dialog's file name entry.

     If the file name isn't in the current folder of CHOOSER, then the
     current folder of CHOOSER will be changed to the folder containing
     FILENAME.  This is equivalent to a sequence of
     `gtk-file-chooser-unselect-all' followed by
     `gtk-file-chooser-select-filename'.

     Note that the file must exist, or nothing will be done except for
     the directory change.

     If you are implementing a use this function if you already have a
     file name to which the user may save; for example, when the user
     opens an existing file and then does "File/Save As...") on it. If
     you don't have a file name already &#x2014; for example, if the
     user just created a new file and is saving it for the first time,
     do not call this function. Instead, use something similar to this:


          if (document_is_new)
            {
              /* the user just created a new document */
              gtk_file_chooser_set_current_folder (chooser, default_folder_for_saving);
              gtk_file_chooser_set_current_name (chooser, "Untitled document");
            }
          else
            {
              /* the user edited an existing document */
              gtk_file_chooser_set_filename (chooser, existing_filename);
            }

    CHOOSER
          a `<gtk-file-chooser>'

    FILENAME
          the filename to set as current

    RET
          ``#t'' if both the folder could be changed and the file was
          selected successfully, ``#f'' otherwise.


     Since 2.4


 -- Function: gtk-file-chooser-select-filename
          (self `<gtk-file-chooser>') (filename `mchars') => 
          (ret `bool')
 -- Method: select-filename
     Selects a filename. If the file name isn't in the current folder of
     CHOOSER, then the current folder of CHOOSER will be changed to the
     folder containing FILENAME.

    CHOOSER
          a `<gtk-file-chooser>'

    FILENAME
          the filename to select

    RET
          ``#t'' if both the folder could be changed and the file was
          selected successfully, ``#f'' otherwise.


     Since 2.4


 -- Function: gtk-file-chooser-unselect-filename
          (self `<gtk-file-chooser>') (filename `mchars')
 -- Method: unselect-filename
     Unselects a currently selected filename. If the filename is not in
     the current directory, does not exist, or is otherwise not
     currently selected, does nothing.

    CHOOSER
          a `<gtk-file-chooser>'

    FILENAME
          the filename to unselect


     Since 2.4


 -- Function: gtk-file-chooser-select-all (self `<gtk-file-chooser>')
 -- Method: select-all
     Selects all the files in the current folder of a file chooser.

    CHOOSER
          a `<gtk-file-chooser>'


     Since 2.4


 -- Function: gtk-file-chooser-unselect-all (self `<gtk-file-chooser>')
 -- Method: unselect-all
     Unselects all the files in the current folder of a file chooser.

    CHOOSER
          a `<gtk-file-chooser>'


     Since 2.4


 -- Function: gtk-file-chooser-get-filenames
          (self `<gtk-file-chooser>') =>  (ret `gslist-of')
 -- Method: get-filenames
     Lists all the selected files and subfolders in the current folder
     of CHOOSER. The returned names are full absolute paths. If files
     in the current folder cannot be represented as local filenames
     they will be ignored.  (See `gtk-file-chooser-get-uris')

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          a `<gs-list>' containing the filenames of all selected files
          and subfolders in the current folder. Free the returned list
          with `g-slist-free', and the filenames with `g-free'.


     Since 2.4


 -- Function: gtk-file-chooser-set-current-folder
          (self `<gtk-file-chooser>') (filename `mchars') => 
          (ret `bool')
 -- Method: set-current-folder
     Sets the current folder for CHOOSER from a local filename. The
     user will be shown the full contents of the current folder, plus
     user interface elements for navigating to other folders.

    CHOOSER
          a `<gtk-file-chooser>'

    FILENAME
          the full path of the new current folder

    RET
          ``#t'' if the folder could be changed successfully, ``#f''
          otherwise.


     Since 2.4


 -- Function: gtk-file-chooser-get-current-folder
          (self `<gtk-file-chooser>') =>  (ret `mchars')
 -- Method: get-current-folder
     Gets the current folder of CHOOSER as a local filename. See
     `gtk-file-chooser-set-current-folder'.

     Note that this is the folder that the file chooser is currently
     displaying (e.g.  "/home/username/Documents"), which is _not the
     same_ as the currently-selected folder if the chooser is in
     `<gtk-file-chooser-select-folder>' mode (e.g.
     "/home/username/Documents/selected-folder/". To get the
     currently-selected folder in that mode, use
     `gtk-file-chooser-get-uri' as the usual way to get the selection.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          the full path of the current folder, or ``#f'' if the current
          path cannot be represented as a local filename. Free with
          `g-free'. This function will also return ``#f'' if the file
          chooser was unable to load the last folder that was requested
          from it; for example, as would be for calling
          `gtk-file-chooser-set-current-folder' on a nonexistent folder.


     Since 2.4


 -- Function: gtk-file-chooser-get-uri (self `<gtk-file-chooser>') => 
          (ret `mchars')
 -- Method: get-uri
     Gets the URI for the currently selected file in the file selector.
     If multiple files are selected, one of the filenames will be
     returned at random.

     If the file chooser is in folder mode, this function returns the
     selected folder.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          The currently selected URI, or ``#f'' if no file is selected.
          Free with `g-free'


     Since 2.4


 -- Function: gtk-file-chooser-set-uri (self `<gtk-file-chooser>')
          (uri `mchars') =>  (ret `bool')
 -- Method: set-uri
     Sets the file referred to by URI as the current file for the file
     chooser, by changing to the URI's parent folder and actually
     selecting the URI in the list. If the CHOOSER is
     `<gtk-file-chooser-action-save>' mode, the URI's base name will
     also appear in the dialog's file name entry.

     If the URI isn't in the current folder of CHOOSER, then the
     current folder of CHOOSER will be changed to the folder containing
     URI. This is equivalent to a sequence of
     `gtk-file-chooser-unselect-all' followed by
     `gtk-file-chooser-select-uri'.

     Note that the URI must exist, or nothing will be done except for
     the directory change. If you are implementing a should use this
     function if you already have a file name to which the user may
     save; for example, when the user opens an existing file and then
     does (guimenuitem "File/Save As...") on it. If you don't have a
     file name already &#x2014; for example, if the user just created a
     new file and is saving it for the first time, do not call this
     function. Instead, use something similar to this:


          if (document_is_new)
            {
              /* the user just created a new document */
              gtk_file_chooser_set_current_folder_uri (chooser, default_folder_for_saving);
              gtk_file_chooser_set_current_name (chooser, "Untitled document");
            }
          else
            {
              /* the user edited an existing document */
              gtk_file_chooser_set_uri (chooser, existing_uri);
            }

    CHOOSER
          a `<gtk-file-chooser>'

    URI
          the URI to set as current

    RET
          ``#t'' if both the folder could be changed and the URI was
          selected successfully, ``#f'' otherwise.


     Since 2.4


 -- Function: gtk-file-chooser-select-uri (self `<gtk-file-chooser>')
          (uri `mchars') =>  (ret `bool')
 -- Method: select-uri
     Selects the file to by URI. If the URI doesn't refer to a file in
     the current folder of CHOOSER, then the current folder of CHOOSER
     will be changed to the folder containing FILENAME.

    CHOOSER
          a `<gtk-file-chooser>'

    URI
          the URI to select

    RET
          ``#t'' if both the folder could be changed and the URI was
          selected successfully, ``#f'' otherwise.


     Since 2.4


 -- Function: gtk-file-chooser-unselect-uri (self `<gtk-file-chooser>')
          (uri `mchars')
 -- Method: unselect-uri
     Unselects the file referred to by URI. If the file is not in the
     current directory, does not exist, or is otherwise not currently
     selected, does nothing.

    CHOOSER
          a `<gtk-file-chooser>'

    URI
          the URI to unselect


     Since 2.4


 -- Function: gtk-file-chooser-get-uris (self `<gtk-file-chooser>') => 
          (ret `gslist-of')
 -- Method: get-uris
     Lists all the selected files and subfolders in the current folder
     of CHOOSER. The returned names are full absolute URIs.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          a `<gs-list>' containing the URIs of all selected files and
          subfolders in the current folder. Free the returned list with
          `g-slist-free', and the filenames with `g-free'.


     Since 2.4


 -- Function: gtk-file-chooser-set-preview-widget
          (self `<gtk-file-chooser>') (preview_widget `<gtk-widget>')
 -- Method: set-preview-widget
     Sets an application-supplied widget to use to display a custom
     preview of the currently selected file. To implement a preview,
     after setting the preview widget, you connect to the
     ::update-preview signal, and call
     `gtk-file-chooser-get-preview-filename' or
     `gtk-file-chooser-get-preview-uri' on each change. If you can
     display a preview of the new file, update your widget and set the
     preview active using `gtk-file-chooser-set-preview-widget-active'.
     Otherwise, set the preview inactive.

     When there is no application-supplied preview widget, or the
     application-supplied preview widget is not active, the file
     chooser may display an internally generated preview of the current
     file or it may display no preview at all.

    CHOOSER
          a `<gtk-file-chooser>'

    PREVIEW-WIDGET
          widget for displaying preview.


     Since 2.4


 -- Function: gtk-file-chooser-get-preview-widget
          (self `<gtk-file-chooser>') =>  (ret `<gtk-widget>')
 -- Method: get-preview-widget
     Gets the current preview widget; see
     `gtk-file-chooser-set-preview-widget'.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          the current preview widget, or ``#f''


     Since 2.4


 -- Function: gtk-file-chooser-get-preview-uri
          (self `<gtk-file-chooser>') =>  (ret `mchars')
 -- Method: get-preview-uri
     Gets the URI that should be previewed in a custom preview widget.
     See `gtk-file-chooser-set-preview-widget'.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          the URI for the file to preview, or ``#f'' if no file is
          selected.  Free with `g-free'.


     Since 2.4


 -- Function: gtk-file-chooser-set-extra-widget
          (self `<gtk-file-chooser>') (extra_widget `<gtk-widget>')
 -- Method: set-extra-widget
     Sets an application-supplied widget to provide extra options to
     the user.

    CHOOSER
          a `<gtk-file-chooser>'

    EXTRA-WIDGET
          widget for extra options


     Since 2.4


 -- Function: gtk-file-chooser-get-extra-widget
          (self `<gtk-file-chooser>') =>  (ret `<gtk-widget>')
 -- Method: get-extra-widget
     Gets the current preview widget; see
     `gtk-file-chooser-set-extra-widget'.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          the current extra widget, or ``#f''


     Since 2.4


 -- Function: gtk-file-chooser-add-filter (self `<gtk-file-chooser>')
          (filter `<gtk-file-filter>')
 -- Method: add-filter
     Adds FILTER to the list of filters that the user can select
     between. When a filter is selected, only files that are passed by
     that filter are displayed.

     Note that the CHOOSER takes ownership of the filter, so you have
     to ref and sink it if you want to keep a reference.

    CHOOSER
          a `<gtk-file-chooser>'

    FILTER
          a `<gtk-file-filter>'


     Since 2.4


 -- Function: gtk-file-chooser-remove-filter
          (self `<gtk-file-chooser>') (filter `<gtk-file-filter>')
 -- Method: remove-filter
     Removes FILTER from the list of filters that the user can select
     between.

    CHOOSER
          a `<gtk-file-chooser>'

    FILTER
          a `<gtk-file-filter>'


     Since 2.4


 -- Function: gtk-file-chooser-list-filters (self `<gtk-file-chooser>')
          =>  (ret `gslist-of')
 -- Method: list-filters
     Lists the current set of user-selectable filters; see
     `gtk-file-chooser-add-filter', `gtk-file-chooser-remove-filter'.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          a `<gs-list>' containing the current set of user selectable
          filters. The contents of the list are owned by GTK+, but you
          must free the list itself with `g-slist-free' when you are
          done with it.


     Since 2.4


 -- Function: gtk-file-chooser-set-filter (self `<gtk-file-chooser>')
          (filter `<gtk-file-filter>')
 -- Method: set-filter
     Sets the current filter; only the files that pass the filter will
     be displayed.  If the user-selectable list of filters is
     non-empty, then the filter should be one of the filters in that
     list. Setting the current filter when the list of filters is empty
     is useful if you want to restrict the displayed set of files
     without letting the user change it.

    CHOOSER
          a `<gtk-file-chooser>'

    FILTER
          a `<gtk-file-filter>'


     Since 2.4


 -- Function: gtk-file-chooser-get-filter (self `<gtk-file-chooser>')
          =>  (ret `<gtk-file-filter>')
 -- Method: get-filter
     Gets the current filter; see `gtk-file-chooser-set-filter'.

    CHOOSER
          a `<gtk-file-chooser>'

    RET
          the current filter, or ``#f''


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkFileChooserButton,  Next: GtkFileChooserDialog,  Prev: GtkFileChooser,  Up: Top

82 GtkFileChooserButton
***********************

A button to launch a file selection dialog

82.1 Overview
=============

The `<gtk-file-chooser-button>' is a widget that lets the user select a
file. It implements the `<gtk-file-chooser>' interface. Visually, it is
a file name with a button to bring up a `<gtk-file-chooser-dialog>'.
The user can then use that dialog to change the file associated with
that button. This widget does not support setting the "select-multiple"
property to ``#t''.


     {
       GtkWidget *button;

       button = gtk_file_chooser_button_new (_("Select a file"),
                                             GTK_FILE_CHOOSER_ACTION_OPEN);
       gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (button),
                                            "/etc");
     }

   The `<gtk-file-chooser-button>' supports the
`<gtk-file-chooser-action>'s `GTK_FILE_CHOOSER_ACTION_OPEN' and
`GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER'.

   The `<gtk-file-chooser-button>' will ellipsize the label, and thus
will thus request little horizontal space. To give the button more
space, you should call `gtk-widget-size-request',
`gtk-file-chooser-button-set-width-chars', or pack the button in such a
way that other interface elements give space to the widget.

82.2 Usage
==========

 -- Class: <gtk-file-chooser-button>
     Derives from `<gtk-file-chooser>', `<gtk-hbox>'.

     This class defines the following properties:

    `dialog'
          The file chooser dialog to use.

    `focus-on-click'
          Whether the button grabs focus when it is clicked with the
          mouse

    `title'
          The title of the file chooser dialog.

    `width-chars'
          The desired width of the button widget, in characters.



 -- Signal on <gtk-file-chooser-button>: file-set
     undocumented

 -- Function: gtk-file-chooser-button-new (title `mchars')
          (action `<gtk-file-chooser-action>') =>  (ret `<gtk-widget>')
     Creates a new file-selecting button widget.

    TITLE
          the title of the browse dialog.

    ACTION
          the open mode for the widget.

    RET
          a new button widget.


     Since 2.6


 -- Function: gtk-file-chooser-button-get-title
          (self `<gtk-file-chooser-button>') =>  (ret `mchars')
 -- Method: get-title
     Retrieves the title of the browse dialog used by BUTTON. The
     returned value should not be modified or freed.

    BUTTON
          the button widget to examine.

    RET
          a pointer to the browse dialog's title.


     Since 2.6


 -- Function: gtk-file-chooser-button-set-title
          (self `<gtk-file-chooser-button>') (title `mchars')
 -- Method: set-title
     Modifies the TITLE of the browse dialog used by BUTTON.

    BUTTON
          the button widget to modify.

    TITLE
          the new browse dialog title.


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkFileChooserDialog,  Next: GtkFileChooserWidget,  Prev: GtkFileChooserButton,  Up: Top

83 GtkFileChooserDialog
***********************

A file chooser dialog, suitable for "File/Open" or "File/Save" commands

83.1 Overview
=============

`<gtk-file-chooser-dialog>' is a dialog box suitable for use with
"File/Open" or "File/Save as" commands. This widget works by putting a
`<gtk-file-chooser-widget>' inside a `<gtk-dialog>'. It exposes the
`<gtk-file-chooser-iface>' interface, so you can use all of the
`<gtk-file-chooser>' functions on the file chooser dialog as well as
those for `<gtk-dialog>'.

   Note that `<gtk-file-chooser-dialog>' does not have any methods of
its own.  Instead, you should use the functions that work on a
`<gtk-file-chooser>'.

   In the simplest of cases, you can the following code to use
`<gtk-file-chooser-dialog>' to select a file for opening:


     GtkWidget *dialog;

     dialog = gtk_file_chooser_dialog_new ("Open File",
     				      parent_window,
     				      GTK_FILE_CHOOSER_ACTION_OPEN,
     				      GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
     				      GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
     				      NULL);

     if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
       {
         char *filename;

         filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
         open_file (filename);
         g_free (filename);
       }

     gtk_widget_destroy (dialog);

   To use a dialog for saving, you can use this:


     GtkWidget *dialog;

     dialog = gtk_file_chooser_dialog_new ("Save File",
     				      parent_window,
     				      GTK_FILE_CHOOSER_ACTION_SAVE,
     				      GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
     				      GTK_STOCK_SAVE, GTK_RESPONSE_ACCEPT,
     				      NULL);
     gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);

     if (user_edited_a_new_document)
       {
         gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (dialog), default_folder_for_saving);
         gtk_file_chooser_set_current_name (GTK_FILE_CHOOSER (dialog), "Untitled document");
       }
     else
       gtk_file_chooser_set_filename (GTK_FILE_CHOOSER (dialog), filename_for_existing_document);


     if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
       {
         char *filename;

         filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
         save_to_file (filename);
         g_free (filename);
       }

     gtk_widget_destroy (dialog);

   `<gtk-file-chooser-dialog>' inherits from `<gtk-dialog>', so buttons
that go in its action area have response codes such as
`<gtk-response-accept>' and `<gtk-response-cancel>'. For example, you
could call `gtk-file-chooser-dialog-new' as follows:


     GtkWidget *dialog;

     dialog = gtk_file_chooser_dialog_new ("Open File",
     				      parent_window,
     				      GTK_FILE_CHOOSER_ACTION_OPEN,
     				      GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
     				      GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
     				      NULL);

   This will create buttons for "Cancel" and "Open" that use stock
response identifiers from `<gtk-response-type>'. For most dialog boxes
you can use your own custom response codes rather than the ones in
`<gtk-response-type>', but `<gtk-file-chooser-dialog>' assumes that its
"accept"-type action, e.g. an "Open" or "Save" button, _will_ have one
of the following response codes:

   This is because `<gtk-file-chooser-dialog>' must intercept responses
and switch to folders if appropriate, rather than letting the dialog
terminate &#x2014; the implementation uses these known response codes
to know which responses can be blocked if appropriate.

   To summarize, make sure you use a stock response code when you use
`<gtk-file-chooser-dialog>' to ensure proper operation.

83.2 Usage
==========

 -- Class: <gtk-file-chooser-dialog>
     Derives from `<gtk-file-chooser>', `<gtk-dialog>'.

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



File: guile-gnome-gtk.info,  Node: GtkFileChooserWidget,  Next: GtkFileFilter,  Prev: GtkFileChooserDialog,  Up: Top

84 GtkFileChooserWidget
***********************

File chooser widget that can be embedded in other widgets

84.1 Overview
=============

`<gtk-file-chooser-widget>' is a widget suitable for selecting files.
It is the main building block of a `<gtk-file-chooser-dialog>'. Most
applications will only need to use the latter; you can use
`<gtk-file-chooser-widget>' as part of a larger window if you have
special needs.

   Note that `<gtk-file-chooser-widget>' does not have any methods of
its own.  Instead, you should use the functions that work on a
`<gtk-file-chooser>'.

84.2 Usage
==========

 -- Class: <gtk-file-chooser-widget>
     Derives from `<gtk-file-chooser>', `<gtk-file-chooser-embed>',
     `<gtk-vbox>'.

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


 -- Function: gtk-file-chooser-widget-new
          (action `<gtk-file-chooser-action>') =>  (ret `<gtk-widget>')
     Creates a new `<gtk-file-chooser-widget>'. This is a file chooser
     widget that can be embedded in custom windows, and it is the same
     widget that is used by `<gtk-file-chooser-dialog>'.

    ACTION
          Open or save mode for the widget

    RET
          a new `<gtk-file-chooser-widget>'


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkFileFilter,  Next: GtkFontButton,  Prev: GtkFileChooserWidget,  Up: Top

85 GtkFileFilter
****************

A filter for selecting a file subset

85.1 Overview
=============

A GtkFileFilter can be used to restrict the files being shown in a
`<gtk-file-chooser>'. Files can be filtered based on their name (with
`gtk-file-filter-add-pattern'), on their mime type (with
`gtk-file-filter-add-mime-type'), or by a custom filter function (with
`gtk-file-filter-add-custom').

   Filtering by mime types handles aliasing and subclassing of mime
types; e.g. a filter for text/plain also matches a file with mime type
application/rtf, since application/rtf is a subclass of text/plain.
Note that `<gtk-file-filter>' allows wildcards for the subtype of a
mime type, so you can e.g. filter for image/*.

   Normally, filters are used by adding them to a `<gtk-file-chooser>',
see `gtk-file-chooser-add-filter', but it is also possible to manually
use a filter on a file with `gtk-file-filter-filter'.

85.2 Usage
==========

 -- Class: <gtk-file-filter>
     Derives from `<gtk-object>'.

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


 -- Function: gtk-file-filter-new =>  (ret `<gtk-file-filter>')
     Creates a new `<gtk-file-filter>' with no rules added to it. Such
     a filter doesn't accept any files, so is not particularly useful
     until you add rules with `gtk-file-filter-add-mime-type',
     `gtk-file-filter-add-pattern', or `gtk-file-filter-add-custom'. To
     create a filter that accepts any file, use:


          GtkFileFilter *filter = gtk_file_filter_new ();
          gtk_file_filter_add_pattern (filter, "*");

    RET
          a new `<gtk-file-filter>'


     Since 2.4


 -- Function: gtk-file-filter-set-name (self `<gtk-file-filter>')
          (name `mchars')
 -- Method: set-name
     Sets the human-readable name of the filter; this is the string
     that will be displayed in the file selector user interface if
     there is a selectable list of filters.

    FILTER
          a `<gtk-file-filter>'

    NAME
          the human-readable-name for the filter, or ``#f'' to remove
          any existing name.


     Since 2.4


 -- Function: gtk-file-filter-get-name (self `<gtk-file-filter>') => 
          (ret `mchars')
 -- Method: get-name
     Gets the human-readable name for the filter. See
     `gtk-file-filter-set-name'.

    FILTER
          a `<gtk-file-filter>'

    RET
          The human-readable name of the filter, or ``#f''. This value
          is owned by GTK+ and must not be modified or freed.


     Since 2.4


 -- Function: gtk-file-filter-add-mime-type (self `<gtk-file-filter>')
          (mime_type `mchars')
 -- Method: add-mime-type
     Adds a rule allowing a given mime type to FILTER.

    FILTER
          A `<gtk-file-filter>'

    MIME-TYPE
          name of a MIME type


     Since 2.4


 -- Function: gtk-file-filter-add-pattern (self `<gtk-file-filter>')
          (pattern `mchars')
 -- Method: add-pattern
     Adds a rule allowing a shell style glob to a filter.

    FILTER
          a `<gtk-file-filter>'

    PATTERN
          a shell style glob


     Since 2.4


 -- Function: gtk-file-filter-add-pixbuf-formats
          (self `<gtk-file-filter>')
 -- Method: add-pixbuf-formats
     Adds a rule allowing image files in the formats supported by
     GdkPixbuf.

    FILTER
          a `<gtk-file-filter>'


     Since 2.6


 -- Function: gtk-file-filter-get-needed (self `<gtk-file-filter>') => 
          (ret `<gtk-file-filter-flags>')
 -- Method: get-needed
     Gets the fields that need to be filled in for the structure passed
     to `gtk-file-filter-filter'

     This function will not typically be used by applications; it is
     intended principally for use in the implementation of
     `<gtk-file-chooser>'.

    FILTER
          a `<gtk-file-filter>'

    RET
          bitfield of flags indicating needed fields when calling
          `gtk-file-filter-filter'


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkFontButton,  Next: GtkFontSelection,  Prev: GtkFileFilter,  Up: Top

86 GtkFontButton
****************

A button to launch a font selection dialog

86.1 Overview
=============

The `<gtk-font-button>' is a button which displays the currently
selected font an allows to open a font selection dialog to change the
font. It is suitable widget for selecting a font in a preference dialog.

86.2 Usage
==========

 -- Class: <gtk-font-button>
     Derives from `<gtk-button>'.

     This class defines the following properties:

    `title'
          The title of the font selection dialog

    `font-name'
          The name of the selected font

    `use-font'
          Whether the label is drawn in the selected font

    `use-size'
          Whether the label is drawn with the selected font size

    `show-style'
          Whether the selected font style is shown in the label

    `show-size'
          Whether selected font size is shown in the label



 -- Signal on <gtk-font-button>: font-set
     The ::font-set signal is emitted when the user selects a font.
     When handling this signal, use `gtk-font-button-get-font-name' to
     find out which font was just selected.

     Note that this signal is only emitted when the _user_ changes the
     font. If you need to react to programmatic font changes as well,
     use the notify::font-name signal.

     Since 2.4


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

    RET
          a new font picker widget.


     Since 2.4


 -- Function: gtk-font-button-new-with-font (fontname `mchars') => 
          (ret `<gtk-widget>')
     Creates a new font picker widget.

    FONTNAME
          Name of font to display in font selection dialog

    RET
          a new font picker widget.


     Since 2.4


 -- Function: gtk-font-button-set-font-name (self `<gtk-font-button>')
          (fontname `mchars') =>  (ret `bool')
 -- Method: set-font-name
     Sets or updates the currently-displayed font in font picker dialog.

    FONT-BUTTON
          a `<gtk-font-button>'

    FONTNAME
          Name of font to display in font selection dialog

    RET
          Return value of `gtk-font-selection-dialog-set-font-name' if
          the font selection dialog exists, otherwise ``#f''.


     Since 2.4


 -- Function: gtk-font-button-get-font-name (self `<gtk-font-button>')
          =>  (ret `mchars')
 -- Method: get-font-name
     Retrieves the name of the currently selected font.

    FONT-BUTTON
          a `<gtk-font-button>'

    RET
          an internal copy of the font name which must not be freed.


     Since 2.4


 -- Function: gtk-font-button-set-show-style (self `<gtk-font-button>')
          (show_style `bool')
 -- Method: set-show-style
     If SHOW-STYLE is ``#t'', the font style will be displayed along
     with name of the selected font.

    FONT-BUTTON
          a `<gtk-font-button>'

    SHOW-STYLE
          ``#t'' if font style should be displayed in label.


     Since 2.4


 -- Function: gtk-font-button-get-show-style (self `<gtk-font-button>')
          =>  (ret `bool')
 -- Method: get-show-style
     Returns whether the name of the font style will be shown in the
     label.

    FONT-BUTTON
          a `<gtk-font-button>'

    RET
          whether the font style will be shown in the label.


     Since 2.4


 -- Function: gtk-font-button-set-show-size (self `<gtk-font-button>')
          (show_size `bool')
 -- Method: set-show-size
     If SHOW-SIZE is ``#t'', the font size will be displayed along with
     the name of the selected font.

    FONT-BUTTON
          a `<gtk-font-button>'

    SHOW-SIZE
          ``#t'' if font size should be displayed in dialog.


     Since 2.4


 -- Function: gtk-font-button-get-show-size (self `<gtk-font-button>')
          =>  (ret `bool')
 -- Method: get-show-size
     Returns whether the font size will be shown in the label.

    FONT-BUTTON
          a `<gtk-font-button>'

    RET
          whether the font size will be shown in the label.


     Since 2.4


 -- Function: gtk-font-button-set-use-font (self `<gtk-font-button>')
          (use_font `bool')
 -- Method: set-use-font
     If USE-FONT is ``#t'', the font name will be written using the
     selected font.

    FONT-BUTTON
          a `<gtk-font-button>'

    USE-FONT
          If ``#t'', font name will be written using font chosen.


     Since 2.4


 -- Function: gtk-font-button-get-use-font (self `<gtk-font-button>')
          =>  (ret `bool')
 -- Method: get-use-font
     Returns whether the selected font is used in the label.

    FONT-BUTTON
          a `<gtk-font-button>'

    RET
          whether the selected font is used in the label.


     Since 2.4


 -- Function: gtk-font-button-set-use-size (self `<gtk-font-button>')
          (use_size `bool')
 -- Method: set-use-size
     If USE-SIZE is ``#t'', the font name will be written using the
     selected size.

    FONT-BUTTON
          a `<gtk-font-button>'

    USE-SIZE
          If ``#t'', font name will be written using the selected size.


     Since 2.4


 -- Function: gtk-font-button-get-use-size (self `<gtk-font-button>')
          =>  (ret `bool')
 -- Method: get-use-size
     Returns whether the selected size is used in the label.

    FONT-BUTTON
          a `<gtk-font-button>'

    RET
          whether the selected size is used in the label.


     Since 2.4


 -- Function: gtk-font-button-set-title (self `<gtk-font-button>')
          (title `mchars')
 -- Method: set-title
     Sets the title for the font selection dialog.

    FONT-BUTTON
          a `<gtk-font-button>'

    TITLE
          a string containing the font selection dialog title


     Since 2.4


 -- Function: gtk-font-button-get-title (self `<gtk-font-button>') => 
          (ret `mchars')
 -- Method: get-title
     Retrieves the title of the font selection dialog.

    FONT-BUTTON
          a `<gtk-font-button>'

    RET
          an internal copy of the title string which must not be freed.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkFontSelection,  Next: GtkFontSelectionDialog,  Prev: GtkFontButton,  Up: Top

87 GtkFontSelection
*******************

A widget for selecting fonts

87.1 Overview
=============

The `<gtk-font-selection>' widget lists the available fonts, styles and
sizes, allowing the user to select a font. It is used in the
`<gtk-font-selection-dialog>' widget to provide a dialog box for
selecting fonts.

   To set the font which is initially selected, use
`gtk-font-selection-set-font-name'.

   To get the selected font use `gtk-font-selection-get-font-name'.

   To change the text which is shown in the preview area, use
`gtk-font-selection-set-preview-text'.

87.2 Usage
==========

 -- Class: <gtk-font-selection>
     Derives from `<gtk-vbox>'.

     This class defines the following properties:

    `font-name'
          The X string that represents this font

    `font'
          The GdkFont that is currently selected

    `preview-text'
          The text to display in order to demonstrate the selected font



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

    RET
          a new `<gtk-font-selection>'.



 -- Function: gtk-font-selection-get-font-name
          (self `<gtk-font-selection>') =>  (ret `mchars')
 -- Method: get-font-name
     Gets the currently-selected font name. Note that this can be a
     different string than what you set with
     `gtk-font-selection-set-font-name', as the font selection widget
     may normalize font names and thus return a string with a different
     structure. For example, "Helvetica Italic Bold 12" could be
     normalized to "Helvetica Bold Italic 12". Use
     `pango-font-description-equal' if you want to compare two font
     descriptions.

    FONTSEL
          a `<gtk-font-selection>'

    RET
          A string with the name of the current font, or ``#f'' if no
          font is selected. You must free this string with `g-free'.



 -- Function: gtk-font-selection-set-font-name
          (self `<gtk-font-selection>') (fontname `mchars') => 
          (ret `bool')
 -- Method: set-font-name
     Sets the currently-selected font. Note that the FONTSEL needs to
     know the screen in which it will appear for this to work; this can
     be guaranteed by simply making sure that the FONTSEL is inserted
     in a toplevel window before you call this function.

    FONTSEL
          a `<gtk-font-selection>'

    FONTNAME
          a font name like "Helvetica 12" or "Times Bold 18"

    RET
          ``#t'' if the font could be set successfully; ``#f'' if no
          such font exists or if the FONTSEL doesn't belong to a
          particular screen yet.



 -- Function: gtk-font-selection-get-preview-text
          (self `<gtk-font-selection>') =>  (ret `mchars')
 -- Method: get-preview-text
     Gets the text displayed in the preview area.

    FONTSEL
          a `<gtk-font-selection>'.

    RET
          the text displayed in the preview area. This string is owned
          by the widget and should not be modified or freed.



 -- Function: gtk-font-selection-set-preview-text
          (self `<gtk-font-selection>') (text `mchars')
 -- Method: set-preview-text
     Sets the text displayed in the preview area.

    FONTSEL
          a `<gtk-font-selection>'.

    TEXT
          the text to display in the preview area.




File: guile-gnome-gtk.info,  Node: GtkFontSelectionDialog,  Next: GtkInputDialog,  Prev: GtkFontSelection,  Up: Top

88 GtkFontSelectionDialog
*************************

A dialog box for selecting fonts

88.1 Overview
=============

The `<gtk-font-selection-dialog>' widget is a dialog box for selecting a
font.

   To set the font which is initially selected, use
`gtk-font-selection-dialog-set-font-name'.

   To get the selected font use
`gtk-font-selection-dialog-get-font-name'.

   To change the text which is shown in the preview area, use
`gtk-font-selection-dialog-set-preview-text'.

88.2 Usage
==========

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

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


 -- Function: gtk-font-selection-dialog-new (title `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-font-selection-dialog>'.

    TITLE
          the title of the dialog box.

    RET
          a new `<gtk-font-selection-dialog>'.




File: guile-gnome-gtk.info,  Node: GtkInputDialog,  Next: GtkAlignment,  Prev: GtkFontSelectionDialog,  Up: Top

89 GtkInputDialog
*****************

Configure devices for the XInput extension

89.1 Overview
=============

NOTE this widget is considered too specialized/little-used for GTK+,
and will in the future be moved to some other package. If your
application needs this widget, feel free to use it, as the widget does
work and is useful in some applications; it's just not of general
interest. However, we are not accepting new features for the widget,
and it will eventually move out of the GTK+ distribution.

   `<gtk-input-dialog>' displays a dialog which allows the user to
configure XInput extension devices. For each device, they can control
the mode of the device (disabled, screen-relative, or window-relative),
the mapping of axes to coordinates, and the mapping of the devices
macro keys to key press events.

   `<gtk-input-dialog>' contains two buttons to which the application
can connect; one for closing the dialog, and one for saving the
changes. No actions are bound to these by default. The changes that the
user makes take effect immediately.

89.2 Usage
==========

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

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


 -- Signal on <gtk-input-dialog>: enable-device (arg0 `<gdk-device>')
     This signal is emitted when the user changes the mode of a device
     from `<gdk-mode-disabled>' to a `<gdk-mode-screen>' or
     `<gdk-mode-window>'.


 -- Signal on <gtk-input-dialog>: disable-device (arg0 `<gdk-device>')
     This signal is emitted when the user changes the mode of a device
     from a `<gdk-mode-screen>' or `<gdk-mode-window>' to
     `<gdk-mode-enabled>'.


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

    RET
          the new `<gtk-input-dialog>'.




File: guile-gnome-gtk.info,  Node: GtkAlignment,  Next: GtkAspectFrame,  Prev: GtkInputDialog,  Up: Top

90 GtkAlignment
***************

A widget which controls the alignment and size of its child

90.1 Overview
=============

The `<gtk-alignment>' widget controls the alignment and size of its
child widget. It has four settings: xscale, yscale, xalign, and yalign.

   The scale settings are used to specify how much the child widget
should expand to fill the space allocated to the `<gtk-alignment>'. The
values can range from 0 (meaning the child doesn't expand at all) to 1
(meaning the child expands to fill all of the available space).

   The align settings are used to place the child widget within the
available area.  The values range from 0 (top or left) to 1 (bottom or
right). Of course, if the scale settings are both set to 1, the
alignment settings have no effect.

90.2 Usage
==========

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

     This class defines the following properties:

    `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

    `xscale'
          If available horizontal space is bigger than needed for the
          child, how much of it to use for the child. 0.0 means none,
          1.0 means all

    `yscale'
          If available vertical space is bigger than needed for the
          child, how much of it to use for the child. 0.0 means none,
          1.0 means all

    `top-padding'
          The padding to insert at the top of the widget.

    `bottom-padding'
          The padding to insert at the bottom of the widget.

    `left-padding'
          The padding to insert at the left of the widget.

    `right-padding'
          The padding to insert at the right of the widget.



 -- Function: gtk-alignment-new (xalign `float') (yalign `float')
          (xscale `float') (yscale `float') =>  (ret `<gtk-widget>')
     Creates a new `<gtk-alignment>'.

    XALIGN
          the horizontal alignment of the child widget, from 0 (left)
          to 1 (right).

    YALIGN
          the vertical alignment of the child widget, from 0 (top) to 1
          (bottom).

    XSCALE
          the amount that the child widget expands horizontally to fill
          up unused space, from 0 to 1. A value of 0 indicates that the
          child widget should never expand. A value of 1 indicates that
          the child widget will expand to fill all of the space
          allocated for the `<gtk-alignment>'.

    YSCALE
          the amount that the child widget expands vertically to fill
          up unused space, from 0 to 1. The values are similar to
          XSCALE.

    RET
          the new `<gtk-alignment>'.



 -- Function: gtk-alignment-set (self `<gtk-alignment>')
          (xalign `float') (yalign `float') (xscale `float')
          (yscale `float')
 -- Method: set
     Sets the `<gtk-alignment>' values.

    ALIGNMENT
          a `<gtk-alignment>'.

    XALIGN
          the horizontal alignment of the child widget, from 0 (left)
          to 1 (right).

    YALIGN
          the vertical alignment of the child widget, from 0 (top) to 1
          (bottom).

    XSCALE
          the amount that the child widget expands horizontally to fill
          up unused space, from 0 to 1. A value of 0 indicates that the
          child widget should never expand. A value of 1 indicates that
          the child widget will expand to fill all of the space
          allocated for the `<gtk-alignment>'.

    YSCALE
          the amount that the child widget expands vertically to fill
          up unused space, from 0 to 1. The values are similar to
          XSCALE.



 -- Function: gtk-alignment-get-padding (self `<gtk-alignment>') => 
          (padding_top `unsigned-int') (padding_bottom `unsigned-int')
          (padding_left `unsigned-int') (padding_right `unsigned-int')
 -- Method: get-padding
     Gets the padding on the different sides of the widget. See
     `gtk-alignment-set-padding'.

    ALIGNMENT
          a `<gtk-alignment>'

    PADDING-TOP
          location to store the padding for the top of the widget, or
          ``#f''

    PADDING-BOTTOM
          location to store the padding for the bottom of the widget,
          or ``#f''

    PADDING-LEFT
          location to store the padding for the left of the widget, or
          ``#f''

    PADDING-RIGHT
          location to store the padding for the right of the widget, or
          ``#f''


     Since 2.4


 -- Function: gtk-alignment-set-padding (self `<gtk-alignment>')
          (padding_top `unsigned-int') (padding_bottom `unsigned-int')
          (padding_left `unsigned-int') (padding_right `unsigned-int')
 -- Method: set-padding
     Sets the padding on the different sides of the widget. The padding
     adds blank space to the sides of the widget. For instance, this
     can be used to indent the child widget towards the right by adding
     padding on the left.

    ALIGNMENT
          a `<gtk-alignment>'

    PADDING-TOP
          the padding at the top of the widget

    PADDING-BOTTOM
          the padding at the bottom of the widget

    PADDING-LEFT
          the padding at the left of the widget

    PADDING-RIGHT
          the padding at the right of the widget.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkAspectFrame,  Next: GtkHBox,  Prev: GtkAlignment,  Up: Top

91 GtkAspectFrame
*****************

A frame that constrains its child to a particular aspect ratio

91.1 Overview
=============

The `<gtk-aspect-frame>' is useful when you want pack a widget so that
it can resize but always retains the same aspect ratio. For instance,
one might be drawing a small preview of a larger image.
`<gtk-aspect-frame>' derives from `<gtk-frame>', so it can draw a label
and a frame around the child.  The frame will be "shrink-wrapped" to
the size of the child.

91.2 Usage
==========

 -- Class: <gtk-aspect-frame>
     Derives from `<gtk-frame>'.

     This class defines the following properties:

    `xalign'
          X alignment of the child

    `yalign'
          Y alignment of the child

    `ratio'
          Aspect ratio if obey_child is FALSE

    `obey-child'
          Force aspect ratio to match that of the frame's child



 -- Function: gtk-aspect-frame-new (label `mchars') (xalign `float')
          (yalign `float') (ratio `float') (obey_child `bool') => 
          (ret `<gtk-widget>')
     Create a new `<gtk-aspect-frame>'.

    LABEL
          Label text.

    XALIGN
          Horizontal alignment of the child within the allocation of the
          `<gtk-aspect-frame>'. This ranges from 0.0 (left aligned) to
          1.0 (right aligned)

    YALIGN
          Vertical alignment of the child within the allocation of the
          `<gtk-aspect-frame>'. This ranges from 0.0 (left aligned) to
          1.0 (right aligned)

    RATIO
          The desired aspect ratio.

    OBEY-CHILD
          If ``#t'', RATIO is ignored, and the aspect ratio is taken
          from the requistion of the child.

    RET
          the new `<gtk-aspect-frame>'.



 -- Function: gtk-aspect-frame-set (self `<gtk-aspect-frame>')
          (xalign `float') (yalign `float') (ratio `float')
          (obey_child `bool')
 -- Method: set
     Set parameters for an existing `<gtk-aspect-frame>'.

    ASPECT-FRAME
          a `<gtk-aspect-frame>'

    XALIGN
          Horizontal alignment of the child within the allocation of the
          `<gtk-aspect-frame>'. This ranges from 0.0 (left aligned) to
          1.0 (right aligned)

    YALIGN
          Vertical alignment of the child within the allocation of the
          `<gtk-aspect-frame>'. This ranges from 0.0 (left aligned) to
          1.0 (right aligned)

    RATIO
          The desired aspect ratio.

    OBEY-CHILD
          If ``#t'', RATIO is ignored, and the aspect ratio is taken
          from the requistion of the child.




File: guile-gnome-gtk.info,  Node: GtkHBox,  Next: GtkVBox,  Prev: GtkAspectFrame,  Up: Top

92 GtkHBox
**********

A horizontal container box

92.1 Overview
=============

GtkHBox is a container that organizes child widgets into a single row.

   Use the `<gtk-box>' packing interface to determine the arrangement,
spacing, width, and alignment of GtkHBox children.

   All children are allocated the same height.

92.2 Usage
==========

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

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


 -- Function: gtk-hbox-new (homogeneous `bool') (spacing `int') => 
          (ret `<gtk-widget>')
     Creates a new GtkHBox.

    HOMOGENEOUS
          ``#t'' if all children are to be given equal space allotments.

    SPACING
          the number of pixels to place by default between children.

    RET
          a new GtkHBox.




File: guile-gnome-gtk.info,  Node: GtkVBox,  Next: GtkHButtonBox,  Prev: GtkHBox,  Up: Top

93 GtkVBox
**********

A vertical container box

93.1 Overview
=============

GtkVBox is a container that organizes child widgets into a single
column.

   Use the `<gtk-box>' packing interface to determine the arrangement,
spacing, height, and alignment of GtkVBox children.

   All children are allocated the same width.

93.2 Usage
==========

 -- Class: <gtk-vbox>
     Derives from `<gtk-box>'.

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


 -- Function: gtk-vbox-new (homogeneous `bool') (spacing `int') => 
          (ret `<gtk-widget>')
     Creates a new GtkVBox.

    HOMOGENEOUS
          ``#t'' if all children are to be given equal space allotments.

    SPACING
          the number of pixels to place by default between children.

    RET
          a new GtkVBox.




File: guile-gnome-gtk.info,  Node: GtkHButtonBox,  Next: GtkVButtonBox,  Prev: GtkVBox,  Up: Top

94 GtkHButtonBox
****************

A container for arranging buttons horizontally

94.1 Overview
=============

A button box should be used to provide a consistent layout of buttons
throughout your application. The layout/spacing can be altered by the
programmer, or if desired, by the user to alter the 'feel' of a program
to a small degree.

   A `<gtk-hbutton-box>' is created with `gtk-hbutton-box-new'. Buttons
are packed into a button box the same way widgets are added to any other
container, using `gtk-container-add'. You can also use
`gtk-box-pack-start' or `gtk-box-pack-end', but for button boxes both
these functions work just like `gtk-container-add', ie., they pack the
button in a way that depends on the current layout style and on whether
the button has had `gtk-button-box-set-child-secondary' called on it.

   The spacing between buttons can be set with `gtk-box-set-spacing'.
The arrangement and layout of the buttons can be changed with
`gtk-button-box-set-layout'.

94.2 Usage
==========

 -- Class: <gtk-hbutton-box>
     Derives from `<gtk-button-box>'.

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


 -- Function: gtk-hbutton-box-new =>  (ret `<gtk-widget>')
     Creates a new horizontal button box.

    RET
          a new button box `<gtk-widget>'.




File: guile-gnome-gtk.info,  Node: GtkVButtonBox,  Next: GtkFixed,  Prev: GtkHButtonBox,  Up: Top

95 GtkVButtonBox
****************

A container for arranging buttons vertically

95.1 Overview
=============

A button box should be used to provide a consistent layout of buttons
throughout your application. The layout/spacing can be altered by the
programmer, or if desired, by the user to alter the 'feel' of a program
to a small degree.

   A `<gtk-vbutton-box>' is created with `gtk-vbutton-box-new'. Buttons
are packed into a button box the same way widgets are added to any other
container, using `gtk-container-add'. You can also use
`gtk-box-pack-start' or `gtk-box-pack-end', but for button boxes both
these functions work just like `gtk-container-add', ie., they pack the
button in a way that depends on the current layout style and on whether
the button has had `gtk-button-box-set-child-secondary' called on it.

   The spacing between buttons can be set with `gtk-box-set-spacing'.
The arrangement and layout of the buttons can be changed with
`gtk-button-box-set-layout'.

95.2 Usage
==========

 -- Class: <gtk-vbutton-box>
     Derives from `<gtk-button-box>'.

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


 -- Function: gtk-vbutton-box-new =>  (ret `<gtk-widget>')
     Creates a new vertical button box.

    RET
          a new button box `<gtk-widget>'.




File: guile-gnome-gtk.info,  Node: GtkFixed,  Next: GtkHPaned,  Prev: GtkVButtonBox,  Up: Top

96 GtkFixed
***********

A container which allows you to position widgets at fixed coordinates

96.1 Overview
=============

The `<gtk-fixed>' widget is a container which can place child widgets at
fixed positions and with fixed sizes, given in pixels. `<gtk-fixed>'
performs no automatic layout management.

   For most applications, you should not use this container! It keeps
you from having to learn about the other GTK+ containers, but it
results in broken applications. With `<gtk-fixed>', the following
things will result in truncated text, overlapping widgets, and other
display bugs:

   Themes, which may change widget sizes.

   Fonts other than the one you used to write the app will of course
change the size of widgets containing text; keep in mind that users may
use a larger font because of difficulty reading the default, or they
may be using Windows or the framebuffer port of GTK+, where different
fonts are available.

   Translation of text into other languages changes its size. Also,
display of non-English text will use a different font in many cases.

   In addition, the fixed widget can't properly be mirrored in
right-to-left languages such as Hebrew and Arabic. i.e. normally GTK+
will flip the interface to put labels to the right of the thing they
label, but it can't do that with `<gtk-fixed>'. So your application
will not be usable in right-to-left languages.

   Finally, fixed positioning makes it kind of annoying to add/remove
GUI elements, since you have to reposition all the other elements. This
is a long-term maintenance problem for your application.

   If you know none of these things are an issue for your application,
and prefer the simplicity of `<gtk-fixed>', by all means use the
widget. But you should be aware of the tradeoffs.

96.2 Usage
==========

 -- Class: <gtk-fixed>
     Derives from `<gtk-container>'.

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


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

    RET
          a new `<gtk-fixed>'.



 -- Function: gtk-fixed-put (self `<gtk-fixed>')
          (widget `<gtk-widget>') (x `int') (y `int')
 -- Method: put
     Adds a widget to a `<gtk-fixed>' container at the given position.

    FIXED
          a `<gtk-fixed>'.

    WIDGET
          the widget to add.

    X
          the horizontal position to place the widget at.

    Y
          the vertical position to place the widget at.



 -- Function: gtk-fixed-move (self `<gtk-fixed>')
          (widget `<gtk-widget>') (x `int') (y `int')
 -- Method: move
     Moves a child of a `<gtk-fixed>' container to the given position.

    FIXED
          a `<gtk-fixed>'.

    WIDGET
          the child widget.

    X
          the horizontal position to move the widget to.

    Y
          the vertical position to move the widget to.



 -- Function: gtk-fixed-get-has-window (self `<gtk-fixed>') => 
          (ret `bool')
 -- Method: get-has-window
     Gets whether the `<gtk-fixed>' has its own `<gdk-window>'. See
     `gdk-fixed-set-has-window'.

    FIXED
          a `<gtk-widget>'

    RET
          ``#t'' if FIXED has its own window.



 -- Function: gtk-fixed-set-has-window (self `<gtk-fixed>')
          (has_window `bool')
 -- Method: set-has-window
     Sets whether a `<gtk-fixed>' widget is created with a separate
     `<gdk-window>' for WIDGET->WINDOW or not. (By default, it will be
     created with no separate `<gdk-window>'). This function must be
     called while the `<gtk-fixed>' is not realized, for instance,
     immediately after the window is created.

     This function was added to provide an easy migration path for
     older applications which may expect `<gtk-fixed>' to have a
     separate window.

    FIXED
          a `<gtk-fixed>'

    HAS-WINDOW
          ``#t'' if a separate window should be created




File: guile-gnome-gtk.info,  Node: GtkHPaned,  Next: GtkVPaned,  Prev: GtkFixed,  Up: Top

97 GtkHPaned
************

A container with two panes arranged horizontally

97.1 Overview
=============

The HPaned widget is a container widget with two children arranged
horizontally.  The division between the two panes is adjustable by the
user by dragging a handle. See `<gtk-paned>' for details.

97.2 Usage
==========

 -- Class: <gtk-hpaned>
     Derives from `<gtk-paned>'.

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


 -- Function: gtk-hpaned-new =>  (ret `<gtk-widget>')
     Create a new `<gtk-hpaned>'

    RET
          the new `<gtk-hpaned>'




File: guile-gnome-gtk.info,  Node: GtkVPaned,  Next: GtkLayout,  Prev: GtkHPaned,  Up: Top

98 GtkVPaned
************

A container with two panes arranged vertically

98.1 Overview
=============

The VPaned widget is a container widget with two children arranged
vertically.  The division between the two panes is adjustable by the
user by dragging a handle. See `<gtk-paned>' for details.

98.2 Usage
==========

 -- Class: <gtk-vpaned>
     Derives from `<gtk-paned>'.

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


 -- Function: gtk-vpaned-new =>  (ret `<gtk-widget>')
     Create a new `<gtk-vpaned>'

    RET
          the new `<gtk-vpaned>'




File: guile-gnome-gtk.info,  Node: GtkLayout,  Next: GtkNotebook,  Prev: GtkVPaned,  Up: Top

99 GtkLayout
************

Infinite scrollable area containing child widgets and/or custom drawing

99.1 Overview
=============

`<gtk-layout>' is similar to `<gtk-drawing-area>' in that it's a "blank
slate" and doesn't do anything but paint a blank background by default.
It's different in that it supports scrolling natively (you can add it
to a `<gtk-scrolled-window>'), and it can contain child widgets, since
it's a `<gtk-container>'. However if you're just going to draw, a
`<gtk-drawing-area>' is a better choice since it has lower overhead.

   When handling expose events on a `<gtk-layout>', you must draw to
GTK_LAYOUT (layout)->bin_window, rather than to GTK_WIDGET
(layout)->window, as you would for a drawing area.

99.2 Usage
==========

 -- Class: <gtk-layout>
     Derives from `<gtk-container>'.

     This class defines the following properties:

    `hadjustment'
          The GtkAdjustment for the horizontal position

    `vadjustment'
          The GtkAdjustment for the vertical position

    `width'
          The width of the layout

    `height'
          The height of the layout



 -- Signal on <gtk-layout>: set-scroll-adjustments
          (arg0 `<gtk-adjustment>') (arg1 `<gtk-adjustment>')

 -- Function: gtk-layout-new (hadjustment `<gtk-adjustment>')
          (vadjustment `<gtk-adjustment>') =>  (ret `<gtk-widget>')
     Creates a new `<gtk-layout>'. Unless you have a specific
     adjustment you'd like the layout to use for scrolling, pass ``#f''
     for HADJUSTMENT and VADJUSTMENT.

    HADJUSTMENT
          horizontal scroll adjustment, or ``#f''

    VADJUSTMENT
          vertical scroll adjustment, or ``#f''

    RET
          a new `<gtk-layout>'



 -- Function: gtk-layout-put (self `<gtk-layout>')
          (child_widget `<gtk-widget>') (x `int') (y `int')
 -- Method: put
     Adds CHILD-WIDGET to LAYOUT, at position (X,Y).  LAYOUT becomes
     the new parent container of CHILD-WIDGET.

    LAYOUT
          a `<gtk-layout>'

    CHILD-WIDGET
          child widget

    X
          X position of child widget

    Y
          Y position of child widget



 -- Function: gtk-layout-move (self `<gtk-layout>')
          (child_widget `<gtk-widget>') (x `int') (y `int')
 -- Method: move
     Moves a current child of LAYOUT to a new position.

    LAYOUT
          a `<gtk-layout>'

    CHILD-WIDGET
          a current child of LAYOUT

    X
          X position to move to

    Y
          Y position to move to



 -- Function: gtk-layout-set-size (self `<gtk-layout>')
          (width `unsigned-int') (height `unsigned-int')
 -- Method: set-size
     Sets the size of the scrollable area of the layout.

    LAYOUT
          a `<gtk-layout>'

    WIDTH
          width of entire scrollable area

    HEIGHT
          height of entire scrollable area



 -- Function: gtk-layout-get-size (self `<gtk-layout>') => 
          (width `unsigned-int') (height `unsigned-int')
 -- Method: get-size
     Gets the size that has been set on the layout, and that determines
     the total extents of the layout's scrollbar area. See
     `gtk-layout-set-size'.

    LAYOUT
          a `<gtk-layout>'

    WIDTH
          location to store the width set on LAYOUT, or ``#f''

    HEIGHT
          location to store the height set on LAYOUT, or ``#f''



 -- Function: gtk-layout-get-hadjustment (self `<gtk-layout>') => 
          (ret `<gtk-adjustment>')
 -- Method: get-hadjustment
     This function should only be called after the layout has been
     placed in a `<gtk-scrolled-window>' or otherwise configured for
     scrolling. It returns the `<gtk-adjustment>' used for
     communication between the horizontal scrollbar and LAYOUT.

     See `<gtk-scrolled-window>', `<gtk-scrollbar>', `<gtk-adjustment>'
     for details.

    LAYOUT
          a `<gtk-layout>'

    RET
          horizontal scroll adjustment



 -- Function: gtk-layout-get-vadjustment (self `<gtk-layout>') => 
          (ret `<gtk-adjustment>')
 -- Method: get-vadjustment
     This function should only be called after the layout has been
     placed in a `<gtk-scrolled-window>' or otherwise configured for
     scrolling. It returns the `<gtk-adjustment>' used for
     communication between the vertical scrollbar and LAYOUT.

     See `<gtk-scrolled-window>', `<gtk-scrollbar>', `<gtk-adjustment>'
     for details.

    LAYOUT
          a `<gtk-layout>'

    RET
          vertical scroll adjustment



 -- Function: gtk-layout-set-hadjustment (self `<gtk-layout>')
          (adjustment `<gtk-adjustment>')
 -- Method: set-hadjustment
     Sets the horizontal scroll adjustment for the layout.

     See `<gtk-scrolled-window>', `<gtk-scrollbar>', `<gtk-adjustment>'
     for details.

    LAYOUT
          a `<gtk-layout>'

    ADJUSTMENT
          new scroll adjustment



 -- Function: gtk-layout-set-vadjustment (self `<gtk-layout>')
          (adjustment `<gtk-adjustment>')
 -- Method: set-vadjustment
     Sets the vertical scroll adjustment for the layout.

     See `<gtk-scrolled-window>', `<gtk-scrollbar>', `<gtk-adjustment>'
     for details.

    LAYOUT
          a `<gtk-layout>'

    ADJUSTMENT
          new scroll adjustment




File: guile-gnome-gtk.info,  Node: GtkNotebook,  Next: GtkTable,  Prev: GtkLayout,  Up: Top

100 GtkNotebook
***************

A tabbed notebook container

100.1 Overview
==============

The `<gtk-notebook>' widget is a `<gtk-container>' whose children are
pages that can be switched between using tab labels along one edge.

   There are many configuration options for `<gtk-notebook>'. Among
other things, you can choose on which edge the tabs appear (see
`gtk-notebook-set-tab-pos'), whether, if there are too many tabs to fit
the noteobook should be made bigger or scrolling arrows added (see
gtk_notebook_set_scrollable), and whether there will be a popup menu
allowing the users to switch pages. (see `gtk-notebook-enable-popup',
`gtk-noteobook-disable-popup')

100.2 Usage
===========

 -- Class: <gtk-notebook>
     Derives from `<gtk-container>'.

     This class defines the following properties:

    `tab-pos'
          Which side of the notebook holds the tabs

    `show-tabs'
          Whether tabs should be shown or not

    `show-border'
          Whether the border should be shown or not

    `scrollable'
          If TRUE, scroll arrows are added if there are too many tabs
          to fit

    `tab-border'
          Width of the border around the tab labels

    `tab-hborder'
          Width of the horizontal border of tab labels

    `tab-vborder'
          Width of the vertical border of tab labels

    `page'
          The index of the current page

    `enable-popup'
          If TRUE, pressing the right mouse button on the notebook pops
          up a menu that you can use to go to a page

    `group-id'
          Group ID for tabs drag and drop

    `group'
          Group for tabs drag and drop

    `homogeneous'
          Whether tabs should have homogeneous sizes



 -- Signal on <gtk-notebook>: switch-page (arg0 `<gpointer>')
          (arg1 `<guint>')
     Emitted when the user or a function changes the current page.


 -- Signal on <gtk-notebook>: focus-tab (arg0 `<gtk-notebook-tab>')
          => `<gboolean>'

 -- Signal on <gtk-notebook>: select-page (arg0 `<gboolean>')
          => `<gboolean>'

 -- Signal on <gtk-notebook>: change-current-page (arg0 `<gint>')
          => `<gboolean>'

 -- Signal on <gtk-notebook>: move-focus-out
          (arg0 `<gtk-direction-type>')

 -- Signal on <gtk-notebook>: reorder-tab (arg0 `<gtk-direction-type>')
          (arg1 `<gboolean>') => `<gboolean>'

 -- Signal on <gtk-notebook>: page-reordered (arg0 `<gtk-widget>')
          (arg1 `<guint>')
     the ::page-reordered signal is emitted in the notebook right after
     a page has been reordered.

     Since 2.10


 -- Signal on <gtk-notebook>: page-removed (arg0 `<gtk-widget>')
          (arg1 `<guint>')
     the ::page-removed signal is emitted in the notebook right after a
     page is removed from the notebook.

     Since 2.10


 -- Signal on <gtk-notebook>: page-added (arg0 `<gtk-widget>')
          (arg1 `<guint>')
     the ::page-added signal is emitted in the notebook right after a
     page is added to the notebook.

     Since 2.10


 -- Signal on <gtk-notebook>: create-window (arg0 `<gtk-widget>')
          (arg1 `<gint>') (arg2 `<gint>') => `<gtk-notebook>'
     undocumented

 -- Function: gtk-notebook-new =>  (ret `<gtk-widget>')
     Creates a new `<gtk-notebook>' widget with no pages.

    RET
          the newly created `<gtk-notebook>'



 -- Function: gtk-notebook-append-page (self `<gtk-notebook>')
          (child `<gtk-widget>') (tab_label `<gtk-widget>') => 
          (ret `int')
 -- Method: append-page
     Appends a page to NOTEBOOK.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the `<gtk-widget>' to use as the contents of the page.

    TAB-LABEL
          the `<gtk-widget>' to be used as the label for the page, or
          ``#f'' to use the default label, 'page N'.

    RET
          the index (starting from 0) of the appended page in the
          notebook, or -1 if function fails



 -- Function: gtk-notebook-append-page-menu (self `<gtk-notebook>')
          (child `<gtk-widget>') (tab_label `<gtk-widget>')
          (menu_label `<gtk-widget>') =>  (ret `int')
 -- Method: append-page-menu
     Appends a page to NOTEBOOK, specifying the widget to use as the
     label in the popup menu.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the `<gtk-widget>' to use as the contents of the page.

    TAB-LABEL
          the `<gtk-widget>' to be used as the label for the page, or
          ``#f'' to use the default label, 'page N'.

    MENU-LABEL
          the widget to use as a label for the page-switch menu, if
          that is enabled. If ``#f'', and TAB-LABEL is a `<gtk-label>'
          or ``#f'', then the menu label will be a newly created label
          with the same text as TAB-LABEL; If TAB-LABEL is not a
          `<gtk-label>', MENU-LABEL must be specified if the
          page-switch menu is to be used.

    RET
          the index (starting from 0) of the appended page in the
          notebook, or -1 if function fails



 -- Function: gtk-notebook-prepend-page (self `<gtk-notebook>')
          (child `<gtk-widget>') (tab_label `<gtk-widget>') => 
          (ret `int')
 -- Method: prepend-page
     Prepends a page to NOTEBOOK.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the `<gtk-widget>' to use as the contents of the page.

    TAB-LABEL
          the `<gtk-widget>' to be used as the label for the page, or
          ``#f'' to use the default label, 'page N'.

    RET
          the index (starting from 0) of the prepended page in the
          notebook, or -1 if function fails



 -- Function: gtk-notebook-prepend-page-menu (self `<gtk-notebook>')
          (child `<gtk-widget>') (tab_label `<gtk-widget>')
          (menu_label `<gtk-widget>') =>  (ret `int')
 -- Method: prepend-page-menu
     Prepends a page to NOTEBOOK, specifying the widget to use as the
     label in the popup menu.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the `<gtk-widget>' to use as the contents of the page.

    TAB-LABEL
          the `<gtk-widget>' to be used as the label for the page, or
          ``#f'' to use the default label, 'page N'.

    MENU-LABEL
          the widget to use as a label for the page-switch menu, if
          that is enabled. If ``#f'', and TAB-LABEL is a `<gtk-label>'
          or ``#f'', then the menu label will be a newly created label
          with the same text as TAB-LABEL; If TAB-LABEL is not a
          `<gtk-label>', MENU-LABEL must be specified if the
          page-switch menu is to be used.

    RET
          the index (starting from 0) of the prepended page in the
          notebook, or -1 if function fails



 -- Function: gtk-notebook-insert-page (self `<gtk-notebook>')
          (child `<gtk-widget>') (tab_label `<gtk-widget>')
          (position `int') =>  (ret `int')
 -- Method: insert-page
     Insert a page into NOTEBOOK at the given position.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the `<gtk-widget>' to use as the contents of the page.

    TAB-LABEL
          the `<gtk-widget>' to be used as the label for the page, or
          ``#f'' to use the default label, 'page N'.

    POSITION
          the index (starting at 0) at which to insert the page, or -1
          to append the page after all other pages.

    RET
          the index (starting from 0) of the inserted page in the
          notebook, or -1 if function fails



 -- Function: gtk-notebook-insert-page-menu (self `<gtk-notebook>')
          (child `<gtk-widget>') (tab_label `<gtk-widget>')
          (menu_label `<gtk-widget>') (position `int') =>  (ret `int')
 -- Method: insert-page-menu
     Insert a page into NOTEBOOK at the given position, specifying the
     widget to use as the label in the popup menu.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the `<gtk-widget>' to use as the contents of the page.

    TAB-LABEL
          the `<gtk-widget>' to be used as the label for the page, or
          ``#f'' to use the default label, 'page N'.

    MENU-LABEL
          the widget to use as a label for the page-switch menu, if
          that is enabled. If ``#f'', and TAB-LABEL is a `<gtk-label>'
          or ``#f'', then the menu label will be a newly created label
          with the same text as TAB-LABEL; If TAB-LABEL is not a
          `<gtk-label>', MENU-LABEL must be specified if the
          page-switch menu is to be used.

    POSITION
          the index (starting at 0) at which to insert the page, or -1
          to append the page after all other pages.

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



 -- Function: gtk-notebook-remove-page (self `<gtk-notebook>')
          (page_num `int')
 -- Method: remove-page
     Removes a page from the notebook given its index in the notebook.

    NOTEBOOK
          a `<gtk-notebook>'.

    PAGE-NUM
          the index of a notebook page, starting from 0. If -1, the
          last page will be removed.



 -- Function: gtk-notebook-page-num (self `<gtk-notebook>')
          (child `<gtk-widget>') =>  (ret `int')
 -- Method: page-num
     Finds the index of the page which contains the given child widget.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          a `<gtk-widget>'

    RET
          the index of the page containing CHILD, or -1 if CHILD is not
          in the notebook.



 -- Function: gtk-notebook-next-page (self `<gtk-notebook>')
 -- Method: next-page
     Switches to the next page. Nothing happens if the current page is
     the last page.

    NOTEBOOK
          a `<gtk-notebook>'



 -- Function: gtk-notebook-prev-page (self `<gtk-notebook>')
 -- Method: prev-page
     Switches to the previous page. Nothing happens if the current page
     is the first page.

    NOTEBOOK
          a `<gtk-notebook>'



 -- Function: gtk-notebook-reorder-child (self `<gtk-notebook>')
          (child `<gtk-widget>') (position `int')
 -- Method: reorder-child
     Reorders the page containing CHILD, so that it appears in position
     POSITION. If POSITION is greater than or equal to the number of
     children in the list or negative, CHILD will be moved to the end
     of the list.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the child to move

    POSITION
          the new position, or -1 to move to the end



 -- Function: gtk-notebook-set-tab-pos (self `<gtk-notebook>')
          (pos `<gtk-position-type>')
 -- Method: set-tab-pos
     Sets the edge at which the tabs for switching pages in the
     notebook are drawn.

    NOTEBOOK
          a `<gtk-notebook>'.

    POS
          the edge to draw the tabs at.



 -- Function: gtk-notebook-set-show-tabs (self `<gtk-notebook>')
          (show_tabs `bool')
 -- Method: set-show-tabs
     Sets whether to show the tabs for the notebook or not.

    NOTEBOOK
          a `<gtk-notebook>'

    SHOW-TABS
          ``#t'' if the tabs should be shown.



 -- Function: gtk-notebook-set-show-border (self `<gtk-notebook>')
          (show_border `bool')
 -- Method: set-show-border
     Sets whether a bevel will be drawn around the notebook pages. This
     only has a visual effect when the tabs are not shown. See
     `gtk-notebook-set-show-tabs'.

    NOTEBOOK
          a `<gtk-notebook>'

    SHOW-BORDER
          ``#t'' if a bevel should be drawn around the notebook.



 -- Function: gtk-notebook-set-scrollable (self `<gtk-notebook>')
          (scrollable `bool')
 -- Method: set-scrollable
     Sets whether the tab label area will have arrows for scrolling if
     there are too many tabs to fit in the area.

    NOTEBOOK
          a `<gtk-notebook>'

    SCROLLABLE
          ``#t'' if scroll arrows should be added



 -- Function: gtk-notebook-popup-enable (self `<gtk-notebook>')
 -- Method: popup-enable
     Enables the popup menu: if the user clicks with the right mouse
     button on the bookmarks, a menu with all the pages will be popped
     up.

    NOTEBOOK
          a `<gtk-notebook>'



 -- Function: gtk-notebook-popup-disable (self `<gtk-notebook>')
 -- Method: popup-disable
     Disables the popup menu.

    NOTEBOOK
          a `<gtk-notebook>'



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

    NOTEBOOK
          a `<gtk-notebook>'

    RET
          the index (starting from 0) of the current page in the
          notebook. If the notebook has no pages, then -1 will be
          returned.



 -- Function: gtk-notebook-get-menu-label (self `<gtk-notebook>')
          (child `<gtk-widget>') =>  (ret `<gtk-widget>')
 -- Method: get-menu-label
     Retrieves the menu label widget of the page containing CHILD.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          a widget contained in a page of NOTEBOOK

    RET
          the menu label, or ``#f'' if the notebook page does not have
          a menu label other than the default (the tab label).



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

    NOTEBOOK
          a `<gtk-notebook>'

    PAGE-NUM
          the index of a page in the noteobok, or -1 to get the last
          page.

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



 -- Function: gtk-notebook-get-n-pages (self `<gtk-notebook>') => 
          (ret `int')
 -- Method: get-n-pages
     Gets the number of pages in a notebook.

    NOTEBOOK
          a `<gtk-notebook>'

    RET
          the number of pages in the notebook.


     Since 2.2


 -- Function: gtk-notebook-get-tab-label (self `<gtk-notebook>')
          (child `<gtk-widget>') =>  (ret `<gtk-widget>')
 -- Method: get-tab-label
     Returns the tab label widget for the page CHILD. ``#f'' is
     returned if CHILD is not in NOTEBOOK or if no tab label has
     specifically been set for CHILD.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the page

    RET
          the tab label



 -- Function: gtk-notebook-set-menu-label (self `<gtk-notebook>')
          (child `<gtk-widget>') (menu_label `<gtk-widget>')
 -- Method: set-menu-label
     Changes the menu label for the page containing CHILD.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the child widget

    MENU-LABEL
          the menu label, or NULL for default



 -- Function: gtk-notebook-set-menu-label-text (self `<gtk-notebook>')
          (child `<gtk-widget>') (menu_text `mchars')
 -- Method: set-menu-label-text
     Creates a new label and sets it as the menu label of CHILD.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the child widget

    MENU-TEXT
          the label text



 -- Function: gtk-notebook-set-tab-label (self `<gtk-notebook>')
          (child `<gtk-widget>') (tab_label `<gtk-widget>')
 -- Method: set-tab-label
     Changes the tab label for CHILD. If ``#f'' is specified for
     TAB-LABEL, then the page will have the label 'page N'.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the page

    TAB-LABEL
          the tab label widget to use, or ``#f'' for default tab label.



 -- Function: gtk-notebook-set-tab-label-packing
          (self `<gtk-notebook>') (child `<gtk-widget>')
          (expand `bool') (fill `bool') (pack_type `<gtk-pack-type>')
 -- Method: set-tab-label-packing
     Sets the packing parameters for the tab label of the page
     containing CHILD. See `gtk-box-pack-start' for the exact meaning
     of the parameters.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the child widget

    EXPAND
          whether to expand the bookmark or not

    FILL
          whether the bookmark should fill the allocated area or not

    PACK-TYPE
          the position of the bookmark



 -- Function: gtk-notebook-set-tab-label-text (self `<gtk-notebook>')
          (child `<gtk-widget>') (tab_text `mchars')
 -- Method: set-tab-label-text
     Creates a new label and sets it as the tab label for the page
     containing CHILD.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the page

    TAB-TEXT
          the label text



 -- Function: gtk-notebook-set-tab-reorderable (self `<gtk-notebook>')
          (child `<gtk-widget>') (reorderable `bool')
 -- Method: set-tab-reorderable
     Sets whether the notebook tab can be reordered via drag and drop
     or not.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          a child `<gtk-widget>'

    REORDERABLE
          whether the tab is reorderable or not.


     Since 2.10


 -- Function: gtk-notebook-set-tab-detachable (self `<gtk-notebook>')
          (child `<gtk-widget>') (detachable `bool')
 -- Method: set-tab-detachable
     Sets whether the tab can be detached from NOTEBOOK to another
     notebook or widget.

     Note that 2 notebooks must share a common group identificator (see
     `gtk-notebook-set-group-id') to allow automatic tabs interchange
     between them.

     If you want a widget to interact with a notebook through DnD
     (i.e.: accept dragged tabs from it) it must be set as a drop
     destination and accept the target "GTK_NOTEBOOK_TAB". The notebook
     will fill the selection with a GtkWidget** pointing to the child
     widget that corresponds to the dropped tab.


           static void
           on_drop_zone_drag_data_received (GtkWidget        *widget,
                                            GdkDragContext   *context,
                                            gint              x,
                                            gint              y,
                                            GtkSelectionData *selection_data,
                                            guint             info,
                                            guint             time,
                                            gpointer          user_data)
           {
             GtkWidget *notebook;
             GtkWidget **child;

             notebook = gtk_drag_get_source_widget (context);
             child = (void*) selection_data->data;

             process_widget (*child);
             gtk_container_remove (GTK_CONTAINER (notebook), *child);
           }

     If you want a notebook to accept drags from other widgets, you
     will have to set your own DnD code to do it.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          a child `<gtk-widget>'

    DETACHABLE
          whether the tab is detachable or not


     Since 2.10


 -- Function: gtk-notebook-get-menu-label-text (self `<gtk-notebook>')
          (child `<gtk-widget>') =>  (ret `mchars')
 -- Method: get-menu-label-text
     Retrieves the text of the menu label for the page containing CHILD.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          the child widget of a page of the notebook.

    RET
          value: the text of the tab label, or ``#f'' if the widget
          does not have a menu label other than the default menu label,
          or the menu label widget is not a `<gtk-label>'. The string
          is owned by the widget and must not be freed.



 -- Function: gtk-notebook-get-scrollable (self `<gtk-notebook>') => 
          (ret `bool')
 -- Method: get-scrollable
     Returns whether the tab label area has arrows for scrolling. See
     `gtk-notebook-set-scrollable'.

    NOTEBOOK
          a `<gtk-notebook>'

    RET
          ``#t'' if arrows for scrolling are present



 -- Function: gtk-notebook-get-show-border (self `<gtk-notebook>') => 
          (ret `bool')
 -- Method: get-show-border
     Returns whether a bevel will be drawn around the notebook pages.
     See `gtk-notebook-set-show-border'.

    NOTEBOOK
          a `<gtk-notebook>'

    RET
          ``#t'' if the bevel is drawn



 -- Function: gtk-notebook-get-show-tabs (self `<gtk-notebook>') => 
          (ret `bool')
 -- Method: get-show-tabs
     Returns whether the tabs of the notebook are shown. See
     `gtk-notebook-set-show-tabs'.

    NOTEBOOK
          a `<gtk-notebook>'

    RET
          ``#t'' if the tabs are shown



 -- Function: gtk-notebook-get-tab-label-text (self `<gtk-notebook>')
          (child `<gtk-widget>') =>  (ret `mchars')
 -- Method: get-tab-label-text
     Retrieves the text of the tab label for the page containing CHILD.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          a widget contained in a page of NOTEBOOK

    RET
          value: the text of the tab label, or ``#f'' if the tab label
          widget is not a `<gtk-label>'. The string is owned by the
          widget and must not be freed.



 -- Function: gtk-notebook-get-tab-pos (self `<gtk-notebook>') => 
          (ret `<gtk-position-type>')
 -- Method: get-tab-pos
     Gets the edge at which the tabs for switching pages in the
     notebook are drawn.

    NOTEBOOK
          a `<gtk-notebook>'

    RET
          the edge at which the tabs are drawn



 -- Function: gtk-notebook-get-tab-reorderable (self `<gtk-notebook>')
          (child `<gtk-widget>') =>  (ret `bool')
 -- Method: get-tab-reorderable
     Gets whether the tab can be reordered via drag and drop or not.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          a child `<gtk-widget>'

    RET
          ``#t'' if the tab is reorderable.


     Since 2.10


 -- Function: gtk-notebook-get-tab-detachable (self `<gtk-notebook>')
          (child `<gtk-widget>') =>  (ret `bool')
 -- Method: get-tab-detachable
     Returns whether the tab contents can be detached from NOTEBOOK.

    NOTEBOOK
          a `<gtk-notebook>'

    CHILD
          a child `<gtk-widget>'

    RET
          TRUE if the tab is detachable.


     Since 2.10


 -- Function: gtk-notebook-set-current-page (self `<gtk-notebook>')
          (page_num `int')
 -- Method: set-current-page
     Switches to the page number PAGE-NUM.

     Note that due to historical reasons, GtkNotebook refuses to switch
     to a page unless the child widget is visible. Therefore, it is
     recommended to show child widgets before adding them to a notebook.

    NOTEBOOK
          a `<gtk-notebook>'

    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 notebook, nothing will be done.



 -- Function: gtk-notebook-set-group-id (self `<gtk-notebook>')
          (group_id `int')
 -- Method: set-group-id
     Sets an group identificator for NOTEBOOK, notebooks sharing the
     same group identificator will be able to exchange tabs via drag
     and drop. A notebook with group identificator -1 will not be able
     to exchange tabs with any other notebook.

    NOTEBOOK
          a `<gtk-notebook>'

    GROUP-ID
          a group identificator, or -1 to unset it


     Since 2.10


 -- Function: gtk-notebook-get-group-id (self `<gtk-notebook>') => 
          (ret `int')
 -- Method: get-group-id
     Gets the current group identificator for NOTEBOOK.

    NOTEBOOK
          a `<gtk-notebook>'

    RET
          the group identificator, or -1 if none is set.


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkTable,  Next: GtkExpander,  Prev: GtkNotebook,  Up: Top

101 GtkTable
************

Pack widgets in regular patterns

101.1 Overview
==============

The `<gtk-table>' functions allow the programmer to arrange widgets in
rows and columns, making it easy to align many widgets next to each
other, horizontally and vertically.

   Tables are created with a call to `gtk-table-new', the size of which
can later be changed with `gtk-table-resize'.

   Widgets can be added to a table using `gtk-table-attach' or the more
convenient (but slightly less flexible) `gtk-table-attach-defaults'.

   To alter the space next to a specific row, use
`gtk-table-set-row-spacing', and for a column,
`gtk-table-set-col-spacing'.

   The gaps between _all_ rows or columns can be changed by calling
`gtk-table-set-row-spacings' or `gtk-table-set-col-spacings'
respectively.

   `gtk-table-set-homogeneous', can be used to set whether all cells in
the table will resize themselves to the size of the largest widget in
the table.

101.2 Usage
===========

 -- Class: <gtk-table>
     Derives from `<gtk-container>'.

     This class defines the following properties:

    `n-rows'
          The number of rows in the table

    `n-columns'
          The number of columns in the table

    `column-spacing'
          The amount of space between two consecutive columns

    `row-spacing'
          The amount of space between two consecutive rows

    `homogeneous'
          If TRUE, the table cells are all the same width/height



 -- Function: gtk-table-new (rows `unsigned-int')
          (columns `unsigned-int') (homogeneous `bool') => 
          (ret `<gtk-widget>')
     Used to create a new table widget. An initial size must be given
     by specifying how many rows and columns the table should have,
     although this can be changed later with `gtk-table-resize'. ROWS
     and COLUMNS must both be in the range 0 .. 65535.

    ROWS
          The number of rows the new table should have.

    COLUMNS
          The number of columns the new table should have.

    HOMOGENEOUS
          If set to ``#t'', all table cells are resized to the size of
          the cell containing the largest widget.

    RET
          A pointer to the the newly created table widget.



 -- Function: gtk-table-resize (self `<gtk-table>')
          (rows `unsigned-int') (columns `unsigned-int')
 -- Method: resize
     If you need to change a table's size _after_ it has been created,
     this function allows you to do so.

    TABLE
          The `<gtk-table>' you wish to change the size of.

    ROWS
          The new number of rows.

    COLUMNS
          The new number of columns.



 -- Function: gtk-table-attach (self `<gtk-table>')
          (child `<gtk-widget>') (left_attach `unsigned-int')
          (right_attach `unsigned-int') (top_attach `unsigned-int')
          (bottom_attach `unsigned-int')
          (xoptions `<gtk-attach-options>')
          (yoptions `<gtk-attach-options>') (xpadding `unsigned-int')
          (ypadding `unsigned-int')
 -- Method: attach
     Adds a widget to a table. The number of 'cells' that a widget will
     occupy is specified by LEFT-ATTACH, RIGHT-ATTACH, TOP-ATTACH and
     BOTTOM-ATTACH. These each represent the leftmost, rightmost,
     uppermost and lowest column and row numbers of the table. (Columns
     and rows are indexed from zero).

    TABLE
          The `<gtk-table>' to add a new widget to.

    CHILD
          The widget to add.

    LEFT-ATTACH
          the column number to attach the left side of a child widget
          to.

    RIGHT-ATTACH
          the column number to attach the right side of a child widget
          to.

    TOP-ATTACH
          the row number to attach the top of a child widget to.

    BOTTOM-ATTACH
          the row number to attach the bottom of a child widget to.

    XOPTIONS
          Used to specify the properties of the child widget when the
          table is resized.

    YOPTIONS
          The same as xoptions, except this field determines behaviour
          of vertical resizing.

    XPADDING
          An integer value specifying the padding on the left and right
          of the widget being added to the table.

    YPADDING
          The amount of padding above and below the child widget.



 -- Function: gtk-table-attach-defaults (self `<gtk-table>')
          (widget `<gtk-widget>') (left_attach `unsigned-int')
          (right_attach `unsigned-int') (top_attach `unsigned-int')
          (bottom_attach `unsigned-int')
 -- Method: attach-defaults
     As there are many options associated with `gtk-table-attach', this
     convenience function provides the programmer with a means to add
     children to a table with identical padding and expansion options.
     The values used for the `<gtk-attach-options>' are `GTK_EXPAND |
     GTK_FILL', and the padding is set to 0.

    TABLE
          The table to add a new child widget to.

    WIDGET
          The child widget to add.

    LEFT-ATTACH
          The column number to attach the left side of the child widget
          to.

    RIGHT-ATTACH
          The column number to attach the right side of the child
          widget to.

    TOP-ATTACH
          The row number to attach the top of the child widget to.

    BOTTOM-ATTACH
          The row number to attach the bottom of the child widget to.



 -- Function: gtk-table-set-row-spacing (self `<gtk-table>')
          (row `unsigned-int') (spacing `unsigned-int')
 -- Method: set-row-spacing
     Changes the space between a given table row and the subsequent row.

    TABLE
          a `<gtk-table>' containing the row whose properties you wish
          to change.

    ROW
          row number whose spacing will be changed.

    SPACING
          number of pixels that the spacing should take up.



 -- Function: gtk-table-set-col-spacing (self `<gtk-table>')
          (column `unsigned-int') (spacing `unsigned-int')
 -- Method: set-col-spacing
     Alters the amount of space between a given table column and the
     following column.

    TABLE
          a `<gtk-table>'.

    COLUMN
          the column whose spacing should be changed.

    SPACING
          number of pixels that the spacing should take up.



 -- Function: gtk-table-set-row-spacings (self `<gtk-table>')
          (spacing `unsigned-int')
 -- Method: set-row-spacings
     Sets the space between every row in TABLE equal to SPACING.

    TABLE
          a `<gtk-table>'.

    SPACING
          the number of pixels of space to place between every row in
          the table.



 -- Function: gtk-table-set-col-spacings (self `<gtk-table>')
          (spacing `unsigned-int')
 -- Method: set-col-spacings
     Sets the space between every column in TABLE equal to SPACING.

    TABLE
          a `<gtk-table>'.

    SPACING
          the number of pixels of space to place between every column
          in the table.



 -- Function: gtk-table-set-homogeneous (self `<gtk-table>')
          (homogeneous `bool')
 -- Method: set-homogeneous
     Changes the homogenous property of table cells, ie. whether all
     cells are an equal size or not.

    TABLE
          The `<gtk-table>' you wish to set the homogeneous properties
          of.

    HOMOGENEOUS
          Set to ``#t'' to ensure all table cells are the same size.
          Set to ``#f'' if this is not your desired behaviour.



 -- Function: gtk-table-get-default-row-spacing (self `<gtk-table>')
          =>  (ret `unsigned-int')
 -- Method: get-default-row-spacing
     Gets the default row spacing for the table. This is the spacing
     that will be used for newly added rows. (See
     `gtk-table-set-row-spacings')

    TABLE
          a `<gtk-table>'

    RET
          value: the default row spacing



 -- Function: gtk-table-get-homogeneous (self `<gtk-table>') => 
          (ret `bool')
 -- Method: get-homogeneous
     Returns whether the table cells are all constrained to the same
     width and height. (See `gtk-table-set-homogenous')

    TABLE
          a `<gtk-table>'

    RET
          ``#t'' if the cells are all constrained to the same size



 -- Function: gtk-table-get-row-spacing (self `<gtk-table>')
          (row `unsigned-int') =>  (ret `unsigned-int')
 -- Method: get-row-spacing
     Gets the amount of space between row ROW, and row ROW + 1. See
     `gtk-table-set-row-spacing'.

    TABLE
          a `<gtk-table>'

    ROW
          a row in the table, 0 indicates the first row

    RET
          the row spacing



 -- Function: gtk-table-get-col-spacing (self `<gtk-table>')
          (column `unsigned-int') =>  (ret `unsigned-int')
 -- Method: get-col-spacing
     Gets the amount of space between column COL, and column COL + 1.
     See `gtk-table-set-col-spacing'.

    TABLE
          a `<gtk-table>'

    COLUMN
          a column in the table, 0 indicates the first column

    RET
          the column spacing



 -- Function: gtk-table-get-default-col-spacing (self `<gtk-table>')
          =>  (ret `unsigned-int')
 -- Method: get-default-col-spacing
     Gets the default column spacing for the table. This is the spacing
     that will be used for newly added columns. (See
     `gtk-table-set-col-spacings')

    TABLE
          a `<gtk-table>'

    RET
          value: the default column spacing




File: guile-gnome-gtk.info,  Node: GtkExpander,  Next: GtkFrame,  Prev: GtkTable,  Up: Top

102 GtkExpander
***************

A container which can hide its child

102.1 Overview
==============

A `<gtk-expander>' allows the user to hide or show its child by
clicking on an expander triangle similar to the triangles used in a
`<gtk-tree-view>'.

   Normally you use an expander as you would use any other descendant of
`<gtk-bin>'; you create the child widget and use `gtk-container-add' to
add it to the expander. When the expander is toggled, it will take care
of showing and hiding the child automatically.

   There are situations in which you may prefer to show and hide the
expanded widget yourself, such as when you want to actually create the
widget at expansion time. In this case, create a `<gtk-expander>' but
do not add a child to it. The expander widget has an `expanded'
property which can be used to monitor its expansion state. You should
watch this property with a signal connection as follows:


     expander = gtk_expander_new_with_mnemonic ("_More Options");
     g_signal_connect (expander, "notify::expanded",
                       G_CALLBACK (expander_callback), NULL);

     ...

     static void
     expander_callback (GObject    *object,
                        GParamSpec *param_spec,
                        gpointer    user_data)
     {
       GtkExpander *expander;

       expander = GTK_EXPANDER (object);

       if (gtk_expander_get_expanded (expander))
         {
           /* Show or create widgets */
         }
       else
         {
           /* Hide or destroy widgets */
         }
     }

102.2 Usage
===========

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

     This class defines the following properties:

    `expanded'
          Whether the expander has been opened to reveal the child
          widget

    `label'
          Text of the expander's label

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

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

    `spacing'
          Space to put between the label and the child

    `label-widget'
          A widget to display in place of the usual expander label



 -- Signal on <gtk-expander>: activate

 -- Function: gtk-expander-new (label `mchars') =>  (ret `<gtk-widget>')
     Creates a new expander using LABEL as the text of the label.

    LABEL
          the text of the label

    RET
          a new `<gtk-expander>' widget.


     Since 2.4


 -- Function: gtk-expander-new-with-mnemonic (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new expander using LABEL as the text of the 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 label with an underscore in front of the
          mnemonic character

    RET
          a new `<gtk-expander>' widget.


     Since 2.4


 -- Function: gtk-expander-set-expanded (self `<gtk-expander>')
          (expanded `bool')
 -- Method: set-expanded
     Sets the state of the expander. Set to ``#t'', if you want the
     child widget to be revealed, and ``#f'' if you want the child
     widget to be hidden.

    EXPANDER
          a `<gtk-expander>'

    EXPANDED
          whether the child widget is revealed


     Since 2.4


 -- Function: gtk-expander-get-expanded (self `<gtk-expander>') => 
          (ret `bool')
 -- Method: get-expanded
     Queries a `<gtk-expander>' and returns its current state. Returns
     ``#t'' if the child widget is revealed.

     See `gtk-expander-set-expanded'.

    EXPANDER
          a `<gtk-expander>'

    RET
          the current state of the expander.


     Since 2.4


 -- Function: gtk-expander-set-spacing (self `<gtk-expander>')
          (spacing `int')
 -- Method: set-spacing
     Sets the spacing field of EXPANDER, which is the number of pixels
     to place between expander and the child.

    EXPANDER
          a `<gtk-expander>'

    SPACING
          distance between the expander and child in pixels.


     Since 2.4


 -- Function: gtk-expander-get-spacing (self `<gtk-expander>') => 
          (ret `int')
 -- Method: get-spacing
     Gets the value set by `gtk-expander-set-spacing'.

    EXPANDER
          a `<gtk-expander>'

    RET
          spacing between the expander and child.


     Since 2.4


 -- Function: gtk-expander-set-label (self `<gtk-expander>')
          (label `mchars')
 -- Method: set-label
     Sets the text of the label of the expander to LABEL.

     This will also clear any previously set labels.

    EXPANDER
          a `<gtk-expander>'

    LABEL
          a string


     Since 2.4


 -- Function: gtk-expander-get-label (self `<gtk-expander>') => 
          (ret `mchars')
 -- Method: get-label
     Fetches the text from the label of the expander, as set by
     `gtk-expander-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.

    EXPANDER
          a `<gtk-expander>'

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


     Since 2.4


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

    EXPANDER
          a `<gtk-expander>'

    USE-UNDERLINE
          ``#t'' if underlines in the text indicate mnemonics


     Since 2.4


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

    EXPANDER
          a `<gtk-expander>'

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


     Since 2.4


 -- Function: gtk-expander-set-use-markup (self `<gtk-expander>')
          (use_markup `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'.

    EXPANDER
          a `<gtk-expander>'

    USE-MARKUP
          ``#t'' if the label's text should be parsed for markup


     Since 2.4


 -- Function: gtk-expander-get-use-markup (self `<gtk-expander>') => 
          (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-expander-set-use-markup'.

    EXPANDER
          a `<gtk-expander>'

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


     Since 2.4


 -- Function: gtk-expander-set-label-widget (self `<gtk-expander>')
          (label_widget `<gtk-widget>')
 -- Method: set-label-widget
     Set the label widget for the expander. This is the widget that
     will appear embedded alongside the expander arrow.

    EXPANDER
          a `<gtk-expander>'

    LABEL-WIDGET
          the new label widget


     Since 2.4


 -- Function: gtk-expander-get-label-widget (self `<gtk-expander>') => 
          (ret `<gtk-widget>')
 -- Method: get-label-widget
     Retrieves the label widget for the frame. See
     `gtk-expander-set-label-widget'.

    EXPANDER
          a `<gtk-expander>'

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


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkFrame,  Next: GtkHSeparator,  Prev: GtkExpander,  Up: Top

103 GtkFrame
************

A bin with a decorative frame and optional label

103.1 Overview
==============

The frame widget is a Bin that surrounds its child with a decorative
frame and an optional label. If present, the label is drawn in a gap in
the top side of the frame. The position of the label can be controlled
with `gtk-frame-set-label-align'.

103.2 Usage
===========

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

     This class defines the following properties:

    `label'
          Text of the frame's label

    `label-xalign'
          The horizontal alignment of the label

    `label-yalign'
          The vertical alignment of the label

    `shadow'
          Deprecated property, use shadow_type instead

    `shadow-type'
          Appearance of the frame border

    `label-widget'
          A widget to display in place of the usual frame label



 -- Function: gtk-frame-new (label `mchars') =>  (ret `<gtk-widget>')
     Creates a new `<gtk-frame>', with optional label LABEL. If LABEL
     is ``#f'', the label is omitted.

    LABEL
          the text to use as the label of the frame

    RET
          a new `<gtk-frame>' widget



 -- Function: gtk-frame-set-label (self `<gtk-frame>') (label `mchars')
 -- Method: set-label
     Sets the text of the label. If LABEL is ``#f'', the current label
     is removed.

    FRAME
          a `<gtk-frame>'

    LABEL
          the text to use as the label of the frame



 -- Function: gtk-frame-set-label-widget (self `<gtk-frame>')
          (label_widget `<gtk-widget>')
 -- Method: set-label-widget
     Sets the label widget for the frame. This is the widget that will
     appear embedded in the top edge of the frame as a title.

    FRAME
          a `<gtk-frame>'

    LABEL-WIDGET
          the new label widget



 -- Function: gtk-frame-set-label-align (self `<gtk-frame>')
          (xalign `float') (yalign `float')
 -- Method: set-label-align
     Sets the alignment of the frame widget's label. The default values
     for a newly created frame are 0.0 and 0.5.

    FRAME
          a `<gtk-frame>'

    XALIGN
          The position of the label along the top edge of the widget. A
          value of 0.0 represents left alignment; 1.0 represents right
          alignment.

    YALIGN
          The y alignment of the label. A value of 0.0 aligns under the
          frame; 1.0 aligns above the frame.



 -- Function: gtk-frame-set-shadow-type (self `<gtk-frame>')
          (type `<gtk-shadow-type>')
 -- Method: set-shadow-type
     Sets the shadow type for FRAME.

    FRAME
          a `<gtk-frame>'

    TYPE
          the new `<gtk-shadow-type>'



 -- Function: gtk-frame-get-label (self `<gtk-frame>') => 
          (ret `mchars')
 -- Method: get-label
     If the frame's label widget is a `<gtk-label>', returns the text
     in the label widget. (The frame will have a `<gtk-label>' for the
     label widget if a non-``#f'' argument was passed to
     `gtk-frame-new'.)

    FRAME
          a `<gtk-frame>'

    RET
          the text in the label, or ``#f'' if there was no label widget
          or the lable widget was not a `<gtk-label>'. This string is
          owned by GTK+ and must not be modified or freed.



 -- Function: gtk-frame-get-label-align (self `<gtk-frame>') => 
          (xalign `float') (yalign `float')
 -- Method: get-label-align
     Retrieves the X and Y alignment of the frame's label. See
     `gtk-frame-set-label-align'.

    FRAME
          a `<gtk-frame>'

    XALIGN
          location to store X alignment of frame's label, or ``#f''

    YALIGN
          location to store X alignment of frame's label, or ``#f''



 -- Function: gtk-frame-get-label-widget (self `<gtk-frame>') => 
          (ret `<gtk-widget>')
 -- Method: get-label-widget
     Retrieves the label widget for the frame. See
     `gtk-frame-set-label-widget'.

    FRAME
          a `<gtk-frame>'

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



 -- Function: gtk-frame-get-shadow-type (self `<gtk-frame>') => 
          (ret `<gtk-shadow-type>')
 -- Method: get-shadow-type
     Retrieves the shadow type of the frame. See
     `gtk-frame-set-shadow-type'.

    FRAME
          a `<gtk-frame>'

    RET
          the current shadow type of the frame.




File: guile-gnome-gtk.info,  Node: GtkHSeparator,  Next: GtkVSeparator,  Prev: GtkFrame,  Up: Top

104 GtkHSeparator
*****************

A horizontal separator

104.1 Overview
==============

The `<gtk-hseparator>' widget is a horizontal separator, used to group
the widgets within a window. It displays a horizontal line with a
shadow to make it appear sunken into the interface.

   The `<gtk-hseparator>' widget is not used as a separator within
menus. To create a separator in a menu create an empty
`<gtk-separator-menu-item>' widget using `gtk-separator-menu-item-new'
and add it to the menu with `gtk-menu-shell-append'.

104.2 Usage
===========

 -- Class: <gtk-hseparator>
     Derives from `<gtk-separator>'.

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


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

    RET
          a new `<gtk-hseparator>'.




File: guile-gnome-gtk.info,  Node: GtkVSeparator,  Next: GtkHScrollbar,  Prev: GtkHSeparator,  Up: Top

105 GtkVSeparator
*****************

A vertical separator

105.1 Overview
==============

The `<gtk-vseparator>' widget is a vertical separator, used to group the
widgets within a window. It displays a vertical line with a shadow to
make it appear sunken into the interface.

105.2 Usage
===========

 -- Class: <gtk-vseparator>
     Derives from `<gtk-separator>'.

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


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

    RET
          a new `<gtk-vseparator>'.




File: guile-gnome-gtk.info,  Node: GtkHScrollbar,  Next: GtkVScrollbar,  Prev: GtkVSeparator,  Up: Top

106 GtkHScrollbar
*****************

A horizontal scrollbar

106.1 Overview
==============

The `<gtk-hscrollbar>' widget is a widget arranged horizontally
creating a scrollbar. See `<gtk-scrollbar>' for details on scrollbars.
`<gtk-adjustment>' pointers may be added to handle the adjustment of the
scrollbar or it may be left ``#f'' in which case one will be created
for you. See `<gtk-adjustment>' for details.

106.2 Usage
===========

 -- Class: <gtk-hscrollbar>
     Derives from `<gtk-scrollbar>'.

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


 -- Function: gtk-hscrollbar-new (adjustment `<gtk-adjustment>') => 
          (ret `<gtk-widget>')
     Creates a new horizontal scrollbar.

    ADJUSTMENT
          the `<gtk-adjustment>' to use, or ``#f'' to create a new
          adjustment.

    RET
          the new `<gtk-hscrollbar>'.




File: guile-gnome-gtk.info,  Node: GtkVScrollbar,  Next: GtkScrolledWindow,  Prev: GtkHScrollbar,  Up: Top

107 GtkVScrollbar
*****************

A vertical scrollbar

107.1 Overview
==============

The `<gtk-vscrollbar>' widget is a widget arranged vertically creating a
scrollbar. See `<gtk-scrollbar>' for details on scrollbars.
`<gtk-adjustment>' pointers may be added to handle the adjustment of the
scrollbar or it may be left ``#f'' in which case one will be created
for you. See `<gtk-adjustment>' for details.

107.2 Usage
===========

 -- Class: <gtk-vscrollbar>
     Derives from `<gtk-scrollbar>'.

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


 -- Function: gtk-vscrollbar-new (adjustment `<gtk-adjustment>') => 
          (ret `<gtk-widget>')
     Creates a new vertical scrollbar.

    ADJUSTMENT
          the `<gtk-adjustment>' to use, or ``#f'' to create a new
          adjustment.

    RET
          the new `<gtk-vscrollbar>'




File: guile-gnome-gtk.info,  Node: GtkScrolledWindow,  Next: GtkPrintOperation,  Prev: GtkVScrollbar,  Up: Top

108 GtkScrolledWindow
*********************

Adds scrollbars to its child widget

108.1 Overview
==============

`<gtk-scrolled-window>' is a `<gtk-bin>' subclass: it's a container the
accepts a single child widget. `<gtk-scrolled-window>' adds scrollbars
to the child widget and optionally draws a beveled frame around the
child widget.

   The scrolled window can work in two ways. Some widgets have native
scrolling support; these widgets have "slots" for `<gtk-adjustment>'
objects. Widgets with native scroll support include `<gtk-tree-view>',
`<gtk-text-view>', and `<gtk-layout>'.

   The scrolled window installs `<gtk-adjustment>' objects in the child
window's slots using the set_scroll_adjustments_signal, found in
`<gtk-widget-class>'. (Conceptually, these widgets implement a
"Scrollable" interface; because GTK+ 1.2 lacked interface support in
the object system, this interface is hackily implemented as a signal in
`<gtk-widget-class>'. The GTK+ 2.0 object system would allow a clean
implementation, but it wasn't worth breaking the API.)

   For widgets that lack native scrolling support, the `<gtk-viewport>'
widget acts as an adaptor class, implementing scrollability for child
widgets that lack their own scrolling capabilities. Use
`<gtk-viewport>' to scroll child widgets such as `<gtk-table>',
`<gtk-box>', and so on.

   If a widget has native scrolling abilities, it can be added to the
`<gtk-scrolled-window>' with `gtk-container-add'. If a widget does not,
you must first add the widget to a `<gtk-viewport>', then add the
`<gtk-viewport>' to the scrolled window. The convenience function
`gtk-scrolled-window-add-with-viewport' does exactly this, so you can
ignore the presence of the viewport.

   The position of the scrollbars is controlled by the scroll
adjustments. See `<gtk-adjustment>' for the fields in an adjustment -
for `<gtk-scrollbar>', used by `<gtk-scrolled-window>', the "value"
field represents the position of the scrollbar, which must be between
the "lower" field and "upper - page_size." The "page_size" field
represents the size of the visible scrollable area. The
"step_increment" and "page_increment" fields are used when the user
asks to step down (using the small stepper arrows) or page down (using
for example the PageDown key).

   If a `<gtk-scrolled-window>' doesn't behave quite as you would like,
or doesn't have exactly the right layout, it's very possible to set up
your own scrolling with `<gtk-scrollbar>' and for example a
`<gtk-table>'.

108.2 Usage
===========

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

     This class defines the following properties:

    `hadjustment'
          The GtkAdjustment for the horizontal position

    `vadjustment'
          The GtkAdjustment for the vertical position

    `hscrollbar-policy'
          When the horizontal scrollbar is displayed

    `vscrollbar-policy'
          When the vertical scrollbar is displayed

    `window-placement'
          Where the contents are located with respect to the
          scrollbars. This property only takes effect if
          "window-placement-set" is TRUE.

    `window-placement-set'
          Whether "window-placement" should be used to determine the
          location of the contents with respect to the scrollbars.

    `shadow-type'
          Style of bevel around the contents



 -- Signal on <gtk-scrolled-window>: move-focus-out
          (arg0 `<gtk-direction-type>')

 -- Signal on <gtk-scrolled-window>: scroll-child
          (arg0 `<gtk-scroll-type>') (arg1 `<gboolean>') => `<gboolean>'

 -- Function: gtk-scrolled-window-new (hadjustment `<gtk-adjustment>')
          (vadjustment `<gtk-adjustment>') =>  (ret `<gtk-widget>')
     Creates a new scrolled window. The two arguments are the scrolled
     window's adjustments; these will be shared with the scrollbars and
     the child widget to keep the bars in sync with the child. Usually
     you want to pass ``#f'' for the adjustments, which will cause the
     scrolled window to create them for you.

    HADJUSTMENT
          Horizontal adjustment.

    VADJUSTMENT
          Vertical adjustment.

    RET
          New scrolled window.



 -- Function: gtk-scrolled-window-get-hadjustment
          (self `<gtk-scrolled-window>') =>  (ret `<gtk-adjustment>')
 -- Method: get-hadjustment
     Returns the horizontal scrollbar's adjustment, used to connect the
     horizontal scrollbar to the child widget's horizontal scroll
     functionality.

    SCROLLED-WINDOW
          A `<gtk-scrolled-window>'.

    RET
          The horizontal `<gtk-adjustment>'.



 -- Function: gtk-scrolled-window-get-vadjustment
          (self `<gtk-scrolled-window>') =>  (ret `<gtk-adjustment>')
 -- Method: get-vadjustment
     Returns the vertical scrollbar's adjustment, used to connect the
     vertical scrollbar to the child widget's vertical scroll
     functionality.

    SCROLLED-WINDOW
          A `<gtk-scrolled-window>'.

    RET
          The vertical `<gtk-adjustment>'.



 -- Function: gtk-scrolled-window-get-hscrollbar
          (self `<gtk-scrolled-window>') =>  (ret `<gtk-widget>')
 -- Method: get-hscrollbar
     Returns the horizontal scrollbar of SCROLLED-WINDOW.

    SCROLLED-WINDOW
          a `<gtk-scrolled-window>'

    RET
          the horizontal scrollbar of the scrolled window, or ``#f'' if
          it does not have one.


     Since 2.8


 -- Function: gtk-scrolled-window-get-vscrollbar
          (self `<gtk-scrolled-window>') =>  (ret `<gtk-widget>')
 -- Method: get-vscrollbar
     Returns the vertical scrollbar of SCROLLED-WINDOW.

    SCROLLED-WINDOW
          a `<gtk-scrolled-window>'

    RET
          the vertical scrollbar of the scrolled window, or ``#f'' if
          it does not have one.


     Since 2.8


 -- Function: gtk-scrolled-window-set-policy
          (self `<gtk-scrolled-window>')
          (hscrollbar_policy `<gtk-policy-type>')
          (vscrollbar_policy `<gtk-policy-type>')
 -- Method: set-policy
     Sets the scrollbar policy for the horizontal and vertical
     scrollbars. The policy determines when the scrollbar should
     appear; it is a value from the `<gtk-policy-type>' enumeration. If
     `GTK_POLICY_ALWAYS', the scrollbar is always present; if
     `GTK_POLICY_NEVER', the scrollbar is never present; if
     `GTK_POLICY_AUTOMATIC', the scrollbar is present only if needed
     (that is, if the slider part of the bar would be smaller than the
     trough - the display is larger than the page size).

    SCROLLED-WINDOW
          A `<gtk-scrolled-window>'.

    HSCROLLBAR-POLICY
          Policy for horizontal bar.

    VSCROLLBAR-POLICY
          Policy for vertical bar.



 -- Function: gtk-scrolled-window-set-placement
          (self `<gtk-scrolled-window>')
          (window_placement `<gtk-corner-type>')
 -- Method: set-placement
     Sets the placement of the contents with respect to the scrollbars
     for the scrolled window.

     See also `gtk-scrolled-window-get-placement' and
     `gtk-scrolled-window-unset-placement'.

     Determines the location of the child widget with respect to the
     scrollbars. The default is `GTK_CORNER_TOP_LEFT', meaning the
     child is in the top left, with the scrollbars underneath and to
     the right. Other values in `<gtk-corner-type>' are
     `GTK_CORNER_TOP_RIGHT', `GTK_CORNER_BOTTOM_LEFT', and
     `GTK_CORNER_BOTTOM_RIGHT'.

    SCROLLED-WINDOW
          a `<gtk-scrolled-window>'

    WINDOW-PLACEMENT
          Position of the child window.



 -- Function: gtk-scrolled-window-unset-placement
          (self `<gtk-scrolled-window>')
 -- Method: unset-placement
     Unsets the placement of the contents with respect to the
     scrollbars for the scrolled window. If no window placement is set
     for a scrolled window, it obeys the
     "gtk-scrolled-window-placement" XSETTING.

     See also `gtk-scrolled-window-set-placement' and
     `gtk-scrolled-window-get-placement'.

    SCROLLED-WINDOW
          a `<gtk-scrolled-window>'


     Since 2.10


 -- Function: gtk-scrolled-window-set-shadow-type
          (self `<gtk-scrolled-window>') (type `<gtk-shadow-type>')
 -- Method: set-shadow-type
     Changes the type of shadow drawn around the contents of
     SCROLLED-WINDOW.

    SCROLLED-WINDOW
          a `<gtk-scrolled-window>'

    TYPE
          kind of shadow to draw around scrolled window contents



 -- Function: gtk-scrolled-window-set-hadjustment
          (self `<gtk-scrolled-window>')
          (hadjustment `<gtk-adjustment>')
 -- Method: set-hadjustment
     Sets the `<gtk-adjustment>' for the horizontal scrollbar.

    SCROLLED-WINDOW
          A `<gtk-scrolled-window>'.

    HADJUSTMENT
          Horizontal scroll adjustment.



 -- Function: gtk-scrolled-window-set-vadjustment
          (self `<gtk-scrolled-window>')
          (vadjustment `<gtk-adjustment>')
 -- Method: set-vadjustment
     Sets the `<gtk-adjustment>' for the vertical scrollbar.

    SCROLLED-WINDOW
          A `<gtk-scrolled-window>'.

    VADJUSTMENT
          Vertical scroll adjustment.



 -- Function: gtk-scrolled-window-get-placement
          (self `<gtk-scrolled-window>') =>  (ret `<gtk-corner-type>')
 -- Method: get-placement
     Gets the placement of the contents with respect to the scrollbars
     for the scrolled window. See `gtk-scrolled-window-set-placement'.

    SCROLLED-WINDOW
          a `<gtk-scrolled-window>'

    RET
          the current placement value. See also
          `gtk-scrolled-window-set-placement' and
          `gtk-scrolled-window-unset-placement'.



 -- Function: gtk-scrolled-window-get-shadow-type
          (self `<gtk-scrolled-window>') =>  (ret `<gtk-shadow-type>')
 -- Method: get-shadow-type
     Gets the shadow type of the scrolled window. See
     `gtk-scrolled-window-set-shadow-type'.

    SCROLLED-WINDOW
          a `<gtk-scrolled-window>'

    RET
          the current shadow type




File: guile-gnome-gtk.info,  Node: GtkPrintOperation,  Next: GtkPrintContext,  Prev: GtkScrolledWindow,  Up: Top

109 GtkPrintOperation
*********************

High-level Printing API

109.1 Overview
==============

GtkPrintOperation is the high-level, portable printing API. It looks a
bit different than other GTK+ dialogs such as the `<gtk-file-chooser>',
since some platforms don't expose enough infrastructure to implement a
good print dialog. On such platforms, GtkPrintOperation uses the native
print dialog. On platforms which do not provide a native print dialog,
GTK+ uses its own, see `<gtk-print-unix-dialog>'.

   The typical way to use the high-level printing API is to create a
`<gtk-print-operation>' object with `gtk-print-operation-new' when the
user selects to print. Then you set some properties on it, e.g. the
page size, any `<gtk-print-settings>' from previous print operations,
the number of pages, the current page, etc.

   Then you start the print operation by calling
`gtk-print-operation-run'. It will then show a dialog, let the user
select a printer and options. When the user finished the dialog various
signals will be emitted on the `<gtk-print-operation>', the main one
being ::draw-page, which you are supposed to catch and render the page
on the provided `<gtk-print-context>' using Cairo.


     static GtkPrintSettings *settings = NULL;

     static void
     do_print (void)
     {
       GtkPrintOperation *print;
       GtkPrintOperationResult res;

       print = gtk_print_operation_new ();

       if (settings != NULL)
         gtk_print_operation_set_print_settings (print, settings);

       g_signal_connect (print, "begin_print", G_CALLBACK (begin_print), NULL);
       g_signal_connect (print, "draw_page", G_CALLBACK (draw_page), NULL);

       res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
                                      GTK_WINDOW (main_window), NULL);

       if (res == GTK_PRINT_OPERATION_RESULT_APPLY)
         {
           if (settings != NULL)
             g_object_unref (settings);
           settings = g_object_ref (gtk_print_operation_get_print_settings (print));
         }

       g_object_unref (print);
     }

   By default GtkPrintOperation uses an external application to do
print preview.  To implement a custom print preview, an application
must connect to the preview signal. The functions
`gtk-print-operation-print-preview-render-page',
`gtk-print-operation-preview-end-preview' and
`gtk-print-operation-preview-is-selected' are useful when implementing a
print preview.

   Printing support was added in GTK+ 2.10.

109.2 Usage
===========

 -- Class: <gtk-print-operation>
     Derives from `<gtk-print-operation-preview>', `<gobject>'.

     This class defines the following properties:

    `default-page-setup'
          The GtkPageSetup used by default

    `print-settings'
          The GtkPrintSettings used for initializing the dialog

    `job-name'
          A string used for identifying the print job.

    `n-pages'
          The number of pages in the document.

    `current-page'
          The current page in the document

    `use-full-page'
          TRUE if the origin of the context should be at the corner of
          the page and not the corner of the imageable area

    `track-print-status'
          TRUE if the print operation will continue to report on the
          print job status after the print data has been sent to the
          printer or print server.

    `unit'
          The unit in which distances can be measured in the context

    `show-progress'
          TRUE if a progress dialog is shown while printing.

    `allow-async'
          TRUE if print process may run asynchronous.

    `export-filename'
          Export filename

    `status'
          The status of the print operation

    `status-string'
          A human-readable description of the status

    `custom-tab-label'
          Label for the tab containing custom widgets.



 -- Signal on <gtk-print-operation>: done
          (arg0 `<gtk-print-operation-result>')
     Emitted when the print operation run has finished doing everything
     required for printing. RESULT gives you information about what
     happened during the run.  If RESULT is
     `GTK_PRINT_OPERATION_RESULT_ERROR' then you can call
     `gtk-print-operation-get-error' for more information.

     If you enabled print status tracking then
     `gtk-print-operation-is-finished' may still return ``#f'' after
     this was emitted.

     Since 2.10


 -- Signal on <gtk-print-operation>: begin-print
          (arg0 `<gtk-print-context>')
     Emitted after the user has finished changing print settings in the
     dialog, before the actual rendering starts.

     A typical use for this signal is to use the parameters from the
     `<gtk-print-context>' and paginate the document accordingly, and
     then set the number of pages with
     `gtk-print-operation-set-n-pages'.

     Since 2.10


 -- Signal on <gtk-print-operation>: paginate
          (arg0 `<gtk-print-context>') => `<gboolean>'
     Emitted after the begin-print signal, but before the actual
     rendering starts. It keeps getting emitted until it returns ``#f''.

     This signal is intended to be used for paginating the document in
     small chunks, to avoid blocking the user interface for a long
     time. The signal handler should update the number of pages using
     `gtk-print-operation-set-n-pages', and return ``#t'' if the
     document has been completely paginated.

     If you don't need to do pagination in chunks, you can simply do it
     all in the begin-print handler, and set the number of pages from
     there.

     Since 2.10


 -- Signal on <gtk-print-operation>: request-page-setup
          (arg0 `<gtk-print-context>') (arg1 `<gint>')
          (arg2 `<gtk-page-setup>')
     Emitted once for every page that is printed, to give the
     application a chance to modify the page setup. Any changes done to
     SETUP will be in force only for printing this page.

     Since 2.10


 -- Signal on <gtk-print-operation>: draw-page
          (arg0 `<gtk-print-context>') (arg1 `<gint>')
     Emitted for every page that is printed. The signal handler must
     render the PAGE-NR's page onto the cairo context obtained from
     CONTEXT using `gtk-print-context-get-cairo-context'.


          static void
          draw_page (GtkPrintOperation *operation,
                     GtkPrintContext   *context,
                     gint               page_nr,
                     gpointer           user_data)
          {
            cairo_t *cr;
            PangoLayout *layout;
            gdouble width, text_height;
            gint layout_height;
            PangoFontDescription *desc;

            cr = gtk_print_context_get_cairo_context (context);
            width = gtk_print_context_get_width (context);

            cairo_rectangle (cr, 0, 0, width, HEADER_HEIGHT);

            cairo_set_source_rgb (cr, 0.8, 0.8, 0.8);
            cairo_fill (cr);

            layout = gtk_print_context_create_pango_layout (context);

            desc = pango_font_description_from_string ("sans 14");
            pango_layout_set_font_description (layout, desc);
            pango_font_description_free (desc);

            pango_layout_set_text (layout, "some text", -1);
            pango_layout_set_width (layout, width);
            pango_layout_set_alignment (layout, PANGO_ALIGN_CENTER);

            pango_layout_get_size (layout, NULL, &layout_height);
            text_height = (gdouble)layout_height / PANGO_SCALE;

            cairo_move_to (cr, width / 2,  (HEADER_HEIGHT - text_height) / 2);
            pango_cairo_show_layout (cr, layout);

            g_object_unref (layout);
          }

     Use `gtk-print-operation-set-use-full-page' and
     `gtk-print-operation-set-unit' before starting the print operation
     to set up the transformation of the cairo context according to
     your needs.

     Since 2.10


 -- Signal on <gtk-print-operation>: end-print
          (arg0 `<gtk-print-context>')
     Emitted after all pages have been rendered. A handler for this
     signal can clean up any resources that have been allocated in the
     ::begin-print handler.

     Since 2.10


 -- Signal on <gtk-print-operation>: status-changed
     Emitted at between the various phases of the print operation. See
     `<gtk-print-status>' for the phases that are being discriminated.
     Use `gtk-print-operation-get-status' to find out the current
     status.

     Since 2.10


 -- Signal on <gtk-print-operation>: create-custom-widget => `<gobject>'
     Emitted when displaying the print dialog. If you return a widget
     in a handler for this signal it will be added to a custom tab in
     the print dialog. You typically return a container widget with
     multiple widgets in it.

     The print dialog owns the returned widget, and its lifetime isn't
     controlled by the app. However, the widget is guaranteed to stay
     around until the custom-widget-apply signal is emitted on the
     operation. Then you can read out any information you need from the
     widgets.

     Since 2.10


 -- Signal on <gtk-print-operation>: custom-widget-apply
          (arg0 `<gtk-widget>')
     Emitted right before begin-print if you added a custom widget in
     the create-custom-widget handler. When you get this signal you
     should read the information from the custom widgets, as the
     widgets are not guaraneed to be around at a later time.

     Since 2.10


 -- Signal on <gtk-print-operation>: preview
          (arg0 `<gtk-print-operation-preview>')
          (arg1 `<gtk-print-context>') (arg2 `<gtk-window>')
          => `<gboolean>'
     Gets emitted when a preview is requested from the native dialog.

     The default handler for this signal uses an external viewer
     application to preview.

     To implement a custom print preview, an application must return
     ``#t'' from its handler for this signal. In order to use the
     provided CONTEXT for the preview implementation, it must be given
     a suitable cairo context with
     `gtk-print-context-set-cairo-context'.

     The custom preview implementation can use
     `gtk-print-operation-preview-is-selected' and
     `gtk-print-operation-preview-render-page' to find pages which are
     selected for print and render them. The preview must be finished
     by calling `gtk-print-operation-preview-end-preview' (typically in
     response to the user clicking a close button).

     Since 2.10


 -- Class: <gtk-print-operation-preview>
     Derives from `<ginterface>'.

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


 -- Signal on <gtk-print-operation-preview>: ready
          (arg0 `<gtk-print-context>')
     undocumented

 -- Signal on <gtk-print-operation-preview>: got-page-size
          (arg0 `<gtk-print-context>') (arg1 `<gtk-page-setup>')
     undocumented

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

    RET
          a new `<gtk-print-operation>'


     Since 2.10


 -- Function: gtk-print-operation-set-allow-async
          (self `<gtk-print-operation>') (allow_async `bool')
 -- Method: set-allow-async
     Sets whether the `gtk-print-operation-run' may return before the
     print operation is completed. Note that some platforms may not
     allow asynchronous operation.

    OP
          a `<gtk-print-operation>'

    ALLOW-ASYNC
          ``#t'' to allow asynchronous operation


     Since 2.10


 -- Function: gtk-print-operation-get-error
          (self `<gtk-print-operation>')
 -- Method: get-error
     Call this when the result of a print operation is
     `GTK_PRINT_OPERATION_RESULT_ERROR', either as returned by
     `gtk-print-operation-run', or in the ::done signal handler. The
     returned `<g-error>' will contain more details on what went wrong.

    OP
          a `<gtk-print-operation>'

    ERROR
          return location for the error


     Since 2.10


 -- Function: gtk-print-operation-set-job-name
          (self `<gtk-print-operation>') (job_name `mchars')
 -- Method: set-job-name
     Sets the name of the print job. The name is used to identify the
     job (e.g. in monitoring applications like eggcups).

     If you don't set a job name, GTK+ picks a default one by numbering
     successive print jobs.

    OP
          a `<gtk-print-operation>'

    JOB-NAME
          a string that identifies the print job


     Since 2.10


 -- Function: gtk-print-operation-set-n-pages
          (self `<gtk-print-operation>') (n_pages `int')
 -- Method: set-n-pages
     Sets the number of pages in the document.

     This _must_ be set to a positive number before the rendering
     starts. It may be set in a ::begin-print signal hander.

     Note that the page numbers passed to the ::request-page-setup and
     ::draw-page signals are 0-based, i.e. if the user chooses to print
     all pages, the last ::draw-page signal will be for page N-PAGES -
     1.

    OP
          a `<gtk-print-operation>'

    N-PAGES
          the number of pages


     Since 2.10


 -- Function: gtk-print-operation-set-unit
          (self `<gtk-print-operation>') (unit `<gtk-unit>')
 -- Method: set-unit
     Sets up the transformation for the cairo context obtained from
     `<gtk-print-context>' in such a way that distances are measured in
     units of UNIT.

    OP
          a `<gtk-print-operation>'

    UNIT
          the unit to use


     Since 2.10


 -- Function: gtk-print-operation-run (self `<gtk-print-operation>')
          (action `<gtk-print-operation-action>')
          (parent `<gtk-window>') => 
          (ret `<gtk-print-operation-result>')
 -- Method: run
     Runs the print operation, by first letting the user modify print
     settings in the print dialog, and then print the document.

     Normally that this function does not return until the rendering of
     all pages is complete. You can connect to the ::status-changed
     signal on OP to obtain some information about the progress of the
     print operation. Furthermore, it may use a recursive mainloop to
     show the print dialog.

     If you call `gtk-print-operation-set-allow-async' or set the
     allow-async property the operation will run asyncronously if this
     is supported on the platform. The ::done signal will be emitted
     with the operation results when the operation is done (i.e. when
     the dialog is canceled, or when the print succeeds or fails).


          if (settings != NULL)
            gtk_print_operation_set_print_settings (print, settings);

          if (page_setup != NULL)
            gtk_print_operation_set_default_page_setup (print, page_setup);

          g_signal_connect (print, "begin-print",
                            G_CALLBACK (begin_print), &data);
          g_signal_connect (print, "draw-page",
                            G_CALLBACK (draw_page), &data);

          res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, parent, &error);

          if (res == GTK_PRINT_OPERATION_RESULT_ERROR)
           {
             error_dialog = gtk_message_dialog_new (GTK_WINDOW (parent),
            			                     GTK_DIALOG_DESTROY_WITH_PARENT,
          					     GTK_MESSAGE_ERROR,
          					     GTK_BUTTONS_CLOSE,
          					     "Error printing file:\n%s",
          					     error->message);
             g_signal_connect (error_dialog, "response",
                               G_CALLBACK (gtk_widget_destroy), NULL);
             gtk_widget_show (error_dialog);
             g_error_free (error);
           }
          else if (res == GTK_PRINT_OPERATION_RESULT_APPLY)
           {
             if (settings != NULL)
          g_object_unref (settings);
             settings = g_object_ref (gtk_print_operation_get_print_settings (print));
           }

     Note that `gtk-print-operation-run' can only be called once on a
     given `<gtk-print-operation>'.

    OP
          a `<gtk-print-operation>'

    ACTION
          the action to start

    PARENT
          Transient parent of the dialog, or ``#f''

    ERROR
          Return location for errors, or ``#f''

    RET
          the result of the print operation. A return value of
          `GTK_PRINT_OPERATION_RESULT_APPLY' indicates that the
          printing was completed successfully. In this case, it is a
          good idea to obtain the used print settings with
          `gtk-print-operation-get-print-settings' and store them for
          reuse with the next print operation. A value of
          `GTK_PRINT_OPERATION_RESULT_IN_PROGRESS' means the operation
          is running asynchronously, and will emit the ::done signal
          when done.


     Since 2.10


 -- Function: gtk-print-operation-cancel (self `<gtk-print-operation>')
 -- Method: cancel
     Cancels a running print operation. This function may be called
     from a begin-print, paginate or draw-page signal handler to stop
     the currently running print operation.

    OP
          a `<gtk-print-operation>'


     Since 2.10


 -- Function: gtk-print-operation-get-status
          (self `<gtk-print-operation>') =>  (ret `<gtk-print-status>')
 -- Method: get-status
     Returns the status of the print operation. Also see
     `gtk-print-operation-get-status-string'.

    OP
          a `<gtk-print-operation>'

    RET
          the status of the print operation


     Since 2.10


 -- Function: gtk-print-operation-is-finished
          (self `<gtk-print-operation>') =>  (ret `bool')
 -- Method: is-finished
     A convenience function to find out if the print operation is
     finished, either successfully (`GTK_PRINT_STATUS_FINISHED') or
     unsuccessfully (`GTK_PRINT_STATUS_FINISHED_ABORTED').

     Note: when you enable print status tracking the print operation
     can be in a non-finished state even after done has been called, as
     the operation status then tracks the print job status on the
     printer.

    OP
          a `<gtk-print-operation>'

    RET
          ``#t'', if the print operation is finished.


     Since 2.10


 -- Function: gtk-print-operation-get-error
          (self `<gtk-print-operation>')
 -- Method: get-error
     Call this when the result of a print operation is
     `GTK_PRINT_OPERATION_RESULT_ERROR', either as returned by
     `gtk-print-operation-run', or in the ::done signal handler. The
     returned `<g-error>' will contain more details on what went wrong.

    OP
          a `<gtk-print-operation>'

    ERROR
          return location for the error


     Since 2.10


 -- Function: gtk-print-run-page-setup-dialog (parent `<gtk-window>')
          (page_setup `<gtk-page-setup>')
          (settings `<gtk-print-settings>') =>  (ret `<gtk-page-setup>')
     Runs a page setup dialog, letting the user modify the values from
     PAGE-SETUP. If the user cancels the dialog, the returned
     `<gtk-page-setup>' is identical to the passed in PAGE-SETUP,
     otherwise it contains the modifications done in the dialog.

     Note that this function may use a recursive mainloop to show the
     page setup dialog. See `gtk-print-run-page-setup-dialog-async' if
     this is a problem.

    PARENT
          transient parent, or ``#f''

    PAGE-SETUP
          an existing `<gtk-page-setup>', or ``#f''

    SETTINGS
          a `<gtk-print-settings>'

    RET
          a new `<gtk-page-setup>'


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkPrintContext,  Next: GtkPrintSettings,  Prev: GtkPrintOperation,  Up: Top

110 GtkPrintContext
*******************

Encapsulates context for drawing pages

110.1 Overview
==============

A GtkPrintContext encapsulates context information that is required
when drawing pages for printing, such as the cairo context and
important parameters like page size and resolution. It also lets you
easily create `<pango-layout>' and `<pango-context>' objects that match
the font metrics of the cairo surface.

   GtkPrintContext objects gets passed to the ::begin-print,
::end-print, ::request-page-setup and ::draw-page signals on the
`<gtk-print-operation>'.


     static void
     draw_page (GtkPrintOperation *operation,
     	   GtkPrintContext   *context,
     	   int                page_nr)
     {
       cairo_t *cr;
       PangoLayout *layout;
       PangoFontDescription *desc;

       cr = gtk_print_context_get_cairo_context (context);

       /* Draw a red rectangle, as wide as the paper (inside the margins) */
       cairo_set_source_rgb (cr, 1.0, 0, 0);
       cairo_rectangle (cr, 0, 0, gtk_print_context_get_width (context), 50);

       cairo_fill (cr);

       /* Draw some lines */
       cairo_move_to (cr, 20, 10);
       cairo_line_to (cr, 40, 20);
       cairo_arc (cr, 60, 60, 20, 0, M_PI);
       cairo_line_to (cr, 80, 20);

       cairo_set_source_rgb (cr, 0, 0, 0);
       cairo_set_line_width (cr, 5);
       cairo_set_line_cap (cr, CAIRO_LINE_CAP_ROUND);
       cairo_set_line_join (cr, CAIRO_LINE_JOIN_ROUND);

       cairo_stroke (cr);

       /* Draw some text */
       layout = gtk_print_context_create_layout (context);
       pango_layout_set_text (layout, "Hello World! Printing is easy", -1);
       desc = pango_font_description_from_string ("sans 28");
       pango_layout_set_font_description (layout, desc);
       pango_font_description_free (desc);

       cairo_move_to (cr, 30, 20);
       pango_cairo_layout_path (cr, layout);

       /* Font Outline */
       cairo_set_source_rgb (cr, 0.93, 1.0, 0.47);
       cairo_set_line_width (cr, 0.5);
       cairo_stroke_preserve (cr);

       /* Font Fill */
       cairo_set_source_rgb (cr, 0, 0.0, 1.0);
       cairo_fill (cr);

       g_object_unref (layout);
     }

   Printing support was added in GTK+ 2.10.

110.2 Usage
===========

 -- Class: <gtk-print-context>
     Derives from `<gobject>'.

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


 -- Function: gtk-print-context-get-cairo-context
          (self `<gtk-print-context>') =>  (ret `cairo-t')
 -- Method: get-cairo-context
     Obtains the cairo context that is associated with the
     `<gtk-print-context>'.

    CONTEXT
          a `<gtk-print-context>'

    RET
          the cairo context of CONTEXT


     Since 2.10


 -- Function: gtk-print-context-set-cairo-context
          (self `<gtk-print-context>') (cr `cairo-t') (dpi_x `double')
          (dpi_y `double')
 -- Method: set-cairo-context
     Sets a new cairo context on a print context.

     This function is intended to be used when implementing an internal
     print preview, it is not needed for printing, since GTK+ itself
     creates a suitable cairo context in that case.

    CONTEXT
          a `<gtk-print-context>'

    CR
          the cairo context

    DPI-X
          the horizontal resolution to use with CR

    DPI-Y
          the vertical resolution to use with CR


     Since 2.10


 -- Function: gtk-print-context-get-page-setup
          (self `<gtk-print-context>') =>  (ret `<gtk-page-setup>')
 -- Method: get-page-setup
     Obtains the `<gtk-page-setup>' that determines the page dimensions
     of the `<gtk-print-context>'.

    CONTEXT
          a `<gtk-print-context>'

    RET
          the page setup of CONTEXT


     Since 2.10


 -- Function: gtk-print-context-get-width (self `<gtk-print-context>')
          =>  (ret `double')
 -- Method: get-width
     Obtains the width of the `<gtk-print-context>', in pixels.

    CONTEXT
          a `<gtk-print-context>'

    RET
          the width of CONTEXT


     Since 2.10


 -- Function: gtk-print-context-get-height (self `<gtk-print-context>')
          =>  (ret `double')
 -- Method: get-height
     Obtains the height of the `<gtk-print-context>', in pixels.

    CONTEXT
          a `<gtk-print-context>'

    RET
          the height of CONTEXT


     Since 2.10


 -- Function: gtk-print-context-get-dpi-x (self `<gtk-print-context>')
          =>  (ret `double')
 -- Method: get-dpi-x
     Obtains the horizontal resolution of the `<gtk-print-context>', in
     dots per inch.

    CONTEXT
          a `<gtk-print-context>'

    RET
          the horizontal resolution of CONTEXT


     Since 2.10


 -- Function: gtk-print-context-get-dpi-y (self `<gtk-print-context>')
          =>  (ret `double')
 -- Method: get-dpi-y
     Obtains the vertical resolution of the `<gtk-print-context>', in
     dots per inch.

    CONTEXT
          a `<gtk-print-context>'

    RET
          the vertical resolution of CONTEXT


     Since 2.10


 -- Function: gtk-print-context-get-pango-fontmap
          (self `<gtk-print-context>') =>  (ret `<pango-font-map>')
 -- Method: get-pango-fontmap
     Returns a `<pango-font-map>' that is suitable for use with the
     `<gtk-print-context>'.

    CONTEXT
          a `<gtk-print-context>'

    RET
          the font map of CONTEXT


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkPrintSettings,  Next: GtkPageSetup,  Prev: GtkPrintContext,  Up: Top

111 GtkPrintSettings
********************

Stores print settings

111.1 Overview
==============

A GtkPrintSettings object represents the settings of a print dialog in a
system-independent way. The main use for this object is that once
you've printed you can get a settings object that represents the
settings the user chose, and the next time you print you can pass that
object in so that the user doesn't have to re-set all his settings.

   Its also possible to enumerate the settings so that you can easily
save the settings for the next time your app runs, or even store them
in a document. The predefined keys try to use shared values as much as
possible so that moving such a document between systems still works.

   Printing support was added in GTK+ 2.10.

111.2 Usage
===========

 -- Class: <gtk-print-settings>
     Derives from `<gobject>'.

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


 -- Function: gtk-print-settings-new =>  (ret `<gtk-print-settings>')
     Creates a new `<gtk-print-settings>' object.

    RET
          a new `<gtk-print-settings>' object


     Since 2.10


 -- Function: gtk-print-settings-has-key (self `<gtk-print-settings>')
          (key `mchars') =>  (ret `bool')
 -- Method: has-key
     Returns ``#t'', if a value is associated with KEY.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    RET
          ``#t'', if KEY has a value


     Since 2.10


 -- Function: gtk-print-settings-get (self `<gtk-print-settings>')
          (key `mchars') =>  (ret `mchars')
 -- Method: get
     Looks up the string value associated with KEY.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    RET
          the string value for KEY


     Since 2.10


 -- Function: gtk-print-settings-set (self `<gtk-print-settings>')
          (key `mchars') (value `mchars')
 -- Method: set
     Associates VALUE with KEY.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    VALUE
          a string value, or ``#f''


     Since 2.10


 -- Function: gtk-print-settings-unset (self `<gtk-print-settings>')
          (key `mchars')
 -- Method: unset
     Removes any value associated with KEY. This has the same effect as
     setting the value to ``#f''.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key


     Since 2.10


 -- Function: gtk-print-settings-get-bool (self `<gtk-print-settings>')
          (key `mchars') =>  (ret `bool')
 -- Method: get-bool
     Returns the boolean represented by the value that is associated
     with KEY.

     The string "true" represents ``#t'', any other string ``#f''.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    RET
          ``#t'', if KEY maps to a true value.


     Since 2.10


 -- Function: gtk-print-settings-set-bool (self `<gtk-print-settings>')
          (key `mchars') (value `bool')
 -- Method: set-bool
     Sets KEY to a boolean value.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    VALUE
          a boolean


     Since 2.10


 -- Function: gtk-print-settings-get-double
          (self `<gtk-print-settings>') (key `mchars') => 
          (ret `double')
 -- Method: get-double
     Returns the double value associated with KEY, or 0.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    RET
          the double value of KEY


     Since 2.10


 -- Function: gtk-print-settings-set-double
          (self `<gtk-print-settings>') (key `mchars') (value `double')
 -- Method: set-double
     Sets KEY to a double value.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    VALUE
          a double value


     Since 2.10


 -- Function: gtk-print-settings-get-length
          (self `<gtk-print-settings>') (key `mchars')
          (unit `<gtk-unit>') =>  (ret `double')
 -- Method: get-length
     Returns the value associated with KEY, interpreted as a length. The
     returned value is converted to UNITS.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    UNIT
          the unit of the return value

    RET
          the length value of KEY, converted to UNIT


     Since 2.10


 -- Function: gtk-print-settings-set-length
          (self `<gtk-print-settings>') (key `mchars') (value `double')
          (unit `<gtk-unit>')
 -- Method: set-length
     Associates a length in units of UNIT with KEY.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    VALUE
          a length

    UNIT
          the unit of LENGTH


     Since 2.10


 -- Function: gtk-print-settings-get-int (self `<gtk-print-settings>')
          (key `mchars') =>  (ret `int')
 -- Method: get-int
     Returns the integer value of KEY, or 0.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    RET
          the integer value of KEY


     Since 2.10


 -- Function: gtk-print-settings-set-int (self `<gtk-print-settings>')
          (key `mchars') (value `int')
 -- Method: set-int
     Sets KEY to an integer value.

    SETTINGS
          a `<gtk-print-settings>'

    KEY
          a key

    VALUE
          an integer


     Since 2.10


 -- Function: gtk-print-settings-get-printer
          (self `<gtk-print-settings>') =>  (ret `mchars')
 -- Method: get-printer
     Convenience function to obtain the value of
     `GTK_PRINT_SETTINGS_PRINTER'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the printer name


     Since 2.10


 -- Function: gtk-print-settings-set-printer
          (self `<gtk-print-settings>') (printer `mchars')
 -- Method: set-printer
     Convenience function to set `GTK_PRINT_SETTINGS_PRINTER' to
     PRINTER.

    SETTINGS
          a `<gtk-print-settings>'

    PRINTER
          the printer name


     Since 2.10


 -- Function: gtk-print-settings-get-orientation
          (self `<gtk-print-settings>') => 
          (ret `<gtk-page-orientation>')
 -- Method: get-orientation
     Get the value of `GTK_PRINT_SETTINGS_ORIENTATION', converted to a
     `<gtk-page-orientation>'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the orientation


     Since 2.10


 -- Function: gtk-print-settings-set-orientation
          (self `<gtk-print-settings>')
          (orientation `<gtk-page-orientation>')
 -- Method: set-orientation
     Sets the value of `GTK_PRINT_SETTINGS_ORIENTATION'.

    SETTINGS
          a `<gtk-print-settings>'

    ORIENTATION
          a page orientation


     Since 2.10


 -- Function: gtk-print-settings-get-paper-size
          (self `<gtk-print-settings>') =>  (ret `<gtk-paper-size>')
 -- Method: get-paper-size
     Gets the value of `GTK_PRINT_SETTINGS_PAPER_FORMAT', converted to a
     `<gtk-paper-size>'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the paper size


     Since 2.10


 -- Function: gtk-print-settings-set-paper-size
          (self `<gtk-print-settings>') (paper_size `<gtk-paper-size>')
 -- Method: set-paper-size
     Sets the value of `GTK_PRINT_SETTINGS_PAPER_FORMAT',
     `GTK_PRINT_SETTINGS_PAPER_WIDTH' and
     `GTK_PRINT_SETTINGS_PAPER_HEIGHT'.

    SETTINGS
          a `<gtk-print-settings>'

    PAPER-SIZE
          a paper size


     Since 2.10


 -- Function: gtk-print-settings-get-paper-width
          (self `<gtk-print-settings>') (unit `<gtk-unit>') => 
          (ret `double')
 -- Method: get-paper-width
     Gets the value of `GTK_PRINT_SETTINGS_PAPER_WIDTH', converted to
     UNIT.

    SETTINGS
          a `<gtk-print-settings>'

    UNIT
          the unit for the return value

    RET
          the paper width, in units of UNIT


     Since 2.10


 -- Function: gtk-print-settings-set-paper-width
          (self `<gtk-print-settings>') (width `double')
          (unit `<gtk-unit>')
 -- Method: set-paper-width
     Sets the value of `GTK_PRINT_SETTINGS_PAPER_WIDTH'.

    SETTINGS
          a `<gtk-print-settings>'

    WIDTH
          the paper width

    UNIT
          the units of WIDTH


     Since 2.10


 -- Function: gtk-print-settings-get-paper-height
          (self `<gtk-print-settings>') (unit `<gtk-unit>') => 
          (ret `double')
 -- Method: get-paper-height
     Gets the value of `GTK_PRINT_SETTINGS_PAPER_HEIGHT', converted to
     UNIT.

    SETTINGS
          a `<gtk-print-settings>'

    UNIT
          the unit for the return value

    RET
          the paper height, in units of UNIT


     Since 2.10


 -- Function: gtk-print-settings-set-paper-height
          (self `<gtk-print-settings>') (height `double')
          (unit `<gtk-unit>')
 -- Method: set-paper-height
     Sets the value of `GTK_PRINT_SETTINGS_PAPER_HEIGHT'.

    SETTINGS
          a `<gtk-print-settings>'

    HEIGHT
          the paper height

    UNIT
          the units of HEIGHT


     Since 2.10


 -- Function: gtk-print-settings-get-use-color
          (self `<gtk-print-settings>') =>  (ret `bool')
 -- Method: get-use-color
     Gets the value of `GTK_PRINT_SETTINGS_USE_COLOR'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          whether to use color


     Since 2.10


 -- Function: gtk-print-settings-set-use-color
          (self `<gtk-print-settings>') (use_color `bool')
 -- Method: set-use-color
     Sets the value of `GTK_PRINT_SETTINGS_USE_COLOR'.

    SETTINGS
          a `<gtk-print-settings>'

    USE-COLOR
          whether to use color


     Since 2.10


 -- Function: gtk-print-settings-get-collate
          (self `<gtk-print-settings>') =>  (ret `bool')
 -- Method: get-collate
     Gets the value of `GTK_PRINT_SETTINGS_COLLATE'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          whether to collate the printed pages


     Since 2.10


 -- Function: gtk-print-settings-set-collate
          (self `<gtk-print-settings>') (collate `bool')
 -- Method: set-collate
     Sets the value of `GTK_PRINT_SETTINGS_COLLATE'.

    SETTINGS
          a `<gtk-print-settings>'

    COLLATE
          whether to collate the output


     Since 2.10


 -- Function: gtk-print-settings-get-reverse
          (self `<gtk-print-settings>') =>  (ret `bool')
 -- Method: get-reverse
     Gets the value of `GTK_PRINT_SETTINGS_REVERSE'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          whether to reverse the order of the printed pages


     Since 2.10


 -- Function: gtk-print-settings-set-reverse
          (self `<gtk-print-settings>') (reverse `bool')
 -- Method: set-reverse
     Sets the value of `GTK_PRINT_SETTINGS_REVERSE'.

    SETTINGS
          a `<gtk-print-settings>'

    REVERSE
          whether to reverse the output


     Since 2.10


 -- Function: gtk-print-settings-get-duplex
          (self `<gtk-print-settings>') =>  (ret `<gtk-print-duplex>')
 -- Method: get-duplex
     Gets the value of `GTK_PRINT_SETTINGS_DUPLEX'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          whether to print the output in duplex.


     Since 2.10


 -- Function: gtk-print-settings-set-duplex
          (self `<gtk-print-settings>') (duplex `<gtk-print-duplex>')
 -- Method: set-duplex
     Sets the value of `GTK_PRINT_SETTINGS_DUPLEX'.

    SETTINGS
          a `<gtk-print-settings>'

    DUPLEX
          a `<gtk-print-duplex>' value


     Since 2.10


 -- Function: gtk-print-settings-get-quality
          (self `<gtk-print-settings>') =>  (ret `<gtk-print-quality>')
 -- Method: get-quality
     Gets the value of `GTK_PRINT_SETTINGS_QUALITY'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the print quality


     Since 2.10


 -- Function: gtk-print-settings-set-quality
          (self `<gtk-print-settings>') (quality `<gtk-print-quality>')
 -- Method: set-quality
     Sets the value of `GTK_PRINT_SETTINGS_QUALITY'.

    SETTINGS
          a `<gtk-print-settings>'

    QUALITY
          a `<gtk-print-quality>' value


     Since 2.10


 -- Function: gtk-print-settings-get-n-copies
          (self `<gtk-print-settings>') =>  (ret `int')
 -- Method: get-n-copies
     Gets the value of `GTK_PRINT_SETTINGS_N_COPIES'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the number of copies to print


     Since 2.10


 -- Function: gtk-print-settings-set-n-copies
          (self `<gtk-print-settings>') (num_copies `int')
 -- Method: set-n-copies
     Sets the value of `GTK_PRINT_SETTINGS_N_COPIES'.

    SETTINGS
          a `<gtk-print-settings>'

    NUM-COPIES
          the number of copies


     Since 2.10


 -- Function: gtk-print-settings-get-number-up
          (self `<gtk-print-settings>') =>  (ret `int')
 -- Method: get-number-up
     Gets the value of `GTK_PRINT_SETTINGS_NUMBER_UP'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the number of pages per sheet


     Since 2.10


 -- Function: gtk-print-settings-set-number-up
          (self `<gtk-print-settings>') (number_up `int')
 -- Method: set-number-up
     Sets the value of `GTK_PRINT_SETTINGS_NUMBER_UP'.

    SETTINGS
          a `<gtk-print-settings>'

    NUMBER-UP
          the number of pages per sheet


     Since 2.10


 -- Function: gtk-print-settings-get-resolution
          (self `<gtk-print-settings>') =>  (ret `int')
 -- Method: get-resolution
     Gets the value of `GTK_PRINT_SETTINGS_RESOLUTION'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the resolution in dpi


     Since 2.10


 -- Function: gtk-print-settings-set-resolution
          (self `<gtk-print-settings>') (resolution `int')
 -- Method: set-resolution
     Sets the value of `GTK_PRINT_SETTINGS_RESOLUTION'.

    SETTINGS
          a `<gtk-print-settings>'

    RESOLUTION
          the resolution in dpi


     Since 2.10


 -- Function: gtk-print-settings-get-scale
          (self `<gtk-print-settings>') =>  (ret `double')
 -- Method: get-scale
     Gets the value of `GTK_PRINT_SETTINGS_SCALE'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the scale in percent


     Since 2.10


 -- Function: gtk-print-settings-set-scale
          (self `<gtk-print-settings>') (scale `double')
 -- Method: set-scale
     Sets the value of `GTK_PRINT_SETTINGS_SCALE'.

    SETTINGS
          a `<gtk-print-settings>'

    SCALE
          the scale in percent


     Since 2.10


 -- Function: gtk-print-settings-get-page-set
          (self `<gtk-print-settings>') =>  (ret `<gtk-page-set>')
 -- Method: get-page-set
     Gets the value of `GTK_PRINT_SETTINGS_PAGE_SET'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the set of pages to print


     Since 2.10


 -- Function: gtk-print-settings-set-page-set
          (self `<gtk-print-settings>') (page_set `<gtk-page-set>')
 -- Method: set-page-set
     Sets the value of `GTK_PRINT_SETTINGS_PAGE_SET'.

    SETTINGS
          a `<gtk-print-settings>'

    PAGE-SET
          a `<gtk-page-set>' value


     Since 2.10


 -- Function: gtk-print-settings-get-media-type
          (self `<gtk-print-settings>') =>  (ret `mchars')
 -- Method: get-media-type
     Gets the value of `GTK_PRINT_SETTINGS_MEDIA_TYPE'.

     The set of media types is defined in PWG 5101.1-2002 PWG.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the media type


     Since 2.10


 -- Function: gtk-print-settings-set-media-type
          (self `<gtk-print-settings>') (media_type `mchars')
 -- Method: set-media-type
     Sets the value of `GTK_PRINT_SETTINGS_MEDIA_TYPE'.

     The set of media types is defined in PWG 5101.1-2002 PWG.

    SETTINGS
          a `<gtk-print-settings>'

    MEDIA-TYPE
          the media type


     Since 2.10


 -- Function: gtk-print-settings-get-dither
          (self `<gtk-print-settings>') =>  (ret `mchars')
 -- Method: get-dither
     Gets the value of `GTK_PRINT_SETTINGS_DITHER'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the dithering that is used


     Since 2.10


 -- Function: gtk-print-settings-set-dither
          (self `<gtk-print-settings>') (dither `mchars')
 -- Method: set-dither
     Sets the value of `GTK_PRINT_SETTINGS_DITHER'.

    SETTINGS
          a `<gtk-print-settings>'

    DITHER
          the dithering that is used


     Since 2.10


 -- Function: gtk-print-settings-get-finishings
          (self `<gtk-print-settings>') =>  (ret `mchars')
 -- Method: get-finishings
     Gets the value of `GTK_PRINT_SETTINGS_FINISHINGS'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the finishings


     Since 2.10


 -- Function: gtk-print-settings-set-finishings
          (self `<gtk-print-settings>') (finishings `mchars')
 -- Method: set-finishings
     Sets the value of `GTK_PRINT_SETTINGS_FINISHINGS'.

    SETTINGS
          a `<gtk-print-settings>'

    FINISHINGS
          the finishings


     Since 2.10


 -- Function: gtk-print-settings-get-output-bin
          (self `<gtk-print-settings>') =>  (ret `mchars')
 -- Method: get-output-bin
     Gets the value of `GTK_PRINT_SETTINGS_OUTPUT_BIN'.

    SETTINGS
          a `<gtk-print-settings>'

    RET
          the output bin


     Since 2.10


 -- Function: gtk-print-settings-set-output-bin
          (self `<gtk-print-settings>') (output_bin `mchars')
 -- Method: set-output-bin
     Sets the value of `GTK_PRINT_SETTINGS_OUTPUT_BIN'.

    SETTINGS
          a `<gtk-print-settings>'

    OUTPUT-BIN
          the output bin


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkPageSetup,  Next: GtkPaperSize,  Prev: GtkPrintSettings,  Up: Top

112 GtkPageSetup
****************

Stores page setup information

112.1 Overview
==============

A GtkPageSetup object stores the page size, orientation and margins.
The idea is that you can get one of these from the page setup dialog
and then pass it to the `<gtk-print-operation>' when printing. The
benefit of splitting this out of the `<gtk-print-settings>' is that
these affect the actual layout of the page, and thus need to be set
long before user prints.

   The margins specified in this object are the "print margins", i.e.
the parts of the page that the printer cannot print on. These are
different from the layout margins that a word processor uses; they are
typically used to determine the _minimal_ size for the layout margins.

   To obtain a `<gtk-page-setup>' use `gtk-page-setup-new' to get the
defaults, or use `gtk-print-run-page-setup-dialog' to show the page
setup dialog and receive the resulting page setup.


     static GtkPrintSettings *settings = NULL;
     static GtkPageSetup *page_setup = NULL;

     static void
     do_page_setup (void)
     {
       GtkPageSetup *new_page_setup;

       if (settings == NULL)
         settings = gtk_print_settings_new ();

       new_page_setup = gtk_print_run_page_setup_dialog (GTK_WINDOW (main_window),
                                                         page_setup, settings);

       if (page_setup)
         g_object_unref (page_setup);

       page_setup = new_page_setup;
     }

   Printing support was added in GTK+ 2.10.

112.2 Usage
===========

 -- Class: <gtk-page-setup>
     Derives from `<gobject>'.

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


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

    RET
          a new `<gtk-page-setup>'.


     Since 2.10


 -- Function: gtk-page-setup-get-orientation (self `<gtk-page-setup>')
          =>  (ret `<gtk-page-orientation>')
 -- Method: get-orientation
     Gets the page orientation of the `<gtk-page-setup>'.

    SETUP
          a `<gtk-page-setup>'

    RET
          the page orientation


     Since 2.10


 -- Function: gtk-page-setup-set-orientation (self `<gtk-page-setup>')
          (orientation `<gtk-page-orientation>')
 -- Method: set-orientation
     Sets the page orientation of the `<gtk-page-setup>'.

    SETUP
          a `<gtk-page-setup>'

    ORIENTATION
          a `<gtk-page-orientation>' value


     Since 2.10


 -- Function: gtk-page-setup-get-paper-size (self `<gtk-page-setup>')
          =>  (ret `<gtk-paper-size>')
 -- Method: get-paper-size
     Gets the paper size of the `<gtk-page-setup>'.

    SETUP
          a `<gtk-page-setup>'

    RET
          the paper size


     Since 2.10


 -- Function: gtk-page-setup-set-paper-size (self `<gtk-page-setup>')
          (size `<gtk-paper-size>')
 -- Method: set-paper-size
     Sets the paper size of the `<gtk-page-setup>' without changing the
     margins.  See `gtk-page-setup-set-paper-size-and-default-margins'.

    SETUP
          a `<gtk-page-setup>'

    SIZE
          a `<gtk-paper-size>'


     Since 2.10


 -- Function: gtk-page-setup-get-top-margin (self `<gtk-page-setup>')
          (unit `<gtk-unit>') =>  (ret `double')
 -- Method: get-top-margin
     Gets the top margin in units of UNIT.

    SETUP
          a `<gtk-page-setup>'

    UNIT
          the unit for the return value

    RET
          the top margin


     Since 2.10


 -- Function: gtk-page-setup-set-top-margin (self `<gtk-page-setup>')
          (margin `double') (unit `<gtk-unit>')
 -- Method: set-top-margin
     Sets the top margin of the `<gtk-page-setup>'.

    SETUP
          a `<gtk-page-setup>'

    MARGIN
          the new top margin in units of UNIT

    UNIT
          the units for MARGIN


     Since 2.10


 -- Function: gtk-page-setup-get-bottom-margin
          (self `<gtk-page-setup>') (unit `<gtk-unit>') => 
          (ret `double')
 -- Method: get-bottom-margin
     Gets the bottom margin in units of UNIT.

    SETUP
          a `<gtk-page-setup>'

    UNIT
          the unit for the return value

    RET
          the bottom margin


     Since 2.10


 -- Function: gtk-page-setup-set-bottom-margin
          (self `<gtk-page-setup>') (margin `double')
          (unit `<gtk-unit>')
 -- Method: set-bottom-margin
     Sets the bottom margin of the `<gtk-page-setup>'.

    SETUP
          a `<gtk-page-setup>'

    MARGIN
          the new bottom margin in units of UNIT

    UNIT
          the units for MARGIN


     Since 2.10


 -- Function: gtk-page-setup-get-left-margin (self `<gtk-page-setup>')
          (unit `<gtk-unit>') =>  (ret `double')
 -- Method: get-left-margin
     Gets the left margin in units of UNIT.

    SETUP
          a `<gtk-page-setup>'

    UNIT
          the unit for the return value

    RET
          the left margin


     Since 2.10


 -- Function: gtk-page-setup-set-left-margin (self `<gtk-page-setup>')
          (margin `double') (unit `<gtk-unit>')
 -- Method: set-left-margin
     Sets the left margin of the `<gtk-page-setup>'.

    SETUP
          a `<gtk-page-setup>'

    MARGIN
          the new left margin in units of UNIT

    UNIT
          the units for MARGIN


     Since 2.10


 -- Function: gtk-page-setup-get-right-margin (self `<gtk-page-setup>')
          (unit `<gtk-unit>') =>  (ret `double')
 -- Method: get-right-margin
     Gets the right margin in units of UNIT.

    SETUP
          a `<gtk-page-setup>'

    UNIT
          the unit for the return value

    RET
          the right margin


     Since 2.10


 -- Function: gtk-page-setup-set-right-margin (self `<gtk-page-setup>')
          (margin `double') (unit `<gtk-unit>')
 -- Method: set-right-margin
     Sets the right margin of the `<gtk-page-setup>'.

    SETUP
          a `<gtk-page-setup>'

    MARGIN
          the new right margin in units of UNIT

    UNIT
          the units for MARGIN


     Since 2.10


 -- Function: gtk-page-setup-get-paper-width (self `<gtk-page-setup>')
          (unit `<gtk-unit>') =>  (ret `double')
 -- Method: get-paper-width
     Returns the paper width in units of UNIT.

     Note that this function takes orientation, but not margins into
     consideration.  See `gtk-page-setup-get-page-width'.

    SETUP
          a `<gtk-page-setup>'

    UNIT
          the unit for the return value

    RET
          the paper width.


     Since 2.10


 -- Function: gtk-page-setup-get-paper-height (self `<gtk-page-setup>')
          (unit `<gtk-unit>') =>  (ret `double')
 -- Method: get-paper-height
     Returns the paper height in units of UNIT.

     Note that this function takes orientation, but not margins into
     consideration.  See `gtk-page-setup-get-page-height'.

    SETUP
          a `<gtk-page-setup>'

    UNIT
          the unit for the return value

    RET
          the paper height.


     Since 2.10


 -- Function: gtk-page-setup-get-page-width (self `<gtk-page-setup>')
          (unit `<gtk-unit>') =>  (ret `double')
 -- Method: get-page-width
     Returns the page width in units of UNIT.

     Note that this function takes orientation and margins into
     consideration. See `gtk-page-setup-get-paper-width'.

    SETUP
          a `<gtk-page-setup>'

    UNIT
          the unit for the return value

    RET
          the page width.


     Since 2.10


 -- Function: gtk-page-setup-get-page-height (self `<gtk-page-setup>')
          (unit `<gtk-unit>') =>  (ret `double')
 -- Method: get-page-height
     Returns the page height in units of UNIT.

     Note that this function takes orientation and margins into
     consideration. See `gtk-page-setup-get-paper-height'.

    SETUP
          a `<gtk-page-setup>'

    UNIT
          the unit for the return value

    RET
          the page height.


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkPaperSize,  Next: GtkPrinter,  Prev: GtkPageSetup,  Up: Top

113 GtkPaperSize
****************

Support for named paper sizes

113.1 Overview
==============

GtkPaperSize handles paper sizes. It uses the standard called "PWG
5101.1-2002 PWG: Standard for Media Standardized Names" to name the
paper sizes (and to get the data for the page sizes). In addition to
standard paper sizes, GtkPaperSize allows to construct custom paper
sizes with arbitrary dimensions.

   The `<gtk-paper-size>' object stores not only the dimensions (width
and height) of a paper size and its name, it also provides default
print margins.

   Printing support has been added in GTK+ 2.10.

113.2 Usage
===========

 -- Class: <gtk-paper-size>
     Derives from `<gboxed>'.


 -- Function: gtk-paper-size-new (name `mchars') => 
          (ret `<gtk-paper-size>')
     Creates a new `<gtk-paper-size>' object by parsing a PWG
     5101.1-2002 PWG paper name.

     If NAME is ``#f'', the default paper size is returned, see
     `gtk-paper-size-get-default'.

    NAME
          a paper size name, or ``#f''

    RET
          a new `<gtk-paper-size>', use `gtk-paper-size-free' to free it


     Since 2.10


 -- Function: gtk-paper-size-new-from-ppd (ppd_name `mchars')
          (ppd_display_name `mchars') (width `double')
          (height `double') =>  (ret `<gtk-paper-size>')
     Creates a new `<gtk-paper-size>' object by using PPD information.

     If PPD-NAME is not a recognized PPD paper name, PPD-DISPLAY-NAME,
     WIDTH and HEIGHT are used to construct a custom `<gtk-paper-size>'
     object.

    PPD-NAME
          a PPD paper name

    PPD-DISPLAY-NAME
          the corresponding human-readable name

    WIDTH
          the paper width, in points

    HEIGHT
          the paper height in points

    RET
          a new `<gtk-paper-size>', use `gtk-paper-size-free' to free it


     Since 2.10


 -- Function: gtk-paper-size-new-custom (name `mchars')
          (display_name `mchars') (width `double') (height `double')
          (unit `<gtk-unit>') =>  (ret `<gtk-paper-size>')
     Creates a new `<gtk-paper-size>' object with the given parameters.

    NAME
          the paper name

    DISPLAY-NAME
          the human-readable name

    WIDTH
          the paper width, in units of UNIT

    HEIGHT
          the paper height, in units of UNIT

    UNIT
          the unit for WIDTH and HEIGHT

    RET
          a new `<gtk-paper-size>' object, use `gtk-paper-size-free' to
          free it


     Since 2.10


 -- Function: gtk-paper-size-is-equal (self `<gtk-paper-size>')
          (size2 `<gtk-paper-size>') =>  (ret `bool')
     Compares two `<gtk-paper-size>' objects.

    SIZE1
          a `<gtk-paper-size>' object

    SIZE2
          another `<gtk-paper-size>' object

    RET
          ``#t'', if SIZE1 and SIZE2 represent the same paper size


     Since 2.10


 -- Function: gtk-paper-size-get-name (self `<gtk-paper-size>') => 
          (ret `mchars')
     Gets the name of the `<gtk-paper-size>'.

    SIZE
          a `<gtk-paper-size>' object

    RET
          the name of SIZE


     Since 2.10


 -- Function: gtk-paper-size-get-display-name (self `<gtk-paper-size>')
          =>  (ret `mchars')
     Gets the human-readable name of the `<gtk-paper-size>'.

    SIZE
          a `<gtk-paper-size>' object

    RET
          the human-readable name of SIZE


     Since 2.10


 -- Function: gtk-paper-size-get-ppd-name (self `<gtk-paper-size>') => 
          (ret `mchars')
     Gets the PPD name of the `<gtk-paper-size>', which may be ``#f''.

    SIZE
          a `<gtk-paper-size>' object

    RET
          the PPD name of SIZE


     Since 2.10


 -- Function: gtk-paper-size-get-width (self `<gtk-paper-size>')
          (unit `<gtk-unit>') =>  (ret `double')
     Gets the paper width of the `<gtk-paper-size>', in units of UNIT.

    SIZE
          a `<gtk-paper-size>' object

    UNIT
          the unit for the return value

    RET
          the paper width


     Since 2.10


 -- Function: gtk-paper-size-get-height (self `<gtk-paper-size>')
          (unit `<gtk-unit>') =>  (ret `double')
     Gets the paper height of the `<gtk-paper-size>', in units of UNIT.

    SIZE
          a `<gtk-paper-size>' object

    UNIT
          the unit for the return value

    RET
          the paper height


     Since 2.10


 -- Function: gtk-paper-size-is-custom (self `<gtk-paper-size>') => 
          (ret `bool')
     Returns ``#t'' if SIZE is not a standard paper size.

    SIZE
          a `<gtk-paper-size>' object

    RET
          whether SIZE is a custom paper size.



 -- Function: gtk-paper-size-set-size (self `<gtk-paper-size>')
          (width `double') (height `double') (unit `<gtk-unit>')
     Changes the dimensions of a SIZE to WIDTH x HEIGHT.

    SIZE
          a custom `<gtk-paper-size>' object

    WIDTH
          the new width in units of UNIT

    HEIGHT
          the new height in units of UNIT

    UNIT
          the unit for WIDTH and HEIGHT


     Since 2.10


 -- Function: gtk-paper-size-get-default =>  (ret `mchars')
     Returns the name of the default paper size, which depends on the
     current locale.

    RET
          the name of the default paper size. The string is owned by
          GTK+ and should not be modified.


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkPrinter,  Next: GtkPrintJob,  Prev: GtkPaperSize,  Up: Top

114 GtkPrinter
**************

Represents a printer

114.1 Overview
==============

A `<gtk-printer>' object represents a printer. You only need to deal
directly with printers if you use the non-portable
`<gtk-print-unix-dialog>' API.

   A `<gtk-printer>' allows to get status information about the
printer, such as its description, its location, the number of queued
jobs, etc. Most importantly, a `<gtk-printer>' object can be used to
create a `<gtk-print-job>' object, which lets you print to the printer.

   Printing support was added in GTK+ 2.10.

114.2 Usage
===========


File: guile-gnome-gtk.info,  Node: GtkPrintJob,  Next: GtkPrintUnixDialog,  Prev: GtkPrinter,  Up: Top

115 GtkPrintJob
***************

Represents a print job

115.1 Overview
==============

A `<gtk-print-job>' object represents a job that is sent to a printer.
You only need to deal directly with print jobs if you use the
non-portable `<gtk-print-unix-dialog>' API.

   Use `gtk-print-job-get-surface' to obtain the cairo surface onto
which the pages must be drawn. Use `gtk-print-job-send' to send the
finished job to the printer. If you don't use cairo `<gtk-print-job>'
also supports printing of manually generated postscript, via
`gtk-print-job-set-source-file'.

   Printing support was added in GTK+ 2.10.

115.2 Usage
===========

