apress foundations_of gtk plus development 2007 phần 10 pptx

544
APPENDIX B
■ GTK+ SIGNALS
Table B-34. GtkMenuItem Signals
Table B-35. GtkMenuShell Signals
Signal Name Additional Parameters Description
activate None The menu item was activated.
If you need to catch activation
of a submenu, you should use
the activate-item signal.
activate-item None The menu item was activated,
or the menu item has a sub-
menu that was activated.
toggle-size-allocate gint new_size The menu item was allo-
cated with a new size.
toggle-size-request gpointer size The menu item requested a
new size.
Signal Name Additional Parameters Description
activate-current gboolean force_hide Activate the current
menu item contained by
GtkMenuShell.
cancel None Cancel the selection of the
selected menu item. This
will cause the selection-
done signal to be emitted.
cycle-focus GtkDirectionType type The focus moved to another
menu bar in the given
direction.
deactivate None The GtkMenuShell was deacti-
vated, which usually means
that it was erased from the

screen.
move-current GtkMenuDirectionType type The current menu item moved
within the menu shell in the
given direction.
selection-done None The selection within the
menu shell was completed.
7931.book Page 544 Wednesday, March 14, 2007 8:28 PM
APPENDIX B ■ GTK+ SIGNALS
545
Table B-36. GtkMenuToolButton Signals
Table B-37. GtkNotebook Signals
Table B-38. GtkObject Signals
Signal Name Description
show-menu This signal is emitted right before the menu is shown, giving you a
chance to update it before the user sees it.
Signal Name Additional Parameters Description
change-current-page gint pages_moved The page currently shown by
GtkNotebook was changed.
focus-tab GtkNotebookTab type The focus was moved by
changing the current tab. The
callback function returns TRUE
if the signal was handled.
move-focus-out GtkDirectionType type The focus was moved out of
the GtkNotebook widget in the
given direction.
page-added GtkWidget *child
guint page_num
A page was added to the
GtkNotebook widget. This sig-
nal was added in GTK+ 2.10.

page-removed GtkWidget *child
guint page_num
A page was removed from the
GtkNotebook widget. This sig-
nal was added in GTK+ 2.10.
page-reordered GtkWidget *child
guint page_num
The GtkNotebook widget pages
were reordered. This signal
was added in GTK+ 2.10.
select-page gboolean focus_moved A new page was selected for
the child widget. The call-
back function returns TRUE if
the signal was handled.
switch-page GtkNotebookPage *page
guint page_num
The notebook page was
changed to the given page.
Signal Name Description
destroy When the GtkObject widget has released all of its references, it will
be destroyed. This will result in finalization of the object when you
release all of the references.
7931.book Page 545 Wednesday, March 14, 2007 8:28 PM
546
APPENDIX B
■ GTK+ SIGNALS
Table B-39. GtkPaned Signals
Signal Name Additional Parameters Description
accept-position None Resizing of the pane was com-
pleted, and the user pressed

the Return key, Enter key, or
space bar. This signal will give
focus and activate the child
widget. The callback function
should return TRUE if the sig-
nal was handled.
cancel-position None Resizing the pane was
stopped, because the user
pressed the Escape key to
cancel the change. The call-
back function should return
TRUE if the signal was
handled.
cycle-child-focus gboolean reversed The user changed the child
focus by pressing F6 or
Shift+F6 while the GtkPaned
widget had focus. The call-
back function returns TRUE if
the signal was handled.
cycle-handle-focus gboolean reversed If the GtkPaned widget had
focus and the user presses
Tab, Ctrl+Tab, Shift+Tab, or
Ctrl+Shift+Tab, the signal is
emitted. The callback func-
tion should return TRUE if the
signal was handled.
move-handle GtkScrollType type The handle was moved, and
one of the following keys was
pressed while it was in focus:
Left, Right, Up, Down, Page

Up, Page Down, Home, or
End. The callback function
should return TRUE if the sig-
nal was handled.
toggle-handle-focus None The GtkPaned widget was
within focus, and F8 was
pressed to give or take away
focus from the handle. The
callback function should
return TRUE if the signal was
handled.
7931.book Page 546 Wednesday, March 14, 2007 8:28 PM
APPENDIX B ■ GTK+ SIGNALS
547
Table B-40. GtkPlug Signals
Table B-41. GtkPrinter Signals
Table B-42. GtkPrintJob Signals
Table B-43. GtkPrintOperation Signals
Signal Name Description
embedded The GtkPlug window was assigned to the socket window as its parent.
GtkPlug allows top-level widgets to be embedded into other processes.
Signal Name Additional Parameters Description
details-acquired gboolean success Detailed information about
the printer was requested
from the print backend.
Signal Name Description
status-changed The current status of the print job changed. You should use gtk_print_
job_get_status() to check the new status of the print job.
Signal Name Additional Parameters Description
begin-print GtkPrintContext *context The user just finished chang-

