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: GtkTextBuffer,  Next: GtkTextTag,  Prev: GtkTextMark,  Up: Top

28 GtkTextBuffer
****************

Stores attributed text for display in a

28.1 Overview
=============

You may wish to begin by reading the text widget conceptual overview
which gives an overview of all the objects and data types related to
the text widget and how they work together.

28.2 Usage
==========

 -- Class: <gtk-text-buffer>
     Derives from `<gobject>'.

     This class defines the following properties:

    `tag-table'
          Text Tag Table

    `text'
          Current text of the buffer

    `has-selection'
          Whether the buffer has some text currently selected

    `cursor-position'
          The position of the insert mark (as offset from the beginning
          of the buffer)

    `copy-target-list'
          The list of targets this buffer supports for clipboard
          copying and DND source

    `paste-target-list'
          The list of targets this buffer supports for clipboard
          pasting and DND destination



 -- Signal on <gtk-text-buffer>: changed
     The changed signal is emitted when the content of a
     `<gtk-text-buffer>' has changed.


 -- Signal on <gtk-text-buffer>: insert-text (arg0 `<gtk-text-iter>')
          (arg1 `<gchararray>') (arg2 `<gint>')
     The insert_text signal is emitted to insert text in a
     `<gtk-text-buffer>'.  Insertion actually occurs in the default
     handler.

     Note that if your handler runs before the default handler it must
     not invalidate the LOCATION iter (or has to revalidate it). The
     default signal handler revalidates it to point to the end of the
     inserted text.

     See also: `gtk-text-buffer-insert', `gtk-text-buffer-insert-range'.


 -- Signal on <gtk-text-buffer>: insert-pixbuf (arg0 `<gtk-text-iter>')
          (arg1 `<gdk-pixbuf>')
     The insert_pixbuf signal is emitted to insert a `<gdk-pixbuf>' in a
     `<gtk-text-buffer>'. Insertion actually occurs in the default
     handler.

     Note that if your handler runs before the default handler it must
     not invalidate the LOCATION iter (or has to revalidate it). The
     default signal handler revalidates it to be placed after the
     inserted PIXBUF.

     See also: `gtk-text-buffer-insert-pixbuf'.


 -- Signal on <gtk-text-buffer>: insert-child-anchor
          (arg0 `<gtk-text-iter>') (arg1 `<gtk-text-child-anchor>')
     The insert_child_anchor signal is emitted to insert a
     `<gtk-text-child-anchor>' in a `<gtk-text-buffer>'. Insertion
     actually occurs in the default handler.

     Note that if your handler runs before the default handler it must
     not invalidate the LOCATION iter (or has to revalidate it). The
     default signal handler revalidates it to be placed after the
     inserted ANCHOR.

     See also: `gtk-text-buffer-insert-child-anchor'.


 -- Signal on <gtk-text-buffer>: delete-range (arg0 `<gtk-text-iter>')
          (arg1 `<gtk-text-iter>')
     The delete_range signal is emitted to delete a range from a
     `<gtk-text-buffer>'.

     Note that if your handler runs before the default handler it must
     not invalidate the START and END iters (or has to revalidate
     them). The default signal handler revalidates the START and END
     iters to both point point to the location where text was deleted.
     Handlers which run after the default handler (see
     `g-signal-connect-after') do not have access to the deleted text.

     See also: `gtk-text-buffer-delete'.


 -- Signal on <gtk-text-buffer>: modified-changed
     The modified_changed signal is emitted when the modified bit of a
     `<gtk-text-buffer>' flips.

     See also: `gtk-text-buffer-set-modified'.


 -- Signal on <gtk-text-buffer>: mark-set (arg0 `<gtk-text-iter>')
          (arg1 `<gtk-text-mark>')
     The mark_set signal is emitted as notification after a
     `<gtk-text-mark>' is set.

     See also: `gtk-text-buffer-create-mark',
     `gtk-text-buffer-move-mark'.


 -- Signal on <gtk-text-buffer>: mark-deleted (arg0 `<gtk-text-mark>')
     The mark_deleted signal is emitted as notification after a
     `<gtk-text-mark>' is deleted.

     See also: `gtk-text-buffer-delete-mark'.


 -- Signal on <gtk-text-buffer>: apply-tag (arg0 `<gtk-text-tag>')
          (arg1 `<gtk-text-iter>') (arg2 `<gtk-text-iter>')
     The apply_tag signal is emitted to apply a tag to a range of text
     in a `<gtk-text-buffer>'. Applying actually occurs in the default
     handler.

     Note that if your handler runs before the default handler it must
     not invalidate the START and END iters (or has to revalidate them).

     See also: `gtk-text-buffer-apply-tag',
     `gtk-text-buffer-insert-with-tags', `gtk-text-buffer-insert-range'.


 -- Signal on <gtk-text-buffer>: remove-tag (arg0 `<gtk-text-tag>')
          (arg1 `<gtk-text-iter>') (arg2 `<gtk-text-iter>')
     The remove_tag signal is emitted to remove all occurrences of TAG
     from a range of text in a `<gtk-text-buffer>'. Removal actually
     occurs in the default handler.

     Note that if your handler runs before the default handler it must
     not invalidate the START and END iters (or has to revalidate them).

     See also: `gtk-text-buffer-remove-tag'.


 -- Signal on <gtk-text-buffer>: begin-user-action
     The begin_user_action signal is emitted at the beginning of a
     single user-visible operation on a `<gtk-text-buffer>'.

     See also: `gtk-text-buffer-begin-user-action',
     `gtk-text-buffer-insert-interactive',
     `gtk-text-buffer-insert-range-interactive',
     `gtk-text-buffer-delete-interactive', `gtk-text-buffer-backspace',
     `gtk-text-buffer-delete-selection'.


 -- Signal on <gtk-text-buffer>: end-user-action
     The end_user_action signal is emitted at the end of a single
     user-visible operation `<gtk-text-buffer>'.

     See also: `gtk-text-buffer-end-user-action',
     `gtk-text-buffer-insert-interactive',
     `gtk-text-buffer-insert-range-interactive',
     `gtk-text-buffer-delete-interactive', `gtk-text-buffer-backspace',
     `gtk-text-buffer-delete-selection', `gtk-text-buffer-backspace'.


 -- Function: gtk-text-buffer-new (table `<gtk-text-tag-table>') => 
          (ret `<gtk-text-buffer>')
     Creates a new text buffer.

    TABLE
          a tag table, or NULL to create a new one

    RET
          a new text buffer



 -- Function: gtk-text-buffer-get-line-count (self `<gtk-text-buffer>')
          =>  (ret `int')
 -- Method: get-line-count
     Obtains the number of lines in the buffer. This value is cached,
     so the function is very fast.

    BUFFER
          a `<gtk-text-buffer>'

    RET
          number of lines in the buffer



 -- Function: gtk-text-buffer-get-char-count (self `<gtk-text-buffer>')
          =>  (ret `int')
 -- Method: get-char-count
     Gets the number of characters in the buffer; note that characters
     and bytes are not the same, you can't e.g. expect the contents of
     the buffer in string form to be this many bytes long. The
     character count is cached, so this function is very fast.

    BUFFER
          a `<gtk-text-buffer>'

    RET
          number of characters in the buffer



 -- Function: gtk-text-buffer-get-tag-table (self `<gtk-text-buffer>')
          =>  (ret `<gtk-text-tag-table>')
 -- Method: get-tag-table
     Get the `<gtk-text-tag-table>' associated with this buffer.

    BUFFER
          a `<gtk-text-buffer>'

    RET
          the buffer's tag table



 -- Function: gtk-text-buffer-insert (self `<gtk-text-buffer>')
          (iter `<gtk-text-iter>') (stext `scm')
 -- Method: insert
     Inserts LEN bytes of TEXT at position ITER. If LEN is -1, TEXT
     must be nul-terminated and will be inserted in its entirety.
     Emits the "insert_text" signal; insertion actually occurs in the
     default handler for the signal. ITER is invalidated when insertion
     occurs (because the buffer contents change), but the default
     signal handler revalidates it to point to the end of the inserted
     text.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          a position in the buffer

    TEXT
          UTF-8 format text to insert

    LEN
          length of text in bytes, or -1



 -- Function: gtk-text-buffer-insert-at-cursor
          (self `<gtk-text-buffer>') (stext `scm')
 -- Method: insert-at-cursor
     Simply calls `gtk-text-buffer-insert', using the current cursor
     position as the insertion point.

    BUFFER
          a `<gtk-text-buffer>'

    TEXT
          some text in UTF-8 format

    LEN
          length of text, in bytes



 -- Function: gtk-text-buffer-insert-interactive
          (self `<gtk-text-buffer>') (iter `<gtk-text-iter>')
          (stext `scm') (default_editable `bool') =>  (ret `bool')
 -- Method: insert-interactive
     Like `gtk-text-buffer-insert', but the insertion will not occur if
     ITER is at a non-editable location in the buffer. Usually you want
     to prevent insertions at ineditable locations if the insertion
     results from a user action (is interactive).

     DEFAULT-EDITABLE indicates the editability of text that doesn't
     have a tag affecting editability applied to it. Typically the
     result of `gtk-text-view-get-editable' is appropriate here.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          a position in BUFFER

    TEXT
          some UTF-8 text

    LEN
          length of text in bytes, or -1

    DEFAULT-EDITABLE
          default editability of buffer

    RET
          whether text was actually inserted



 -- Function: gtk-text-buffer-insert-range (self `<gtk-text-buffer>')
          (iter `<gtk-text-iter>') (start `<gtk-text-iter>')
          (end `<gtk-text-iter>')
 -- Method: insert-range
     Copies text, tags, and pixbufs between START and END (the order of
     START and END doesn't matter) and inserts the copy at ITER.  Used
     instead of simply getting/inserting text because it preserves
     images and tags. If START and END are in a different buffer from
     BUFFER, the two buffers must share the same tag table.

     Implemented via emissions of the insert_text and apply_tag
     signals, so expect those.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          a position in BUFFER

    START
          a position in a `<gtk-text-buffer>'

    END
          another position in the same buffer as START



 -- Function: gtk-text-buffer-insert-with-tags
          (self `<gtk-text-buffer>') (iter `<gtk-text-iter>')
          (stext `scm') (tag_list `glist-of')
 -- Method: insert-with-tags
     Inserts TEXT into BUFFER at ITER, applying the list of tags to the
     newly-inserted text. The last tag specified must be NULL to
     terminate the list. Equivalent to calling
     `gtk-text-buffer-insert', then `gtk-text-buffer-apply-tag' on the
     inserted text; `gtk-text-buffer-insert-with-tags' is just a
     convenience function.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          an iterator in BUFFER

    TEXT
          UTF-8 text

    LEN
          length of TEXT, or -1

    FIRST-TAG
          first tag to apply to TEXT

    ...
          NULL-terminated list of tags to apply



 -- Function: gtk-text-buffer-delete (self `<gtk-text-buffer>')
          (start `<gtk-text-iter>') (end `<gtk-text-iter>')
 -- Method: delete
     Deletes text between START and END. The order of START and END is
     not actually relevant; `gtk-text-buffer-delete' will reorder them.
     This function actually emits the "delete_range" signal, and the
     default handler of that signal deletes the text. Because the
     buffer is modified, all outstanding iterators become invalid after
     calling this function; however, the START and END will be
     re-initialized to point to the location where text was deleted.

    BUFFER
          a `<gtk-text-buffer>'

    START
          a position in BUFFER

    END
          another position in BUFFER



 -- Function: gtk-text-buffer-delete-interactive
          (self `<gtk-text-buffer>') (start_iter `<gtk-text-iter>')
          (end_iter `<gtk-text-iter>') (default_editable `bool') => 
          (ret `bool')
 -- Method: delete-interactive
     Deletes all _editable_ text in the given range. Calls
     `gtk-text-buffer-delete' for each editable sub-range of
     [START,END). START and END are revalidated to point to the
     location of the last deleted range, or left untouched if no text
     was deleted.

    BUFFER
          a `<gtk-text-buffer>'

    START-ITER
          start of range to delete

    END-ITER
          end of range

    DEFAULT-EDITABLE
          whether the buffer is editable by default

    RET
          whether some text was actually deleted



 -- Function: gtk-text-buffer-backspace (self `<gtk-text-buffer>')
          (iter `<gtk-text-iter>') (interactive `bool')
          (default_editable `bool') =>  (ret `bool')
 -- Method: backspace
     Performs the appropriate action as if the user hit the delete key
     with the cursor at the position specified by ITER. In the normal
     case a single character will be deleted, but when combining
     accents are involved, more than one character can be deleted, and
     when precomposed character and accent combinations are involved,
     less than one character will be deleted.

     Because the buffer is modified, all outstanding iterators become
     invalid after calling this function; however, the ITER will be
     re-initialized to point to the location where text was deleted.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          a position in BUFFER

    INTERACTIVE
          whether the deletion is caused by user interaction

    DEFAULT-EDITABLE
          whether the buffer is editable by default

    RET
          ``#t'' if the buffer was modified


     Since 2.6


 -- Function: gtk-text-buffer-set-text (self `<gtk-text-buffer>')
          (stext `scm')
 -- Method: set-text
     Deletes current contents of BUFFER, and inserts TEXT instead. If
     LEN is -1, TEXT must be nul-terminated. TEXT must be valid UTF-8.

    BUFFER
          a `<gtk-text-buffer>'

    TEXT
          UTF-8 text to insert

    LEN
          length of TEXT in bytes



 -- Function: gtk-text-buffer-get-text (self `<gtk-text-buffer>')
          (start `<gtk-text-iter>') (end `<gtk-text-iter>')
          (include_hidden_chars `bool') =>  (ret `mchars')
 -- Method: get-text
     Returns the text in the range [START,END). Excludes undisplayed
     text (text marked with tags that set the invisibility attribute) if
     INCLUDE-HIDDEN-CHARS is ``#f''. Does not include characters
     representing embedded images, so byte and character indexes into
     the returned string do _not_ correspond to byte and character
     indexes into the buffer.  Contrast with
     `gtk-text-buffer-get-slice'.

    BUFFER
          a `<gtk-text-buffer>'

    START
          start of a range

    END
          end of a range

    INCLUDE-HIDDEN-CHARS
          whether to include invisible text

    RET
          an allocated UTF-8 string



 -- Function: gtk-text-buffer-get-slice (self `<gtk-text-buffer>')
          (start `<gtk-text-iter>') (end `<gtk-text-iter>')
          (include_hidden_chars `bool') =>  (ret `mchars')
 -- Method: get-slice
     Returns the text in the range [START,END). Excludes undisplayed
     text (text marked with tags that set the invisibility attribute) if
     INCLUDE-HIDDEN-CHARS is ``#f''. The returned string includes a
     0xFFFC character whenever the buffer contains embedded images, so
     byte and character indexes into the returned string _do_
     correspond to byte and character indexes into the buffer. Contrast
     with `gtk-text-buffer-get-text'. Note that 0xFFFC can occur in
     normal text as well, so it is not a reliable indicator that a
     pixbuf or widget is in the buffer.

    BUFFER
          a `<gtk-text-buffer>'

    START
          start of a range

    END
          end of a range

    INCLUDE-HIDDEN-CHARS
          whether to include invisible text

    RET
          an allocated UTF-8 string



 -- Function: gtk-text-buffer-insert-pixbuf (self `<gtk-text-buffer>')
          (iter `<gtk-text-iter>') (pixbuf `<gdk-pixbuf>')
 -- Method: insert-pixbuf
     Inserts an image into the text buffer at ITER. The image will be
     counted as one character in character counts, and when obtaining
     the buffer contents as a string, will be represented by the
     Unicode "object replacement character" 0xFFFC. Note that the
     "slice" variants for obtaining portions of the buffer as a string
     include this character for pixbufs, but the "text" variants do
     not. e.g.  see `gtk-text-buffer-get-slice' and
     `gtk-text-buffer-get-text'.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          location to insert the pixbuf

    PIXBUF
          a `<gdk-pixbuf>'



 -- Function: gtk-text-buffer-insert-child-anchor
          (self `<gtk-text-buffer>') (iter `<gtk-text-iter>')
          (anchor `<gtk-text-child-anchor>')
 -- Method: insert-child-anchor
     Inserts a child widget anchor into the text buffer at ITER. The
     anchor will be counted as one character in character counts, and
     when obtaining the buffer contents as a string, will be
     represented by the Unicode "object replacement character" 0xFFFC.
     Note that the "slice" variants for obtaining portions of the
     buffer as a string include this character for child anchors, but
     the "text" variants do not. e.g. see `gtk-text-buffer-get-slice'
     and `gtk-text-buffer-get-text'. Consider
     `gtk-text-buffer-create-child-anchor' as a more convenient
     alternative to this function. The buffer will add a reference to
     the anchor, so you can unref it after insertion.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          location to insert the anchor

    ANCHOR
          a `<gtk-text-child-anchor>'



 -- Function: gtk-text-buffer-create-child-anchor
          (self `<gtk-text-buffer>') (iter `<gtk-text-iter>') => 
          (ret `<gtk-text-child-anchor>')
 -- Method: create-child-anchor
     This is a convenience function which simply creates a child anchor
     with `gtk-text-child-anchor-new' and inserts it into the buffer
     with `gtk-text-buffer-insert-child-anchor'. The new anchor is
     owned by the buffer; no reference count is returned to the caller
     of `gtk-text-buffer-create-child-anchor'.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          location in the buffer

    RET
          the created child anchor



 -- Function: gtk-text-buffer-create-mark (self `<gtk-text-buffer>')
          (mark_name `mchars') (where `<gtk-text-iter>')
          (left_gravity `bool') =>  (ret `<gtk-text-mark>')
 -- Method: create-mark
     Creates a mark at position WHERE. If MARK-NAME is ``#f'', the mark
     is anonymous; otherwise, the mark can be retrieved by name using
     `gtk-text-buffer-get-mark'. If a mark has left gravity, and text is
     inserted at the mark's current location, the mark will be moved to
     the left of the newly-inserted text. If the mark has right gravity
     (LEFT-GRAVITY = ``#f''), the mark will end up on the right of
     newly-inserted text. The standard left-to-right cursor is a mark
     with right gravity (when you type, the cursor stays on the right
     side of the text you're typing).

     The caller of this function does _not_ own a reference to the
     returned `<gtk-text-mark>', so you can ignore the return value if
     you like. Marks are owned by the buffer and go away when the
     buffer does.

     Emits the "mark_set" signal as notification of the mark's initial
     placement.

    BUFFER
          a `<gtk-text-buffer>'

    MARK-NAME
          name for mark, or ``#f''

    WHERE
          location to place mark

    LEFT-GRAVITY
          whether the mark has left gravity

    RET
          the new `<gtk-text-mark>' object



 -- Function: gtk-text-buffer-move-mark (self `<gtk-text-buffer>')
          (mark `<gtk-text-mark>') (where `<gtk-text-iter>')
 -- Method: move-mark
     Moves MARK to the new location WHERE. Emits the "mark_set" signal
     as notification of the move.

    BUFFER
          a `<gtk-text-buffer>'

    MARK
          a `<gtk-text-mark>'

    WHERE
          new location for MARK in BUFFER



 -- Function: gtk-text-buffer-move-mark-by-name
          (self `<gtk-text-buffer>') (name `mchars')
          (where `<gtk-text-iter>')
 -- Method: move-mark-by-name
     Moves the mark named NAME (which must exist) to location WHERE. See
     `gtk-text-buffer-move-mark' for details.

    BUFFER
          a `<gtk-text-buffer>'

    NAME
          name of a mark

    WHERE
          new location for mark



 -- Function: gtk-text-buffer-delete-mark (self `<gtk-text-buffer>')
          (mark `<gtk-text-mark>')
 -- Method: delete-mark
     Deletes MARK, so that it's no longer located anywhere in the
     buffer.  Removes the reference the buffer holds to the mark, so if
     you haven't called `g-object-ref' on the mark, it will be freed.
     Even if the mark isn't freed, most operations on MARK become
     invalid. There is no way to undelete a mark.
     `gtk-text-mark-get-deleted' will return TRUE after this function
     has been called on a mark; `gtk-text-mark-get-deleted' indicates
     that a mark no longer belongs to a buffer. The "mark_deleted"
     signal will be emitted as notification after the mark is deleted.

    BUFFER
          a `<gtk-text-buffer>'

    MARK
          a `<gtk-text-mark>' in BUFFER



 -- Function: gtk-text-buffer-delete-mark-by-name
          (self `<gtk-text-buffer>') (name `mchars')
 -- Method: delete-mark-by-name
     Deletes the mark named NAME; the mark must exist. See
     `gtk-text-buffer-delete-mark' for details.

    BUFFER
          a `<gtk-text-buffer>'

    NAME
          name of a mark in BUFFER



 -- Function: gtk-text-buffer-get-mark (self `<gtk-text-buffer>')
          (name `mchars') =>  (ret `<gtk-text-mark>')
 -- Method: get-mark
     Returns the mark named NAME in buffer BUFFER, or NULL if no such
     mark exists in the buffer.

    BUFFER
          a `<gtk-text-buffer>'

    NAME
          a mark name

    RET
          a `<gtk-text-mark>', or NULL



 -- Function: gtk-text-buffer-get-insert (self `<gtk-text-buffer>') => 
          (ret `<gtk-text-mark>')
 -- Method: get-insert
     Returns the mark that represents the cursor (insertion point).
     Equivalent to calling `gtk-text-buffer-get-mark' to get the mark
     named "insert", but very slightly more efficient, and involves
     less typing.

    BUFFER
          a `<gtk-text-buffer>'

    RET
          insertion point mark



 -- Function: gtk-text-buffer-get-selection-bound
          (self `<gtk-text-buffer>') =>  (ret `<gtk-text-mark>')
 -- Method: get-selection-bound
     Returns the mark that represents the selection bound. Equivalent
     to calling `gtk-text-buffer-get-mark' to get the mark named
     "selection_bound", but very slightly more efficient, and involves
     less typing.

     The currently-selected text in BUFFER is the region between the
     "selection_bound" and "insert" marks. If "selection_bound" and
     "insert" are in the same place, then there is no current selection.
     `gtk-text-buffer-get-selection-bounds' is another convenient
     function for handling the selection, if you just want to know
     whether there's a selection and what its bounds are.

    BUFFER
          a `<gtk-text-buffer>'

    RET
          selection bound mark



 -- Function: gtk-text-buffer-get-has-selection
          (self `<gtk-text-buffer>') =>  (ret `bool')
 -- Method: get-has-selection
     Indicates whether the buffer has some text currently selected.

    BUFFER
          a `<gtk-text-buffer>'

    RET
          ``#t'' if the there is text selected


     Since 2.10


 -- Function: gtk-text-buffer-place-cursor (self `<gtk-text-buffer>')
          (where `<gtk-text-iter>')
 -- Method: place-cursor
     This function moves the "insert" and "selection_bound" marks
     simultaneously. If you move them to the same place in two steps
     with `gtk-text-buffer-move-mark', you will temporarily select a
     region in between their old and new locations, which can be pretty
     inefficient since the temporarily-selected region will force stuff
     to be recalculated. This function moves them as a unit, which can
     be optimized.

    BUFFER
          a `<gtk-text-buffer>'

    WHERE
          where to put the cursor



 -- Function: gtk-text-buffer-select-range (self `<gtk-text-buffer>')
          (ins `<gtk-text-iter>') (bound `<gtk-text-iter>')
 -- Method: select-range
     This function moves the "insert" and "selection_bound" marks
     simultaneously. If you move them in two steps with
     `gtk-text-buffer-move-mark', you will temporarily select a region
     in between their old and new locations, which can be pretty
     inefficient since the temporarily-selected region will force stuff
     to be recalculated. This function moves them as a unit, which can
     be optimized.

    BUFFER
          a `<gtk-text-buffer>'

    INS
          where to put the "insert" mark

    BOUND
          where to put the "selection_bound" mark


     Since 2.4


 -- Function: gtk-text-buffer-apply-tag (self `<gtk-text-buffer>')
          (tag `<gtk-text-tag>') (start `<gtk-text-iter>')
          (end `<gtk-text-iter>')
 -- Method: apply-tag
     Emits the "apply_tag" signal on BUFFER. The default handler for
     the signal applies TAG to the given range. START and END do not
     have to be in order.

    BUFFER
          a `<gtk-text-buffer>'

    TAG
          a `<gtk-text-tag>'

    START
          one bound of range to be tagged

    END
          other bound of range to be tagged



 -- Function: gtk-text-buffer-remove-tag (self `<gtk-text-buffer>')
          (tag `<gtk-text-tag>') (start `<gtk-text-iter>')
          (end `<gtk-text-iter>')
 -- Method: remove-tag
     Emits the "remove_tag" signal. The default handler for the signal
     removes all occurrences of TAG from the given range. START and END
     don't have to be in order.

    BUFFER
          a `<gtk-text-buffer>'

    TAG
          a `<gtk-text-tag>'

    START
          one bound of range to be untagged

    END
          other bound of range to be untagged



 -- Function: gtk-text-buffer-apply-tag-by-name
          (self `<gtk-text-buffer>') (name `mchars')
          (start `<gtk-text-iter>') (end `<gtk-text-iter>')
 -- Method: apply-tag-by-name
     Calls `gtk-text-tag-table-lookup' on the buffer's tag table to get
     a `<gtk-text-tag>', then calls `gtk-text-buffer-apply-tag'.

    BUFFER
          a `<gtk-text-buffer>'

    NAME
          name of a named `<gtk-text-tag>'

    START
          one bound of range to be tagged

    END
          other bound of range to be tagged



 -- Function: gtk-text-buffer-remove-tag-by-name
          (self `<gtk-text-buffer>') (name `mchars')
          (start `<gtk-text-iter>') (end `<gtk-text-iter>')
 -- Method: remove-tag-by-name
     Calls `gtk-text-tag-table-lookup' on the buffer's tag table to get
     a `<gtk-text-tag>', then calls `gtk-text-buffer-remove-tag'.

    BUFFER
          a `<gtk-text-buffer>'

    NAME
          name of a `<gtk-text-tag>'

    START
          one bound of range to be untagged

    END
          other bound of range to be untagged



 -- Function: gtk-text-buffer-remove-all-tags
          (self `<gtk-text-buffer>') (start `<gtk-text-iter>')
          (end `<gtk-text-iter>')
 -- Method: remove-all-tags
     Removes all tags in the range between START and END. Be careful
     with this function; it could remove tags added in code unrelated
     to the code you're currently writing. That is, using this function
     is probably a bad idea if you have two or more unrelated code
     sections that add tags.

    BUFFER
          a `<gtk-text-buffer>'

    START
          one bound of range to be untagged

    END
          other bound of range to be untagged



 -- Function: gtk-text-buffer-get-iter-at-offset
          (self `<gtk-text-buffer>') (char_offset `int') => 
          (ret `<gtk-text-iter>')
 -- Method: get-iter-at-offset
     Initializes ITER to a position CHAR-OFFSET chars from the start of
     the entire buffer. If CHAR-OFFSET is -1 or greater than the number
     of characters in the buffer, ITER is initialized to the end
     iterator, the iterator one past the last valid character in the
     buffer.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          iterator to initialize

    CHAR-OFFSET
          char offset from start of buffer, counting from 0, or -1



 -- Function: gtk-text-buffer-get-iter-at-line
          (self `<gtk-text-buffer>') (line_number `int') => 
          (ret `<gtk-text-iter>')
 -- Method: get-iter-at-line
     Initializes ITER to the start of the given line.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          iterator to initialize

    LINE-NUMBER
          line number counting from 0



 -- Function: gtk-text-buffer-get-iter-at-mark
          (self `<gtk-text-buffer>') (mark `<gtk-text-mark>') => 
          (ret `<gtk-text-iter>')
 -- Method: get-iter-at-mark
     Initializes ITER with the current position of MARK.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          iterator to initialize

    MARK
          a `<gtk-text-mark>' in BUFFER



 -- Function: gtk-text-buffer-get-start-iter (self `<gtk-text-buffer>')
          =>  (ret `<gtk-text-iter>')
 -- Method: get-start-iter
     Initialized ITER with the first position in the text buffer. This
     is the same as using `gtk-text-buffer-get-iter-at-offset' to get
     the iter at character offset 0.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          iterator to initialize



 -- Function: gtk-text-buffer-get-end-iter (self `<gtk-text-buffer>')
          =>  (ret `<gtk-text-iter>')
 -- Method: get-end-iter
     Initializes ITER with the "end iterator," one past the last valid
     character in the text buffer. If dereferenced with
     `gtk-text-iter-get-char', the end iterator has a character value
     of 0. The entire buffer lies in the range from the first position
     in the buffer (call `gtk-text-buffer-get-start-iter' to get
     character position 0) to the end iterator.

    BUFFER
          a `<gtk-text-buffer>'

    ITER
          iterator to initialize



 -- Function: gtk-text-buffer-get-bounds (self `<gtk-text-buffer>') => 
          (start `<gtk-text-iter>') (end `<gtk-text-iter>')
 -- Method: get-bounds
 -- Method: get-bounds
     Retrieves the first and last iterators in the buffer, i.e. the
     entire buffer lies within the range [START,END).

    BUFFER
          a `<gtk-text-buffer>'

    START
          iterator to initialize with first position in the buffer

    END
          iterator to initialize with the end iterator



 -- Function: gtk-text-buffer-get-modified (self `<gtk-text-buffer>')
          =>  (ret `bool')
 -- Method: get-modified
     Indicates whether the buffer has been modified since the last call
     to `gtk-text-buffer-set-modified' set the modification flag to
     ``#f''. Used for example to enable a "save" function in a text
     editor.

    BUFFER
          a `<gtk-text-buffer>'

    RET
          ``#t'' if the buffer has been modified



 -- Function: gtk-text-buffer-set-modified (self `<gtk-text-buffer>')
          (setting `bool')
 -- Method: set-modified
     Used to keep track of whether the buffer has been modified since
     the last time it was saved. Whenever the buffer is saved to disk,
     call gtk_text_buffer_set_modified (BUFFER, FALSE). When the buffer
     is modified, it will automatically toggled on the modified bit
     again. When the modified bit flips, the buffer emits a
     "modified_changed" signal.

    BUFFER
          a `<gtk-text-buffer>'

    SETTING
          modification flag setting



 -- Function: gtk-text-buffer-delete-selection
          (self `<gtk-text-buffer>') (interactive `bool')
          (default_editable `bool') =>  (ret `bool')
 -- Method: delete-selection
     Deletes the range between the "insert" and "selection_bound"
     marks, that is, the currently-selected text. If INTERACTIVE is
     ``#t'', the editability of the selection will be considered (users
     can't delete uneditable text).

    BUFFER
          a `<gtk-text-buffer>'

    INTERACTIVE
          whether the deletion is caused by user interaction

    DEFAULT-EDITABLE
          whether the buffer is editable by default

    RET
          whether there was a non-empty selection to delete



 -- Function: gtk-text-buffer-paste-clipboard
          (self `<gtk-text-buffer>') (clipboard `<gtk-clipboard>')
          (override_location `<gtk-text-iter>')
          (default_editable `bool')
 -- Method: paste-clipboard
     Pastes the contents of a clipboard at the insertion point, or at
     OVERRIDE-LOCATION. (Note: pasting is asynchronous, that is, we'll
     ask for the paste data and return, and at some point later after
     the main loop runs, the paste data will be inserted.)

    BUFFER
          a `<gtk-text-buffer>'

    CLIPBOARD
          the `<gtk-clipboard>' to paste from

    OVERRIDE-LOCATION
          location to insert pasted text, or ``#f'' for at the cursor

    DEFAULT-EDITABLE
          whether the buffer is editable by default



 -- Function: gtk-text-buffer-copy-clipboard (self `<gtk-text-buffer>')
          (clipboard `<gtk-clipboard>')
 -- Method: copy-clipboard
     Copies the currently-selected text to a clipboard.

    BUFFER
          a `<gtk-text-buffer>'

    CLIPBOARD
          the `<gtk-clipboard>' object to copy to.



 -- Function: gtk-text-buffer-cut-clipboard (self `<gtk-text-buffer>')
          (clipboard `<gtk-clipboard>') (default_editable `bool')
 -- Method: cut-clipboard
     Copies the currently-selected text to a clipboard, then deletes
     said text if it's editable.

    BUFFER
          a `<gtk-text-buffer>'

    CLIPBOARD
          the `<gtk-clipboard>' object to cut to.

    DEFAULT-EDITABLE
          default editability of the buffer



 -- Function: gtk-text-buffer-begin-user-action
          (self `<gtk-text-buffer>')
 -- Method: begin-user-action
     Called to indicate that the buffer operations between here and a
     call to `gtk-text-buffer-end-user-action' are part of a single
     user-visible operation. The operations between
     `gtk-text-buffer-begin-user-action' and
     `gtk-text-buffer-end-user-action' can then be grouped when
     creating an undo stack. `<gtk-text-buffer>' maintains a count of
     calls to `gtk-text-buffer-begin-user-action' that have not been
     closed with a call to `gtk-text-buffer-end-user-action', and emits
     the "begin_user_action" and "end_user_action" signals only for the
     outermost pair of calls. This allows you to build user actions
     from other user actions.

     The "interactive" buffer mutation functions, such as
     `gtk-text-buffer-insert-interactive', automatically call begin/end
     user action around the buffer operations they perform, so there's
     no need to add extra calls if you user action consists solely of a
     single call to one of those functions.

    BUFFER
          a `<gtk-text-buffer>'



 -- Function: gtk-text-buffer-end-user-action (self `<gtk-text-buffer>')
 -- Method: end-user-action
     Should be paired with a call to
     `gtk-text-buffer-begin-user-action'. See that function for a full
     explanation.

    BUFFER
          a `<gtk-text-buffer>'




File: guile-gnome-gtk.info,  Node: GtkTextTag,  Next: GtkTextTagTable,  Prev: GtkTextBuffer,  Up: Top

29 GtkTextTag
*************

A tag that can be applied to text in a

29.1 Overview
=============

You may wish to begin by reading the text widget conceptual overview
which gives an overview of all the objects and data types related to
the text widget and how they work together.

   Tags should be in the `<gtk-text-tag-table>' for a given
`<gtk-text-buffer>' before using them with that buffer.

   `gtk-text-buffer-create-tag' is the best way to create tags. See for
numerous examples.

   The "invisible" property was not implemented for GTK+ 2.0; it's
planned to be implemented in future releases.

29.2 Usage
==========

 -- Class: <gtk-text-tag>
     Derives from `<gobject>'.

     This class defines the following properties:

    `name'
          Name used to refer to the text tag. NULL for anonymous tags

    `background'
          Background color as a string

    `foreground'
          Foreground color as a string

    `background-gdk'
          Background color as a (possibly unallocated) GdkColor

    `foreground-gdk'
          Foreground color as a (possibly unallocated) GdkColor

    `background-stipple'
          Bitmap to use as a mask when drawing the text background

    `foreground-stipple'
          Bitmap to use as a mask when drawing the text foreground

    `font'
          Font description as a string, e.g. "Sans Italic 12"

    `font-desc'
          Font description as a PangoFontDescription struct

    `family'
          Name of the font family, e.g. Sans, Helvetica, Times,
          Monospace

    `style'
          Font style as a PangoStyle, e.g. PANGO_STYLE_ITALIC

    `variant'
          Font variant as a PangoVariant, e.g. PANGO_VARIANT_SMALL_CAPS

    `weight'
          Font weight as an integer, see predefined values in
          PangoWeight; for example, PANGO_WEIGHT_BOLD

    `stretch'
          Font stretch as a PangoStretch, e.g. PANGO_STRETCH_CONDENSED

    `size'
          Font size in Pango units

    `size-points'
          Font size in points

    `scale'
          Font size as a scale factor relative to the default font
          size. This properly adapts to theme changes etc. so is
          recommended. Pango predefines some scales such as
          PANGO_SCALE_X_LARGE

    `pixels-above-lines'
          Pixels of blank space above paragraphs

    `pixels-below-lines'
          Pixels of blank space below paragraphs

    `pixels-inside-wrap'
          Pixels of blank space between wrapped lines in a paragraph

    `editable'
          Whether the text can be modified by the user

    `wrap-mode'
          Whether to wrap lines never, at word boundaries, or at
          character boundaries

    `justification'
          Left, right, or center justification

    `direction'
          Text direction, e.g. right-to-left or left-to-right

    `left-margin'
          Width of the left margin in pixels

    `indent'
          Amount to indent the paragraph, in pixels

    `strikethrough'
          Whether to strike through the text

    `right-margin'
          Width of the right margin in pixels

    `underline'
          Style of underline for this text

    `rise'
          Offset of text above the baseline (below the baseline if rise
          is negative) in Pango units

    `background-full-height'
          Whether the background color fills the entire line height or
          only the height of the tagged characters

    `language'
          The language this text is in, as an ISO code. Pango can use
          this as a hint when rendering the text. If not set, an
          appropriate default will be used.

    `tabs'
          Custom tabs for this text

    `invisible'
          Whether this text is hidden.

    `paragraph-background'
          Paragraph background color as a string

    `paragraph-background-gdk'
          Paragraph background color as a (possibly unallocated)
          GdkColor

    `accumulative-margin'
          Whether left and right margins accumulate.

    `background-set'
          Whether this tag affects the background color

    `foreground-set'
          Whether this tag affects the foreground color

    `background-stipple-set'
          Whether this tag affects the background stipple

    `foreground-stipple-set'
          Whether this tag affects the foreground stipple

    `family-set'
          Whether this tag affects the font family

    `style-set'
          Whether this tag affects the font style

    `variant-set'
          Whether this tag affects the font variant

    `weight-set'
          Whether this tag affects the font weight

    `stretch-set'
          Whether this tag affects the font stretch

    `size-set'
          Whether this tag affects the font size

    `scale-set'
          Whether this tag scales the font size by a factor

    `pixels-above-lines-set'
          Whether this tag affects the number of pixels above lines

    `pixels-below-lines-set'
          Whether this tag affects the number of pixels above lines

    `pixels-inside-wrap-set'
          Whether this tag affects the number of pixels between wrapped
          lines

    `editable-set'
          Whether this tag affects text editability

    `wrap-mode-set'
          Whether this tag affects line wrap mode

    `justification-set'
          Whether this tag affects paragraph justification

    `left-margin-set'
          Whether this tag affects the left margin

    `indent-set'
          Whether this tag affects indentation

    `strikethrough-set'
          Whether this tag affects strikethrough

    `right-margin-set'
          Whether this tag affects the right margin

    `underline-set'
          Whether this tag affects underlining

    `rise-set'
          Whether this tag affects the rise

    `background-full-height-set'
          Whether this tag affects background height

    `language-set'
          Whether this tag affects the language the text is rendered as

    `tabs-set'
          Whether this tag affects tabs

    `invisible-set'
          Whether this tag affects text visibility

    `paragraph-background-set'
          Whether this tag affects the paragraph background color



 -- Signal on <gtk-text-tag>: event (arg0 `<gobject>')
          (arg1 `<gdk-event>') (arg2 `<gtk-text-iter>') => `<gboolean>'

 -- Class: <gtk-text-attributes>
     Derives from `<gboxed>'.


 -- Function: gtk-text-tag-new (name `mchars') => 
          (ret `<gtk-text-tag>')
     Creates a `<gtk-text-tag>'. Configure the tag using object
     arguments, i.e.  using `g-object-set'.

    NAME
          tag name, or ``#f''

    RET
          a new `<gtk-text-tag>'



 -- Function: gtk-text-tag-get-priority (self `<gtk-text-tag>') => 
          (ret `int')
 -- Method: get-priority
     Get the tag priority.

    TAG
          a `<gtk-text-tag>'

    RET
          The tag's priority.



 -- Function: gtk-text-tag-set-priority (self `<gtk-text-tag>')
          (priority `int')
 -- Method: set-priority
     Sets the priority of a `<gtk-text-tag>'. Valid priorities are
     start at 0 and go to one less than `gtk-text-tag-table-get-size'.
     Each tag in a table has a unique priority; setting the priority of
     one tag shifts the priorities of all the other tags in the table
     to maintain a unique priority for each tag.  Higher priority tags
     "win" if two tags both set the same text attribute. When adding a
     tag to a tag table, it will be assigned the highest priority in the
     table by default; so normally the precedence of a set of tags is
     the order in which they were added to the table, or created with
     `gtk-text-buffer-create-tag', which adds the tag to the buffer's
     table automatically.

    TAG
          a `<gtk-text-tag>'

    PRIORITY
          the new priority



 -- Function: gtk-text-tag-event (self `<gtk-text-tag>')
          (event_object `<gobject>') (event `<gdk-event>')
          (iter `<gtk-text-iter>') =>  (ret `bool')
 -- Method: event
     Emits the "event" signal on the `<gtk-text-tag>'.

    TAG
          a `<gtk-text-tag>'

    EVENT-OBJECT
          object that received the event, such as a widget

    EVENT
          the event

    ITER
          location where the event was received

    RET
          result of signal emission (whether the event was handled)



 -- Function: gtk-text-attributes-new =>  (ret `<gtk-text-attributes>')
     Creates a `<gtk-text-attributes>', which describes a set of
     properties on some text.

    RET
          a new `<gtk-text-attributes>'



 -- Function: gtk-text-attributes-copy (self `<gtk-text-attributes>')
          =>  (ret `<gtk-text-attributes>')
     Copies SRC and returns a new `<gtk-text-attributes>'.

    SRC
          a `<gtk-text-attributes>' to be copied

    RET
          a copy of SRC



 -- Function: gtk-text-attributes-copy-values
          (self `<gtk-text-attributes>') (dest `<gtk-text-attributes>')
     Copies the values from SRC to DEST so that DEST has the same
     values as SRC. Frees existing values in DEST.

    SRC
          a `<gtk-text-attributes>'

    DEST
          another `<gtk-text-attributes>'




File: guile-gnome-gtk.info,  Node: GtkTextTagTable,  Next: GtkTextView,  Prev: GtkTextTag,  Up: Top

30 GtkTextTagTable
******************

Collection of tags that can be used together

30.1 Overview
=============

You may wish to begin by reading the text widget conceptual overview
which gives an overview of all the objects and data types related to
the text widget and how they work together.

30.2 Usage
==========

 -- Class: <gtk-text-tag-table>
     Derives from `<gobject>'.

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


 -- Signal on <gtk-text-tag-table>: tag-changed (arg0 `<gtk-text-tag>')
          (arg1 `<gboolean>')

 -- Signal on <gtk-text-tag-table>: tag-added (arg0 `<gtk-text-tag>')

 -- Signal on <gtk-text-tag-table>: tag-removed (arg0 `<gtk-text-tag>')

 -- Function: gtk-text-tag-table-new =>  (ret `<gtk-text-tag-table>')
     Creates a new `<gtk-text-tag-table>'. The table contains no tags by
     default.

    RET
          a new `<gtk-text-tag-table>'



 -- Function: gtk-text-tag-table-add (self `<gtk-text-tag-table>')
          (tag `<gtk-text-tag>')
 -- Method: add
     Add a tag to the table. The tag is assigned the highest priority
     in the table.

     TAG must not be in a tag table already, and may not have the same
     name as an already-added tag.

    TABLE
          a `<gtk-text-tag-table>'

    TAG
          a `<gtk-text-tag>'



 -- Function: gtk-text-tag-table-remove (self `<gtk-text-tag-table>')
          (tag `<gtk-text-tag>')
 -- Method: remove
     Remove a tag from the table. This will remove the table's
     reference to the tag, so be careful - the tag will end up
     destroyed if you don't have a reference to it.

    TABLE
          a `<gtk-text-tag-table>'

    TAG
          a `<gtk-text-tag>'



 -- Function: gtk-text-tag-table-lookup (self `<gtk-text-tag-table>')
          (name `mchars') =>  (ret `<gtk-text-tag>')
 -- Method: lookup
     Look up a named tag.

    TABLE
          a `<gtk-text-tag-table>'

    NAME
          name of a tag

    RET
          The tag, or ``#f'' if none by that name is in the table.



 -- Function: gtk-text-tag-table-get-size (self `<gtk-text-tag-table>')
          =>  (ret `int')
 -- Method: get-size
     Returns the size of the table (number of tags)

    TABLE
          a `<gtk-text-tag-table>'

    RET
          number of tags in TABLE




File: guile-gnome-gtk.info,  Node: GtkTextView,  Next: GtkTreeModel,  Prev: GtkTextTagTable,  Up: Top

31 GtkTextView
**************

Widget that displays a

31.1 Overview
=============

You may wish to begin by reading the text widget conceptual overview
which gives an overview of all the objects and data types related to
the text widget and how they work together.

31.2 Usage
==========

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

     This class defines the following properties:

    `pixels-above-lines'
          Pixels of blank space above paragraphs

    `pixels-below-lines'
          Pixels of blank space below paragraphs

    `pixels-inside-wrap'
          Pixels of blank space between wrapped lines in a paragraph

    `editable'
          Whether the text can be modified by the user

    `wrap-mode'
          Whether to wrap lines never, at word boundaries, or at
          character boundaries

    `justification'
          Left, right, or center justification

    `left-margin'
          Width of the left margin in pixels

    `right-margin'
          Width of the right margin in pixels

    `indent'
          Amount to indent the paragraph, in pixels

    `tabs'
          Custom tabs for this text

    `cursor-visible'
          If the insertion cursor is shown

    `buffer'
          The buffer which is displayed

    `overwrite'
          Whether entered text overwrites existing contents

    `accepts-tab'
          Whether Tab will result in a tab character being entered



 -- Signal on <gtk-text-view>: move-cursor (arg0 `<gtk-movement-step>')
          (arg1 `<gint>') (arg2 `<gboolean>')
     The ::move-cursor signal is a keybinding signal which gets emitted
     when the user initiates a cursor movement.

     Applications should not connect to it, but may emit it with
     `g-signal-emit-by-name' if they need to control scrolling
     programmatically.


 -- Signal on <gtk-text-view>: copy-clipboard

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

 -- Signal on <gtk-text-view>: insert-at-cursor (arg0 `<gchararray>')

 -- Signal on <gtk-text-view>: delete-from-cursor
          (arg0 `<gtk-delete-type>') (arg1 `<gint>')

 -- Signal on <gtk-text-view>: backspace

 -- Signal on <gtk-text-view>: cut-clipboard

 -- Signal on <gtk-text-view>: paste-clipboard

 -- Signal on <gtk-text-view>: toggle-overwrite

 -- Signal on <gtk-text-view>: set-scroll-adjustments
          (arg0 `<gtk-adjustment>') (arg1 `<gtk-adjustment>')

 -- Signal on <gtk-text-view>: select-all (arg0 `<gboolean>')

 -- Signal on <gtk-text-view>: page-horizontally (arg0 `<gint>')
          (arg1 `<gboolean>')

 -- Signal on <gtk-text-view>: move-viewport (arg0 `<gtk-scroll-step>')
          (arg1 `<gint>')

 -- Signal on <gtk-text-view>: set-anchor

 -- Signal on <gtk-text-view>: toggle-cursor-visible
     undocumented

 -- Class: <gtk-text-child-anchor>
     Derives from `<gobject>'.

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


 -- Function: gtk-text-view-new-with-buffer
          (buffer `<gtk-text-buffer>') =>  (ret `<gtk-widget>')
     Creates a new `<gtk-text-view>' widget displaying the buffer
     BUFFER.  One buffer can be shared among many widgets. BUFFER may
     be NULL to create a default buffer, in which case this function is
     equivalent to `gtk-text-view-new'. The text view adds its own
     reference count to the buffer; it does not take over an existing
     reference.

    BUFFER
          a `<gtk-text-buffer>'

    RET
          a new `<gtk-text-view>'.



 -- Function: gtk-text-view-set-buffer (self `<gtk-text-view>')
          (buffer `<gtk-text-buffer>')
 -- Method: set-buffer
     Sets BUFFER as the buffer being displayed by TEXT-VIEW. The
     previous buffer displayed by the text view is unreferenced, and a
     reference is added to BUFFER. If you owned a reference to BUFFER
     before passing it to this function, you must remove that reference
     yourself; `<gtk-text-view>' will not "adopt" it.

    TEXT-VIEW
          a `<gtk-text-view>'

    BUFFER
          a `<gtk-text-buffer>'



 -- Function: gtk-text-view-get-buffer (self `<gtk-text-view>') => 
          (ret `<gtk-text-buffer>')
 -- Method: get-buffer
     Returns the `<gtk-text-buffer>' being displayed by this text view.
     The reference count on the buffer is not incremented; the caller
     of this function won't own a new reference.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          a `<gtk-text-buffer>'



 -- Function: gtk-text-view-scroll-to-mark (self `<gtk-text-view>')
          (mark `<gtk-text-mark>') (within_margin `double')
          (use_align `bool') (xalign `double') (yalign `double')
 -- Method: scroll-to-mark
     Scrolls TEXT-VIEW so that MARK is on the screen in the position
     indicated by XALIGN and YALIGN. An alignment of 0.0 indicates left
     or top, 1.0 indicates right or bottom, 0.5 means center. If
     USE-ALIGN is ``#f'', the text scrolls the minimal distance to get
     the mark onscreen, possibly not scrolling at all. The effective
     screen for purposes of this function is reduced by a margin of
     size WITHIN-MARGIN.

    TEXT-VIEW
          a `<gtk-text-view>'

    MARK
          a `<gtk-text-mark>'

    WITHIN-MARGIN
          margin as a [0.0,0.5) fraction of screen size

    USE-ALIGN
          whether to use alignment arguments (if ``#f'', just get the
          mark onscreen)

    XALIGN
          horizontal alignment of mark within visible area.

    YALIGN
          vertical alignment of mark within visible area



 -- Function: gtk-text-view-scroll-to-iter (self `<gtk-text-view>')
          (iter `<gtk-text-iter>') (within_margin `double')
          (use_align `bool') (xalign `double') (yalign `double') => 
          (ret `bool')
 -- Method: scroll-to-iter
     Scrolls TEXT-VIEW so that ITER is on the screen in the position
     indicated by XALIGN and YALIGN. An alignment of 0.0 indicates left
     or top, 1.0 indicates right or bottom, 0.5 means center. If
     USE-ALIGN is ``#f'', the text scrolls the minimal distance to get
     the mark onscreen, possibly not scrolling at all. The effective
     screen for purposes of this function is reduced by a margin of
     size WITHIN-MARGIN. NOTE: This function uses the
     currently-computed height of the lines in the text buffer.  Note
     that line heights are computed in an idle handler; so this
     function may not have the desired effect if it's called before the
     height computations. To avoid oddness, consider using
     `gtk-text-view-scroll-to-mark' which saves a point to be scrolled
     to after line validation.

    TEXT-VIEW
          a `<gtk-text-view>'

    ITER
          a `<gtk-text-iter>'

    WITHIN-MARGIN
          margin as a [0.0,0.5) fraction of screen size

    USE-ALIGN
          whether to use alignment arguments (if ``#f'', just get the
          mark onscreen)

    XALIGN
          horizontal alignment of mark within visible area.

    YALIGN
          vertical alignment of mark within visible area

    RET
          ``#t'' if scrolling occurred



 -- Function: gtk-text-view-scroll-mark-onscreen
          (self `<gtk-text-view>') (mark `<gtk-text-mark>')
 -- Method: scroll-mark-onscreen
     Scrolls TEXT-VIEW the minimum distance such that MARK is contained
     within the visible area of the widget.

    TEXT-VIEW
          a `<gtk-text-view>'

    MARK
          a mark in the buffer for TEXT-VIEW



 -- Function: gtk-text-view-move-mark-onscreen (self `<gtk-text-view>')
          (mark `<gtk-text-mark>') =>  (ret `bool')
 -- Method: move-mark-onscreen
     Moves a mark within the buffer so that it's located within the
     currently-visible text area.

    TEXT-VIEW
          a `<gtk-text-view>'

    MARK
          a `<gtk-text-mark>'

    RET
          ``#t'' if the mark moved (wasn't already onscreen)



 -- Function: gtk-text-view-place-cursor-onscreen
          (self `<gtk-text-view>') =>  (ret `bool')
 -- Method: place-cursor-onscreen
     Moves the cursor to the currently visible region of the buffer, it
     it isn't there already.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          TRUE if the cursor had to be moved.



 -- Function: gtk-text-view-get-visible-rect (self `<gtk-text-view>')
          (visible_rect `<gdk-rectangle>')
 -- Method: get-visible-rect
     Fills VISIBLE-RECT with the currently-visible region of the
     buffer, in buffer coordinates. Convert to window coordinates with
     `gtk-text-view-buffer-to-window-coords'.

    TEXT-VIEW
          a `<gtk-text-view>'

    VISIBLE-RECT
          rectangle to fill



 -- Function: gtk-text-view-get-iter-location (self `<gtk-text-view>')
          (iter `<gtk-text-iter>') (location `<gdk-rectangle>')
 -- Method: get-iter-location
     Gets a rectangle which roughly contains the character at ITER. The
     rectangle position is in buffer coordinates; use
     `gtk-text-view-buffer-to-window-coords' to convert these
     coordinates to coordinates for one of the windows in the text view.

    TEXT-VIEW
          a `<gtk-text-view>'

    ITER
          a `<gtk-text-iter>'

    LOCATION
          bounds of the character at ITER



 -- Function: gtk-text-view-get-line-at-y (self `<gtk-text-view>')
          (target_iter `<gtk-text-iter>') (y `int') =>  (line_top `int')
 -- Method: get-line-at-y
     Gets the `<gtk-text-iter>' at the start of the line containing the
     coordinate Y. Y is in buffer coordinates, convert from window
     coordinates with `gtk-text-view-window-to-buffer-coords'. If
     non-``#f'', LINE-TOP will be filled with the coordinate of the top
     edge of the line.

    TEXT-VIEW
          a `<gtk-text-view>'

    TARGET-ITER
          a `<gtk-text-iter>'

    Y
          a y coordinate

    LINE-TOP
          return location for top coordinate of the line



 -- Function: gtk-text-view-get-line-yrange (self `<gtk-text-view>')
          (iter `<gtk-text-iter>') =>  (y `int') (height `int')
 -- Method: get-line-yrange
     Gets the y coordinate of the top of the line containing ITER, and
     the height of the line. The coordinate is a buffer coordinate;
     convert to window coordinates with
     `gtk-text-view-buffer-to-window-coords'.

    TEXT-VIEW
          a `<gtk-text-view>'

    ITER
          a `<gtk-text-iter>'

    Y
          return location for a y coordinate

    HEIGHT
          return location for a height



 -- Function: gtk-text-view-get-iter-at-location
          (self `<gtk-text-view>') (iter `<gtk-text-iter>') (x `int')
          (y `int')
 -- Method: get-iter-at-location
     Retrieves the iterator at buffer coordinates X and Y. Buffer
     coordinates are coordinates for the entire buffer, not just the
     currently-displayed portion. If you have coordinates from an
     event, you have to convert those to buffer coordinates with
     `gtk-text-view-window-to-buffer-coords'.

    TEXT-VIEW
          a `<gtk-text-view>'

    ITER
          a `<gtk-text-iter>'

    X
          x position, in buffer coordinates

    Y
          y position, in buffer coordinates



 -- Function: gtk-text-view-get-window (self `<gtk-text-view>')
          (win `<gtk-text-window-type>') =>  (ret `<gdk-window>')
 -- Method: get-window
     Retrieves the `<gdk-window>' corresponding to an area of the text
     view; possible windows include the overall widget window, child
     windows on the left, right, top, bottom, and the window that
     displays the text buffer. Windows are ``#f'' and nonexistent if
     their width or height is 0, and are nonexistent before the widget
     has been realized.

    TEXT-VIEW
          a `<gtk-text-view>'

    WIN
          window to get

    RET
          a `<gdk-window>', or ``#f''



 -- Function: gtk-text-view-get-window-type (self `<gtk-text-view>')
          (window `<gdk-window>') =>  (ret `<gtk-text-window-type>')
 -- Method: get-window-type
     Usually used to find out which window an event corresponds to. If
     you connect to an event signal on TEXT-VIEW, this function should
     be called on `event->window' to see which window it was.

    TEXT-VIEW
          a `<gtk-text-view>'

    WINDOW
          a window type

    RET
          the window type.



 -- Function: gtk-text-view-forward-display-line
          (self `<gtk-text-view>') (iter `<gtk-text-iter>') => 
          (ret `bool')
 -- Method: forward-display-line
     Moves the given ITER forward by one display (wrapped) line. A
     display line is different from a paragraph. Paragraphs are
     separated by newlines or other paragraph separator characters.
     Display lines are created by line-wrapping a paragraph. If
     wrapping is turned off, display lines and paragraphs will be the
     same. Display lines are divided differently for each view, since
     they depend on the view's width; paragraphs are the same in all
     views, since they depend on the contents of the
     `<gtk-text-buffer>'.

    TEXT-VIEW
          a `<gtk-text-view>'

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER was moved and is not on the end iterator



 -- Function: gtk-text-view-backward-display-line
          (self `<gtk-text-view>') (iter `<gtk-text-iter>') => 
          (ret `bool')
 -- Method: backward-display-line
     Moves the given ITER backward by one display (wrapped) line. A
     display line is different from a paragraph. Paragraphs are
     separated by newlines or other paragraph separator characters.
     Display lines are created by line-wrapping a paragraph. If
     wrapping is turned off, display lines and paragraphs will be the
     same. Display lines are divided differently for each view, since
     they depend on the view's width; paragraphs are the same in all
     views, since they depend on the contents of the
     `<gtk-text-buffer>'.

    TEXT-VIEW
          a `<gtk-text-view>'

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER was moved and is not on the end iterator



 -- Function: gtk-text-view-starts-display-line
          (self `<gtk-text-view>') (iter `<gtk-text-iter>') => 
          (ret `bool')
 -- Method: starts-display-line
     Determines whether ITER is at the start of a display line. See
     `gtk-text-view-forward-display-line' for an explanation of display
     lines vs. paragraphs.

    TEXT-VIEW
          a `<gtk-text-view>'

    ITER
          a `<gtk-text-iter>'

    RET
          ``#t'' if ITER begins a wrapped line



 -- Function: gtk-text-view-move-visually (self `<gtk-text-view>')
          (iter `<gtk-text-iter>') (count `int') =>  (ret `bool')
 -- Method: move-visually
     Move the iterator a given number of characters visually, treating
     it as the strong cursor position. If COUNT is positive, then the
     new strong cursor position will be COUNT positions to the right of
     the old cursor position.  If COUNT is negative then the new strong
     cursor position will be COUNT positions to the left of the old
     cursor position.

     In the presence of bidirection text, the correspondence between
     logical and visual order will depend on the direction of the
     current run, and there may be jumps when the cursor is moved off
     of the end of a run.

    TEXT-VIEW
          a `<gtk-text-view>'

    ITER
          a `<gtk-text-iter>'

    COUNT
          number of characters to move (negative moves left, positive
          moves right)

    RET
          ``#t'' if ITER moved and is not on the end iterator



 -- Function: gtk-text-view-add-child-at-anchor
          (self `<gtk-text-view>') (child `<gtk-widget>')
          (anchor `<gtk-text-child-anchor>')
 -- Method: add-child-at-anchor
     Adds a child widget in the text buffer, at the given ANCHOR.

    TEXT-VIEW
          a `<gtk-text-view>'

    CHILD
          a `<gtk-widget>'

    ANCHOR
          a `<gtk-text-child-anchor>' in the `<gtk-text-buffer>' for
          TEXT-VIEW



 -- Function: gtk-text-child-anchor-new => 
          (ret `<gtk-text-child-anchor>')
     Creates a new `<gtk-text-child-anchor>'. Usually you would then
     insert it into a `<gtk-text-buffer>' with
     `gtk-text-buffer-insert-child-anchor'.  To perform the creation
     and insertion in one step, use the convenience function
     `gtk-text-buffer-create-child-anchor'.

    RET
          a new `<gtk-text-child-anchor>'



 -- Function: gtk-text-child-anchor-get-widgets
          (self `<gtk-text-child-anchor>') =>  (ret `glist-of')
 -- Method: get-widgets
     Gets a list of all widgets anchored at this child anchor. The
     returned list should be freed with `g-list-free'.

    ANCHOR
          a `<gtk-text-child-anchor>'

    RET
          list of widgets anchored at ANCHOR



 -- Function: gtk-text-child-anchor-get-deleted
          (self `<gtk-text-child-anchor>') =>  (ret `bool')
 -- Method: get-deleted
     Determines whether a child anchor has been deleted from the
     buffer. Keep in mind that the child anchor will be unreferenced
     when removed from the buffer, so you need to hold your own
     reference (with `g-object-ref') if you plan to use this function
     &#x2014; otherwise all deleted child anchors will also be
     finalized.

    ANCHOR
          a `<gtk-text-child-anchor>'

    RET
          ``#t'' if the child anchor has been deleted from its buffer



 -- Function: gtk-text-view-add-child-in-window
          (self `<gtk-text-view>') (child `<gtk-widget>')
          (which_window `<gtk-text-window-type>') (xpos `int')
          (ypos `int')
 -- Method: add-child-in-window
     Adds a child at fixed coordinates in one of the text widget's
     windows. The window must have nonzero size (see
     `gtk-text-view-set-border-window-size').  Note that the child
     coordinates are given relative to the `<gdk-window>' in question,
     and that these coordinates have no sane relationship to scrolling.
     When placing a child in `<gtk-text-window-widget>', scrolling is
     irrelevant, the child floats above all scrollable areas. But when
     placing a child in one of the scrollable windows (border windows
     or text window), you'll need to compute the child's correct
     position in buffer coordinates any time scrolling occurs or buffer
     changes occur, and then call `gtk-text-view-move-child' to update
     the child's position. Unfortunately there's no good way to detect
     that scrolling has occurred, using the current API; a possible
     hack would be to update all child positions when the scroll
     adjustments change or the text buffer changes. See bug 64518 on
     bugzilla.gnome.org for status of fixing this issue.

    TEXT-VIEW
          a `<gtk-text-view>'

    CHILD
          a `<gtk-widget>'

    WHICH-WINDOW
          which window the child should appear in

    XPOS
          X position of child in window coordinates

    YPOS
          Y position of child in window coordinates



 -- Function: gtk-text-view-move-child (self `<gtk-text-view>')
          (child `<gtk-widget>') (xpos `int') (ypos `int')
 -- Method: move-child
     Updates the position of a child, as for
     `gtk-text-view-add-child-in-window'.

    TEXT-VIEW
          a `<gtk-text-view>'

    CHILD
          child widget already added to the text view

    XPOS
          new X position in window coordinates

    YPOS
          new Y position in window coordinates



 -- Function: gtk-text-view-set-wrap-mode (self `<gtk-text-view>')
          (wrap_mode `<gtk-wrap-mode>')
 -- Method: set-wrap-mode
     Sets the line wrapping for the view.

    TEXT-VIEW
          a `<gtk-text-view>'

    WRAP-MODE
          a `<gtk-wrap-mode>'



 -- Function: gtk-text-view-get-wrap-mode (self `<gtk-text-view>') => 
          (ret `<gtk-wrap-mode>')
 -- Method: get-wrap-mode
     Gets the line wrapping for the view.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          the line wrap setting



 -- Function: gtk-text-view-set-editable (self `<gtk-text-view>')
          (setting `bool')
 -- Method: set-editable
     Sets the default editability of the `<gtk-text-view>'. You can
     override this default setting with tags in the buffer, using the
     "editable" attribute of tags.

    TEXT-VIEW
          a `<gtk-text-view>'

    SETTING
          whether it's editable



 -- Function: gtk-text-view-get-editable (self `<gtk-text-view>') => 
          (ret `bool')
 -- Method: get-editable
     Returns the default editability of the `<gtk-text-view>'. Tags in
     the buffer may override this setting for some ranges of text.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          whether text is editable by default



 -- Function: gtk-text-view-set-cursor-visible (self `<gtk-text-view>')
          (setting `bool')
 -- Method: set-cursor-visible
     Toggles whether the insertion point is displayed. A buffer with no
     editable text probably shouldn't have a visible cursor, so you may
     want to turn the cursor off.

    TEXT-VIEW
          a `<gtk-text-view>'

    SETTING
          whether to show the insertion cursor



 -- Function: gtk-text-view-get-cursor-visible (self `<gtk-text-view>')
          =>  (ret `bool')
 -- Method: get-cursor-visible
     Find out whether the cursor is being displayed.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          whether the insertion mark is visible



 -- Function: gtk-text-view-set-overwrite (self `<gtk-text-view>')
          (overwrite `bool')
 -- Method: set-overwrite
     Changes the `<gtk-text-view>' overwrite mode.

    TEXT-VIEW
          a `<gtk-text-view>'

    OVERWRITE
          ``#t'' to turn on overwrite mode, ``#f'' to turn it off


     Since 2.4


 -- Function: gtk-text-view-get-overwrite (self `<gtk-text-view>') => 
          (ret `bool')
 -- Method: get-overwrite
     Returns whether the `<gtk-text-view>' is in overwrite mode or not.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          whether TEXT-VIEW is in overwrite mode or not.


     Since 2.4


 -- Function: gtk-text-view-set-justification (self `<gtk-text-view>')
          (justification `<gtk-justification>')
 -- Method: set-justification
     Sets the default justification of text in TEXT-VIEW. Tags in the
     view's buffer may override the default.

    TEXT-VIEW
          a `<gtk-text-view>'

    JUSTIFICATION
          justification



 -- Function: gtk-text-view-get-justification (self `<gtk-text-view>')
          =>  (ret `<gtk-justification>')
 -- Method: get-justification
     Gets the default justification of paragraphs in TEXT-VIEW. Tags in
     the buffer may override the default.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          default justification



 -- Function: gtk-text-view-set-left-margin (self `<gtk-text-view>')
          (left_margin `int')
 -- Method: set-left-margin
     Sets the default left margin for text in TEXT-VIEW. Tags in the
     buffer may override the default.

    TEXT-VIEW
          a `<gtk-text-view>'

    LEFT-MARGIN
          left margin in pixels



 -- Function: gtk-text-view-get-left-margin (self `<gtk-text-view>')
          =>  (ret `int')
 -- Method: get-left-margin
     Gets the default left margin size of paragraphs in the TEXT-VIEW.
     Tags in the buffer may override the default.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          left margin in pixels



 -- Function: gtk-text-view-set-right-margin (self `<gtk-text-view>')
          (right_margin `int')
 -- Method: set-right-margin
     Sets the default right margin for text in the text view. Tags in
     the buffer may override the default.

    TEXT-VIEW
          a `<gtk-text-view>'

    RIGHT-MARGIN
          right margin in pixels



 -- Function: gtk-text-view-get-right-margin (self `<gtk-text-view>')
          =>  (ret `int')
 -- Method: get-right-margin
     Gets the default right margin for text in TEXT-VIEW. Tags in the
     buffer may override the default.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          right margin in pixels



 -- Function: gtk-text-view-set-indent (self `<gtk-text-view>')
          (indent `int')
 -- Method: set-indent
     Sets the default indentation for paragraphs in TEXT-VIEW. Tags in
     the buffer may override the default.

    TEXT-VIEW
          a `<gtk-text-view>'

    INDENT
          indentation in pixels



 -- Function: gtk-text-view-get-indent (self `<gtk-text-view>') => 
          (ret `int')
 -- Method: get-indent
     Gets the default indentation of paragraphs in TEXT-VIEW. Tags in
     the view's buffer may override the default. The indentation may be
     negative.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          number of pixels of indentation



 -- Function: gtk-text-view-set-tabs (self `<gtk-text-view>')
          (tabs `<pango-tab-array>')
 -- Method: set-tabs
     Sets the default tab stops for paragraphs in TEXT-VIEW. Tags in
     the buffer may override the default.

    TEXT-VIEW
          a `<gtk-text-view>'

    TABS
          tabs as a `<pango-tab-array>'



 -- Function: gtk-text-view-get-tabs (self `<gtk-text-view>') => 
          (ret `<pango-tab-array>')
 -- Method: get-tabs
     Gets the default tabs for TEXT-VIEW. Tags in the buffer may
     override the defaults. The returned array will be ``#f'' if
     "standard" (8-space) tabs are used. Free the return value with
     `pango-tab-array-free'.

    TEXT-VIEW
          a `<gtk-text-view>'

    RET
          copy of default tab array, or ``#f'' if "standard" tabs are
          used; must be freed with `pango-tab-array-free'.



 -- Function: gtk-text-view-set-accepts-tab (self `<gtk-text-view>')
          (accepts_tab `bool')
 -- Method: set-accepts-tab
     Sets the behavior of the text widget when the Tab key is pressed.
     If ACCEPTS-TAB is ``#t'' a tab character is inserted. If
     ACCEPTS-TAB is ``#f'' the keyboard focus is moved to the next
     widget in the focus chain.

    TEXT-VIEW
          A `<gtk-text-view>'

    ACCEPTS-TAB
          ``#t'' if pressing the Tab key should insert a tab character,
          ``#f'', if pressing the Tab key should move the keyboard
          focus.


     Since 2.4


 -- Function: gtk-text-view-get-accepts-tab (self `<gtk-text-view>')
          =>  (ret `bool')
 -- Method: get-accepts-tab
     Returns whether pressing the Tab key inserts a tab characters.
     `gtk-text-view-set-accepts-tab'.

    TEXT-VIEW
          A `<gtk-text-view>'

    RET
          ``#t'' if pressing the Tab key inserts a tab character,
          ``#f'' if pressing the Tab key moves the keyboard focus.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkTreeModel,  Next: GtkTreeSelection,  Prev: GtkTextView,  Up: Top

32 GtkTreeModel
***************

The tree interface used by

32.1 Overview
=============

The `<gtk-tree-model>' interface defines a generic tree interface for
use by the `<gtk-tree-view>' widget. It is an abstract interface, and is
designed to be usable with any appropriate data structure. The
programmer just has to implement this interface on their own data type
for it to be viewable by a `<gtk-tree-view>' widget.

   The model is represented as a hierarchical tree of strongly-typed,
columned data. In other words, the model can be seen as a tree where
every node has different values depending on which column is being
queried. The type of data found in a column is determined by using the
GType system (ie.  `<g-type-int>', `<gtk-type-button>',
`<g-type-pointer>', etc.).  The types are homogeneous per column across
all nodes. It is important to note that this interface only provides a
way of examining a model and observing changes. The implementation of
each individual model decides how and if changes are made.

   In order to make life simpler for programmers who do not need to
write their own specialized model, two generic models are provided
&#x2014; the `<gtk-tree-store>' and the `<gtk-list-store>'. To use
these, the developer simply pushes data into these models as necessary.
These models provide the data structure as well as all appropriate tree
interfaces. As a result, implementing drag and drop, sorting, and
storing data is trivial. For the vast majority of trees and lists,
these two models are sufficient.

   Models are accessed on a node/column level of granularity. One can
query for the value of a model at a certain node and a certain column
on that node. There are two structures used to reference a particular
node in a model. They are the `<gtk-tree-path>' and the
`<gtk-tree-iter>' Most of the interface consists of operations on a
`<gtk-tree-iter>'.

   Here, is short for

   A path is essentially a potential node. It is a location on a model
that may or may not actually correspond to a node on a specific model.
The `<gtk-tree-path>' struct can be converted into either an array of
unsigned integers or a string. The string form is a list of numbers
separated by a colon.  Each number refers to the offset at that level.
Thus, the path refers to the root node and the path refers to the fifth
child of the third node.

   By contrast, a `<gtk-tree-iter>' is a reference to a specific node
on a specific model. It is a generic struct with an integer and three
generic pointers. These are filled in by the model in a model-specific
way. One can convert a path to an iterator by calling
`gtk-tree-model-get-iter'. These iterators are the primary way of
accessing a model and are similar to the iterators used by
`<gtk-text-buffer>'. They are generally statically allocated on the
stack and only used for a short time. The model interface defines a set
of operations using them for navigating the model.

   It is expected that models fill in the iterator with private data.
For example, the `<gtk-list-store>' model, which is internally a simple
linked list, stores a list node in one of the pointers. The
`<gtk-tree-model-sort>' stores an array and an offset in two of the
pointers. Additionally, there is an integer field. This field is
generally filled with a unique stamp per model.  This stamp is for
catching errors resulting from using invalid iterators with a model.

   The lifecycle of an iterator can be a little confusing at first.
Iterators are expected to always be valid for as long as the model is
unchanged (and doesn't emit a signal). The model is considered to own
all outstanding iterators and nothing needs to be done to free them
from the user's point of view.  Additionally, some models guarantee
that an iterator is valid for as long as the node it refers to is valid
(most notably the `<gtk-tree-store>' and `<gtk-list-store>'). Although
generally uninteresting, as one always has to allow for the case where
iterators do not persist beyond a signal, some very important
performance enhancements were made in the sort model. As a result, the
`<gtk-tree-model-iters-persist>' flag was added to indicate this
behavior.

   To help show some common operation of a model, some examples are
provided. The first example shows three ways of getting the iter at the
location . While the first method shown is easier, the second is much
more common, as you often get paths from callbacks.


     /* Three ways of getting the iter pointing to the location
      */
     {
       GtkTreePath *path;
       GtkTreeIter iter;
       GtkTreeIter parent_iter;

       /* get the iterator from a string */
       gtk_tree_model_get_iter_from_string (model, &iter, "3:2:5");

       /* get the iterator from a path */
       path = gtk_tree_path_new_from_string ("3:2:5");
       gtk_tree_model_get_iter (model, &iter, path);
       gtk_tree_path_free (path);


       /* walk the tree to find the iterator */
       gtk_tree_model_iter_nth_child (model, &iter, NULL, 3);
       parent_iter = iter;
       gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 2);
       parent_iter = iter;
       gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 5);
     }

   This second example shows a quick way of iterating through a list
and getting a string and an integer from each row. The `populate-model'
function used below is not shown, as it is specific to the
`<gtk-list-store>'. For information on how to write such a function,
see the `<gtk-list-store>' documentation.


     enum
     {
       STRING_COLUMN,
       INT_COLUMN,
       N_COLUMNS
     };

     {
       GtkTreeModel *list_store;
       GtkTreeIter iter;
       gboolean valid;
       gint row_count = 0;

       /* make a new list_store */
       list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT);

       /* Fill the list store with data */
       populate_model (list_store);

       /* Get the first iter in the list */
       valid = gtk_tree_model_get_iter_first (list_store, &iter);

       while (valid)
         {
           /* Walk through the list, reading each row */
           gchar *str_data;
           gint   int_data;

           /* Make sure you terminate calls to gtk_tree_model_get()
            * with a '-1' value
            */
           gtk_tree_model_get (list_store, &iter,
                               STRING_COLUMN, &str_data,
                               INT_COLUMN, &int_data,
                               -1);

           /* Do something with the data */
           g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data);
           g_free (str_data);

           row_count ++;
           valid = gtk_tree_model_iter_next (list_store, &iter);
         }
     }

32.2 Usage
==========

 -- Class: <gtk-tree-model>
     Derives from `<ginterface>'.

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


 -- Signal on <gtk-tree-model>: row-changed (arg0 `<gtk-tree-path>')
          (arg1 `<gtk-tree-iter>')
     This signal is emitted when a row in the model has changed.


 -- Signal on <gtk-tree-model>: row-inserted (arg0 `<gtk-tree-path>')
          (arg1 `<gtk-tree-iter>')
     This signal is emitted when a new row has been inserted in the
     model.

     Note that the row may still be empty at this point, since it is a
     common pattern to first insert an empty row, and then fill it with
     the desired values.


 -- Signal on <gtk-tree-model>: row-has-child-toggled
          (arg0 `<gtk-tree-path>') (arg1 `<gtk-tree-iter>')
     This signal is emitted when a row has gotten the first child row
     or lost its last child row.


 -- Signal on <gtk-tree-model>: row-deleted (arg0 `<gtk-tree-path>')
     This signal is emitted when a row has been deleted.

     Note that no iterator is passed to the signal handler, since the
     row is already deleted.

     Implementations of GtkTreeModel must emit row-deleted _before_
     removing the node from its internal data structures. This is
     because models and views which access and monitor this model might
     have references on the node which need to be released in the
     row-deleted handler.


 -- Signal on <gtk-tree-model>: rows-reordered (arg0 `<gtk-tree-path>')
          (arg1 `<gtk-tree-iter>') (arg2 `<gpointer>')
     This signal is emitted when the children of a node in the
     `<gtk-tree-model>' have been reordered.

     Note that this signal is _not_ emitted when rows are reordered by
     DND, since this is implemented by removing and then reinserting
     the row.


 -- Class: <gtk-tree-iter>
     Derives from `<gboxed>'.


 -- Class: <gtk-tree-path>
     Derives from `<gboxed>'.


 -- Class: <gtk-tree-row-reference>
     Derives from `<gboxed>'.


 -- Function: gtk-tree-path-new-from-string (path `mchars')
          (path `mchars') =>  (ret `<gtk-tree-path>')
     Creates a new `<gtk-tree-path>' initialized to PATH. PATH is
     expected to be a colon separated list of numbers. For example, the
     string "10:4:0" would create a path of depth 3 pointing to the
     11th child of the root node, the 5th child of that 11th child, and
     the 1st child of that 5th child. If an invalid path string is
     passed in, ``#f'' is returned.

    PATH
          The string representation of a path.

    RET
          A newly-created `<gtk-tree-path>', or ``#f''



 -- Function: gtk-tree-path-append-index (self `<gtk-tree-path>')
          (index `int')
     Appends a new index to a path. As a result, the depth of the path
     is increased.

    PATH
          A `<gtk-tree-path>'.

    INDEX
          The index.



 -- Function: gtk-tree-path-prepend-index (self `<gtk-tree-path>')
          (index `int')
     Prepends a new index to a path. As a result, the depth of the path
     is increased.

    PATH
          A `<gtk-tree-path>'.

    INDEX
          The index.



 -- Function: gtk-tree-path-copy (self `<gtk-tree-path>') => 
          (ret `<gtk-tree-path>')
     Creates a new `<gtk-tree-path>' as a copy of PATH.

    PATH
          A `<gtk-tree-path>'.

    RET
          A new `<gtk-tree-path>'.



 -- Function: gtk-tree-row-reference-new (model `<gtk-tree-model>')
          (path `<gtk-tree-path>') =>  (ret `<gtk-tree-row-reference>')
     Creates a row reference based on PATH. This reference will keep
     pointing to the node pointed to by PATH, so long as it exists. It
     listens to all signals emitted by MODEL, and updates its path
     appropriately. If PATH isn't a valid path in MODEL, then ``#f'' is
     returned.

    MODEL
          A `<gtk-tree-model>'

    PATH
          A valid `<gtk-tree-path>' to monitor

    RET
          A newly allocated `<gtk-tree-row-reference>', or ``#f''



 -- Function: gtk-tree-row-reference-new-proxy (proxy `<gobject>')
          (model `<gtk-tree-model>') (path `<gtk-tree-path>') => 
          (ret `<gtk-tree-row-reference>')
     You do not need to use this function. Creates a row reference
     based on PATH. This reference will keep pointing to the node
     pointed to by PATH, so long as it exists. If PATH isn't a valid
     path in MODEL, then ``#f'' is returned. However, unlike references
     created with `gtk-tree-row-reference-new', it does not listen to
     the model for changes. The creator of the row reference must do
     this explicitly using `gtk-tree-row-reference-inserted',
     `gtk-tree-row-reference-deleted',
     `gtk-tree-row-reference-reordered'.

     These functions must be called exactly once per proxy when the
     corresponding signal on the model is emitted. This single call
     updates all row references for that proxy. Since built-in GTK+
     objects like `<gtk-tree-view>' already use this mechanism
     internally, using them as the proxy object will produce
     unpredictable results. Further more, passing the same object as
     MODEL and PROXY doesn't work for reasons of internal
     implementation.

     This type of row reference is primarily meant by structures that
     need to carefully monitor exactly when a row reference updates
     itself, and is not generally needed by most applications.

    PROXY
          A proxy `<gobject>'

    MODEL
          A `<gtk-tree-model>'

    PATH
          A valid `<gtk-tree-path>' to monitor

    RET
          A newly allocated `<gtk-tree-row-reference>', or ``#f''



 -- Function: gtk-tree-row-reference-get-model
          (self `<gtk-tree-row-reference>') =>  (ret `<gtk-tree-model>')
     Returns the model that the row reference is monitoring.

    REFERENCE
          A `<gtk-tree-row-reference>'

    RET
          the model


     Since 2.8


 -- Function: gtk-tree-row-reference-get-path
          (self `<gtk-tree-row-reference>') =>  (ret `<gtk-tree-path>')
     Returns a path that the row reference currently points to, or
     ``#f'' if the path pointed to is no longer valid.

    REFERENCE
          A `<gtk-tree-row-reference>'

    RET
          A current path, or ``#f''.



 -- Function: gtk-tree-row-reference-valid
          (self `<gtk-tree-row-reference>') =>  (ret `bool')
     Returns ``#t'' if the REFERENCE is non-``#f'' and refers to a
     current valid path.

    REFERENCE
          A `<gtk-tree-row-reference>', or ``#f''

    RET
          ``#t'' if REFERENCE points to a valid path.



 -- Function: gtk-tree-row-reference-inserted (proxy `<gobject>')
          (path `<gtk-tree-path>')
     Lets a set of row reference created by
     `gtk-tree-row-reference-new-proxy' know that the model emitted the
     "row_inserted" signal.

    PROXY
          A `<gobject>'

    PATH
          The row position that was inserted



 -- Function: gtk-tree-row-reference-deleted (proxy `<gobject>')
          (path `<gtk-tree-path>')
     Lets a set of row reference created by
     `gtk-tree-row-reference-new-proxy' know that the model emitted the
     "row_deleted" signal.

    PROXY
          A `<gobject>'

    PATH
          The path position that was deleted



 -- Function: gtk-tree-row-reference-reordered (proxy `<gobject>')
          (path `<gtk-tree-path>') (iter `<gtk-tree-iter>') => 
          (new_order `int')
     Lets a set of row reference created by
     `gtk-tree-row-reference-new-proxy' know that the model emitted the
     "rows_reordered" signal.

    PROXY
          A `<gobject>'

    PATH
          The parent path of the reordered signal

    ITER
          The iter pointing to the parent of the reordered

    NEW-ORDER
          The new order of rows



 -- Function: gtk-tree-iter-copy (self `<gtk-tree-iter>') => 
          (ret `<gtk-tree-iter>')
     Creates a dynamically allocated tree iterator as a copy of ITER.
     This function is not intended for use in applications, because you
     can just copy the structs by value (`GtkTreeIter new_iter =
     iter;'). You must free this iter with `gtk-tree-iter-free'.

    ITER
          A `<gtk-tree-iter>'.

    RET
          a newly-allocated copy of ITER.



 -- Function: gtk-tree-model-get-flags (self `<gtk-tree-model>') => 
          (ret `<gtk-tree-model-flags>')
 -- Method: get-flags
     Returns a set of flags supported by this interface. The flags are
     a bitwise combination of `<gtk-tree-model-flags>'. The flags
     supported should not change during the lifecycle of the TREE-MODEL.

    TREE-MODEL
          A `<gtk-tree-model>'.

    RET
          The flags supported by this interface.



 -- Function: gtk-tree-model-get-n-columns (self `<gtk-tree-model>')
          =>  (ret `int')
 -- Method: get-n-columns
     Returns the number of columns supported by TREE-MODEL.

    TREE-MODEL
          A `<gtk-tree-model>'.

    RET
          The number of columns.



 -- Function: gtk-tree-model-get-column-type (self `<gtk-tree-model>')
          (index `int') =>  (ret `<gtype>')
 -- Method: get-column-type
     Returns the type of the column.

    TREE-MODEL
          A `<gtk-tree-model>'.

    INDEX
          The column index.

    RET
          The type of the column.



 -- Function: gtk-tree-model-get-iter (self `<gtk-tree-model>')
          (path `<gtk-tree-path>') =>  (ret `<gtk-tree-iter>')
 -- Method: get-iter
     Sets ITER to a valid iterator pointing to PATH.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The uninitialized `<gtk-tree-iter>'.

    PATH
          The `<gtk-tree-path>'.

    RET
          ``#t'', if ITER was set.



 -- Function: gtk-tree-model-get-iter-first (self `<gtk-tree-model>')
          =>  (ret `<gtk-tree-iter>')
 -- Method: get-iter-first
     Initializes ITER with the first iterator in the tree (the one at
     the path "0") and returns ``#t''. Returns ``#f'' if the tree is
     empty.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The uninitialized `<gtk-tree-iter>'.

    RET
          ``#t'', if ITER was set.



 -- Function: gtk-tree-model-get-path (self `<gtk-tree-model>')
          (iter `<gtk-tree-iter>') =>  (ret `<gtk-tree-path>')
 -- Method: get-path
     Returns a newly-created `<gtk-tree-path>' referenced by ITER. This
     path should be freed with `gtk-tree-path-free'.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The `<gtk-tree-iter>'.

    RET
          a newly-created `<gtk-tree-path>'.



 -- Function: gtk-tree-model-get-value (self `<gtk-tree-model>')
          (iter `<gtk-tree-iter>') (column `int') =>  (ret `scm')
 -- Method: get-value
     Sets initializes and sets VALUE to that at COLUMN. When done with
     VALUE, `g-value-unset' needs to be called to free any allocated
     memory.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The `<gtk-tree-iter>'.

    COLUMN
          The column to lookup the value at.

    VALUE
          An empty `<gvalue>' to set.



 -- Function: gtk-tree-model-iter-next (self `<gtk-tree-model>')
          (iter `<gtk-tree-iter>') =>  (ret `<gtk-tree-iter>')
 -- Method: iter-next
     Sets ITER to point to the node following it at the current level.
     If there is no next ITER, ``#f'' is returned and ITER is set to be
     invalid.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The `<gtk-tree-iter>'.

    RET
          ``#t'' if ITER has been changed to the next node.



 -- Function: gtk-tree-model-iter-children (self `<gtk-tree-model>')
          (parent `<gtk-tree-iter>') =>  (ret `glist-of')
 -- Method: iter-children
     Sets ITER to point to the first child of PARENT. If PARENT has no
     children, ``#f'' is returned and ITER is set to be invalid.
     PARENT will remain a valid node after this function has been
     called.

     If PARENT is ``#f'' returns the first node, equivalent to
     `gtk_tree_model_get_iter_first (tree_model, iter);'

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The new `<gtk-tree-iter>' to be set to the child.

    PARENT
          The `<gtk-tree-iter>', or ``#f''

    RET
          ``#t'', if CHILD has been set to the first child.



 -- Function: gtk-tree-model-iter-has-child (self `<gtk-tree-model>')
          (iter `<gtk-tree-iter>') =>  (ret `bool')
 -- Method: iter-has-child
     Returns ``#t'' if ITER has children, ``#f'' otherwise.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The `<gtk-tree-iter>' to test for children.

    RET
          ``#t'' if ITER has children.



 -- Function: gtk-tree-model-iter-n-children (self `<gtk-tree-model>')
          (iter `<gtk-tree-iter>') =>  (ret `int')
 -- Method: iter-n-children
     Returns the number of children that ITER has. As a special case, if
     ITER is ``#f'', then the number of toplevel nodes is returned.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The `<gtk-tree-iter>', or ``#f''.

    RET
          The number of children of ITER.



 -- Function: gtk-tree-model-iter-nth-child (self `<gtk-tree-model>')
          (parent `<gtk-tree-iter>') (n `int') => 
          (ret `<gtk-tree-iter>')
 -- Method: iter-nth-child
     Sets ITER to be the child of PARENT, using the given index. The
     first index is 0. If N is too big, or PARENT has no children, ITER
     is set to an invalid iterator and ``#f'' is returned.  PARENT will
     remain a valid node after this function has been called. As a
     special case, if PARENT is ``#f'', then the Nth root node is set.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The `<gtk-tree-iter>' to set to the nth child.

    PARENT
          The `<gtk-tree-iter>' to get the child from, or ``#f''.

    N
          Then index of the desired child.

    RET
          ``#t'', if PARENT has an Nth child.



 -- Function: gtk-tree-model-iter-parent (self `<gtk-tree-model>')
          (child `<gtk-tree-iter>') =>  (ret `<gtk-tree-iter>')
 -- Method: iter-parent
     Sets ITER to be the parent of CHILD. If CHILD is at the toplevel,
     and doesn't have a parent, then ITER is set to an invalid iterator
     and ``#f'' is returned. CHILD will remain a valid node after this
     function has been called.

    TREE-MODEL
          A `<gtk-tree-model>'

    ITER
          The new `<gtk-tree-iter>' to set to the parent.

    CHILD
          The `<gtk-tree-iter>'.

    RET
          ``#t'', if ITER is set to the parent of CHILD.



 -- Function: gtk-tree-model-get-string-from-iter
          (self `<gtk-tree-model>') (iter `<gtk-tree-iter>') => 
          (ret `mchars')
 -- Method: get-string-from-iter
     Generates a string representation of the iter. This string is a
     ':' separated list of numbers. For example, "4:10:0:3" would be an
     acceptable return value for this string.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          An `<gtk-tree-iter>'.

    RET
          A newly-allocated string. Must be freed with `g-free'.


     Since 2.2


 -- Function: gtk-tree-model-ref-node (self `<gtk-tree-model>')
          (iter `<gtk-tree-iter>')
 -- Method: ref-node
     Lets the tree ref the node. This is an optional method for models
     to implement.  To be more specific, models may ignore this call as
     it exists primarily for performance reasons.

     This function is primarily meant as a way for views to let caching
     model know when nodes are being displayed (and hence, whether or
     not to cache that node.)  For example, a file-system based model
     would not want to keep the entire file-hierarchy in memory, just
     the sections that are currently being displayed by every current
     view.

     A model should be expected to be able to get an iter independent
     of its reffed state.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The `<gtk-tree-iter>'.



 -- Function: gtk-tree-model-unref-node (self `<gtk-tree-model>')
          (iter `<gtk-tree-iter>')
 -- Method: unref-node
     Lets the tree unref the node. This is an optional method for
     models to implement. To be more specific, models may ignore this
     call as it exists primarily for performance reasons.

     For more information on what this means, see
     `gtk-tree-model-ref-node'.  Please note that nodes that are
     deleted are not unreffed.

    TREE-MODEL
          A `<gtk-tree-model>'.

    ITER
          The `<gtk-tree-iter>'.



 -- Function: gtk-tree-model-row-changed (self `<gtk-tree-model>')
          (path `<gtk-tree-path>') (iter `<gtk-tree-iter>')
 -- Method: row-changed
     Emits the "row_changed" signal on TREE-MODEL.

    TREE-MODEL
          A `<gtk-tree-model>'

    PATH
          A `<gtk-tree-path>' pointing to the changed row

    ITER
          A valid `<gtk-tree-iter>' pointing to the changed row



 -- Function: gtk-tree-model-row-inserted (self `<gtk-tree-model>')
          (path `<gtk-tree-path>') (iter `<gtk-tree-iter>')
 -- Method: row-inserted
     Emits the "row_inserted" signal on TREE-MODEL

    TREE-MODEL
          A `<gtk-tree-model>'

    PATH
          A `<gtk-tree-path>' pointing to the inserted row

    ITER
          A valid `<gtk-tree-iter>' pointing to the inserted row



 -- Function: gtk-tree-model-row-deleted (self `<gtk-tree-model>')
          (path `<gtk-tree-path>')
 -- Method: row-deleted
     Emits the "row_deleted" signal on TREE-MODEL. This should be
     called by models after a row has been removed. The location
     pointed to by PATH should be the location that the row previously
     was at. It may not be a valid location anymore.

    TREE-MODEL
          A `<gtk-tree-model>'

    PATH
          A `<gtk-tree-path>' pointing to the previous location of the
          deleted row.



 -- Function: gtk-tree-model-rows-reordered (self `<gtk-tree-model>')
          (path `<gtk-tree-path>') (iter `<gtk-tree-iter>') => 
          (new_order `int')
 -- Method: rows-reordered
     Emits the "rows_reordered" signal on TREE-MODEL. This should be
     called by models when their rows have been reordered.

    TREE-MODEL
          A `<gtk-tree-model>'

    PATH
          A `<gtk-tree-path>' pointing to the tree node whose children
          have been reordered

    ITER
          A valid `<gtk-tree-iter>' pointing to the node whose children
          have been reordered, or ``#f'' if the depth of PATH is 0.

    NEW-ORDER
          an array of integers mapping the current position of each
          child to its old position before the re-ordering, i.e.
          NEW-ORDER`[newpos] = oldpos'.




File: guile-gnome-gtk.info,  Node: GtkTreeSelection,  Next: GtkTreeViewColumn,  Prev: GtkTreeModel,  Up: Top

33 GtkTreeSelection
*******************

The selection object for

33.1 Overview
=============

The `<gtk-tree-selection>' object is a helper object to manage the
selection for a `<gtk-tree-view>' widget. The `<gtk-tree-selection>'
object is automatically created when a new `<gtk-tree-view>' widget is
created, and cannot exist independentally of this widget. The primary
reason the `<gtk-tree-selection>' objects exists is for cleanliness of
code and API.  That is, there is no conceptual reason all these
functions could not be methods on the `<gtk-tree-view>' widget instead
of a separate function.

   The `<gtk-tree-selection>' object is gotten from a `<gtk-tree-view>'
by calling `gtk-tree-view-get-selection'. It can be manipulated to check
the selection status of the tree, as well as select and deselect
individual rows. Selection is done completely view side. As a result,
multiple views of the same model can have completely different
selections. Additionally, you cannot change the selection of a row on
the model that is not currently displayed by the view without expanding
its parents first.

   One of the important things to remember when monitoring the
selection of a view is that the "changed" signal is mostly a hint. That
is, it may only emit one signal when a range of rows is selected.
Additionally, it may on occasion emit a "changed" signal when nothing
has happened (mostly as a result of programmers calling select_row on
an already selected row).

33.2 Usage
==========

 -- Class: <gtk-tree-selection>
     Derives from `<gobject>'.

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


 -- Signal on <gtk-tree-selection>: changed
     Emitted whenever the selection has (possibly) changed. Please note
     that this signal is mostly a hint. It may only be emitted once
     when a range of rows are selected, and it may occasionally be
     emitted when nothing has happened.


 -- Function: gtk-tree-selection-set-mode (self `<gtk-tree-selection>')
          (type `<gtk-selection-mode>')
 -- Method: set-mode
     Sets the selection mode of the SELECTION. If the previous type was
     `<gtk-selection-multiple>', then the anchor is kept selected, if
     it was previously selected.

    SELECTION
          A `<gtk-tree-selection>'.

    TYPE
          The selection mode



 -- Function: gtk-tree-selection-get-mode (self `<gtk-tree-selection>')
          =>  (ret `<gtk-selection-mode>')
 -- Method: get-mode
     Gets the selection mode for SELECTION. See
     `gtk-tree-selection-set-mode'.

    SELECTION
          a `<gtk-tree-selection>'

    RET
          the current selection mode



 -- Function: gtk-tree-selection-get-tree-view
          (self `<gtk-tree-selection>') =>  (ret `<gtk-tree-view>')
 -- Method: get-tree-view
     Returns the tree view associated with SELECTION.

    SELECTION
          A `<gtk-tree-selection>'

    RET
          A `<gtk-tree-view>'



 -- Function: gtk-tree-selection-get-selected
          (self `<gtk-tree-selection>') =>  (model `<gtk-tree-model>')
          (iter `<gtk-tree-iter>')
 -- Method: get-selected
 -- Method: get-selected
     Retrieve the current selection, if SELECTION is set to
     `<gtk-selection-single>' or `<gtk-selection-browse>'.

     This function will not work if you use SELECTION is
     `<gtk-selection-multiple>'.

    SELECTION
          A `<gtk-tree-selection>'.

    MODEL
          A pointer to set to the `<gtk-tree-model>', or NULL.

    ITER
          The `<gtk-tree-iter>', or NULL.



 -- Function: gtk-tree-selection-select-path
          (self `<gtk-tree-selection>') (path `<gtk-tree-path>')
 -- Method: select-path
     Select the row at PATH.

    SELECTION
          A `<gtk-tree-selection>'.

    PATH
          The `<gtk-tree-path>' to be selected.



 -- Function: gtk-tree-selection-unselect-path
          (self `<gtk-tree-selection>') (path `<gtk-tree-path>')
 -- Method: unselect-path
     Unselects the row at PATH.

    SELECTION
          A `<gtk-tree-selection>'.

    PATH
          The `<gtk-tree-path>' to be unselected.



 -- Function: gtk-tree-selection-path-is-selected
          (self `<gtk-tree-selection>') (path `<gtk-tree-path>') => 
          (ret `bool')
 -- Method: path-is-selected
     Returns ``#t'' if the row pointed to by PATH is currently
     selected. If PATH does not point to a valid location, ``#f'' is
     returned

    SELECTION
          A `<gtk-tree-selection>'.

    PATH
          A `<gtk-tree-path>' to check selection on.

    RET
          ``#t'' if PATH is selected.



 -- Function: gtk-tree-selection-select-iter
          (self `<gtk-tree-selection>') (iter `<gtk-tree-iter>')
 -- Method: select-iter
     Selects the specified iterator.

    SELECTION
          A `<gtk-tree-selection>'.

    ITER
          The `<gtk-tree-iter>' to be selected.



 -- Function: gtk-tree-selection-unselect-iter
          (self `<gtk-tree-selection>') (iter `<gtk-tree-iter>')
 -- Method: unselect-iter
     Unselects the specified iterator.

    SELECTION
          A `<gtk-tree-selection>'.

    ITER
          The `<gtk-tree-iter>' to be unselected.



 -- Function: gtk-tree-selection-iter-is-selected
          (self `<gtk-tree-selection>') (iter `<gtk-tree-iter>') => 
          (ret `bool')
 -- Method: iter-is-selected
     Returns ``#t'' if the row at ITER is currently selected.

    SELECTION
          A `<gtk-tree-selection>'

    ITER
          A valid `<gtk-tree-iter>'

    RET
          ``#t'', if ITER is selected



 -- Function: gtk-tree-selection-select-all
          (self `<gtk-tree-selection>')
 -- Method: select-all
     Selects all the nodes. SELECTION must be set to
     `<gtk-selection-multiple>' mode.

    SELECTION
          A `<gtk-tree-selection>'.



 -- Function: gtk-tree-selection-unselect-all
          (self `<gtk-tree-selection>')
 -- Method: unselect-all
     Unselects all the nodes.

    SELECTION
          A `<gtk-tree-selection>'.



 -- Function: gtk-tree-selection-select-range
          (self `<gtk-tree-selection>') (start_path `<gtk-tree-path>')
          (end_path `<gtk-tree-path>')
 -- Method: select-range
     Selects a range of nodes, determined by START-PATH and END-PATH
     inclusive. SELECTION must be set to `<gtk-selection-multiple>'
     mode.

    SELECTION
          A `<gtk-tree-selection>'.

    START-PATH
          The initial node of the range.

    END-PATH
          The final node of the range.



 -- Function: gtk-tree-selection-unselect-range
          (self `<gtk-tree-selection>') (start_path `<gtk-tree-path>')
          (end_path `<gtk-tree-path>')
 -- Method: unselect-range
     Unselects a range of nodes, determined by START-PATH and END-PATH
     inclusive.

    SELECTION
          A `<gtk-tree-selection>'.

    START-PATH
          The initial node of the range.

    END-PATH
          The initial node of the range.


     Since 2.2



File: guile-gnome-gtk.info,  Node: GtkTreeViewColumn,  Next: GtkTreeView,  Prev: GtkTreeSelection,  Up: Top

34 GtkTreeViewColumn
********************

A visible column in a widget

34.1 Overview
=============

The GtkTreeViewColumn object represents a visible column in a
`<gtk-tree-view>' widget. It allows to set properties of the column
header, and functions as a holding pen for the cell renderers which
determine how the data in the column is displayed.

   Please refer to the tree widget conceptual overview for an overview
of all the objects and data types related to the tree widget and how
they work together.

34.2 Usage
==========

 -- Class: <gtk-tree-view-column>
     Derives from `<gtk-buildable>', `<gtk-cell-layout>',
     `<gtk-object>'.

     This class defines the following properties:

    `visible'
          Whether to display the column

    `resizable'
          Column is user-resizable

    `width'
          Current width of the column

    `spacing'
          Space which is inserted between cells

    `sizing'
          Resize mode of the column

    `fixed-width'
          Current fixed width of the column

    `min-width'
          Minimum allowed width of the column

    `max-width'
          Maximum allowed width of the column

    `title'
          Title to appear in column header

    `expand'
          Column gets share of extra width allocated to the widget

    `clickable'
          Whether the header can be clicked

    `widget'
          Widget to put in column header button instead of column title

    `alignment'
          X Alignment of the column header text or widget

    `reorderable'
          Whether the column can be reordered around the headers

    `sort-indicator'
          Whether to show a sort indicator

    `sort-order'
          Sort direction the sort indicator should indicate



 -- Signal on <gtk-tree-view-column>: clicked

 -- Function: gtk-tree-view-column-new => 
          (ret `<gtk-tree-view-column>')
     Creates a new `<gtk-tree-view-column>'.

    RET
          A newly created `<gtk-tree-view-column>'.



 -- Function: gtk-tree-view-column-pack-start
          (self `<gtk-tree-view-column>') (cell `<gtk-cell-renderer>')
          (expand `bool')
 -- Method: pack-start
     Packs the CELL into the beginning of the column. If EXPAND is
     ``#f'', then the CELL is allocated no more space than it needs.
     Any unused space is divided evenly between cells for which EXPAND
     is ``#t''.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    CELL
          The `<gtk-cell-renderer>'.

    EXPAND
          ``#t'' if CELL is to be given extra space allocated to
          TREE-COLUMN.



 -- Function: gtk-tree-view-column-pack-end
          (self `<gtk-tree-view-column>') (cell `<gtk-cell-renderer>')
          (expand `bool')
 -- Method: pack-end
     Adds the CELL to end of the column. If EXPAND is ``#f'', then the
     CELL is allocated no more space than it needs. Any unused space is
     divided evenly between cells for which EXPAND is ``#t''.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    CELL
          The `<gtk-cell-renderer>'.

    EXPAND
          ``#t'' if CELL is to be given extra space allocated to
          TREE-COLUMN.



 -- Function: gtk-tree-view-column-clear (self `<gtk-tree-view-column>')
 -- Method: clear
     Unsets all the mappings on all renderers on the TREE-COLUMN.

    TREE-COLUMN
          A `<gtk-tree-view-column>'



 -- Function: gtk-tree-view-column-add-attribute
          (self `<gtk-tree-view-column>')
          (cell_renderer `<gtk-cell-renderer>') (attribute `mchars')
          (column `int')
 -- Method: add-attribute
     Adds an attribute mapping to the list in TREE-COLUMN. The COLUMN is
     the column of the model to get a value from, and the ATTRIBUTE is
     the parameter on CELL-RENDERER to be set from the value. So for
     example if column 2 of the model contains strings, you could have
     the "text" attribute of a `<gtk-cell-renderer-text>' get its
     values from column 2.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    CELL-RENDERER
          the `<gtk-cell-renderer>' to set attributes on

    ATTRIBUTE
          An attribute on the renderer

    COLUMN
          The column position on the model to get the attribute from.



 -- Function: gtk-tree-view-column-set-spacing
          (self `<gtk-tree-view-column>') (spacing `int')
 -- Method: set-spacing
     Sets the spacing field of TREE-COLUMN, which is the number of
     pixels to place between cell renderers packed into it.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    SPACING
          distance between cell renderers in pixels.



 -- Function: gtk-tree-view-column-get-spacing
          (self `<gtk-tree-view-column>') =>  (ret `int')
 -- Method: get-spacing
     Returns the spacing of TREE-COLUMN.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    RET
          the spacing of TREE-COLUMN.



 -- Function: gtk-tree-view-column-set-visible
          (self `<gtk-tree-view-column>') (visible `bool')
 -- Method: set-visible
     Sets the visibility of TREE-COLUMN.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    VISIBLE
          ``#t'' if the TREE-COLUMN is visible.



 -- Function: gtk-tree-view-column-get-visible
          (self `<gtk-tree-view-column>') =>  (ret `bool')
 -- Method: get-visible
     Returns ``#t'' if TREE-COLUMN is visible.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    RET
          whether the column is visible or not. If it is visible, then
          the tree will show the column.



 -- Function: gtk-tree-view-column-set-resizable
          (self `<gtk-tree-view-column>') (resizable `bool')
 -- Method: set-resizable
     If RESIZABLE is ``#t'', then the user can explicitly resize the
     column by grabbing the outer edge of the column button. If
     resizable is ``#t'' and sizing mode of the column is
     `<gtk-tree-view-column-autosize>', then the sizing mode is changed
     to `<gtk-tree-view-column-grow-only>'.

    TREE-COLUMN
          A `<gtk-tree-view-column>'

    RESIZABLE
          ``#t'', if the column can be resized



 -- Function: gtk-tree-view-column-get-resizable
          (self `<gtk-tree-view-column>') =>  (ret `bool')
 -- Method: get-resizable
     Returns ``#t'' if the TREE-COLUMN can be resized by the end user.

    TREE-COLUMN
          A `<gtk-tree-view-column>'

    RET
          ``#t'', if the TREE-COLUMN can be resized.



 -- Function: gtk-tree-view-column-set-sizing
          (self `<gtk-tree-view-column>')
          (type `<gtk-tree-view-column-sizing>')
 -- Method: set-sizing
     Sets the growth behavior of TREE-COLUMN to TYPE.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    TYPE
          The `<gtk-tree-view-column-sizing>'.



 -- Function: gtk-tree-view-column-get-sizing
          (self `<gtk-tree-view-column>') => 
          (ret `<gtk-tree-view-column-sizing>')
 -- Method: get-sizing
     Returns the current type of TREE-COLUMN.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    RET
          The type of TREE-COLUMN.



 -- Function: gtk-tree-view-column-get-width
          (self `<gtk-tree-view-column>') =>  (ret `int')
 -- Method: get-width
     Returns the current size of TREE-COLUMN in pixels.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    RET
          The current width of TREE-COLUMN.



 -- Function: gtk-tree-view-column-set-min-width
          (self `<gtk-tree-view-column>') (min_width `int')
 -- Method: set-min-width
     Sets the minimum width of the TREE-COLUMN. If MIN-WIDTH is -1, then
     the minimum width is unset.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    MIN-WIDTH
          The minimum width of the column in pixels, or -1.



 -- Function: gtk-tree-view-column-get-min-width
          (self `<gtk-tree-view-column>') =>  (ret `int')
 -- Method: get-min-width
     Returns the minimum width in pixels of the TREE-COLUMN, or -1 if no
     minimum width is set.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    RET
          The minimum width of the TREE-COLUMN.



 -- Function: gtk-tree-view-column-set-max-width
          (self `<gtk-tree-view-column>') (max_width `int')
 -- Method: set-max-width
     Sets the maximum width of the TREE-COLUMN. If MAX-WIDTH is -1, then
     the maximum width is unset. Note, the column can actually be wider
     than max width if it's the last column in a view. In this case,
     the column expands to fill any extra space.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    MAX-WIDTH
          The maximum width of the column in pixels, or -1.



 -- Function: gtk-tree-view-column-get-max-width
          (self `<gtk-tree-view-column>') =>  (ret `int')
 -- Method: get-max-width
     Returns the maximum width in pixels of the TREE-COLUMN, or -1 if no
     maximum width is set.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    RET
          The maximum width of the TREE-COLUMN.



 -- Function: gtk-tree-view-column-clicked
          (self `<gtk-tree-view-column>')
 -- Method: clicked
     Emits the "clicked" signal on the column. This function will only
     work if TREE-COLUMN is clickable.

    TREE-COLUMN
          a `<gtk-tree-view-column>'



 -- Function: gtk-tree-view-column-set-title
          (self `<gtk-tree-view-column>') (title `mchars')
 -- Method: set-title
     Sets the title of the TREE-COLUMN. If a custom widget has been
     set, then this value is ignored.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    TITLE
          The title of the TREE-COLUMN.



 -- Function: gtk-tree-view-column-get-title
          (self `<gtk-tree-view-column>') =>  (ret `mchars')
 -- Method: get-title
     Returns the title of the widget.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    RET
          the title of the column. This string should not be modified
          or freed.



 -- Function: gtk-tree-view-column-set-expand
          (self `<gtk-tree-view-column>') (expand `bool')
 -- Method: set-expand
     Sets the column to take available extra space. This space is
     shared equally amongst all columns that have the expand set to
     ``#t''. If no column has this option set, then the last column
     gets all extra space. By default, every column is created with
     this ``#f''.

    TREE-COLUMN
          A `<gtk-tree-view-column>'

    EXPAND
          ``#t'' if the column should take available extra space,
          ``#f'' if not


     Since 2.4


 -- Function: gtk-tree-view-column-get-expand
          (self `<gtk-tree-view-column>') =>  (ret `bool')
 -- Method: get-expand
     Return ``#t'' if the column expands to take any available space.

    TREE-COLUMN
          a `<gtk-tree-view-column>'

    RET
          ``#t'', if the column expands


     Since 2.4


 -- Function: gtk-tree-view-column-set-clickable
          (self `<gtk-tree-view-column>') (clickable `bool')
 -- Method: set-clickable
     Sets the header to be active if ACTIVE is ``#t''. When the header
     is active, then it can take keyboard focus, and can be clicked.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    CLICKABLE
          ``#t'' if the header is active.



 -- Function: gtk-tree-view-column-get-clickable
          (self `<gtk-tree-view-column>') =>  (ret `bool')
 -- Method: get-clickable
     Returns ``#t'' if the user can click on the header for the column.

    TREE-COLUMN
          a `<gtk-tree-view-column>'

    RET
          ``#t'' if user can click the column header.



 -- Function: gtk-tree-view-column-set-widget
          (self `<gtk-tree-view-column>') (widget `<gtk-widget>')
 -- Method: set-widget
     Sets the widget in the header to be WIDGET. If widget is ``#f'',
     then the header button is set with a `<gtk-label>' set to the
     title of TREE-COLUMN.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    WIDGET
          A child `<gtk-widget>', or ``#f''.



 -- Function: gtk-tree-view-column-get-widget
          (self `<gtk-tree-view-column>') =>  (ret `<gtk-widget>')
 -- Method: get-widget
     Returns the `<gtk-widget>' in the button on the column header. If
     a custom widget has not been set then ``#f'' is returned.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    RET
          The `<gtk-widget>' in the column header, or ``#f''



 -- Function: gtk-tree-view-column-set-alignment
          (self `<gtk-tree-view-column>') (xalign `float')
 -- Method: set-alignment
     Sets the alignment of the title or custom widget inside the column
     header. The alignment determines its location inside the button -
     0.0 for left, 0.5 for center, 1.0 for right.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    XALIGN
          The alignment, which is between [0.0 and 1.0] inclusive.



 -- Function: gtk-tree-view-column-get-alignment
          (self `<gtk-tree-view-column>') =>  (ret `float')
 -- Method: get-alignment
     Returns the current x alignment of TREE-COLUMN. This value can
     range between 0.0 and 1.0.

    TREE-COLUMN
          A `<gtk-tree-view-column>'.

    RET
          The current alignent of TREE-COLUMN.



 -- Function: gtk-tree-view-column-set-sort-order
          (self `<gtk-tree-view-column>') (order `<gtk-sort-type>')
 -- Method: set-sort-order
     Changes the appearance of the sort indicator.

     This _does not_ actually sort the model. Use
     `gtk-tree-view-column-set-sort-column-id' if you want automatic
     sorting support. This function is primarily for custom sorting
     behavior, and should be used in conjunction with
     `gtk-tree-sortable-set-sort-column' to do that.  For custom
     models, the mechanism will vary.

     The sort indicator changes direction to indicate normal sort or
     reverse sort.  Note that you must have the sort indicator enabled
     to see anything when calling this function; see
     `gtk-tree-view-column-set-sort-indicator'.

    TREE-COLUMN
          a `<gtk-tree-view-column>'

    ORDER
          sort order that the sort indicator should indicate



 -- Function: gtk-tree-view-column-get-sort-order
          (self `<gtk-tree-view-column>') =>  (ret `<gtk-sort-type>')
 -- Method: get-sort-order
     Gets the value set by `gtk-tree-view-column-set-sort-order'.

    TREE-COLUMN
          a `<gtk-tree-view-column>'

    RET
          the sort order the sort indicator is indicating



 -- Function: gtk-tree-view-column-focus-cell
          (self `<gtk-tree-view-column>') (cell `<gtk-cell-renderer>')
 -- Method: focus-cell
     Sets the current keyboard focus to be at CELL, if the column
     contains 2 or more editable and activatable cells.

    TREE-COLUMN
          A `<gtk-tree-view-column>'

    CELL
          A `<gtk-cell-renderer>'


     Since 2.2


 -- Function: gtk-tree-view-column-queue-resize
          (self `<gtk-tree-view-column>')
 -- Method: queue-resize
     Flags the column, and the cell renderers added to this column, to
     have their sizes renegotiated.

    TREE-COLUMN
          A `<gtk-tree-view-column>'


     Since 2.8



File: guile-gnome-gtk.info,  Node: GtkTreeView,  Next: GtkTreeView drag-and-drop,  Prev: GtkTreeViewColumn,  Up: Top

35 GtkTreeView
**************

A widget for displaying both trees and lists

35.1 Overview
=============

Widget that displays any object that implements the GtkTreeModel
interface.

   Please refer to the tree widget conceptual overview for an overview
of all the objects and data types related to the tree widget and how
they work together.

35.2 Usage
==========

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

     This class defines the following properties:

    `model'
          The model for the tree view

    `hadjustment'
          Horizontal Adjustment for the widget

    `vadjustment'
          Vertical Adjustment for the widget

    `headers-visible'
          Show the column header buttons

    `headers-clickable'
          Column headers respond to click events

    `expander-column'
          Set the column for the expander column

    `reorderable'
          View is reorderable

    `rules-hint'
          Set a hint to the theme engine to draw rows in alternating
          colors

    `enable-search'
          View allows user to search through columns interactively

    `search-column'
          Model column to search through when searching through code

    `fixed-height-mode'
          Speeds up GtkTreeView by assuming that all rows have the same
          height

    `hover-selection'
          Whether the selection should follow the pointer

    `hover-expand'
          Whether rows should be expanded/collapsed when the pointer
          moves over them

    `show-expanders'
          View has expanders

    `level-indentation'
          Extra indentation for each level

    `rubber-banding'
          Whether to enable selection of multiple items by dragging the
          mouse pointer

    `enable-grid-lines'
          Whether grid lines should be drawn in the tree view

    `enable-tree-lines'
          Whether tree lines should be drawn in the tree view

    `tooltip-column'
          The column in the model containing the tooltip texts for the
          rows



 -- Signal on <gtk-tree-view>: move-cursor (arg0 `<gtk-movement-step>')
          (arg1 `<gint>') => `<gboolean>'

 -- Signal on <gtk-tree-view>: set-scroll-adjustments
          (arg0 `<gtk-adjustment>') (arg1 `<gtk-adjustment>')

 -- Signal on <gtk-tree-view>: select-all => `<gboolean>'

 -- Signal on <gtk-tree-view>: unselect-all => `<gboolean>'

 -- Signal on <gtk-tree-view>: row-activated (arg0 `<gtk-tree-path>')
          (arg1 `<gtk-tree-view-column>')
     The "row-activated" signal is emitted when the method
     `gtk-tree-view-row-activated' is called or the user double clicks a
     treeview row. It is also emitted when a non-editable row is
     selected and one of the keys: Space, Shift+Space, Return or Enter
     is pressed.

     For selection handling refer to the tree widget conceptual
     overview as well as `<gtk-tree-selection>'.


 -- Signal on <gtk-tree-view>: test-expand-row (arg0 `<gtk-tree-iter>')
          (arg1 `<gtk-tree-path>') => `<gboolean>'
     The given row is about to be expanded (show its children nodes).
     Use this signal if you need to control the expandability of
     individual rows.


 -- Signal on <gtk-tree-view>: test-collapse-row
          (arg0 `<gtk-tree-iter>') (arg1 `<gtk-tree-path>')
          => `<gboolean>'
     The given row is about to be collapsed (hide its children nodes).
     Use this signal if you need to control the collapsibility of
     individual rows.


 -- Signal on <gtk-tree-view>: row-expanded (arg0 `<gtk-tree-iter>')
          (arg1 `<gtk-tree-path>')
     The given row has been expanded (child nodes are shown).


 -- Signal on <gtk-tree-view>: row-collapsed (arg0 `<gtk-tree-iter>')
          (arg1 `<gtk-tree-path>')
     The given row has been collapsed (child nodes are hidden).


 -- Signal on <gtk-tree-view>: columns-changed
     The number of columns of the treeview has changed.


 -- Signal on <gtk-tree-view>: cursor-changed
     The position of the cursor (focused cell) has changed.


 -- Signal on <gtk-tree-view>: select-cursor-row (arg0 `<gboolean>')
          => `<gboolean>'

 -- Signal on <gtk-tree-view>: toggle-cursor-row => `<gboolean>'

 -- Signal on <gtk-tree-view>: expand-collapse-cursor-row
          (arg0 `<gboolean>') (arg1 `<gboolean>') (arg2 `<gboolean>')
          => `<gboolean>'

 -- Signal on <gtk-tree-view>: select-cursor-parent => `<gboolean>'

 -- Signal on <gtk-tree-view>: start-interactive-search => `<gboolean>'

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

    RET
          A newly created `<gtk-tree-view>' widget.



 -- Function: gtk-tree-view-new-with-model (model `<gtk-tree-model>')
          =>  (ret `<gtk-widget>')
     Creates a new `<gtk-tree-view>' widget with the model initialized
     to MODEL.

    MODEL
          the model.

    RET
          A newly created `<gtk-tree-view>' widget.



 -- Function: gtk-tree-view-get-model (self `<gtk-tree-view>') => 
          (ret `<gtk-tree-model>')
 -- Method: get-model
     Returns the model the `<gtk-tree-view>' is based on. Returns
     ``#f'' if the model is unset.

    TREE-VIEW
          a `<gtk-tree-view>'

    RET
          A `<gtk-tree-model>', or ``#f'' if none is currently being
          used.



 -- Function: gtk-tree-view-set-model (self `<gtk-tree-view>')
          (model `<gtk-tree-model>')
 -- Method: set-model
     Sets the model for a `<gtk-tree-view>'. If the TREE-VIEW already
     has a model set, it will remove it before setting the new model.
     If MODEL is ``#f'', then it will unset the old model.

    TREE-VIEW
          A `<gtk-tree-node>'.

    MODEL
          The model.



 -- Function: gtk-tree-view-get-selection (self `<gtk-tree-view>') => 
          (ret `<gtk-tree-selection>')
 -- Method: get-selection
     Gets the `<gtk-tree-selection>' associated with TREE-VIEW.

    TREE-VIEW
          A `<gtk-tree-view>'.

    RET
          A `<gtk-tree-selection>' object.



 -- Function: gtk-tree-view-get-hadjustment (self `<gtk-tree-view>')
          =>  (ret `<gtk-adjustment>')
 -- Method: get-hadjustment
     Gets the `<gtk-adjustment>' currently being used for the
     horizontal aspect.

    TREE-VIEW
          A `<gtk-tree-view>'

    RET
          A `<gtk-adjustment>' object, or ``#f'' if none is currently
          being used.



 -- Function: gtk-tree-view-set-hadjustment (self `<gtk-tree-view>')
          (adjustment `<gtk-adjustment>')
 -- Method: set-hadjustment
     Sets the `<gtk-adjustment>' for the current horizontal aspect.

    TREE-VIEW
          A `<gtk-tree-view>'

    ADJUSTMENT
          The `<gtk-adjustment>' to set, or ``#f''



 -- Function: gtk-tree-view-get-vadjustment (self `<gtk-tree-view>')
          =>  (ret `<gtk-adjustment>')
 -- Method: get-vadjustment
     Gets the `<gtk-adjustment>' currently being used for the vertical
     aspect.

    TREE-VIEW
          A `<gtk-tree-view>'

    RET
          A `<gtk-adjustment>' object, or ``#f'' if none is currently
          being used.



 -- Function: gtk-tree-view-set-vadjustment (self `<gtk-tree-view>')
          (adjustment `<gtk-adjustment>')
 -- Method: set-vadjustment
     Sets the `<gtk-adjustment>' for the current vertical aspect.

    TREE-VIEW
          A `<gtk-tree-view>'

    ADJUSTMENT
          The `<gtk-adjustment>' to set, or ``#f''



 -- Function: gtk-tree-view-get-headers-visible
          (self `<gtk-tree-view>') =>  (ret `bool')
 -- Method: get-headers-visible
     Returns ``#t'' if the headers on the TREE-VIEW are visible.

    TREE-VIEW
          A `<gtk-tree-view>'.

    RET
          Whether the headers are visible or not.



 -- Function: gtk-tree-view-set-headers-visible
          (self `<gtk-tree-view>') (headers_visible `bool')
 -- Method: set-headers-visible
     Sets the visibility state of the headers.

    TREE-VIEW
          A `<gtk-tree-view>'.

    HEADERS-VISIBLE
          ``#t'' if the headers are visible



 -- Function: gtk-tree-view-columns-autosize (self `<gtk-tree-view>')
 -- Method: columns-autosize
     Resizes all columns to their optimal width. Only works after the
     treeview has been realized.

    TREE-VIEW
          A `<gtk-tree-view>'.



 -- Function: gtk-tree-view-get-headers-clickable
          (self `<gtk-tree-view>') =>  (ret `bool')
 -- Method: get-headers-clickable
     Returns whether all header columns are clickable.

    TREE-VIEW
          A `<gtk-tree-view>'.

    RET
          ``#t'' if all header columns are clickable, otherwise ``#f''


     Since 2.10


 -- Function: gtk-tree-view-set-headers-clickable
          (self `<gtk-tree-view>') (setting `bool')
 -- Method: set-headers-clickable
     Allow the column title buttons to be clicked.

    TREE-VIEW
          A `<gtk-tree-view>'.

    SETTING
          ``#t'' if the columns are clickable.



 -- Function: gtk-tree-view-set-rules-hint (self `<gtk-tree-view>')
          (setting `bool')
 -- Method: set-rules-hint
     This function tells GTK+ that the user interface for your
     application requires users to read across tree rows and associate
     cells with one another. By default, GTK+ will then render the tree
     with alternating row colors. Do _not_ use it just because you
     prefer the appearance of the ruled tree; that's a question for the
     theme. Some themes will draw tree rows in alternating colors even
     when rules are turned off, and users who prefer that appearance
     all the time can choose those themes. You should call this
     function only as a _semantic_ hint to the theme engine that your
     tree makes alternating colors useful from a functional standpoint
     (since it has lots of columns, generally).

    TREE-VIEW
          a `<gtk-tree-view>'

    SETTING
          ``#t'' if the tree requires reading across rows



 -- Function: gtk-tree-view-get-rules-hint (self `<gtk-tree-view>') => 
          (ret `bool')
 -- Method: get-rules-hint
     Gets the setting set by `gtk-tree-view-set-rules-hint'.

    TREE-VIEW
          a `<gtk-tree-view>'

    RET
          ``#t'' if rules are useful for the user of this tree



 -- Function: gtk-tree-view-append-column (self `<gtk-tree-view>')
          (column `<gtk-tree-view-column>') =>  (ret `int')
 -- Method: append-column
     Appends COLUMN to the list of columns. If TREE-VIEW has
     "fixed_height" mode enabled, then COLUMN must have its "sizing"
     property set to be GTK_TREE_VIEW_COLUMN_FIXED.

    TREE-VIEW
          A `<gtk-tree-view>'.

    COLUMN
          The `<gtk-tree-view-column>' to add.

    RET
          The number of columns in TREE-VIEW after appending.



 -- Function: gtk-tree-view-remove-column (self `<gtk-tree-view>')
          (column `<gtk-tree-view-column>') =>  (ret `int')
 -- Method: remove-column
     Removes COLUMN from TREE-VIEW.

    TREE-VIEW
          A `<gtk-tree-view>'.

    COLUMN
          The `<gtk-tree-view-column>' to remove.

    RET
          The number of columns in TREE-VIEW after removing.



 -- Function: gtk-tree-view-insert-column (self `<gtk-tree-view>')
          (column `<gtk-tree-view-column>') (position `int') => 
          (ret `int')
 -- Method: insert-column
     This inserts the COLUMN into the TREE-VIEW at POSITION. If
     POSITION is -1, then the column is inserted at the end. If
     TREE-VIEW has "fixed_height" mode enabled, then COLUMN must have
     its "sizing" property set to be GTK_TREE_VIEW_COLUMN_FIXED.

    TREE-VIEW
          A `<gtk-tree-view>'.

    COLUMN
          The `<gtk-tree-view-column>' to be inserted.

    POSITION
          The position to insert COLUMN in.

    RET
          The number of columns in TREE-VIEW after insertion.



 -- Function: gtk-tree-view-get-column (self `<gtk-tree-view>')
          (n `int') =>  (ret `<gtk-tree-view-column>')
 -- Method: get-column
     Gets the `<gtk-tree-view-column>' at the given position in the
     `<tree-view>'.

    TREE-VIEW
          A `<gtk-tree-view>'.

    N
          The position of the column, counting from 0.

    RET
          The `<gtk-tree-view-column>', or ``#f'' if the position is
          outside the range of columns.



 -- Function: gtk-tree-view-get-columns (self `<gtk-tree-view>') => 
          (ret `glist-of')
 -- Method: get-columns
     Returns a `<g-list>' of all the `<gtk-tree-view-column>' s
     currently in TREE-VIEW. The returned list must be freed with
     `g-list-free'.

    TREE-VIEW
          A `<gtk-tree-view>'

    RET
          A list of `<gtk-tree-view-column>' s



 -- Function: gtk-tree-view-move-column-after (self `<gtk-tree-view>')
          (column `<gtk-tree-view-column>')
          (base_column `<gtk-tree-view-column>')
 -- Method: move-column-after
     Moves COLUMN to be after to BASE-COLUMN. If BASE-COLUMN is ``#f'',
     then COLUMN is placed in the first position.

    TREE-VIEW
          A `<gtk-tree-view>'

    COLUMN
          The `<gtk-tree-view-column>' to be moved.

    BASE-COLUMN
          The `<gtk-tree-view-column>' to be moved relative to, or
          ``#f''.



 -- Function: gtk-tree-view-set-expander-column
          (self `<gtk-tree-view>') (column `<gtk-tree-view-column>')
 -- Method: set-expander-column
     Sets the column to draw the expander arrow at. It must be in
     TREE-VIEW. If COLUMN is ``#f'', then the expander arrow is always
     at the first visible column.

     If you do not want expander arrow to appear in your tree, set the
     expander column to a hidden column.

    TREE-VIEW
          A `<gtk-tree-view>'

    COLUMN
          ``#f'', or the column to draw the expander arrow at.



 -- Function: gtk-tree-view-get-expander-column
          (self `<gtk-tree-view>') =>  (ret `<gtk-tree-view-column>')
 -- Method: get-expander-column
     Returns the column that is the current expander column. This
     column has the expander arrow drawn next to it.

    TREE-VIEW
          A `<gtk-tree-view>'

    RET
          The expander column.



 -- Function: gtk-tree-view-scroll-to-point (self `<gtk-tree-view>')
          (tree_x `int') (tree_y `int')
 -- Method: scroll-to-point
     Scrolls the tree view such that the top-left corner of the visible
     area is TREE-X, TREE-Y, where TREE-X and TREE-Y are specified in
     tree window coordinates. The TREE-VIEW must be realized before this
     function is called. If it isn't, you probably want to be using
     `gtk-tree-view-scroll-to-cell'.

     If either TREE-X or TREE-Y are -1, then that direction isn't
     scrolled.

    TREE-VIEW
          a `<gtk-tree-view>'

    TREE-X
          X coordinate of new top-left pixel of visible area, or -1

    TREE-Y
          Y coordinate of new top-left pixel of visible area, or -1



 -- Function: gtk-tree-view-scroll-to-cell (self `<gtk-tree-view>')
          (path `<gtk-tree-path>') (column `<gtk-tree-view-column>')
          (use_align `bool') (row_align `float') (col_align `float')
 -- Method: scroll-to-cell
     Moves the alignments of TREE-VIEW to the position specified by
     COLUMN and PATH. If COLUMN is ``#f'', then no horizontal scrolling
     occurs. Likewise, if PATH is ``#f'' no vertical scrolling occurs.
     At a minimum, one of COLUMN or PATH need to be non-``#f''.
     ROW-ALIGN determines where the row is placed, and COL-ALIGN
     determines where COLUMN is placed. Both are expected to be between
     0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom
     alignment, 0.5 means center.

     If USE-ALIGN is ``#f'', then the alignment arguments are ignored,
     and the tree does the minimum amount of work to scroll the cell
     onto the screen. This means that the cell will be scrolled to the
     edge closest to its current position. If the cell is currently
     visible on the screen, nothing is done.

     This function only works if the model is set, and PATH is a valid
     row on the model. If the model changes before the TREE-VIEW is
     realized, the centered path will be modified to reflect this
     change.

    TREE-VIEW
          A `<gtk-tree-view>'.

    PATH
          The path of the row to move to, or ``#f''.

    COLUMN
          The `<gtk-tree-view-column>' to move horizontally to, or
          ``#f''.

    USE-ALIGN
          whether to use alignment arguments, or ``#f''.

    ROW-ALIGN
          The vertical alignment of the row specified by PATH.

    COL-ALIGN
          The horizontal alignment of the column specified by COLUMN.



 -- Function: gtk-tree-view-set-cursor (self `<gtk-tree-view>')
          (path `<gtk-tree-path>')
          (focus_column `<gtk-tree-view-column>') (start_editing `bool')
 -- Method: set-cursor
     Sets the current keyboard focus to be at PATH, and selects it.
     This is useful when you want to focus the user's attention on a
     particular row. If FOCUS-COLUMN is not ``#f'', then focus is given
     to the column specified by it. Additionally, if FOCUS-COLUMN is
     specified, and START-EDITING is ``#t'', then editing should be
     started in the specified cell. This function is often followed by
     GTK-WIDGET-GRAB-FOCUS (TREE-VIEW) in order to give keyboard focus
     to the widget. Please note that editing can only happen when the
     widget is realized.

    TREE-VIEW
          A `<gtk-tree-view>'

    PATH
          A `<gtk-tree-path>'

    FOCUS-COLUMN
          A `<gtk-tree-view-column>', or ``#f''

    START-EDITING
          ``#t'' if the specified cell should start being edited.



 -- Function: gtk-tree-view-set-cursor-on-cell (self `<gtk-tree-view>')
          (path `<gtk-tree-path>')
          (focus_column `<gtk-tree-view-column>')
          (focus_cell `<gtk-cell-renderer>') (start_editing `bool')
 -- Method: set-cursor-on-cell
     Sets the current keyboard focus to be at PATH, and selects it.
     This is useful when you want to focus the user's attention on a
     particular row. If FOCUS-COLUMN is not ``#f'', then focus is given
     to the column specified by it. If FOCUS-COLUMN and FOCUS-CELL are
     not ``#f'', and FOCUS-COLUMN contains 2 or more editable or
     activatable cells, then focus is given to the cell specified by
     FOCUS-CELL. Additionally, if FOCUS-COLUMN is specified, and
     START-EDITING is ``#t'', then editing should be started in the
     specified cell. This function is often followed by
     GTK-WIDGET-GRAB-FOCUS (TREE-VIEW) in order to give keyboard focus
     to the widget. Please note that editing can only happen when the
     widget is realized.

    TREE-VIEW
          A `<gtk-tree-view>'

    PATH
          A `<gtk-tree-path>'

    FOCUS-COLUMN
          A `<gtk-tree-view-column>', or ``#f''

    FOCUS-CELL
          A `<gtk-cell-renderer>', or ``#f''

    START-EDITING
          ``#t'' if the specified cell should start being edited.


     Since 2.2


 -- Function: gtk-tree-view-row-activated (self `<gtk-tree-view>')
          (path `<gtk-tree-path>') (column `<gtk-tree-view-column>')
 -- Method: row-activated
     Activates the cell determined by PATH and COLUMN.

    TREE-VIEW
          A `<gtk-tree-view>'

    PATH
          The `<gtk-tree-path>' to be activated.

    COLUMN
          The `<gtk-tree-view-column>' to be activated.



 -- Function: gtk-tree-view-expand-all (self `<gtk-tree-view>')
 -- Method: expand-all
     Recursively expands all nodes in the TREE-VIEW.

    TREE-VIEW
          A `<gtk-tree-view>'.



 -- Function: gtk-tree-view-collapse-all (self `<gtk-tree-view>')
 -- Method: collapse-all
     Recursively collapses all visible, expanded nodes in TREE-VIEW.

    TREE-VIEW
          A `<gtk-tree-view>'.



 -- Function: gtk-tree-view-expand-to-path (self `<gtk-tree-view>')
          (path `<gtk-tree-path>')
 -- Method: expand-to-path
     Expands the row at PATH. This will also expand all parent rows of
     PATH as necessary.

    TREE-VIEW
          A `<gtk-tree-view>'.

    PATH
          path to a row.


     Since 2.2


 -- Function: gtk-tree-view-expand-row (self `<gtk-tree-view>')
          (path `<gtk-tree-path>') (open_all `bool') =>  (ret `bool')
 -- Method: expand-row
     Opens the row so its children are visible.

    TREE-VIEW
          a `<gtk-tree-view>'

    PATH
          path to a row

    OPEN-ALL
          whether to recursively expand, or just expand immediate
          children

    RET
          ``#t'' if the row existed and had children



 -- Function: gtk-tree-view-collapse-row (self `<gtk-tree-view>')
          (path `<gtk-tree-path>') =>  (ret `bool')
 -- Method: collapse-row
     Collapses a row (hides its child rows, if they exist).

    TREE-VIEW
          a `<gtk-tree-view>'

    PATH
          path to a row in the TREE-VIEW

    RET
          ``#t'' if the row was collapsed.



 -- Function: gtk-tree-view-row-expanded (self `<gtk-tree-view>')
          (path `<gtk-tree-path>') =>  (ret `bool')
 -- Method: row-expanded
     Returns ``#t'' if the node pointed to by PATH is expanded in
     TREE-VIEW.

    TREE-VIEW
          A `<gtk-tree-view>'.

    PATH
          A `<gtk-tree-path>' to test expansion state.

    RET
          ``#t'' if `<path>' is expanded.



 -- Function: gtk-tree-view-set-reorderable (self `<gtk-tree-view>')
          (reorderable `bool')
 -- Method: set-reorderable
     This function is a convenience function to allow you to reorder
     models that support the `<gtk-drag-source-iface>' and the
     `<gtk-drag-dest-iface>'.  Both `<gtk-tree-store>' and
     `<gtk-list-store>' support these. If REORDERABLE is ``#t'', then
     the user can reorder the model by dragging and dropping rows. The
     developer can listen to these changes by connecting to the model's
     row_inserted and row_deleted signals.

     This function does not give you any degree of control over the
     order - any reordering is allowed. If more control is needed, you
     should probably handle drag and drop manually.

    TREE-VIEW
          A `<gtk-tree-view>'.

    REORDERABLE
          ``#t'', if the tree can be reordered.



 -- Function: gtk-tree-view-get-reorderable (self `<gtk-tree-view>')
          =>  (ret `bool')
 -- Method: get-reorderable
     Retrieves whether the user can reorder the tree via drag-and-drop.
     See `gtk-tree-view-set-reorderable'.

    TREE-VIEW
          a `<gtk-tree-view>'

    RET
          ``#t'' if the tree can be reordered.



 -- Function: gtk-tree-view-get-bin-window (self `<gtk-tree-view>') => 
          (ret `<gdk-window>')
 -- Method: get-bin-window
     Returns the window that TREE-VIEW renders to. This is used
     primarily to compare to `event->window' to confirm that the event
     on TREE-VIEW is on the right window.

    TREE-VIEW
          A `<gtk-tree-view>'

    RET
          A `<gdk-window>', or ``#f'' when TREE-VIEW hasn't been
          realized yet



 -- Function: gtk-tree-view-widget-to-tree-coords
          (self `<gtk-tree-view>') (wx `int') (wy `int') =>  (tx `int')
          (ty `int')
 -- Method: widget-to-tree-coords
     Converts widget coordinates to coordinates for the tree window
     (the full scrollable area of the tree).

    TREE-VIEW
          a `<gtk-tree-view>'

    WX
          widget X coordinate

    WY
          widget Y coordinate

    TX
          return location for tree X coordinate

    TY
          return location for tree Y coordinate



 -- Function: gtk-tree-view-tree-to-widget-coords
          (self `<gtk-tree-view>') (tx `int') (ty `int') =>  (wx `int')
          (wy `int')
 -- Method: tree-to-widget-coords
     Converts tree coordinates (coordinates in full scrollable area of
     the tree) to widget coordinates.

    TREE-VIEW
          a `<gtk-tree-view>'

    TX
          tree X coordinate

    TY
          tree Y coordinate

    WX
          return location for widget X coordinate

    WY
          return location for widget Y coordinate



 -- Function: gtk-tree-view-unset-rows-drag-dest
          (self `<gtk-tree-view>')
 -- Method: unset-rows-drag-dest
     Undoes the effect of `gtk-tree-view-enable-model-drag-dest'.

    TREE-VIEW
          a `<gtk-tree-view>'



 -- Function: gtk-tree-view-set-drag-dest-row (self `<gtk-tree-view>')
          (path `<gtk-tree-path>') (pos `<gtk-tree-view-drop-position>')
 -- Method: set-drag-dest-row
     Sets the row that is highlighted for feedback.

    TREE-VIEW
          a `<gtk-tree-view>'

    PATH
          The path of the row to highlight, or ``#f''.

    POS
          Specifies whether to drop before, after or into the row



 -- Function: gtk-tree-view-create-row-drag-icon
          (self `<gtk-tree-view>') (path `<gtk-tree-path>') => 
          (ret `<gdk-pixmap>')
 -- Method: create-row-drag-icon
     Creates a `<gdk-pixmap>' representation of the row at PATH. This
     image is used for a drag icon.

    TREE-VIEW
          a `<gtk-tree-view>'

    PATH
          a `<gtk-tree-path>' in TREE-VIEW

    RET
          a newly-allocated pixmap of the drag icon.



 -- Function: gtk-tree-view-set-enable-search (self `<gtk-tree-view>')
          (enable_search `bool')
 -- Method: set-enable-search
     If ENABLE-SEARCH is set, then the user can type in text to search
     through the tree interactively (this is sometimes called
     "typeahead find").

     Note that even if this is ``#f'', the user can still initiate a
     search using the "start-interactive-search" key binding.

    TREE-VIEW
          A `<gtk-tree-view>'

    ENABLE-SEARCH
          ``#t'', if the user can search interactively



 -- Function: gtk-tree-view-get-enable-search (self `<gtk-tree-view>')
          =>  (ret `bool')
 -- Method: get-enable-search
     Returns whether or not the tree allows to start interactive
     searching by typing in text.

    TREE-VIEW
          A `<gtk-tree-view>'

    RET
          whether or not to let the user search interactively



 -- Function: gtk-tree-view-get-search-column (self `<gtk-tree-view>')
          =>  (ret `int')
 -- Method: get-search-column
     Gets the column searched on by the interactive search code.

    TREE-VIEW
          A `<gtk-tree-view>'

    RET
          the column the interactive search code searches in.



 -- Function: gtk-tree-view-set-search-column (self `<gtk-tree-view>')
          (column `int')
 -- Method: set-search-column
     Sets COLUMN as the column where the interactive search code should
     search in.

     If the sort column is set, users can use the
     "start-interactive-search" key binding to bring up search popup.
     The enable-search property controls whether simply typing text
     will also start an interactive search.

     Note that COLUMN refers to a column of the model.

    TREE-VIEW
          A `<gtk-tree-view>'

    COLUMN
          the column of the model to search in, or -1 to disable
          searching



 -- Function: gtk-tree-view-get-search-entry (self `<gtk-tree-view>')
          =>  (ret `<gtk-entry>')
 -- Method: get-search-entry
     Returns the GtkEntry which is currently in use as interactive
     search entry for TREE-VIEW. In case the built-in entry is being
     used, ``#f'' will be returned.

    TREE-VIEW
          A `<gtk-tree-view>'

    RET
          the entry currently in use as search entry.


     Since 2.10


 -- Function: gtk-tree-view-set-search-entry (self `<gtk-tree-view>')
          (entry `<gtk-entry>')
 -- Method: set-search-entry
     Sets the entry which the interactive search code will use for this
     TREE-VIEW. This is useful when you want to provide a search entry
     in our interface at all time at a fixed position. Passing ``#f''
     for ENTRY will make the interactive search code use the built-in
     popup entry again.

    TREE-VIEW
          A `<gtk-tree-view>'

    ENTRY
          the entry the interactive search code of TREE-VIEW should use
          or ``#f''


     Since 2.10


 -- Function: gtk-tree-view-get-fixed-height-mode
          (self `<gtk-tree-view>') =>  (ret `bool')
 -- Method: get-fixed-height-mode
     Returns whether fixed height mode is turned on for TREE-VIEW.

    TREE-VIEW
          a `<gtk-tree-view>'

    RET
          ``#t'' if TREE-VIEW is in fixed height mode


     Since 2.6


 -- Function: gtk-tree-view-set-fixed-height-mode
          (self `<gtk-tree-view>') (enable `bool')
 -- Method: set-fixed-height-mode
     Enables or disables the fixed height mode of TREE-VIEW. Fixed
     height mode speeds up `<gtk-tree-view>' by assuming that all rows
     have the same height.  Only enable this option if all rows are the
     same height and all columns are of type
     `GTK_TREE_VIEW_COLUMN_FIXED'.

    TREE-VIEW
          a `<gtk-tree-view>'

    ENABLE
          ``#t'' to enable fixed height mode


     Since 2.6


 -- Function: gtk-tree-view-get-hover-selection
          (self `<gtk-tree-view>') =>  (ret `bool')
 -- Method: get-hover-selection
     Returns whether hover selection mode is turned on for TREE-VIEW.

    TREE-VIEW
          a `<gtk-tree-view>'

    RET
          ``#t'' if TREE-VIEW is in hover selection mode


     Since 2.6


 -- Function: gtk-tree-view-set-hover-selection
          (self `<gtk-tree-view>') (hover `bool')
 -- Method: set-hover-selection
     Enables of disables the hover selection mode of TREE-VIEW. Hover
     selection makes the selected row follow the pointer. Currently,
     this works only for the selection modes `GTK_SELECTION_SINGLE' and
     `GTK_SELECTION_BROWSE'.

    TREE-VIEW
          a `<gtk-tree-view>'

    HOVER
          ``#t'' to enable hover selection mode


     Since 2.6


 -- Function: gtk-tree-view-get-hover-expand (self `<gtk-tree-view>')
          =>  (ret `bool')
 -- Method: get-hover-expand
     Returns whether hover expansion mode is turned on for TREE-VIEW.

    TREE-VIEW
          a `<gtk-tree-view>'

    RET
          ``#t'' if TREE-VIEW is in hover expansion mode


     Since 2.6


 -- Function: gtk-tree-view-set-hover-expand (self `<gtk-tree-view>')
          (expand `bool')
 -- Method: set-hover-expand
     Enables of disables the hover expansion mode of TREE-VIEW. Hover
     expansion makes rows expand or collaps if the pointer moves over
     them.

    TREE-VIEW
          a `<gtk-tree-view>'

    EXPAND
          ``#t'' to enable hover selection mode


     Since 2.6


 -- Function: gtk-tree-view-get-rubber-banding (self `<gtk-tree-view>')
          =>  (ret `bool')
 -- Method: get-rubber-banding
     Returns whether rubber banding is turned on for TREE-VIEW. If the
     selection mode is `<gtk-selection-multiple>', rubber banding will
     allow the user to select multiple rows by dragging the mouse.

    TREE-VIEW
          a `<gtk-tree-view>'

    RET
          ``#t'' if rubber banding in TREE-VIEW is enabled.


     Since 2.10


 -- Function: gtk-tree-view-set-rubber-banding (self `<gtk-tree-view>')
          (enable `bool')
 -- Method: set-rubber-banding
     Enables or disables rubber banding in TREE-VIEW. If the selection
     mode is `<gtk-selection-multiple>', rubber banding will allow the
     user to select multiple rows by dragging the mouse.

    TREE-VIEW
          a `<gtk-tree-view>'

    ENABLE
          ``#t'' to enable rubber banding


     Since 2.10


 -- Function: gtk-tree-view-get-enable-tree-lines
          (self `<gtk-tree-view>') =>  (ret `bool')
 -- Method: get-enable-tree-lines
     Returns whether or not tree lines are drawn in TREE-VIEW.

    TREE-VIEW
          a `<gtk-tree-view>'.

    RET
          ``#t'' if tree lines are drawn in TREE-VIEW, ``#f'' otherwise.


     Since 2.10


 -- Function: gtk-tree-view-set-enable-tree-lines
          (self `<gtk-tree-view>') (enabled `bool')
 -- Method: set-enable-tree-lines
     Sets whether to draw lines interconnecting the expanders in
     TREE-VIEW.  This does not have any visible effects for lists.

    TREE-VIEW
          a `<gtk-tree-view>'

    ENABLED
          ``#t'' to enable tree line drawing, ``#f'' otherwise.


     Since 2.10


 -- Function: gtk-tree-view-get-grid-lines (self `<gtk-tree-view>') => 
          (ret `<gtk-tree-view-grid-lines>')
 -- Method: get-grid-lines
     Returns which grid lines are enabled in TREE-VIEW.

    TREE-VIEW
          a `<gtk-tree-view>'

    RET
          a `<gtk-tree-view-grid-lines>' value indicating which grid
          lines are enabled.


     Since 2.10


 -- Function: gtk-tree-view-set-grid-lines (self `<gtk-tree-view>')
          (grid_lines `<gtk-tree-view-grid-lines>')
 -- Method: set-grid-lines
     Sets which grid lines to draw in TREE-VIEW.

    TREE-VIEW
          a `<gtk-tree-view>'

    GRID-LINES
          a `<gtk-tree-view-grid-lines>' value indicating which grid
          lines to enable.


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkTreeView drag-and-drop,  Next: GtkCellView,  Prev: GtkTreeView,  Up: Top

36 GtkTreeView drag-and-drop
****************************

Interfaces for drag-and-drop support in GtkTreeView

36.1 Overview
=============

GTK+ supports Drag-and-Drop in tree views with a high-level and a
low-level API.

   The low-level API consists of the GTK+ DND API, augmented by some
treeview utility functions: `gtk-tree-view-set-drag-dest-row',
`gtk-tree-view-get-drag-dest-row', `gtk-tree-view-get-dest-row-at-pos',
`gtk-tree-view-create-row-drag-icon', `gtk-tree-set-row-drag-data' and
`gtk-tree-get-row-drag-data'. This API leaves a lot of flexibility, but
nothing is done automatically, and implementing advanced features like
hover-to-open-rows or autoscrolling on top of this API is a lot of work.

   On the other hand, if you write to the high-level API, then all the
bookkeeping of rows is done for you, as well as things like
hover-to-open and auto-scroll, but your models have to implement the
`<gtk-tree-drag-source>' and `<gtk-tree-drag-dest>' interfaces.

36.2 Usage
==========

 -- Class: <gtk-tree-drag-source>
     Derives from `<ginterface>'.

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


 -- Class: <gtk-tree-drag-dest>
     Derives from `<ginterface>'.

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


 -- Function: gtk-tree-drag-source-drag-data-get
          (self `<gtk-tree-drag-source>') (path `<gtk-tree-path>')
          (selection_data `<gtk-selection-data>') =>  (ret `bool')
 -- Method: drag-data-get
     Asks the `<gtk-tree-drag-source>' to fill in SELECTION-DATA with a
     representation of the row at PATH. SELECTION-DATA->TARGET gives the
     required type of the data. Should robustly handle a PATH no longer
     found in the model!

    DRAG-SOURCE
          a `<gtk-tree-drag-source>'

    PATH
          row that was dragged

    SELECTION-DATA
          a `<gtk-selection-data>' to fill with data from the dragged
          row

    RET
          ``#t'' if data of the required type was provided



 -- Function: gtk-tree-drag-source-row-draggable
          (self `<gtk-tree-drag-source>') (path `<gtk-tree-path>') => 
          (ret `bool')
 -- Method: row-draggable
     Asks the `<gtk-tree-drag-source>' whether a particular row can be
     used as the source of a DND operation. If the source doesn't
     implement this interface, the row is assumed draggable.

    DRAG-SOURCE
          a `<gtk-tree-drag-source>'

    PATH
          row on which user is initiating a drag

    RET
          ``#t'' if the row can be dragged



 -- Function: gtk-tree-set-row-drag-data (self `<gtk-selection-data>')
          (tree_model `<gtk-tree-model>') (path `<gtk-tree-path>') => 
          (ret `bool')
     Sets selection data of target type `GTK_TREE_MODEL_ROW'. Normally
     used in a drag_data_get handler.

    SELECTION-DATA
          some `<gtk-selection-data>'

    TREE-MODEL
          a `<gtk-tree-model>'

    PATH
          a row in TREE-MODEL

    RET
          ``#t'' if the `<gtk-selection-data>' had the proper target
          type to allow us to set a tree row




File: guile-gnome-gtk.info,  Node: GtkCellView,  Next: GtkIconView,  Prev: GtkTreeView drag-and-drop,  Up: Top

37 GtkCellView
**************

A widget displaying a single row of a GtkTreeModel

37.1 Overview
=============

A `<gtk-cell-view>' displays a single row of a `<gtk-tree-model>',
using cell renderers just like `<gtk-tree-view>'. `<gtk-cell-view>'
doesn't support some of the more complex features of `<gtk-tree-view>',
like cell editing and drag and drop.

37.2 Usage
==========

 -- Class: <gtk-cell-view>
     Derives from `<gtk-cell-layout>', `<gtk-widget>'.

     This class defines the following properties:

    `background'
          Background color as a string

    `background-gdk'
          Background color as a GdkColor

    `background-set'
          Whether this tag affects the background color

    `model'
          The model for cell view



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

    RET
          A newly created `<gtk-cell-view>' widget.


     Since 2.6


 -- Function: gtk-cell-view-new-with-text (text `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-cell-view>' widget, adds a
     `<gtk-cell-renderer-text>' to it, and makes its show TEXT.

    TEXT
          the text to display in the cell view

    RET
          A newly created `<gtk-cell-view>' widget.


     Since 2.6


 -- Function: gtk-cell-view-new-with-markup (markup `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-cell-view>' widget, adds a
     `<gtk-cell-renderer-text>' to it, and makes its show MARKUP. The
     text can text can be marked up with the Pango text markup language.

    MARKUP
          the text to display in the cell view

    RET
          A newly created `<gtk-cell-view>' widget.


     Since 2.6


 -- Function: gtk-cell-view-new-with-pixbuf (pixbuf `<gdk-pixbuf>') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-cell-view>' widget, adds a
     `<gtk-cell-renderer-pixbuf>' to it, and makes its show PIXBUF.

    PIXBUF
          the image to display in the cell view

    RET
          A newly created `<gtk-cell-view>' widget.


     Since 2.6


 -- Function: gtk-cell-view-set-model (self `<gtk-cell-view>')
          (model `<gtk-tree-model>')
 -- Method: set-model
     Sets the model for CELL-VIEW. If CELL-VIEW already has a model set,
     it will remove it before setting the new model. If MODEL is
     ``#f'', then it will unset the old model.

    CELL-VIEW
          a `<gtk-cell-view>'

    MODEL
          a `<gtk-tree-model>'


     Since 2.6


 -- Function: gtk-cell-view-set-displayed-row (self `<gtk-cell-view>')
          (path `<gtk-tree-path>')
 -- Method: set-displayed-row
     Sets the row of the model that is currently displayed by the
     `<gtk-cell-view>'. If the path is unset, then the contents of the
     cellview "stick" at their last value; this is not normally a
     desired result, but may be a needed intermediate state if say, the
     model for the `<gtk-cell-view>' becomes temporarily empty.

    CELL-VIEW
          a `<gtk-cell-view>'

    PATH
          a `<gtk-tree-path>' or ``#f'' to unset.


     Since 2.6


 -- Function: gtk-cell-view-get-displayed-row (self `<gtk-cell-view>')
          =>  (ret `<gtk-tree-path>')
 -- Method: get-displayed-row
     Returns a `<gtk-tree-path>' referring to the currently displayed
     row. If no row is currently displayed, ``#f'' is returned.

    CELL-VIEW
          a `<gtk-cell-view>'

    RET
          the currently displayed row or ``#f''


     Since 2.6


 -- Function: gtk-cell-view-get-size-of-row (self `<gtk-cell-view>')
          (path `<gtk-tree-path>') (requisition `<gtk-requisition>')
          =>  (ret `bool')
 -- Method: get-size-of-row
     Sets REQUISITION to the size needed by CELL-VIEW to display the
     model row pointed to by PATH.

    CELL-VIEW
          a `<gtk-cell-view>'

    PATH
          a `<gtk-tree-path>'

    REQUISITION
          return location for the size

    RET
          ``#t''


     Since 2.6


 -- Function: gtk-cell-view-set-background-color
          (self `<gtk-cell-view>') (color `<gdk-color>')
 -- Method: set-background-color
     Sets the background color of VIEW.

    CELL-VIEW
          a `<gtk-cell-view>'

    COLOR
          the new background color


     Since 2.6


 -- Function: gtk-cell-view-get-cell-renderers (self `<gtk-cell-view>')
          =>  (ret `glist-of')
 -- Method: get-cell-renderers
     Returns the cell renderers which have been added to CELL-VIEW.

    CELL-VIEW
          a `<gtk-cell-view>'

    RET
          a list of cell renderers. The list, but not the renderers has
          been newly allocated and should be freed with `g-list-free'
          when no longer needed.


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkIconView,  Next: GtkTreeSortable,  Prev: GtkCellView,  Up: Top

38 GtkIconView
**************

A widget which displays a list of icons in a grid

38.1 Overview
=============

`<gtk-icon-view>' provides an alternative view on a list model. It
displays the model as a grid of icons with labels. Like
`<gtk-tree-view>', it allows to select one or multiple items (depending
on the selection mode, see `gtk-icon-view-set-selection-mode'). In
addition to selection with the arrow keys, `<gtk-icon-view>' supports
rubberband selection, which is controlled by dragging the pointer.

38.2 Usage
==========

 -- Class: <gtk-icon-view>
     Derives from `<gtk-cell-layout>', `<gtk-container>'.

     This class defines the following properties:

    `pixbuf-column'
          Model column used to retrieve the icon pixbuf from

    `text-column'
          Model column used to retrieve the text from

    `markup-column'
          Model column used to retrieve the text if using Pango markup

    `selection-mode'
          The selection mode

    `orientation'
          How the text and icon of each item are positioned relative to
          each other

    `model'
          The model for the icon view

    `columns'
          Number of columns to display

    `item-width'
          The width used for each item

    `spacing'
          Space which is inserted between cells of an item

    `row-spacing'
          Space which is inserted between grid rows

    `column-spacing'
          Space which is inserted between grid columns

    `margin'
          Space which is inserted at the edges of the icon view

    `reorderable'
          View is reorderable

    `tooltip-column'
          The column in the model containing the tooltip texts for the
          items



 -- Signal on <gtk-icon-view>: move-cursor (arg0 `<gtk-movement-step>')
          (arg1 `<gint>') => `<gboolean>'

 -- Signal on <gtk-icon-view>: selection-changed

 -- Signal on <gtk-icon-view>: set-scroll-adjustments
          (arg0 `<gtk-adjustment>') (arg1 `<gtk-adjustment>')

 -- Signal on <gtk-icon-view>: item-activated (arg0 `<gtk-tree-path>')

 -- Signal on <gtk-icon-view>: select-all

 -- Signal on <gtk-icon-view>: unselect-all

 -- Signal on <gtk-icon-view>: select-cursor-item

 -- Signal on <gtk-icon-view>: toggle-cursor-item

 -- Signal on <gtk-icon-view>: activate-cursor-item => `<gboolean>'

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

    RET
          A newly created `<gtk-icon-view>' widget


     Since 2.6


 -- Function: gtk-icon-view-new-with-model (model `<gtk-tree-model>')
          =>  (ret `<gtk-widget>')
     Creates a new `<gtk-icon-view>' widget with the model MODEL.

    MODEL
          The model.

    RET
          A newly created `<gtk-icon-view>' widget.


     Since 2.6


 -- Function: gtk-icon-view-set-model (self `<gtk-icon-view>')
          (model `<gtk-tree-model>')
 -- Method: set-model
     Sets the model for a `<gtk-icon-view>'. If the ICON-VIEW already
     has a model set, it will remove it before setting the new model.
     If MODEL is ``#f'', then it will unset the old model.

    ICON-VIEW
          A `<gtk-icon-view>'.

    MODEL
          The model.


     Since 2.6


 -- Function: gtk-icon-view-get-model (self `<gtk-icon-view>') => 
          (ret `<gtk-tree-model>')
 -- Method: get-model
     Returns the model the `<gtk-icon-view>' is based on. Returns
     ``#f'' if the model is unset.

    ICON-VIEW
          a `<gtk-icon-view>'

    RET
          A `<gtk-tree-model>', or ``#f'' if none is currently being
          used.


     Since 2.6


 -- Function: gtk-icon-view-set-text-column (self `<gtk-icon-view>')
          (column `int')
 -- Method: set-text-column
     Sets the column with text for ICON-VIEW to be COLUMN. The text
     column must be of type `<g-type-string>'.

    ICON-VIEW
          A `<gtk-icon-view>'.

    COLUMN
          A column in the currently used model.


     Since 2.6


 -- Function: gtk-icon-view-get-text-column (self `<gtk-icon-view>')
          =>  (ret `int')
 -- Method: get-text-column
     Returns the column with text for ICON-VIEW.

    ICON-VIEW
          A `<gtk-icon-view>'.

    RET
          the text column, or -1 if it's unset.


     Since 2.6


 -- Function: gtk-icon-view-set-markup-column (self `<gtk-icon-view>')
          (column `int')
 -- Method: set-markup-column
     Sets the column with markup information for ICON-VIEW to be COLUMN.
     The markup column must be of type `<g-type-string>'. If the markup
     column is set to something, it overrides the text column set by
     `gtk-icon-view-set-text-column'.

    ICON-VIEW
          A `<gtk-icon-view>'.

    COLUMN
          A column in the currently used model.


     Since 2.6


 -- Function: gtk-icon-view-get-markup-column (self `<gtk-icon-view>')
          =>  (ret `int')
 -- Method: get-markup-column
     Returns the column with markup text for ICON-VIEW.

    ICON-VIEW
          A `<gtk-icon-view>'.

    RET
          the markup column, or -1 if it's unset.


     Since 2.6


 -- Function: gtk-icon-view-set-pixbuf-column (self `<gtk-icon-view>')
          (column `int')
 -- Method: set-pixbuf-column
     Sets the column with pixbufs for ICON-VIEW to be COLUMN. The pixbuf
     column must be of type `<gdk-type-pixbuf>'

    ICON-VIEW
          A `<gtk-icon-view>'.

    COLUMN
          A column in the currently used model.


     Since 2.6


 -- Function: gtk-icon-view-get-pixbuf-column (self `<gtk-icon-view>')
          =>  (ret `int')
 -- Method: get-pixbuf-column
     Returns the column with pixbufs for ICON-VIEW.

    ICON-VIEW
          A `<gtk-icon-view>'.

    RET
          the pixbuf column, or -1 if it's unset.


     Since 2.6


 -- Function: gtk-icon-view-get-path-at-pos (self `<gtk-icon-view>')
          (x `int') (y `int') =>  (ret `<gtk-tree-path>')
 -- Method: get-path-at-pos
     Finds the path at the point (X, Y), relative to widget coordinates.
     See `gtk-icon-view-get-item-at-pos', if you are also interested in
     the cell at the specified position.

    ICON-VIEW
          A `<gtk-icon-view>'.

    X
          The x position to be identified

    Y
          The y position to be identified

    RET
          The `<gtk-tree-path>' corresponding to the icon or ``#f'' if
          no icon exists at that position.


     Since 2.6


 -- Function: gtk-icon-view-set-cursor (self `<gtk-icon-view>')
          (path `<gtk-tree-path>') (cell `<gtk-cell-renderer>')
          (start_editing `bool')
 -- Method: set-cursor
     Sets the current keyboard focus to be at PATH, and selects it.
     This is useful when you want to focus the user's attention on a
     particular item. If CELL is not ``#f'', then focus is given to the
     cell specified by it. Additionally, if START-EDITING is ``#t'',
     then editing should be started in the specified cell.

     This function is often followed by `gtk_widget_grab_focus
     (icon_view)' in order to give keyboard focus to the widget. Please
     note that editing can only happen when the widget is realized.

    ICON-VIEW
          A `<gtk-icon-view>'

    PATH
          A `<gtk-tree-path>'

    CELL
          One of the cell renderers of ICON-VIEW, or ``#f''

    START-EDITING
          ``#t'' if the specified cell should start being edited.


     Since 2.8


 -- Function: gtk-icon-view-set-selection-mode (self `<gtk-icon-view>')
          (mode `<gtk-selection-mode>')
 -- Method: set-selection-mode
     Sets the selection mode of the ICON-VIEW.

    ICON-VIEW
          A `<gtk-icon-view>'.

    MODE
          The selection mode


     Since 2.6


 -- Function: gtk-icon-view-get-selection-mode (self `<gtk-icon-view>')
          =>  (ret `<gtk-selection-mode>')
 -- Method: get-selection-mode
     Gets the selection mode of the ICON-VIEW.

    ICON-VIEW
          A `<gtk-icon-view>'.

    RET
          the current selection mode


     Since 2.6


 -- Function: gtk-icon-view-set-orientation (self `<gtk-icon-view>')
          (orientation `<gtk-orientation>')
 -- Method: set-orientation
     Sets the ::orientation property which determines whether the
     labels are drawn beside the icons instead of below.

    ICON-VIEW
          a `<gtk-icon-view>'

    ORIENTATION
          the relative position of texts and icons


     Since 2.6


 -- Function: gtk-icon-view-get-orientation (self `<gtk-icon-view>')
          =>  (ret `<gtk-orientation>')
 -- Method: get-orientation
     Returns the value of the ::orientation property which determines
     whether the labels are drawn beside the icons instead of below.

    ICON-VIEW
          a `<gtk-icon-view>'

    RET
          the relative position of texts and icons


     Since 2.6


 -- Function: gtk-icon-view-set-columns (self `<gtk-icon-view>')
          (columns `int')
 -- Method: set-columns
     Sets the ::columns property which determines in how many columns
     the icons are arranged. If COLUMNS is -1, the number of columns
     will be chosen automatically to fill the available area.

    ICON-VIEW
          a `<gtk-icon-view>'

    COLUMNS
          the number of columns


     Since 2.6


 -- Function: gtk-icon-view-get-columns (self `<gtk-icon-view>') => 
          (ret `int')
 -- Method: get-columns
     Returns the value of the ::columns property.

    ICON-VIEW
          a `<gtk-icon-view>'

    RET
          the number of columns, or -1


     Since 2.6


 -- Function: gtk-icon-view-set-item-width (self `<gtk-icon-view>')
          (item_width `int')
 -- Method: set-item-width
     Sets the ::item-width property which specifies the width to use
     for each item.  If it is set to -1, the icon view will
     automatically determine a suitable item size.

    ICON-VIEW
          a `<gtk-icon-view>'

    ITEM-WIDTH
          the width for each item


     Since 2.6


 -- Function: gtk-icon-view-get-item-width (self `<gtk-icon-view>') => 
          (ret `int')
 -- Method: get-item-width
     Returns the value of the ::item-width property.

    ICON-VIEW
          a `<gtk-icon-view>'

    RET
          the width of a single item, or -1


     Since 2.6


 -- Function: gtk-icon-view-set-spacing (self `<gtk-icon-view>')
          (spacing `int')
 -- Method: set-spacing
     Sets the ::spacing property which specifies the space which is
     inserted between the cells (i.e. the icon and the text) of an item.

    ICON-VIEW
          a `<gtk-icon-view>'

    SPACING
          the spacing


     Since 2.6


 -- Function: gtk-icon-view-get-spacing (self `<gtk-icon-view>') => 
          (ret `int')
 -- Method: get-spacing
     Returns the value of the ::spacing property.

    ICON-VIEW
          a `<gtk-icon-view>'

    RET
          the space between cells


     Since 2.6


 -- Function: gtk-icon-view-set-row-spacing (self `<gtk-icon-view>')
          (row_spacing `int')
 -- Method: set-row-spacing
     Sets the ::row-spacing property which specifies the space which is
     inserted between the rows of the icon view.

    ICON-VIEW
          a `<gtk-icon-view>'

    ROW-SPACING
          the row spacing


     Since 2.6


 -- Function: gtk-icon-view-get-row-spacing (self `<gtk-icon-view>')
          =>  (ret `int')
 -- Method: get-row-spacing
     Returns the value of the ::row-spacing property.

    ICON-VIEW
          a `<gtk-icon-view>'

    RET
          the space between rows


     Since 2.6


 -- Function: gtk-icon-view-set-column-spacing (self `<gtk-icon-view>')
          (column_spacing `int')
 -- Method: set-column-spacing
     Sets the ::column-spacing property which specifies the space which
     is inserted between the columns of the icon view.

    ICON-VIEW
          a `<gtk-icon-view>'

    COLUMN-SPACING
          the column spacing


     Since 2.6


 -- Function: gtk-icon-view-get-column-spacing (self `<gtk-icon-view>')
          =>  (ret `int')
 -- Method: get-column-spacing
     Returns the value of the ::column-spacing property.

    ICON-VIEW
          a `<gtk-icon-view>'

    RET
          the space between columns


     Since 2.6


 -- Function: gtk-icon-view-set-margin (self `<gtk-icon-view>')
          (margin `int')
 -- Method: set-margin
     Sets the ::margin property which specifies the space which is
     inserted at the top, bottom, left and right of the icon view.

    ICON-VIEW
          a `<gtk-icon-view>'

    MARGIN
          the margin


     Since 2.6


 -- Function: gtk-icon-view-get-margin (self `<gtk-icon-view>') => 
          (ret `int')
 -- Method: get-margin
     Returns the value of the ::margin property.

    ICON-VIEW
          a `<gtk-icon-view>'

    RET
          the space at the borders


     Since 2.6


 -- Function: gtk-icon-view-select-path (self `<gtk-icon-view>')
          (path `<gtk-tree-path>')
 -- Method: select-path
     Selects the row at PATH.

    ICON-VIEW
          A `<gtk-icon-view>'.

    PATH
          The `<gtk-tree-path>' to be selected.


     Since 2.6


 -- Function: gtk-icon-view-unselect-path (self `<gtk-icon-view>')
          (path `<gtk-tree-path>')
 -- Method: unselect-path
     Unselects the row at PATH.

    ICON-VIEW
          A `<gtk-icon-view>'.

    PATH
          The `<gtk-tree-path>' to be unselected.


     Since 2.6


 -- Function: gtk-icon-view-path-is-selected (self `<gtk-icon-view>')
          (path `<gtk-tree-path>') =>  (ret `bool')
 -- Method: path-is-selected
     Returns ``#t'' if the icon pointed to by PATH is currently
     selected. If ICON does not point to a valid location, ``#f'' is
     returned.

    ICON-VIEW
          A `<gtk-icon-view>'.

    PATH
          A `<gtk-tree-path>' to check selection on.

    RET
          ``#t'' if PATH is selected.


     Since 2.6


 -- Function: gtk-icon-view-get-selected-items (self `<gtk-icon-view>')
          =>  (ret `glist-of')
 -- Method: get-selected-items
     Creates a list of paths of all selected items. Additionally, if
     you are planning on modifying the model after calling this
     function, you may want to convert the returned list into a list of
     `<gtk-tree-row-reference>'s. To do this, you can use
     `gtk-tree-row-reference-new'.

     To free the return value, use:


          g_list_foreach (list, gtk_tree_path_free, NULL);
          g_list_free (list);

    ICON-VIEW
          A `<gtk-icon-view>'.

    RET
          A `<g-list>' containing a `<gtk-tree-path>' for each selected
          row.


     Since 2.6


 -- Function: gtk-icon-view-select-all (self `<gtk-icon-view>')
 -- Method: select-all
     Selects all the icons. ICON-VIEW must has its selection mode set to
     `<gtk-selection-multiple>'.

    ICON-VIEW
          A `<gtk-icon-view>'.


     Since 2.6


 -- Function: gtk-icon-view-unselect-all (self `<gtk-icon-view>')
 -- Method: unselect-all
     Unselects all the icons.

    ICON-VIEW
          A `<gtk-icon-view>'.


     Since 2.6


 -- Function: gtk-icon-view-item-activated (self `<gtk-icon-view>')
          (path `<gtk-tree-path>')
 -- Method: item-activated
     Activates the item determined by PATH.

    ICON-VIEW
          A `<gtk-icon-view>'

    PATH
          The `<gtk-tree-path>' to be activated


     Since 2.6


 -- Function: gtk-icon-view-scroll-to-path (self `<gtk-icon-view>')
          (path `<gtk-tree-path>') (use_align `bool')
          (row_align `float') (col_align `float')
 -- Method: scroll-to-path
     Moves the alignments of ICON-VIEW to the position specified by
     PATH.  ROW-ALIGN determines where the row is placed, and COL-ALIGN
     determines where COLUMN is placed. Both are expected to be between
     0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom
     alignment, 0.5 means center.

     If USE-ALIGN is ``#f'', then the alignment arguments are ignored,
     and the tree does the minimum amount of work to scroll the item
     onto the screen. This means that the item will be scrolled to the
     edge closest to its current position. If the item is currently
     visible on the screen, nothing is done.

     This function only works if the model is set, and PATH is a valid
     row on the model. If the model changes before the ICON-VIEW is
     realized, the centered path will be modified to reflect this
     change.

    ICON-VIEW
          A `<gtk-icon-view>'.

    PATH
          The path of the item to move to.

    USE-ALIGN
          whether to use alignment arguments, or ``#f''.

    ROW-ALIGN
          The vertical alignment of the item specified by PATH.

    COL-ALIGN
          The horizontal alignment of the item specified by PATH.


     Since 2.8


 -- Function: gtk-icon-view-unset-model-drag-dest
          (self `<gtk-icon-view>')
 -- Method: unset-model-drag-dest
     Undoes the effect of `gtk-icon-view-enable-model-drag-dest'.

    ICON-VIEW
          a `<gtk-icon-view>'


     Since 2.8


 -- Function: gtk-icon-view-set-reorderable (self `<gtk-icon-view>')
          (reorderable `bool')
 -- Method: set-reorderable
     This function is a convenience function to allow you to reorder
     models that support the `<gtk-tree-drag-source-iface>' and the
     `<gtk-tree-drag-dest-iface>'. Both `<gtk-tree-store>' and
     `<gtk-list-store>' support these. If REORDERABLE is ``#t'', then
     the user can reorder the model by dragging and dropping rows. The
     developer can listen to these changes by connecting to the model's
     row_inserted and row_deleted signals.

     This function does not give you any degree of control over the
     order - any reordering is allowed. If more control is needed, you
     should probably handle drag and drop manually.

    ICON-VIEW
          A `<gtk-icon-view>'.

    REORDERABLE
          ``#t'', if the list of items can be reordered.


     Since 2.8


 -- Function: gtk-icon-view-get-reorderable (self `<gtk-icon-view>')
          =>  (ret `bool')
 -- Method: get-reorderable
     Retrieves whether the user can reorder the list via drag-and-drop.
     See `gtk-icon-view-set-reorderable'.

    ICON-VIEW
          a `<gtk-icon-view>'

    RET
          ``#t'' if the list can be reordered.


     Since 2.8


 -- Function: gtk-icon-view-set-drag-dest-item (self `<gtk-icon-view>')
          (path `<gtk-tree-path>') (pos `<gtk-icon-view-drop-position>')
 -- Method: set-drag-dest-item
     Sets the item that is highlighted for feedback.

    ICON-VIEW
          a `<gtk-icon-view>'

    PATH
          The path of the item to highlight, or ``#f''.

    POS
          Specifies where to drop, relative to the item


     Since 2.8


 -- Function: gtk-icon-view-create-drag-icon (self `<gtk-icon-view>')
          (path `<gtk-tree-path>') =>  (ret `<gdk-pixmap>')
 -- Method: create-drag-icon
     Creates a `<gdk-pixmap>' representation of the item at PATH. This
     image is used for a drag icon.

    ICON-VIEW
          a `<gtk-icon-view>'

    PATH
          a `<gtk-tree-path>' in ICON-VIEW

    RET
          a newly-allocated pixmap of the drag icon.


     Since 2.8



File: guile-gnome-gtk.info,  Node: GtkTreeSortable,  Next: GtkTreeModelSort,  Prev: GtkIconView,  Up: Top

39 GtkTreeSortable
******************

The interface for sortable models used by GtkTreeView

39.1 Overview
=============

`<gtk-tree-sortable>' is an interface to be implemented by tree models
which support sorting. The `<gtk-tree-view>' uses the methods provided
by this interface to sort the model.

39.2 Usage
==========

 -- Class: <gtk-tree-sortable>
     Derives from `<ginterface>'.

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


 -- Signal on <gtk-tree-sortable>: sort-column-changed


File: guile-gnome-gtk.info,  Node: GtkTreeModelSort,  Next: GtkTreeModelFilter,  Prev: GtkTreeSortable,  Up: Top

40 GtkTreeModelSort
*******************

A GtkTreeModel which makes an underlying tree model sortable

40.1 Overview
=============

The `<gtk-tree-model-sort>' is a model which implements the
`<gtk-tree-sortable>' interface. It does not hold any data itself, but
rather is created with a child model and proxies its data. It has
identical column types to this child model, and the changes in the
child are propagated.  The primary purpose of this model is to provide
a way to sort a different model without modifying it. Note that the
sort function used by `<gtk-tree-model-sort>' is not guaranteed to be
stable.

   The use of this is best demonstrated through an example. In the
following sample code we create two `<gtk-tree-view>' widgets each with
a view of the same data. As the model is wrapped here by a
`<gtk-tree-model-sort>', the two `<gtk-tree-view>'s can each sort their
view of the data without affecting the other. By contrast, if we simply
put the same model in each widget, then sorting the first would sort
the second.


     {
       GtkTreeView *tree_view1;
       GtkTreeView *tree_view2;
       GtkTreeModel *sort_model1;
       GtkTreeModel *sort_model2;
       GtkTreeModel *child_model;

       /* get the child model */
       child_model = get_my_model ();

       /* Create the first tree */
       sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
       tree_view1 = gtk_tree_view_new_with_model (sort_model1);

       /* Create the second tree */
       sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
       tree_view2 = gtk_tree_view_new_with_model (sort_model2);

       /* Now we can sort the two models independently */
       gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
                                             COLUMN_1, GTK_SORT_ASCENDING);
       gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
                                             COLUMN_1, GTK_SORT_DESCENDING);
     }

   To demonstrate how to access the underlying child model from the
sort model, the next example will be a callback for the
`<gtk-tree-selection>' "changed" signal. In this callback, we get a
string from COLUMN_1 of the model. We then modify the string, find the
same selected row on the child model, and change the row there.


     void
     selection_changed (GtkTreeSelection *selection, gpointer data)
     {
       GtkTreeModel *sort_model = NULL;
       GtkTreeModel *child_model;
       GtkTreeIter sort_iter;
       GtkTreeIter child_iter;
       char *some_data = NULL;
       char *modified_data;

       /* Get the current selected row and the model. */
       if (! gtk_tree_selection_get_selected (selection,
                                              &sort_model,
                                              &sort_iter))
         return;


       /* Look up the current value on the selected row and get a new value
        * to change it to.
        */
       gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter,
                           COLUMN_1, &some_data,
                           -1);

       modified_data = change_the_data (some_data);
       g_free (some_data);

       /* Get an iterator on the child model, instead of the sort model. */
       gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
                                                       &child_iter,
                                                       &sort_iter);

       /* Get the child model and change the value of the row.  In this
        * example, the child model is a GtkListStore.  It could be any other
        * type of model, though.
        */
       child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
       gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter,
                           COLUMN_1, &modified_data,
                           -1);
       g_free (modified_data);
     }

40.2 Usage
==========

 -- Class: <gtk-tree-model-sort>
     Derives from `<gtk-tree-model>', `<gtk-tree-drag-source>',
     `<gtk-tree-sortable>', `<gobject>'.

     This class defines the following properties:

    `model'
          The model for the TreeModelSort to sort



 -- Function: gtk-tree-model-sort-new-with-model
          (child_model `<gtk-tree-model>') =>  (ret `<gtk-tree-model>')
     Creates a new `<gtk-tree-model>', with CHILD-MODEL as the child
     model.

    CHILD-MODEL
          A `<gtk-tree-model>'

    RET
          A new `<gtk-tree-model>'.



 -- Function: gtk-tree-model-sort-get-model
          (self `<gtk-tree-model-sort>') =>  (ret `<gtk-tree-model>')
 -- Method: get-model
     Returns the model the `<gtk-tree-model-sort>' is sorting.

    TREE-MODEL
          a `<gtk-tree-model-sort>'

    RET
          the "child model" being sorted



 -- Function: gtk-tree-model-sort-clear-cache
          (self `<gtk-tree-model-sort>')
 -- Method: clear-cache
     This function should almost never be called. It clears the
     TREE-MODEL-SORT of any cached iterators that haven't been reffed
     with `gtk-tree-model-ref-node'. This might be useful if the child
     model being sorted is static (and doesn't change often) and there
     has been a lot of unreffed access to nodes. As a side effect of
     this function, all unreffed iters will be invalid.

    TREE-MODEL-SORT
          A `<gtk-tree-model-sort>'



 -- Function: gtk-tree-model-sort-iter-is-valid
          (self `<gtk-tree-model-sort>') (iter `<gtk-tree-iter>') => 
          (ret `bool')
 -- Method: iter-is-valid
     This function is slow. Only use it for debugging and/or testing
     purposes.

     Checks if the given iter is a valid iter for this
     `<gtk-tree-model-sort>'.

    TREE-MODEL-SORT
          A `<gtk-tree-model-sort>'.

    ITER
          A `<gtk-tree-iter>'.

    RET
          ``#t'' if the iter is valid, ``#f'' if the iter is invalid.


     Since 2.2



File: guile-gnome-gtk.info,  Node: GtkTreeModelFilter,  Next: GtkCellLayout,  Prev: GtkTreeModelSort,  Up: Top

41 GtkTreeModelFilter
*********************

A GtkTreeModel which hides parts of an underlying tree model

41.1 Overview
=============

A `<gtk-tree-model-filter>' is a tree model which wraps another tree
model, and can do the following things:

   Filter specific rows, based on data from a "visible column", a
column storing booleans indicating whether the row should be filtered
or not, or based on the return value of a "visible function", which
gets a model, iter and user_data and returns a boolean indicating
whether the row should be filtered or not.

   Modify the "appearance" of the model, using a modify function. This
is extremely powerful and allows for just changing some values and also
for creating a completely different model based on the given child
model.

   Set a different root node, also known as a "virtual root". You can
pass in a `<gtk-tree-path>' indicating the root node for the filter at
construction time.

41.2 Usage
==========

 -- Class: <gtk-tree-model-filter>
     Derives from `<gtk-tree-model>', `<gtk-tree-drag-source>',
     `<gobject>'.

     This class defines the following properties:

    `child-model'
          The model for the filtermodel to filter

    `virtual-root'
          The virtual root (relative to the child model) for this
          filtermodel



 -- Function: gtk-tree-model-filter-new (self `<gtk-tree-model>')
          (root `<gtk-tree-path>') =>  (ret `<gtk-tree-model>')
 -- Method: filter-new
     Creates a new `<gtk-tree-model>', with CHILD-MODEL as the
     child_model and ROOT as the virtual root.

    CHILD-MODEL
          A `<gtk-tree-model>'.

    ROOT
          A `<gtk-tree-path>' or ``#f''.

    RET
          A new `<gtk-tree-model>'.


     Since 2.4


 -- Function: gtk-tree-model-filter-get-model
          (self `<gtk-tree-model-filter>') =>  (ret `<gtk-tree-model>')
 -- Method: get-model
     Returns a pointer to the child model of FILTER.

    FILTER
          A `<gtk-tree-model-filter>'.

    RET
          A pointer to a `<gtk-tree-model>'.


     Since 2.4


 -- Function: gtk-tree-model-filter-refilter
          (self `<gtk-tree-model-filter>')
 -- Method: refilter
     Emits ::row_changed for each row in the child model, which causes
     the filter to re-evaluate whether a row is visible or not.

    FILTER
          A `<gtk-tree-model-filter>'.


     Since 2.4


 -- Function: gtk-tree-model-filter-clear-cache
          (self `<gtk-tree-model-filter>')
 -- Method: clear-cache
     This function should almost never be called. It clears the FILTER
     of any cached iterators that haven't been reffed with
     `gtk-tree-model-ref-node'.  This might be useful if the child
     model being filtered is static (and doesn't change often) and
     there has been a lot of unreffed access to nodes. As a side effect
     of this function, all unreffed iters will be invalid.

    FILTER
          A `<gtk-tree-model-filter>'.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkCellLayout,  Next: GtkCellRenderer,  Prev: GtkTreeModelFilter,  Up: Top

42 GtkCellLayout
****************

An interface for packing cells

42.1 Overview
=============

`<gtk-cell-layout>' is an interface to be implemented by all objects
which want to provide a `<gtk-tree-view-column-like>' API for packing
cells, setting attributes and data funcs.

   One of the notable features provided by implementations of
GtkCellLayout are _attributes_. Attributes let you set the properties
in flexible ways. They can just be set to constant values like regular
properties. But they can also be mapped to a column of the underlying
tree model with `gtk-cell-layout-set-attributes', which means that the
value of the attribute can change from cell to cell as they are
rendered by the cell renderer. Finally, it is possible to specify a
function with `gtk-cell-layout-set-cell-data-func' that is called to
determine the value of the attribute for each cell that is rendered.

42.2 Usage
==========

 -- Class: <gtk-cell-layout>
     Derives from `<ginterface>'.

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


 -- Function: gtk-cell-layout-pack-start (self `<gtk-cell-layout>')
          (cell `<gtk-cell-renderer>') (expand `bool')
 -- Method: pack-start
     Packs the CELL into the beginning of CELL-LAYOUT. If EXPAND is
     ``#f'', then the CELL is allocated no more space than it needs.
     Any unused space is divided evenly between cells for which EXPAND
     is ``#t''.

     Note that reusing the same cell renderer is not supported.

    CELL-LAYOUT
          A `<gtk-cell-layout>'.

    CELL
          A `<gtk-cell-renderer>'.

    EXPAND
          ``#t'' if CELL is to be given extra space allocated to
          CELL-LAYOUT.


     Since 2.4


 -- Function: gtk-cell-layout-pack-end (self `<gtk-cell-layout>')
          (cell `<gtk-cell-renderer>') (expand `bool')
 -- Method: pack-end
     Adds the CELL to the end of CELL-LAYOUT. If EXPAND is ``#f'', then
     the CELL is allocated no more space than it needs.  Any unused
     space is divided evenly between cells for which EXPAND is ``#t''.

     Note that reusing the same cell renderer is not supported.

    CELL-LAYOUT
          A `<gtk-cell-layout>'.

    CELL
          A `<gtk-cell-renderer>'.

    EXPAND
          ``#t'' if CELL is to be given extra space allocated to
          CELL-LAYOUT.


     Since 2.4


 -- Function: gtk-cell-layout-reorder (self `<gtk-cell-layout>')
          (cell `<gtk-cell-renderer>') (position `int')
 -- Method: reorder
     Re-inserts CELL at POSITION. Note that CELL has already to be
     packed into CELL-LAYOUT for this to function properly.

    CELL-LAYOUT
          A `<gtk-cell-layout>'.

    CELL
          A `<gtk-cell-renderer>' to reorder.

    POSITION
          New position to insert CELL at.


     Since 2.4


 -- Function: gtk-cell-layout-clear (self `<gtk-cell-layout>')
 -- Method: clear
     Unsets all the mappings on all renderers on CELL-LAYOUT and
     removes all renderers from CELL-LAYOUT.

    CELL-LAYOUT
          A `<gtk-cell-layout>'.


     Since 2.4


 -- Function: gtk-cell-layout-add-attribute (self `<gtk-cell-layout>')
          (cell `<gtk-cell-renderer>') (attribute `mchars')
          (column `int')
 -- Method: add-attribute
     Adds an attribute mapping to the list in CELL-LAYOUT. The COLUMN is
     the column of the model to get a value from, and the ATTRIBUTE is
     the parameter on CELL to be set from the value. So for example if
     column 2 of the model contains strings, you could have the "text"
     attribute of a `<gtk-cell-renderer-text>' get its values from
     column 2.

    CELL-LAYOUT
          A `<gtk-cell-layout>'.

    CELL
          A `<gtk-cell-renderer>'.

    ATTRIBUTE
          An attribute on the renderer.

    COLUMN
          The column position on the model to get the attribute from.


     Since 2.4


 -- Function: gtk-cell-layout-clear-attributes
          (self `<gtk-cell-layout>') (cell `<gtk-cell-renderer>')
 -- Method: clear-attributes
     Clears all existing attributes previously set with
     `gtk-cell-layout-set-attributes'.

    CELL-LAYOUT
          A `<gtk-cell-layout>'.

    CELL
          A `<gtk-cell-renderer>' to clear the attribute mapping on.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkCellRenderer,  Next: GtkCellEditable,  Prev: GtkCellLayout,  Up: Top

43 GtkCellRenderer
******************

An object for rendering a single cell on a

43.1 Overview
=============

The `<gtk-cell-renderer>' is a base class of a set of objects used for
rendering a cell to a `<gdk-drawable>'. These objects are used
primarily by the `<gtk-tree-view>' widget, though they aren't tied to
them in any specific way. It is worth noting that `<gtk-cell-renderer>'
is not a `<gtk-widget>' and cannot be treated as such.

   The primary use of a `<gtk-cell-renderer>' is for drawing a certain
graphical elements on a `<gdk-drawable>'. Typically, one cell renderer
is used to draw many cells on the screen. To this extent, it isn't
expected that a CellRenderer keep any permanent state around. Instead,
any state is set just prior to use using `<gobject>'s property system.
Then, the cell is measured using `gtk-cell-renderer-get-size'. Finally,
the cell is rendered in the correct location using
`gtk-cell-renderer-render'.

   There are a number of rules that must be followed when writing a new
`<gtk-cell-renderer>'. First and formost, it's important that a certain
set of properties will always yield a cell renderer of the same size,
barring a `<gtk-style>' change. The `<gtk-cell-renderer>' also has a
number of generic properties that are expected to be honored by all
children.

   Beyond merely rendering a cell, cell renderers can optionally
provide active user interface elements. A cell renderer can be
"activatable" like `<gtk-cell-renderer-toggle>', which toggles when it
gets activated by a mouse click, or it can be "editable" like
`<gtk-cell-renderer-text>', which allows the user to edit the text
using a `<gtk-entry>'. To make a cell renderer activatable or editable,
you have to implement the ACTIVATE or START-EDITING virtual functions,
respectively.

43.2 Usage
==========

 -- Class: <gtk-cell-renderer>
     Derives from `<gtk-object>'.

     This class defines the following properties:

    `mode'
          Editable mode of the CellRenderer

    `visible'
          Display the cell

    `sensitive'
          Display the cell sensitive

    `xalign'
          The x-align

    `yalign'
          The y-align

    `xpad'
          The xpad

    `ypad'
          The ypad

    `width'
          The fixed width

    `height'
          The fixed height

    `is-expander'
          Row has children

    `is-expanded'
          Row is an expander row, and is expanded

    `cell-background'
          Cell background color as a string

    `cell-background-gdk'
          Cell background color as a GdkColor

    `cell-background-set'
          Whether this tag affects the cell background color



 -- Signal on <gtk-cell-renderer>: editing-canceled
     This signal gets emitted when the user cancels the process of
     editing a cell.  For example, an editable cell renderer could be
     written to cancel editing when the user presses Escape.

     See also: `gtk-cell-renderer-editing-canceled'

     Since 2.4


 -- Signal on <gtk-cell-renderer>: editing-started
          (arg0 `<gtk-cell-editable>') (arg1 `<gchararray>')
     This signal gets emitted when a cell starts to be edited. The
     indended use of this signal is to do special setup on EDITABLE,
     e.g. adding a `<gtk-entry-completion>' or setting up additional
     columns in a `<gtk-combo-box>'.

     Note that GTK+ doesn't guarantee that cell renderers will continue
     to use the same kind of widget for editing in future releases,
     therefore you should check the type of EDITABLE before doing any
     specific setup, as in the following example:


          static void
          text_editing_started (GtkCellRenderer *cell,
                                GtkCellEditable *editable,
                                const gchar     *path,
                                gpointer         data)
          {
            if (GTK_IS_ENTRY (editable))
              {
                GtkEntry *entry = GTK_ENTRY (editable);

                /* ... create a GtkEntryCompletion */

                gtk_entry_set_completion (entry, completion);
              }
          }

     Since 2.6


 -- Function: gtk-cell-renderer-render (self `<gtk-cell-renderer>')
          (window `<gdk-window>') (widget `<gtk-widget>')
          (background_area `<gdk-rectangle>')
          (cell_area `<gdk-rectangle>') (expose_area `<gdk-rectangle>')
          (flags `<gtk-cell-renderer-state>')
 -- Method: render
     Invokes the virtual render function of the `<gtk-cell-renderer>'.
     The three passed-in rectangles are areas of WINDOW. Most renderers
     will draw within CELL-AREA; the xalign, yalign, xpad, and ypad
     fields of the `<gtk-cell-renderer>' should be honored with respect
     to CELL-AREA.  BACKGROUND-AREA includes the blank space around the
     cell, and also the area containing the tree expander; so the
     BACKGROUND-AREA rectangles for all cells tile to cover the entire
     WINDOW. EXPOSE-AREA is a clip rectangle.

    CELL
          a `<gtk-cell-renderer>'

    WINDOW
          a `<gdk-drawable>' to draw to

    WIDGET
          the widget owning WINDOW

    BACKGROUND-AREA
          entire cell area (including tree expanders and maybe padding
          on the sides)

    CELL-AREA
          area normally rendered by a cell renderer

    EXPOSE-AREA
          area that actually needs updating

    FLAGS
          flags that affect rendering



 -- Function: gtk-cell-renderer-activate (self `<gtk-cell-renderer>')
          (event `<gdk-event>') (widget `<gtk-widget>') (path `mchars')
          (background_area `<gdk-rectangle>')
          (cell_area `<gdk-rectangle>')
          (flags `<gtk-cell-renderer-state>') =>  (ret `bool')
 -- Method: activate
     Passes an activate event to the cell renderer for possible
     processing. Some cell renderers may use events; for example,
     `<gtk-cell-renderer-toggle>' toggles when it gets a mouse click.

    CELL
          a `<gtk-cell-renderer>'

    EVENT
          a `<gdk-event>'

    WIDGET
          widget that received the event

    PATH
          widget-dependent string representation of the event location;
          e.g. for `<gtk-tree-view>', a string representation of
          `<gtk-tree-path>'

    BACKGROUND-AREA
          background area as passed to GTK-CELL-RENDERER-RENDER

    CELL-AREA
          cell area as passed to GTK-CELL-RENDERER-RENDER

    FLAGS
          render flags

    RET
          ``#t'' if the event was consumed/handled



 -- Function: gtk-cell-renderer-start-editing
          (self `<gtk-cell-renderer>') (event `<gdk-event>')
          (widget `<gtk-widget>') (path `mchars')
          (background_area `<gdk-rectangle>')
          (cell_area `<gdk-rectangle>')
          (flags `<gtk-cell-renderer-state>') => 
          (ret `<gtk-cell-editable>')
 -- Method: start-editing
     Passes an activate event to the cell renderer for possible
     processing.

    CELL
          a `<gtk-cell-renderer>'

    EVENT
          a `<gdk-event>'

    WIDGET
          widget that received the event

    PATH
          widget-dependent string representation of the event location;
          e.g. for `<gtk-tree-view>', a string representation of
          `<gtk-tree-path>'

    BACKGROUND-AREA
          background area as passed to GTK-CELL-RENDERER-RENDER

    CELL-AREA
          cell area as passed to GTK-CELL-RENDERER-RENDER

    FLAGS
          render flags

    RET
          A new `<gtk-cell-editable>', or ``#f''



 -- Function: gtk-cell-renderer-editing-canceled
          (self `<gtk-cell-renderer>')
 -- Method: editing-canceled
     `gtk_cell_renderer_editing_canceled' has been deprecated since
     version 2.6 and should not be used in newly-written code. Use
     `gtk-cell-renderer-stop-editing' instead

     Causes the cell renderer to emit the "editing-canceled" signal.
     This function is for use only by implementations of cell renderers
     that need to notify the client program that an editing process was
     canceled and the changes were not committed.

    CELL
          A `<gtk-cell-renderer>'


     Since 2.4


 -- Function: gtk-cell-renderer-stop-editing
          (self `<gtk-cell-renderer>') (canceled `bool')
 -- Method: stop-editing
     Informs the cell renderer that the editing is stopped. If CANCELED
     is ``#t'', the cell renderer will emit the "editing-canceled"
     signal.  This function should be called by cell renderer
     implementations in response to the "editing-done" signal of
     `<gtk-cell-editable>'.

    CELL
          A `<gtk-cell-renderer>'

    CANCELED
          ``#t'' if the editing has been canceled


     Since 2.6


 -- Function: gtk-cell-renderer-get-fixed-size
          (self `<gtk-cell-renderer>') =>  (width `int') (height `int')
 -- Method: get-fixed-size
     Fills in WIDTH and HEIGHT with the appropriate size of CELL.

    CELL
          A `<gtk-cell-renderer>'

    WIDTH
          location to fill in with the fixed width of the widget, or
          ``#f''

    HEIGHT
          location to fill in with the fixed height of the widget, or
          ``#f''



 -- Function: gtk-cell-renderer-set-fixed-size
          (self `<gtk-cell-renderer>') (width `int') (height `int')
 -- Method: set-fixed-size
     Sets the renderer size to be explicit, independent of the
     properties set.

    CELL
          A `<gtk-cell-renderer>'

    WIDTH
          the width of the cell renderer, or -1

    HEIGHT
          the height of the cell renderer, or -1




File: guile-gnome-gtk.info,  Node: GtkCellEditable,  Next: GtkCellRendererAccel,  Prev: GtkCellRenderer,  Up: Top

44 GtkCellEditable
******************

Interface for widgets which can are used for editing cells

44.1 Overview
=============

The `<gtk-cell-editable>' interface must be implemented for widgets to
be usable when editing the contents of a `<gtk-tree-view>' cell.

44.2 Usage
==========

 -- Class: <gtk-cell-editable>
     Derives from `<ginterface>'.

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


 -- Signal on <gtk-cell-editable>: editing-done

 -- Signal on <gtk-cell-editable>: remove-widget

 -- Function: gtk-cell-editable-start-editing
          (self `<gtk-cell-editable>') (event `<gdk-event>')
 -- Method: start-editing
     Begins editing on a CELL-EDITABLE. EVENT is the `<gdk-event>' that
     began the editing process. It may be ``#f'', in the instance that
     editing was initiated through programatic means.

    CELL-EDITABLE
          A `<gtk-cell-editable>'

    EVENT
          A `<gdk-event>', or ``#f''



 -- Function: gtk-cell-editable-editing-done
          (self `<gtk-cell-editable>')
 -- Method: editing-done
     Emits the "editing_done" signal. This signal is a sign for the
     cell renderer to update its value from the cell.

    CELL-EDITABLE
          A `<gtk-tree-editable>'



 -- Function: gtk-cell-editable-remove-widget
          (self `<gtk-cell-editable>')
 -- Method: remove-widget
     Emits the "remove_widget" signal. This signal is meant to indicate
     that the cell is finished editing, and the widget may now be
     destroyed.

    CELL-EDITABLE
          A `<gtk-tree-editable>'




File: guile-gnome-gtk.info,  Node: GtkCellRendererAccel,  Next: GtkCellRendererCombo,  Prev: GtkCellEditable,  Up: Top

45 GtkCellRendererAccel
***********************

Renders a keyboard accelerator in a cell

45.1 Overview
=============

`<gtk-cell-renderer-accel>' displays a keyboard accelerator (i.e. a key
combination like <Control>-a). If the cell renderer is editable, the
accelerator can be changed by simply typing the new combination.

   The `<gtk-cell-renderer-accel>' cell renderer was added in GTK+ 2.10.

45.2 Usage
==========

 -- Class: <gtk-cell-renderer-accel>
     Derives from `<gtk-cell-renderer-text>'.

     This class defines the following properties:

    `accel-key'
          The keyval of the accelerator

    `accel-mods'
          The modifier mask of the accelerator

    `keycode'
          The hardware keycode of the accelerator

    `accel-mode'
          The type of accelerators



 -- Signal on <gtk-cell-renderer-accel>: accel-edited
          (arg0 `<gchararray>') (arg1 `<guint>')
          (arg2 `<gdk-modifier-type>') (arg3 `<guint>')
     Gets emitted when the user has selected a new accelerator.

     Since 2.10


 -- Signal on <gtk-cell-renderer-accel>: accel-cleared
          (arg0 `<gchararray>')
     Gets emitted when the user has removed the accelerator.

     Since 2.10


 -- Function: gtk-cell-renderer-accel-new => 
          (ret `<gtk-cell-renderer>')
     Creates a new `<gtk-cell-renderer-accel>'.

    RET
          the new cell renderer


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkCellRendererCombo,  Next: GtkCellRendererPixbuf,  Prev: GtkCellRendererAccel,  Up: Top

46 GtkCellRendererCombo
***********************

Renders a combobox in a cell

46.1 Overview
=============

`<gtk-cell-renderer-combo>' renders text in a cell like
`<gtk-cell-renderer-text>' from which it is derived. But while
`<gtk-cell-renderer-text>' offers a simple entry to edit the text,
`<gtk-cell-renderer-combo>' offers a `<gtk-combo-box>' or
`<gtk-combo-box-entry>' widget to edit the text. The values to display
in the combo box are taken from the tree model specified in the model
property.

   The combo cell renderer takes care of adding a text cell renderer to
the combo box and sets it to display the column specified by its
text-column property.  Further properties of the comnbo box can be set
in a handler for the editing-started signal.

   The `<gtk-cell-renderer-combo>' cell renderer was added in GTK+ 2.6.

46.2 Usage
==========

 -- Class: <gtk-cell-renderer-combo>
     Derives from `<gtk-cell-renderer-text>'.

     This class defines the following properties:

    `model'
          The model containing the possible values for the combo box

    `text-column'
          A column in the data source model to get the strings from

    `has-entry'
          If FALSE, don't allow to enter strings other than the chosen
          ones



 -- Function: gtk-cell-renderer-combo-new => 
          (ret `<gtk-cell-renderer>')
     Creates a new `<gtk-cell-renderer-combo>'. Adjust how text is
     drawn using object properties. Object properties can be set
     globally (with `g-object-set'). Also, with
     `<gtk-tree-view-column>', you can bind a property to a value in a
     `<gtk-tree-model>'. For example, you can bind the "text" property
     on the cell renderer to a string value in the model, thus
     rendering a different string in each row of the `<gtk-tree-view>'.

    RET
          the new cell renderer


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkCellRendererPixbuf,  Next: GtkCellRendererProgress,  Prev: GtkCellRendererCombo,  Up: Top

47 GtkCellRendererPixbuf
************************

Renders a pixbuf in a cell

47.1 Overview
=============

A `<gtk-cell-renderer-pixbuf>' can be used to render an image in a
cell. It allows to render either a given `<gdk-pixbuf>' (set via the
pixbuf property) or a stock icon (set via the stock-id property).

   To support the tree view, `<gtk-cell-renderer-pixbuf>' also supports
rendering two alternative pixbufs, when the is-expander property is
``#t''. If the is-expanded property is ``#t'' and the
pixbuf-expander-open property is set to a pixbuf, it renders that
pixbuf, if the is-expanded property is ``#f'' and the
pixbuf-expander-closed property is set to a pixbuf, it renders that one.

47.2 Usage
==========

 -- Class: <gtk-cell-renderer-pixbuf>
     Derives from `<gtk-cell-renderer>'.

     This class defines the following properties:

    `pixbuf'
          The pixbuf to render

    `pixbuf-expander-open'
          Pixbuf for open expander

    `pixbuf-expander-closed'
          Pixbuf for closed expander

    `stock-id'
          The stock ID of the stock icon to render

    `stock-size'
          The GtkIconSize value that specifies the size of the rendered
          icon

    `stock-detail'
          Render detail to pass to the theme engine

    `follow-state'
          Whether the rendered pixbuf should be colorized according to
          the state

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



 -- Function: gtk-cell-renderer-pixbuf-new => 
          (ret `<gtk-cell-renderer>')
     Creates a new `<gtk-cell-renderer-pixbuf>'. Adjust rendering
     parameters using object properties. Object properties can be set
     globally (with `g-object-set'). Also, with
     `<gtk-tree-view-column>', you can bind a property to a value in a
     `<gtk-tree-model>'. For example, you can bind the "pixbuf"
     property on the cell renderer to a pixbuf value in the model, thus
     rendering a different image in each row of the `<gtk-tree-view>'.

    RET
          the new cell renderer




File: guile-gnome-gtk.info,  Node: GtkCellRendererProgress,  Next: GtkCellRendererSpin,  Prev: GtkCellRendererPixbuf,  Up: Top

48 GtkCellRendererProgress
**************************

Renders numbers as progress bars

48.1 Overview
=============

`<gtk-cell-renderer-progress>' renders a numeric value as a progress
par in a cell. Additionally, it can display a text on top of the
progress bar.

   The `<gtk-cell-renderer-progress>' cell renderer was added in GTK+
2.6.

48.2 Usage
==========

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

     This class defines the following properties:

    `value'
          Value of the progress bar

    `text'
          Text on the progress bar

    `pulse'
          Set this to positive values to indicate that some progress is
          made, but you don't know how much.

    `text-xalign'
          The horizontal text alignment, from 0 (left) to 1 (right).
          Reversed for RTL layouts.

    `text-yalign'
          The vertical text alignment, from 0 (top) to 1 (bottom).

    `orientation'
          Orientation and growth direction of the progress bar



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

    RET
          the new cell renderer


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkCellRendererSpin,  Next: GtkCellRendererText,  Prev: GtkCellRendererProgress,  Up: Top

49 GtkCellRendererSpin
**********************

Renders a spin button in a cell

49.1 Overview
=============

`<gtk-cell-renderer-spin>' renders text in a cell like
`<gtk-cell-renderer-text>' from which it is derived. But while
`<gtk-cell-renderer-text>' offers a simple entry to edit the text,
`<gtk-cell-renderer-spin>' offers a `<gtk-spin-button>' widget. Of
course, that means that the text has to be parseable as a floating
point number.

   The range of the spinbutton is taken from the adjustment property of
the cell renderer, which can be set explicitly or mapped to a column in
the tree model, like all properties of cell renders.
`<gtk-cell-renderer-spin>' also has properties for the climb rate and
the number of digits to display. Other `<gtk-spin-button>' properties
can be set in a handler for the start-editing signal.

   The `<gtk-cell-renderer-spin>' cell renderer was added in GTK+ 2.10.

49.2 Usage
==========

 -- Class: <gtk-cell-renderer-spin>
     Derives from `<gtk-cell-renderer-text>'.

     This class defines the following properties:

    `adjustment'
          The adjustment that holds the value of the spinbutton.

    `climb-rate'
          The acceleration rate when you hold down a button

    `digits'
          The number of decimal places to display



 -- Function: gtk-cell-renderer-spin-new =>  (ret `<gtk-cell-renderer>')
     Creates a new `<gtk-cell-renderer-spin>'.

    RET
          a new `<gtk-cell-renderer-spin>'


     Since 2.10



File: guile-gnome-gtk.info,  Node: GtkCellRendererText,  Next: GtkCellRendererToggle,  Prev: GtkCellRendererSpin,  Up: Top

50 GtkCellRendererText
**********************

Renders text in a cell

50.1 Overview
=============

A `<gtk-cell-renderer-text>' renders a given text in its cell, using the
font, color and style information provided by its properties. The text
will be ellipsized if it is too long and the ellipsize property allows
it.

   If the mode is `GTK_CELL_RENDERER_MODE_EDITABLE', the
`<gtk-cell-renderer-text>' allows to edit its text using an entry.

50.2 Usage
==========

 -- Class: <gtk-cell-renderer-text>
     Derives from `<gtk-cell-renderer>'.

     This class defines the following properties:

    `text'
          Text to render

    `markup'
          Marked up text to render

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

    `single-paragraph-mode'
          Whether or not to keep all text in a single paragraph

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

    `wrap-width'
          The width at which the text is wrapped

    `alignment'
          How to align the lines

    `background'
          Background color as a string

    `foreground'
          Foreground color as a string

    `background-gdk'
          Background color as a GdkColor

    `foreground-gdk'
          Foreground color as a GdkColor

    `font'
          Font description as a string, e.g. "Sans Italic 12"

    `font-desc'
          Font description as a PangoFontDescription struct

    `family'
          Name of the font family, e.g. Sans, Helvetica, Times,
          Monospace

    `style'
          Font style

    `variant'
          Font variant

    `weight'
          Font weight

    `stretch'
          Font stretch

    `size'
          Font size

    `size-points'
          Font size in points

    `scale'
          Font scaling factor

    `editable'
          Whether the text can be modified by the user

    `strikethrough'
          Whether to strike through the text

    `underline'
          Style of underline for this text

    `rise'
          Offset of text above the baseline (below the baseline if rise
          is negative)

    `language'
          The language this text is in, as an ISO code. Pango can use
          this as a hint when rendering the text. If you don't
          understand this parameter, you probably don't need it

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

    `wrap-mode'
          How to break the string into multiple lines, if the cell
          renderer does not have enough room to display the entire
          string

    `background-set'
          Whether this tag affects the background color

    `foreground-set'
          Whether this tag affects the foreground color

    `family-set'
          Whether this tag affects the font family

    `style-set'
          Whether this tag affects the font style

    `variant-set'
          Whether this tag affects the font variant

    `weight-set'
          Whether this tag affects the font weight

    `stretch-set'
          Whether this tag affects the font stretch

    `size-set'
          Whether this tag affects the font size

    `scale-set'
          Whether this tag scales the font size by a factor

    `editable-set'
          Whether this tag affects text editability

    `strikethrough-set'
          Whether this tag affects strikethrough

    `underline-set'
          Whether this tag affects underlining

    `rise-set'
          Whether this tag affects the rise

    `language-set'
          Whether this tag affects the language the text is rendered as

    `ellipsize-set'
          Whether this tag affects the ellipsize mode

    `align-set'
          Whether this tag affects the alignment mode



 -- Signal on <gtk-cell-renderer-text>: edited (arg0 `<gchararray>')
          (arg1 `<gchararray>')
     This signal is emitted after RENDERER has been edited.


 -- Function: gtk-cell-renderer-text-new =>  (ret `<gtk-cell-renderer>')
     Creates a new `<gtk-cell-renderer-text>'. Adjust how text is drawn
     using object properties. Object properties can be set globally
     (with `g-object-set'). Also, with `<gtk-tree-view-column>', you
     can bind a property to a value in a `<gtk-tree-model>'. For
     example, you can bind the "text" property on the cell renderer to
     a string value in the model, thus rendering a different string in
     each row of the `<gtk-tree-view>'

    RET
          the new cell renderer




File: guile-gnome-gtk.info,  Node: GtkCellRendererToggle,  Next: GtkListStore,  Prev: GtkCellRendererText,  Up: Top

51 GtkCellRendererToggle
************************

Renders a toggle button in a cell

51.1 Overview
=============

`<gtk-cell-renderer-toggle>' renders a toggle button in a cell. The
button is drawn as a radio- or checkbutton, depending on the radio
property. When activated, it emits the toggled signal.

51.2 Usage
==========

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

     This class defines the following properties:

    `activatable'
          The toggle button can be activated

    `active'
          The toggle state of the button

    `radio'
          Draw the toggle button as a radio button

    `inconsistent'
          The inconsistent state of the button

    `indicator-size'
          Size of check or radio indicator



 -- Signal on <gtk-cell-renderer-toggle>: toggled (arg0 `<gchararray>')
     The ::toggled signal is emitted when the cell is toggled.


 -- Function: gtk-cell-renderer-toggle-new => 
          (ret `<gtk-cell-renderer>')
     Creates a new `<gtk-cell-renderer-toggle>'. Adjust rendering
     parameters using object properties. Object properties can be set
     globally (with `g-object-set'). Also, with
     `<gtk-tree-view-column>', you can bind a property to a value in a
     `<gtk-tree-model>'. For example, you can bind the "active"
     property on the cell renderer to a boolean value in the model, thus
     causing the check button to reflect the state of the model.

    RET
          the new cell renderer



 -- Function: gtk-cell-renderer-toggle-get-radio
          (self `<gtk-cell-renderer-toggle>') =>  (ret `bool')
 -- Method: get-radio
     Returns whether we're rendering radio toggles rather than
     checkboxes.

    TOGGLE
          a `<gtk-cell-renderer-toggle>'

    RET
          ``#t'' if we're rendering radio toggles rather than checkboxes



 -- Function: gtk-cell-renderer-toggle-set-radio
          (self `<gtk-cell-renderer-toggle>') (radio `bool')
 -- Method: set-radio
     If RADIO is ``#t'', the cell renderer renders a radio toggle (i.e.
     a toggle in a group of mutually-exclusive toggles). If ``#f'', it
     renders a check toggle (a standalone boolean option). This can be
     set globally for the cell renderer, or changed just before
     rendering each cell in the model (for `<gtk-tree-view>', you set
     up a per-row setting using `<gtk-tree-view-column>' to associate
     model columns with cell renderer properties).

    TOGGLE
          a `<gtk-cell-renderer-toggle>'

    RADIO
          ``#t'' to make the toggle look like a radio button



 -- Function: gtk-cell-renderer-toggle-get-active
          (self `<gtk-cell-renderer-toggle>') =>  (ret `bool')
 -- Method: get-active
     Returns whether the cell renderer is active. See
     `gtk-cell-renderer-toggle-set-active'.

    TOGGLE
          a `<gtk-cell-renderer-toggle>'

    RET
          ``#t'' if the cell renderer is active.



 -- Function: gtk-cell-renderer-toggle-set-active
          (self `<gtk-cell-renderer-toggle>') (setting `bool')
 -- Method: set-active
     Activates or deactivates a cell renderer.

    TOGGLE
          a `<gtk-cell-renderer-toggle>'.

    SETTING
          the value to set.




File: guile-gnome-gtk.info,  Node: GtkListStore,  Next: GtkTreeStore,  Prev: GtkCellRendererToggle,  Up: Top

52 GtkListStore
***************

A list-like data structure that can be used with the

52.1 Overview
=============

The `<gtk-list-store>' object is a list model for use with a
`<gtk-tree-view>' widget. It implements the `<gtk-tree-model>'
interface, and consequentialy, can use all of the methods available
there. It also implements the `<gtk-tree-sortable>' interface so it can
be sorted by the view. Finally, it also implements the tree drag and
drop interfaces.

   The `<gtk-list-store>' can accept most GObject types as a column
type, though it can't accept all custom types. Internally, it will keep
a copy of data passed in (such as a string or a boxed pointer). Columns
that accept `<gobject>'s are handled a little differently. The
`<gtk-list-store>' will keep a reference to the object instead of
copying the value. As a result, if the object is modified, it is up to
the application writer to call GTK-TREE-MODEL-ROW-CHANGED to emit the
"row_changed" signal. This most commonly affects lists with
`<gdk-pixbuf>'s stored.


     enum {
       COLUMN_STRING,
       COLUMN_INT,
       COLUMN_BOOLEAN,
       N_COLUMNS
     };

     {
       GtkListStore *list_store;
       GtkTreePath *path;
       GtkTreeIter iter;
       gint i;

       list_store = gtk_list_store_new (N_COLUMNS,
                                        G_TYPE_STRING,
                                        G_TYPE_INT,
                                        G_TYPE_BOOLEAN);

       for (i = 0; i < 10; i++)
         {
           gchar *some_data;

           some_data = get_some_data (i);

           /* Add a new row to the model */
           gtk_list_store_append (list_store, &iter);
           gtk_list_store_set (list_store, &iter,
                               COLUMN_STRING, some_data,
                               COLUMN_INT, i,
                               COLUMN_BOOLEAN,  FALSE,
                               -1);

           /* As the store will keep a copy of the string internally, we
            * free some_data.
            */
           g_free (some_data);
         }

       /* Modify a particular row */
       path = gtk_tree_path_new_from_string ("4");
       gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
                                &iter,
                                path);
       gtk_tree_path_free (path);
       gtk_list_store_set (list_store, &iter,
                           COLUMN_BOOLEAN, TRUE,
                           -1);
     }

52.2 Performance Considerations
===============================

Internally, the `<gtk-list-store>' was implemented with a linked list
with a tail pointer prior to GTK+ 2.6. As a result, it was fast at data
insertion and deletion, and not fast at random data access. The
`<gtk-list-store>' sets the `<gtk-tree-model-iters-persist>' flag,
which means that `<gtk-tree-iter>'s can be cached while the row exists.
Thus, if access to a particular row is needed often and your code is
expected to run on older versions of GTK+, it is worth keeping the iter
around.

   It is important to note that only the methods
GTK-LIST-STORE-INSERT-WITH-VALUES and
GTK-LIST-STORE-INSERT-WITH-VALUESV are atomic, in the sense that the row
is being appended to the store and the values filled in in a single
operation with regard to `<gtk-tree-model>' signaling. In contrast,
using e.g.  GTK-LIST-STORE-APPEND and then GTK-LIST-STORE-SET will
first create a row, which triggers the "row_inserted"
`<gtk-tree-model>' signal on `<gtk-list-store>'. The row, however, is
still empty, and any signal handler connecting to "row_inserted" on
this particular store should be prepared for the situation that the row
might be empty. This is especially important if you are wrapping the
`<gtk-list-store>' inside a `<gtk-tree-model-filter>' and are using a
`<gtk-tree-model-filter-visible-func>'. Using any of the non-atomic
operations to append rows to the `<gtk-list-store>' will cause the
`<gtk-tree-model-filter-visible-func>' to be visited with an empty row
first; the function must be prepared for that.

52.3 Usage
==========

 -- Class: <gtk-list-store>
     Derives from `<gtk-buildable>', `<gtk-tree-model>',
     `<gtk-tree-drag-source>', `<gtk-tree-drag-dest>',
     `<gtk-tree-sortable>', `<gobject>'.

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


 -- Function: gtk-list-store-new (types `scm') => 
          (ret `<gtk-list-store>')
     Creates a new list store as with N-COLUMNS columns each of the
     types passed in. Note that only types derived from standard
     GObject fundamental types are supported.

     As an example, `gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
     GDK_TYPE_PIXBUF);' will create a new `<gtk-list-store>' with three
     columns, of type int, string and `<gdk-pixbuf>' respectively.

    N-COLUMNS
          number of columns in the list store

    ...
          all `<g-type>' types for the columns, from first to last

    RET
          a new `<gtk-list-store>'



 -- Function: gtk-list-store-set-value (self `<gtk-list-store>')
          (iter `<gtk-tree-iter>') (column `int') (value `scm')
 -- Method: set-value
     Sets the data in the cell specified by ITER and COLUMN. The type of
     VALUE must be convertible to the type of the column.

    LIST-STORE
          A `<gtk-list-store>'

    ITER
          A valid `<gtk-tree-iter>' for the row being modified

    COLUMN
          column number to modify

    VALUE
          new value for the cell



 -- Function: gtk-list-store-remove (self `<gtk-list-store>')
          (iter `<gtk-tree-iter>') =>  (ret `<gtk-tree-iter>')
 -- Method: remove
     Removes the given row from the list store. After being removed,
     ITER is set to be the next valid row, or invalidated if it pointed
     to the last row in LIST-STORE.

    LIST-STORE
          A `<gtk-list-store>'

    ITER
          A valid `<gtk-tree-iter>'

    RET
          ``#t'' if ITER is valid, ``#f'' if not.



 -- Function: gtk-list-store-insert (self `<gtk-list-store>')
          (position `int') =>  (ret `<gtk-tree-iter>')
 -- Method: insert
     Creates a new row at POSITION. ITER will be changed to point to
     this new row. If POSITION is larger than the number of rows on the
     list, then the new row will be appended to the list. The row will
     be empty after this function is called. To fill in values, you
     need to call `gtk-list-store-set' or `gtk-list-store-set-value'.

    LIST-STORE
          A `<gtk-list-store>'

    ITER
          An unset `<gtk-tree-iter>' to set to the new row

    POSITION
          position to insert the new row



 -- Function: gtk-list-store-insert-before (self `<gtk-list-store>')
          (sibling `<gtk-tree-iter>') =>  (ret `<gtk-tree-iter>')
 -- Method: insert-before
     Inserts a new row before SIBLING. If SIBLING is ``#f'', then the
     row will be appended to the end of the list. ITER will be changed
     to point to this new row. The row will be empty after this
     function is called.  To fill in values, you need to call
     `gtk-list-store-set' or `gtk-list-store-set-value'.

    LIST-STORE
          A `<gtk-list-store>'

    ITER
          An unset `<gtk-tree-iter>' to set to the new row

    SIBLING
          A valid `<gtk-tree-iter>', or ``#f''



 -- Function: gtk-list-store-insert-after (self `<gtk-list-store>')
          (sibling `<gtk-tree-iter>') =>  (ret `<gtk-tree-iter>')
 -- Method: insert-after
     Inserts a new row after SIBLING. If SIBLING is ``#f'', then the
     row will be prepended to the beginning of the list. ITER will be
     changed to point to this new row. The row will be empty after this
     function is called. To fill in values, you need to call
     `gtk-list-store-set' or `gtk-list-store-set-value'.

    LIST-STORE
          A `<gtk-list-store>'

    ITER
          An unset `<gtk-tree-iter>' to set to the new row

    SIBLING
          A valid `<gtk-tree-iter>', or ``#f''



 -- Function: gtk-list-store-prepend (self `<gtk-list-store>') => 
          (ret `<gtk-tree-iter>')
 -- Method: prepend
     Prepends a new row to LIST-STORE. ITER will be changed to point to
     this new row. The row will be empty after this function is called.
     To fill in values, you need to call `gtk-list-store-set' or
     `gtk-list-store-set-value'.

    LIST-STORE
          A `<gtk-list-store>'

    ITER
          An unset `<gtk-tree-iter>' to set to the prepend row



 -- Function: gtk-list-store-append (self `<gtk-list-store>') => 
          (ret `<gtk-tree-iter>')
 -- Method: append
     Appends a new row to LIST-STORE. ITER will be changed to point to
     this new row. The row will be empty after this function is called.
     To fill in values, you need to call `gtk-list-store-set' or
     `gtk-list-store-set-value'.

    LIST-STORE
          A `<gtk-list-store>'

    ITER
          An unset `<gtk-tree-iter>' to set to the appended row



 -- Function: gtk-list-store-clear (self `<gtk-list-store>')
 -- Method: clear
     Removes all rows from the list store.

    LIST-STORE
          a `<gtk-list-store>'.



 -- Function: gtk-list-store-iter-is-valid (self `<gtk-list-store>')
          (iter `<gtk-tree-iter>') =>  (ret `bool')
 -- Method: iter-is-valid
     purposes.")

     Checks if the given iter is a valid iter for this
     `<gtk-list-store>'.

    LIST-STORE
          A `<gtk-list-store>'.

    ITER
          A `<gtk-tree-iter>'.

    RET
          ``#t'' if the iter is valid, ``#f'' if the iter is invalid.


     Since 2.2


 -- Function: gtk-list-store-reorder (self `<gtk-list-store>') => 
          (new_order `int')
 -- Method: reorder
     Reorders STORE to follow the order indicated by NEW-ORDER. Note
     that this function only works with unsorted stores.

    STORE
          A `<gtk-list-store>'.

    NEW-ORDER
          an array of integers mapping the new position of each child
          to its old position before the re-ordering, i.e.
          NEW-ORDER`[newpos] = oldpos'.


     Since 2.2


 -- Function: gtk-list-store-swap (self `<gtk-list-store>')
          (a `<gtk-tree-iter>') (b `<gtk-tree-iter>')
 -- Method: swap
     Swaps A and B in STORE. Note that this function only works with
     unsorted stores.

    STORE
          A `<gtk-list-store>'.

    A
          A `<gtk-tree-iter>'.

    B
          Another `<gtk-tree-iter>'.


     Since 2.2


 -- Function: gtk-list-store-move-before (self `<gtk-list-store>')
          (iter `<gtk-tree-iter>') (position `<gtk-tree-iter>')
 -- Method: move-before
     Moves ITER in STORE to the position before POSITION. Note that
     this function only works with unsorted stores. If POSITION is
     ``#f'', ITER will be moved to the end of the list.

    STORE
          A `<gtk-list-store>'.

    ITER
          A `<gtk-tree-iter>'.

    POSITION
          A `<gtk-tree-iter>', or ``#f''.


     Since 2.2


 -- Function: gtk-list-store-move-after (self `<gtk-list-store>')
          (iter `<gtk-tree-iter>') (position `<gtk-tree-iter>')
 -- Method: move-after
     Moves ITER in STORE to the position after POSITION. Note that this
     function only works with unsorted stores. If POSITION is ``#f'',
     ITER will be moved to the start of the list.

    STORE
          A `<gtk-list-store>'.

    ITER
          A `<gtk-tree-iter>'.

    POSITION
          A `<gtk-tree-iter>' or ``#f''.


     Since 2.2



File: guile-gnome-gtk.info,  Node: GtkTreeStore,  Next: GtkComboBox,  Prev: GtkListStore,  Up: Top

53 GtkTreeStore
***************

A tree-like data structure that can be used with the

53.1 Overview
=============

The `<gtk-tree-store>' object is a list model for use with a
`<gtk-tree-view>' widget. It implements the `<gtk-tree-model>'
interface, and consequentialy, can use all of the methods available
there. It also implements the `<gtk-tree-sortable>' interface so it can
be sorted by the view. Finally, it also implements the tree drag and
drop interfaces.

53.2 Usage
==========

 -- Class: <gtk-tree-store>
     Derives from `<gtk-buildable>', `<gtk-tree-model>',
     `<gtk-tree-drag-source>', `<gtk-tree-drag-dest>',
     `<gtk-tree-sortable>', `<gobject>'.

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


 -- Function: gtk-tree-store-new (types `scm') => 
          (ret `<gtk-tree-store>')
     Creates a new tree store as with N-COLUMNS columns each of the
     types passed in. Note that only types derived from standard
     GObject fundamental types are supported.

     As an example, `gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
     GDK_TYPE_PIXBUF);' will create a new `<gtk-tree-store>' with three
     columns, of type `<int>', `<string>' and `<gdk-pixbuf>'
     respectively.

    N-COLUMNS
          number of columns in the tree store

    ...
          all `<g-type>' types for the columns, from first to last

    RET
          a new `<gtk-tree-store>'



 -- Function: gtk-tree-store-set-value (self `<gtk-tree-store>')
          (iter `<gtk-tree-iter>') (column `int') (value `scm')
 -- Method: set-value
     Sets the data in the cell specified by ITER and COLUMN. The type of
     VALUE must be convertible to the type of the column.

    TREE-STORE
          a `<gtk-tree-store>'

    ITER
          A valid `<gtk-tree-iter>' for the row being modified

    COLUMN
          column number to modify

    VALUE
          new value for the cell



 -- Function: gtk-tree-store-remove (self `<gtk-tree-store>')
          (iter `<gtk-tree-iter>') =>  (ret `<gtk-tree-iter>')
 -- Method: remove
     Removes ITER from TREE-STORE. After being removed, ITER is set to
     the next valid row at that level, or invalidated if it previously
     pointed to the last one.

    TREE-STORE
          A `<gtk-tree-store>'

    ITER
          A valid `<gtk-tree-iter>'

    RET
          ``#t'' if ITER is still valid, ``#f'' if not.



 -- Function: gtk-tree-store-insert (self `<gtk-tree-store>')
          (parent `<gtk-tree-iter>') (position `int') => 
          (ret `<gtk-tree-iter>')
 -- Method: insert
     Creates a new row at POSITION. If parent is non-``#f'', then the
     row will be made a child of PARENT. Otherwise, the row will be
     created at the toplevel. If POSITION is larger than the number of
     rows at that level, then the new row will be inserted to the end
     of the list. ITER will be changed to point to this new row. The
     row will be empty after this function is called. To fill in
     values, you need to call `gtk-tree-store-set' or
     `gtk-tree-store-set-value'.

    TREE-STORE
          A `<gtk-tree-store>'

    ITER
          An unset `<gtk-tree-iter>' to set to the new row

    PARENT
          A valid `<gtk-tree-iter>', or ``#f''

    POSITION
          position to insert the new row



 -- Function: gtk-tree-store-insert-before (self `<gtk-tree-store>')
          (parent `<gtk-tree-iter>') (sibling `<gtk-tree-iter>') => 
          (ret `<gtk-tree-iter>')
 -- Method: insert-before
     Inserts a new row before SIBLING. If SIBLING is ``#f'', then the
     row will be appended to PARENT 's children. If PARENT and SIBLING
     are ``#f'', then the row will be appended to the toplevel. If both
     SIBLING and PARENT are set, then PARENT must be the parent of
     SIBLING. When SIBLING is set, PARENT is optional.

     ITER will be changed to point to this new row. The row will be
     empty after this function is called. To fill in values, you need
     to call `gtk-tree-store-set' or `gtk-tree-store-set-value'.

    TREE-STORE
          A `<gtk-tree-store>'

    ITER
          An unset `<gtk-tree-iter>' to set to the new row

    PARENT
          A valid `<gtk-tree-iter>', or ``#f''

    SIBLING
          A valid `<gtk-tree-iter>', or ``#f''



 -- Function: gtk-tree-store-insert-after (self `<gtk-tree-store>')
          (parent `<gtk-tree-iter>') (sibling `<gtk-tree-iter>') => 
          (ret `<gtk-tree-iter>')
 -- Method: insert-after
     Inserts a new row after SIBLING. If SIBLING is ``#f'', then the
     row will be prepended to PARENT 's children. If PARENT and SIBLING
     are ``#f'', then the row will be prepended to the toplevel. If
     both SIBLING and PARENT are set, then PARENT must be the parent of
     SIBLING. When SIBLING is set, PARENT is optional.

     ITER will be changed to point to this new row. The row will be
     empty after this function is called. To fill in values, you need
     to call `gtk-tree-store-set' or `gtk-tree-store-set-value'.

    TREE-STORE
          A `<gtk-tree-store>'

    ITER
          An unset `<gtk-tree-iter>' to set to the new row

    PARENT
          A valid `<gtk-tree-iter>', or ``#f''

    SIBLING
          A valid `<gtk-tree-iter>', or ``#f''



 -- Function: gtk-tree-store-prepend (self `<gtk-tree-store>')
          (parent `<gtk-tree-iter>') =>  (ret `<gtk-tree-iter>')
 -- Method: prepend
     Prepends a new row to TREE-STORE. If PARENT is non-``#f'', then it
     will prepend the new row before the first child of PARENT,
     otherwise it will prepend a row to the top level. ITER will be
     changed to point to this new row. The row will be empty after this
     function is called. To fill in values, you need to call
     `gtk-tree-store-set' or `gtk-tree-store-set-value'.

    TREE-STORE
          A `<gtk-tree-store>'

    ITER
          An unset `<gtk-tree-iter>' to set to the prepended row

    PARENT
          A valid `<gtk-tree-iter>', or ``#f''



 -- Function: gtk-tree-store-append (self `<gtk-tree-store>')
          (parent `<gtk-tree-iter>') =>  (ret `<gtk-tree-iter>')
 -- Method: append
     Appends a new row to TREE-STORE. If PARENT is non-``#f'', then it
     will append the new row after the last child of PARENT, otherwise
     it will append a row to the top level. ITER will be changed to
     point to this new row. The row will be empty after this function
     is called. To fill in values, you need to call
     `gtk-tree-store-set' or `gtk-tree-store-set-value'.

    TREE-STORE
          A `<gtk-tree-store>'

    ITER
          An unset `<gtk-tree-iter>' to set to the appended row

    PARENT
          A valid `<gtk-tree-iter>', or ``#f''



 -- Function: gtk-tree-store-is-ancestor (self `<gtk-tree-store>')
          (iter `<gtk-tree-iter>') (descendant `<gtk-tree-iter>') => 
          (ret `bool')
 -- Method: is-ancestor
     Returns ``#t'' if ITER is an ancestor of DESCENDANT. That is, ITER
     is the parent (or grandparent or great-grandparent) of DESCENDANT.

    TREE-STORE
          A `<gtk-tree-store>'

    ITER
          A valid `<gtk-tree-iter>'

    DESCENDANT
          A valid `<gtk-tree-iter>'

    RET
          ``#t'', if ITER is an ancestor of DESCENDANT



 -- Function: gtk-tree-store-iter-depth (self `<gtk-tree-store>')
          (iter `<gtk-tree-iter>') =>  (ret `int')
 -- Method: iter-depth
     Returns the depth of ITER. This will be 0 for anything on the root
     level, 1 for anything down a level, etc.

    TREE-STORE
          A `<gtk-tree-store>'

    ITER
          A valid `<gtk-tree-iter>'

    RET
          The depth of ITER



 -- Function: gtk-tree-store-clear (self `<gtk-tree-store>')
 -- Method: clear
     Removes all rows from TREE-STORE

    TREE-STORE
          a `<gtk-tree-store>'



 -- Function: gtk-tree-store-iter-is-valid (self `<gtk-tree-store>')
          (iter `<gtk-tree-iter>') =>  (ret `bool')
 -- Method: iter-is-valid
     WARNING: This function is slow. Only use it for debugging and/or
     testing purposes.

     Checks if the given iter is a valid iter for this
     `<gtk-tree-store>'.

    TREE-STORE
          A `<gtk-tree-store>'.

    ITER
          A `<gtk-tree-iter>'.

    RET
          ``#t'' if the iter is valid, ``#f'' if the iter is invalid.


     Since 2.2


 -- Function: gtk-tree-store-reorder (self `<gtk-tree-store>')
          (parent `<gtk-tree-iter>') =>  (new_order `int')
 -- Method: reorder
     Reorders the children of PARENT in TREE-STORE to follow the order
     indicated by NEW-ORDER. Note that this function only works with
     unsorted stores.

    TREE-STORE
          A `<gtk-tree-store>'.

    PARENT
          A `<gtk-tree-iter>'.

    NEW-ORDER
          an array of integers mapping the new position of each child
          to its old position before the re-ordering, i.e.
          NEW-ORDER`[newpos] = oldpos'.


     Since 2.2


 -- Function: gtk-tree-store-swap (self `<gtk-tree-store>')
          (a `<gtk-tree-iter>') (b `<gtk-tree-iter>')
 -- Method: swap
     Swaps A and B in the same level of TREE-STORE. Note that this
     function only works with unsorted stores.

    TREE-STORE
          A `<gtk-tree-store>'.

    A
          A `<gtk-tree-iter>'.

    B
          Another `<gtk-tree-iter>'.


     Since 2.2


 -- Function: gtk-tree-store-move-before (self `<gtk-tree-store>')
          (iter `<gtk-tree-iter>') (position `<gtk-tree-iter>')
 -- Method: move-before
     Moves ITER in TREE-STORE to the position before POSITION.  ITER
     and POSITION should be in the same level. Note that this function
     only works with unsorted stores. If POSITION is ``#f'', ITER will
     be moved to the end of the level.

    TREE-STORE
          A `<gtk-tree-store>'.

    ITER
          A `<gtk-tree-iter>'.

    POSITION
          A `<gtk-tree-iter>' or ``#f''.


     Since 2.2


 -- Function: gtk-tree-store-move-after (self `<gtk-tree-store>')
          (iter `<gtk-tree-iter>') (position `<gtk-tree-iter>')
 -- Method: move-after
     Moves ITER in TREE-STORE to the position after POSITION.  ITER and
     POSITION should be in the same level. Note that this function only
     works with unsorted stores. If POSITION is ``#f'', ITER will be
     moved to the start of the level.

    TREE-STORE
          A `<gtk-tree-store>'.

    ITER
          A `<gtk-tree-iter>'.

    POSITION
          A `<gtk-tree-iter>'.


     Since 2.2



File: guile-gnome-gtk.info,  Node: GtkComboBox,  Next: GtkComboBoxEntry,  Prev: GtkTreeStore,  Up: Top

54 GtkComboBox
**************

A widget used to choose from a list of items

54.1 Overview
=============

A `<gtk-combo-box>' is a widget that allows the user to choose from a
list of valid choices. The `<gtk-combo-box>' displays the selected
choice. When activated, the `<gtk-combo-box>' displays a popup which
allows the user to make a new choice. The style in which the selected
value is displayed, and the style of the popup is determined by the
current theme. It may be similar to a `<gtk-option-menu>', or similar
to a Windows-style combo box.

   Unlike its predecessors `<gtk-combo>' and `<gtk-option-menu>', the
`<gtk-combo-box>' uses the model-view pattern; the list of valid
choices is specified in the form of a tree model, and the display of
the choices can be adapted to the data in the model by using cell
renderers, as you would in a tree view. This is possible since
`<gtk-combo-box>' implements the `<gtk-cell-layout>' interface. The
tree model holding the valid choices is not restricted to a flat list,
it can be a real tree, and the popup will reflect the tree structure.

   In addition to the model-view API, `<gtk-combo-box>' offers a simple
API which is suitable for text-only combo boxes, and hides the
complexity of managing the data in a model. It consists of the functions
`gtk-combo-box-new-text', `gtk-combo-box-append-text',
`gtk-combo-box-insert-text', `gtk-combo-box-prepend-text',
`gtk-combo-box-remove-text' and `gtk-combo-box-get-active-text'.

54.2 Usage
==========

 -- Class: <gtk-combo-box>
     Derives from `<gtk-cell-layout>', `<gtk-cell-editable>',
     `<gtk-bin>'.

     This class defines the following properties:

    `model'
          The model for the combo box

    `wrap-width'
          Wrap width for laying out the items in a grid

    `row-span-column'
          TreeModel column containing the row span values

    `column-span-column'
          TreeModel column containing the column span values

    `active'
          The item which is currently active

    `add-tearoffs'
          Whether dropdowns should have a tearoff menu item

    `tearoff-title'
          A title that may be displayed by the window manager when the
          popup is torn-off

    `has-frame'
          Whether the combo box draws a frame around the child

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

    `popup-shown'
          Whether the combo's dropdown is shown



 -- Signal on <gtk-combo-box>: changed
     The changed signal is emitted when the active item is changed. The
     can be due to the user selecting a different item from the list,
     or due to a call to `gtk-combo-box-set-active-iter'. It will also
     be emitted while typing into a GtkComboBoxEntry, as well as when
     selecting an item from the GtkComboBoxEntry's list.

     Since 2.4


 -- Signal on <gtk-combo-box>: move-active (arg0 `<gtk-scroll-type>')
     undocumented

 -- Signal on <gtk-combo-box>: popup
     undocumented

 -- Signal on <gtk-combo-box>: popdown => `<gboolean>'
     undocumented

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

    RET
          A new `<gtk-combo-box>'.


     Since 2.4


 -- Function: gtk-combo-box-new-with-model (model `<gtk-tree-model>')
          =>  (ret `<gtk-widget>')
     Creates a new `<gtk-combo-box>' with the model initialized to
     MODEL.

    MODEL
          A `<gtk-tree-model>'.

    RET
          A new `<gtk-combo-box>'.


     Since 2.4


 -- Function: gtk-combo-box-get-wrap-width (self `<gtk-combo-box>') => 
          (ret `int')
 -- Method: get-wrap-width
     Returns the wrap width which is used to determine the number of
     columns for the popup menu. If the wrap width is larger than 1,
     the combo box is in table mode.

    COMBO-BOX
          A `<gtk-combo-box>'.

    RET
          the wrap width.


     Since 2.6


 -- Function: gtk-combo-box-set-wrap-width (self `<gtk-combo-box>')
          (width `int')
 -- Method: set-wrap-width
     Sets the wrap width of COMBO-BOX to be WIDTH. The wrap width is
     basically the preferred number of columns when you want the popup
     to be layed out in a table.

    COMBO-BOX
          A `<gtk-combo-box>'.

    WIDTH
          Preferred number of columns.


     Since 2.4


 -- Function: gtk-combo-box-get-row-span-column
          (self `<gtk-combo-box>') =>  (ret `int')
 -- Method: get-row-span-column
     Returns the column with row span information for COMBO-BOX.

    COMBO-BOX
          A `<gtk-combo-box>'.

    RET
          the row span column.


     Since 2.6


 -- Function: gtk-combo-box-set-row-span-column
          (self `<gtk-combo-box>') (row_span `int')
 -- Method: set-row-span-column
     Sets the column with row span information for COMBO-BOX to be
     ROW-SPAN. The row span column contains integers which indicate how
     many rows an item should span.

    COMBO-BOX
          A `<gtk-combo-box>'.

    ROW-SPAN
          A column in the model passed during construction.


     Since 2.4


 -- Function: gtk-combo-box-get-active (self `<gtk-combo-box>') => 
          (ret `int')
 -- Method: get-active
     Returns the index of the currently active item, or -1 if there's
     no active item.  If the model is a non-flat treemodel, and the
     active item is not an immediate child of the root of the tree,
     this function returns `gtk_tree_path_get_indices (path)[0]', where
     `path' is the `<gtk-tree-path>' of the active item.

    COMBO-BOX
          A `<gtk-combo-box>'.

    RET
          An integer which is the index of the currently active item,
          or -1 if there's no active item.


     Since 2.4


 -- Function: gtk-combo-box-set-active (self `<gtk-combo-box>')
          (index_ `int')
 -- Method: set-active
     Sets the active item of COMBO-BOX to be the item at INDEX.

    COMBO-BOX
          A `<gtk-combo-box>'.

    INDEX
          An index in the model passed during construction, or -1 to
          have no active item.


     Since 2.4


 -- Function: gtk-combo-box-get-active-iter (self `<gtk-combo-box>')
          (iter `<gtk-tree-iter>') =>  (ret `bool')
 -- Method: get-active-iter
     Sets ITER to point to the current active item, if it exists.

    COMBO-BOX
          A `<gtk-combo-box>'

    ITER
          The uninitialized `<gtk-tree-iter>'.

    RET
          ``#t'', if ITER was set


     Since 2.4


 -- Function: gtk-combo-box-set-active-iter (self `<gtk-combo-box>')
          (iter `<gtk-tree-iter>')
 -- Method: set-active-iter
     Sets the current active item to be the one referenced by ITER. ITER
     must correspond to a path of depth one.

    COMBO-BOX
          A `<gtk-combo-box>'

    ITER
          The `<gtk-tree-iter>'.


     Since 2.4


 -- Function: gtk-combo-box-get-model (self `<gtk-combo-box>') => 
          (ret `<gtk-tree-model>')
 -- Method: get-model
     Returns the `<gtk-tree-model>' which is acting as data source for
     COMBO-BOX.

    COMBO-BOX
          A `<gtk-combo-box>'.

    RET
          A `<gtk-tree-model>' which was passed during construction.


     Since 2.4


 -- Function: gtk-combo-box-set-model (self `<gtk-combo-box>')
          (model `<gtk-tree-model>')
 -- Method: set-model
     Sets the model used by COMBO-BOX to be MODEL. Will unset a
     previously set model (if applicable). If model is ``#f'', then it
     will unset the model.

     Note that this function does not clear the cell renderers, you
     have to call `gtk-combo-box-cell-layout-clear' yourself if you
     need to set up different cell renderers for the new model.

    COMBO-BOX
          A `<gtk-combo-box>'.

    MODEL
          A `<gtk-tree-model>'.


     Since 2.4


 -- Function: gtk-combo-box-new-text =>  (ret `<gtk-widget>')
     Convenience function which constructs a new text combo box, which
     is a `<gtk-combo-box>' just displaying strings. If you use this
     function to create a text combo box, you should only manipulate
     its data source with the following convenience functions:
     `gtk-combo-box-append-text', `gtk-combo-box-insert-text',
     `gtk-combo-box-prepend-text' and `gtk-combo-box-remove-text'.

    RET
          A new text combo box.


     Since 2.4


 -- Function: gtk-combo-box-append-text (self `<gtk-combo-box>')
          (text `mchars')
 -- Method: append-text
     Appends STRING to the list of strings stored in COMBO-BOX. Note
     that you can only use this function with combo boxes constructed
     with `gtk-combo-box-new-text'.

    COMBO-BOX
          A `<gtk-combo-box>' constructed using
          `gtk-combo-box-new-text'.

    TEXT
          A string.


     Since 2.4


 -- Function: gtk-combo-box-insert-text (self `<gtk-combo-box>')
          (position `int') (text `mchars')
 -- Method: insert-text
     Inserts STRING at POSITION in the list of strings stored in
     COMBO-BOX. Note that you can only use this function with combo
     boxes constructed with `gtk-combo-box-new-text'.

    COMBO-BOX
          A `<gtk-combo-box>' constructed using
          `gtk-combo-box-new-text'.

    POSITION
          An index to insert TEXT.

    TEXT
          A string.


     Since 2.4


 -- Function: gtk-combo-box-prepend-text (self `<gtk-combo-box>')
          (text `mchars')
 -- Method: prepend-text
     Prepends STRING to the list of strings stored in COMBO-BOX. Note
     that you can only use this function with combo boxes constructed
     with `gtk-combo-box-new-text'.

    COMBO-BOX
          A `<gtk-combo-box>' constructed with `gtk-combo-box-new-text'.

    TEXT
          A string.


     Since 2.4


 -- Function: gtk-combo-box-remove-text (self `<gtk-combo-box>')
          (position `int')
 -- Method: remove-text
     Removes the string at POSITION from COMBO-BOX. Note that you can
     only use this function with combo boxes constructed with
     `gtk-combo-box-new-text'.

    COMBO-BOX
          A `<gtk-combo-box>' constructed with `gtk-combo-box-new-text'.

    POSITION
          Index of the item to remove.


     Since 2.4


 -- Function: gtk-combo-box-get-active-text (self `<gtk-combo-box>')
          =>  (ret `mchars')
 -- Method: get-active-text
     Returns the currently active string in COMBO-BOX or ``#f'' if none
     is selected. Note that you can only use this function with combo
     boxes constructed with `gtk-combo-box-new-text' and with
     `<gtk-combo-box-entry>'s.

    COMBO-BOX
          A `<gtk-combo-box>' constructed with `gtk-combo-box-new-text'.

    RET
          a newly allocated string containing the currently active text.


     Since 2.6


 -- Function: gtk-combo-box-popup (self `<gtk-combo-box>')
 -- Method: popup
     Pops up the menu or dropdown list of COMBO-BOX.

     This function is mostly intended for use by accessibility
     technologies; applications should have little use for it.

    COMBO-BOX
          a `<gtk-combo-box>'


     Since 2.4


 -- Function: gtk-combo-box-popdown (self `<gtk-combo-box>')
 -- Method: popdown
     Hides the menu or dropdown list of COMBO-BOX.

     This function is mostly intended for use by accessibility
     technologies; applications should have little use for it.

    COMBO-BOX
          a `<gtk-combo-box>'


     Since 2.4


 -- Function: gtk-combo-box-get-popup-accessible
          (self `<gtk-combo-box>') =>  (ret `<atk-object>')
 -- Method: get-popup-accessible
     Gets the accessible object corresponding to the combo box's popup.

     This function is mostly intended for use by accessibility
     technologies; applications should have little use for it.

    COMBO-BOX
          a `<gtk-combo-box>'

    RET
          the accessible object corresponding to the combo box's popup.


     Since 2.6


 -- Function: gtk-combo-box-set-add-tearoffs (self `<gtk-combo-box>')
          (add_tearoffs `bool')
 -- Method: set-add-tearoffs
     Sets whether the popup menu should have a tearoff menu item.

    COMBO-BOX
          a `<gtk-combo-box>'

    ADD-TEAROFFS
          ``#t'' to add tearoff menu items


     Since 2.6


 -- Function: gtk-combo-box-get-add-tearoffs (self `<gtk-combo-box>')
          =>  (ret `bool')
 -- Method: get-add-tearoffs
     Gets the current value of the :add-tearoffs property.

    COMBO-BOX
          a `<gtk-combo-box>'

    RET
          the current value of the :add-tearoffs property.



 -- Function: gtk-combo-box-set-title (self `<gtk-combo-box>')
          (title `mchars')
 -- Method: set-title
     Sets the menu's title in tearoff mode.

    COMBO-BOX
          a `<gtk-combo-box>'

    TITLE
          a title for the menu in tearoff mode.


     Since 2.10


 -- Function: gtk-combo-box-get-title (self `<gtk-combo-box>') => 
          (ret `mchars')
 -- Method: get-title
     Gets the current title of the menu in tearoff mode. See
     `gtk-combo-box-set-add-tearoffs'.

    COMBO-BOX
          a `<gtk-combo-box>'

    RET
          the menu's title in tearoff mode. This is an internal copy of
          the string which must not be freed.


     Since 2.10


 -- Function: gtk-combo-box-set-focus-on-click (self `<gtk-combo-box>')
          (focus_on_click `bool')
 -- Method: set-focus-on-click
     Sets whether the combo box will grab focus when it is clicked with
     the mouse.  Making mouse clicks not grab focus is useful in places
     like toolbars where you don't want the keyboard focus removed from
     the main area of the application.

    COMBO
          a `<gtk-combo-box>'

    FOCUS-ON-CLICK
          whether the combo box grabs focus when clicked with the mouse


     Since 2.6


 -- Function: gtk-combo-box-get-focus-on-click (self `<gtk-combo-box>')
          =>  (ret `bool')
 -- Method: get-focus-on-click
     Returns whether the combo box grabs focus when it is clicked with
     the mouse. See `gtk-combo-box-set-focus-on-click'.

    COMBO
          a `<gtk-combo-box>'

    RET
          ``#t'' if the combo box grabs focus when it is clicked with
          the mouse.


     Since 2.6



File: guile-gnome-gtk.info,  Node: GtkComboBoxEntry,  Next: GtkMenu,  Prev: GtkComboBox,  Up: Top

55 GtkComboBoxEntry
*******************

A text entry field with a dropdown list

55.1 Overview
=============

A `<gtk-combo-box-entry>' is a widget that allows the user to choose
from a list of valid choices or enter a different value. It is very
similar to a `<gtk-combo-box>', but it displays the selected value in
an entry to allow modifying it.

   In contrast to a `<gtk-combo-box>', the underlying model of a
`<gtk-combo-box-entry>' must always have a text column (see
`gtk-combo-box-entry-set-text-column'), and the entry will show the
content of the text column in the selected row. To get the text from
the entry, use `gtk-combo-box-get-active-text'.

   The changed signal will be emitted while typing into a
GtkComboBoxEntry, as well as when selecting an item from the
GtkComboBoxEntry's list. Use `gtk-combo-box-get-active' or
`gtk-combo-box-get-active-iter' to discover whether an item was
actually selected from the list.

   Connect to the activate signal of the GtkEntry (use
`gtk-bin-get-child') to detect when the user actually finishes entering
text.

   The convenience API to construct simple text-only
`<gtk-combo-box>'es can also be used with `<gtk-combo-box-entry>'s
which have been constructed with `gtk-combo-box-entry-new-text'.

55.2 Usage
==========

 -- Class: <gtk-combo-box-entry>
     Derives from `<gtk-combo-box>'.

     This class defines the following properties:

    `text-column'
          A column in the data source model to get the strings from



 -- Function: gtk-combo-box-entry-new =>  (ret `<gtk-widget>')
     Creates a new `<gtk-combo-box-entry>' which has a `<gtk-entry>' as
     child. After construction, you should set a model using
     `gtk-combo-box-set-model' and a text_column * using
     `gtk-combo-box-entry-set-text-column'.

    RET
          A new `<gtk-combo-box-entry>'.


     Since 2.4


 -- Function: gtk-combo-box-entry-new-with-model
          (model `<gtk-tree-model>') (text_column `int') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-combo-box-entry>' which has a `<gtk-entry>' as
     child and a list of strings as popup. You can get the
     `<gtk-entry>' from a `<gtk-combo-box-entry>' using GTK_ENTRY
     (GTK_BIN (combo_box_entry)->child).  To add and remove strings
     from the list, just modify MODEL using its data manipulation API.

    MODEL
          A `<gtk-tree-model>'.

    TEXT-COLUMN
          A column in MODEL to get the strings from.

    RET
          A new `<gtk-combo-box-entry>'.


     Since 2.4


 -- Function: gtk-combo-box-entry-new-text =>  (ret `<gtk-widget>')
     Convenience function which constructs a new editable text combo
     box, which is a `<gtk-combo-box-entry>' just displaying strings.
     If you use this function to create a text combo box, you should
     only manipulate its data source with the following convenience
     functions: `gtk-combo-box-append-text',
     `gtk-combo-box-insert-text', `gtk-combo-box-prepend-text' and
     `gtk-combo-box-remove-text'.

    RET
          A new text `<gtk-combo-box-entry>'.


     Since 2.4


 -- Function: gtk-combo-box-entry-set-text-column
          (self `<gtk-combo-box-entry>') (text_column `int')
 -- Method: set-text-column
     Sets the model column which ENTRY-BOX should use to get strings
     from to be TEXT-COLUMN.

    ENTRY-BOX
          A `<gtk-combo-box-entry>'.

    TEXT-COLUMN
          A column in MODEL to get the strings from.


     Since 2.4


 -- Function: gtk-combo-box-entry-get-text-column
          (self `<gtk-combo-box-entry>') =>  (ret `int')
 -- Method: get-text-column
     Returns the column which ENTRY-BOX is using to get the strings
     from.

    ENTRY-BOX
          A `<gtk-combo-box-entry>'.

    RET
          A column in the data source model of ENTRY-BOX.


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkMenu,  Next: GtkMenuBar,  Prev: GtkComboBoxEntry,  Up: Top

56 GtkMenu
**********

A menu widget

56.1 Overview
=============

A `<gtk-menu>' is a `<gtk-menu-shell>' that implements a drop down menu
consisting of a list of `<gtk-menu-item>' objects which can be
navigated and activated by the user to perform application functions.

   A `<gtk-menu>' is most commonly dropped down by activating a
`<gtk-menu-item>' in a `<gtk-menu-bar>' or popped up by activating a
`<gtk-menu-item>' in another `<gtk-menu>'.

   A `<gtk-menu>' can also be popped up by activating a
`<gtk-option-menu>'. Other composite widgets such as the
`<gtk-notebook>' can pop up a `<gtk-menu>' as well.

   Applications can display a `<gtk-menu>' as a popup menu by calling
the `gtk-menu-popup' function. The example below shows how an
application can pop up a menu when the 3rd mouse button is pressed.


         /* connect our handler which will popup the menu */
         g_signal_connect_swapped (window, "button_press_event",
     	G_CALLBACK (my_popup_handler), menu);


     static gint
     my_popup_handler (GtkWidget *widget, GdkEvent *event)
     {
       GtkMenu *menu;
       GdkEventButton *event_button;

       g_return_val_if_fail (widget != NULL, FALSE);
       g_return_val_if_fail (GTK_IS_MENU (widget), FALSE);
       g_return_val_if_fail (event != NULL, FALSE);

       /* The "widget" is the menu that was supplied when
        * g_signal_connect_swapped() was called.
        */
       menu = GTK_MENU (widget);

       if (event->type == GDK_BUTTON_PRESS)
         {
           event_button = (GdkEventButton *) event;
           if (event_button->button == 3)
     	{
     	  gtk_menu_popup (menu, NULL, NULL, NULL, NULL,
     			  event_button->button, event_button->time);
     	  return TRUE;
     	}
         }

       return FALSE;
     }

56.2 Usage
==========

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

     This class defines the following properties:

    `tearoff-state'
          A boolean that indicates whether the menu is torn-off

    `tearoff-title'
          A title that may be displayed by the window manager when this
          menu is torn-off



 -- Signal on <gtk-menu>: move-scroll (arg0 `<gtk-scroll-type>')

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

    RET
          a new `<gtk-menu>'.



 -- Function: gtk-menu-set-screen (self `<gtk-menu>')
          (screen `<gdk-screen>')
 -- Method: set-screen
     Sets the `<gdk-screen>' on which the menu will be displayed.

    MENU
          a `<gtk-menu>'.

    SCREEN
          a `<gdk-screen>', or ``#f'' if the screen should be
          determined by the widget the menu is attached to.


     Since 2.2


 -- Function: gtk-menu-reorder-child (self `<gtk-menu>')
          (child `<gtk-widget>') (position `int')
 -- Method: reorder-child
     Moves a `<gtk-menu-item>' to a new position within the
     `<gtk-menu>'.

    MENU
          a `<gtk-menu>'.

    CHILD
          the `<gtk-menu-item>' to move.

    POSITION
          the new position to place CHILD. Positions are numbered from
          0 to n-1.



 -- Function: gtk-menu-attach (self `<gtk-menu>')
          (child `<gtk-widget>') (left_attach `unsigned-int')
          (right_attach `unsigned-int') (top_attach `unsigned-int')
          (bottom_attach `unsigned-int')
 -- Method: attach
     Adds a new `<gtk-menu-item>' to a (table) menu. The number of
     'cells' that an item will occupy is specified by LEFT-ATTACH,
     RIGHT-ATTACH, TOP-ATTACH and BOTTOM-ATTACH. These each represent
     the leftmost, rightmost, uppermost and lower column and row
     numbers of the table. (Columns and rows are indexed from zero).

     Note that this function is not related to `gtk-menu-detach'.

    MENU
          a `<gtk-menu>'.

    CHILD
          a `<gtk-menu-item>'.

    LEFT-ATTACH
          The column number to attach the left side of the item to.

    RIGHT-ATTACH
          The column number to attach the right side of the item to.

    TOP-ATTACH
          The row number to attach the top of the item to.

    BOTTOM-ATTACH
          The row number to attach the bottom of the item to.


     Since 2.4


 -- Function: gtk-menu-set-accel-group (self `<gtk-menu>')
          (accel_group `<gtk-accel-group>')
 -- Method: set-accel-group
     Set the `<gtk-accel-group>' which holds global accelerators for
     the menu.  This accelerator group needs to also be added to all
     windows that this menu is being used in with
     `gtk-window-add-accel-group', in order for those windows to
     support all the accelerators contained in this group.

    MENU
          a `<gtk-menu>'.

    ACCEL-GROUP
          the `<gtk-accel-group>' to be associated with the menu.



 -- Function: gtk-menu-get-accel-group (self `<gtk-menu>') => 
          (ret `<gtk-accel-group>')
 -- Method: get-accel-group
     Gets the `<gtk-accel-group>' which holds global accelerators for
     the menu.  See `gtk-menu-set-accel-group'.

    MENU
          a `<gtk-menu>'.

    RET
          the `<gtk-accel-group>' associated with the menu.



 -- Function: gtk-menu-set-accel-path (self `<gtk-menu>')
          (accel_path `mchars')
 -- Method: set-accel-path
     Sets an accelerator path for this menu from which accelerator
     paths for its immediate children, its menu items, can be
     constructed. The main purpose of this function is to spare the
     programmer the inconvenience of having to call
     `gtk-menu-item-set-accel-path' on each menu item that should
     support runtime user changable accelerators. Instead, by just
     calling `gtk-menu-set-accel-path' on their parent, each menu item
     of this menu, that contains a label describing its purpose,
     automatically gets an accel path assigned. For example, a menu
     containing menu items "New" and "Exit", will, after
     `gtk_menu_set_accel_path (menu, "<Gnumeric-Sheet>/File");' has been
     called, assign its items the accel paths:
     `"<Gnumeric-Sheet>/File/New"' and `"<Gnumeric-Sheet>/File/Exit"'.
     Assigning accel paths to menu items then enables the user to
     change their accelerators at runtime. More details about
     accelerator paths and their default setups can be found at
     `gtk-accel-map-add-entry'.

    MENU
          a valid `<gtk-menu>'

    ACCEL-PATH
          a valid accelerator path



 -- Function: gtk-menu-set-title (self `<gtk-menu>') (title `mchars')
 -- Method: set-title
     Sets the title string for the menu. The title is displayed when
     the menu is shown as a tearoff menu. If TITLE is ``#f'', the menu
     will see if it is attached to a parent menu item, and if so it
     will try to use the same text as that menu item's label.

    MENU
          a `<gtk-menu>'

    TITLE
          a string containing the title for the menu.



 -- Function: gtk-menu-get-tearoff-state (self `<gtk-menu>') => 
          (ret `bool')
 -- Method: get-tearoff-state
     Returns whether the menu is torn off. See
     `gtk-menu-set-tearoff-state'.

    MENU
          a `<gtk-menu>'

    RET
          ``#t'' if the menu is currently torn off.



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

    MENU
          a `<gtk-menu>'

    RET
          the title of the menu, or ``#f'' if the menu has no title set
          on it.  This string is owned by the widget and should not be
          modified or freed.



 -- Function: gtk-menu-popdown (self `<gtk-menu>')
 -- Method: popdown
     Removes the menu from the screen.

    MENU
          a `<gtk-menu>'.



 -- Function: gtk-menu-reposition (self `<gtk-menu>')
 -- Method: reposition
     Repositions the menu according to its position function.

    MENU
          a `<gtk-menu>'.



 -- Function: gtk-menu-get-active (self `<gtk-menu>') => 
          (ret `<gtk-widget>')
 -- Method: get-active
     Returns the selected menu item from the menu. This is used by the
     `<gtk-option-menu>'.

    MENU
          a `<gtk-menu>'.

    RET
          the `<gtk-menu-item>' that was last selected in the menu. If
          a selection has not yet been made, the first menu item is
          selected.



 -- Function: gtk-menu-set-active (self `<gtk-menu>')
          (index `unsigned-int')
 -- Method: set-active
     Selects the specified menu item within the menu. This is used by
     the `<gtk-option-menu>' and should not be used by anyone else.

    MENU
          a `<gtk-menu>'.

    INDEX
          the index of the menu item to select. Index values are from 0
          to n-1.



 -- Function: gtk-menu-set-tearoff-state (self `<gtk-menu>')
          (torn_off `bool')
 -- Method: set-tearoff-state
     Changes the tearoff state of the menu. A menu is normally
     displayed as drop down menu which persists as long as the menu is
     active. It can also be displayed as a tearoff menu which persists
     until it is closed or reattached.

    MENU
          a `<gtk-menu>'.

    TORN-OFF
          If ``#t'', menu is displayed as a tearoff menu.



 -- Function: gtk-menu-detach (self `<gtk-menu>')
 -- Method: detach
     Detaches the menu from the widget to which it had been attached.
     This function will call the callback function, DETACHER, provided
     when the `gtk-menu-attach-to-widget' function was called.

    MENU
          a `<gtk-menu>'.



 -- Function: gtk-menu-get-attach-widget (self `<gtk-menu>') => 
          (ret `<gtk-widget>')
 -- Method: get-attach-widget
     Returns the `<gtk-widget>' that the menu is attached to.

    MENU
          a `<gtk-menu>'.

    RET
          the `<gtk-widget>' that the menu is attached to.



 -- Function: gtk-menu-get-for-attach-widget (widget `<gtk-widget>')
          =>  (ret `glist-of')
     Returns a list of the menus which are attached to this widget.
     This list is owned by GTK+ and must not be modified.

    WIDGET
          a `<gtk-widget>'

    RET
          the list of menus attached to his widget.


     Since 2.6


 -- Function: gtk-menu-set-monitor (self `<gtk-menu>')
          (monitor_num `int')
 -- Method: set-monitor
     Informs GTK+ on which monitor a menu should be popped up. See
     `gdk-screen-get-monitor-geometry'.

     This function should be called from a `<gtk-menu-position-func>'
     if the menu should not appear on the same monitor as the pointer.
     This information can't be reliably inferred from the coordinates
     returned by a `<gtk-menu-position-func>', since, for very long
     menus, these coordinates may extend beyond the monitor boundaries
     or even the screen boundaries.

    MENU
          a `<gtk-menu>'

    MONITOR-NUM
          the number of the monitor on which the menu should be popped
          up


     Since 2.4



File: guile-gnome-gtk.info,  Node: GtkMenuBar,  Next: GtkMenuItem,  Prev: GtkMenu,  Up: Top

57 GtkMenuBar
*************

A subclass widget for which holds widgets

57.1 Overview
=============

The `<gtk-menu-bar>' is a subclass of `<gtk-menu-shell>' which contains
one to many `<gtk-menu-item>'. The result is a standard menu bar which
can hold many menu items. `<gtk-menu-bar>' allows for a shadow type to
be set for aesthetic purposes. The shadow types are defined in the
`<gtk-menu-bar-set-shadow-type>' function.

57.2 Usage
==========

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

     This class defines the following properties:

    `pack-direction'
          The pack direction of the menubar

    `child-pack-direction'
          The child pack direction of the menubar



 -- Function: gtk-menu-bar-new =>  (ret `<gtk-widget>')
     Creates the new `<gtk-menu-bar>'

    RET
          the `<gtk-menu-bar>'



 -- Function: gtk-menu-bar-set-pack-direction (self `<gtk-menu-bar>')
          (pack_dir `<gtk-pack-direction>')
 -- Method: set-pack-direction
     Sets how items should be packed inside a menubar.

    MENUBAR
          a `<gtk-menu-bar>'.

    PACK-DIR
          a new `<gtk-pack-direction>'.


     Since 2.8


 -- Function: gtk-menu-bar-get-pack-direction (self `<gtk-menu-bar>')
          =>  (ret `<gtk-pack-direction>')
 -- Method: get-pack-direction
     Retrieves the current pack direction of the menubar. See
     `gtk-menu-bar-set-pack-direction'.

    MENUBAR
          a `<gtk-menu-bar>'

    RET
          the pack direction


     Since 2.8



File: guile-gnome-gtk.info,  Node: GtkMenuItem,  Next: GtkMenuShell,  Prev: GtkMenuBar,  Up: Top

58 GtkMenuItem
**************

The widget used for item in menus

58.1 Overview
=============

The `<gtk-menu-item>' widget and the derived widgets are the only valid
childs for menus. Their function is to correctly handle highlighting,
alignment, events and submenus.

   As it derives from `<gtk-bin>' it can hold any valid child widget,
altough only a few are really useful.

58.2 Usage
==========

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

     This class defines the following properties:

    `submenu'
          The submenu attached to the menu item, or NULL if it has none



 -- Signal on <gtk-menu-item>: activate
     Emitted when the item is activated.


 -- Signal on <gtk-menu-item>: activate-item
     Emitted when the item is activated, but also if the menu item has
     a submenu. For normal applications, the relevant signal is
     "activate".


 -- Signal on <gtk-menu-item>: toggle-size-request (arg0 `<gpointer>')

 -- Signal on <gtk-menu-item>: toggle-size-allocate (arg0 `<gint>')

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

    RET
          the newly created `<gtk-menu-item>'



 -- Function: gtk-menu-item-new-with-label (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-menu-item>' whose child is a `<gtk-label>'.

    LABEL
          the text for the label

    RET
          the newly created `<gtk-menu-item>'



 -- Function: gtk-menu-item-new-with-mnemonic (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-menu-item>' containing a label. The label will
     be created using `gtk-label-new-with-mnemonic', so underscores in
     LABEL indicate the mnemonic for the menu item.

    LABEL
          The text of the button, with an underscore in front of the
          mnemonic character

    RET
          a new `<gtk-menu-item>'



 -- Function: gtk-menu-item-set-right-justified
          (self `<gtk-menu-item>') (right_justified `bool')
 -- Method: set-right-justified
     Sets whether the menu item appears justified at the right side of
     a menu bar.  This was traditionally done for "Help" menu items,
     but is now considered a bad idea. (If the widget layout is
     reversed for a right-to-left language like Hebrew or Arabic,
     right-justified-menu-items appear at the left.)

    MENU-ITEM
          a `<gtk-menu-item>'.

    RIGHT-JUSTIFIED
          if ``#t'' the menu item will appear at the far right if added
          to a menu bar.



 -- Function: gtk-menu-item-set-submenu (self `<gtk-menu-item>')
          (submenu `<gtk-widget>')
 -- Method: set-submenu
     Sets the widget submenu, or changes it.

    MENU-ITEM
          the menu item widget

    SUBMENU
          the submenu



 -- Function: gtk-menu-item-set-accel-path (self `<gtk-menu-item>')
          (accel_path `mchars')
 -- Method: set-accel-path
     Set the accelerator path on MENU-ITEM, through which runtime
     changes of the menu item's accelerator caused by the user can be
     identified and saved to persistant storage (see
     `gtk-accel-map-save' on this). To setup a default accelerator for
     this menu item, call `gtk-accel-map-add-entry' with the same
     ACCEL-PATH. See also `gtk-accel-map-add-entry' on the specifics of
     accelerator paths, and `gtk-menu-set-accel-path' for a more
     convenient variant of this function.

     This function is basically a convenience wrapper that handles
     calling `gtk-widget-set-accel-path' with the appropriate
     accelerator group for the menu item.

     Note that you do need to set an accelerator on the parent menu with
     `gtk-menu-set-accel-group' for this to work.

    MENU-ITEM
          a valid `<gtk-menu-item>'

    ACCEL-PATH
          accelerator path, corresponding to this menu item's
          functionality, or ``#f'' to unset the current path.



 -- Function: gtk-menu-item-remove-submenu (self `<gtk-menu-item>')
 -- Method: remove-submenu
     Removes the widget's submenu.

    MENU-ITEM
          the menu item widget



 -- Function: gtk-menu-item-select (self `<gtk-menu-item>')
 -- Method: select
     Emits the "select" signal on the given item. Behaves exactly like
     `<gtk-item-select>'.

    MENU-ITEM
          the menu item



 -- Function: gtk-menu-item-deselect (self `<gtk-menu-item>')
 -- Method: deselect
     Emits the "deselect" signal on the given item. Behaves exactly like
     `<gtk-item-deselect>'.

    MENU-ITEM
          the menu item



 -- Function: gtk-menu-item-activate (self `<gtk-menu-item>')
 -- Method: activate
     Emits the "activate" signal on the given item

    MENU-ITEM
          the menu item



 -- Function: gtk-menu-item-toggle-size-request
          (self `<gtk-menu-item>') =>  (requisition `int')
 -- Method: toggle-size-request
     Emits the "toggle_size_request" signal on the given item.

    MENU-ITEM
          the menu item

    REQUISITION
          the requisition to use as signal data.



 -- Function: gtk-menu-item-toggle-size-allocate
          (self `<gtk-menu-item>') (allocation `int')
 -- Method: toggle-size-allocate
     Emits the "toggle_size_allocate" signal on the given item.

    MENU-ITEM
          the menu item.

    ALLOCATION
          the allocation to use as signal data.



 -- Function: gtk-menu-item-get-right-justified
          (self `<gtk-menu-item>') =>  (ret `bool')
 -- Method: get-right-justified
     Gets whether the menu item appears justified at the right side of
     the menu bar.

    MENU-ITEM
          a `<gtk-menu-item>'

    RET
          ``#t'' if the menu item will appear at the far right if added
          to a menu bar.



 -- Function: gtk-menu-item-get-submenu (self `<gtk-menu-item>') => 
          (ret `<gtk-widget>')
 -- Method: get-submenu
     Gets the submenu underneath this menu item, if any. See
     `gtk-menu-item-set-submenu'.

    MENU-ITEM
          a `<gtk-menu-item>'

    RET
          submenu for this menu item, or ``#f'' if none.




File: guile-gnome-gtk.info,  Node: GtkMenuShell,  Next: GtkImageMenuItem,  Prev: GtkMenuItem,  Up: Top

59 GtkMenuShell
***************

A base class for menu objects

59.1 Overview
=============

A `<gtk-menu-shell>' is the abstract base class used to derive the
`<gtk-menu>' and `<gtk-menu-bar>' subclasses.

   A `<gtk-menu-shell>' is a container of `<gtk-menu-item>' objects
arranged in a list which can be navigated, selected, and activated by
the user to perform application functions. A `<gtk-menu-item>' can have
a submenu associated with it, allowing for nested hierarchical menus.

59.2 Usage
==========

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

     This class defines the following properties:

    `take-focus'
          A boolean that determines whether the menu grabs the keyboard
          focus



 -- Signal on <gtk-menu-shell>: cancel
     An action signal which cancels the selection within the menu
     shell. Causes the GtkMenuShell::selection-done signal to be
     emitted.


 -- Signal on <gtk-menu-shell>: deactivate
     This signal is emitted when a menu shell is deactivated.


 -- Signal on <gtk-menu-shell>: selection-done
     This signal is emitted when a selection has been completed within
     a menu shell.


 -- Signal on <gtk-menu-shell>: move-current
          (arg0 `<gtk-menu-direction-type>')
     An action signal which moves the current menu item in the
     direction specified by DIRECTION.


 -- Signal on <gtk-menu-shell>: activate-current (arg0 `<gboolean>')
     An action signal that activates the current menu item within the
     menu shell.


 -- Signal on <gtk-menu-shell>: cycle-focus
          (arg0 `<gtk-direction-type>')

 -- Signal on <gtk-menu-shell>: move-selected (arg0 `<gint>')
          => `<gboolean>'
     undocumented

 -- Function: gtk-menu-shell-append (self `<gtk-menu-shell>')
          (child `<gtk-widget>')
 -- Method: append
     Adds a new `<gtk-menu-item>' to the end of the menu shell's item
     list.

    MENU-SHELL
          a `<gtk-menu-shell>'.

    CHILD
          The `<gtk-menu-item>' to add.



 -- Function: gtk-menu-shell-prepend (self `<gtk-menu-shell>')
          (child `<gtk-widget>')
 -- Method: prepend
     Adds a new `<gtk-menu-item>' to the beginning of the menu shell's
     item list.

    MENU-SHELL
          a `<gtk-menu-shell>'.

    CHILD
          The `<gtk-menu-item>' to add.



 -- Function: gtk-menu-shell-insert (self `<gtk-menu-shell>')
          (child `<gtk-widget>') (position `int')
 -- Method: insert
     Adds a new `<gtk-menu-item>' to the menu shell's item list at the
     position indicated by POSITION.

    MENU-SHELL
          a `<gtk-menu-shell>'.

    CHILD
          The `<gtk-menu-item>' to add.

    POSITION
          The position in the item list where CHILD is added. Positions
          are numbered from 0 to n-1.



 -- Function: gtk-menu-shell-deactivate (self `<gtk-menu-shell>')
 -- Method: deactivate
     Deactivates the menu shell. Typically this results in the menu
     shell being erased from the screen.

    MENU-SHELL
          a `<gtk-menu-shell>'.



 -- Function: gtk-menu-shell-select-item (self `<gtk-menu-shell>')
          (menu_item `<gtk-widget>')
 -- Method: select-item
     Selects the menu item from the menu shell.

    MENU-SHELL
          a `<gtk-menu-shell>'.

    MENU-ITEM
          The `<gtk-menu-item>' to select.



 -- Function: gtk-menu-shell-select-first (self `<gtk-menu-shell>')
          (search_sensitive `bool')
 -- Method: select-first
     Select the first visible or selectable child of the menu shell;
     don't select tearoff items unless the only item is a tearoff item.

    MENU-SHELL
          a `<gtk-menu-shell>'

    SEARCH-SENSITIVE
          if ``#t'', search for the first selectable menu item,
          otherwise select nothing if the first item isn't sensitive.
          This should be ``#f'' if the menu is being popped up
          initially.


     Since 2.2


 -- Function: gtk-menu-shell-deselect (self `<gtk-menu-shell>')
 -- Method: deselect
     Deselects the currently selected item from the menu shell, if any.

    MENU-SHELL
          a `<gtk-menu-shell>'.



 -- Function: gtk-menu-shell-activate-item (self `<gtk-menu-shell>')
          (menu_item `<gtk-widget>') (force_deactivate `bool')
 -- Method: activate-item
     Activates the menu item within the menu shell.

    MENU-SHELL
          a `<gtk-menu-shell>'.

    MENU-ITEM
          The `<gtk-menu-item>' to activate.

    FORCE-DEACTIVATE
          If TRUE, force the deactivation of the menu shell after the
          menu item is activated.



 -- Function: gtk-menu-shell-cancel (self `<gtk-menu-shell>')
 -- Method: cancel
     Cancels the selection within the menu shell.

    MENU-SHELL
          a `<gtk-menu-shell>'


     Since 2.4


 -- Function: gtk-menu-shell-set-take-focus (self `<gtk-menu-shell>')
          (take_focus `bool')
 -- Method: set-take-focus
     If TAKE-FOCUS is ``#t'' (the default) the menu shell will take the
     keyboard focus so that it will receive all keyboard events which
     is needed to enable keyboard navigation in menus.

     Setting TAKE-FOCUS to ``#f'' is useful only for special
     applications like virtual keyboard implementations which should
     not take keyboard focus.

     The TAKE-FOCUS state of a menu or menu bar is automatically
     propagated to submenus whenever a submenu is popped up, so you
     don't have to worry about recursively setting it for your entire
     menu hierarchy. Only when programmatically picking a submenu and
     popping it up manually, the TAKE-FOCUS property of the submenu
     needs to be set explicitely.

     Note that setting it to ``#f'' has side-effects:

     If the focus is in some other app, it keeps the focus and keynav
     in the menu doesn't work. Consequently, keynav on the menu will
     only work if the focus is on some toplevel owned by the onscreen
     keyboard.

     To avoid confusing the user, menus with TAKE-FOCUS set to ``#f''
     should not display mnemonics or accelerators, since it cannot be
     guaranteed that they will work.

     See also `gdk-keyboard-grab'

    MENU-SHELL
          a `<gtk-menu-shell>'

    TAKE-FOCUS
          ``#t'' if the menu shell should take the keyboard focus on
          popup.


     Since 2.8


 -- Function: gtk-menu-shell-get-take-focus (self `<gtk-menu-shell>')
          =>  (ret `bool')
 -- Method: get-take-focus
     Returns ``#t'' if the menu shell will take the keyboard focus on
     popup.

    MENU-SHELL
          a `<gtk-menu-shell>'

    RET
          ``#t'' if the menu shell will take the keyboard focus on
          popup.


     Since 2.8



File: guile-gnome-gtk.info,  Node: GtkImageMenuItem,  Next: GtkRadioMenuItem,  Prev: GtkMenuShell,  Up: Top

60 GtkImageMenuItem
*******************

A menu item with an icon

60.1 Overview
=============

A GtkImageMenuItem is a menu item which has an icon next to the text
label.

   Note that the user can disable display of menu icons, so make sure
to still fill in the text label.

60.2 Usage
==========

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

     This class defines the following properties:

    `image'
          Child widget to appear next to the menu text



 -- Function: gtk-image-menu-item-set-image
          (self `<gtk-image-menu-item>') (image `<gtk-widget>')
 -- Method: set-image
     Sets the image of IMAGE-MENU-ITEM to the given widget. Note that it
     depends on the show-menu-images setting whether the image will be
     displayed or not.

    IMAGE-MENU-ITEM
          a `<gtk-image-menu-item>'.

    IMAGE
          a widget to set as the image for the menu item.



 -- Function: gtk-image-menu-item-get-image
          (self `<gtk-image-menu-item>') =>  (ret `<gtk-widget>')
 -- Method: get-image
     Gets the widget that is currently set as the image of
     IMAGE-MENU-ITEM. See `gtk-image-menu-item-set-image'.

    IMAGE-MENU-ITEM
          a `<gtk-image-menu-item>'.

    RET
          the widget set as image of IMAGE-MENU-ITEM.



 -- Function: gtk-image-menu-item-new =>  (ret `<gtk-widget>')
     Creates a new `<gtk-image-menu-item>' with an empty label.

    RET
          a new `<gtk-image-menu-item>'.



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

     If you want this menu item to have changeable accelerators, then
     pass in ``#f'' for accel_group. Next call
     `gtk-menu-item-set-accel-path' with an appropriate path for the
     menu item, use `gtk-stock-lookup' to look up the standard
     accelerator for the stock item, and if one is found, call
     `gtk-accel-map-add-entry' to register it.

    STOCK-ID
          the name of the stock item.

    ACCEL-GROUP
          the `<gtk-accel-group>' to add the menu items accelerator to,
          or ``#f''.

    RET
          a new `<gtk-image-menu-item>'.



 -- Function: gtk-image-menu-item-new-with-label (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-image-menu-item>' containing a label.

    LABEL
          the text of the menu item.

    RET
          a new `<gtk-image-menu-item>'.




File: guile-gnome-gtk.info,  Node: GtkRadioMenuItem,  Next: GtkCheckMenuItem,  Prev: GtkImageMenuItem,  Up: Top

61 GtkRadioMenuItem
*******************

A choice from multiple check menu items

61.1 Overview
=============

A radio menu item is a check menu item that belongs to a group. At each
instant exactly one of the radio menu items from a group is selected.

   The group list does not need to be freed, as each
`<gtk-radio-menu-item>' will remove itself and its list item when it is
destroyed.

   The correct way to create a group of radio menu items is
approximatively this:


     GSList *group = NULL;
     GtkWidget *item;
     gint i;

     for (i = 0; i < 5; i++)
     {
       item = gtk_radio_menu_item_new_with_label (group, "This is an example");
       group = gtk_radio_menu_item_get_group (GTK_RADIO_MENU_ITEM (item));
       if (i == 1)
         gtk_check_menu_item_set_active (GTK_CHECK_MENU_ITEM (item), TRUE);
     }

61.2 Usage
==========

 -- Class: <gtk-radio-menu-item>
     Derives from `<gtk-check-menu-item>'.

     This class defines the following properties:

    `group'
          The radio menu item whose group this widget belongs to.



 -- Signal on <gtk-radio-menu-item>: group-changed

 -- Function: gtk-radio-menu-item-new (group `<gtk-radio-group*>') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-radio-menu-item>'.

    GROUP
          the group to which the radio menu item is to be attached

    RET
          a new `<gtk-radio-menu-item>'



 -- Function: gtk-radio-menu-item-new-with-label
          (group `<gtk-radio-group*>') (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-radio-menu-item>' whose child is a simple
     `<gtk-label>'.

    GROUP
          the group to which the radio menu item is to be attached

    LABEL
          the text for the label

    RET
          a new `<gtk-radio-menu-item>'



 -- Function: gtk-radio-menu-item-new-from-widget
          (group `<gtk-radio-menu-item>') =>  (ret `<gtk-widget>')
     Creates a new `<gtk-radio-menu-item>' adding it to the same group
     as GROUP.

    GROUP
          An existing `<gtk-radio-menu-item>'

    RET
          The new `<gtk-radio-menu-item>'


     Since 2.4


 -- Function: gtk-radio-menu-item-set-group
          (self `<gtk-radio-menu-item>') (group `<gtk-radio-group*>')
 -- Method: set-group
     Sets the group of a radio menu item, or changes it.

    RADIO-MENU-ITEM
          a `<gtk-radio-menu-item>'.

    GROUP
          the new group.



 -- Function: gtk-radio-menu-item-get-group
          (self `<gtk-radio-menu-item>') =>  (ret `<gtk-radio-group*>')
 -- Method: get-group
     Returns the group to which the radio menu item belongs, as a
     `<g-list>' of `<gtk-radio-menu-item>'. The list belongs to GTK+
     and should not be freed.

    RADIO-MENU-ITEM
          a `<gtk-radio-menu-item>'.

    RET
          the group of RADIO-MENU-ITEM.




File: guile-gnome-gtk.info,  Node: GtkCheckMenuItem,  Next: GtkSeparatorMenuItem,  Prev: GtkRadioMenuItem,  Up: Top

62 GtkCheckMenuItem
*******************

A menu item with a check box

62.1 Overview
=============

A `<gtk-check-menu-item>' is a menu item that maintains the state of a
boolean value in addition to a `<gtk-menu-item>''s usual role in
activating application code.

   A check box indicating the state of the boolean value is displayed
at the left side of the `<gtk-menu-item>'. Activating the
`<gtk-menu-item>' toggles the value.

62.2 Usage
==========

 -- Class: <gtk-check-menu-item>
     Derives from `<gtk-menu-item>'.

     This class defines the following properties:

    `active'
          Whether the menu item is checked

    `inconsistent'
          Whether to display an "inconsistent" state

    `draw-as-radio'
          Whether the menu item looks like a radio menu item



 -- Signal on <gtk-check-menu-item>: toggled
     This signal is emitted when the state of the check box is changed.

     A signal handler can examine the `<gtk-check-menu-item>' struct to
     discover the new state.


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

    RET
          a new `<gtk-check-menu-item>'.



 -- Function: gtk-check-menu-item-new-with-label (label `mchars') => 
          (ret `<gtk-widget>')
     Creates a new `<gtk-check-menu-item>' with a label.

    LABEL
          the string to use for the label.

    RET
          a new `<gtk-check-menu-item>'.



 -- Function: gtk-check-menu-item-get-active
          (self `<gtk-check-menu-item>') =>  (ret `bool')
 -- Method: get-active
     Returns whether the check menu item is active. See
     `gtk-check-menu-item-set-active'.

    CHECK-MENU-ITEM
          a `<gtk-check-menu-item>'

    RET
          ``#t'' if the menu item is checked.



 -- Function: gtk-check-menu-item-set-active
          (self `<gtk-check-menu-item>') (is_active `bool')
 -- Method: set-active
     Sets the active state of the menu item's check box.

    CHECK-MENU-ITEM
          a `<gtk-check-menu-item>'.

    IS-ACTIVE
          boolean value indicating whether the check box is active.



 -- Function: gtk-check-menu-item-toggled (self `<gtk-check-menu-item>')
 -- Method: toggled
     Emits the GtkCheckMenuItem::toggled signal.

    CHECK-MENU-ITEM
          a `<gtk-check-menu-item>'.




File: guile-gnome-gtk.info,  Node: GtkSeparatorMenuItem,  Next: GtkTearoffMenuItem,  Prev: GtkCheckMenuItem,  Up: Top

63 GtkSeparatorMenuItem
***********************

A separator used in menus

63.1 Overview
=============

The `<gtk-separator-menu-item>' is a separator used to group items
within a menu. It displays a horizontal line with a shadow to make it
appear sunken into the interface.

63.2 Usage
==========

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

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


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

    RET
          a new `<gtk-separator-menu-item>'.




File: guile-gnome-gtk.info,  Node: GtkTearoffMenuItem,  Next: GtkToolbar,  Prev: GtkSeparatorMenuItem,  Up: Top

64 GtkTearoffMenuItem
*********************

A menu item used to tear off and reattach its menu

64.1 Overview
=============

A `<gtk-tearoff-menu-item>' is a special `<gtk-menu-item>' which is
used to tear off and reattach its menu.

   When its menu is shown normally, the `<gtk-tearoff-menu-item>' is
drawn as a dotted line indicating that the menu can be torn off.
Activating it causes its menu to be torn off and displayed in its own
window as a tearoff menu.

   When its menu is shown as a tearoff menu, the
`<gtk-tearoff-menu-item>' is drawn as a dotted line which has a left
pointing arrow graphic indicating that the tearoff menu can be
reattached. Activating it will erase the tearoff menu window.

64.2 Usage
==========

 -- Class: <gtk-tearoff-menu-item>
     Derives from `<gtk-menu-item>'.

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


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

    RET
          a new `<gtk-tearoff-menu-item>'.



