* 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/>.
*/
/*
#include "config.h"
+#define GDK_DISABLE_DEPRECATION_WARNINGS 1
+
#include "gdkmain.h"
#include "gdkinternals.h"
* @Title: General
*
* This section describes the GDK initialization functions and miscellaneous
- * utility functions.
+ * utility functions, as well as deprecation facilities.
+ *
+ * The GDK and GTK+ headers annotate deprecated APIs in a way that produces
+ * compiler warnings if these deprecated APIs are used. The warnings
+ * can be turned off by defining the macro %GDK_DISABLE_DEPRECATION_WARNINGS
+ * before including the glib.h header.
+ *
+ * GDK and GTK+ also provide support for building applications against
+ * defined subsets of deprecated or new APIs. Define the macro
+ * %GDK_VERSION_MIN_REQUIRED to specify up to what version
+ * you want to receive warnings about deprecated APIs. Define the
+ * macro %GDK_VERSION_MAX_ALLOWED to specify the newest version
+ * whose API you want to use.
+ */
+
+/**
+ * GDK_WINDOWING_X11:
+ *
+ * The #GDK_WINDOWING_X11 macro is defined if the X11 backend
+ * is supported.
+ *
+ * Use this macro to guard code that is specific to the X11 backend.
+ */
+
+/**
+ * GDK_WINDOWING_WIN32:
+ *
+ * The #GDK_WINDOWING_WIN32 macro is defined if the Win32 backend
+ * is supported.
+ *
+ * Use this macro to guard code that is specific to the Win32 backend.
*/
+/**
+ * GDK_WINDOWING_QUARTZ:
+ *
+ * The #GDK_WINDOWING_QUARTZ macro is defined if the Quartz backend
+ * is supported.
+ *
+ * Use this macro to guard code that is specific to the Quartz backend.
+ */
+
+/**
+ * GDK_DISABLE_DEPRECATION_WARNINGS:
+ *
+ * A macro that should be defined before including the gdk.h header.
+ * If it is defined, no compiler warnings will be produced for uses
+ * of deprecated GDK APIs.
+ */
typedef struct _GdkPredicate GdkPredicate;
static gchar *gdk_progclass = NULL;
-static GMutex *gdk_threads_mutex = NULL; /* Global GDK lock */
+static GMutex gdk_threads_mutex;
static GCallback gdk_threads_lock = NULL;
static GCallback gdk_threads_unlock = NULL;
{"dnd", GDK_DEBUG_DND},
{"xim", GDK_DEBUG_XIM},
{"nograbs", GDK_DEBUG_NOGRABS},
- {"colormap", GDK_DEBUG_COLORMAP},
{"input", GDK_DEBUG_INPUT},
{"cursor", GDK_DEBUG_CURSOR},
{"multihead", GDK_DEBUG_MULTIHEAD},
{"xinerama", GDK_DEBUG_XINERAMA},
{"draw", GDK_DEBUG_DRAW},
- {"eventloop", GDK_DEBUG_EVENTLOOP}
+ {"eventloop", GDK_DEBUG_EVENTLOOP},
+ {"frames", GDK_DEBUG_FRAMES}
};
static gboolean
/**
* gdk_add_option_entries_libgtk_only:
* @group: An option group.
- *
+ *
* Appends gdk option entries to the passed in option group. This is
* not public API and must not be used by applications.
- **/
+ */
void
gdk_add_option_entries_libgtk_only (GOptionGroup *group)
{
g_option_group_add_entries (group, gdk_args);
- g_option_group_add_entries (group, _gdk_windowing_args);
}
void
gdk_pre_parse_libgtk_only (void)
{
+ const char *rendering_mode;
+
gdk_initialized = TRUE;
/* We set the fallback program class here, rather than lazily in
if (getenv ("GDK_NATIVE_WINDOWS"))
{
- _gdk_native_windows = TRUE;
- /* Ensure that this is not propagated to spawned applications */
+ g_warning ("The GDK_NATIVE_WINDOWS environment variable is not supported in GTK3.\n"
+ "See the documentation for gdk_window_ensure_native() on how to get native windows.");
g_unsetenv ("GDK_NATIVE_WINDOWS");
}
- g_type_init ();
+ rendering_mode = g_getenv ("GDK_RENDERING");
+ if (rendering_mode)
+ {
+ if (g_str_equal (rendering_mode, "similar"))
+ _gdk_rendering_mode = GDK_RENDERING_MODE_SIMILAR;
+ else if (g_str_equal (rendering_mode, "image"))
+ _gdk_rendering_mode = GDK_RENDERING_MODE_IMAGE;
+ else if (g_str_equal (rendering_mode, "recording"))
+ _gdk_rendering_mode = GDK_RENDERING_MODE_RECORDING;
+ }
/* Do any setup particular to the windowing system */
gdk_display_manager_get ();
/**
* gdk_parse_args:
* @argc: the number of command line arguments.
- * @argv: the array of command line arguments.
+ * @argv: (inout) (array length=argc): the array of command line arguments.
*
* Parse command line arguments, and store for future
* use by calls to gdk_display_open().
g_option_context_set_main_group (option_context, option_group);
g_option_group_add_entries (option_group, gdk_args);
- g_option_group_add_entries (option_group, _gdk_windowing_args);
if (!g_option_context_parse (option_context, argc, argv, &error))
{
*
* Since: 2.2
*/
-G_CONST_RETURN gchar *
+const gchar *
gdk_get_display_arg_name (void)
{
if (!_gdk_display_arg_name)
* @argc: (inout): the number of command line arguments.
* @argv: (array length=argc) (inout): the array of command line arguments.
*
- * Initializes the GDK library and connects to the X server, returning %TRUE on
- * success.
+ * Initializes the GDK library and connects to the windowing system,
+ * returning %TRUE on success.
*
- * Any arguments used by GDK are removed from the array and @argc and @argv are
- * updated accordingly.
+ * Any arguments used by GDK are removed from the array and @argc and @argv
+ * are updated accordingly.
*
- * GTK+ initializes GDK in gtk_init() and so this function is not usually needed
- * by GTK+ applications.
+ * GTK+ initializes GDK in gtk_init() and so this function is not usually
+ * needed by GTK+ applications.
*
* Returns: %TRUE if initialization succeeded.
*/
* @argc: (inout): the number of command line arguments.
* @argv: (array length=argc) (inout): the array of command line arguments.
*
- * Initializes the GDK library and connects to the X server.
+ * Initializes the GDK library and connects to the windowing system.
* If initialization fails, a warning message is output and the application
* terminates with a call to <literal>exit(1)</literal>.
*
- * Any arguments used by GDK are removed from the array and @argc and @argv are
- * updated accordingly.
+ * Any arguments used by GDK are removed from the array and @argc and @argv
+ * are updated accordingly.
*
- * GTK+ initializes GDK in gtk_init() and so this function is not usually needed
- * by GTK+ applications.
+ * GTK+ initializes GDK in gtk_init() and so this function is not usually
+ * needed by GTK+ applications.
*/
void
gdk_init (int *argc, char ***argv)
* which protects all use of GTK+. That is, only one thread can use GTK+
* at any given time.
*
- * Unfortunately the above holds with the X11 backend only. With the
- * Win32 backend, GDK calls should not be attempted from multiple threads
- * at all.
- *
- * You must call g_thread_init() and gdk_threads_init() before executing
- * any other GTK+ or GDK functions in a threaded GTK+ program.
+ * You must call gdk_threads_init() before executing any other GTK+ or
+ * GDK functions in a threaded GTK+ program.
*
- * Idles, timeouts, and input functions from GLib, such as g_idle_add(), are
- * executed outside of the main GTK+ lock.
- * So, if you need to call GTK+ inside of such a callback, you must surround
- * the callback with a gdk_threads_enter()/gdk_threads_leave() pair or use
+ * Idles, timeouts, and input functions from GLib, such as g_idle_add(),
+ * are executed outside of the main GTK+ lock. So, if you need to call
+ * GTK+ inside of such a callback, you must surround the callback with
+ * a gdk_threads_enter()/gdk_threads_leave() pair or use
* gdk_threads_add_idle_full() which does this for you.
* However, event dispatching from the mainloop is still executed within
* the main GTK+ lock, so callback functions connected to event signals
* {
* GtkWidget *window;
*
- * g_thread_init (NULL);
* gdk_threads_init (<!-- -->);
* gdk_threads_enter (<!-- -->);
*
* pthread_t no_tid, yes_tid;
*
* /<!---->* init threads *<!---->/
- * g_thread_init (NULL);
* gdk_threads_init (<!-- -->);
* gdk_threads_enter (<!-- -->);
*
* }
* </programlisting>
* </informalexample>
+ *
+ * Unfortunately, all of the above documentation holds with the X11
+ * backend only. With the Win32 backend, GDK and GTK+ calls should not
+ * be attempted from multiple threads at all. Combining the GDK lock
+ * with other locks such as the Python global interpreter lock can be
+ * complicated.
+ *
+ * For these reason, the threading support has been deprecated in
+ * GTK+ 3.6. Instead of calling GTK+ directly from multiple threads,
+ * it is recommended to use g_idle_add(), g_main_context_invoke()
+ * and similar functions to make these calls from the main thread
+ * instead. The main thread is the thread which has called gtk_init()
+ * and is running the GTK+ mainloop. GTK+ itself will continue to
+ * use the GDK lock internally as long as the deprecated functionality
+ * is still available, and other libraries should probably do the same.
*/
/**
* gdk_threads_enter:
*
- * This macro marks the beginning of a critical section in which GDK and
- * GTK+ functions can be called safely and without causing race
- * conditions. Only one thread at a time can be in such a critial
+ * This function marks the beginning of a critical section in which
+ * GDK and GTK+ functions can be called safely and without causing race
+ * conditions. Only one thread at a time can be in such a critial
* section.
+ *
+ * Deprecated:3.6: All GDK and GTK+ calls should be made from the main
+ * thread
*/
void
gdk_threads_enter (void)
* gdk_threads_leave:
*
* Leaves a critical region begun with gdk_threads_enter().
+ *
+ * Deprecated:3.6: All GDK and GTK+ calls should be made from the main
+ * thread
*/
void
gdk_threads_leave (void)
static void
gdk_threads_impl_lock (void)
{
- if (gdk_threads_mutex)
- g_mutex_lock (gdk_threads_mutex);
+ g_mutex_lock (&gdk_threads_mutex);
}
static void
gdk_threads_impl_unlock (void)
{
- if (gdk_threads_mutex)
- g_mutex_unlock (gdk_threads_mutex);
+ g_mutex_unlock (&gdk_threads_mutex);
}
/**
*
* Initializes GDK so that it can be used from multiple threads
* in conjunction with gdk_threads_enter() and gdk_threads_leave().
- * g_thread_init() must be called previous to this function.
*
* This call must be made before any use of the main loop from
* GTK+; to be safe, call it before gtk_init().
- **/
+ *
+ * Deprecated:3.6: All GDK and GTK+ calls should be made from the main
+ * thread
+ */
void
gdk_threads_init (void)
{
- if (!g_thread_supported ())
- g_error ("g_thread_init() must be called before gdk_threads_init()");
-
- gdk_threads_mutex = g_mutex_new ();
if (!gdk_threads_lock)
gdk_threads_lock = gdk_threads_impl_lock;
if (!gdk_threads_unlock)
}
/**
- * gdk_threads_set_lock_functions:
+ * gdk_threads_set_lock_functions: (skip)
* @enter_fn: function called to guard GDK
* @leave_fn: function called to release the guard
*
* This method must be called before gdk_threads_init(), and cannot
* be called multiple times.
*
+ * Deprecated:3.6: All GDK and GTK+ calls should be made from the main
+ * thread
+ *
* Since: 2.4
**/
void
GdkThreadsDispatch *dispatch = data;
gboolean ret = FALSE;
- GDK_THREADS_ENTER ();
+ gdk_threads_enter ();
if (!g_source_is_destroyed (g_main_current_source ()))
ret = dispatch->func (dispatch->data);
- GDK_THREADS_LEAVE ();
+ gdk_threads_leave ();
return ret;
}
/**
* gdk_threads_add_idle_full:
* @priority: the priority of the idle source. Typically this will be in the
- * range btweeen #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE
+ * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE
* @function: function to call
* @data: data to pass to @function
* @notify: (allow-none): function to call when the idle is removed, or %NULL
* removed from the list of event sources and will not be called again.
*
* This variant of g_idle_add_full() calls @function with the GDK lock
- * held. It can be thought of a MT-safe version for GTK+ widgets for the
+ * held. It can be thought of a MT-safe version for GTK+ widgets for the
* following use case, where you have to worry about idle_callback()
* running in thread A and accessing @self after it has been finalized
* in thread B:
* Return value: the ID (greater than 0) of the event source.
*
* Since: 2.12
+ * Rename to: gdk_threads_add_idle
*/
guint
gdk_threads_add_idle_full (gint priority,
}
/**
- * gdk_threads_add_idle:
+ * gdk_threads_add_idle: (skip)
* @function: function to call
* @data: data to pass to @function
*
*
* self->timeout_id = 0;
*
- * return FALSE;
+ * return G_SOURCE_REMOVE;
* }
*
* static void some_widget_do_stuff_later (SomeWidget *self)
* Return value: the ID (greater than 0) of the event source.
*
* Since: 2.12
+ * Rename to: gdk_threads_add_timeout
*/
guint
gdk_threads_add_timeout_full (gint priority,
}
/**
- * gdk_threads_add_timeout:
+ * gdk_threads_add_timeout: (skip)
* @interval: the time between calls to the function, in milliseconds
* (1/1000ths of a second)
* @function: function to call
* @interval: the time between calls to the function, in seconds
* @function: function to call
* @data: data to pass to @function
- * @notify: (allow-none): function to call when the timeout is removed, or %NULL
+ * @notify: (allow-none): function to call when the timeout is removed, or %NULL
*
- * A variant of gdk_threads_add_timout_full() with second-granularity.
+ * A variant of gdk_threads_add_timeout_full() with second-granularity.
* See g_timeout_add_seconds_full() for a discussion of why it is
* a good idea to use this function if you don't need finer granularity.
*
* Return value: the ID (greater than 0) of the event source.
*
* Since: 2.14
+ * Rename to: gdk_threads_add_timeout_seconds
*/
guint
gdk_threads_add_timeout_seconds_full (gint priority,
}
/**
- * gdk_threads_add_timeout_seconds:
+ * gdk_threads_add_timeout_seconds: (skip)
* @interval: the time between calls to the function, in seconds
* @function: function to call
* @data: data to pass to @function
*
* Returns: the program class.
*/
-G_CONST_RETURN char *
+const char *
gdk_get_program_class (void)
{
return gdk_progclass;
* any way and doesn't observe the presence of XInput 2.
*
* Since: 3.0
- **/
+ */
void
gdk_disable_multidevice (void)
{