ing printer settings but
rendering has not yet begun.
create-custom-widget None The dialog was just dis-
played. You can return a
widget or a container widget
containing multiple widgets
from the callback function
so that it will be added as a
custom page to the dialog’s
GtkNotebook.
custom-widget-apply GtkWidget *widget Right before begin-print is
emitted, this signal is emit-
ted if a custom widget was
added in the create-custom-
widget signal handler.
Continued
7931.book Page 547 Wednesday, March 14, 2007 8:28 PM
548
APPENDIX B
■ GTK+ SIGNALS
Table B-43. Continued
Signal Name Additional Parameters Description
done GtkPrintOperationResult result Printing completed, and
you can now view the result.
You should use gtk_print_
operation_get_error() to
check the error message if
the result was GTK_PRINT_
OPERATION_RESULT_ERROR.
draw-page GtkPrintContext *context

gint page_num
Each page must be con-
verted into a Cairo context.
You can use this callback to
render a page manually.
end-print GtkPrintContext *context All of the pages were rendered.
paginate GtkPrintContext *context This signal is emitted after
begin-print but before page
rendering begins. It will con-
tinue to be emitted until
FALSE is returned or until it is
not handled. This allows you
to split the document into
pages in steps so that the
user interface is not notice-
ably blocked.
preview GtkPrintOperationPreview *preview
GtkPrintContext *context
GtkWindow *parent
The user requested a pre-
view of the document from
the main printing dialog. This
signal allows you to create
your own preview dialog. If
this signal is not handled, the
default handler will be used.
The callback function returns
TRUE if you are handling the
print preview.
request-page-setup GtkPrintContext *context

gint page_num
GtkPageSetup *setup
This signal is emitted for every
page, which gives you one last
chance to edit the setup of a
page before it is printed. Any
changes will be applied to
only the current page!
status-changed None The status of the print
operation changed. Possible
values are defined by the
GtkPrintStatus enumer-
ation, and the current
value can be retrieved with
gtk_print_operation_get_
status().
7931.book Page 548 Wednesday, March 14, 2007 8:28 PM
APPENDIX B ■ GTK+ SIGNALS
549
Table B-44. GtkRadioAction Signals
Table B-45. GtkRadioButton and GtkRadioMenuItem Signals
Table B-46. GtkRange Signals
Table B-47. GtkScale Signals
Signal Name Additional Parameters Description
changed GtkRadioAction *current The states of two radio but-
tons in a group were changed.
This signal is emitted on every
member of a radio group
when the selection is changed.
Signal Name Description

group-changed The radio button switched to a new group, or it was removed from a
radio group altogether.
Signal Name Additional Parameters Description
adjust-bounds gdouble value The bounds of a GtkRange
were altered by some type
of user action.
change-value GtkScrollType type
gdouble value
The current value of the range
was changed. You can pre-
vent the range from being
updated by returning TRUE,
but you will have to manually
round the displayed value to
the desired number of deci-
mal places.
move-slider GtkScrollType type The user pressed a keyboard
key such as Page Up, Page
Down, Home, End, or an
arrow key that caused the
slider to move.
value-changed None The range value was
changed. This can be
caused by user action or
a call within your code.
Signal Name Additional Parameters Description
format-value gdouble value A scale is about to be dis-
played, but GTK+ first gives
you an opportunity to cus-
tomize how it is displayed.

The callback function returns
a customized string display-
ing the value created by you.
7931.book Page 549 Wednesday, March 14, 2007 8:28 PM
550
APPENDIX B
■ GTK+ SIGNALS
Table B-48. GtkScrolledWindow Signals
Table B-49. GtkSocket Signals
Table B-50. GtkSpinButton Signals
Signal Name Additional Parameters Description
move-focus-out GtkDirectionType type The user moved focus from
the scrolled window by press-
ing Ctrl+Tab or Ctrl+Shift+Tab.
The given direction is always
either GTK_DIR_TAB_FORWARD or
GTK_DIR_TAB_BACKWARD.
scroll-child GtkScrollType type
gboolean horizontal
The child widget was scrolled
in one direction. This could
be caused by the mouse or
one of the following default
key bindings: Ctrl+Left,
Ctrl+Right, Ctrl+Up,
Ctrl+Down, Ctrl+Page Up,
Ctrl+Page Down, Page Up,
Page Down, Ctrl +Home,
Ctrl+End, Home, or End.
Signal Name Description

