GtkBubbleWindow: use OSD style class

[~andy/gtk] / gtk / gtkeditable.c

diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c
index 5f5b89e410535154aceb690360348b82cb90cfe8..43dfd45564fc675cd5e31682d3fcb48230946ad1 100644 (file)
--- a/gtk/gtkeditable.c
+++ b/gtk/gtkeditable.c
@@ -12,9 +12,7 @@
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
 
 /*
@@ -24,6 +22,49 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/**
+ * SECTION:gtkeditable
+ * @Short_description: Interface for text-editing widgets
+ * @Title: GtkEditable
+ *
+ * The #GtkEditable interface is an interface which should be implemented by
+ * text editing widgets, such as #GtkEntry and #GtkSpinButton. It contains functions
+ * for generically manipulating an editable widget, a large number of action
+ * signals used for key bindings, and several signals that an application can
+ * connect to to modify the behavior of a widget.
+ *
+ * As an example of the latter usage, by connecting
+ * the following handler to #GtkEditable::insert-text, an application
+ * can convert all entry into a widget into uppercase.
+ *
+ * <example>
+ * <title>Forcing entry to uppercase.</title>
+ * <programlisting>
+ * #include &lt;ctype.h&gt;
+ *
+ * void
+ * insert_text_handler (GtkEditable &ast;editable,
+ *                      const gchar &ast;text,
+ *                      gint         length,
+ *                      gint        &ast;position,
+ *                      gpointer     data)
+ * {
+ *   gchar &ast;result = g_utf8_strup (text, length);
+ *
+ *   g_signal_handlers_block_by_func (editable,
+ *                                (gpointer) insert_text_handler, data);
+ *   gtk_editable_insert_text (editable, result, length, position);
+ *   g_signal_handlers_unblock_by_func (editable,
+ *                                      (gpointer) insert_text_handler, data);
+ *
+ *   g_signal_stop_emission_by_name (editable, "insert_text");
+ *
+ *   g_free (result);
+ * }
+ * </programlisting>
+ * </example>
+ */
+
 #include "config.h"
 #include <string.h>
 
@@ -69,10 +110,10 @@ gtk_editable_base_init (gpointer g_class)
        * @new_text: the new text to insert
        * @new_text_length: the length of the new text, in bytes,
        *     or -1 if new_text is nul-terminated
-       * @position: the position, in characters, at which to insert
-       *     the new text. this is an in-out parameter.
-       *     After the signal emission is finished, it should
-       *     point after the newly inserted text.
+       * @position: (inout) (type int): the position, in characters,
+       *     at which to insert the new text. this is an in-out
+       *     parameter.  After the signal emission is finished, it
+       *     should point after the newly inserted text.
        *
        * This signal is emitted when text is inserted into
        * the widget by the user. The default handler for
@@ -155,6 +196,8 @@ gtk_editable_base_init (gpointer g_class)
  *
  * Note that the position is in characters, not in bytes. 
  * The function updates @position to point after the newly inserted text.
+ *
+ * Virtual: do_insert_text
  */
 void
 gtk_editable_insert_text (GtkEditable *editable,
@@ -179,10 +222,12 @@ gtk_editable_insert_text (GtkEditable *editable,
  *
  * Deletes a sequence of characters. The characters that are deleted are 
  * those characters at positions from @start_pos up to, but not including 
- * @end_pos. If @end_pos is negative, then the the characters deleted
+ * @end_pos. If @end_pos is negative, then the characters deleted
  * are those from @start_pos to the end of the text.
  *
  * Note that the positions are specified in characters, not bytes.
+ *
+ * Virtual: do_delete_text
  */
 void
 gtk_editable_delete_text (GtkEditable *editable,
@@ -202,7 +247,7 @@ gtk_editable_delete_text (GtkEditable *editable,
  *
  * Retrieves a sequence of characters. The characters that are retrieved 
  * are those characters at positions from @start_pos up to, but not 
- * including @end_pos. If @end_pos is negative, then the the characters 
+ * including @end_pos. If @end_pos is negative, then the characters
  * retrieved are those characters from @start_pos to the end of the text.
  * 
  * Note that positions are specified in characters, not bytes.
@@ -322,11 +367,13 @@ gtk_editable_delete_selection (GtkEditable *editable)
  *
  * Selects a region of text. The characters that are selected are 
  * those characters at positions from @start_pos up to, but not 
- * including @end_pos. If @end_pos is negative, then the the 
+ * including @end_pos. If @end_pos is negative, then the
  * characters selected are those characters from @start_pos to 
  * the end of the text.
  * 
  * Note that positions are specified in characters, not bytes.
+ *
+ * Virtual: set_selection_bounds
  */
 void
 gtk_editable_select_region (GtkEditable *editable,