Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtktoolbar.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkToolbar
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 create bars of buttons and other widgets.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A toolbar is created with a call to gtk_toolbar_new().
  10 </para>
  11 <para>
  12 Buttons with text and/or images are added with gtk_toolbar_append_item(), gtk_toolbar_prepend_item(), and gtk_toolbar_insert_item().
  13 </para>
  14 <para>
  15 Any of #GtkToggleButton, #GtkRadioButton, or an arbitrary widget can be added to the toolbar with gtk_toolbar_append_element(), gtk_toolbar_prepend_element(), and gtk_toolbar_insert_element().
  16 </para>
  17 <para>
  18 Widgets can be visibly grouped by adding gaps between widgets using gtk_toolbar_append_space(), gtk_toolbar_prepend_space(), and gtk_toolbar_insert_space().
  19 </para>
  20
  21 <!-- ##### SECTION See_Also ##### -->
  22 <para>
  23 <variablelist>
  24 <varlistentry>
  25 <term>#GtkToolTips</term>
  26 <listitem><para>Change the properties of a #GtkToolbar's #GtkTooltips.</para></listitem>
  27 </varlistentry>
  28 <varlistentry>
  29 <term>#GtkTipsQuery</term>
  30 <listitem><para>Make use of the private tips of toolbar elements.</para></listitem>
  31 </varlistentry>
  32 </variablelist>
  33 </para>
  34
  35 <!-- ##### STRUCT GtkToolbar ##### -->
  36 <para>
  37 <structfield>num_children</structfield> is an integer specifying how many toolbar items the #GtkToolbar contains. <structfield>children</structfield> is a #GList of the child widgets of the toolbar.
  38 </para>
  39 <para>
  40 <structfield>orientation</structfield>
  41 </para>
  42
  43
  44 <!-- ##### ENUM GtkToolbarChildType ##### -->
  45 <para>
  46 #GtkToolbarChildType is used to set the type of new elements that are added
  47 to a #GtkToolbar.
  48 </para>
  49
  50 @GTK_TOOLBAR_CHILD_SPACE: a space in the style of the toolbar's #GtkToolbarSpaceStyle.
  51 @GTK_TOOLBAR_CHILD_BUTTON: a #GtkButton.
  52 @GTK_TOOLBAR_CHILD_TOGGLEBUTTON: a #GtkToggleButton.
  53 @GTK_TOOLBAR_CHILD_RADIOBUTTON: a #GtkRadioButton.
  54 @GTK_TOOLBAR_CHILD_WIDGET: a standard #GtkWidget.
  55
  56 <!-- ##### ENUM GtkToolbarSpaceStyle ##### -->
  57 <para>
  58
  59 </para>
  60
  61 @GTK_TOOLBAR_SPACE_EMPTY:
  62 @GTK_TOOLBAR_SPACE_LINE:
  63
  64 <!-- ##### STRUCT GtkToolbarChild ##### -->
  65 <para>
  66
  67 </para>
  68
  69 @type:
  70 @widget:
  71 @icon:
  72 @label:
  73
  74 <!-- ##### FUNCTION gtk_toolbar_new ##### -->
  75 <para>
  76 Creates a new toolbar.
  77 </para>
  78
  79 @Returns: the newly-created toolbar.
  80
  81
  82 <!-- ##### FUNCTION gtk_toolbar_append_item ##### -->
  83 <para>
  84 Adds a new button to the end (right or bottom edges) of the given toolbar.
  85 </para>
  86
  87 @toolbar: a #GtkToolbar.
  88 @text: give your toolbar button a label.
  89 @tooltip_text: a string that appears when the user holds the mouse over this item.
  90 @tooltip_private_text: use with #GtkTipsQuery.
  91 @icon: a #GtkWidget that should be used as the button's icon.
  92 @callback: the function to be executed when the button is pressed.
  93 @user_data: a pointer to any data you wish to be passed to the callback.
  94 @Returns: the new toolbar item as a #GtkWidget.
  95
  96
  97 <!-- ##### FUNCTION gtk_toolbar_prepend_item ##### -->
  98 <para>
  99 Adds a new button to the beginning (top or left edges) of the given toolbar.
 100 </para>
 101
 102 @toolbar: a #GtkToolbar.
 103 @text: give your toolbar button a label.
 104 @tooltip_text: a string that appears when the user holds the mouse over this item.
 105 @tooltip_private_text: use with #GtkTipsQuery.
 106 @icon: a #GtkWidget that should be used as the button's icon.
 107 @callback: the function to be executed when the button is pressed.
 108 @user_data: a pointer to any data you wish to be passed to the callback.
 109 @Returns: the new toolbar item as a #GtkWidget.
 110
 111
 112 <!-- ##### FUNCTION gtk_toolbar_insert_item ##### -->
 113 <para>
 114 Inserts a new item into the toolbar. You must specify the position in the toolbar where it will be inserted.
 115 </para>
 116
 117 @toolbar: a #GtkToolbar.
 118 @text: give your toolbar button a label.
 119 @tooltip_text: a string that appears when the user holds the mouse over this item.
 120 @tooltip_private_text: use with #GtkTipsQuery.
 121 @icon: a #GtkWidget that should be used as the button's icon.
 122 @callback: the function to be executed when the button is pressed.
 123 @user_data: a pointer to any data you wish to be passed to the callback.
 124 @position: the number of widgets to insert this item after.
 125 @Returns: the new toolbar item as a #GtkWidget.
 126
 127
 128 <!-- ##### FUNCTION gtk_toolbar_append_space ##### -->
 129 <para>
 130 Adds a new space to the end of the toolbar.
 131 </para>
 132
 133 @toolbar: a #GtkToolbar.
 134
 135
 136 <!-- ##### FUNCTION gtk_toolbar_prepend_space ##### -->
 137 <para>
 138 Adds a new space to the beginning of the toolbar.
 139 </para>
 140
 141 @toolbar: a #GtkToolbar.
 142
 143
 144 <!-- ##### FUNCTION gtk_toolbar_insert_space ##### -->
 145 <para>
 146 Inserts a new space in the toolbar at the specified position.
 147 </para>
 148
 149 @toolbar: a #GtkToolbar
 150 @position: the number of widgets after which a space should be inserted.
 151
 152
 153 <!-- ##### FUNCTION gtk_toolbar_append_element ##### -->
 154 <para>
 155 Adds a new element to the end of a toolbar.
 156 </para>
 157 <para>
 158 If @type == %GTK_TOOLBAR_CHILD_WIDGET, @widget is used as the new element.
 159 If @type == %GTK_TOOLBAR_CHILD_RADIOBUTTON, @widget is used to determine
 160 the radio group for the new element. In all other cases, @widget must
 161 be %NULL.
 162 </para>
 163
 164 @toolbar: a #GtkToolbar.
 165 @type: a value of type #GtkToolbarChildType that determines what @widget will be.
 166 @widget: a #GtkWidget, or %NULL.
 167 @text: the element's label.
 168 @tooltip_text: the element's tooltip.
 169 @tooltip_private_text: used for context-sensitive help about this toolbar element.
 170 @icon: a #GtkWidget that provides pictorial representation of the element's function.
 171 @callback: the function to be executed when the button is pressed.
 172 @user_data: any data you wish to pass to the callback.
 173 @Returns: the new toolbar element as a #GtkWidget.
 174
 175
 176 <!-- ##### FUNCTION gtk_toolbar_prepend_element ##### -->
 177 <para>
 178 Adds a new element to the beginning of a toolbar.
 179 </para>
 180 <para>
 181 If @type == %GTK_TOOLBAR_CHILD_WIDGET, @widget is used as the new element.
 182 If @type == %GTK_TOOLBAR_CHILD_RADIOBUTTON, @widget is used to determine
 183 the radio group for the new element. In all other cases, @widget must
 184 be %NULL.
 185 </para>
 186
 187 @toolbar: a #GtkToolbar.
 188 @type: a value of type #GtkToolbarChildType that determines what @widget will be.
 189 @widget: a #GtkWidget, or %NULL
 190 @text: the element's label.
 191 @tooltip_text: the element's tooltip.
 192 @tooltip_private_text: used for context-sensitive help about this toolbar element.
 193 @icon: a #GtkWidget that provides pictorial representation of the element's function.
 194 @callback: the function to be executed when the button is pressed.
 195 @user_data: any data you wish to pass to the callback.
 196 @Returns: the new toolbar element as a #GtkWidget.
 197
 198
 199 <!-- ##### FUNCTION gtk_toolbar_insert_element ##### -->
 200 <para>
 201
 202 </para>
 203
 204 @toolbar:
 205 @type:
 206 @widget:
 207 @text:
 208 @tooltip_text:
 209 @tooltip_private_text:
 210 @icon:
 211 @callback:
 212 @user_data:
 213 @position:
 214 @Returns:
 215
 216
 217 <!-- ##### FUNCTION gtk_toolbar_append_widget ##### -->
 218 <para>
 219
 220 </para>
 221
 222 @toolbar:
 223 @widget:
 224 @tooltip_text:
 225 @tooltip_private_text:
 226
 227
 228 <!-- ##### FUNCTION gtk_toolbar_prepend_widget ##### -->
 229 <para>
 230
 231 </para>
 232
 233 @toolbar:
 234 @widget:
 235 @tooltip_text:
 236 @tooltip_private_text:
 237
 238
 239 <!-- ##### FUNCTION gtk_toolbar_insert_widget ##### -->
 240 <para>
 241
 242 </para>
 243
 244 @toolbar:
 245 @widget:
 246 @tooltip_text:
 247 @tooltip_private_text:
 248 @position:
 249
 250
 251 <!-- ##### FUNCTION gtk_toolbar_set_orientation ##### -->
 252 <para>
 253 Sets whether a toolbar should appear horizontally or vertically.
 254 </para>
 255
 256 @toolbar: a #GtkToolbar.
 257 @orientation: a new #GtkOrientation.
 258
 259
 260 <!-- ##### FUNCTION gtk_toolbar_set_style ##### -->
 261 <para>
 262 Alters the view of @toolbar to display either icons only, text only, or both.
 263 </para>
 264
 265 @toolbar: a #GtkToolbar.
 266 @style: the new style for @toolbar.
 267
 268
 269 <!-- ##### FUNCTION gtk_toolbar_set_tooltips ##### -->
 270 <para>
 271 Sets if the tooltips of a toolbar should be active or not.
 272 </para>
 273
 274 @toolbar: a #GtkToolbar.
 275 @enable: set to %FALSE to disable the tooltips, or %TRUE to enable them.
 276
 277
 278 <!-- ##### FUNCTION gtk_toolbar_insert_stock ##### -->
 279 <para>
 280
 281 </para>
 282
 283 @toolbar:
 284 @stock_id:
 285 @tooltip_text:
 286 @tooltip_private_text:
 287 @callback:
 288 @user_data:
 289 @position:
 290 @Returns:
 291
 292
 293 <!-- ##### FUNCTION gtk_toolbar_set_icon_size ##### -->
 294 <para>
 295
 296 </para>
 297
 298 @toolbar:
 299 @icon_size:
 300
 301
 302 <!-- ##### FUNCTION gtk_toolbar_get_icon_size ##### -->
 303 <para>
 304
 305 </para>
 306
 307 @toolbar:
 308 @Returns:
 309
 310
 311 <!-- ##### FUNCTION gtk_toolbar_get_orientation ##### -->
 312 <para>
 313
 314 </para>
 315
 316 @toolbar:
 317 @Returns:
 318
 319
 320 <!-- ##### FUNCTION gtk_toolbar_get_style ##### -->
 321 <para>
 322
 323 </para>
 324
 325 @toolbar:
 326 @Returns:
 327
 328
 329 <!-- ##### FUNCTION gtk_toolbar_get_tooltips ##### -->
 330 <para>
 331
 332 </para>
 333
 334 @toolbar:
 335 @Returns:
 336
 337
 338 <!-- ##### FUNCTION gtk_toolbar_remove_space ##### -->
 339 <para>
 340
 341 </para>
 342
 343 @toolbar:
 344 @position:
 345
 346
 347 <!-- ##### FUNCTION gtk_toolbar_unset_icon_size ##### -->
 348 <para>
 349
 350 </para>
 351
 352 @toolbar:
 353
 354
 355 <!-- ##### FUNCTION gtk_toolbar_unset_style ##### -->
 356 <para>
 357
 358 </para>
 359
 360 @toolbar:
 361
 362
 363 <!-- ##### SIGNAL GtkToolbar::orientation-changed ##### -->
 364 <para>
 365 Should be used if you wish to perform an action when the orientation of a toolbar is changed.
 366 </para>
 367
 368 @toolbar: the object which received the signal.
 369 @orientation: the new #GtkOrientation of the toolbar.
 370
 371 <!-- ##### SIGNAL GtkToolbar::style-changed ##### -->
 372 <para>
 373 Should be used if you wish to perform an action when ever the style of a toolbar is adjusted. For example, this would be a useful signal to connect to if you want to display more items on the toolbar when it is in icon-only mode; each item takes less space on the bar.
 374 </para>
 375
 376 @toolbar: the object which received the signal.
 377 @style: the new #GtkToolbarStyle of @toolbar.
 378
 379 <!-- ##### ARG GtkToolbar:orientation ##### -->
 380 <para>
 381
 382 </para>
 383
 384 <!-- ##### ARG GtkToolbar:toolbar-style ##### -->
 385 <para>
 386
 387 </para>
 388
 389 <!-- ##### ARG GtkToolbar:button-relief ##### -->
 390 <para>
 391
 392 </para>
 393
 394 <!-- ##### ARG GtkToolbar:internal-padding ##### -->
 395 <para>
 396
 397 </para>
 398
 399 <!-- ##### ARG GtkToolbar:shadow-type ##### -->
 400 <para>
 401
 402 </para>
 403
 404 <!-- ##### ARG GtkToolbar:space-size ##### -->
 405 <para>
 406
 407 </para>
 408
 409 <!-- ##### ARG GtkToolbar:space-style ##### -->
 410 <para>
 411
 412 </para>
 413