plug-added A client was successfully added to the socket.
plug-removed A client was removed from the socket. Usually, you will want to
destroy the GtkSocket widget, which is the default. To prevent this,
you can return TRUE from the callback function.
Signal Name Additional Parameters Description
change-value GtkScrollType type The displayed value of the
spin button was changed.
This was done by pressing
one of the following keyboard
bindings: Up, Down, Page Up,
Page Down, Ctrl+Page Up, or
Ctrl+Page Down.
input gpointer value The displayed value was
changed.
output None The displayed value of the
spin button was changed by
either setting a new value or
changing the digits property
of a realized widget. You
should return TRUE if you suc-
cessfully handle the signal so
that no further action is taken.
7931.book Page 550 Wednesday, March 14, 2007 8:28 PM
APPENDIX B ■ GTK+ SIGNALS
551
Table B-51. GtkStatusbar Signals
Table B-52. GtkStatusIcon Signals
value-changed None Any one of the properties
that require the spin button
value to be changed (e.g.,

value or digits) of the spin
button was changed.
wrapped None The spin button wrapped
from the maximum to the
minimum value or vice versa.
This signal was introduced in
GTK+ 2.10.
Signal Name Additional Parameters Description
text-popped guint context_id
gchar *message
The top message was
removed from the status
bar’s stack. The next mes-
sage will be displayed.
text-pushed guint context_id
gchar *message
A message was added to the
top of the status bar’s stack.
Signal Name Additional Parameters Description
activate None The status icon was acti-
vated. How the status icon
was activated is dependent
on the user’s platform. In any
case, you should take appro-
priate action.
popup-menu guint button
guint activate_time
The pop-up menu of the
status icon was shown. The
function parameters can

be passed to gtk_menu_
popup(). The pop-up menu
feature is not available
on every platform, so you
should always provide alter-
native functionality!
size-changed gint size The area available to the sta-
tus icon was changed. The
callback function returns
TRUE if you scaled the icon.
Otherwise, GTK+ will take
care of scaling for you.
Signal Name Additional Parameters Description
7931.book Page 551 Wednesday, March 14, 2007 8:28 PM
552
APPENDIX B
■ GTK+ SIGNALS
Table B-53. GtkTextBuffer Signals
Table B-54. GtkTextTag Signals
Signal Name Additional Parameters Description
apply-tag GtkTextTag *tag
GtkTextIter *start
GtkTextIter *end
A GtkTextTag widget was
applied to a section of the
text buffer.
begin-user-action None The user began some type of
action on the text buffer.
changed None The text buffer was changed
in some way, which resulted

in a change of visible or invis-
ible text, images, or widgets.
delete-range GtkTextIter *start
GtkTextIter *end
Text was deleted from the
text buffer.
end-user-action None Some type of user action on
the text buffer ended.
insert-child-anchor GtkTextIter *location
GtkTextChildAnchor *anchor
An anchor was inserted,
which allows the text buffer
to contain other widgets.
insert-pixbuf GtkTextIter *location
GdkPixbuf *pixbuf
A GdkPixbuf object was
inserted into the text buffer.
insert-text GtkTextIter *location
gchar *new_text
gint text_length
Text was inserted into the
text buffer.
mark-deleted GtkTextMark *mark A GtkTextMark object was
deleted from the text buffer.
mark-set GtkTextIter *location
GtkTextMark *mark
A GtkTextMark object was
added to the text buffer.
modified-changed None The text buffer was set as
modified or unmodified.

remove-tag GtkTextTag *tag
GtkTextIter *start
GtkTextIter *end
A tag was removed from the
text buffer between the given
iterators.
Signal Name Additional Parameters Description
event GObject *object
GdkEvent *event
GtkTextIter *location
An event occurred that was
within the range of the text
encompassed by GtkTextTag.
7931.book Page 552 Wednesday, March 14, 2007 8:28 PM
APPENDIX B ■ GTK+ SIGNALS
553
Table B-55. GtkTextTagTable Signals
Table B-56. GtkTextView Signals
Signal Name Additional Parameters Description
tag-added GtkTextTag *tag A GtkTextTag object was
added to the tag table.
tag-changed GtkTextTag *tag
gboolean size_changed
A property of a tag contained
by the tag table was changed.
The size of the displayed text
can be changed by other prop-
erties besides the size, such as
weight and font family.
tag-removed GtkTextTag *tag A GtkTextTag object was

