* Library General Public License for more details.
*
* You should have received a copy of the GNU Library 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/>.
*/
#include "config.h"
+#include "gdkinternals.h"
#include "gdkscreenprivate.h"
#include "gdkrectangle.h"
#include "gdkwindow.h"
* @Short_description: Object representing a physical screen
* @Title: GdkScreen
*
- * #GdkScreen objects are the GDK representation of a physical screen. It is used
- * throughout GDK and GTK+ to specify which screen the top level windows
- * are to be displayed on.
- * It is also used to query the screen specification and default settings such as
- * the screen width (gdk_screen_get_width()), etc.
- *
- * Note that a screen may consist of multiple monitors which are merged to
- * form a large screen area.
+ * #GdkScreen objects are the GDK representation of the screen on
+ * which windows can be displayed and on which the pointer moves.
+ * X originally identified screens with physical screens, but
+ * nowadays it is more common to have a single #GdkScreen which
+ * combines several physical monitors (see gdk_screen_get_n_monitors()).
+ *
+ * GdkScreen is used throughout GDK and GTK+ to specify which screen
+ * the top level windows are to be displayed on. it is also used to
+ * query the screen specification and default settings such as
+ * the default visual (gdk_screen_get_system_visual()), the dimensions
+ * of the physical monitors (gdk_screen_get_monitor_geometry()), etc.
*/
* gdk_screen_get_monitor_at_window:
* @screen: a #GdkScreen.
* @window: a #GdkWindow
- * @returns: the monitor number in which most of @window is located,
- * or if @window does not intersect any monitors, a monitor,
- * close to @window.
*
- * Returns the number of the monitor in which the largest area of the
+ * Returns the number of the monitor in which the largest area of the
* bounding rectangle of @window resides.
*
+ * Returns: the monitor number in which most of @window is located,
+ * or if @window does not intersect any monitors, a monitor,
+ * close to @window.
+ *
* Since: 2.2
**/
gint
GdkDisplay *
gdk_screen_get_display (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_display (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_display (screen);
}
gint
gdk_screen_get_width (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_width (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_width (screen);
}
/**
gint
gdk_screen_get_height (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_height (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_height (screen);
}
/**
gint
gdk_screen_get_width_mm (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_width_mm (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_width_mm (screen);
}
/**
gint
gdk_screen_get_height_mm (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_height_mm (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_height_mm (screen);
}
/**
gint
gdk_screen_get_number (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_number (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_number (screen);
}
/**
GdkWindow *
gdk_screen_get_root_window (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_root_window (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_root_window (screen);
}
/**
gint
gdk_screen_get_n_monitors (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_n_monitors (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_n_monitors (screen);
}
/**
gint
gdk_screen_get_primary_monitor (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_primary_monitor (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), 0);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_primary_monitor (screen);
}
/**
gdk_screen_get_monitor_width_mm (GdkScreen *screen,
gint monitor_num)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_monitor_width_mm (screen, monitor_num);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), -1);
+ g_return_val_if_fail (monitor_num >= 0, -1);
+ g_return_val_if_fail (monitor_num < gdk_screen_get_n_monitors (screen), -1);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_monitor_width_mm (screen, monitor_num);
}
/**
gdk_screen_get_monitor_height_mm (GdkScreen *screen,
gint monitor_num)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_monitor_height_mm (screen, monitor_num);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), -1);
+ g_return_val_if_fail (monitor_num >= 0, -1);
+ g_return_val_if_fail (monitor_num < gdk_screen_get_n_monitors (screen), -1);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_monitor_height_mm (screen, monitor_num);
}
/**
gdk_screen_get_monitor_plug_name (GdkScreen *screen,
gint monitor_num)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_monitor_plug_name (screen, monitor_num);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
+ g_return_val_if_fail (monitor_num >= 0, NULL);
+ g_return_val_if_fail (monitor_num < gdk_screen_get_n_monitors (screen), NULL);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_monitor_plug_name (screen, monitor_num);
}
/**
* gdk_screen_get_monitor_geometry:
* @screen: a #GdkScreen
- * @monitor_num: the monitor number, between 0 and gdk_screen_get_n_monitors (screen)
- * @dest: (out) (allow-none): a #GdkRectangle to be filled with the monitor geometry
+ * @monitor_num: the monitor number
+ * @dest: (out) (allow-none): a #GdkRectangle to be filled with
+ * the monitor geometry
*
* Retrieves the #GdkRectangle representing the size and position of
* the individual monitor within the entire screen area.
*
+ * Monitor numbers start at 0. To obtain the number of monitors of
+ * @screen, use gdk_screen_get_n_monitors().
+ *
* Note that the size of the entire screen area can be retrieved via
* gdk_screen_get_width() and gdk_screen_get_height().
*
gint monitor_num,
GdkRectangle *dest)
{
+ g_return_if_fail (GDK_IS_SCREEN (screen));
+ g_return_if_fail (monitor_num >= 0);
+ g_return_if_fail (monitor_num < gdk_screen_get_n_monitors (screen));
+
GDK_SCREEN_GET_CLASS(screen)->get_monitor_geometry (screen, monitor_num, dest);
}
+/**
+ * gdk_screen_get_monitor_workarea:
+ * @screen: a #GdkScreen
+ * @monitor_num: the monitor number
+ * @dest: (out) (allow-none): a #GdkRectangle to be filled with
+ * the monitor workarea
+ *
+ * Retrieves the #GdkRectangle representing the size and position of
+ * the "work area" on a monitor within the entire screen area.
+ *
+ * The work area should be considered when positioning menus and
+ * similar popups, to avoid placing them below panels, docks or other
+ * desktop components.
+ *
+ * Monitor numbers start at 0. To obtain the number of monitors of
+ * @screen, use gdk_screen_get_n_monitors().
+ *
+ * Since: 3.4
+ */
+void
+gdk_screen_get_monitor_workarea (GdkScreen *screen,
+ gint monitor_num,
+ GdkRectangle *dest)
+{
+ g_return_if_fail (GDK_IS_SCREEN (screen));
+ g_return_if_fail (monitor_num >= 0);
+ g_return_if_fail (monitor_num < gdk_screen_get_n_monitors (screen));
+
+ GDK_SCREEN_GET_CLASS (screen)->get_monitor_workarea (screen, monitor_num, dest);
+}
+
/**
* gdk_screen_list_visuals:
* @screen: the relevant #GdkScreen.
GList *
gdk_screen_list_visuals (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->list_visuals (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
+
+ return GDK_SCREEN_GET_CLASS (screen)->list_visuals (screen);
}
/**
GdkVisual *
gdk_screen_get_system_visual (GdkScreen * screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_system_visual (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_system_visual (screen);
}
/**
GdkVisual *
gdk_screen_get_rgba_visual (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_rgba_visual (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_rgba_visual (screen);
}
/**
gboolean
gdk_screen_is_composited (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->is_composited (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), FALSE);
+
+ return GDK_SCREEN_GET_CLASS (screen)->is_composited (screen);
}
/**
gchar *
gdk_screen_make_display_name (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->make_display_name (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
+
+ return GDK_SCREEN_GET_CLASS (screen)->make_display_name (screen);
}
/**
GdkWindow *
gdk_screen_get_active_window (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_active_window (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_active_window (screen);
}
/**
GList *
gdk_screen_get_window_stack (GdkScreen *screen)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_window_stack (screen);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), NULL);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_window_stack (screen);
}
/**
const gchar *name,
GValue *value)
{
- return GDK_SCREEN_GET_CLASS(screen)->get_setting (screen, name, value);
+ g_return_val_if_fail (GDK_IS_SCREEN (screen), FALSE);
+ g_return_val_if_fail (name != NULL, FALSE);
+ g_return_val_if_fail (value != NULL, FALSE);
+
+ return GDK_SCREEN_GET_CLASS (screen)->get_setting (screen, name, value);
}
projects / ~andy / gtk / blobdiff