]> Pileus Git - ~andy/gtk/blobdiff - gtk/gtkwindow.c
Minor documentation improvements
[~andy/gtk] / gtk / gtkwindow.c
index e69c0185bd285bdcfb0e343bdfcab8e353c38ef4..98b5c86dd0c381245350f9ec6adcd31dc166330e 100644 (file)
@@ -336,8 +336,6 @@ static gint gtk_window_focus_in_event     (GtkWidget         *widget,
 static gint gtk_window_focus_out_event    (GtkWidget         *widget,
                                           GdkEventFocus     *event);
 static void gtk_window_style_updated      (GtkWidget         *widget);
-static gint gtk_window_client_event      (GtkWidget         *widget,
-                                          GdkEventClient    *event);
 static gboolean gtk_window_state_event    (GtkWidget          *widget,
                                            GdkEventWindowState *event);
 static void gtk_window_check_resize       (GtkContainer      *container);
@@ -575,7 +573,6 @@ gtk_window_class_init (GtkWindowClass *klass)
   widget_class->focus_in_event = gtk_window_focus_in_event;
   widget_class->button_press_event = gtk_window_button_press_event;
   widget_class->focus_out_event = gtk_window_focus_out_event;
-  widget_class->client_event = gtk_window_client_event;
   widget_class->focus = gtk_window_focus;
   widget_class->move_focus = gtk_window_move_focus;
   widget_class->draw = gtk_window_draw;
@@ -861,7 +858,7 @@ gtk_window_class_init (GtkWindowClass *klass)
                                                          GTK_PARAM_READWRITE));
 
   /**
-   * GtkWindow: resize-grip-visible:
+   * GtkWindow:resize-grip-visible:
    *
    * Whether a corner resize grip is currently shown.
    *
@@ -943,15 +940,18 @@ gtk_window_class_init (GtkWindowClass *klass)
                                                              0, G_MAXINT, 16, GTK_PARAM_READWRITE));
 
 
-  /* Signals
-   */
   /**
    * GtkWindow:application:
    *
    * The #GtkApplication associated with the window.
    *
-   * The application will be kept alive for at least as long as the
-   * window is open.
+   * The application will be kept alive for at least as long as it
+   * has any windows associated with it (see g_application_hold()
+   * for a way to keep it alive without windows).
+   *
+   * Normally, the connection between the application and the window
+   * will remain until the window is destroyed, but you can explicitly
+   * remove it by setting the ::application property to %NULL.
    *
    * Since: 3.0
    */
@@ -1108,8 +1108,9 @@ gtk_window_init (GtkWindow *window)
   priv->has_user_ref_count = TRUE;
   toplevel_list = g_slist_prepend (toplevel_list, window);
 
-  g_signal_connect (priv->screen, "composited-changed",
-                   G_CALLBACK (gtk_window_on_composited_changed), window);
+  if (priv->screen)
+    g_signal_connect (priv->screen, "composited-changed",
+                      G_CALLBACK (gtk_window_on_composited_changed), window);
 }
 
 static void
@@ -2291,50 +2292,6 @@ gtk_window_list_toplevels (void)
   return list;
 }
 