removed from the tag table.
Signal Name Additional Parameters Description
backspace None One character was deleted
from the document from
behind the cursor.
copy-clipboard None Selected text was copied to
the clipboard.
cut-clipboard None Selected text was copied to
the clipboard and removed
from the document.
delete-from-cursor GtkDeleteType type
gint length
Text was deleted from
around the cursor.
insert-at-cursor gchar *text Text was inserted at the cur-
rent cursor position.
move-cursor GtkMovementStep step
gint num_steps
gboolean extended
The cursor was moved to a
new position, possibly extend-
ing the current selection.
move-focus GtkDirectionType type Focus has been moved in the
given direction.
move-viewport GtkScrollStep step
gint num_steps
Some type of scrolling
occurred, which is described
by the given step.
paste-clipboard None Text from the clipboard was

inserted into the document.
Continued
7931.book Page 553 Wednesday, March 14, 2007 8:28 PM
554
APPENDIX B
■ GTK+ SIGNALS
Table B-56. Continued
Table B-57. GtkToggleAction, GtkToggleButton, and GtkToggleToolButton Signals
Table B-58. GtkToolbar Signals
Signal Name Additional Parameters Description
populate-popup GtkMenu *menu The pop-up menu was
shown and is available for
editing.
select-all gboolean selected All of the text in the document
was selected or deselected.
set-anchor None An anchor was added to the
text view.
set-scroll-adjustments GtkAdjustment *hadj
GtkAdjustment *vadj
The adjustments of the text
view were set.
toggle-overwrite None The overwrite key was tog-
gled on or off.
Signal Name Description
toggled The state of the toggle was changed. You should connect to this
signal if you want to take some type of action when the toggle is
activated or deactivated.
Signal Name Additional Parameters Description
focus-home-or-end gboolean focus_home This signal is used internally
by GTK+ to move to the first

or last element in the toolbar
and cannot be used in appli-
cation code. The callback
function returns TRUE if the
signal was handled.
move-focus GtkDirectionType type This signal is used internally
by GTK+ to move the focused
item and cannot be used in
application code.
orientation-changed GtkOrientation dir The orientation of the toolbar
was changed to horizontal or
vertical.
7931.book Page 554 Wednesday, March 14, 2007 8:28 PM
APPENDIX B ■ GTK+ SIGNALS
555
Table B-59. GtkToolButton Signals
Table B-60. GtkToolItem Signals
popup-context-menu gint x_position
gint y_position
gint button
The user right-clicked the
toolbar or pressed a key bind-
ing that causes a pop-up
menu to be displayed. You
can use this to display a cus-
tom context menu for the
toolbar. You should return
TRUE if the signal was handled.
style-changed GtkToolbarStyle style The style of the toolbar was
changed.

Signal Name Description
changed The tool button was clicked with the mouse. This signal can also be
emitted if the tool button was activated with a keyboard binding.
Signal Name Additional Parameters Description
create-menu-proxy None The toolbar needs to know
whether the item should
appear in an overflow menu.
To handle this signal, you
should either call gtk_tool_
item_set_proxy_menu_item()
or return FALSE to prevent it
from appearing in the over-
flow menu. You should
return TRUE if the signal was
handled.
set-tooltip GtkTooltips *tooltips
gchar *tip_text
gchar *tip_private
The tooltip of an item
was changed to the given
configuration.
toolbar-reconfigured None Some property of the tool
item’s parent was changed
that requires the child to be
changed. This is caused by a
change in the orientation,
style, icon size, or relief style
of the toolbar.
Signal Name Additional Parameters Description
7931.book Page 555 Wednesday, March 14, 2007 8:28 PM

556
APPENDIX B
■ GTK+ SIGNALS
Table B-61. GtkTreeModel Signals
Table B-62. GtkTreeSelection Signals
Table B-63. GtkTreeSortable Signals
Signal Name Additional Parameters Description
row-changed GtkTreePath *path
GtkTreeIter *iter
A row in the tree model at the
given location was changed.
row-deleted GtkTreePath *path A row was removed from
the tree model at the given
location.
row-has-child-toggled GtkTreePath *path
GtkTreeIter *iter
A row at the given location
was given its first child, or
its last remaining child was
removed.
row-inserted GtkTreePath *path
GtkTreeIter *iter
A row was added to the tree
model. This signal is called
immediately after the row is
added, so it may not yet con-
tain any data.
rows-reordered GtkTreePath *path
GtkTreeIter *iter
gpointer row_nums

