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

   1 <!-- ##### SECTION Title ##### -->
   2 GtkAccelLabel
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A label which displays an accelerator key on the right of the text
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkAccelLabel widget is a subclass of #GtkLabel that also displays an
  10 accelerator key on the right of the label text, e.g. 'Ctl+S'.
  11 It is commonly used in menus to show the keyboard short-cuts for commands.
  12 </para>
  13 <para>
  14 The accelerator key to display is not set explicitly.
  15 Instead, the #GtkAccelLabel displays the accelerators which have been added to
  16 a particular widget. This widget is set by calling
  17 gtk_accel_label_set_accel_widget().
  18 </para>
  19 <para>
  20 For example, a #GtkMenuItem widget may have an accelerator added to emit the
  21 "activate" signal when the 'Ctl+S' key combination is pressed.
  22 A #GtkAccelLabel is created and added to the #GtkMenuItem, and
  23 gtk_accel_label_set_accel_widget() is called with the #GtkMenuItem as the
  24 second argument. The #GtkAccelLabel will now display 'Ctl+S' after its label.
  25 </para>
  26 <para>
  27 Note that creating a #GtkMenuItem with gtk_menu_item_new_with_label() (or
  28 one of the similar functions for #GtkCheckMenuItem and #GtkRadioMenuItem)
  29 automatically adds a #GtkAccelLabel to the #GtkMenuItem and calls
  30 gtk_accel_label_set_accel_widget() to set it up for you.
  31 </para>
  32 <para>
  33 A #GtkAccelLabel will only display accelerators which have %GTK_ACCEL_VISIBLE
  34 set (see #GtkAccelFlags).
  35 A #GtkAccelLabel can display multiple accelerators and even signal names,
  36 though it is almost always used to display just one accelerator key.
  37 </para>
  38
  39 <example>
  40 <title>Creating a simple menu item with an accelerator key.</title>
  41 <programlisting>
  42   GtkWidget *save_item;
  43   GtkAccelGroup *accel_group;
  44
  45   /* Create a GtkAccelGroup and add it to the window. */
  46   accel_group = gtk_accel_group_new (<!-- -->);
  47   gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);
  48
  49   /* Create the menu item using the convenience function. */
  50   save_item = gtk_menu_item_new_with_label ("Save");
  51   gtk_widget_show (save_item);
  52   gtk_container_add (GTK_CONTAINER (menu), save_item);
  53
  54   /* Now add the accelerator to the GtkMenuItem. Note that since we called
  55      gtk_menu_item_new_with_label(<!-- -->) to create the GtkMenuItem the
  56      GtkAccelLabel is automatically set up to display the GtkMenuItem
  57      accelerators. We just need to make sure we use GTK_ACCEL_VISIBLE here. */
  58   gtk_widget_add_accelerator (save_item, "activate", accel_group,
  59                               GDK_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
  60 </programlisting>
  61 </example>
  62
  63 <!-- ##### SECTION See_Also ##### -->
  64 <para>
  65 <variablelist>
  66
  67 <varlistentry>
  68 <term><link linkend="gtk-keyboard-accelerators">Keyboard Accelerators</link>
  69 </term>
  70 <listitem><para>installing and using keyboard short-cuts.</para></listitem>
  71 </varlistentry>
  72
  73 <varlistentry>
  74 <term>#GtkItemFactory</term>
  75 <listitem><para>an easier way to create menus.</para></listitem>
  76 </varlistentry>
  77
  78 </variablelist>
  79 </para>
  80
  81 <!-- ##### STRUCT GtkAccelLabel ##### -->
  82 <para>
  83 The #GtkAccelLabel-struct struct contains private data only, and
  84 should be accessed using the functions below.
  85 </para>
  86
  87
  88 <!-- ##### ARG GtkAccelLabel:accel-closure ##### -->
  89 <para>
  90
  91 </para>
  92
  93 <!-- ##### ARG GtkAccelLabel:accel-widget ##### -->
  94 <para>
  95
  96 </para>
  97
  98 <!-- ##### FUNCTION gtk_accel_label_new ##### -->
  99 <para>
 100 Creates a new #GtkAccelLabel.
 101 </para>
 102
 103 @string: the label string. Must be non-%NULL.
 104 @Returns: a new #GtkAccelLabel.
 105
 106
 107 <!-- ##### FUNCTION gtk_accel_label_set_accel_closure ##### -->
 108 <para>
 109
 110 </para>
 111
 112 @accel_label:
 113 @accel_closure:
 114 <!-- # Unused Parameters # -->
 115 @closure:
 116
 117
 118 <!-- ##### FUNCTION gtk_accel_label_get_accel_widget ##### -->
 119 <para>
 120
 121 </para>
 122
 123 @accel_label:
 124 @Returns:
 125
 126
 127 <!-- ##### FUNCTION gtk_accel_label_set_accel_widget ##### -->
 128 <para>
 129
 130 </para>
 131
 132 @accel_label:
 133 @accel_widget:
 134
 135
 136 <!-- ##### FUNCTION gtk_accel_label_get_accel_width ##### -->
 137 <para>
 138 Returns the width needed to display the accelerator key(s).
 139 This is used by menus to align all of the #GtkMenuItem widgets, and shouldn't
 140 be needed by applications.
 141 </para>
 142
 143 @accel_label: a #GtkAccelLabel.
 144 @Returns: the width needed to display the accelerator key(s).
 145
 146
 147 <!-- ##### FUNCTION gtk_accel_label_refetch ##### -->
 148 <para>
 149 Recreates the string representing the accelerator keys.
 150 This should not be needed since the string is automatically updated whenever
 151 accelerators are added or removed from the associated widget.
 152 </para>
 153
 154 @accel_label: a #GtkAccelLabel.
 155 @Returns: always returns %FALSE.
 156
 157