-void
-gtk_window_add_embedded_xid (GtkWindow *window, GdkNativeWindow xid)
-{
-  GList *embedded_windows;
-
-  g_return_if_fail (GTK_IS_WINDOW (window));
-
-  embedded_windows = g_object_get_qdata (G_OBJECT (window), quark_gtk_embedded);
-  if (embedded_windows)
-    g_object_steal_qdata (G_OBJECT (window), quark_gtk_embedded);
-  embedded_windows = g_list_prepend (embedded_windows,
-                                    GUINT_TO_POINTER (xid));
-
-  g_object_set_qdata_full (G_OBJECT (window), quark_gtk_embedded, 
-                          embedded_windows,
-                          embedded_windows ?
-                          (GDestroyNotify) g_list_free : NULL);
-}
-
-void
-gtk_window_remove_embedded_xid (GtkWindow *window, GdkNativeWindow xid)
-{
-  GList *embedded_windows;
-  GList *node;
-
-  g_return_if_fail (GTK_IS_WINDOW (window));
-  
-  embedded_windows = g_object_get_qdata (G_OBJECT (window), quark_gtk_embedded);
-  if (embedded_windows)
-    g_object_steal_qdata (G_OBJECT (window), quark_gtk_embedded);
-
-  node = g_list_find (embedded_windows, GUINT_TO_POINTER (xid));
-  if (node)
-    {
-      embedded_windows = g_list_remove_link (embedded_windows, node);
-      g_list_free_1 (node);
-    }
-  
-  g_object_set_qdata_full (G_OBJECT (window), quark_gtk_embedded,
-                          embedded_windows,
-                          embedded_windows ?
-                          (GDestroyNotify) g_list_free : NULL);
-}
-
 static void
 gtk_window_dispose (GObject *object)
 {
@@ -2598,7 +2555,7 @@ gtk_window_get_opacity (GtkWindow *window)
  *
  * Gets the #GtkApplication associated with the window (if any).
  *
- * Return value: a #GtkApplication, or %NULL
+ * Return value: (transfer none): a #GtkApplication, or %NULL
  *
  * Since: 3.0
  **/
@@ -2629,7 +2586,7 @@ gtk_window_release_application (GtkWindow *window)
 /**
  * gtk_window_set_application:
  * @window: a #GtkWindow
- * @application: a #GtkApplication, or %NULL
+ * @application: (allow-none): a #GtkApplication, or %NULL
  *
  * Sets or unsets the #GtkApplication associated with the window.
  *
@@ -3426,7 +3383,7 @@ gtk_window_unrealize_icon (GtkWindow *window)
 /**
  * gtk_window_set_icon_list:
  * @window: a #GtkWindow
- * @list: (element-type GdkPixbuf) (transfer container): list of #GdkPixbuf
+ * @list: (element-type GdkPixbuf): list of #GdkPixbuf
  *
  * Sets up the icon representing a #GtkWindow. The icon is used when
  * the window is minimized (also known as iconified).  Some window
@@ -3686,7 +3643,7 @@ load_pixbuf_verbosely (const char *filename,
 /**
  * gtk_window_set_icon_from_file:
  * @window: a #GtkWindow
- * @filename: location of icon file
+ * @filename: (type filename): location of icon file
  * @err: (allow-none): location to store error, or %NULL.
  *
  * Sets the icon for @window.  
@@ -3864,7 +3821,7 @@ gtk_window_get_default_icon_name (void)
 
 /**
  * gtk_window_set_default_icon_from_file:
- * @filename: location of icon file
+ * @filename: (type filename): location of icon file
  * @err: (allow-none): location to store error, or %NULL.
  *
  * Sets an icon to be used as fallback for windows that haven't
@@ -4252,9 +4209,9 @@ gtk_window_get_size (GtkWindow *window,
  * gdk_screen_height () - window_height)</literal> (note that this
  * example does not take multi-head scenarios into account).
  *
- * The Extended Window Manager Hints specification at <ulink 
+ * The Extended Window Manager Hints specification at <ulink
  * url="http://www.freedesktop.org/Standards/wm-spec">
- * http://www.freedesktop.org/Standards/wm-spec</ulink> has a 
+ * http://www.freedesktop.org/Standards/wm-spec</ulink> has a
  * nice table of gravities in the "implementation notes" section.
  *
  * The gtk_window_get_position() documentation may also be relevant.
@@ -4264,17 +4221,15 @@ gtk_window_move (GtkWindow *window,
                  gint       x,
                  gint       y)
 {
-  GtkWindowPrivate *priv;
   GtkWindowGeometryInfo *info;
   GtkWidget *widget;
-  
+
   g_return_if_fail (GTK_IS_WINDOW (window));
 
-  priv = window->priv;
   widget = GTK_WIDGET (window);
 
   info = gtk_window_get_geometry_info (window, TRUE);  
-  
+
   if (gtk_widget_get_mapped (widget))
     {
       GtkAllocation allocation;
@@ -4297,7 +4252,7 @@ gtk_window_move (GtkWindow *window,
       gtk_window_constrain_position (window,
                                      allocation.width, allocation.height,
                                      &x, &y);
-      
+
       /* Note that this request doesn't go through our standard request
        * framework, e.g. doesn't increment configure_request_count,
        * doesn't set info->last, etc.; that's because
@@ -4584,6 +4539,7 @@ gtk_window_show (GtkWidget *widget)
   GtkWindowPrivate *priv = window->priv;
   GtkContainer *container = GTK_CONTAINER (window);
   gboolean need_resize;
+  gboolean is_plug;
 
   if (!gtk_widget_is_toplevel (GTK_WIDGET (widget)))
     {
@@ -4655,7 +4611,12 @@ gtk_window_show (GtkWidget *widget)
 
   /* Try to make sure that we have some focused widget
    */
-  if (!priv->focus_widget && !GTK_IS_PLUG (window))
+#ifdef GDK_WINDOWING_X11
+  is_plug = GTK_IS_PLUG (window);
+#else
+  is_plug = FALSE;
+#endif
+  if (!priv->focus_widget && !is_plug)
     gtk_window_move_focus (widget, GTK_DIR_TAB_FORWARD);
   
   if (priv->modal)
@@ -4889,8 +4850,7 @@ gtk_window_realize (GtkWidget *widget)
       gtk_widget_set_window (widget, gdk_window);
       gdk_window_set_user_data (gdk_window, widget);
 
-      gtk_widget_style_attach (widget);
-      gtk_style_set_background (gtk_widget_get_style (widget), gdk_window, GTK_STATE_NORMAL);
+      gtk_style_context_set_background (gtk_widget_get_style_context (widget), gdk_window);
 
       gdk_window_enable_synchronized_configure (gdk_window);
       return;
@@ -5381,6 +5341,8 @@ gtk_window_style_updated (GtkWidget *widget)
   GtkWindowPrivate *priv = window->priv;
   GdkRectangle rect;
 
+  GTK_WIDGET_CLASS (gtk_window_parent_class)->style_updated (widget);
+
   if (priv->grip_window != NULL && gtk_window_get_resize_grip_area (window, &rect))
     {
       gdk_window_move_resize (priv->grip_window,
@@ -5520,7 +5482,7 @@ update_grip_visibility (GtkWindow *window)
  *
  * Determines whether a resize grip is visible for the specified window.
  *
- * Returns %TRUE if a resize grip exists and is visible.
+ * Returns: %TRUE if a resize grip exists and is visible
  *
  * Since: 3.0
  */
@@ -5567,7 +5529,7 @@ gtk_window_resize_grip_is_visible (GtkWindow *window)
  *
  * Determines whether the window may have a resize grip.
  *
- * Returns: %TRUE if the window has a resize grip.
+ * Returns: %TRUE if the window has a resize grip
  *
  * Since: 3.0
  */
@@ -5582,13 +5544,13 @@ gtk_window_get_has_resize_grip (GtkWindow *window)
 /**
  * gtk_window_get_resize_grip_area:
  * @window: a #GtkWindow
- * @rect: a pointer to a #GdkRectangle which we should store the
- *     resize grip area.
+ * @rect: (out): a pointer to a #GdkRectangle which we should store
+ *     the resize grip area
  *
  * If a window has a resize grip, this will retrieve the grip
  * position, width and height into the specified #GdkRectangle.
  *
- * Returns: %TRUE if the resize grip's area was retrieved.
+ * Returns: %TRUE if the resize grip's area was retrieved
  *
  * Since: 3.0
  */
@@ -5906,62 +5868,6 @@ gtk_window_focus_out_event (GtkWidget     *widget,
   return FALSE;
 }
 
-static GdkAtom atom_rcfiles = GDK_NONE;
-static GdkAtom atom_iconthemes = GDK_NONE;
-
-static void
-send_client_message_to_embedded_windows (GtkWidget *widget,
-                                        GdkAtom    message_type)
-{
-  GList *embedded_windows;
-
-  embedded_windows = g_object_get_qdata (G_OBJECT (widget), quark_gtk_embedded);
-  if (embedded_windows)
-    {
-      GdkEvent *send_event = gdk_event_new (GDK_CLIENT_EVENT);
-      int i;
-      
-      for (i = 0; i < 5; i++)
-       send_event->client.data.l[i] = 0;
-      send_event->client.data_format = 32;
-      send_event->client.message_type = message_type;
-      
-      while (embedded_windows)
-       {
-         GdkNativeWindow xid = GDK_GPOINTER_TO_NATIVE_WINDOW(embedded_windows->data);
-         gdk_event_send_client_message_for_display (gtk_widget_get_display (widget), send_event, xid);
-         embedded_windows = embedded_windows->next;
-       }
-
-      gdk_event_free (send_event);
-    }
-}
-
-static gint
-gtk_window_client_event (GtkWidget     *widget,
-                        GdkEventClient *event)
-{
-  if (!atom_rcfiles)
-    {
-      atom_rcfiles = gdk_atom_intern_static_string ("_GTK_READ_RCFILES");
-      atom_iconthemes = gdk_atom_intern_static_string ("_GTK_LOAD_ICONTHEMES");
-    }
-
-  if (event->message_type == atom_rcfiles) 
-    {
-      send_client_message_to_embedded_windows (widget, atom_rcfiles);
-      gtk_style_context_reset_widgets (gtk_widget_get_screen (widget));
-    }
-
-  if (event->message_type == atom_iconthemes) 
-    {
-      send_client_message_to_embedded_windows (widget, atom_iconthemes);
-      _gtk_icon_theme_check_reload (gtk_widget_get_display (widget));    
-    }
-
-  return FALSE;
-}
-
 static void
 gtk_window_check_resize (GtkContainer *container)
 {
@@ -6501,21 +6407,18 @@ gtk_window_compute_configure_request (GtkWindow    *window,
   GdkGeometry new_geometry;
   guint new_flags;
   int w, h;
-  GtkWidget *widget;
   GtkWindowPosition pos;
   GtkWidget *parent_widget;
   GtkWindowGeometryInfo *info;
   GdkScreen *screen;
   int x, y;
-  
-  widget = GTK_WIDGET (window);
 
   screen = gtk_window_check_screen (window);
 
   gtk_window_compute_hints (window, &new_geometry, &new_flags);
   gtk_window_compute_configure_request_size (window,
-                                            &new_geometry, new_flags,
-                                            (guint *)&w, (guint *)&h);
+                                             &new_geometry, new_flags,
+                                             (guint *)&w, (guint *)&h);
 
   gtk_window_constrain_size (window,
                              &new_geometry, new_flags,
@@ -6523,10 +6426,10 @@ gtk_window_compute_configure_request (GtkWindow    *window,
                              &w, &h);
 
   parent_widget = (GtkWidget*) priv->transient_parent;
-  
+
   pos = get_effective_position (window);
   info = gtk_window_get_geometry_info (window, FALSE);
-  
+
   /* by default, don't change position requested */
   if (info)
     {
@@ -6548,7 +6451,6 @@ gtk_window_compute_configure_request (GtkWindow    *window,
        *
        * Not sure how to go about that.
        */
-      
       switch (pos)
         {
           /* here we are only handling CENTER_ALWAYS
@@ -6559,7 +6461,7 @@ gtk_window_compute_configure_request (GtkWindow    *window,
         case GTK_WIN_POS_CENTER:
           center_window_on_monitor (window, w, h, &x, &y);
           break;
-      
+
         case GTK_WIN_POS_CENTER_ON_PARENT:
           {
             GtkAllocation allocation;
@@ -6567,7 +6469,7 @@ gtk_window_compute_configure_request (GtkWindow    *window,
             gint monitor_num;
             GdkRectangle monitor;
             gint ox, oy;
-            
+
             g_assert (gtk_widget_get_mapped (parent_widget)); /* established earlier */
 
             gdk_window = gtk_widget_get_window (parent_widget);
@@ -6601,8 +6503,8 @@ gtk_window_compute_configure_request (GtkWindow    *window,
           {
             gint screen_width = gdk_screen_get_width (screen);
             gint screen_height = gdk_screen_get_height (screen);
-           gint monitor_num;
-           GdkRectangle monitor;
+            gint monitor_num;
+            GdkRectangle monitor;
             GdkDisplay *display;
             GdkDeviceManager *device_manager;
             GdkDevice *pointer;
@@ -6621,7 +6523,7 @@ gtk_window_compute_configure_request (GtkWindow    *window,
               monitor_num = gdk_screen_get_monitor_at_point (screen, px, py);
             else
               monitor_num = -1;
-            
+
             x = px - w / 2;
             y = py - h / 2;
             x = CLAMP (x, 0, screen_width - w);
@@ -6651,7 +6553,7 @@ gtk_window_compute_configure_request (GtkWindow    *window,
       y = info->initial_y;
       gtk_window_constrain_position (window, w, h, &x, &y);
     }
-  
+
   request->x = x;
   request->y = y;
   request->width = w;
@@ -7990,16 +7892,13 @@ gtk_window_begin_resize_drag  (GtkWindow    *window,
                                gint          root_y,
                                guint32       timestamp)
 {
-  GtkWindowPrivate *priv;
   GtkWidget *widget;
   GdkWindow *toplevel;
-  
+
   g_return_if_fail (GTK_IS_WINDOW (window));
   widget = GTK_WIDGET (window);
   g_return_if_fail (gtk_widget_get_visible (widget));
 
-  priv = window->priv;
-
   toplevel = gtk_widget_get_window (widget);
 
   gdk_window_begin_resize_drag (toplevel,
@@ -8031,16 +7930,13 @@ gtk_window_begin_move_drag  (GtkWindow *window,
                              gint       root_y,
                              guint32    timestamp)
 {
-  GtkWindowPrivate *priv;
   GtkWidget *widget;
   GdkWindow *toplevel;
-  
+
   g_return_if_fail (GTK_IS_WINDOW (window));
   widget = GTK_WIDGET (window);
   g_return_if_fail (gtk_widget_get_visible (widget));
 
-  priv = window->priv;
-
   toplevel = gtk_widget_get_window (widget);
 
   gdk_window_begin_move_drag (toplevel,
@@ -8049,7 +7945,7 @@ gtk_window_begin_move_drag  (GtkWindow *window,
                               timestamp);
 }
 
-/** 
+/**
  * gtk_window_set_screen:
  * @window: a #GtkWindow.
  * @screen: a #GdkScreen.
@@ -8068,7 +7964,7 @@ gtk_window_set_screen (GtkWindow *window,
   GtkWidget *widget;
   GdkScreen *previous_screen;
   gboolean was_mapped;
-  
+
   g_return_if_fail (GTK_IS_WINDOW (window));
   g_return_if_fail (GDK_IS_SCREEN (screen));
 
@@ -8086,17 +7982,18 @@ gtk_window_set_screen (GtkWindow *window,
     gtk_widget_unmap (widget);
   if (gtk_widget_get_realized (widget))
     gtk_widget_unrealize (widget);
-      
+
   gtk_window_free_key_hash (window);
   priv->screen = screen;
   gtk_widget_reset_rc_styles (widget);
   if (screen != previous_screen)
     {
-      g_signal_handlers_disconnect_by_func (previous_screen,
-                                           gtk_window_on_composited_changed, window);
-      g_signal_connect (screen, "composited-changed", 
-                       G_CALLBACK (gtk_window_on_composited_changed), window);
-      
+      if (previous_screen)
+        g_signal_handlers_disconnect_by_func (previous_screen,
+                                              gtk_window_on_composited_changed, window);
+      g_signal_connect (screen, "composited-changed",
+                        G_CALLBACK (gtk_window_on_composited_changed), window);
+
       _gtk_widget_propagate_screen_changed (widget, previous_screen);
       _gtk_widget_propagate_composited_changed (widget);
     }
@@ -8336,8 +8233,8 @@ gtk_window_group_remove_window (GtkWindowGroup *window_group,
  *
  * Returns a list of the #GtkWindows that belong to @window_group.
  *
- * Returns: (element-type GtkWidget) (transfer container): A newly-allocated list of
- *   windows inside the group.
+ * Returns: (element-type GtkWindow) (transfer container): A
+ *   newly-allocated list of windows inside the group.
  *
  * Since: 2.14
  **/
@@ -8359,6 +8256,8 @@ gtk_window_group_list_windows (GtkWindowGroup *window_group)
        group_windows = g_list_prepend (group_windows, window);
     }
 
+  g_list_free (toplevels);
+
   return g_list_reverse (group_windows);
 }
 
@@ -8415,7 +8314,7 @@ gtk_window_has_group (GtkWindow *window)
  * Gets the current grab widget of the given group,
  * see gtk_grab_add().
  *
- * Returns: the current grab widget of the group
+ * Returns: (transfer none): the current grab widget of the group
  *
  * Since: 2.22
  */
@@ -8514,7 +8413,7 @@ _gtk_window_group_remove_device_grab (GtkWindowGroup *window_group,
  *
  * Returns the current grab widget for @device, or %NULL if none.
  *
- * Returns: The grab widget, or %NULL
+ * Returns: (transfer none): The grab widget, or %NULL
  *
  * Since: 3.0
  */
@@ -9216,11 +9115,10 @@ _gtk_window_set_is_active (GtkWindow *window,
  */
 void
 _gtk_window_set_is_toplevel (GtkWindow *window,
-                            gboolean   is_toplevel)
+                             gboolean   is_toplevel)
 {
   GtkWidget *widget;
   GtkWidget *toplevel;
-  gboolean   was_anchored;
 
   widget = GTK_WIDGET (window);
 
@@ -9232,8 +9130,6 @@ _gtk_window_set_is_toplevel (GtkWindow *window,
   if (is_toplevel == gtk_widget_is_toplevel (widget))
     return;
 
-  was_anchored = _gtk_widget_get_anchored (widget);
-
   if (is_toplevel)
     {
       /* Pass through regular pathways of an embedded toplevel
@@ -9248,21 +9144,21 @@ _gtk_window_set_is_toplevel (GtkWindow *window,
       gtk_widget_hide (widget);
 
       /* Save the toplevel this widget was previously anchored into before
-       * propagating a hierarchy-changed. 
+       * propagating a hierarchy-changed.
        *
        * Usually this happens by way of gtk_widget_unparent() and we are
        * already unanchored at this point, just adding this clause incase
        * things happen differently.
        */
       toplevel = gtk_widget_get_toplevel (widget);
-      if (!gtk_widget_is_toplevel (widget))
-       toplevel = NULL;
+      if (!gtk_widget_is_toplevel (toplevel))
+        toplevel = NULL;
 
       _gtk_widget_set_is_toplevel (widget, TRUE);
 
       /* When a window becomes toplevel after being embedded and anchored
-       * into another window we need to unset it's anchored flag so that
-       * the hierarchy changed signal kicks in properly. 
+       * into another window we need to unset its anchored flag so that
+       * the hierarchy changed signal kicks in properly.
        */
       _gtk_widget_set_anchored (widget, FALSE);
       _gtk_widget_propagate_hierarchy_changed (widget, toplevel);
@@ -9406,3 +9302,27 @@ _gtk_window_get_wmclass (GtkWindow  *window,
   *wmclass_name = priv->wmclass_name;
   *wmclass_class = priv->wmclass_class;
 }
+
+/**
+ * gtk_window_set_has_user_ref_count:
+ * @window: a #GtkWindow
+ * @setting: the new value
+ *
+ * Tells GTK+ whether to drop its extra reference to the window
+ * when gtk_window_destroy() is called.
+ *
+ * This function is only exported for the benefit of language
+ * bindings which may need to keep the window alive until their
+ * wrapper object is garbage collected. There is no justification
+ * for ever calling this function in an application.
+ *
+ * Since: 3.0
+ */
+void
+gtk_window_set_has_user_ref_count (GtkWindow *window,
+                                   gboolean   setting)
+{
+  g_return_if_fail (GTK_IS_WINDOW (window));
+
+  window->priv->has_user_ref_count = setting;
+}