Rows within a tree model
were reordered by some
method besides drag and
drop. The callback function
receives an array of reordered
row numbers.
Signal Name Description
changed The selection may have been changed. This signal is not always
reliable, because it is only emitted once when multiple rows are
selected with the Shift key and can be emitted when nothing at all
has occurred. You should build error protection into callback func-
tions for this signal.
Signal Name Description
sort-column-changed The sort column is the column that will be used to sort all of the rows
within a GtkTreeSortable model. This signal is emitted when the
chosen sort column is changed.
7931.book Page 556 Wednesday, March 14, 2007 8:28 PM
APPENDIX B ■ GTK+ SIGNALS
557
Table B-64. GtkTreeView Signals
Signal Name Additional Parameters Description
columns-changed None Columns were added or
removed from the tree view,
which caused the number
of columns to change.
cursor-changed None The position of the cursor
within a cell with focus
changed.
expand-collapse-
cursor-row

gboolean logical
gboolean expanded
expand_children
A row located at the cursor
position needs to expanded
or collapsed. You should
return TRUE if the signal is
handled.
move-cursor GtkMovementStep step
gint num_steps
The cursor was moved by
using one of the following
key bindings: Right, Left, Up,
Down, Page Up, Page Down,
Home, or End. You should
return TRUE if the signal was
handled.
row-activated GtkTreePath *path
GtkTreeViewColumn *column
The user double-clicked a
row, or gtk_tree_view_row_
activated() was called. It can
also be emitted with the fol-
lowing key bindings: Space,
Shift+space bar, Return, or
Enter.
row-collapsed GtkTreeIter *iter
GtkTreePath *path
The child nodes of the given
row were hidden.

row-expanded GtkTreeIter *iter
GtkTreePath *path
The child nodes of the given
row were shown.
select-all None All of the rows within the tree
view were selected. This can
be done by pressing Ctrl+A or
Ctrl+/.
select-cursor-parent None The user pressed the Back-
space key while the row had
cursor focus. The callback
function should return TRUE if
the signal was handled.
Continued
7931.book Page 557 Wednesday, March 14, 2007 8:28 PM
558
APPENDIX B
■ GTK+ SIGNALS
Table B-64. Continued
Signal Name Additional Parameters Description
select-cursor-row gboolean editing A noneditable row was
selected by pressing one of
the following key bindings:
space bar, Shift+space bar,
Return, or Enter. The callback
function should return TRUE if
the signal was handled.
set-scroll-adjustments GtkAdjustment *hadj
GtkAdjustment *vadj
Horizontal and vertical scroll

adjustments were set for the
tree view. The callback func-
tion should return TRUE if the
signal was handled.
start-interactive-
search
None The user pressed Crtl+F while
the tree view had focus. You
should return TRUE if the sig-
nal was handled.
test-collapse-row GtkTreeIter *iter
GtkTreePath *path
A row is about to be collapsed.
The callback function should
return TRUE to go forward with
the collapse.
test-expand-row GtkTreeIter *iter
GtkTreePath *path
A row is about to be expanded.
The callback function should
return TRUE to go forward with
the expansion.
toggle-cursor-row None The user pressed Ctrl+space
bar while a row had focus.
You should return TRUE if the
signal was handled.
unselect-all None All of the rows in a tree view
were deselected by pressing
Shift+Ctrl+A or Shift+Ctrl+/.
You should return TRUE if the

signal was handled.
7931.book Page 558 Wednesday, March 14, 2007 8:28 PM
APPENDIX B ■ GTK+ SIGNALS
559
Table B-65. GtkTreeViewColumn Signals
Table B-66. GtkUIManager Signals
Table B-67. GtkViewport Signals
Signal Name Description
clicked The user pressed the tree view column’s header button. This usually
causes the tree view’s rows to be sorted according to that column in
views that support sorting.
Signal Name Additional Parameters Description
actions-changed None A set of actions within the UI
manager were changed.
add-widget GtkWidget *widget A menu bar or toolbar was
generated. This signal is not
emitted for pop-up menus,
so you will have to use gtk_
ui_manager_get_widget() to
retrieve those.
connect-proxy GtkAction *action
GtkWidget *proxy
A proxy was connected to an
action within the group. You
can use this signal for cus-
tomizations that are used by
many actions.
disconnect-proxy GtkAction *action
GtkWidget *proxy
A proxy was connected to an

