Pileus Git - ~andy/gtk/blob - gdk/gdkcursor.c

   1 /* GDK - The GIMP Drawing Kit
   2  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 /*
  21  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  22  * file for a list of people on the GTK+ Team.  See the ChangeLog
  23  * files for a list of changes.  These files are distributed with
  24  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  25  */
  26
  27 #include "config.h"
  28
  29 #include "gdkcursor.h"
  30 #include "gdkcursorprivate.h"
  31 #include "gdkdisplayprivate.h"
  32 #include "gdkinternals.h"
  33
  34
  35 /**
  36  * SECTION:cursors
  37  * @Short_description: Standard and pixmap cursors
  38  * @Title: Cursors
  39  *
  40  * These functions are used to create and destroy cursors.
  41  * There is a number of standard cursors, but it is also
  42  * possible to construct new cursors from pixbufs. There
  43  * may be limitations as to what kinds of cursors can be
  44  * constructed on a given display, see
  45  * gdk_display_supports_cursor_alpha(),
  46  * gdk_display_supports_cursor_color(),
  47  * gdk_display_get_default_cursor_size() and
  48  * gdk_display_get_maximal_cursor_size().
  49  *
  50  * Cursors by themselves are not very interesting, they must be be
  51  * bound to a window for users to see them. This is done with
  52  * gdk_window_set_cursor() or by setting the cursor member of the
  53  * #GdkWindowAttr struct passed to gdk_window_new().
  54  */
  55
  56 /**
  57  * GdkCursor:
  58  *
  59  * The #GdkCursor structure represents a cursor. Its contents are private.
  60  */
  61
  62 G_DEFINE_ABSTRACT_TYPE (GdkCursor, gdk_cursor, G_TYPE_OBJECT)
  63
  64 static void
  65 gdk_cursor_class_init (GdkCursorClass *cursor_class)
  66 {
  67 }
  68
  69 static void
  70 gdk_cursor_init (GdkCursor *cursor)
  71 {
  72 }
  73
  74 /**
  75  * gdk_cursor_ref:
  76  * @cursor: a #GdkCursor
  77  *
  78  * Adds a reference to @cursor.
  79  *
  80  * Return value: Same @cursor that was passed in
  81  *
  82  * Deprecated: 3.0: Use g_object_ref() instead
  83  */
  84 GdkCursor*
  85 gdk_cursor_ref (GdkCursor *cursor)
  86 {
  87   g_return_val_if_fail (cursor != NULL, NULL);
  88
  89   return g_object_ref (cursor);
  90 }
  91
  92 /**
  93  * gdk_cursor_unref:
  94  * @cursor: a #GdkCursor
  95  *
  96  * Removes a reference from @cursor, deallocating the cursor
  97  * if no references remain.
  98  *
  99  * Deprecated: 3.0: Use g_object_unref() instead
 100  */
 101 void
 102 gdk_cursor_unref (GdkCursor *cursor)
 103 {
 104   g_return_if_fail (cursor != NULL);
 105
 106   g_object_unref (cursor);
 107 }
 108
 109 /**
 110  * gdk_cursor_new:
 111  * @cursor_type: cursor to create
 112  *
 113  * Creates a new cursor from the set of builtin cursors for the default display.
 114  * See gdk_cursor_new_for_display().
 115  *
 116  * To make the cursor invisible, use %GDK_BLANK_CURSOR.
 117  *
 118  * Return value: a new #GdkCursor
 119  */
 120 GdkCursor*
 121 gdk_cursor_new (GdkCursorType cursor_type)
 122 {
 123   return gdk_cursor_new_for_display (gdk_display_get_default(), cursor_type);
 124 }
 125
 126 /**
 127  * gdk_cursor_get_cursor_type:
 128  * @cursor:  a #GdkCursor
 129  *
 130  * Returns the cursor type for this cursor.
 131  *
 132  * Return value: a #GdkCursorType
 133  *
 134  * Since: 2.22
 135  **/
 136 GdkCursorType
 137 gdk_cursor_get_cursor_type (GdkCursor *cursor)
 138 {
 139   g_return_val_if_fail (cursor != NULL, GDK_BLANK_CURSOR);
 140
 141   return cursor->type;
 142 }
 143
 144 /**
 145  * gdk_cursor_new_for_display:
 146  * @display: the #GdkDisplay for which the cursor will be created
 147  * @cursor_type: cursor to create
 148  *
 149  * Creates a new cursor from the set of builtin cursors.
 150  * Some useful ones are:
 151  * <itemizedlist>
 152  * <listitem><para>
 153  *  <inlinegraphic format="PNG" fileref="right_ptr.png"></inlinegraphic> #GDK_RIGHT_PTR (right-facing arrow)
 154  * </para></listitem>
 155  * <listitem><para>
 156  *  <inlinegraphic format="PNG" fileref="crosshair.png"></inlinegraphic> #GDK_CROSSHAIR (crosshair)
 157  * </para></listitem>
 158  * <listitem><para>
 159  *  <inlinegraphic format="PNG" fileref="xterm.png"></inlinegraphic> #GDK_XTERM (I-beam)
 160  * </para></listitem>
 161  * <listitem><para>
 162  * <inlinegraphic format="PNG" fileref="watch.png"></inlinegraphic> #GDK_WATCH (busy)
 163  * </para></listitem>
 164  * <listitem><para>
 165  * <inlinegraphic format="PNG" fileref="fleur.png"></inlinegraphic> #GDK_FLEUR (for moving objects)
 166  * </para></listitem>
 167  * <listitem><para>
 168  * <inlinegraphic format="PNG" fileref="hand1.png"></inlinegraphic> #GDK_HAND1 (a right-pointing hand)
 169  * </para></listitem>
 170  * <listitem><para>
 171  * <inlinegraphic format="PNG" fileref="hand2.png"></inlinegraphic> #GDK_HAND2 (a left-pointing hand)
 172  * </para></listitem>
 173  * <listitem><para>
 174  * <inlinegraphic format="PNG" fileref="left_side.png"></inlinegraphic> #GDK_LEFT_SIDE (resize left side)
 175  * </para></listitem>
 176  * <listitem><para>
 177  * <inlinegraphic format="PNG" fileref="right_side.png"></inlinegraphic> #GDK_RIGHT_SIDE (resize right side)
 178  * </para></listitem>
 179  * <listitem><para>
 180  * <inlinegraphic format="PNG" fileref="top_left_corner.png"></inlinegraphic> #GDK_TOP_LEFT_CORNER (resize northwest corner)
 181  * </para></listitem>
 182  * <listitem><para>
 183  * <inlinegraphic format="PNG" fileref="top_right_corner.png"></inlinegraphic> #GDK_TOP_RIGHT_CORNER (resize northeast corner)
 184  * </para></listitem>
 185  * <listitem><para>
 186  * <inlinegraphic format="PNG" fileref="bottom_left_corner.png"></inlinegraphic> #GDK_BOTTOM_LEFT_CORNER (resize southwest corner)
 187  * </para></listitem>
 188  * <listitem><para>
 189  * <inlinegraphic format="PNG" fileref="bottom_right_corner.png"></inlinegraphic> #GDK_BOTTOM_RIGHT_CORNER (resize southeast corner)
 190  * </para></listitem>
 191  * <listitem><para>
 192  * <inlinegraphic format="PNG" fileref="top_side.png"></inlinegraphic> #GDK_TOP_SIDE (resize top side)
 193  * </para></listitem>
 194  * <listitem><para>
 195  * <inlinegraphic format="PNG" fileref="bottom_side.png"></inlinegraphic> #GDK_BOTTOM_SIDE (resize bottom side)
 196  * </para></listitem>
 197  * <listitem><para>
 198  * <inlinegraphic format="PNG" fileref="sb_h_double_arrow.png"></inlinegraphic> #GDK_SB_H_DOUBLE_ARROW (move vertical splitter)
 199  * </para></listitem>
 200  * <listitem><para>
 201  * <inlinegraphic format="PNG" fileref="sb_v_double_arrow.png"></inlinegraphic> #GDK_SB_V_DOUBLE_ARROW (move horizontal splitter)
 202  * </para></listitem>
 203  * <listitem><para>
 204  * #GDK_BLANK_CURSOR (Blank cursor). Since 2.16
 205  * </para></listitem>
 206  * </itemizedlist>
 207  *
 208  * Return value: a new #GdkCursor
 209  *
 210  * Since: 2.2
 211  **/
 212 GdkCursor*
 213 gdk_cursor_new_for_display (GdkDisplay    *display,
 214                             GdkCursorType  cursor_type)
 215 {
 216   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 217
 218   return GDK_DISPLAY_GET_CLASS (display)->get_cursor_for_type (display, cursor_type);
 219 }
 220
 221 /**
 222  * gdk_cursor_new_from_name:
 223  * @display: the #GdkDisplay for which the cursor will be created
 224  * @name: the name of the cursor
 225  *
 226  * Creates a new cursor by looking up @name in the current cursor
 227  * theme.
 228  *
 229  * Returns: a new #GdkCursor, or %NULL if there is no cursor with
 230  *   the given name
 231  *
 232  * Since: 2.8
 233  */
 234 GdkCursor*
 235 gdk_cursor_new_from_name (GdkDisplay  *display,
 236                           const gchar *name)
 237 {
 238   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 239
 240   return GDK_DISPLAY_GET_CLASS (display)->get_cursor_for_name (display, name);
 241 }
 242
 243 /**
 244  * gdk_cursor_new_from_pixbuf:
 245  * @display: the #GdkDisplay for which the cursor will be created
 246  * @pixbuf: the #GdkPixbuf containing the cursor image
 247  * @x: the horizontal offset of the 'hotspot' of the cursor.
 248  * @y: the vertical offset of the 'hotspot' of the cursor.
 249  *
 250  * Creates a new cursor from a pixbuf.
 251  *
 252  * Not all GDK backends support RGBA cursors. If they are not
 253  * supported, a monochrome approximation will be displayed.
 254  * The functions gdk_display_supports_cursor_alpha() and
 255  * gdk_display_supports_cursor_color() can be used to determine
 256  * whether RGBA cursors are supported;
 257  * gdk_display_get_default_cursor_size() and
 258  * gdk_display_get_maximal_cursor_size() give information about
 259  * cursor sizes.
 260  *
 261  * If @x or @y are <literal>-1</literal>, the pixbuf must have
 262  * options named "x_hot" and "y_hot", resp., containing
 263  * integer values between %0 and the width resp. height of
 264  * the pixbuf. (Since: 3.0)
 265  *
 266  * On the X backend, support for RGBA cursors requires a
 267  * sufficently new version of the X Render extension.
 268  *
 269  * Returns: a new #GdkCursor.
 270  *
 271  * Since: 2.4
 272  */
 273 GdkCursor *
 274 gdk_cursor_new_from_pixbuf (GdkDisplay *display,
 275                             GdkPixbuf  *pixbuf,
 276                             gint        x,
 277                             gint        y)
 278 {
 279   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 280   g_return_val_if_fail (GDK_IS_PIXBUF (pixbuf), NULL);
 281
 282   return GDK_DISPLAY_GET_CLASS (display)->get_cursor_for_pixbuf (display, pixbuf, x, y);
 283 }