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 "gdkintl.h"
  33 #include "gdkinternals.h"
  34
  35
  36 /**
  37  * SECTION:cursors
  38  * @Short_description: Standard and pixmap cursors
  39  * @Title: Cursors
  40  *
  41  * These functions are used to create and destroy cursors.
  42  * There is a number of standard cursors, but it is also
  43  * possible to construct new cursors from pixbufs. There
  44  * may be limitations as to what kinds of cursors can be
  45  * constructed on a given display, see
  46  * gdk_display_supports_cursor_alpha(),
  47  * gdk_display_supports_cursor_color(),
  48  * gdk_display_get_default_cursor_size() and
  49  * gdk_display_get_maximal_cursor_size().
  50  *
  51  * Cursors by themselves are not very interesting, they must be be
  52  * bound to a window for users to see them. This is done with
  53  * gdk_window_set_cursor() or by setting the cursor member of the
  54  * #GdkWindowAttr struct passed to gdk_window_new().
  55  */
  56
  57 /**
  58  * GdkCursor:
  59  *
  60  * The #GdkCursor structure represents a cursor. Its contents are private.
  61  */
  62
  63 enum {
  64   PROP_0,
  65   PROP_CURSOR_TYPE,
  66   PROP_DISPLAY
  67 };
  68
  69 G_DEFINE_ABSTRACT_TYPE (GdkCursor, gdk_cursor, G_TYPE_OBJECT)
  70
  71 static void
  72 gdk_cursor_get_property (GObject    *object,
  73                          guint       prop_id,
  74                          GValue     *value,
  75                          GParamSpec *pspec)
  76 {
  77   GdkCursor *cursor = GDK_CURSOR (object);
  78
  79   switch (prop_id)
  80     {
  81     case PROP_CURSOR_TYPE:
  82       g_value_set_enum (value, cursor->type);
  83       break;
  84     case PROP_DISPLAY:
  85       g_value_set_object (value, cursor->display);
  86       break;
  87     default:
  88       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
  89       break;
  90     }
  91 }
  92
  93 static void
  94 gdk_cursor_set_property (GObject      *object,
  95                          guint         prop_id,
  96                          const GValue *value,
  97                          GParamSpec   *pspec)
  98 {
  99   GdkCursor *cursor = GDK_CURSOR (object);
 100
 101   switch (prop_id)
 102     {
 103     case PROP_CURSOR_TYPE:
 104       cursor->type = g_value_get_enum (value);
 105       break;
 106     case PROP_DISPLAY:
 107       cursor->display = g_value_get_object (value);
 108       /* check that implementations actually provide the display when constructing */
 109       g_assert (cursor->display != NULL);
 110       break;
 111     default:
 112       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 113       break;
 114     }
 115 }
 116
 117 static void
 118 gdk_cursor_class_init (GdkCursorClass *cursor_class)
 119 {
 120   GObjectClass *object_class = G_OBJECT_CLASS (cursor_class);
 121
 122   object_class->get_property = gdk_cursor_get_property;
 123   object_class->set_property = gdk_cursor_set_property;
 124
 125   g_object_class_install_property (object_class,
 126                                    PROP_CURSOR_TYPE,
 127                                    g_param_spec_enum ("cursor-type",
 128                                                       P_("Cursor type"),
 129                                                       P_("Standard cursor type"),
 130                                                       GDK_TYPE_CURSOR_TYPE, GDK_X_CURSOR,
 131                                                       G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 132
 133   g_object_class_install_property (object_class,
 134                                    PROP_DISPLAY,
 135                                    g_param_spec_object ("display",
 136                                                         P_("Display"),
 137                                                         P_("Display of this cursor"),
 138                                                         GDK_TYPE_DISPLAY,
 139                                                         G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 140 }
 141
 142 static void
 143 gdk_cursor_init (GdkCursor *cursor)
 144 {
 145 }
 146
 147 /**
 148  * gdk_cursor_ref:
 149  * @cursor: a #GdkCursor
 150  *
 151  * Adds a reference to @cursor.
 152  *
 153  * Return value: (transfer full): Same @cursor that was passed in
 154  *
 155  * Deprecated: 3.0: Use g_object_ref() instead
 156  */
 157 GdkCursor*
 158 gdk_cursor_ref (GdkCursor *cursor)
 159 {
 160   g_return_val_if_fail (cursor != NULL, NULL);
 161
 162   return g_object_ref (cursor);
 163 }
 164
 165 /**
 166  * gdk_cursor_unref:
 167  * @cursor: a #GdkCursor
 168  *
 169  * Removes a reference from @cursor, deallocating the cursor
 170  * if no references remain.
 171  *
 172  * Deprecated: 3.0: Use g_object_unref() instead
 173  */
 174 void
 175 gdk_cursor_unref (GdkCursor *cursor)
 176 {
 177   g_return_if_fail (cursor != NULL);
 178
 179   g_object_unref (cursor);
 180 }
 181
 182 /**
 183  * gdk_cursor_new:
 184  * @cursor_type: cursor to create
 185  *
 186  * Creates a new cursor from the set of builtin cursors for the default display.
 187  * See gdk_cursor_new_for_display().
 188  *
 189  * To make the cursor invisible, use %GDK_BLANK_CURSOR.
 190  *
 191  * Return value: a new #GdkCursor
 192  */
 193 GdkCursor*
 194 gdk_cursor_new (GdkCursorType cursor_type)
 195 {
 196   return gdk_cursor_new_for_display (gdk_display_get_default(), cursor_type);
 197 }
 198
 199 /**
 200  * gdk_cursor_get_cursor_type:
 201  * @cursor:  a #GdkCursor
 202  *
 203  * Returns the cursor type for this cursor.
 204  *
 205  * Return value: a #GdkCursorType
 206  *
 207  * Since: 2.22
 208  **/
 209 GdkCursorType
 210 gdk_cursor_get_cursor_type (GdkCursor *cursor)
 211 {
 212   g_return_val_if_fail (cursor != NULL, GDK_BLANK_CURSOR);
 213
 214   return cursor->type;
 215 }
 216
 217 /**
 218  * gdk_cursor_new_for_display:
 219  * @display: the #GdkDisplay for which the cursor will be created
 220  * @cursor_type: cursor to create
 221  *
 222  * Creates a new cursor from the set of builtin cursors.
 223  * Some useful ones are:
 224  * <itemizedlist>
 225  * <listitem><para>
 226  *  <inlinegraphic format="PNG" fileref="right_ptr.png"></inlinegraphic> #GDK_RIGHT_PTR (right-facing arrow)
 227  * </para></listitem>
 228  * <listitem><para>
 229  *  <inlinegraphic format="PNG" fileref="crosshair.png"></inlinegraphic> #GDK_CROSSHAIR (crosshair)
 230  * </para></listitem>
 231  * <listitem><para>
 232  *  <inlinegraphic format="PNG" fileref="xterm.png"></inlinegraphic> #GDK_XTERM (I-beam)
 233  * </para></listitem>
 234  * <listitem><para>
 235  * <inlinegraphic format="PNG" fileref="watch.png"></inlinegraphic> #GDK_WATCH (busy)
 236  * </para></listitem>
 237  * <listitem><para>
 238  * <inlinegraphic format="PNG" fileref="fleur.png"></inlinegraphic> #GDK_FLEUR (for moving objects)
 239  * </para></listitem>
 240  * <listitem><para>
 241  * <inlinegraphic format="PNG" fileref="hand1.png"></inlinegraphic> #GDK_HAND1 (a right-pointing hand)
 242  * </para></listitem>
 243  * <listitem><para>
 244  * <inlinegraphic format="PNG" fileref="hand2.png"></inlinegraphic> #GDK_HAND2 (a left-pointing hand)
 245  * </para></listitem>
 246  * <listitem><para>
 247  * <inlinegraphic format="PNG" fileref="left_side.png"></inlinegraphic> #GDK_LEFT_SIDE (resize left side)
 248  * </para></listitem>
 249  * <listitem><para>
 250  * <inlinegraphic format="PNG" fileref="right_side.png"></inlinegraphic> #GDK_RIGHT_SIDE (resize right side)
 251  * </para></listitem>
 252  * <listitem><para>
 253  * <inlinegraphic format="PNG" fileref="top_left_corner.png"></inlinegraphic> #GDK_TOP_LEFT_CORNER (resize northwest corner)
 254  * </para></listitem>
 255  * <listitem><para>
 256  * <inlinegraphic format="PNG" fileref="top_right_corner.png"></inlinegraphic> #GDK_TOP_RIGHT_CORNER (resize northeast corner)
 257  * </para></listitem>
 258  * <listitem><para>
 259  * <inlinegraphic format="PNG" fileref="bottom_left_corner.png"></inlinegraphic> #GDK_BOTTOM_LEFT_CORNER (resize southwest corner)
 260  * </para></listitem>
 261  * <listitem><para>
 262  * <inlinegraphic format="PNG" fileref="bottom_right_corner.png"></inlinegraphic> #GDK_BOTTOM_RIGHT_CORNER (resize southeast corner)
 263  * </para></listitem>
 264  * <listitem><para>
 265  * <inlinegraphic format="PNG" fileref="top_side.png"></inlinegraphic> #GDK_TOP_SIDE (resize top side)
 266  * </para></listitem>
 267  * <listitem><para>
 268  * <inlinegraphic format="PNG" fileref="bottom_side.png"></inlinegraphic> #GDK_BOTTOM_SIDE (resize bottom side)
 269  * </para></listitem>
 270  * <listitem><para>
 271  * <inlinegraphic format="PNG" fileref="sb_h_double_arrow.png"></inlinegraphic> #GDK_SB_H_DOUBLE_ARROW (move vertical splitter)
 272  * </para></listitem>
 273  * <listitem><para>
 274  * <inlinegraphic format="PNG" fileref="sb_v_double_arrow.png"></inlinegraphic> #GDK_SB_V_DOUBLE_ARROW (move horizontal splitter)
 275  * </para></listitem>
 276  * <listitem><para>
 277  * #GDK_BLANK_CURSOR (Blank cursor). Since 2.16
 278  * </para></listitem>
 279  * </itemizedlist>
 280  *
 281  * Return value: a new #GdkCursor
 282  *
 283  * Since: 2.2
 284  **/
 285 GdkCursor*
 286 gdk_cursor_new_for_display (GdkDisplay    *display,
 287                             GdkCursorType  cursor_type)
 288 {
 289   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 290
 291   return GDK_DISPLAY_GET_CLASS (display)->get_cursor_for_type (display, cursor_type);
 292 }
 293
 294 /**
 295  * gdk_cursor_new_from_name:
 296  * @display: the #GdkDisplay for which the cursor will be created
 297  * @name: the name of the cursor
 298  *
 299  * Creates a new cursor by looking up @name in the current cursor
 300  * theme.
 301  *
 302  * Returns: a new #GdkCursor, or %NULL if there is no cursor with
 303  *   the given name
 304  *
 305  * Since: 2.8
 306  */
 307 GdkCursor*
 308 gdk_cursor_new_from_name (GdkDisplay  *display,
 309                           const gchar *name)
 310 {
 311   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 312
 313   return GDK_DISPLAY_GET_CLASS (display)->get_cursor_for_name (display, name);
 314 }
 315
 316 /**
 317  * gdk_cursor_new_from_pixbuf:
 318  * @display: the #GdkDisplay for which the cursor will be created
 319  * @pixbuf: the #GdkPixbuf containing the cursor image
 320  * @x: the horizontal offset of the 'hotspot' of the cursor.
 321  * @y: the vertical offset of the 'hotspot' of the cursor.
 322  *
 323  * Creates a new cursor from a pixbuf.
 324  *
 325  * Not all GDK backends support RGBA cursors. If they are not
 326  * supported, a monochrome approximation will be displayed.
 327  * The functions gdk_display_supports_cursor_alpha() and
 328  * gdk_display_supports_cursor_color() can be used to determine
 329  * whether RGBA cursors are supported;
 330  * gdk_display_get_default_cursor_size() and
 331  * gdk_display_get_maximal_cursor_size() give information about
 332  * cursor sizes.
 333  *
 334  * If @x or @y are <literal>-1</literal>, the pixbuf must have
 335  * options named "x_hot" and "y_hot", resp., containing
 336  * integer values between %0 and the width resp. height of
 337  * the pixbuf. (Since: 3.0)
 338  *
 339  * On the X backend, support for RGBA cursors requires a
 340  * sufficently new version of the X Render extension.
 341  *
 342  * Returns: a new #GdkCursor.
 343  *
 344  * Since: 2.4
 345  */
 346 GdkCursor *
 347 gdk_cursor_new_from_pixbuf (GdkDisplay *display,
 348                             GdkPixbuf  *pixbuf,
 349                             gint        x,
 350                             gint        y)
 351 {
 352   g_return_val_if_fail (GDK_IS_DISPLAY (display), NULL);
 353   g_return_val_if_fail (GDK_IS_PIXBUF (pixbuf), NULL);
 354
 355   return GDK_DISPLAY_GET_CLASS (display)->get_cursor_for_pixbuf (display, pixbuf, x, y);
 356 }
 357
 358 /**
 359  * gdk_cursor_get_display:
 360  * @cursor: a #GdkCursor.
 361  *
 362  * Returns the display on which the #GdkCursor is defined.
 363  *
 364  * Returns: (transfer none): the #GdkDisplay associated to @cursor
 365  *
 366  * Since: 2.2
 367  */
 368
 369 GdkDisplay *
 370 gdk_cursor_get_display (GdkCursor *cursor)
 371 {
 372   g_return_val_if_fail (GDK_IS_CURSOR (cursor), NULL);
 373
 374   return cursor->display;
 375 }
 376
 377 /**
 378  * gdk_cursor_get_image:
 379  * @cursor: a #GdkCursor
 380  *
 381  * Returns a #GdkPixbuf with the image used to display the cursor.
 382  *
 383  * Note that depending on the capabilities of the windowing system and
 384  * on the cursor, GDK may not be able to obtain the image data. In this
 385  * case, %NULL is returned.
 386  *
 387  * Returns: (transfer full): a #GdkPixbuf representing @cursor, or %NULL
 388  *
 389  * Since: 2.8
 390  */
 391 GdkPixbuf*
 392 gdk_cursor_get_image (GdkCursor *cursor)
 393 {
 394   g_return_val_if_fail (GDK_IS_CURSOR (cursor), NULL);
 395
 396   return GDK_CURSOR_GET_CLASS (cursor)->get_image (cursor);
 397 }