action within the group.
post-activate GtkAction *action An action was just activated.
This signal can be used to
retrieve notice of activation
of all actions.
pre-activate GtkAction *action An action is about to be acti-
vated. This signal can be used
to retrieve notice of activa-
tion of all actions.
Signal Name Additional Parameters Description
set-scroll-adjustments GtkAdjustment *hadj
GtkAdjustment *vadj
The adjustments for the
viewport were changed.
7931.book Page 559 Wednesday, March 14, 2007 8:28 PM
560
APPENDIX B
■ GTK+ SIGNALS
Table B-68. GtkWidget Signals with Events Removed
Signal Name Additional Parameters Description
accel-closures-changed None An accelerator was added or
removed from the widget’s
accelerator group. This sig-
nal is also emitted when an
accelerator path is set up.
can-activate-accel guint signal_id You can use this signal to
override the default handler
for whether an accelerator
can be activated. You should
return TRUE if the signal can

be activated.
child-notify GParamSpec *pspec A child property was changed
for the widget. This signal
can be used to monitor a sig-
nal property.
composited-changed None The composited status of the
widget was changed; com-
posited is a property that
determines whether the wid-
get’s alpha channel will be
honored.
direction-changed GtkTextDirection dir The direction of the text within
the widget was changed. This
is usually initiated by a call to
gtk_widget_set_direction().
drag-begin GdkDragContext *context A drag action began. This
signal is emitted on the drag
source. You can use this sig-
nal to set up a custom icon to
display when dragging.
drag-data-delete GdkDragContext *context A drag action was success-
fully completed. This signal is
used to delete the data that
was being dragged when the
action is completed.
drag-data-get GdkDragContext *context
GtkSelectionData *data
guint info
guint timestamp
The drop site requested the

data that was dragged.
drag-data-received GdkDragContext *context
gint x_position
gint y_position
GtkSelectionData *data
guint int
guint timestamp
The drag data was received
by the drop site.
7931.book Page 560 Wednesday, March 14, 2007 8:28 PM
APPENDIX B ■ GTK+ SIGNALS
561
drag-drop GdkDragContext *context
gint x_position
gint y_position
guint timestamp
The user dropped data onto a
widget. You must determine
whether the cursor position
is within the accepted drop
region. You should return
TRUE if the drop is acceptable.
drag-end GdkDragContext *context A drag action was completed,
which can be used to undo
actions performed in the
drag-begin callback.
drag-leave GdkDragContext *context
guint timestamp
The cursor left the proximity
of the drop site. This signal

can be used to undo actions
performed in the drag-motion
callback.
drag-motion GdkDragContext *context
gint x_position
gint y_position
guint timestamp
The cursor was moved over
the drop site during a drag.
You should return TRUE if the
cursor is within an accept-
able drop area.
focus GtkDirectionType type The widget received focus.
You should return TRUE if the
signal was handled.
grab-focus None The widget forced focus on
itself by calling gtk_widget_
grab_focus(). This signal can
also be initiated with mne-
monic accelerators.
grab-notify gboolean was_grabbed The widget became shad-
owed because of an explicit
call to gtk_grab_add() on
another widget, or it became
unshadowed because of a
removed grab.
hide None The widget was hidden from
the user’s view. The user
interface will be redrawn to
accommodate for the miss-

ing widget.
hierarchy-changed GtkWidget *toplevel The widget is considered to
be anchored when its top-
level ancestor is a GtkWindow
widget. This signal is emitted
when the child becomes
anchored or unanchored.
Continued
Signal Name Additional Parameters Description
7931.book Page 561 Wednesday, March 14, 2007 8:28 PM
562
APPENDIX B
■ GTK+ SIGNALS
Table B-68. Continued
Signal Name Additional Parameters Description
map None The widget requested
to be mapped. This can
be initiated by calling
gtk_widget_show() or
gtk_widget_map().
mnemonic-activate gboolean shift_focus A mnemonic accelerator was
used to activate the widget.
parent-set GtkObject *old_parent The parent widget was
changed.
popup-menu None The user requested a pop-up
menu to be shown. This call-
back function returns TRUE if
it was handled.
realize None The widget requested to be
realized because of a call to

gtk_widget_realize(). This is
not usually explicitly called
by your code unless you are
creating your own custom
widget.
screen-changed GdkScreen *screen The widget was moved to a
new screen.
selection-get GtkSelectionData *data
guint info
guint timestamp
Selection data was requested
from the widget.
selection-received GtkSelectionData *data
guint timestamp
The owner of a selection
responded to a request for
selection data for the widget.
show None The widget was set as visible.
The user interface will be
redrawn to accommodate the
newly visible widget.
show-help GtkWidgetHelpType type The user requested help with
the widget by pressing Ctrl+F1.
Help types are defined by
GtkWidgetHelpType, which is
composed of GTK_WIDGET_
HELP_TOOLTIP and GTK_WIDGET_
HELP_WHATS_THIS.
size-allocate GtkAllocation *alloc The widget was given a new
size allocation.

