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 visibily 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 is used to set the type of new elements that are added to a #GtkToolbar.
  47 </para>
  48 <para>
  49 SPACE is just a space in the style of the toolbar's GtkToolbarSpaceStyle. BUTTON denotes a #GtkButton. TOGGLEBUTTON denotes a #GtkToggleButton, RADIOBUTTON denotes a #GtkRadioButton, and WIDGET denotes a standard #GtkWidget.
  50 </para>
  51
  52 @GTK_TOOLBAR_CHILD_SPACE:
  53 @GTK_TOOLBAR_CHILD_BUTTON:
  54 @GTK_TOOLBAR_CHILD_TOGGLEBUTTON:
  55 @GTK_TOOLBAR_CHILD_RADIOBUTTON:
  56 @GTK_TOOLBAR_CHILD_WIDGET:
  57
  58 <!-- ##### ENUM GtkToolbarSpaceStyle ##### -->
  59 <para>
  60
  61 </para>
  62
  63 @GTK_TOOLBAR_SPACE_EMPTY:
  64 @GTK_TOOLBAR_SPACE_LINE:
  65
  66 <!-- ##### STRUCT GtkToolbarChild ##### -->
  67 <para>
  68
  69 </para>
  70
  71 @type:
  72 @widget:
  73 @icon:
  74 @label:
  75
  76 <!-- ##### FUNCTION gtk_toolbar_new ##### -->
  77 <para>
  78 creates a new toolbar.
  79 </para>
  80
  81 @orientation: a #GtkOrientation. It determines whether the toolbar appears horizontally or vertically.
  82 @style: a #GtkToolbarStyle. It determines if the toolbar will contain buttons with just labels, just images, or both.
  83 @Returns: the newly created toolbar.
  84
  85
  86 <!-- ##### FUNCTION gtk_toolbar_append_item ##### -->
  87 <para>
  88 adds a new button to the beginning (left or top edges) of the given toolbar.
  89 </para>
  90
  91 @toolbar: a #GtkToolbar.
  92 @text: give your toolbar button a label.
  93 @tooltip_text: a string that appears when the user holds the mouse over this item.
  94 @tooltip_private_text: use with #GtkTipsQuery.
  95 @icon: a #GtkWidget that should be used as the button's icon.
  96 @callback: the function to be executed when the button is pressed.
  97 @user_data: a pointer to any data you wish to be passed to the callback.
  98 @Returns: the new toolbar item as a #GtkWidget.
  99
 100
 101 <!-- ##### FUNCTION gtk_toolbar_prepend_item ##### -->
 102 <para>
 103 adds a new button to the beginning of the given toolbar.
 104 </para>
 105
 106 @toolbar: a #GtkToolbar.
 107 @text: give your toolbar button a label.
 108 @tooltip_text: a string that appears when the user holds the mouse over this item.
 109 @tooltip_private_text: use with #GtkTipsQuery.
 110 @icon: a #GtkWidget that should be used as the button's icon.
 111 @callback: the function to be executed when the button is pressed.
 112 @user_data: a pointer to any data you wish to be passed to the callback.
 113 @Returns: the new toolbar item as a #GtkWidget.
 114
 115
 116 <!-- ##### FUNCTION gtk_toolbar_insert_item ##### -->
 117 <para>
 118 inserts a new item into the toolbar. You must specify the position in the toolbar where it will be inserted.
 119 </para>
 120
 121 @toolbar: a #GtkToolbar.
 122 @text: give your toolbar button a label.
 123 @tooltip_text: a string that appears when the user holds the mouse over this item.
 124 @tooltip_private_text: use with #GtkTipsQuery.
 125 @icon: a #GtkWidget that should be used as the button's icon.
 126 @callback: the function to be executed when the button is pressed.
 127 @user_data: a pointer to any data you wish to be passed to the callback.
 128 @position: the number of widgets to insert this item after.
 129 @Returns: the new toolbar item as a #GtkWidget.
 130
 131
 132 <!-- ##### FUNCTION gtk_toolbar_append_space ##### -->
 133 <para>
 134 adds a new space to the end of the toolbar.
 135 </para>
 136
 137 @toolbar: a #GtkToolbar.
 138
 139
 140 <!-- ##### FUNCTION gtk_toolbar_prepend_space ##### -->
 141 <para>
 142 adds a new space to the beginning of the toolbar.
 143 </para>
 144
 145 @toolbar: a #GtkToolbar.
 146
 147
 148 <!-- ##### FUNCTION gtk_toolbar_insert_space ##### -->
 149 <para>
 150 inserts a new space in the toolbar at the specified position.
 151 </para>
 152
 153 @toolbar: a #GtkToolbar
 154 @position: the number of widgets after which a space should be inserted.
 155
 156
 157 <!-- ##### FUNCTION gtk_toolbar_append_element ##### -->
 158 <para>
 159 adds a new element to the end of a toolbar.
 160 </para>
 161
 162 @toolbar: a #GtkToolbar.
 163 @type: a value of type #GtkToolbarChildType that determines what @widget will be.
 164 @widget: a #GtkWidget to add to the toolbar. (FIXME: double check this).
 165 @text: the element's label.
 166 @tooltip_text: the element's tooltip.
 167 @tooltip_private_text: used for context-sensitive help about this toolbar element.
 168 @icon: a #GtkWidget that provides pictorial representation of the element's function.
 169 @callback: the function to be executed when the button is pressed.
 170 @user_data: any data you wish to pass to the callback.
 171 @Returns: the new toolbar element as a #GtkWidget.
 172
 173
 174 <!-- ##### FUNCTION gtk_toolbar_prepend_element ##### -->
 175 <para>
 176 adds a new element to the beginning of a toolbar.
 177 </para>
 178
 179 @toolbar: a #GtkToolbar.
 180 @type: a value of type #GtkToolbarChildType that determines what @widget will be.
 181 @widget: a #GtkWidget to add to the toolbar. (FIXME: double check this).
 182 @text: the element's label.
 183 @tooltip_text: the element's tooltip.
 184 @tooltip_private_text: used for context-sensitive help about this toolbar element.
 185 @icon: a #GtkWidget that provides pictorial representation of the element's function.
 186 @callback: the function to be executed when the button is pressed.
 187 @user_data: any data you wish to pass to the callback.
 188 @Returns: the new toolbar element as a #GtkWidget.
 189
 190
 191 <!-- ##### FUNCTION gtk_toolbar_insert_element ##### -->
 192 <para>
 193
 194 </para>
 195
 196 @toolbar: a #GtkToolbar.
 197 @type: a value of type #GtkToolbarChildType that determines what @widget will be.
 198 @widget: a #GtkWidget to add to the toolbar. (FIXME: double check this).
 199 @text: the element's label.
 200 @tooltip_text: the element's tooltip.
 201 @tooltip_private_text: used for context-sensitive help about this toolbar element.
 202 @icon: a #GtkWidget that provides pictorial representation of the element's function.
 203 @callback: the function to be executed when the button is pressed.
 204 @user_data: any data you wish to pass to the callback.
 205 @position: the number of widgets to insert this element after.
 206 @Returns: the new toolbar element as a #GtkWidget.
 207
 208
 209 <!-- ##### FUNCTION gtk_toolbar_append_widget ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @toolbar:
 215 @widget:
 216 @tooltip_text:
 217 @tooltip_private_text:
 218
 219
 220 <!-- ##### FUNCTION gtk_toolbar_prepend_widget ##### -->
 221 <para>
 222
 223 </para>
 224
 225 @toolbar:
 226 @widget:
 227 @tooltip_text:
 228 @tooltip_private_text:
 229
 230
 231 <!-- ##### FUNCTION gtk_toolbar_insert_widget ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @toolbar:
 237 @widget:
 238 @tooltip_text:
 239 @tooltip_private_text:
 240 @position:
 241
 242
 243 <!-- ##### FUNCTION gtk_toolbar_set_orientation ##### -->
 244 <para>
 245 sets whether a toolbar should appear horizontally or vertically.
 246 </para>
 247
 248 @toolbar: a #GtkToolbar.
 249 @orientation: a new #GtkOrientation.
 250
 251
 252 <!-- ##### FUNCTION gtk_toolbar_set_style ##### -->
 253 <para>
 254 alters the view of @toolbar to display either icons only, text only, or both.
 255 </para>
 256
 257 @toolbar: a #GtkToolbar.
 258 @style: the new style for @toolbar.
 259
 260
 261 <!-- ##### FUNCTION gtk_toolbar_set_space_size ##### -->
 262 <para>
 263 should be used to set the number of pixels each item of space takes up in a toolbar.
 264 </para>
 265
 266 @toolbar: a #GtkToolbar.
 267 @space_size: the new number of pixels that spaces should consume.
 268
 269
 270 <!-- ##### FUNCTION gtk_toolbar_set_space_style ##### -->
 271 <para>
 272 sets whether a 'space' in the toolbar appears as a line or just plain empty space.
 273 </para>
 274
 275 @toolbar: a #GtkToolbar.
 276 @space_style: the new style for the toolbar's spaces.
 277
 278
 279 <!-- ##### FUNCTION gtk_toolbar_set_tooltips ##### -->
 280 <para>
 281 sets if the tooltips of a toolbar should be active or not.
 282 </para>
 283
 284 @toolbar: a #GtkToolbar.
 285 @enable: set to 0 to disable the tooltips, or 1 to enable them.
 286
 287
 288 <!-- ##### FUNCTION gtk_toolbar_set_button_relief ##### -->
 289 <para>
 290
 291 </para>
 292
 293 @toolbar:
 294 @relief:
 295
 296
 297 <!-- ##### FUNCTION gtk_toolbar_get_button_relief ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @toolbar:
 303 @Returns:
 304
 305
 306 <!-- ##### SIGNAL GtkToolbar::orientation-changed ##### -->
 307 <para>
 308 should be used if you wish to perform an action when the orientation of a toolbar is changed.
 309 </para>
 310
 311 @toolbar: the object which received the signal.
 312 @orientation: the new #GtkOrientation of the toolbar.
 313
 314 <!-- ##### SIGNAL GtkToolbar::style-changed ##### -->
 315 <para>
 316 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.
 317 </para>
 318
 319 @toolbar: the object which received the signal.
 320 @style: the new #GtkToolbarStyle of @toolbar.
 321
 322 <!-- ##### ARG GtkToolbar:orientation ##### -->
 323 <para>
 324
 325 </para>
 326
 327 <!-- ##### ARG GtkToolbar:toolbar-style ##### -->
 328 <para>
 329
 330 </para>
 331
 332 <!-- ##### ARG GtkToolbar:space-size ##### -->
 333 <para>
 334
 335 </para>
 336
 337 <!-- ##### ARG GtkToolbar:space-style ##### -->
 338 <para>
 339
 340 </para>
 341
 342 <!-- ##### ARG GtkToolbar:relief ##### -->
 343 <para>
 344
 345 </para>
 346