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
 158 @toolbar: a #GtkToolbar.
 159 @type: a value of type #GtkToolbarChildType that determines what @widget will be.
 160 @widget: a #GtkWidget to add to the toolbar. (FIXME: double check this).
 161 @text: the element's label.
 162 @tooltip_text: the element's tooltip.
 163 @tooltip_private_text: used for context-sensitive help about this toolbar element.
 164 @icon: a #GtkWidget that provides pictorial representation of the element's function.
 165 @callback: the function to be executed when the button is pressed.
 166 @user_data: any data you wish to pass to the callback.
 167 @Returns: the new toolbar element as a #GtkWidget.
 168
 169
 170 <!-- ##### FUNCTION gtk_toolbar_prepend_element ##### -->
 171 <para>
 172 Adds a new element to the beginning of a toolbar.
 173 </para>
 174
 175 @toolbar: a #GtkToolbar.
 176 @type: a value of type #GtkToolbarChildType that determines what @widget will be.
 177 @widget: a #GtkWidget to add to the toolbar. (FIXME: double check this).
 178 @text: the element's label.
 179 @tooltip_text: the element's tooltip.
 180 @tooltip_private_text: used for context-sensitive help about this toolbar element.
 181 @icon: a #GtkWidget that provides pictorial representation of the element's function.
 182 @callback: the function to be executed when the button is pressed.
 183 @user_data: any data you wish to pass to the callback.
 184 @Returns: the new toolbar element as a #GtkWidget.
 185
 186
 187 <!-- ##### FUNCTION gtk_toolbar_insert_element ##### -->
 188 <para>
 189
 190 </para>
 191
 192 @toolbar: a #GtkToolbar.
 193 @type: a value of type #GtkToolbarChildType that determines what @widget will be.
 194 @widget: a #GtkWidget to add to the toolbar. (FIXME: double check this).
 195 @text: the element's label.
 196 @tooltip_text: the element's tooltip.
 197 @tooltip_private_text: used for context-sensitive help about this toolbar element.
 198 @icon: a #GtkWidget that provides pictorial representation of the element's function.
 199 @callback: the function to be executed when the button is pressed.
 200 @user_data: any data you wish to pass to the callback.
 201 @position: the number of widgets to insert this element after.
 202 @Returns: the new toolbar element as a #GtkWidget.
 203
 204
 205 <!-- ##### FUNCTION gtk_toolbar_append_widget ##### -->
 206 <para>
 207
 208 </para>
 209
 210 @toolbar:
 211 @widget:
 212 @tooltip_text:
 213 @tooltip_private_text:
 214
 215
 216 <!-- ##### FUNCTION gtk_toolbar_prepend_widget ##### -->
 217 <para>
 218
 219 </para>
 220
 221 @toolbar:
 222 @widget:
 223 @tooltip_text:
 224 @tooltip_private_text:
 225
 226
 227 <!-- ##### FUNCTION gtk_toolbar_insert_widget ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @toolbar:
 233 @widget:
 234 @tooltip_text:
 235 @tooltip_private_text:
 236 @position:
 237
 238
 239 <!-- ##### FUNCTION gtk_toolbar_set_orientation ##### -->
 240 <para>
 241 Sets whether a toolbar should appear horizontally or vertically.
 242 </para>
 243
 244 @toolbar: a #GtkToolbar.
 245 @orientation: a new #GtkOrientation.
 246
 247
 248 <!-- ##### FUNCTION gtk_toolbar_set_style ##### -->
 249 <para>
 250 Alters the view of @toolbar to display either icons only, text only, or both.
 251 </para>
 252
 253 @toolbar: a #GtkToolbar.
 254 @style: the new style for @toolbar.
 255
 256
 257 <!-- ##### FUNCTION gtk_toolbar_set_tooltips ##### -->
 258 <para>
 259 Sets if the tooltips of a toolbar should be active or not.
 260 </para>
 261
 262 @toolbar: a #GtkToolbar.
 263 @enable: set to %FALSE to disable the tooltips, or %TRUE to enable them.
 264
 265
 266 <!-- ##### FUNCTION gtk_toolbar_insert_stock ##### -->
 267 <para>
 268
 269 </para>
 270
 271 @toolbar:
 272 @stock_id:
 273 @tooltip_text:
 274 @tooltip_private_text:
 275 @callback:
 276 @user_data:
 277 @position:
 278 @Returns:
 279
 280
 281 <!-- ##### FUNCTION gtk_toolbar_set_icon_size ##### -->
 282 <para>
 283
 284 </para>
 285
 286 @toolbar:
 287 @icon_size:
 288
 289
 290 <!-- ##### FUNCTION gtk_toolbar_get_icon_size ##### -->
 291 <para>
 292
 293 </para>
 294
 295 @toolbar:
 296 @Returns:
 297
 298
 299 <!-- ##### FUNCTION gtk_toolbar_get_orientation ##### -->
 300 <para>
 301
 302 </para>
 303
 304 @toolbar:
 305 @Returns:
 306
 307
 308 <!-- ##### FUNCTION gtk_toolbar_get_style ##### -->
 309 <para>
 310
 311 </para>
 312
 313 @toolbar:
 314 @Returns:
 315
 316
 317 <!-- ##### FUNCTION gtk_toolbar_get_tooltips ##### -->
 318 <para>
 319
 320 </para>
 321
 322 @toolbar:
 323 @Returns:
 324
 325
 326 <!-- ##### FUNCTION gtk_toolbar_remove_space ##### -->
 327 <para>
 328
 329 </para>
 330
 331 @toolbar:
 332 @position:
 333
 334
 335 <!-- ##### FUNCTION gtk_toolbar_unset_icon_size ##### -->
 336 <para>
 337
 338 </para>
 339
 340 @toolbar:
 341
 342
 343 <!-- ##### FUNCTION gtk_toolbar_unset_style ##### -->
 344 <para>
 345
 346 </para>
 347
 348 @toolbar:
 349
 350
 351 <!-- ##### SIGNAL GtkToolbar::orientation-changed ##### -->
 352 <para>
 353 Should be used if you wish to perform an action when the orientation of a toolbar is changed.
 354 </para>
 355
 356 @toolbar: the object which received the signal.
 357 @orientation: the new #GtkOrientation of the toolbar.
 358
 359 <!-- ##### SIGNAL GtkToolbar::style-changed ##### -->
 360 <para>
 361 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.
 362 </para>
 363
 364 @toolbar: the object which received the signal.
 365 @style: the new #GtkToolbarStyle of @toolbar.
 366
 367 <!-- ##### ARG GtkToolbar:orientation ##### -->
 368 <para>
 369
 370 </para>
 371
 372 <!-- ##### ARG GtkToolbar:toolbar-style ##### -->
 373 <para>
 374
 375 </para>
 376