size-request GtkRequisition *req The widget requested a new
size by using gtk_widget_
set_size_request().
7931.book Page 562 Wednesday, March 14, 2007 8:28 PM
APPENDIX B ■ GTK+ SIGNALS
563
Table B-69. GtkWindow Signals
state-changed GtkStateType state The current state of the wid-
get changed to the given state.
style-set GtkStyle *prev_style The widget’s style was
modified. This is caused
by changing the whole style
or by changing specific
elements of the style.
unmap None The widget requested to be
unmapped. This can be initi-
ated by calling gtk_widget_
unmap().
unrealize None The widget requested to be
unrealized. This will cause all
of its associated resources
and the resources of any
child widgets to be freed.
Signal Name Additional Parameters Description
activate-default None The default widget of the
window was activated.
This is usually because the
user pressed the Return or
Enter key.
activate-focus None The child widget of the

window that has focus was
activated. This is usually
because the user pressed
the space bar.
frame-event GdkEvent *event An event other than key-
press-event, key-release-
event, or a change in focus
was received on the win-
dow’s frame.
keys-changed None A mnemonic accelerator was
added, removed, or changed
within the window. This can
also be caused by setting a
mnemonic modifier.
move-focus GtkDirectionType type The focus was changed
within the child widgets of
the window. This usually
happens when the user
presses one of the following
key bindings: Tab, Shift+Tab,
Up, Down, Left, or Right.
set-focus GtkWidget *widget The focus was changed to a
different child in the window.
Signal Name Additional Parameters Description
7931.book Page 563 Wednesday, March 14, 2007 8:28 PM
7931.book Page 564 Wednesday, March 14, 2007 8:28 PM
565
■ ■ ■
APPENDIX C
GTK+ Styles

GTK+ provides many ways to customize the styles of widgets. Most customization of widget
styles is done through style properties and resource (RC) files, which were covered in the
Widget Styles section of Chapter 4.
In addition to the information in Chapter 4, this appendix provides a reference to default
RC file elements that can be applied to any widget, the Pango Text Markup Language, and
GtkTextTag styles.
Default RC File Styles
Resource files are introduced in Chapter 4, but this section can be used as a reference of the
default styles supported by every widget.
Along with the background, foreground, base, and text color styles, you need to specify a
widget state for which many styles will be attributed. States are also required when specifying
stock icons for some functions. The five widget states follow:
• NORMAL: The state of the widget during normal operation.
• ACTIVE: The state of an active widget, such as when a toggle is depressed.
• PRELIGHT: The mouse pointer is over the widget, which will respond to button clicks.
• SELECTED: The widget or widget text has been selected.
• INSENSITIVE: The widget is deactivated and will not respond to the user.
Colors can be specified in multiple formats. These may include hexadecimal formats like
#RGB, #RRGGBB, #RRRGGGBBB, and #RRRRGGGGBBBB where R, G, and B are hexadecimal digits represent-
ing red, green, and blue values respectively. You can also specify colors as { R, G, B } where the
values are given as integers between 0 and 65,535 or floating point values between 0.0 and 1.0.
Table C-1 gives a complete list of the default RC file styles that are supported as of GTK+ 2.10.
Some of the style descriptions also include examples of how they are implemented.
7931.book Page 565 Wednesday, March 14, 2007 8:28 PM
566
APPENDIX C
■ GTK+ STYLES
Table C-1. RC File Styles
Style Description
base[state] Set the background color of widgets that allow text to be edited (e.g.,

GtkEntry) in one of the five states.
Example: base[ACTIVE] = { 0.5, 0.3, 1.0 }
bg[state] Set the background color for most widgets in one of the five states.
Example: bg[NORMAL] = "#036"
bg_pixmap[state] Set an image to use as the background for the widget in one of the five
states. If the image file is relative, it will be searched for in one of the
paths specified by pixmap_path.
Example: bg_pixmap[SELECTED] = "image.xpm"
class::property Set a style property for the specific widget class. For example, GtkWidget
properties include cursor-aspect-ratio, cursor-color, and draw-border.
Example: class::cursor-aspect-ratio = 0.1
color["color_name"] As of GTK+ 2.10, you can define your own colors. A color is referred to as
@color_name. More information can be found immediately after this table.
engine Theme engines allow you to define your own widget styles from an RC
file. More information about using engines can be found in the GTK+
documentation.
fg Set the foreground color for most widgets in one of the five states.
Example: fg[PRELIGHT] = "#123456"
font_name The font and fontset styles are ignored as of GTK+ 2.10 in favor of this
style. You should specify this font name as you would to a Pango Font
Description string.
Example: font_name = "Sans Bold 12"
stock["stockid"] Define a new stock item that can be used by the application. The stock
item accepts the image filename, text direction (left to right or right to
left), widget state, and size. Sizes include gtk-menu, gtk-small-toolbar,
gtk-large-toolbar, gtk-button, and gtk-dialog. The asterisk (*) charac-
ter can be used as a wildcard for any of the last three parameters.
Example: stock["myitem"] = { "myitem.png", LTR, NORMAL, "gtk-
menu" }
text[state] Set the text color for widgets such as GtkEntry. Example: fg[PRELIGHT] =

{ 0, 65535, 0 }
xthickness Set horizontal padding for various values in GTK+. This value is speci-
fied as an integer.
ythickness Set vertical padding for various values in GTK+. This value is specified as
an integer.
7931.book Page 566 Wednesday, March 14, 2007 8:28 PM
APPENDIX C ■ GTK+ STYLES
567
As of GTK+ 2.10, you can define your own colors. Four functions are provided that allow
you to alter existing colors. Each of the following methods accepts any of the supported color
expressions:
• shade (factor, color): Make the specified color lighter or darker. The factor can be a
floating point number, where 1.0 leaves the color as it is. A smaller factor will darken the
color, while larger factors will lighten it.
• darker (color): This expression is equivalent to shade (0.7, color).
• lighter (color): This expression is equivalent to shade (1.3, color).
• mix (factor, color1, color2): Create a new color by mixing the two colors, where a fac-
tor of 0.0 outputs color2 and a factor of 1.0 outputs color1.
These methods can also be used together to create colors. To help you understand, a few
examples of color creation expressions follow:
color["blackwhite"] = mix (0.5, "#000000", "#FFFFFF")
color["darker"] = shade (0.5, @blackwhite)
color["multiple"] = shade (1.4, mix (0.1, "#369", { 0, 1.0, 0 }))
Pango Text Markup Language
The Pango Text Markup Language allows you to change the styles of text with XML tags in some
widgets, such as
GtkLabel.
The
<span> tag can be used with many attributes to define the styles of text. For example,
<span font_desc='Sans Bold 12'>Text</span> sets the text between the tags with the specified

font. Table C-2 gives a list of supported attributes for the
<span> tag.
Table C-2. Span Tag Attributes
Attribute Description
background A value that describes the background color. Possible values include the
hexadecimal RGB value in the form #RRGGBB or a supported color name
like blue.
face A font family name such as Sans or Monospace. This tag is the same thing
as font_family.
Continued
7931.book Page 567 Wednesday, March 14, 2007 8:28 PM
568
APPENDIX C
■ GTK+ STYLES
Table C-2. Continued
Attribute Description
fallback When enabled, which is the default, the system will try to find the font
that most closely matches the specified font. You should not turn this
off, but if it is necessary, you should use a value of false.
font_desc A font description string that would be supported by PangoFontDescription
such as “Sans Bold 12”.
font_family A font family name such as Sans or Monospace. This tag is the same thing
as face.
foreground A value that describes the foreground color. Possible values include the
hexadecimal RGB value in the form #RRGGBB or a supported color name
like blue.
lang A language code that states what language the text string is in.
rise This value allows you to create superscripts and subscripts by specify-
ing a vertical displacement, in 10,000ths of an em unit. Negative values
create a subscript, and positive values create a superscript.

size The size of the font, in 1,024ths of a point. You can also use xx-small,
x-small, small, medium, large, x-large, xx-large, larger, or smaller.
Absolute sizes are usually easier to specify by using font_desc.
stretch How much the text will be stretched. Possible values include
ultracondensed, extracondensed, condensed, semicondensed, normal,
semiexpanded, expanded, extraexpanded, and ultraexpanded.
strikethrough You should specify true to place a single line through the text or false to
turn it off.
strikethrough_color A value that describes the strikethrough line color. Possible values
include the hexadecimal RGB value in the form #RRGGBB or a supported
color name like blue.
style The italicized style of the text. Possible values include normal, oblique
,
and italic.
underline A value describing how the text will be underlined. Possible values
include single, double, low, and none.
underline_color A value that describes the underline color. Possible values include the
hexadecimal RGB value in the form #RRGGBB or a supported color name
like blue.
variant A value of normal or smallcaps, which allows text to be rendered as all
capital letters.
weight The weight of the text. Possible values include ultralight, light, normal,
bold, ultrabold, heavy, and a numeric weight value.
7931.book Page 568 Wednesday, March 14, 2007 8:28 PM