From 32abeb4c969e28d58ad3aa34d05353d6b12476c6 Mon Sep 17 00:00:00 2001 From: Owen Taylor Date: Mon, 12 Feb 2001 17:50:13 +0000 Subject: [PATCH] Use the new snazzy mother-of-all-gtk-doc-makefiles. Sun Feb 11 22:16:34 2001 Owen Taylor * */Makefile.am: Use the new snazzy mother-of-all-gtk-doc-makefiles. * gdk/tmpl/* gdk-pixbuf/tmpl/*: Recover a bunch of docs that were lost at one point. --- docs/reference/ChangeLog | 7 + docs/reference/gdk-pixbuf/Makefile.am | 162 +- docs/reference/gdk-pixbuf/tmpl/animation.sgml | 61 +- docs/reference/gdk-pixbuf/tmpl/creating.sgml | 52 +- .../gdk-pixbuf/tmpl/file-loading.sgml | 32 +- .../gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml | 1346 ++-- .../gdk-pixbuf/tmpl/gdk-pixbuf-xlib-init.sgml | 31 +- .../reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml | 61 +- .../tmpl/initialization_versions.sgml | 25 - .../gdk-pixbuf/tmpl/refcounting.sgml | 71 +- docs/reference/gdk-pixbuf/tmpl/scaling.sgml | 107 +- docs/reference/gdk-pixbuf/tmpl/util.sgml | 26 +- docs/reference/gdk/Makefile.am | 143 +- docs/reference/gdk/tmpl/colors.sgml | 307 +- docs/reference/gdk/tmpl/drawing.sgml | 235 +- docs/reference/gdk/tmpl/fonts.sgml | 576 +- docs/reference/gdk/tmpl/gcs.sgml | 445 +- docs/reference/gdk/tmpl/gdk-unused.sgml | 1734 ++++- docs/reference/gdk/tmpl/images.sgml | 144 +- docs/reference/gdk/tmpl/regions.sgml | 38 +- docs/reference/gdk/tmpl/rgb.sgml | 403 +- docs/reference/gdk/tmpl/windows.sgml | 10 + docs/reference/gtk/Makefile.am | 126 +- docs/reference/gtk/tmpl/gtk-unused.sgml | 6518 +++++++++++------ .../reference/gtk/tmpl/gtktreeviewcolumn.sgml | 33 +- 25 files changed, 9093 insertions(+), 3600 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 17d6f702cc..8d9c0d7d3c 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,10 @@ +Sun Feb 11 22:16:34 2001 Owen Taylor + + * */Makefile.am: Use the new snazzy mother-of-all-gtk-doc-makefiles. + + * gdk/tmpl/* gdk-pixbuf/tmpl/*: Recover a bunch of docs that were + lost at one point. + 2001-02-08 Havoc Pennington * gtk/windows.sgml: windows (file is blank) diff --git a/docs/reference/gdk-pixbuf/Makefile.am b/docs/reference/gdk-pixbuf/Makefile.am index 9ac1083f77..00a9e48118 100644 --- a/docs/reference/gdk-pixbuf/Makefile.am +++ b/docs/reference/gdk-pixbuf/Makefile.am @@ -6,40 +6,34 @@ DOC_MODULE=gdk-pixbuf # The top-level SGML file. DOC_MAIN_SGML_FILE=gdk-pixbuf.sgml -# The directory containing the source code (if it contains documentation). -DOC_SOURCE_DIR=$(GDK_PIXBUF_DIR)/gdk-pixbuf -SECOND_DOC_SOURCE_DIR=$(top_srcdir)/contrib/gdk-pixbuf-xlib +# The directory containing the source code. Relative to $(srcdir) +DOC_SOURCE_DIR=../../../gdk-pixbuf + +# Extra options to supply to gtkdoc-scan +SCAN_OPTIONS=--source-dir=../../../contrib/gdk-pixbuf-xlib + +# Extra options to supply to gtkdoc-mkdb +MKDB_OPTIONS=--source-dir=../../../contrib/gdk-pixbuf-xlib # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS= +# Used for dependencies +HFILE_GLOB=$(top_srcdir)/gdk-pixbuf/*.h $(top_srcdir)/contrib/gdk-pixbuf-xlib/*.h +CFILE_GLOB=$(top_srcdir)/gdk-pixbuf/*.c $(top_srcdir)/contrib/gdk-pixbuf-xlib/*.c + # Header files to ignore when scanning -IGNORE_HFILES=pixops.h pixops-internal.h gdk-pixbuf-xlib-private.h gdk-pixbuf-i18n.h gdk-pixbuf-private.h +IGNORE_HFILES= \ + pixops \ + gdk-pixbuf-xlib-private.h \ + gdk-pixbuf-i18n.h \ + gdk-pixbuf-private.h # Extra files to add when scanning -EXTRA_HFILES= \ - $(top_srcdir)/gtk/gdk-pixbuf-loader.h +EXTRA_HFILES= -# CFLAGS and LDFLAGS for compiling scan program -CFLAGS= -LDFLAGS= - -tmpl_sources = \ - tmpl/animation.sgml \ - tmpl/creating.sgml \ - tmpl/file-loading.sgml \ - tmpl/gdk-pixbuf-loader.sgml \ - tmpl/gdk-pixbuf-unused.sgml \ - tmpl/gdk-pixbuf.sgml \ - tmpl/initialization_versions.sgml \ - tmpl/module_interface.sgml \ - tmpl/refcounting.sgml \ - tmpl/scaling.sgml \ - tmpl/util.sgml \ - tmpl/gdk-pixbuf-xlib-from-drawables.sgml \ - tmpl/gdk-pixbuf-xlib-init.sgml \ - tmpl/gdk-pixbuf-xlib-rendering.sgml \ - tmpl/gdk-pixbuf-xlib-rgb.sgml +# Images to copy into HTML directory +HTML_IMAGES = # Extra SGML files that are included by DOC_MAIN_SGML_FILE content_files = \ @@ -47,6 +41,30 @@ content_files = \ gdk-pixbuf.sgml \ porting-from-imlib.sgml +# Other files to distribute +extra_files = + +# CFLAGS and LDFLAGS for compiling scan program. Only needed +# if $(DOC_MODULE).types is non-empty. +GTKDOC_CFLAGS = @STRIP_BEGIN@ \ + @CFLAGS@ \ + -I$(top_srcdir) \ + @GLIB_CFLAGS@ \ + @more_cflags@ \ +@STRIP_END@ + +GTKDOC_LIBS = @STRIP_BEGIN@ \ + $(top_builddir)/gdk-pixbuf/libgdk_pixbuf-1.3.la \ + @more_ldflags@ \ + @more_libs@ \ + @GLIB_LIBS@ \ + -lm \ +@STRIP_END@ + +GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC) +GTKDOC_LD=$(LIBTOOL) --mode=link $(CC) + + #################################### # Everything below here is generic # #################################### @@ -54,47 +72,76 @@ content_files = \ TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) EXTRA_DIST = \ - $(DOC_MODULE).types \ - $(DOC_MAIN_SGML_FILE) \ $(content_files) \ + $(extra_files) \ + $(HTML_IMAGES) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE).types \ $(DOC_MODULE)-sections.txt \ $(DOC_MODULE)-overrides.txt +DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp + if ENABLE_GTK_DOC -all-local: html/index.html +all-local: html-build.stamp -$(DOC_MODULE)-decl.txt: - $(MAKE) scan +SCANOBJ_FILES = \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).signal -$(tmpl_sources): $(DOC_MODULE)-decl.txt $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt - $(MAKE) templates +scan-build.stamp: $(HFILE_GLOB) + @echo '*** Scanning header files ***' + cd $(srcdir) && ( \ + if grep -l '^.+$$' $(DOC_MODULE).types > /dev/null ; then \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) ; \ + else \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ + fi ) + cd $(srcdir) && \ + gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES) + touch scan-build.stamp -sgml/$(DOC_MODULE)-doc.bottom: $(tmpl_sources) $(DOC_MODULE)-decl.txt - $(MAKE) sgml +check_scan: + $(MAKE) scan-build.stamp -html/index.html: sgml/$(DOC_MODULE)-doc.bottom $(DOC_MAIN_SGML_FILE) $(content_files) - $(MAKE) html -endif +$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): check_scan -scan: - -(cd $(srcdir) \ - && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --source-dir=$(SECOND_DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(EXTRA_HFILES)) - -templates: +tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt + @echo '*** Rebuilding template files ***' cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) + touch tmpl-build.stamp -sgml: - cd $(srcdir) \ - && gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --source-dir=$(SECOND_DOC_SOURCE_DIR) +check_templates: + $(MAKE) tmpl-build.stamp -html: +tmpl.stamp: check_templates + +sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) + @echo '*** Building SGML ***' + cd $(srcdir) && \ + gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS) + touch sgml-build.stamp + +check_sgml: + $(MAKE) sgml-build.stamp + +sgml.stamp: check_sgml + +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) + @echo '*** Building HTML ***' test -d $(srcdir)/html || mkdir $(srcdir)/html - -cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html ) @echo '-- Fixing Crossreferences' cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) + touch html-build.stamp +endif clean-local: - rm -f *~ *.bak *.signals *-unused.txt + rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS) $(srcdir)/sgml.stamp maintainer-clean-local: clean cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt @@ -120,17 +167,22 @@ if ENABLE_GTK_DOC dist-check-gtkdoc: else dist-check-gtkdoc: - @echo "*** gtk-doc must be installed and enabled in order to make dist + @echo "*** gtk-doc must be installed and enabled in order to make dist" @false endif -dist-hook: dist-check-gtkdoc - mkdir $(distdir)/html - mkdir $(distdir)/sgml +dist-hook: dist-check-gtkdoc dist-hook-local mkdir $(distdir)/tmpl - -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(srcdir)/html/index.sgml $(distdir)/html + mkdir $(distdir)/sgml + mkdir $(distdir)/html -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl -cp $(srcdir)/sgml/*.sgml $(distdir)/sgml -cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml + -cp $(srcdir)/html/index.sgml $(distdir)/html + -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html + for i in $(HTML_IMAGES) ; do \ + cp $(srcdir)/$$i $(distdir)/html ; \ + done + +.PHONY : check_sgml check_templates check_scan dist-hook-local -.PHONY : html sgml templates scan diff --git a/docs/reference/gdk-pixbuf/tmpl/animation.sgml b/docs/reference/gdk-pixbuf/tmpl/animation.sgml index 8253cb491d..c8bff9b017 100644 --- a/docs/reference/gdk-pixbuf/tmpl/animation.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/animation.sgml @@ -1,38 +1,52 @@ -animation +Animations - +Animations as multi-frame structures. - - - + + The &gdk-pixbuf; library provides a simple mechanism to load and + represent animations, primarily animated GIF files. Animations + are represented as lists of #GdkPixbufFrame structures. Each + frame structure contains a #GdkPixbuf structure and information + about the frame's overlay mode and duration. + - - - + + #GdkPixbufLoader + - + + Each animation frame can have several things happen to it when the + next frame is displayed. The #GdkPixbufFrameAction determines + this. These are essentially the overlay modes supported by GIF + animations. + - - -@GDK_PIXBUF_FRAME_RETAIN: -@GDK_PIXBUF_FRAME_DISPOSE: -@GDK_PIXBUF_FRAME_REVERT: +@GDK_PIXBUF_FRAME_RETAIN: The previous image should remain displayed, +and will potentially be occluded by the new frame. +@GDK_PIXBUF_FRAME_DISPOSE: The animation will be reverted to the state +before the frame was shown. +@GDK_PIXBUF_FRAME_REVERT: The animation will be reverted to the first +frame. - - - + + This structure describes a frame in a #GdkPixbufAnimation. Each + frame consists of a #GdkPixbuf, an offset of the frame within the + animation's bounding box, a duration, and an overlay mode or + action. + - - - + + This structure describes an animation, which is represented as a + list of #GdkPixbufFrame structures. + @@ -140,6 +154,11 @@ animation @frame: -@Returns: +@Returns: diff --git a/docs/reference/gdk-pixbuf/tmpl/creating.sgml b/docs/reference/gdk-pixbuf/tmpl/creating.sgml index f3d9f9aafd..0bbce5405a 100644 --- a/docs/reference/gdk-pixbuf/tmpl/creating.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/creating.sgml @@ -1,18 +1,47 @@ -creating +Image Data in Memory - +Creating a pixbuf from image data that is already in memory. - + + The most basic way to create a pixbuf is to wrap an existing pixel + buffer with a #GdkPixbuf structure. You can use the + gdk_pixbuf_new_from_data() function to do this You need to specify + the destroy notification function that will be called when the + data buffer needs to be freed; this will happen when a #GdkPixbuf + is finalized by the reference counting functions If you have a + chunk of static data compiled into your application, you can pass + in #NULL as the destroy notification function so that the data + will not be freed. + - + + The gdk_pixbuf_new() function can be used as a convenience to + create a pixbuf with an empty buffer. This is equivalent to + allocating a data buffer using malloc() and then wrapping it with + gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() function will + compute an optimal rowstride so that rendering can be performed + with an efficient algorithm. + + + + As a special case, you can use the gdk_pixbuf_new_from_xpm_data() + function to create a pixbuf from inline XPM image data. + + + + You can also copy an existing pixbuf with the gdk_pixbuf_copy() + function. This is not the same as just doing a gdk_pixbuf_ref() + on the old pixbuf; the copy function will actually duplicate the + pixel data in memory and create a new #GdkPixbuf structure for it. + - - - + + gdk_pixbuf_finalize(). + @@ -84,8 +113,11 @@ creating @pixbuf: -@Returns: - -@src: +@Returns: diff --git a/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml b/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml index 125cf84c48..7025c7edd5 100644 --- a/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml @@ -1,18 +1,29 @@ -file-loading +File Loading - +Loading a pixbuf from a file. - + + The &gdk-pixbuf; library provides a simple mechanism for loading + an image from a file in synchronous fashion. This means that the + library takes control of the application while the file is being + loaded; from the user's point of view, the application will block + until the image is done loading. + - + + This interface can be used by applications in which blocking is + acceptable while an image is being loaded. It can also be used to + load small images in general. Applications that need progressive + loading can use the #GdkPixbufLoader functionality instead. + - - - + + #GdkPixbufLoader. + @@ -21,6 +32,11 @@ file-loading @filename: @error: -@Returns: +@Returns: diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml index ff05728569..b8af403062 100644 --- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml @@ -1,141 +1,152 @@ + + + The &gdk-pixbuf; library provides a simple mechanism to load and + represent animations, primarily animated GIF files. Animations + are represented as lists of #GdkPixbufFrame structures. Each + frame structure contains a #GdkPixbuf structure and information + about the frame's overlay mode and duration. + + + + + + #GdkPixbufLoader + + + + +Animations as multi-frame structures. + + + +Animations + + + + + The functions in this section allow you to take the image data + from a GDK drawable and dump it into a #GdkPixbuf. This can be + used for screenshots and other special effects. Note that these + operations can be expensive, since the image data has to be + transferred from the X server to the client program and converted. + + + + + + gdk_image_get(). + + + + +Getting parts of a drawable's image data into a pixbuf. + + Drawables to Pixbufs - - - A function of this type can be used to override the default - operation when a pixbuf loses its last reference, i.e. when - gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a - reference count of 1. This function should determine whether to - finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether - to just resume normal execution. The last unref handler for a - #GdkPixbuf can be set using the - gdk_pixbuf_set_last_unref_handler() function. By default, pixbufs - will be finalized automatically if no last unref handler has been - defined. - - -@pixbuf: The pixbuf that is losing its last reference. -@data: User closure data. - - - - - - -@src: -@Returns: -@frame: - - - - GdkRGB - - - - -X Drawables to Pixbufs - - - - - - - -@pixbuf: -@pixmap_return: -@mask_return: -@alpha_threshold: - - - - Indicates the width the pixbuf will be scaled to. This argument - will only be used if the width_set argument - is %TRUE. If the width_in_pixels - argument is %FALSE, the width will be taken to be in canvas units, - and thus will be scaled along with the canvas item's affine - transformation. If width_in_pixels is %TRUE, the width will be - taken to be in pixels, and will visually remain a constant size - even if the item's affine transformation changes. - - - - + - + -@pixbuf: -@drawable: -@gc: -@src_x: -@src_y: -@dest_x: -@dest_y: -@width: -@height: -@dither: -@x_dither: -@y_dither: - - + - -@dest: -@src: -@cmap: -@src_x: -@src_y: -@dest_x: -@dest_y: -@width: -@height: -@Returns: - + +gdk-pixbuf-io + + + - Indicates the horizontal translation offset of the pixbuf item's - image. This offset may not actually appear horizontal, since it - will be affected by the item's affine transformation. The default - is 0.0. + #GdkPixbufLoader provides a way for applications to drive the + process of loading an image, by letting them send the image data + directly to the loader instead of having the loader read the data + from a file. Applications can use this functionality instead of + gdk_pixbuf_new_from_file() when they need to parse image data in + small chunks. For example, it should be used when reading an + image from a (potentially) slow network connection, or when + loading an extremely large file. + + + + To use #GdkPixbufLoader to load an image, just create a new one, + and call gdk_pixbuf_loader_write() to send the data to it. When + done, gdk_pixbuf_loader_close() should be called to end the stream + and finalize everything. The loader will emit two important + signals throughout the process. The first, "area_prepared", + will be called as soon as the image has enough information to + determine the size of the image to be used. It will pass a + @GdkPixbuf in. If you want to use it, you can simply ref it. In + addition, no actual information will be passed in yet, so the + pixbuf can be safely filled with any temporary graphics (or an + initial color) as needed. You can also call the + gdk_pixbuf_loader_get_pixbuf() once this signal has been emitted + and get the same pixbuf. + + + + The other signal, "area_updated" gets + called every time a region is updated. This way you can update a + partially completed image. Note that you do not know anything + about the completeness of an image from the area updated. For + example, in an interlaced image, you need to make several passes + before the image is done loading. + + + + Loading an animation + + + Loading an animation is a little more complex then loading an + image. In addition to the above signals, there is also a "frame_done" signal, + as well as an "animation_done" + signal. The first lets the application know that it is dealing + with an animation, instead of a static image. It also passes a + #GdkPixbufFrame in the signal. As before, if you want to keep + the frame, you need to ref it. Once the first "frame_done" signal + has been emitted, you can call gdk_pixbuf_loader_get_animation() + to get the #GdkPixbufAnimation struct. Each subsequent frame + goes through a similar lifecycle. For example "area_prepared" is + re-emitted. Then "area_updated" is + emitted as many times as necessary. Finally, "animation_done" + is emitted as soon as all frames are done. + + + + + + + gdk_pixbuf_new_from_file() - - - Indicates the vertical translation offset of the pixbuf item's - image. Works in the same way as the x argument. The default is - 0.0. - + +Application-driven progressive image loading. - -Initializing the &gdk-pixbuf; Xlib library. + +GdkPixbufLoader - + The functions in this section allow you to take the image data from an X drawable and dump it into a #GdkPixbuf. This can be @@ -150,204 +161,21 @@ Initializing the &gdk-pixbuf; Xlib library. - - - - - -@art_pixbuf: -@Returns: - - - - XlibRGB - - - - - - #GnomeCanvas, #GdkPixbuf - - - - - - Contains a pointer to a #GdkPixbuf structure that will be used by - the pixbuf canvas item as an image source. When a pixbuf is set - its reference count is incremented; if the pixbuf item kept a - pointer to another #GdkPixbuf structure, the reference count of - this structure will be decremented. Also, the GdkPixbuf's - reference count will automatically be decremented when the - #GnomeCanvasPixbuf item is destroyed. When a pixbuf is queried, a - reference count will not be added to the return value; you must do - this yourself if you intend to keep the pixbuf structure around. - - - - + - - - GdkRGB - + +Getting parts of an X drawable's image data into a pixbuf. - - - Determines whether the x argument is used to - translate the pixbuf from its logical origin in item-relative - coordinates. - + +X Drawables to Pixbufs - - - The &gdk-pixbuf; Xlib library provides several convenience - functions to render pixbufs to X drawables. It uses XlibRGB to - render the image data. - - - - These functions are analogous to those for the Gdk version of - &gdk-pixbuf;. - - - - - - - - -Canvas item to display #GdkPixbuf images. - - - - - The functions in this section allow you to take the image data - from a GDK drawable and dump it into a #GdkPixbuf. This can be - used for screenshots and other special effects. Note that these - operations can be expensive, since the image data has to be - transferred from the X server to the client program and converted. - - - - - - Determines whether the width argument is taken - into account when scaling the pixbuf item. If this argument is - %FALSE, then the width value of the pixbuf will be used instead. - This argument is %FALSE by default. - - - - - - The XlibRGB set of functions is a port of the GdkRGB library to - use plain Xlib and X drawables. You can use these functions to - render RGB buffers into drawables very quickly with high-quality - dithering. - - - - -Functions for rendering RGB buffers to X drawables. - - - - - Casts a #GtkOjbect to a #GnomeCanvasPixbuf. - - -@obj: A GTK+ object. - - - - - - - - - - - - - - - - Works in the same way as the x_in_pixels - argument, but controls whether the y translation offset is - scaled or not. The default is %FALSE. - - - - - - -Rendering a pixbuf to an X drawable. - - - - - - - -@pixbuf: - - - - If this argument is %TRUE, the pixbuf's translation with respect - to its logical origin in item-relative coordinates will be in - pixels, that is, the visible offset will not change even if the - item's affine transformation changes. If it is %FALSE, the - pixbuf's translation will be taken to be in canvas units, and thus - will change along with the item's affine transformation. The - default is %FALSE. - - - - -Rendering a pixbuf to a GDK drawable. - - - - - - - -@pixbuf: -@last_unref_fn: -@last_unref_fn_data: - - - - Determines whether the y argument is used to - translate the pixbuf from its logical origin in item-relative - coordinates. Works in the same way as the x_set argument. The - default is %FALSE. - - - - + In addition to the normal Gdk-specific functions, the &gdk-pixbuf; package provides a small library that lets Xlib-only applications @@ -361,186 +189,70 @@ Rendering a pixbuf to a GDK drawable. - - - - - -@pixbuf: -@Returns: - - - - - + + + XlibRGB + - - - - - -@pixbuf: -@drawable: -@src_x: -@src_y: -@dest_x: -@dest_y: -@width: -@height: -@alpha_mode: -@alpha_threshold: -@dither: -@x_dither: -@y_dither: - - - - - + +Initializing the &gdk-pixbuf; Xlib library. - + &gdk-pixbuf; Xlib initialization - + - Determines whether the height argument is - taken into account when scaling the pixbuf item. Works in the - same way as the width_set argument. - The default is %FALSE. + The &gdk-pixbuf; Xlib library provides several convenience + functions to render pixbufs to X drawables. It uses XlibRGB to + render the image data. + + + + These functions are analogous to those for the Gdk version of + &gdk-pixbuf;. - -Getting parts of an X drawable's image data into a pixbuf. + + + + - + +Rendering a pixbuf to an X drawable. + + + +Xlib Rendering + + + + + The XlibRGB set of functions is a port of the GdkRGB library to + use plain Xlib and X drawables. You can use these functions to + render RGB buffers into drawables very quickly with high-quality + dithering. + + + + + + GdkRGB + + + + +Functions for rendering RGB buffers to X drawables. + + + XlibRGB - - - If this argument is %TRUE, then the width of the pixbuf will be - considered to be in pixels, that is, it will not be visually - scaled even if the item's affine transformation changes. If this - is %FALSE, then the width of the pixbuf will be considered to be - in canvas units, and so will be scaled normally by affine - transformations. The default is %FALSE. - - - - - - Indicates the height the pixbuf will be scaled to. This argument - will only be used if the height_set argument - is %TRUE. Works in the same way as the width argument. - - - - - - Works in the same way as the width_in_pixels - argument. The default is %FALSE. - - - - - - gdk_image_get(). - - - - - - - - - - - - - - - - -Rendering - - - -GnomeCanvasPixbuf - - - - - Casts a #GtkObject to a #GdkPixbufLoader. - - -@obj: A GTK+ object. - - - - The &gdk-pixbuf; library provides several convenience functions to - render pixbufs to GDK drawables. It uses the GdkRGB to render the - image data. - - - - At this point there is not a standard alpha channel extension for - the X Window System, so it is not possible to use full opacity - information when painting images to arbitrary drawables. The - &gdk-pixbuf; convenience functions will threshold the opacity - information to create a bi-level clipping mask (black and white), - and use that to draw the image onto a drawable. - - - - - Since these functions use GdkRGB for rendering, you must - initialize GdkRGB before using any of them. You can do this by - calling gdk_rgb_init() near the beginning of your program. - - - - - -Getting parts of a drawable's image data into a pixbuf. - - - - - - - -@pixbuf: -@bitmap: -@src_x: -@src_y: -@dest_x: -@dest_y: -@width: -@height: -@alpha_threshold: - - - - - - - - - - - - - This canvas item displays #GdkPixbuf images. It handles full @@ -710,19 +422,709 @@ Getting parts of a drawable's image data into a pixbuf. - -Xlib Rendering + + + #GnomeCanvas, #GdkPixbuf + - + +Canvas item to display #GdkPixbuf images. + + + +GnomeCanvasPixbuf + + + -@frame: + + + + + + + + + + + + +Module Interface + + + + + The &gdk-pixbuf; library provides several convenience functions to + render pixbufs to GDK drawables. It uses the GdkRGB to render the + image data. + + + + At this point there is not a standard alpha channel extension for + the X Window System, so it is not possible to use full opacity + information when painting images to arbitrary drawables. The + &gdk-pixbuf; convenience functions will threshold the opacity + information to create a bi-level clipping mask (black and white), + and use that to draw the image onto a drawable. + + + + + Since these functions use GdkRGB for rendering, you must + initialize GdkRGB before using any of them. You can do this by + calling gdk_rgb_init() near the beginning of your program. + + + + + + + GdkRGB + + + + +Rendering a pixbuf to a GDK drawable. + + + +Rendering + + + + + The &gdk-pixbuf; contains functions to scale pixbufs, to scale + pixbufs and composite against an existing image, and to scale + pixbufs and composite against a solid color or checkerboard. + Compositing a checkerboard is a common way to show an image with + an alpha channel in image-viewing and editing software. + + + + Since the full-featured functions (gdk_pixbuf_scale(), + gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are + rather complex to use and have many arguments, two simple + convenience functions are provided, gdk_pixbuf_scale_simple() and + gdk_pixbuf_composite_color_simple() which create a new pixbuf of a + given size, scale an original image to fit, and then return the + new pixmap. + + + + The following example demonstrates handling an expose event by + rendering the appropriate area of a source image (which is scaled + to fit the widget) onto the widget's window. The source image is + rendered against a checkerboard, which provides a visual + representation of the alpha channel if the image has one. If the + image doesn't have an alpha channel, calling + gdk_pixbuf_composite_color() function has exactly the same effect + as calling gdk_pixbuf_scale(). + + + +gboolean +expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) +{ + GdkPixbuf *dest; + + gdk_window_set_back_pixmap (widget->window, NULL, FALSE); + + dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, event->area.width, event->area.height); + + gdk_pixbuf_composite_color (pixbuf, dest, + 0, 0, event->area.width, event->area.height, + -event->area.x, -event->area.y, + (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf), + (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf), + GDK_INTERP_BILINEAR, 255, + event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555); + + gdk_pixbuf_render_to_drawable (dest, widget->window, widget->style->fg_gc[GTK_STATE_NORMAL], + 0, 0, event->area.x, event->area.y, + event->area.width, event->area.height, + GDK_RGB_DITHER_NORMAL, event->area.x, event->area.y); + + gdk_pixbuf_unref (dest); + + return TRUE; +} + + + + + + GdkRGB + + + + +Scaling pixbufs and scaling and compositing pixbufs + + + +Scaling + + + + + These functions provide miscellaneous utilities for manipulating + pixbufs. The pixel data in pixbufs may of course be manipulated + directly by applications, but several common operations can be + performed by these functions instead. + + + + + + #GdkPixbuf + + + + +Utility and miscellaneous convenience functions. + + + +Utilities + + + + + The functions in this section allow you to take the image data + from an X drawable and dump it into a #GdkPixbuf. This can be + used for screenshots and other special effects. Note that these + operations can be expensive, since the image data has to be + transferred from the X server to the client program and converted. + + + + These functions are analogous to those for the Gdk version of + &gdk-pixbuf;. + + + + + + + + + + +Getting parts of an X drawable's image data into a pixbuf. + + + +X Drawables to Pixbufs + + + + + In addition to the normal Gdk-specific functions, the &gdk-pixbuf; + package provides a small library that lets Xlib-only applications + use #GdkPixbuf structures and render them to X drawables. The + functions in this section are used to initialize the &gdk-pixbuf; + Xlib library. This library must be initialized near the beginning + or the program or before calling any of the other &gdk-pixbuf; + Xlib functions; it cannot be initialized automatically since + Xlib-only applications do not call gdk_rgb_init() like GNOME + applications do. + + + + + + XlibRGB + + + + +Initializing the &gdk-pixbuf; Xlib library. + + + +&gdk-pixbuf; Xlib initialization + + + + + The &gdk-pixbuf; Xlib library provides several convenience + functions to render pixbufs to X drawables. It uses XlibRGB to + render the image data. + + + + These functions are analogous to those for the Gdk version of + &gdk-pixbuf;. + + + + + + + + + + +Rendering a pixbuf to an X drawable. + + + +Xlib Rendering + + + + + The XlibRGB set of functions is a port of the GdkRGB library to + use plain Xlib and X drawables. You can use these functions to + render RGB buffers into drawables very quickly with high-quality + dithering. + + + + + + GdkRGB + + + + +Functions for rendering RGB buffers to X drawables. + + + +XlibRGB + + + + + Casts a #GtkObject to a #GdkPixbufLoader. + + +@obj: A GTK+ object. + + + + Casts a #GtkOjbect to a #GnomeCanvasPixbuf. + + +@obj: A GTK+ object. + + + + + + + + + + + + + + + + A function of this type can be used to override the default + operation when a pixbuf loses its last reference, i.e. when + gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a + reference count of 1. This function should determine whether to + finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether + to just resume normal execution. The last unref handler for a + #GdkPixbuf can be set using the + gdk_pixbuf_set_last_unref_handler() function. By default, pixbufs + will be finalized automatically if no last unref handler has been + defined. + + +@pixbuf: The pixbuf that is losing its last reference. +@data: User closure data. + + + + This signal is emitted when an animation is done loading. + + +@gdkpixbufloader: the object which received the signal. +@loader: Loader which emitted the signal. + + + + This signal is emitted when the pixbuf loader has been fed the + initial amount of data that is required to figure out the size and + format of the image that it will create. After this signal is + emitted, applications can call gdk_pixbuf_loader_get_pixbuf() to + fetch the partially-loaded pixbuf. + + +@gdkpixbufloader: the object which received the signal. +@loader: Loader which emitted the signal. + + + + This signal is emitted when a significant area of the image being + loaded has been updated. Normally it means that a complete + scanline has been read in, but it could be a different area as + well. Applications can use this signal to know when to repaint + areas of an image that is being loaded. + + +@gdkpixbufloader: the object which received the signal. +@arg1: +@arg2: +@arg3: +@arg4: +@loader: Loader which emitted the signal. +@x: X offset of upper-left corner of the updated area. +@y: Y offset of upper-left corner of the updated area. +@width: Width of updated area. +@height: Height of updated area. + + + + This signal is emitted when gdk_pixbuf_loader_close() is called. + It can be used by different parts of an application to receive + notification when an image loader is closed by the code that + drives it. + + +@gdkpixbufloader: the object which received the signal. +@loader: Loader which emitted the signal. + + + + + + This signal is emitted when a frame is done loading. It will be + emitted for each frame in an animation data stream. + + +@gdkpixbufloader: the object which received the signal. +@arg1: +@loader: Loader which emitted the signal. +@frame: Frame which just completed loading. + + + + Indicates the height the pixbuf will be scaled to. This argument + will only be used if the height_set argument + is %TRUE. Works in the same way as the width argument. + + + + + + Works in the same way as the width_in_pixels + argument. The default is %FALSE. + + + + + + + + + + + + Determines whether the height argument is + taken into account when scaling the pixbuf item. Works in the + same way as the width_set argument. + The default is %FALSE. + + + + + + Contains a pointer to a #GdkPixbuf structure that will be used by + the pixbuf canvas item as an image source. When a pixbuf is set + its reference count is incremented; if the pixbuf item kept a + pointer to another #GdkPixbuf structure, the reference count of + this structure will be decremented. Also, the GdkPixbuf's + reference count will automatically be decremented when the + #GnomeCanvasPixbuf item is destroyed. When a pixbuf is queried, a + reference count will not be added to the return value; you must do + this yourself if you intend to keep the pixbuf structure around. + + + + + + Indicates the width the pixbuf will be scaled to. This argument + will only be used if the width_set argument + is %TRUE. If the width_in_pixels + argument is %FALSE, the width will be taken to be in canvas units, + and thus will be scaled along with the canvas item's affine + transformation. If width_in_pixels is %TRUE, the width will be + taken to be in pixels, and will visually remain a constant size + even if the item's affine transformation changes. + + + + + + If this argument is %TRUE, then the width of the pixbuf will be + considered to be in pixels, that is, it will not be visually + scaled even if the item's affine transformation changes. If this + is %FALSE, then the width of the pixbuf will be considered to be + in canvas units, and so will be scaled normally by affine + transformations. The default is %FALSE. + + + + + + + + + + + + Determines whether the width argument is taken + into account when scaling the pixbuf item. If this argument is + %FALSE, then the width value of the pixbuf will be used instead. + This argument is %FALSE by default. + + + + + + Indicates the horizontal translation offset of the pixbuf item's + image. This offset may not actually appear horizontal, since it + will be affected by the item's affine transformation. The default + is 0.0. + + + + + + If this argument is %TRUE, the pixbuf's translation with respect + to its logical origin in item-relative coordinates will be in + pixels, that is, the visible offset will not change even if the + item's affine transformation changes. If it is %FALSE, the + pixbuf's translation will be taken to be in canvas units, and thus + will change along with the item's affine transformation. The + default is %FALSE. + + + + + + + + + + + + Determines whether the x argument is used to + translate the pixbuf from its logical origin in item-relative + coordinates. + + + + + + Indicates the vertical translation offset of the pixbuf item's + image. Works in the same way as the x argument. The default is + 0.0. + + + + + + Works in the same way as the x_in_pixels + argument, but controls whether the y translation offset is + scaled or not. The default is %FALSE. + + + + + + + + + + + + + + Determines whether the y argument is used to + translate the pixbuf from its logical origin in item-relative + coordinates. Works in the same way as the x_set argument. The + default is %FALSE. + + + + + + + + +@pixbuf: + + + + + + +@pixbuf: +@Returns: + + + + + + +@dest: @src: +@cmap: +@src_x: +@src_y: +@dest_x: +@dest_y: +@width: +@height: +@Returns: - -gdk-pixbuf-io + + + + + + + + + +@art_pixbuf: +@Returns: + + + + + + +@app: +@modinfo: + + + + + + +@app: +@modinfo: + + + + + + +@pixbuf: +@pixmap_return: +@mask_return: +@alpha_threshold: + + + + + + +@pixbuf: +@bitmap: +@src_x: +@src_y: +@dest_x: +@dest_y: +@width: +@height: +@alpha_threshold: + + + + + + +@pixbuf: +@drawable: +@gc: +@src_x: +@src_y: +@dest_x: +@dest_y: +@width: +@height: +@dither: +@x_dither: +@y_dither: + + + + + + +@pixbuf: +@drawable: +@src_x: +@src_y: +@dest_x: +@dest_y: +@width: +@height: +@alpha_mode: +@alpha_threshold: +@dither: +@x_dither: +@y_dither: + + + + + + +@pixbuf: +@last_unref_fn: +@last_unref_fn_data: + diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-xlib-init.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-xlib-init.sgml index c35a9ef47f..e841a19b02 100644 --- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-xlib-init.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-xlib-init.sgml @@ -1,18 +1,26 @@ -gdk-pixbuf-xlib-init +&gdk-pixbuf; Xlib initialization - +Initializing the &gdk-pixbuf; Xlib library. - - - + + In addition to the normal Gdk-specific functions, the &gdk-pixbuf; + package provides a small library that lets Xlib-only applications + use #GdkPixbuf structures and render them to X drawables. The + functions in this section are used to initialize the &gdk-pixbuf; + Xlib library. This library must be initialized near the beginning + or the program or before calling any of the other &gdk-pixbuf; + Xlib functions; it cannot be initialized automatically since + Xlib-only applications do not call gdk_rgb_init() like GNOME + applications do. + - - - + + XlibRGB + @@ -30,6 +38,11 @@ gdk-pixbuf-xlib-init @display: @screen_num: -@prefDepth: +@prefDepth: diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml index 5fc249f255..403941efa9 100644 --- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml @@ -1,18 +1,19 @@ -gdk-pixbuf +The GdkPixbuf Structure - +Information that describes an image. - - + + The GdkPixbuf structure contains + information that describes an image in memory. + - - - + + @@ -34,24 +35,39 @@ gdk-pixbuf - + + This enumeration defines the color spaces that are supported by + the &gdk-pixbuf; library. Currently only RGB is supported. + - - -@GDK_COLORSPACE_RGB: +@GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space. - + + These values can be passed to + gdk_pixbuf_render_to_drawable_alpha() to control how the alpha + chanel of an image should be handled. This function can create a + bilevel clipping mask (black and white) and use it while painting + the image. In the future, when the X Window System gets an alpha + channel extension, it will be possible to do full alpha + compositing onto arbitrary drawables. For now both cases fall + back to a bilevel clipping mask. + - - -@GDK_PIXBUF_ALPHA_BILEVEL: -@GDK_PIXBUF_ALPHA_FULL: +@GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white) +will be created and used to draw the image. Pixels below 0.5 opacity +will be considered fully transparent, and all others will be +considered fully opaque. +@GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL. +In the future it will do full alpha compositing. - - - + + This is the main structure in the &gdk-pixbuf; library. It is + used to represent images. It contains information about the + image's pixel data, its color space, bits per sample, width and + height, and the rowstride or number of bytes between rows. + @@ -123,6 +139,11 @@ gdk-pixbuf @pixbuf: -@Returns: +@Returns: diff --git a/docs/reference/gdk-pixbuf/tmpl/initialization_versions.sgml b/docs/reference/gdk-pixbuf/tmpl/initialization_versions.sgml index 41302c27ca..b5eef8ccb9 100644 --- a/docs/reference/gdk-pixbuf/tmpl/initialization_versions.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/initialization_versions.sgml @@ -14,31 +14,6 @@ Initialization and Versions - - - - - - - - - - - - -@app: -@modinfo: - - - - - - - -@app: -@modinfo: - - diff --git a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml index 9ae00cfe50..f975e4f69a 100644 --- a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml @@ -1,32 +1,77 @@ -refcounting +Reference Counting and Memory Mangement +Functions to perform reference counting and memory management on a +#GdkPixbuf. - + + #GdkPixbuf structures are reference counted. This means that + an application can share a single pixbuf among many parts of the + code. When a piece of the program needs to keep a pointer to a + pixbuf, it should add a reference to it. When it no longer needs + the pixbuf, it should subtract a reference. The pixbuf will be + destroyed when its reference count drops to zero. Newly-created + #GdkPixbuf structures start with a reference count of one. + - + + Finalizing a pixbuf means to free its pixel + data and to free the #GdkPixbuf structure itself. Most of the + library functions that create #GdkPixbuf structures create the + pixel data by themselves and define the way it should be freed; + you do not need to worry about those. The only function that lets + you specify how to free the pixel data is + gdk_pixbuf_new_from_data(). Since you pass it a pre-allocated + pixel buffer, you must also specify a way to free that data. This + is done with a function of type #GdkPixbufDestroyNotify. When a + pixbuf created with gdk_pixbuf_new_from_data() is finalized, your + destroy notification function will be called, and it is its + responsibility to free the pixel array. + + + + As an extension to traditional reference counting, #GdkPixbuf + structures support defining a handler for the last unref + operation. If gdk_pixbuf_unref() is called on a #GdkPixbuf + structure that has a reference count of 1, i.e. its last + reference, then the pixbuf's last unref handler function will be + called. It is up to this function to determine whether to + finalize the pixbuf using gdk_pixbuf_finalize() or to just + continue execution. This can be used to implement a pixbuf cache + efficiently; please see the programmer's documentation for + details. + + + - - - + + #GdkPixbuf, gdk_pixbuf_new_from_data(). + - + + A function of this type is responsible for freeing the pixel array + of a pixbuf. The gdk_pixbuf_new_from_data() function lets you + pass in a pre-allocated pixel array so that a pixbuf can be + created from it; in this case you will need to pass in a function + of #GdkPixbufDestroyNotify so that the pixel data can be freed + when the pixbuf is finalized. + - - -@pixels: -@data: +@pixels: The pixel array of the pixbuf that is being finalized. +@data: User closure data. - + - + @pixbuf: @Returns: diff --git a/docs/reference/gdk-pixbuf/tmpl/scaling.sgml b/docs/reference/gdk-pixbuf/tmpl/scaling.sgml index bcdbee8324..a8d41a1170 100644 --- a/docs/reference/gdk-pixbuf/tmpl/scaling.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/scaling.sgml @@ -1,28 +1,102 @@ -scaling +Scaling - +Scaling pixbufs and scaling and compositing pixbufs - + + The &gdk-pixbuf; contains functions to scale pixbufs, to scale + pixbufs and composite against an existing image, and to scale + pixbufs and composite against a solid color or checkerboard. + Compositing a checkerboard is a common way to show an image with + an alpha channel in image-viewing and editing software. + - + + Since the full-featured functions (gdk_pixbuf_scale(), + gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are + rather complex to use and have many arguments, two simple + convenience functions are provided, gdk_pixbuf_scale_simple() and + gdk_pixbuf_composite_color_simple() which create a new pixbuf of a + given size, scale an original image to fit, and then return the + new pixmap. + + + + The following example demonstrates handling an expose event by + rendering the appropriate area of a source image (which is scaled + to fit the widget) onto the widget's window. The source image is + rendered against a checkerboard, which provides a visual + representation of the alpha channel if the image has one. If the + image doesn't have an alpha channel, calling + gdk_pixbuf_composite_color() function has exactly the same effect + as calling gdk_pixbuf_scale(). + + + +gboolean +expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) +{ + GdkPixbuf *dest; + + gdk_window_set_back_pixmap (widget->window, NULL, FALSE); + + dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, event->area.width, event->area.height); + + gdk_pixbuf_composite_color (pixbuf, dest, + 0, 0, event->area.width, event->area.height, + -event->area.x, -event->area.y, + (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf), + (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf), + GDK_INTERP_BILINEAR, 255, + event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555); + + gdk_pixbuf_render_to_drawable (dest, widget->window, widget->style->fg_gc[GTK_STATE_NORMAL], + 0, 0, event->area.x, event->area.y, + event->area.width, event->area.height, + GDK_RGB_DITHER_NORMAL, event->area.x, event->area.y); + + gdk_pixbuf_unref (dest); + + return TRUE; +} + - - - + + GdkRGB + - + + This enumeration describes the different interpolation modes that + can be used with the scaling functions. - + + + Cubic filtering is missing from the list; hyperbolic + interpolation is just as fast and results in higher quality. + + + -@GDK_INTERP_NEAREST: -@GDK_INTERP_TILES: -@GDK_INTERP_BILINEAR: -@GDK_INTERP_HYPER: +@GDK_INTERP_NEAREST: Nearest neighbor sampling; this is the fastest +and lowest quality mode. +@GDK_INTERP_TILES: This is an accurate simulation of the PostScript +image operator without any interpolation enabled. Each pixel is +rendered as a tiny parallelogram of solid color, the edges of which +are implemented with antialiasing. It resembles nearest neighbor for +enlargement, and bilinear for reduction. +@GDK_INTERP_BILINEAR: Bilinear interpolation. For enlargement, it is +equivalent to point-sampling the ideal bilinear-interpolated image. +For reduction, it is equivalent to laying down small tiles and +integrating over the coverage area. +@GDK_INTERP_HYPER: This is the slowest and highest quality +reconstruction function. It is derived from the hyperbolic filters in +Wolberg's "Digital Image Warping", and is formally defined as the +hyperbolic-filter sampling the ideal hyperbolic-filter interpolated +image (the filter is designed to be idempotent for 1:1 pixel mapping). @@ -110,6 +184,11 @@ scaling @check_size: @color1: @color2: -@Returns: +@Returns: diff --git a/docs/reference/gdk-pixbuf/tmpl/util.sgml b/docs/reference/gdk-pixbuf/tmpl/util.sgml index a119a3f317..35726a967b 100644 --- a/docs/reference/gdk-pixbuf/tmpl/util.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/util.sgml @@ -1,18 +1,21 @@ -util +Utilities - +Utility and miscellaneous convenience functions. - - - + + These functions provide miscellaneous utilities for manipulating + pixbufs. The pixel data in pixbufs may of course be manipulated + directly by applications, but several common operations can be + performed by these functions instead. + - - - + + #GdkPixbuf + @@ -39,7 +42,12 @@ util @height: @dest_pixbuf: @dest_x: -@dest_y: +@dest_y: diff --git a/docs/reference/gdk/Makefile.am b/docs/reference/gdk/Makefile.am index 0caaeb723d..bb75e310ba 100644 --- a/docs/reference/gdk/Makefile.am +++ b/docs/reference/gdk/Makefile.am @@ -9,9 +9,19 @@ DOC_MAIN_SGML_FILE=gdk-docs.sgml # The directory containing the source code (if it contains documentation). DOC_SOURCE_DIR=$(top_srcdir)/gdk +# Extra options to supply to gtkdoc-scan +SCAN_OPTIONS= + +# Extra options to supply to gtkdoc-mkdb +MKDB_OPTIONS= + # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html +# Used for dependencies +HFILE_GLOB=$(top_srcdir)/gdk/*.h $(top_srcdir)/gdk/x11/gdkx.h +CFILE_GLOB=$(top_srcdir)/gdk/*.c + # Header files to ignore when scanning IGNORE_HFILES= \ gdkkeysyms.h \ @@ -28,39 +38,24 @@ IGNORE_HFILES= \ EXTRA_HFILES= \ $(top_srcdir)/gdk/x11/gdkx.h -tmpl_sources = \ - tmpl/color_contexts.sgml \ - tmpl/colors.sgml \ - tmpl/cursors.sgml \ - tmpl/dnd.sgml \ - tmpl/drawing.sgml \ - tmpl/event_structs.sgml \ - tmpl/events.sgml \ - tmpl/fonts.sgml \ - tmpl/gcs.sgml \ - tmpl/gdk-unused.sgml \ - tmpl/general.sgml \ - tmpl/images.sgml \ - tmpl/input.sgml \ - tmpl/input_contexts.sgml \ - tmpl/input_devices.sgml \ - tmpl/input_methods.sgml \ - tmpl/keys.sgml \ - tmpl/pango_interaction.sgml \ - tmpl/pixbufs.sgml \ - tmpl/pixmaps.sgml \ - tmpl/properties.sgml \ - tmpl/regions.sgml \ - tmpl/rgb.sgml \ - tmpl/selections.sgml \ - tmpl/threads.sgml \ - tmpl/visuals.sgml \ - tmpl/windows.sgml \ - tmpl/x_interaction.sgml +# Images to copy into HTML directory +HTML_IMAGES = # Extra SGML files that are included by DOC_MAIN_SGML_FILE content_files = +# Other files to distribute +extra_files = + +# CFLAGS and LDFLAGS for compiling scan program. Only needed +# if $(DOC_MODULE).types is non-empty. +GTKDOC_CFLAGS = +GTKDOC_LIBS = + +# Commands for compiling and linking +GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC) +GTKDOC_LD=$(LIBTOOL) --mode=link $(CC) + #################################### # Everything below here is generic # @@ -69,46 +64,76 @@ content_files = TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) EXTRA_DIST = \ - $(DOC_MAIN_SGML_FILE) \ $(content_files) \ + $(extra_files) \ + $(HTML_IMAGES) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE).types \ $(DOC_MODULE)-sections.txt \ $(DOC_MODULE)-overrides.txt +DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp + if ENABLE_GTK_DOC -all-local: html/index.html +all-local: html-build.stamp -$(DOC_MODULE)-decl.txt: - $(MAKE) scan +SCANOBJ_FILES = \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).signal -$(tmpl_sources): $(DOC_MODULE)-decl.txt $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt - $(MAKE) templates +scan-build.stamp: $(HFILE_GLOB) + @echo '*** Scanning header files ***' + cd $(srcdir) && ( \ + if grep -l '^.+$$' $(DOC_MODULE).types > /dev/null ; then \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) ; \ + else \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ + fi ) + cd $(srcdir) && \ + gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES) + touch scan-build.stamp -sgml/$(DOC_MODULE)-doc.bottom: $(tmpl_sources) $(DOC_MODULE)-decl.txt - $(MAKE) sgml +check_scan: + $(MAKE) scan-build.stamp -html/index.html: sgml/$(DOC_MODULE)-doc.bottom $(DOC_MAIN_SGML_FILE) $(content_files) - $(MAKE) html -endif +$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): check_scan -scan: - -(cd $(srcdir) \ - && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(EXTRA_HFILES)) - -templates: +tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt + @echo '*** Rebuilding template files ***' cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) + touch tmpl-build.stamp -sgml: - cd $(srcdir) \ - && gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) +check_templates: + $(MAKE) tmpl-build.stamp -html: +tmpl.stamp: check_templates + +sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) + @echo '*** Building SGML ***' + cd $(srcdir) && \ + gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS) + touch sgml-build.stamp + +check_sgml: + $(MAKE) sgml-build.stamp + +sgml.stamp: check_sgml + +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) + @echo '*** Building HTML ***' test -d $(srcdir)/html || mkdir $(srcdir)/html - -cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html ) @echo '-- Fixing Crossreferences' cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) + touch html-build.stamp +endif clean-local: - rm -f *~ *.bak *.signals *-unused.txt + rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS) $(srcdir)/sgml.stamp maintainer-clean-local: clean cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt @@ -134,17 +159,21 @@ if ENABLE_GTK_DOC dist-check-gtkdoc: else dist-check-gtkdoc: - @echo "*** gtk-doc must be installed and enabled in order to make dist + @echo "*** gtk-doc must be installed and enabled in order to make dist" @false endif -dist-hook: dist-check-gtkdoc - mkdir $(distdir)/html - mkdir $(distdir)/sgml +dist-hook: dist-check-gtkdoc dist-hook-local mkdir $(distdir)/tmpl - -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(srcdir)/html/index.sgml $(distdir)/html + mkdir $(distdir)/sgml + mkdir $(distdir)/html -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl -cp $(srcdir)/sgml/*.sgml $(distdir)/sgml -cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml + -cp $(srcdir)/html/index.sgml $(distdir)/html + -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html + for i in $(HTML_IMAGES) ; do \ + cp $(srcdir)/$$i $(distdir)/html ; \ + done -.PHONY : html sgml templates scan +.PHONY : check_sgml check_templates check_scan dist-hook-local diff --git a/docs/reference/gdk/tmpl/colors.sgml b/docs/reference/gdk/tmpl/colors.sgml index e307e1a4d2..d4185b515c 100644 --- a/docs/reference/gdk/tmpl/colors.sgml +++ b/docs/reference/gdk/tmpl/colors.sgml @@ -2,11 +2,40 @@ Colormaps and Colors - +manipulation of colors and colormaps. +These functions are used to modify colormaps. +A colormap is an object that contains the mapping +between the color values stored in memory and +the RGB values that are used to display color +values. In general, colormaps only contain +significant information for pseudo-color visuals, +but even for other visual types, a colormap object +is required in some circumstances. + + +There are a couple of special colormaps that can +be retrieved. The system colormap (retrieved +with gdk_colormap_get_system()) is the default +colormap of the system. If you are using GdkRGB, +there is another colormap that is important - the +colormap in which GdkRGB works, retrieved with +gdk_rgb_get_cmap(). However, when using GdkRGB, +it is not generally necessary to allocate colors +directly. + + + +In previous revisions of this interface, a number +of functions that take a #GdkColormap parameter +were replaced with functions whose names began +with "gdk_colormap_". This process will probably +be extended somewhat in the future - +gdk_color_white(), gdk_color_black(), and +gdk_color_change() will probably become aliases. @@ -16,7 +45,37 @@ Colormaps and Colors +The #GdkColor structure is used to describe an +allocated or unallocated color. + + + + + +pixel +For allocated colors, the value used to +draw this color on the screen. + + + +red +The red component of the color. This is +a value between 0 and 65535, with 65535 indicating +full intensitiy. + + + +green +the blue component of the color. + + + +blue +the green component of the color.. + + + @pixel: @@ -26,7 +85,28 @@ Colormaps and Colors +The colormap structure contains the following public +fields. + + + + + +size +For pseudo-color colormaps, the number of colors +in the colormap.. + + + +colors +An array containing the current values in the +colormap. This can be used to map from pixel values +back to RGB values. This is only meaningful for +pseudo-color colormaps. + + + @parent_instance: @@ -35,219 +115,278 @@ Colormaps and Colors - +Create a new colormap for the given visual. -@visual: -@allocate: -@Returns: +@visual: a #GdkVisual. +@allocate: if %TRUE, the newly created colormap will be + a private colormap, and all colors in it will be + allocated for the applications use. +@Returns: the new #GdkColormap. - +Increase the reference count of a colormap. -@cmap: -@Returns: +@cmap: a #GdkColormap. +@Returns: @cmap - +Decrease the reference count of a colormap. If the +resulting reference count is zero, destroys the colormap. -@cmap: +@cmap: a #GdkColormap. - +Returns the system's default colormap. -@Returns: +@Returns: the default colormap. - +Returns the size of the system's default colormap. +(See the description of struct #GdkColormap for an +explanation of the size of a colormap.) -@Returns: +@Returns: the size of the system's default colormap. - +Change the value of the first @ncolors in a private colormap +to match the values in the colors +array in the color map. This function is obsolete and +should not be used. See gdk_color_change(). -@colormap: -@ncolors: +@colormap: a #GdkColormap. +@ncolors: the number of colors to change. - +Allocates colors from a colormap. -@colormap: -@colors: -@ncolors: -@writeable: -@best_match: -@success: -@Returns: +@colormap: a #GdkColormap. +@colors: The color values to allocate. On return, the pixel + values for allocated colors will be filled in. +@ncolors: The number of colors in @colors. +@writeable: If %TRUE, the colors are allocated writeable + (their values can later be changed using gdk_color_change()). + Writeable colors cannot be shared between applications. +@best_match: If %TRUE, GDK will attempt to do matching against + existing colors if the colors cannot be allocated as + requested. +@success: An array of length @ncolors. On return, this + indicates whether the corresponding color in @colors was + sucessfully allocated or not. +@Returns: The number of colors that were not sucessfully + allocated. - +Allocate a single color from a colormap. -@colormap: -@color: -@writeable: -@best_match: -@Returns: +@colormap: a #GdkColormap. +@color: the color to allocate. On return the +pixel field will be +filled in if allocation succeeds. +@writeable: If %TRUE, the color is allocated writeable + (their values can later be changed using gdk_color_change()). + Writeable colors cannot be shared between applications. +@best_match: If %TRUE, GDK will attempt to do matching against + existing colors if the color cannot be allocated as + requested. +@Returns: %TRUE if the allocation succeeded. - +Free previously allocated colors. -@colormap: -@colors: -@ncolors: +@colormap: a #GdkColormap. +@colors: the colors to free. +@ncolors: the number of colors in @colors. - +Return the visual for which a given colormap was created. -@colormap: -@Returns: +@colormap: a #GdkColormap. +@Returns: the visual of the colormap. - +Change the value of the first @ncolors colors in +a private colormap. This function is obsolete and +should not be used. See gdk_color_change(). -@colormap: -@colors: -@ncolors: +@colormap: a #GdkColormap. +@colors: the new color values. +@ncolors: the number of colors to change. - +Make a copy of a color structure. The result +must be freed using gdk_color_free(). -@color: -@Returns: +@color: a #GdkColor. +@Returns: a copy of @color. - +Free a color structure created with +gdk_color_copy(). -@color: +@color: a #GdkColor. - +Allocate colors from a colormap. This function +is obsolete. See gdk_colormap_alloc_colors(). +For full documentation of the fields, see +the Xlib documentation for XAllocColorCells. -@colormap: -@contiguous: -@planes: -@nplanes: -@pixels: -@npixels: +@colormap: a #GdkColormap. +@contiguous: if %TRUE, the colors should be allocated + in contiguous color cells. +@planes: an array in which to store the plane masks. +@nplanes: the number of planes to allocate. (Or zero, + to indicate that the color allocation should not be + planar.) +@pixels: an array into which to store allocated pixel + values. +@npixels: the number of pixels in each plane to allocate. @Returns: - +Free colors allocated with gdk_colors_alloc(). This +function is obsolete. See gdk_colormap_free_colors(). -@colormap: -@pixels: -@npixels: -@planes: +@colormap: a #GdkColormap. +@pixels: the pixel values of the colors to free. +@npixels: the number of values in @pixels. +@planes: the plane masks for all planes to free, OR'd + together. - +Return the white color for a given colormap. The resulting +value has already allocated been allocated. -@colormap: -@color: -@Returns: +@colormap: a #GdkColormap. +@color: the location to store the color. +@Returns: %TRUE if the allocation succeeded. - +Return the black color for a given colormap. The resulting +value has already benn allocated. -@colormap: -@color: -@Returns: +@colormap: a #GdkColormap. +@color: the location to store the color. +@Returns: %TRUE if the allocation succeeded. - +Parse a textual specification of a color and fill in +the red, +green, and +blue fields of a +#GdkColor structure. The color is not +allocated, you must call gdk_colormap_alloc_color() yourself. +The text string can be in any of the forms accepted +by XParseColor; these include +name for a color from rgb.txt, such as +DarkSlateGray, or a hex specification +such as 305050. -@spec: -@color: +@spec: the string specifying the color. +@color: the #GdkColor to fill in @Returns: - +Allocate a single color from a colormap. +This function is obsolete. See gdk_colormap_alloc_color(). -@colormap: -@color: -@Returns: +@colormap: a #GdkColormap. +@color: The color to allocate. On return, the +pixel field will be +filled in. +@Returns: %TRUE if the allocation succeeded. - +Change the value of a color that has already +been allocated. If @colormap is not a private +colormap, then the color must have been allocated +using gdk_colormap_alloc_colors() with the +@writeable set to %TRUE. -@colormap: -@color: +@colormap: a #GdkColormap. +@color: a #GdkColor, with the color to change +in the pixel field, +and the new value in the remaining fields. @Returns: - +Compare two colors. -@colora: -@colorb: -@Returns: +@colora: a #GdkColor. +@colorb: another #GdkColor. +@Returns: %TRUE if the two colors compare equal - +A hash function suitable for using for a hash +table that stores #GdkColor's. -@colora: -@Returns: +@colora: a #GdkColor. +@Returns: The hash function appled to @colora + +@colorb: NOT USED. diff --git a/docs/reference/gdk/tmpl/drawing.sgml b/docs/reference/gdk/tmpl/drawing.sgml index 55adf506c7..0c03abcc6d 100644 --- a/docs/reference/gdk/tmpl/drawing.sgml +++ b/docs/reference/gdk/tmpl/drawing.sgml @@ -2,11 +2,22 @@ Drawing Primitives - +functions for drawing points, lines, arcs, and text. - +These functions provide support for drawing points, lines, arcs and text +onto what are called 'drawables'. Drawables, as the name suggests, are things +which support drawing onto them, and are either #GdkWindow or #GdkPixmap +objects. + + +Many of the drawing operations take a #GdkGC argument, which represents a +graphics context. This #GdkGC contains a number of drawing attributes such +as foreground color, background color and line width, and is used to reduce +the number of arguments needed for each drawing operation. See the +Graphics Contexts section for +more information. @@ -113,111 +124,134 @@ Drawing Primitives - +Draws a point, using the foreground color and other attributes of the #GdkGC. -@drawable: -@gc: -@x: -@y: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@x: the x coordinate of the point. +@y: the y coordinate of the point. - +Draws a number of points, using the foreground color and other attributes of +the #GdkGC. -@drawable: -@gc: -@points: -@npoints: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@points: an array of #GdkPoint structures. +@npoints: the number of points to be drawn. - +Draws a line, using the foreground color and other attributes of the #GdkGC. -@drawable: -@gc: -@x1: -@y1: -@x2: -@y2: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@x1: the x coordinate of the start point. +@y1: the y coordinate of the start point. +@x2: the x coordinate of the end point. +@y2: the y coordinate of the end point. - +Draws a series of lines connecting the given points. +The way in which joins between lines are draw is determined by the +#GdkCapStyle value in the #GdkGC. This can be set with +gdk_gc_set_line_attributes(). -@drawable: -@gc: -@points: -@npoints: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@points: an array of #GdkPoint structures specifying the endpoints of the +lines. +@npoints: the size of the @points array. - +Draws a number of unconnected lines. -@drawable: -@gc: -@segs: -@nsegs: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@segs: an array of #GdkSegment structures specifying the start and end points +of the lines to be drawn, +@nsegs: the number of line segments to draw, i.e. the size of the @segs array. - +Specifies the start and end point of a line for use by the gdk_draw_segments() +function. -@x1: -@y1: -@x2: -@y2: +@x1: the x coordinate of the start point. +@y1: the y coordinate of the start point. +@x2: the x coordinate of the end point. +@y2: the y coordinate of the end point. - +Draws a rectangular outline or filled rectangle, using the foreground color +and other attributes of the #GdkGC. + + +A rectangle drawn filled is 1 pixel smaller in both dimensions than a rectangle +outlined. Calling gdk_draw_rectangle (window, gc, TRUE, 0, 0, 20, 20) results +in a filled rectangle 20 pixels wide and 20 pixels high. Calling +gdk_draw_rectangle (window, gc, FALSE, 0, 0, 20, 20) results in an outlined +rectangle with corners at (0, 0), (0, 20), (20, 20), and (20, 0), which +makes it 21 pixels wide and 21 pixels high. + + -@drawable: -@gc: -@filled: -@x: -@y: -@width: -@height: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@filled: TRUE if the rectangle should be filled. +@x: the x coordinate of the left edge of the rectangle. +@y: the y coordinate of the top edge of the rectangle. +@width: the width of the rectangle. +@height: the height of the rectangle. - +Draws an arc or a filled 'pie slice'. The arc is defined by the bounding +rectangle of the entire ellipse, and the start and end angles of the part of +the ellipse to be drawn. -@drawable: -@gc: -@filled: -@x: -@y: -@width: -@height: -@angle1: -@angle2: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@filled: TRUE if the arc should be filled, producing a 'pie slice'. +@x: the x coordinate of the left edge of the bounding rectangle. +@y: the y coordinate of the top edge of the bounding rectangle. +@width: the width of the bounding rectangle. +@height: the height of the bounding rectangle. +@angle1: the start angle of the arc, relative to the 3 o'clock position, +counter-clockwise, in 1/64ths of a degree. +@angle2: the end angle of the arc, relative to @angle1, in 1/64ths of a degree. - +Draws an outlined or filled polygon. -@drawable: -@gc: -@filled: -@points: -@npoints: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@filled: TRUE if the polygon should be filled. The polygon is closed +automatically, connecting the last point to the first point if necessary. +@points: an array of #GdkPoint structures specifying the points making up the +polygon. +@npoints: the number of points. @@ -259,50 +293,64 @@ Drawing Primitives - +Draws a string of characters in the given font or fontset. -@drawable: -@font: -@gc: -@x: -@y: -@string: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@font: a #GdkFont. +@gc: a #GdkGC. +@x: the x coordinate of the left edge of the text. +@y: the y coordinate of the baseline of the text. +@string: the string of characters to draw. - +Draws a number of characters in the given font or fontset. -@drawable: -@font: -@gc: -@x: -@y: -@text: -@text_length: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@font: a #GdkFont. +@gc: a #GdkGC. +@x: the x coordinate of the left edge of the text. +@y: the y coordinate of the baseline of the text. +@text: the characters to draw. +@text_length: the number of characters of @text to draw. - +Draws a number of wide characters using the given font of fontset. +If the font is a 1-byte font, the string is converted into 1-byte characters +(discarding the high bytes) before output. -@drawable: -@font: -@gc: -@x: -@y: -@text: -@text_length: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@font: a #GdkFont. +@gc: a #GdkGC. +@x: the x coordinate of the left edge of the text. +@y: the y coordinate of the baseline of the text. +@text: the wide characters to draw. +@text_length: the number of characters to draw. - +Draws a pixmap, or a part of a pixmap, onto another drawable. + +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@src: the source #GdkPixmap to draw. +@xsrc: the left edge of the source rectangle within @src. +@ysrc: the top of the source rectangle within @src. +@xdest: the x coordinate of the destination within @drawable. +@ydest: the y coordinate of the destination within @drawable. +@width: the width of the area to be copied, or -1 to make the area extend to +the right edge of the source pixmap. +@height: the height of the area to be copied, or -1 to make the area extend +to the bottom edge of the source pixmap. @@ -323,18 +371,21 @@ Drawing Primitives - +Draws a #GdkImage onto a drawable. +The depth of the #GdkImage must match the depth of the #GdkDrawable. -@drawable: -@gc: -@image: -@xsrc: -@ysrc: -@xdest: -@ydest: -@width: -@height: +@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). +@gc: a #GdkGC. +@image: the #GdkImage to draw. +@xsrc: the left edge of the source rectangle within @image. +@ysrc: the top of the source rectangle within @image. +@xdest: the x coordinate of the destination within @drawable. +@ydest: the y coordinate of the destination within @drawable. +@width: the width of the area to be copied, or -1 to make the area extend to +the right edge of @image. +@height: the height of the area to be copied, or -1 to make the area extend +to the bottom edge of @image. diff --git a/docs/reference/gdk/tmpl/fonts.sgml b/docs/reference/gdk/tmpl/fonts.sgml index 438d124904..858f052fa9 100644 --- a/docs/reference/gdk/tmpl/fonts.sgml +++ b/docs/reference/gdk/tmpl/fonts.sgml @@ -2,11 +2,260 @@ Fonts - +loading and manipulating fonts +The GdkFont data type represents a font for drawing on +the screen. These functions provide support for +loading fonts, and also for determining the dimensions +of characters and strings when drawn with a particular +font. + + +Fonts in X are specified by a +X Logical Font Description. +The following description is considerably simplified. +For definitive information about XLFD's see the +X reference documentation. A X Logical Font Description (XLFD) +consists of a sequence of fields separated (and surrounded by) '-' +characters. For example, Adobe Helvetica Bold 12 pt, has the +full description: + + +"-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1" + + + + +The fields in the XLFD are: + + + + + + +Foundry +the company or organization where the font originated. + + + +Family +the font family (a group of related font designs). + + + +Weight +A name for the font's typographic weight +For example, 'bold' or 'medium'). + + + +Slant +The slant of the font. Common values are 'R' for Roman, +'I' for italoc, and 'O' for oblique. + + + +Set Width +A name for the width of the font. For example, +'normal' or 'condensed'. + + + +Add Style +Additional information to distinguish a font from +other fonts of the same family. + + + +Pixel Size +The body size of the font in pixels. + + + +Point Size +The body size of the font in 10ths of a point. +(A point is 1/72.27 inch) + + + +Resolution X +The horizontal resolution that the font was designed for. + + + +Resolution Y +The vertical resolution that the font was designed for . + + + +Spacing +The type of spacing for the font - can be 'p' for proportional, +'m' for monospaced or 'c' for charcell. + + + +Average Width +The average width of a glyph in the font. For monospaced +and charcell fonts, all glyphs in the font have this width + + + +Charset Registry +The registration authority that owns the encoding for +the font. Together with the Charset Encoding field, this +defines the character set for the font. + + + +Charset Encoding +An identifier for the particular character set encoding. + + + + + + +When specifying a font via a X logical Font Description, +'*' can be used as a wildcard to match any portion of +the XLFD. For instance, the above example could +also be specified as + + +"-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1" + + +It is generally a good idea to use wildcards for any +portion of the XLFD that your program does not care +about specifically, since that will improve the +chances of finding a matching font. + + + +A fontset is a list of fonts +that is used for drawing international text that may +contain characters from a number of different character +sets. It is represented by a list of XLFD's. + + + +The font for a given character set is determined by going +through the list of XLFD's in order. For each one, if +the registry and and encoding fields match the desired +character set, then that font is used, otherwise if +the XLFD contains wild-cards for the registry and encoding +fields, the registry and encoding for the desired character +set are subsituted in and a lookup is done. If a match is found +that font is used. Otherwise, processing continues +on to the next font in the list. + + + +The functions for determining the metrics of a string +come in several varieties that can take a number +of forms of string input: + + + + 8-bit string + + When using functions like gdk_string_width() that + take a gchar *, if the font is of type + %GDK_FONT_FONT and is an 8-bit font, then each + gchar indexes the glyphs in the font directly. + + + + 16-bit string + + For functions taking a gchar *, if the + font is of type %GDK_FONT_FONT, and is a 16-bit + font, then the gchar * argument is + interpreted as a guint16 * cast to + a gchar * and each guint16 + indexes the glyphs in the font directly. + + + + Multibyte string + + For functions taking a gchar *, if the + font is of type %GDK_FONT_FONTSET, then the input + string is interpreted as a multibyte + encoded according to the current locale. (A multibyte + string is one in which each character may consist + of one or more bytes, with different lengths for different + characters in the string). They can be converted to and + from wide character strings (see below) using + gdk_wcstombs() and gdk_mbstowcs().) The string will + be rendered using one or more different fonts from + the fontset. + + + + Wide character string + + For a number of the text-measuring functions, GTK+ + provides a variant (such as gdk_text_width_wc()) which + takes a GdkWChar * instead of a + gchar *. The input is then taken to + be a wide character string in the encoding of the + current locale. (A wide character string is a string + in which each character consists of several bytes, + and the width of each character in the string is + constant.) + + + + + + +GDK provides functions to determine a number of different +measurements (metrics) for a given string. (Need diagram +here). + + + + ascent + + The vertical distance from the origin of the drawing + opereration to the top of the drawn character. + + + + descent + + The vertical distance from the origin of the drawing + opereration to the bottom of the drawn character. + + + + left bearing + + The horizontal distance from the origin of the drawing + operation to the left-most part of the drawn character. + + + + right bearing + + The horizontal distance from the origin of the drawing + operation to the right-most part of the drawn character. + + + + width bearing + + The horizontal distance from the origin of the drawing + operation to the correct origin for drawing another + string to follow the current one. Depending on the + font, this could be greater than or less than the + right bearing. + + + @@ -16,7 +265,34 @@ Fonts +The GdkFont structure represents a font or fontset. It +contains the following public fields. A new GdkFont +structure is returned by gdk_font_load() or gdk_fontset_load(), +and is reference counted with gdk_font_ref() and gdk_font_unref() + + + + + +type +a value of type #GdkFontType which indicates +whether this font is a single font or a fontset. + + + +ascent +the maximum distance that the font, when drawn, +ascends above the baseline. + + + +descent +the maximum distance that the font, when drawn, +descends below the baseline. + + + @type: @@ -25,7 +301,24 @@ Fonts +Indicates the type of a font. The possible values +are currently: + + + + + +GDK_FONT_FONT +the font is a single font. + + + +GDK_FONT_FONT +the font is a fontset. + + + @GDK_FONT_FONT: @@ -33,20 +326,34 @@ Fonts - +Loads a font. -@font_name: -@Returns: + +Currently, this function will always return a new +font, however, in the future, it may be changed to +look up the font in a cache. You should make no +assumptions about the initial reference count. + + +@font_name: a XLFD describing the font to load. +@Returns: a #GdkFont, or NULL if the font could not be loaded. - +Loads a fontset. + + +Currently this function will always return a new +font, however, in the future, it may be changed to +look up the font in a cache. You should make no +assumptions about the initial reference count. -@fontset_name: -@Returns: +@fontset_name: a comma-separated list of XLFDs describing + the component fonts of the fontset to load. +@Returns: a #GdkFont, or NULL if the fontset could not be loaded. @@ -60,196 +367,225 @@ Fonts - +Increase the reference count of a count by one. -@font: -@Returns: +@font: a #GdkFont +@Returns: @font - +Decrease the reference count of a count by one. +If the result is zero, destroys the font. -@font: +@font: a #GdkFont - +Returns the X Font ID for the given font. -@font: -@Returns: +@font: a #GdkFont. +@Returns: the numeric X Font ID - +Compares two fonts for equality. Single fonts compare equal +if they have the same X font ID. This operation does +not currently work correctly for fontsets. -@fonta: -@fontb: -@Returns: +@fonta: a #GdkFont. +@fontb: another #GdkFont. +@Returns: %TRUE if the fonts are equal. - +Returns the metrics of a NULL-terminated string. -@font: -@string: -@lbearing: -@rbearing: -@width: -@ascent: -@descent: +@font: a #GdkFont. +@string: the NULL-terminated string to measure. +@lbearing: the left bearing of the string. +@rbearing: the right bearing of the string. +@width: the width of the string. +@ascent: the ascent of the string. +@descent: the descent of the string. - +Returns the metrics of a string. -@font: -@text: -@text_length: -@lbearing: -@rbearing: -@width: -@ascent: -@descent: +@font: a #GdkFont +@text: the text to measure +@text_length: the length of the text in bytes. (If the + font is a 16-bit font, this is twice the length + of the text in characters.) +@lbearing: the left bearing of the string. +@rbearing: the right bearing of the string. +@width: the width of the string. +@ascent: the ascent of the string. +@descent: the descent of the string. - +Returns the metrics of a string of wide characters. -@font: -@text: -@text_length: -@lbearing: -@rbearing: -@width: -@ascent: -@descent: +@font: a #GdkFont +@text: the text to measure. +@text_length: the length of the text in character. +@lbearing: the left bearing of the string. +@rbearing: the right bearing of the string. +@width: the width of the string. +@ascent: the ascent of the string. +@descent: the descent of the string. - +Determine the width of a NULL-terminated string. +(The distance from the origin of the string to the +point where the next string in a sequence of strings +should be drawn) -@font: -@string: -@Returns: +@font: a #GdkFont +@string: the NULL-terminated string to measure +@Returns: the width of the string in pixels. - +Determine the width of a given string. -@font: -@text: -@text_length: -@Returns: +@font: a #GdkFont +@text: the text to measure. +@text_length: the length of the text in bytes. +@Returns: the width of the string in pixels. - +Determine the width of a given wide-character string. -@font: -@text: -@text_length: -@Returns: +@font: a #GdkFont +@text: the text to measure. +@text_length: the length of the text in characters. +@Returns: the width of the string in pixels. - +Determine the width of a given character. -@font: -@character: -@Returns: +@font: a #GdkFont +@character: the character to measure. +@Returns: the width of the character in pixels. - +Determine the width of a given wide character. (Encoded +in the wide-character encoding of the current locale). -@font: -@character: -@Returns: +@font: a #GdkFont +@character: the character to measure. +@Returns: the width of the character in pixels. - +Determines the distance from the origin to the rightmost +portion of a NULL-terminated string when drawn. This is not the +correct value for determining the origin of the next +portion when drawing text in multiple pieces. +See gdk_string_width(). -@font: -@string: -@Returns: +@font: a #GdkFont +@string: the NULL-terminated string to measure. +@Returns: the right bearing of the string in pixels. - +Determines the distance from the origin to the rightmost +portion of a string when drawn. This is not the +correct value for determining the origin of the next +portion when drawing text in multiple pieces. +See gdk_text_width(). -@font: -@text: -@text_length: -@Returns: +@font: a #GdkFont +@text: the text to measure. +@text_length: the length of the text in bytes. +@Returns: the right bearing of the string in pixels. - +Determines the distance from the origin to the rightmost +portion of a character when drawn. This is not the +correct value for determining the origin of the next +portion when drawing text in multiple pieces. -@font: -@character: -@Returns: +@font: a #GdkFont +@character: the character to measure. +@Returns: the right bearing of the character in pixels. - +Determines the total height of a given NULL-terminated +string. This value is not generally useful, because you +cannot determine how this total height will be drawn in +relation to the baseline. See gdk_string_extents(). -@font: -@string: -@Returns: +@font: a #GdkFont +@string: the NULL-terminated string to measure. +@Returns: the height of the string in pixels. - +Determines the total height of a given string. +This value is not generally useful, because you cannot +determine how this total height will be drawn in +relation to the baseline. See gdk_text_extents(). -@font: -@text: -@text_length: -@Returns: +@font: a #GdkFont +@text: the text to measure. +@text_length: the length of the text in bytes. +@Returns: the height of the string in pixels. - +Determines the total height of a given character. +This value is not generally useful, because you cannot +determine how this total height will be drawn in +relation to the baseline. See gdk_text_extents(). -@font: -@character: -@Returns: +@font: a #GdkFont +@character: the character to measure. +@Returns: the height of the character in pixels. @@ -271,27 +607,63 @@ Fonts - +Specifies a wide character type, used to represent character codes. +This is needed since some native languages have character sets which have +more than 256 characters (Japanese and Chinese, for example). + + +Wide character values between 0 and 127 are always identical in meaning to +the ASCII character codes. The wide character value 0 is often used to +terminate strings of wide characters in a similar way to normal strings +using the char type. + + +An alternative to wide characters is multi-byte characters, which extend +normal char strings to cope with larger character sets. As the name suggests, +multi-byte characters use a different number of bytes to store different +character codes. For example codes 0-127 (i.e. the ASCII codes) often +use just one byte of memory, while other codes may use 2, 3 or even 4 bytes. +Multi-byte characters have the advantage that they can often be used in an +application with little change, since strings are still represented as arrays +of char values. However multi-byte strings are much easier to manipulate since +the character are all of the same size. + + +Applications typically use wide characters to represent character codes +internally, and multi-byte strings when saving the characters to a file. +The gdk_wcstombs() and gdk_mbstowcs() functions can be used to convert from +one representation to the other. + + +See the 'Extended Characters' section of the GNU C Library Reference Manual +for more detailed information on wide and multi-byte characters. - +Converts a wide character string to a multi-byte string. +(The function name comes from an acronym of 'Wide Character String TO +Multi-Byte String'). -@src: -@Returns: +@src: a wide character string. +@Returns: the multi-byte string corresponding to @src, or NULL if the +conversion failed. The returned string should be freed with g_free() when no +longer needed. - +Converts a multi-byte string to a wide character string. +(The function name comes from an acronym of 'Multi-Byte String TO Wide +Character String'). -@dest: -@src: -@dest_max: -@Returns: +@dest: the space to place the converted wide character string into. +@src: the multi-byte string to convert, which must be null-terminated. +@dest_max: the maximum number of wide characters to place in @dest. +@Returns: the number of wide characters written into @dest, or -1 if the +conversion failed. diff --git a/docs/reference/gdk/tmpl/gcs.sgml b/docs/reference/gdk/tmpl/gcs.sgml index 6f85c1df53..a72835bc60 100644 --- a/docs/reference/gdk/tmpl/gcs.sgml +++ b/docs/reference/gdk/tmpl/gcs.sgml @@ -2,11 +2,27 @@ Graphics Contexts - +objects to encapsulate drawing properties. - +All drawing operations in GDK take a +graphics context (GC) argument. +A graphics context encapsulates information about +the way things are drawn, such as the foreground +color or line width. By using graphics contexts, +the number of arguments to each drawing call is +greatly reduced, and communication overhead is +minimized, since identical arguments do not need +to be passed repeatedly. + + +Most values of a graphics context can be set at +creation time by using gdk_gc_new_with_values(), +or can be set one-by-one using functions such +as gdk_gc_set_foreground(). A few of the values +in the GC, such as the dash pattern, can only +be set by the latter method. @@ -16,7 +32,9 @@ Graphics Contexts - +The #GdkGC structure represents a graphics context. +It is an opaque structure with no user-visible +elements. @parent_instance: @@ -34,7 +52,104 @@ Graphics Contexts +The #GdkGCValues structure holds a set of values used +to create or modify a graphics context. + + + + + +#GdkColor foreground; +the foreground color. + + + +#GdkColor background; +the background color. + + + +#GdkFont *font; +the default font.. + + + +#GdkFunction function; +the bitwise operation used when drawing. + + + +#GdkFill fill; +the fill style. + + + +#GdkPixmap *tile; +the tile pixmap. + + + +#GdkPixmap *stipple; +the stipple bitmap. + + + +#GdkPixmap *clip_mask; +the clip mask bitmap. + + + +#GdkSubwindowMode subwindow_mode; +the subwindow mode. + + + +#gint ts_x_origin; +the x origin of the tile or stipple. + + + +#gint ts_y_origin; +the y origin of the tile or stipple. + + + +#gint clip_x_origin; +the x origin of the clip mask. + + + +#gint clip_y_origin; +the y origin of the clip mask. + + + +#gint graphics_exposures; +whether graphics exposures are enabled. + + + +#gint line_width; +the line width + + + +#GdkLineStyle line_style; +the way dashed lines are drawn + + + +#GdkCapStyle cap_style; +the way the ends of lines are drawn + + + +#GdkJoinStyle join_style; +the way joins between lines are drawn + + + @foreground: @@ -58,7 +173,8 @@ Graphics Contexts - +A set of bit flags used to indicate which fields +#GdkGCValues structure are set. @GDK_GC_FOREGROUND: @@ -82,7 +198,12 @@ Graphics Contexts - +Determines how the bit values for the source pixels are combined with +the bit values for destination pixels to produce the final result. The +sixteen values here correspond to the 16 different possible 2x2 truth +tables. Only a couple of these values are usually useful; for colored +images, only %GDK_COPY, %GDK_XOR and %GDK_INVERT are generally +useful. For bitmaps, %GDK_AND and %GDK_OR are also useful. @GDK_COPY: @@ -104,46 +225,58 @@ Graphics Contexts - +Create a new graphics context with default values. @drawable: -@Returns: +@Returns: the new graphics context. + +@window: a #GdkDrawable. The created GC must always be used + with drawables of the same depth as this one. - +Create a new GC with the given initial values. @drawable: -@values: -@values_mask: -@Returns: +@values: a structure containing initial values for the GC. +@values_mask: a bit mask indicating which fields in @values + are set. +@Returns: the new graphics context. + +@window: a #GdkDrawable. The created GC must always be used + with drawables of the same depth as this one. - +Increase the reference count on a graphics context. -@gc: -@Returns: +@gc: a #GdkGC. +@Returns: @gc. - +Decrease the reference count on a graphics context. If +the resulting reference count is zero, the graphics +context will be destroyed. -@gc: +@gc: a #GdkGC. - +Identical to gdk_gc_unref(). This function is obsolete +and should not be used. + +@gc: a #GdkGC. @@ -158,29 +291,29 @@ Graphics Contexts - +Retrieves the current values from a graphics context. -@gc: -@values: +@gc: a #GdkGC. +@values: the #GdkGCValues structure in which to store the results. - +Sets the foreground color for a graphics context. -@gc: -@color: +@gc: a #GdkGC. +@color: the new foreground color. - +Sets the background color for a graphics context. -@gc: -@color: +@gc: a #GdkGC. +@color: the new background color. @@ -203,34 +336,71 @@ Graphics Contexts - +Sets the font for a graphics context. (Note that +all text-drawing functions in GDK take a @font +argument; the value set here is used when that +argument is %NULL.) -@gc: -@font: +@gc: a #GdkGC. +@font: the new font. - +Determines how the current pixel values and the +pixel values being drawn are combined to produce +the final pixel values. -@gc: +@gc: a #GdkGC. @function: - +Set the fill mode for a graphics context. -@gc: -@fill: +@gc: a #GdkGC. +@fill: the new fill mode. +Determines how primitives are drawn. + + + + + +GDK_SOLID +draw with the foreground color. + + + +GDK_TILED +draw with a tiled pixmap. + + + +GDK_STIPPLED +draw using the stipple bitmap. Pixels corresponding +to bits in the stipple bitmap that are set will be drawn in the +foreground color; pixels corresponding to bits that are +not set will be left untouched. + + + +GDK_OPAQUE_STIPPLED +draw using the stipple bitmap. Pixels corresponding +to bits in the stipple bitmap that are set will be drawn in the +foreground color; pixels corresponding to bits that are +not set will be drawn with the background color. + + + @GDK_SOLID: @@ -240,81 +410,116 @@ Graphics Contexts - +Set a tile pixmap for a graphics context. +This will only be used if the fill mode +is %GDK_TILED. -@gc: -@tile: +@gc: a #GdkGC. +@tile: the new tile pixmap. - +Set the stipple bitmap for a graphics context. The +stipple will only be used if the fill mode is +%GDK_STIPPLED or %GDK_OPAQUE_STIPPLED. -@gc: -@stipple: +@gc: a #GdkGC. +@stipple: the new stipple bitmap. - +Set the origin when using tiles or stipples with +the GC. The tile or stipple will be aligned such +that the upper left corner of the tile or stipple +will coincide with this point. -@gc: -@x: -@y: +@gc: a #GdkGC. +@x: the x-coordinate of the origin. +@y: the y-coordinate of the origin. - +Sets the origin of the clip mask. The coordinates are +interpreted relative to the upper-left corner of +the destination drawable of the current operation. -@gc: -@x: -@y: +@gc: a #GdkGC. +@x: the x-coordinate of the origin. +@y: the y-coordinate of the origin. - +Sets the clip mask for a graphics context from a bitmap. +The clip mask is interpreted relative to the clip +origin. (See gdk_gc_set_clip_origin()). -@gc: -@mask: +@gc: the #GdkGC. +@mask: a bitmap. +Sets the clip mask for a graphics context from a +rectangle. The clip mask is interpreted relative to the clip +origin. (See gdk_gc_set_clip_origin()). -@gc: -@rectangle: +@gc: a #GdkGC. +@rectangle: the rectangle to clip to. - +Sets the clip mask for a graphics context from a region structure. +The clip mask is interpreted relative to the clip origin. (See +gdk_gc_set_clip_origin()). -@gc: -@region: +@gc: a #GdkGC. +@region: the #GdkRegion. - +Sets how drawing with this GC on a window will affect child +windows of that window. -@gc: -@mode: +@gc: a #GdkGC. +@mode: the subwindow mode. +Determines how drawing onto a window will affect child +windows of that window. + + + + + + +GDK_CLIP_BY_CHILDREN +only draw onto the window itself. + + + +GDK_INCLUDE_INFERIORS +Draw onto the window and child windows. + + + @GDK_CLIP_BY_CHILDREN: @@ -322,28 +527,57 @@ Graphics Contexts - +Sets whether copying non-visible portions of a drawable +using this graphics context generate exposure events +for the corresponding regions of the destination +drawable. (See gdk_draw_pixmap()). -@gc: -@exposures: +@gc: a #GdkGC. +@exposures: if %TRUE, exposure events will be generated. - +Sets various attributes of how lines are drawn. See +the corresponding members of GdkGCValues for full +explanations of the arguments. -@gc: -@line_width: -@line_style: -@cap_style: -@join_style: +@gc: a #GdkGC. +@line_width: the width of lines. +@line_style: the dash-style for lines. +@cap_style: the manner in which the ends of lines are drawn. +@join_style: the in which lines are joined together. +Determines how lines are drawn. + + + + + +GDK_LINE_SOLID +lines are drawn solid. + + + +GDK_LINE_ON_OFF_DASH +even segments are drawn; odd segments are not drawn. + + + +GDK_LINE_DOUBLE_DASH +even segments are normally. Odd segments are drawn +in the background color if the fill style is %GDK_SOLID, +or in the background color masked by the stipple if the +fill style is %GDK_STIPPLED. + + + @GDK_LINE_SOLID: @@ -352,7 +586,38 @@ Graphics Contexts +Determines how the end of lines are drawn. + + + + + +GDK_CAP_NOT_LAST +the same as %GDK_CAP_BUTT for lines of non-zero width. + for zero width lines, the final point on the line + will not be drawn. + + + +GDK_CAP_BUTT +the ends of the lines are drawn squared off and extending + to the coordinates of the end point. + + + +GDK_CAP_ROUND +the ends of the lines are drawn as semicircles with the + diameter equal to the line width and centered at the + end point. + + + +GDK_CAP_PROJECTING +the ends of the lines are drawn squared off and extending + half the width of the line beyond the end point. + + @GDK_CAP_NOT_LAST: @@ -362,7 +627,29 @@ Graphics Contexts +Determines how the joins between segments of a polygon are drawn. + + + + + +GDK_JOIN_MITER +the sides of each line are extended to meet at an angle. + + + +GDK_JOIN_ROUND +the sides of the two lines are joined by a circular arc. + + + +GDK_JOIN_BEVEL +the sides of the two lines are joined by a straight line which + makes an equal angle with each line. + + + @GDK_JOIN_MITER: @@ -371,22 +658,28 @@ Graphics Contexts - +Sets the way dashed-lines are drawn. Lines will be +drawn with alternating on and off segments of the +lengths specified in @dash_list. The manner in +which the on and off segments are drawn is determined +by the @line_style value of the GC. (This can +be changed with gdk_gc_set_line_attributes) -@gc: -@dash_offset: -@dash_list: -@n: +@gc: a #GdkGC. +@dash_offset: the +@dash_list: an array of dash lengths. +@n: the number of elements in @dash_list. - +Copy the set of values from one graphics context +onto another graphics context. -@dst_gc: -@src_gc: +@dst_gc: the destination graphics context. +@src_gc: the source graphics context. diff --git a/docs/reference/gdk/tmpl/gdk-unused.sgml b/docs/reference/gdk/tmpl/gdk-unused.sgml index fb52e4a9e9..7e2703d4a1 100644 --- a/docs/reference/gdk/tmpl/gdk-unused.sgml +++ b/docs/reference/gdk/tmpl/gdk-unused.sgml @@ -1,83 +1,1384 @@ - + + +The #GdkColorContext type is used for allocating groups of colors. + + +It is now deprecated in favor of the gdk_colormap_*() functions described in +the Colormaps and Colors +section. + + + + - + +routines for allocating colors (deprecated). + + + +Color Contexts + + + -Returns the difference between the union and the intersection of two regions. -This is a region containing the pixels that are in one of the source regions, -but which are not in both. +These functions are used to modify colormaps. +A colormap is an object that contains the mapping +between the color values stored in memory and +the RGB values that are used to display color +values. In general, colormaps only contain +significant information for pseudo-color visuals, +but even for other visual types, a colormap object +is required in some circumstances. -@source1: a #GdkRegion. -@source2: a #GdkRegion. -@Returns: the difference between the union and the intersection of @source1 -and @source2. - - -Retrieves the motion history for a given device/window pair. +There are a couple of special colormaps that can +be retrieved. The system colormap (retrieved +with gdk_colormap_get_system()) is the default +colormap of the system. If you are using GdkRGB, +there is another colormap that is important - the +colormap in which GdkRGB works, retrieved with +gdk_rgb_get_cmap(). However, when using GdkRGB, +it is not generally necessary to allocate colors +directly. -@window: a #GdkWindow. -@deviceid: the device for which to retrieve motion history. -@start: the start time. -@stop: the stop time. -@nevents_return: location to store the number of events returned. -@Returns: a newly allocated array containing all the events - from @start to @stop. This array should be freed - with g_free() when you are finished using it. + +In previous revisions of this interface, a number +of functions that take a #GdkColormap parameter +were replaced with functions whose names began +with "gdk_colormap_". This process will probably +be extended somewhat in the future - +gdk_color_white(), gdk_color_black(), and +gdk_color_change() will probably become aliases. + - + + - + +manipulation of colors and colormaps. + + + +Colormaps and Colors + + + -@keymap: -@hardware_keycode: -@state: -@group: -@keyval: -@effective_group: -@level: -@unused_modifiers: -@Returns: - + -@keymap: -@keyval: -@keys: -@n_keys: -@Returns: - + +standard and pixmap cursors. + + + +Cursors + + + + +These functions provide a low level interface for drag and drop. +GDK supports both the Xdnd and Motif drag and drop protocols transparently. + + +GTK+ provides a higher level abstraction based on top of these functions, +and so they are not normally needed in GTK+ applications. +See the Drag and Drop section of +the GTK+ documentation for more information. + + + + + +functions for controlling drag and drop handling. + + + +Drag and Drop + + + + +These functions provide support for drawing points, lines, arcs and text +onto what are called 'drawables'. Drawables, as the name suggests, are things +which support drawing onto them, and are either #GdkWindow or #GdkPixmap +objects. + + +Many of the drawing operations take a #GdkGC argument, which represents a +graphics context. This #GdkGC contains a number of drawing attributes such +as foreground color, background color and line width, and is used to reduce +the number of arguments needed for each drawing operation. See the +Graphics Contexts section for +more information. + + + + + + + + + + +functions for drawing points, lines, arcs, and text. + + + +Drawing Primitives + + + + +The event structs contain data specific to each type of event in GDK. + + + +A common mistake is to forget to set the event mask of a widget so that the +required events are received. See gtk_widget_set_events(). + + + + + + + + + + + +data structures specific to each type of event. + + + +Event Structures + + + + +This section describes functions dealing with events from the window system. + + +In GTK+ applications the events are handled automatically in +gtk_main_do_event() and passed on to the appropriate widgets, so these +functions are rarely needed. Though some of the fields in the +Event Structures are useful. + + + + + + + +Event Structures + +The structs used for each type of event. + + + + + + + +functions for handling events from the window system. + + + +Events + + + + +The GdkFont data type represents a font for drawing on +the screen. These functions provide support for +loading fonts, and also for determining the dimensions +of characters and strings when drawn with a particular +font. + + + +Fonts in X are specified by a +X Logical Font Description. +The following description is considerably simplified. +For definitive information about XLFD's see the +X reference documentation. A X Logical Font Description (XLFD) +consists of a sequence of fields separated (and surrounded by) '-' +characters. For example, Adobe Helvetica Bold 12 pt, has the +full description: + + +"-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1" + + + + +The fields in the XLFD are: + + + + + + +Foundry +the company or organization where the font originated. + + + +Family +the font family (a group of related font designs). + + + +Weight +A name for the font's typographic weight +For example, 'bold' or 'medium'). + + + +Slant +The slant of the font. Common values are 'R' for Roman, +'I' for italoc, and 'O' for oblique. + + + +Set Width +A name for the width of the font. For example, +'normal' or 'condensed'. + + + +Add Style +Additional information to distinguish a font from +other fonts of the same family. + + + +Pixel Size +The body size of the font in pixels. + + + +Point Size +The body size of the font in 10ths of a point. +(A point is 1/72.27 inch) + + + +Resolution X +The horizontal resolution that the font was designed for. + + + +Resolution Y +The vertical resolution that the font was designed for . + + + +Spacing +The type of spacing for the font - can be 'p' for proportional, +'m' for monospaced or 'c' for charcell. + + + +Average Width +The average width of a glyph in the font. For monospaced +and charcell fonts, all glyphs in the font have this width + + + +Charset Registry +The registration authority that owns the encoding for +the font. Together with the Charset Encoding field, this +defines the character set for the font. + + + +Charset Encoding +An identifier for the particular character set encoding. + + + + + + +When specifying a font via a X logical Font Description, +'*' can be used as a wildcard to match any portion of +the XLFD. For instance, the above example could +also be specified as + + +"-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1" + + +It is generally a good idea to use wildcards for any +portion of the XLFD that your program does not care +about specifically, since that will improve the +chances of finding a matching font. + + + +A fontset is a list of fonts +that is used for drawing international text that may +contain characters from a number of different character +sets. It is represented by a list of XLFD's. + + + +The font for a given character set is determined by going +through the list of XLFD's in order. For each one, if +the registry and and encoding fields match the desired +character set, then that font is used, otherwise if +the XLFD contains wild-cards for the registry and encoding +fields, the registry and encoding for the desired character +set are subsituted in and a lookup is done. If a match is found +that font is used. Otherwise, processing continues +on to the next font in the list. + + + +The functions for determining the metrics of a string +come in several varieties that can take a number +of forms of string input: + + + + 8-bit string + + When using functions like gdk_string_width() that + take a gchar *, if the font is of type + %GDK_FONT_FONT and is an 8-bit font, then each + gchar indexes the glyphs in the font directly. + + + + 16-bit string + + For functions taking a gchar *, if the + font is of type %GDK_FONT_FONT, and is a 16-bit + font, then the gchar * argument is + interpreted as a guint16 * cast to + a gchar * and each guint16 + indexes the glyphs in the font directly. + + + + Multibyte string + + For functions taking a gchar *, if the + font is of type %GDK_FONT_FONTSET, then the input + string is interpreted as a multibyte + encoded according to the current locale. (A multibyte + string is one in which each character may consist + of one or more bytes, with different lengths for different + characters in the string). They can be converted to and + from wide character strings (see below) using + gdk_wcstombs() and gdk_mbstowcs().) The string will + be rendered using one or more different fonts from + the fontset. + + + + Wide character string + + For a number of the text-measuring functions, GTK+ + provides a variant (such as gdk_text_width_wc()) which + takes a GdkWChar * instead of a + gchar *. The input is then taken to + be a wide character string in the encoding of the + current locale. (A wide character string is a string + in which each character consists of several bytes, + and the width of each character in the string is + constant.) + + + + + + +GDK provides functions to determine a number of different +measurements (metrics) for a given string. (Need diagram +here). + + + + ascent + + The vertical distance from the origin of the drawing + opereration to the top of the drawn character. + + + + descent + + The vertical distance from the origin of the drawing + opereration to the bottom of the drawn character. + + + + left bearing + + The horizontal distance from the origin of the drawing + operation to the left-most part of the drawn character. + + + + right bearing + + The horizontal distance from the origin of the drawing + operation to the right-most part of the drawn character. + + + + width bearing + + The horizontal distance from the origin of the drawing + operation to the correct origin for drawing another + string to follow the current one. Depending on the + font, this could be greater than or less than the + right bearing. + + + + + + + + + + + + + +loading and manipulating fonts + + + +Fonts + + + + +All drawing operations in GDK take a +graphics context (GC) argument. +A graphics context encapsulates information about +the way things are drawn, such as the foreground +color or line width. By using graphics contexts, +the number of arguments to each drawing call is +greatly reduced, and communication overhead is +minimized, since identical arguments do not need +to be passed repeatedly. + + +Most values of a graphics context can be set at +creation time by using gdk_gc_new_with_values(), +or can be set one-by-one using functions such +as gdk_gc_set_foreground(). A few of the values +in the GC, such as the dash pattern, can only +be set by the latter method. + + + + + + + + + + +objects to encapsulate drawing properties. + + + +Graphics Contexts + + + + + + + + + + + + + +Keyboard Handling + + + + + + + + + + + + + + + + + + + +Points, Rectangles and Regions + + + + +The functions in this section are used to establish +callbacks when some condition becomes true for +a file descriptor. They are currently just wrappers around +the IO Channel +facility. + + + + + + + + +GLib Main Loop +The main loop in which input callbacks run. + + + +IO Channels +A newer and more flexible way of doing IO +callbacks. + + + + + + + +Callbacks on file descriptors. + + + +Input + + + + +A #GdkIC input context is used for each user interface element which supports +internationalized text input. See the +Input Methods section for an overview +of how internationalized text input works in GTK+. + + + + + + + + + + +internationalized text input properties. + + + +Input Contexts + + + + +In addition to the normal keyboard and mouse input devices, GTK+ also +contains support for extended input devices. In +particular, this support is targeted at graphics tablets. Graphics +tablets typically return sub-pixel positioning information and possibly +information about the pressure and tilt of the stylus. Under +X, the support for extended devices is done through the +XInput extension. + + +Because handling extended input devices may involve considerable +overhead, they need to be turned on for each #GdkWindow +individually using gdk_input_set_extension_events(). +(Or, more typically, for GtkWidgets, using gtk_widget_set_extension_events()). +As an additional complication, depending on the support from +the windowing system, its possible that a normal mouse +cursor will not be displayed for a particular extension +device. If an application does not want to deal with displaying +a cursor itself, it can ask only to get extension events +from devices that will display a cursor, by passing the +%GDK_EXTENSION_EVENTS_CURSOR value to +gdk_input_set_extension_events(). Otherwise, the application +must retrieve the device information using gdk_input_list_devices(), +check the has_cursor field, and, +if it is %FALSE, draw a cursor itself when it receives +motion events. + + +Each pointing device is assigned a unique integer ID; events from a +particular device can be identified by the +deviceid field in the event structure. The +events generated by pointer devices have also been extended to contain +pressure, xtilt +and ytilt fields which contain the extended +information reported as additional valuators +from the device. The pressure field is a +a double value ranging from 0.0 to 1.0, while the tilt fields are +double values ranging from -1.0 to 1.0. (With -1.0 representing the +maximum title to the left or up, and 1.0 representing the maximum +tilt to the right or down.) + + +One additional field in each event is the +source field, which contains an +enumeration value describing the type of device; this currently +can be one of +%GDK_SOURCE_MOUSE, + %GDK_SOURCE_PEN, +%GDK_SOURCE_ERASER, +or %GDK_SOURCE_CURSOR. This field is present to allow simple +applications to (for instance) delete when they detect eraser +devices without having to keep track of complicated per-device +settings. + + +Various aspects of each device may be configured. The easiest way of +creating a GUI to allow the user to conifigure such a device +is to use to use the #GtkInputDialog widget in GTK+. +However, even when using this widget, application writers +will need to directly query and set the configuration parameters +in order to save the state between invocations of the application. +The configuration of devices is queried using gdk_input_list_devices. +Each device must is activated using gdk_input_set_mode(), which +also controls whether the device's range is mapped to the +entire screen or to a single window. The mapping of the valuators of +the device onto the predefined valuator types is set using +gdk_input_set_axes. And the source type for each device +can be set with gdk_input_set_source(). + + +Devices may also have associated keys +or macro buttons. Such keys can be globally set to map +into normal X keyboard events. The mapping is set using +gdk_input_set_key(). + + +The interfaces in this section will most likely be considerably +modified in the future to accomodate devices that may have different +sets of additional valuators than the pressure xtilt and ytilt. + + + + + + + + + + +Functions for handling extended input devices. + + + +Input Devices + + + + + + + + + + + + + + + +Pango Interaction + + + + +Input Methods provide a way for complex character sets to be used in GTK+. +Languages such as Chinese, Japanese, and Korean (often abbreviated to CJK) +use a large number of ideographs, making it impossible to support all +characters with a simple keyboard. Instead, text is usually +pre-edited using a phonetic alphabet and then +composed to form the ideographs. + + +GTK+ makes use of the input method mechanism provided by the X Windows +platform. When a GTK+ application is started, it opens a connection to the +input method appropriate for the current locale (if any). + + +Widgets which handle textual input, such as #GtkEntry, need to do a number of +things to support internationalized text input: + + +When the widget is realized: +Check if an input method is being used with gdk_im_ready(). +If it is, create a new Input Context +using gdk_ic_new(). Find out which events the +Input Context needs to receive +with gdk_ic_get_events(), and make sure that the widget's window receives +these events using gdk_window_set_events(). + + + + +When the widget's size, state or cursor position changes: + +Update the appropriate +Input Context attributes +using gdk_ic_set_attr(). + + + + +When the keyboard focus enters or leaves the widget: + +Call gdk_im_begin() or gdk_im_end() to start or finish editing the text. + + + + +When the widget receives a key_press event: + +The string and length +fields of the #GdkEventKey struct should be used to insert the composed text +into the widget. + + + + +When the widget is unrealized: + +Destroy the Input Context. + + + + + + +See the XLib reference manual for more detailed information on input methods, +and the #GtkEntry and #GtkText widgets for some example code. + + + + + + + +Input Contexts + +Used for each widget that handles internationalized text input using the +global input method. + + + + + + + + +support for internationalized text input. + + + +Input Methods + + + + +Key values are the codes which are sent whenever a key is pressed or released. +They appear in the keyval field of the +#GdkEventKey structure, which is passed to signal handlers for the +"key-press-event" and "key-release-event" signals. +The complete list of key values can be found in the <gdk/gdkkeysyms.h> +header file. + + +Key values can be converted into a string representation using +gdk_keyval_name(). The reverse function, converting a string to a key value, +is provided by gdk_keyval_from_name(). + + +The case of key values can be determined using gdk_keyval_is_upper() and +gdk_keyval_is_lower(). Key values can be converted to upper or lower case +using gdk_keyval_to_upper() and gdk_keyval_to_lower(). + + + + + + + + + + +functions for manipulating keyboard codes. + + + +Key Values + + + + + + + + + + + + + + + + + + + +Pango Interaction + + + + + + + + + + + + + + + + + + + +Pixbufs + + + + +Each window under X can have any number of associated +properties attached to it. +Properties are arbitrary chunks of data identified by +atoms. (An atom +is a numeric index into a string table on the X server. They are used +to transfer strings efficiently between clients without +having to transfer the entire string.) A property +has an associated type, which is also identified +using an atom. + + +A property has an associated format, +an integer describing how many bits are in each unit +of data inside the property. It must be 8, 16, or 32. +When data is transfered between the server and client, +if they are of different endianesses it will be byteswapped +as necessary according to the format of the property. +Note that on the client side, properties of format 32 +will be stored with one unit per long, +even if a long integer has more than 32 bits on the platform. +(This decision was apparently made for Xlib to maintain +compatibility with programs that assumed longs were 32 +bits, at the expense of programs that knew better.) + + +The functions in this section are used to add, remove +and change properties on windows, to convert atoms +to and from strings and to manipulate some types of +data commonly stored in X window properties. + + + + + + + + + + +functions to manipulate properties on windows. + + + +Properties and Atoms + + + + +GDK provides the #GdkPoint, #GdkRectangle, #GdkRegion and #GdkSpan data types +for representing pixels and sets of pixels on the screen. + + +#GdkPoint is a simple structure containing an x and y coordinate of a point. + + +#GdkRectangle is a structure holding the position and size of a rectangle. +The intersection of two rectangles can be computed with +gdk_rectangle_intersect(). To find the union of two rectangles use +gdk_rectangle_union(). + + +#GdkRegion is an opaque data type holding a set of arbitrary pixels, and is +usually used for clipping graphical operations (see gdk_gc_set_clip_region()). + + +#GdkSpan is a structure holding a spanline. A spanline is a horizontal line that +is one pixel wide. It is mainly used when rasterizing other graphics primitives. +It can be intersected to regions by using gdk_region_spans_intersect_foreach(). + + + + + + + + + + +simple graphical data types. + + + +Points, Rectangles and Regions + + + + +GDK provides the #GdkPoint, #GdkRectangle and #GdkRegion data types for +representing pixels and sets of pixels on the screen. + + +#GdkPoint is a simple structure containing an x and y coordinate of a point. + + +#GdkRectangle is a structure holding the position and size of a rectangle. +The intersection of two rectangles can be computed with +gdk_rectangle_intersect(). To find the union of two rectangles use +gdk_rectangle_union(). + + +#GdkRegion is an opaque data type holding a set of arbitrary pixels, and is +usually used for clipping graphical operations (see gdk_gc_set_clip_region()). + + + + + + + + + + +simple graphical data types. + + + +Points, Rectangles and Regions + + + + + +GdkRgb converts RGB, grayscale, and colormapped images into the native +window pixel format and displays them. It takes care of colormaps, +visuals, dithering, and management of the temporary buffers. + + + + +You must call gdk_rgb_init() before using any GdkRgb functionality. If +you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb +(including #GtkPreview) call gdk_rgb_init() in their class_init method. +Thus, if you use GdkRgb only indirectly, you don't need to worry +about it. + + + +GdkRgb tries to use the system default visual and colormap, but +doesn't always succeed. Thus, you have to be prepared to install the +visual and colormap generated by GdkRgb. The following code sequence +(before any widgets are created) should work in most applications: + + + + + gdk_rgb_init (); + + gtk_widget_set_default_colormap (gdk_rgb_get_cmap ()); + gtk_widget_set_default_visual (gdk_rgb_get_visual ()); + + + + +You can also push the colormap and visual, but in general it doesn't +work unless the push wraps the window creation call. If you wrap the +push around a widget which is embedded in a window without the GdkRgb +colormap and visual, it probably won't work, and is likely to cause +colormap flashing, as well. + + + +On 8-bit systems, the colormaps used by Imlib and GdkRgb may +conflict. There is no good general solution to this other than phasing +out the dependence on Imlib. + + + +You can set the threshold for installing colormaps with +gdk_rgb_set_min_colors (). The default is 5x5x5 (125). If a colorcube +of this size or larger can be allocated in the default colormap, then +that's done. Otherwise, GdkRgb creates its own private colormap. +Setting it to 0 means that it always tries to use the default +colormap, and setting it to 216 means that it always creates a private +one if it cannot allocate the 6x6x6 colormap in the default. If you +always want a private colormap (to avoid consuming too many colormap +entries for other apps, say), you can use gdk_rgb_set_install(TRUE). +Setting the value greater than 216 exercises a bug in older versions +of GdkRgb. Note, however, that setting it to 0 doesn't let you get +away with ignoring the colormap and visual - a colormap is always +created in grayscale and direct color modes, and the visual is changed +in cases where a "better" visual than the default is available. + + + +A simple example program using GdkRGB. + +#include <gtk/gtk.h> + +#define IMAGE_WIDTH 256 +#define IMAGE_HEIGHT 256 + +guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3]; + +gboolean on_darea_expose (GtkWidget *widget, + GdkEventExpose *event, + gpointer user_data); + +int +main (int argc, char *argv[]) +{ + GtkWidget *window, *darea; + gint x, y; + guchar *pos; + + gtk_init (&argc, &argv); + gdk_rgb_init (); + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + darea = gtk_drawing_area_new (); + gtk_drawing_area_size (GTK_DRAWING_AREA (darea), IMAGE_WIDTH, IMAGE_HEIGHT); + gtk_container_add (GTK_CONTAINER (window), darea); + gtk_signal_connect (GTK_OBJECT (darea), "expose-event", + GTK_SIGNAL_FUNC (on_darea_expose), NULL); + gtk_widget_show_all (window); + + /* Set up the RGB buffer. */ + pos = rgbbuf; + for (y = 0; y < IMAGE_HEIGHT; y++) + { + for (x = 0; x < IMAGE_WIDTH; x++) + { + *pos++ = x - x % 32; /* Red. */ + *pos++ = (x / 32) * 4 + y - y % 32; /* Green. */ + *pos++ = y - y % 32; /* Blue. */ + } + } + + gtk_main (); + return 0; +} + + +gboolean +on_darea_expose (GtkWidget *widget, + GdkEventExpose *event, + gpointer user_data) +{ + gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL], + 0, 0, IMAGE_WIDTH, IMAGE_HEIGHT, + GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3); +} + + + + + + + + + +#GdkColor +The underlying Gdk mechanism for allocating +colors. + + + + + + + + +displays RGB images (as well as grayscale and colormapped) to +the native window. + + + +GdkRGB + + + + +The X selection mechanism provides a way to transfer +arbitrary chunks of data between programs. +A selection is a essentially +a named clipboard, identified by a string interned +as a #GdkAtom. By claiming ownership of a selection, +an application indicates that it will be responsible +for supplying its contents. The most common +selections are PRIMARY and +CLIPBOARD. + + +The contents of a selection can be represented in +a number of formats, called targets. +Each target is identified by an atom. A list of +all possible targets supported by the selection owner +can be retrieved by requesting the special target +TARGETS. When a selection is +retrieved, the data is accompanied by a type +(an atom), and a format (an integer, representing +the number of bits per item). +See Properties and Atoms +for more information. + + +The functions in this section only contain the lowlevel +parts of the selection protocol. A considerably more +complicated implementation is needed on top of this. +GTK+ contains such an implementation in the functions +in gtkselection.h and programmers +should use those functions instead of the ones presented +here. If you plan to implement selection handling +directly on top of the functions here, you should refer +to the X Inter-client Communication Conventions Manual +(ICCCM). + + + + + + + + + + +functions for transfering data via the X selection mechanism. + + + +Selections + + + + + + + + + + + + + + + + + + + +Threads + + + + +The way that the data stored on the screen is stored +in memory can vary considerably between different X +servers; some X servers even support multiple formats +used simultaneously. An X visual +represents a particular format for screen data. +It includes information about the number of bits +used for each color, the way the bits are translated +into an RGB value for display, and the way the bits +are stored in memory. + + +There are several standard visuals. The visual returned +by gdk_visual_get_system() is the system's default +visual. gdk_rgb_get_visual() return the visual most +suited to displaying full-color image data. If you +use the calls in GdkRGB, you should create your windows +using this visual (and the colormap returned by +gdk_rgb_get_colormap()). + + +A number of functions are provided for determining +the "best" available visual. For the purposes of +making this determination, higher bit depths are +considered better, and for visuals of the same +bit depth, %GDK_VISUAL_PSEUDO_COLOR is preferred at +8bpp, otherwise, the visual types are ranked in the +order of (highest to lowest) %GDK_VISUAL_DIRECT_COLOR, +%GDK_VISUAL_TRUE_COLOR, %GDK_VISUAL_PSEUDO_COLOR, +%GDK_VISUAL_STATIC_COLOR, %GDK_VISUAL_GRAYSCALE, +then %GDK_VISUAL_STATIC_GRAY. + + + + + + + + + + +manipulation of visuals. + + + +Visuals + + + + + + + + + + + + + + + + + + + +Windows + + + + + + + + + + + + + + + + + + + +X Window System Interaction + + + + +This macro contains an integer value representing +the device ID for the core pointer device. + + + + + + + + +@visual: +@colormap: +@num_colors: +@max_colors: +@num_allocated: +@mode: +@need_to_free_colormap: +@std_cmap_atom: +@clut: +@cmap: +@color_hash: +@palette: +@num_palette: +@fast_dither: + + + + + + +@fast_rgb: +@fast_err: +@fast_erg: +@fast_erb: + + + + + + +@GDK_CC_MODE_UNDEFINED: +@GDK_CC_MODE_BW: +@GDK_CC_MODE_STD_CMAP: +@GDK_CC_MODE_TRUE: +@GDK_CC_MODE_MY_GRAY: +@GDK_CC_MODE_PALETTE: + The #GdkDeviceInfo structure contains information about a @@ -102,78 +1403,178 @@ device. It has the following fields: which describe what key press events are generated for each macro button. - -Pango Interaction - - - - -Returns the union of two regions. -This is all pixels in either of @source1 or @source2. - - -@source1: a #GdkRegion. -@source2: a #GdkRegion. -@Returns: the union of @source1 and @source2. - - + -@drawable: +@GDK_PIXBUF_ALPHA_BILEVEL: +@GDK_PIXBUF_ALPHA_FULL: + + + + + + +@cc: +@palette: +@num_palette: @Returns: - + +@cc: + + + + + + +@cc: + + + + + + +@cc: +@red: +@green: +@blue: +@failed: +@Returns: + + + + + + +@cc: +@red: +@green: +@blue: +@failed: +@Returns: + + + + + + +@cc: +@red: +@green: +@blue: +@failed: +@Returns: + + + + + + +@cc: +@reds: +@greens: +@blues: +@ncolors: +@colors: +@nallocated: + + + + + + +@cc: +@reds: +@greens: +@blues: +@ncolors: +@used: +@colors: +@nallocated: + + + + + + +@cc: + + + + + + +@visual: @colormap: -@pixel: -@result: +@Returns: - + -@event: -@state: +@visual: +@colormap: @Returns: - - - - - + -@window: -@decorations: +@cc: +@color: @Returns: - + -@keymap: -@hardware_keycode: -@keys: -@keyvals: -@n_entries: +@cc: +@colors: +@num_colors: @Returns: - + - +Lists all available input devices, along with their +configuration information. -@drawable: -@Returns: +@Returns: A #GList of #GdkDeviceInfo structures. This list + is internal data of GTK+ and should not be modified + or freed. + + + +Retrieves the motion history for a given device/window pair. + + +@window: a #GdkWindow. +@deviceid: the device for which to retrieve motion history. +@start: the start time. +@stop: the stop time. +@nevents_return: location to store the number of events returned. +@Returns: a newly allocated array containing all the events + from @start to @stop. This array should be freed + with g_free() when you are finished using it. + + + +Sets the mapping of the axes (valuators) of a device +onto the predefined valuator types that GTK+ understands. + + +@deviceid: the device to configure. +@axes: an array of GdkAxisUse. This length of this array + must match the number of axes for the device. @@ -187,47 +1588,24 @@ Sets the key event generated when a macro button is pressed. @modifiers: the modifier field for the generated #GdkKeyPressEvent. - + -Lists all available input devices, along with their -configuration information. +Enables or disables a device, and determines how the +device maps onto the screen. -@Returns: A #GList of #GdkDeviceInfo structures. This list - is internal data of GTK+ and should not be modified - or freed. +@deviceid: the device to configure. +@mode: the new mode. +@Returns: %TRUE if the device supports the given mode, otherwise + %FALSE and the device's mode is unchanged. - + - +Sets the source type for a device. -@parent_instance: - - - - - - - - - - - - -@GDK_PIXBUF_ALPHA_BILEVEL: -@GDK_PIXBUF_ALPHA_FULL: - - - -Subtracts one region from another. -The result is a region containing all the pixels which are in @source1, but -which are not in @source2. - - -@source1: a #GdkRegion. -@source2: a #GdkRegion to subtract from @source1. -@Returns: @source1 - @source2. +@deviceid: the device to configure +@source: the new source type. @@ -246,78 +1624,6 @@ they will be ignored. @ytilt: location to store current tilt in the y direction. @mask: location to store the current modifier state. - - - - - - -This macro contains an integer value representing -the device ID for the core pointer device. - - - - - -Sets the mapping of the axes (valuators) of a device -onto the predefined valuator types that GTK+ understands. - - -@deviceid: the device to configure. -@axes: an array of GdkAxisUse. This length of this array - must match the number of axes for the device. - - - - - - -@x: -@y: -@width: - - - - - - -@keycode: -@group: -@level: - - - -Sets the source type for a device. - - -@deviceid: the device to configure -@source: the new source type. - - - -Intersects a set of spans with a region and call a user specified -function for each resulting spanline. This function is a lot more effective -if the spans are sorted. - - -@region: The region to intersect against. -@spans: Array of spans to intersect. -@n_spans: Number of spans. -@sorted: True if the spans are sorted in increasing y order. -@function: The function to call for each intersected spanline. -@data: Opaque user data passed to function. - - - - - - -@Returns: - - -Points, Rectangles and Regions - - Returns the intersection of two regions. @@ -327,56 +1633,36 @@ Returns the intersection of two regions. @source2: a #GdkRegion. @Returns: the intersection of @source1 and @source2. - + - +Subtracts one region from another. +The result is a region containing all the pixels which are in @source1, but +which are not in @source2. -@keymap: -@key: -@Returns: +@source1: a #GdkRegion. +@source2: a #GdkRegion to subtract from @source1. +@Returns: @source1 - @source2. - + - +Returns the union of two regions. +This is all pixels in either of @source1 or @source2. -@span: The intersected part of the span. -@data: Opaque data passed by user. +@source1: a #GdkRegion. +@source2: a #GdkRegion. +@Returns: the union of @source1 and @source2. - + - - - - - -Keyboard Handling - - - - - - - -@keycode: -@group: -@level: - - - -Enables or disables a device, and determines how the -device maps onto the screen. - - -@deviceid: the device to configure. -@mode: the new mode. -@Returns: %TRUE if the device supports the given mode, otherwise - %FALSE and the device's mode is unchanged. - - - - +Returns the difference between the union and the intersection of two regions. +This is a region containing the pixels that are in one of the source regions, +but which are not in both. +@source1: a #GdkRegion. +@source2: a #GdkRegion. +@Returns: the difference between the union and the intersection of @source1 +and @source2. diff --git a/docs/reference/gdk/tmpl/images.sgml b/docs/reference/gdk/tmpl/images.sgml index f3ef9f1a28..1fe14205ca 100644 --- a/docs/reference/gdk/tmpl/images.sgml +++ b/docs/reference/gdk/tmpl/images.sgml @@ -2,79 +2,131 @@ Images - +an area for bit-mapped graphics stored on the X Windows client. - +The #GdkImage type represents an area for drawing graphics. +It has now been superceded to a large extent by the much more flexible +GdkRGB functions. + + +To create an empty #GdkImage use gdk_image_new(). +To create a #GdkImage from bitmap data use gdk_image_new_bitmap(). +To create an image from part of a #GdkWindow use gdk_image_get(). + + +The image can be manipulated with gdk_image_get_pixel() and +gdk_image_put_pixel(), or alternatively by changing the actual pixel data. +Though manipulating the pixel data requires complicated code to cope with +the different formats that may be used. + + +To draw a #GdkImage in a #GdkWindow or #GdkPixmap use gdk_draw_image(). + + +To destroy a #GdkImage use gdk_image_destroy(). + + +Bitmaps and Pixmaps + +Graphics which are stored on the X Windows server. +Since these are stored on the server they can be drawn very quickly, and all +of the Drawing Primitives can be +used to draw on them. Their main disadvantage is that manipulating individual +pixels can be very slow. + + + + +GdkRGB + +Built on top of #GdkImage, this provides much more functionality, +including the dithering of colors to produce better output on low-color +displays. + + + + - +The #GdkImage struct contains information on the image and the pixel data. @parent_instance: -@type: -@visual: -@byte_order: -@width: -@height: -@depth: -@bpp: -@bpl: -@mem: +@type: the type of the image. +@visual: the visual. +@byte_order: the byte order. +@width: the width of the image in pixels. +@height: the height of the image in pixels. +@depth: the depth of the image, i.e. the number of bits per pixel. +@bpp: the number of bytes per pixel. +@bpl: the number of bytes per line of the image. +@bits_per_pixel: +@mem: the pixel data. @windowing_data: - +Creates a new #GdkImage. -@type: -@visual: -@width: -@height: -@Returns: +@type: the type of the #GdkImage, one of %GDK_IMAGE_NORMAL, %GDK_IMAGE_SHARED +and %GDK_IMAGE_FASTEST. %GDK_IMAGE_FASTEST is probably the best choice, since +it will try creating a %GDK_IMAGE_SHARED image first and if that fails it will +then use %GDK_IMAGE_NORMAL. +@visual: the #GdkVisual to use for the image. +@width: the width of the image in pixels. +@height: the height of the image in pixels. +@Returns: a new #GdkImage, or NULL if the image could not be created. - +Specifies the type of a #GdkImage. -@GDK_IMAGE_NORMAL: -@GDK_IMAGE_SHARED: -@GDK_IMAGE_FASTEST: +@GDK_IMAGE_NORMAL: The original X image type, which is quite slow since the +image has to be transferred from the client to the server to display it. +@GDK_IMAGE_SHARED: A faster image type, which uses shared memory to transfer +the image data between client and server. However this will only be available +if client and server are on the same machine and the shared memory extension +is supported by the server. +@GDK_IMAGE_FASTEST: Specifies that %GDK_IMAGE_SHARED should be tried first, +and if that fails then %GDK_IMAGE_NORMAL will be used. - +Creates a new #GdkImage with a depth of 1 from the given data. -@visual: -@data: -@width: -@height: -@Returns: +@visual: the #GdkVisual to use for the image. +@data: the pixel data. +@width: the width of the image in pixels. +@height: the height of the image in pixels. +@Returns: a new #GdkImage. - +Gets part of a #GdkWindow and stores it in a new #GdkImage. @drawable: -@x: -@y: -@width: -@height: -@Returns: +@x: the left edge of the rectangle to copy from @window. +@y: the top edge of the rectangle to copy from @window. +@width: the width of the area to copy, in pixels. +@height: the height of the area to copy, in pixels. +@Returns: a new #GdkImage with a copy of the given area of @window. + +@window: the #GdkWindow to copy from. @@ -96,30 +148,32 @@ Images - +Destroys a #GdkImage, freeing any resources allocated for it. + +@image: a #GdkImage. - +Sets a pixel in a #GdkImage to a given pixel value. -@image: -@x: -@y: -@pixel: +@image: a #GdkImage. +@x: the x coordinate of the pixel to set. +@y: the y coordinate of the pixel to set. +@pixel: the pixel value to set. - +Gets a pixel value at a specified position in a #GdkImage. -@image: -@x: -@y: -@Returns: +@image: a #GdkImage. +@x: the x coordinate of the pixel to get. +@y: the y coordinate of the pixel to get. +@Returns: the pixel value at the given position. diff --git a/docs/reference/gdk/tmpl/regions.sgml b/docs/reference/gdk/tmpl/regions.sgml index 387544c82b..816da7bd29 100644 --- a/docs/reference/gdk/tmpl/regions.sgml +++ b/docs/reference/gdk/tmpl/regions.sgml @@ -35,41 +35,45 @@ It can be intersected to regions by using gdk_region_spans_intersect_foreach(). - +Defines the x and y coordinates of a point. +Note that both are defined as #gint16 values, so the coordinates are limited +to between -32,768 and 32,767. -@x: -@y: +@x: the x coordinate of the point. +@y: the y coordinate of the point. - +Defines the position and size of a rectangle. -@x: -@y: -@width: -@height: +@x: the x coordinate of the left edge of the rectangle. +@y: the y coordinate of the top of the rectangle. +@width: the width of the rectangle. +@height: the height of the rectangle. - +Calculates the intersection of two rectangles. -@src1: -@src2: -@dest: -@Returns: +@src1: a #GdkRectangle. +@src2: a #GdkRectangle. +@dest: the intersection of @src1 and @src2. +@Returns: TRUE if the rectangles intersect. - +Calculates the union of two rectangles. +The union of rectangles @src1 and @src2 is the smallest rectangle which +includes both @src1 and @src2 within it. -@src1: -@src2: -@dest: +@src1: a #GdkRectangle. +@src2: a #GdkRectangle. +@dest: the union of @src1 and @src2. diff --git a/docs/reference/gdk/tmpl/rgb.sgml b/docs/reference/gdk/tmpl/rgb.sgml index 03920b93c9..c60cde24ac 100644 --- a/docs/reference/gdk/tmpl/rgb.sgml +++ b/docs/reference/gdk/tmpl/rgb.sgml @@ -2,106 +2,294 @@ GdkRGB - +displays RGB images (as well as grayscale and colormapped) to +the native window. +GdkRgb converts RGB, grayscale, and colormapped images into the native +window pixel format and displays them. It takes care of colormaps, +visuals, dithering, and management of the temporary buffers. + + +You must call gdk_rgb_init() before using any GdkRgb functionality. If +you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb +(including #GtkPreview) call gdk_rgb_init() in their class_init method. +Thus, if you use GdkRgb only indirectly, you don't need to worry +about it. + + + +GdkRgb tries to use the system default visual and colormap, but +doesn't always succeed. Thus, you have to be prepared to install the +visual and colormap generated by GdkRgb. The following code sequence +(before any widgets are created) should work in most applications: + + + + + gdk_rgb_init (); + + gtk_widget_set_default_colormap (gdk_rgb_get_cmap ()); + gtk_widget_set_default_visual (gdk_rgb_get_visual ()); + + + + +You can also push the colormap and visual, but in general it doesn't +work unless the push wraps the window creation call. If you wrap the +push around a widget which is embedded in a window without the GdkRgb +colormap and visual, it probably won't work, and is likely to cause +colormap flashing, as well. + + + +On 8-bit systems, the colormaps used by Imlib and GdkRgb may +conflict. There is no good general solution to this other than phasing +out the dependence on Imlib. + + + +You can set the threshold for installing colormaps with +gdk_rgb_set_min_colors (). The default is 5x5x5 (125). If a colorcube +of this size or larger can be allocated in the default colormap, then +that's done. Otherwise, GdkRgb creates its own private colormap. +Setting it to 0 means that it always tries to use the default +colormap, and setting it to 216 means that it always creates a private +one if it cannot allocate the 6x6x6 colormap in the default. If you +always want a private colormap (to avoid consuming too many colormap +entries for other apps, say), you can use gdk_rgb_set_install(TRUE). +Setting the value greater than 216 exercises a bug in older versions +of GdkRgb. Note, however, that setting it to 0 doesn't let you get +away with ignoring the colormap and visual - a colormap is always +created in grayscale and direct color modes, and the visual is changed +in cases where a "better" visual than the default is available. + + + +A simple example program using GdkRGB. + +#include <gtk/gtk.h> + +#define IMAGE_WIDTH 256 +#define IMAGE_HEIGHT 256 + +guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3]; + +gboolean on_darea_expose (GtkWidget *widget, + GdkEventExpose *event, + gpointer user_data); + +int +main (int argc, char *argv[]) +{ + GtkWidget *window, *darea; + gint x, y; + guchar *pos; + + gtk_init (&argc, &argv); + gdk_rgb_init (); + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + darea = gtk_drawing_area_new (); + gtk_drawing_area_size (GTK_DRAWING_AREA (darea), IMAGE_WIDTH, IMAGE_HEIGHT); + gtk_container_add (GTK_CONTAINER (window), darea); + gtk_signal_connect (GTK_OBJECT (darea), "expose-event", + GTK_SIGNAL_FUNC (on_darea_expose), NULL); + gtk_widget_show_all (window); + + /* Set up the RGB buffer. */ + pos = rgbbuf; + for (y = 0; y < IMAGE_HEIGHT; y++) + { + for (x = 0; x < IMAGE_WIDTH; x++) + { + *pos++ = x - x % 32; /* Red. */ + *pos++ = (x / 32) * 4 + y - y % 32; /* Green. */ + *pos++ = y - y % 32; /* Blue. */ + } + } + + gtk_main (); + return 0; +} + + +gboolean +on_darea_expose (GtkWidget *widget, + GdkEventExpose *event, + gpointer user_data) +{ + gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL], + 0, 0, IMAGE_WIDTH, IMAGE_HEIGHT, + GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3); +} + + + + + + +#GdkColor +The underlying Gdk mechanism for allocating +colors. + + + +Initializes GdkRgb statically. It may be called more than once with no +ill effects. It must, however, be called before any other GdkRgb +operations are performed. + + +The GdkRgb "context" is allocated statically. Thus, GdkRgb may be used +to drive only one visual in any given application. GdkRgb +automatically selects a best visual and sets its own colormap, if +necessary. gdk_rgb_get_visual() and gdk_rgb_get_cmap () retrieve +the chosen visual and colormap, respectively. - +Draws an RGB image in the drawable. This is the core GdkRgb +function, and likely the only one you will need to use other than the +initialization stuff. -@drawable: -@gc: -@x: -@y: -@width: -@height: -@dith: -@rgb_buf: -@rowstride: + +The @rowstride parameter allows for lines to be aligned more flexibly. +For example, lines may be allocated to begin on 32-bit boundaries, +even if the width of the rectangle is odd. Rowstride is also useful +when drawing a subrectangle of a larger image in memory. Finally, to +replicate the same line a number of times, the trick of setting +@rowstride to 0 is allowed. + + + +In general, for 0 <= i < @width and 0 <= j < height, +the pixel (x + i, y + j) is colored with red value @rgb_buf[@j * +@rowstride + @i * 3], green value @rgb_buf[@j * @rowstride + @i * 3 + +1], and blue value @rgb_buf[@j * @rowstride + @i * 3 + 2]. + + +@drawable: The #GdkDrawable to draw in (usually a #GdkWindow). +@gc: The graphics context (all Gdk drawing operations require one; its +contents are ignored). +@x: The x coordinate of the top-left corner in the drawable. +@y: The y coordinate of the top-left corner in the drawable. +@width: The width of the rectangle to be drawn. +@height: The height of the rectangle to be drawn. +@dith: A #GdkRgbDither value, selecting the desired dither mode. +@rgb_buf: The pixel data, represented as packed 24-bit data. +@rowstride: The number of bytes from the start of one row in @rgb_buf to the +start of the next. - +Draws an RGB image in the drawable, with an adjustment for dither alignment. -@drawable: -@gc: -@x: -@y: -@width: -@height: -@dith: -@rgb_buf: -@rowstride: -@xdith: -@ydith: + +This function is useful when drawing dithered images into a window +that may be scrolled. Pixel (x, y) will be drawn dithered as if its +actual location is (x + @xdith, y + @ydith). Thus, if you draw an +image into a window using zero dither alignment, then scroll up one +pixel, subsequent draws to the window should have @ydith = 1. + + + +Setting the dither alignment correctly allows updating of small parts +of the screen while avoiding visible "seams" between the different +dither textures. + + +@drawable: The #GdkDrawable to draw in (usually a #GdkWindow). +@gc: The graphics context. +@x: The x coordinate of the top-left corner in the drawable. +@y: The y coordinate of the top-left corner in the drawable. +@width: The width of the rectangle to be drawn. +@height: The height of the rectangle to be drawn. +@dith: A #GdkRgbDither value, selecting the desired dither mode. +@rgb_buf: The pixel data, represented as packed 24-bit data. +@rowstride: The number of bytes from the start of one row in @rgb_buf to the +start of the next. +@xdith: An x offset for dither alignment. +@ydith: A y offset for dither alignment. - +Draws an indexed image in the drawable, using a #GdkRgbCmap to assign +actual colors to the color indices. -@drawable: -@gc: -@x: -@y: -@width: -@height: -@dith: -@buf: -@rowstride: -@cmap: +@drawable: The #GdkDrawable to draw in (usually a #GdkWindow). +@gc: The graphics context. +@x: The x coordinate of the top-left corner in the drawable. +@y: The y coordinate of the top-left corner in the drawable. +@width: The width of the rectangle to be drawn. +@height: The height of the rectangle to be drawn. +@dith: A #GdkRgbDither value, selecting the desired dither mode. +@buf: The pixel data, represented as 8-bit color indices. +@rowstride: The number of bytes from the start of one row in @buf to the +start of the next. +@cmap: The #GdkRgbCmap used to assign colors to the color indices. +Draws a grayscale image in the drawable. -@drawable: -@gc: -@x: -@y: -@width: -@height: -@dith: -@buf: -@rowstride: +@drawable: The #GdkDrawable to draw in (usually a #GdkWindow). +@gc: The graphics context. +@x: The x coordinate of the top-left corner in the drawable. +@y: The y coordinate of the top-left corner in the drawable. +@width: The width of the rectangle to be drawn. +@height: The height of the rectangle to be drawn. +@dith: A #GdkRgbDither value, selecting the desired dither mode. +@buf: The pixel data, represented as 8-bit gray values. +@rowstride: The number of bytes from the start of one row in @buf to the +start of the next. - +Draws a padded RGB image in the drawable. The image is stored as one +pixel per 32-bit word. It is laid out as a red byte, a green byte, a +blue byte, and a padding byte. -@drawable: -@gc: -@x: -@y: -@width: -@height: -@dith: -@buf: -@rowstride: + +It's unlikely that this function will give significant performance +gains in practice. In my experience, the performance gain from having +pixels aligned to 32-bit boundaries is cancelled out by the increased +memory bandwidth. + + +@drawable: The #GdkDrawable to draw in (usually a #GdkWindow). +@gc: The graphics context. +@x: The x coordinate of the top-left corner in the drawable. +@y: The y coordinate of the top-left corner in the drawable. +@width: The width of the rectangle to be drawn. +@height: The height of the rectangle to be drawn. +@dith: A #GdkRgbDither value, selecting the desired dither mode. +@buf: The pixel data, represented as padded 32-bit data. +@rowstride: The number of bytes from the start of one row in @buf to the +start of the next. @@ -125,6 +313,36 @@ GdkRGB +Selects whether or not GdkRgb applies dithering +to the image on display. There are three values: + + + + + + +%GDK_RGB_DITHER_NONE: Never use dithering. + + + + + +%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below) +only. + + + + + +%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below. + + + + + + +Since GdkRgb currently only handles images with 8 bits per component, +dithering on 24 bit per pixel displays is a moot point. @GDK_RGB_DITHER_NONE: @@ -133,25 +351,29 @@ GdkRGB - +Creates a new #GdkRgbCmap structure. The cmap maps color indexes to +RGB colors. If @n_colors is less than 256, then images containing +color values greater than or equal to @n_colors will produce undefined +results, including possibly segfaults. -@colors: -@n_colors: -@Returns: +@colors: The colors, represented as 0xRRGGBB integer values. +@n_colors: The number of colors in the cmap. +@Returns: The newly created #GdkRgbCmap - +Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new(). -@cmap: +@cmap: The #GdkRgbCmap to free. - +A private data structure which maps color indices to actual RGB +colors. This is used only for gdk_draw_indexed_image(). @colors: @@ -159,29 +381,33 @@ GdkRGB - +Sets the foreground color in @gc to the specified color (or the +closest approximation, in the case of limited visuals). -@gc: -@rgb: +@gc: The #GdkGC to modify. +@rgb: The color, represented as a 0xRRGGBB integer value. - +Sets the background color in @gc to the specified color (or the +closest approximation, in the case of limited visuals). -@gc: -@rgb: +@gc: The #GdkGC to modify. +@rgb: The color, represented as a 0xRRGGBB integer value. - +Finds the X pixel closest in color to the @rgb color specified. This +value may be used to set the pixel field of +a #GdkColor struct. -@rgb: -@Returns: +@rgb: The color, represented as a 0xRRGGBB integer value. +@Returns: The X pixel value. @@ -195,26 +421,38 @@ GdkRGB - +If @install is TRUE, directs GdkRgb to always install a new "private" +colormap rather than trying to find a best fit with the colors already +allocated. Ordinarily, GdkRgb will install a colormap only if a +sufficient cube cannot be allocated. -@install: + +A private colormap has more colors, leading to better quality display, +but also leads to the dreaded "colormap flashing" effect. + + +@install: TRUE to set install mode. - +Sets the minimum number of colors for the color cube. Generally, +GdkRgb tries to allocate the largest color cube it can. If it can't +allocate a color cube at least as large as @min_colors, it installs a +private colormap. -@min_colors: +@min_colors: The minimum number of colors accepted. - +Gets the visual chosen by GdkRgb. This visual and the corresponding +colormap should be used when creating windows that will be drawn in by GdkRgb. -@Returns: +@Returns: The #GdkVisual chosen by GdkRgb. @@ -227,24 +465,29 @@ GdkRGB - +Gets the colormap set by GdkRgb. This colormap and the corresponding +visual should be used when creating windows that will be drawn in by GdkRgb. +@Returns: The #GdkColormap set by GdkRgb. - +Determine whether the visual is ditherable. This function may be +useful for presenting a user interface choice to the user about which +dither mode is desired; if the display is not ditherable, it may make +sense to gray out or hide the corresponding UI widget. -@Returns: +@Returns: TRUE if the visual is ditherable. - +Sets the "verbose" flag. This is generally only useful for debugging. -@verbose: +@verbose: TRUE if verbose messages are desired. diff --git a/docs/reference/gdk/tmpl/windows.sgml b/docs/reference/gdk/tmpl/windows.sgml index cc811058b6..1e6c7b0c26 100644 --- a/docs/reference/gdk/tmpl/windows.sgml +++ b/docs/reference/gdk/tmpl/windows.sgml @@ -871,6 +871,16 @@ Windows @decorations: + + + + + +@window: The window to get the decorations from +@decorations: The window decorations will be written here +@Returns: TRUE if the window has decorations set, FALSE otherwise. + + diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index d20fe80f24..8e73da65a2 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -6,12 +6,22 @@ DOC_MODULE=gtk # The top-level SGML file. DOC_MAIN_SGML_FILE=gtk-docs.sgml -# The directory containing the source code -DOC_SOURCE_DIR=$(top_srcdir)/gtk +# The directory containing the source code. Relative to $(srcdir) +DOC_SOURCE_DIR=../../../gtk + +# Extra options to supply to gtkdoc-scan +SCAN_OPTIONS=--deprecated-guards="GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED" + +# Extra options to supply to gtkdoc-mkdb +MKDB_OPTIONS= # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +# Used for dependencies +HFILE_GLOB=$(top_srcdir)/gtk/*.h +CFILE_GLOB=$(top_srcdir)/gtk/*.c + # Header files to ignore when scanning IGNORE_HFILES= \ fnmatch.h \ @@ -37,6 +47,22 @@ IGNORE_HFILES= \ gtktexttypes.h \ gtktypebuiltins.h +# Images to copy into HTML directory +HTML_IMAGES = + +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE) +content_files = \ + compiling.sgml \ + framebuffer.sgml \ + objects_grouped.sgml \ + text_widget.sgml \ + tree_widget.sgml + +# Other files to distribute +extra_files = + +# CFLAGS and LDFLAGS for compiling scan program. Only needed +# if $(DOC_MODULE).types is non-empty. GTKDOC_CFLAGS = @STRIP_BEGIN@ \ @CFLAGS@ \ -I$(top_srcdir) \ @@ -66,10 +92,6 @@ GTKDOC_LIBS = @STRIP_BEGIN@ \ GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC) GTKDOC_LD=$(LIBTOOL) --mode=link $(CC) -content_files = \ - objects_grouped.sgml \ - text_widget.sgml \ - tree_widget.sgml #################################### # Everything below here is generic # @@ -78,48 +100,76 @@ content_files = \ TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) EXTRA_DIST = \ - $(DOC_MODULE).types \ - $(DOC_MAIN_SGML_FILE) \ $(content_files) \ + $(extra_files) \ + $(HTML_IMAGES) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE).types \ $(DOC_MODULE)-sections.txt \ $(DOC_MODULE)-overrides.txt +DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp + if ENABLE_GTK_DOC -all-local: html/index.html +all-local: html-build.stamp -$(DOC_MODULE)-decl.txt: - $(MAKE) scan +SCANOBJ_FILES = \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).signal -$(tmpl_sources): $(DOC_MODULE)-decl.txt $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt - $(MAKE) templates +scan-build.stamp: $(HFILE_GLOB) + @echo '*** Scanning header files ***' + cd $(srcdir) && ( \ + if grep -l '^.+$$' $(DOC_MODULE).types > /dev/null ; then \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) ; \ + else \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ + fi ) + cd $(srcdir) && \ + gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES) + touch scan-build.stamp -sgml/$(DOC_MODULE)-doc.bottom: $(tmpl_sources) $(DOC_MODULE)-decl.txt - $(MAKE) sgml +check_scan: + $(MAKE) scan-build.stamp -html/index.html: sgml/$(DOC_MODULE)-doc.bottom $(DOC_MAIN_SGML_FILE) $(content_files) - $(MAKE) html -endif +$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): check_scan -scan: - (cd $(srcdir) \ - && CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj --module=$(DOC_MODULE) \ - && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --deprecated-guards="GTK_ENABLE_BROKEN|GTK_DISABLE_DEPRECATED" --ignore-headers="$(IGNORE_HFILES)" $(EXTRA_HFILES)) - -templates: +tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt + @echo '*** Rebuilding template files ***' cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) + touch tmpl-build.stamp -sgml: - cd $(srcdir) \ - && gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) +check_templates: + $(MAKE) tmpl-build.stamp -html: +tmpl.stamp: check_templates + +sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) + @echo '*** Building SGML ***' + cd $(srcdir) && \ + gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS) + touch sgml-build.stamp + +check_sgml: + $(MAKE) sgml-build.stamp + +sgml.stamp: check_sgml + +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) + @echo '*** Building HTML ***' test -d $(srcdir)/html || mkdir $(srcdir)/html - -cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html ) @echo '-- Fixing Crossreferences' cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) + touch html-build.stamp +endif clean-local: - rm -f *~ *.bak *.signals *-unused.txt + rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS) $(srcdir)/sgml.stamp maintainer-clean-local: clean cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt @@ -145,17 +195,21 @@ if ENABLE_GTK_DOC dist-check-gtkdoc: else dist-check-gtkdoc: - @echo "*** gtk-doc must be installed and enabled in order to make dist + @echo "*** gtk-doc must be installed and enabled in order to make dist" @false endif -dist-hook: dist-check-gtkdoc - mkdir $(distdir)/html - mkdir $(distdir)/sgml +dist-hook: dist-check-gtkdoc dist-hook-local mkdir $(distdir)/tmpl - -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(srcdir)/html/index.sgml $(distdir)/html + mkdir $(distdir)/sgml + mkdir $(distdir)/html -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl -cp $(srcdir)/sgml/*.sgml $(distdir)/sgml -cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml + -cp $(srcdir)/html/index.sgml $(distdir)/html + -cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html + for i in $(HTML_IMAGES) ; do \ + cp $(srcdir)/$$i $(distdir)/html ; \ + done -.PHONY : html sgml templates scan +.PHONY : check_sgml check_templates check_scan dist-hook-local diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml index 7f37ff2cab..88a292bb43 100644 --- a/docs/reference/gtk/tmpl/gtk-unused.sgml +++ b/docs/reference/gtk/tmpl/gtk-unused.sgml @@ -1,52 +1,547 @@ - -Debugging - - - + -An action signal. Causes the characters in the current -selection to be copied to the clipboard and then deleted from -the widget. + + + + + + + + + + + + + + + +Keyboard Accelerators + + + + +All the functions in here are marked a Non-public. +We describe it anyway because it is occasionally useful +to understand how the work is done. + + +Arguments are a way of describing a named parameter to a function. +They have two important roles within gtk+: + + + +they describe object properties. +This means that they present an interface to get and set a named-type +for any type of object in a consistent way. +(All the relevant functions to do this start with gtk_object_set +or gtk_object_get). + + + + +they describe signal arguments. +This is a lot less often needed but still useful. +Usually if you are just emitting or creating a particular signal +it is more convenient to just use gtk_signal_emit() or gtk_signal_new(). +However if you are writing a function to emit or create an arbitrary +signal, you must use gtk_signal_emitv() or gtk_signal_newv(). + + + + + + + + +#GtkObject. + + + + +Utility function to manipulate lists of named, typed arguments. + + + +Implementation of Object Properties + + + + + + + + + + + + + + + + + + + +Bindings + + + + + + + + + + + + + + + + + + + +GtkCellRenderer + + + + + + + + + + + + + + + + + + + +GtkCellRendererPixbuf + + + + + + + + + + + + + + + + + + + +GtkCellRendererText + + + + + + + + + + + + + + + + + + + +GtkCellRendererTextPixbuf + + + + + + + + + + + + + + + + + + + +GtkCellRendererToggle + + + + + The #GtkClipboard object represents a clipboard of data shared + between different processes or between different widgets in + the same process. Each clipboard is identified by a name encoded as a + #GdkAtom. (Conversion to and from strings can be done with + gdk_atom_intern() and gdk_atom_name().) The default clipboard + corresponds to the CLIPBOARD atom; another commonly used clipboard + is the PRIMARY clipboard, which, in X, traditionally contains + the currently selected text. + + + To support having a number of different formats on the clipboard + at the same time, the clipboard mechanism allows providing + callbacks instead of the actual data. When you set the contents + of the clipboard, you can either supply the data directly (via + functions like gtk_clipboard_set_text()), or you can supply a + callback to be called at a later time when the data is needed (via + gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner().) + Providing a callback also avoids having to make copies of the data + when it is not needed. + + + gtk_clipboard_set_with_data() and gtk_clipboard_set_with_owner() + are quite similar; the choice between the two depends mostly on + which is more convenient in a particular situation. + The former is most useful when you want to have a blob of data + with callbacks to convert it into the various data types that you + advertise. When the @clear_func you provided is called, you + simply free the data blob. The latter is more useful when the + contents of clipboard reflect the internal state of a @GObject + (As an example, for the PRIMARY clipboard, when an entry widget + provides the clipboard's contents the contents are simply the + text within the selected region.) If the contents change, the + entry widget can call gtk_clipboard_set_with_owner() to update + the timestamp for clipboard ownership, without having to worry + about @clear_func being called. + + + Requesting the data from the clipboard is essentially + asynchronous. If the contents of the clipboard are provided within + the same process, then a direct function call will be made to + retrieve the data, but if they are provided by another process, + then the data needs to be retrieved from the other process, which + may take some time. To avoid blocking the user interface, the call + to request the selection, gtk_clipboard_request_contents() takes a + callback that will be called when the contents are received (or + when the request fails.) If you don't want to deal with providing + a separate callback, you can also use gtk_clipboard_wait_for_contents(). + What this does is run the Glib main loop recursively waiting for + the contents. This can simplify the code flow, but you still have + to be aware that other callbacks in your program can be called + while this recursive mainloop is running. + + + Along with the functions to get the clipboard contents as an + arbitrary data chunk, there are also functions to retrieve + it as text, gtk_clipboard_request_text() and + gtk_clipboard_wait_for_text(). These functions take care of + determining which formats are advertised by the clipboard + provider, asking for the clipboard in the best available format + and converting the results into the UTF-8 encoding. (The standard + form for representing strings in GTK+.) + + + + + + + + +#GtkSelection +@GtkClipboard provides a high-level wrapper around the + lower level routines that deal with X selections. It is + also possibly to directly manipulate the X selections, + though it is seldom necessary to do so. + + + + + + + +Storing data on Clipboards. + + + +Clipboards + + + + + + + + + + + -@editable: the object which received the signal. - + +Debugging + + + + +GTK+ has a rich set of functions for doing inter-process +communication via the drag-and-drop metaphore. GTK+ +can do drag and drop (DND) via multiple protocols. +The currently supported protocols are the Xdnd and +Motif protocols. + +As well as the functions listed here, applications +may need to use some facilities provided for +Selections. +Also, the Drag and Drop API makes use of signals +in the #GtkWidget class. + + + + - + +Functions for controlling drag and drop handling. + + + +Drag and Drop + + + -@simple: -@path: -@iter: - + -@type: -@nargs: -@args: -@Returns: - + + + + + +gtkenums.sgml + + + -A macro to check whether a child widget of the CList -has the focus. + -@clist: The #GtkCList widget to check. + + + + + + + + +Public enumerated types used throughout GTK+. + + + +Standard Enumerations + + + + +This section describes the variables and functions available to test the +version of the GTK+ library in use. +FIXME: probably merge with other general stuff. + + + + + + + + + + +variables and functions to check the GTK+ version. + + + +Version Information + + + + +These functions provide access to a shared pool of #GdkGC objects. +When a new #GdkGC is needed, gtk_gc_get() is called with the required depth, +colormap and #GdkGCValues. If a #GdkGC with the required properties already +exists then that is returned. If not, a new #GdkGC is created. +When the #GdkGC is no longer needed, gtk_gc_release() is called. + + + + + + + + + + +provides access to a shared pool of #GdkGC objects. + + + +Graphics Contexts + + + + + An icon factory manages a collection of #GtkIconSet; a #GtkIconSet manages a + set of variants of a particular icon (i.e. a #GtkIconSet contains variants for + different sizes and widget states). Icons in an icon factory are named by a + stock ID, which is a simple string identifying the icon. Each #GtkStyle has a + list of #GtkIconFactory derived from the current theme; those icon factories + are consulted first when searching for an icon. If the theme doesn't set a + particular icon, GTK+ looks for the icon in a list of default icon factories, + maintained by gtk_icon_factory_add_default() and + gtk_icon_factory_remove_default(). Applications with icons should add a default + icon factory with their icons, which will allow themes to override the icons + for the application. + + + +To display an icon, always use gtk_style_lookup_icon_set() on the widget that +will display the icon, or the convenience function +gtk_widget_render_icon(). These functions take the theme into account when +looking up the icon to use for a given stock ID. + + + + + + + + + + + +Manipulating stock icons + + + +Themeable Stock Images + + + + + + + + + + + + + + + + + + + +GtkIMContextSimple + + + + + + + + + + + + + + + + + + + +GtkListStore + + + + +GTK uses an event oriented programming model. While conventional C programs +have control over the program flow all the time this does not apply to +applications written using GTK. Instead you set up some objects and +register some functions (callbacks) to be called whenever +some event occurs and give control to the GTK mainloop (e.g. by calling +gtk_main). + + + + Typical <function>main</function> function for a GTK application + +int +main (int argc, char **argv) +{ + /* Initialize i18n support */ + gtk_set_locale (); + + /* Initialize the widget set */ + gtk_init (&argc, &argv); + + /* Create the main window */ + mainwin = gtk_window_new (GTK_WINDOW_TOPLEVEL); + + /* Set up our GUI elements */ + ... + + /* Show the application window */ + gtk_widget_showall (mainwin); + + /* Let the user interact with our application */ + gtk_main (); + + /* The user lost interest */ + gtk_exit (0); +} + + + + + + + + + + +Mainloop and event handling + + + +General + @@ -114,135 +609,33 @@ void marshal_INT__POINTER_POINTER_INT_INT(GtkObject* object, - - - - - + -Add an array of signals to a #GtkObjectClass. -Usually this is called when registering a new type of object. - + -@klass: the object class to append signals to. -@signals: the signals to append. -@nsignals: the number of signals being appended. - - - + +#GtkSignal +The signal handling functions (of which marshallers are +really an implementation detail). + + - + +Functions to adapt C structures to native calling convention. + + + +Signal Marshallers + + + -@wid: -@flag: - - - - - - -@obj: - - - - - - -@Returns: - - - - - - - - - - - - -@engine: -@Returns: - - - - - - -@selection: -@type: - - - - - - - - - - - - -@n_columns: -@Varargs: -@Returns: - - - - - - -@textview: the object which received the signal. -@arg1: - - - - - - -@v: -@visual: - - - - - - -@window: -@focus: - - - - - - - - - - - - -@widget: -@arg: - - - - - - - - - -A boolean indicating whether the widget is editable by -the user. - - @@ -250,271 +643,1339 @@ the user. - - -Sets one of the two font filters, to limit the fonts shown. - - -@fontsel: a #GtkFontSelection. -@filter_type: which of the two font filters to set, either -#GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter -can be changed by the user, but the base filter is permanent. -@font_type: the types of font to be shown. This is a bitwise combination of -#GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP, -or #GTK_FONT_ALL to show all three font types. -@foundries: a NULL-terminated array of strings containing foundry names which -will be shown, or NULL to show all foundries. -@weights: a NULL-terminated array of strings containing weight names which -will be shown, or NULL to show all weights. -@slants: a NULL-terminated array of strings containing slant names which -will be shown, or NULL to show all slants. -@setwidths: a NULL-terminated array of strings containing setwidth names which -will be shown, or NULL to show all setwidths. -@spacings: a NULL-terminated array of strings containing spacings which -will be shown, or NULL to show all spacings. -@charsets: a NULL-terminated array of strings containing charset names which -will be shown, or NULL to show all charsets. - - - - - - -@container: - - -Signal Marshallers + - + + +Menu Factory + + + - + -A structure used to return values from @gtk_type_query. + + + + + + + + + +Private Information + + + + +GTK+ provides resource file mechanism for configuring +various aspects of the operation of a GTK+ program +at runtime. + + +Default files + +An application can cause GTK+ to parse a specific RC +file by calling gtk_rc_parse(). In addition to this, +certain files will be read at the end of gtk_init(). +Unless modified, the files looked for will be .gtkrc +in the users home directory, and +$localstatedir/gtk/gtkrc +($localstatedir defaults to +/usr/local/etc). + + +The set of these default files +can be retrieved with gtk_rc_get_default_files() +and modified with gtk_rc_add_default_file() and +gtk_rc_set_default_files(). + + +For each default file, in addition to the file itself, +GTK+ will look for a locale-specific file that will +be parsed in addition to the main file. For instance, +if LANG is set to ja_JP.ujis, +when loading the default file ~/.gtkrc +then GTK+ looks for ~/.gtkrc.ja_JP.ujis, +~/.gtkrc.ja_JP, and +~/.gtkrc.ja, and parses the +first one it finds. + + + +Pathnames and patterns + +A resource file defines a number of styles and key bindings and +attaches them to particular widgets. The attachment is done +by the widget, widget_class, +and class declarations. As an example +of such a statement: + +widget "mywindow.*.GtkEntry" style "my-entry-class" + +attaches the style "my-entry-class" +to all widgets whose widget class +matches the pattern +"mywindow.*.GtkEntry". + + +The patterns here are given in the standard shell glob +syntax. The "?" wildcard matches +any character, while "*" matches +zero or more of any character. The three types of +matching are against the widget path, the +class path and the class +heirarchy. Both the widget and the class paths consists of a +"." separated list of all the +parents of the widget and the widget itself from +outermost to innermost. The difference is that in +the widget path, the name assigned by +gtk_widget_set_name() is used +if present, otherwise the class name of the widget, while +for the widget path, the class name is always used. + + +So, if you have a GtkEntry named +"myentry", inside of a of a window +named "mywindow", then the +widget path is: + +"mwindow.GtkHBox.myentry" + +while the class path is: + +"GtkWindow.GtkHBox.GtkEntry" + + + +Matching against class is a little different. The pattern +match is done against all class names in the widgets +class heirarchy (not the layout heirarchy) in sequence, so the +pattern: + +class "GtkButton" style "my-style" + +will match not just GtkButton widgets, +but also GtkToggleButton and +GtkCheckButton widgets, since +those classes derive from GtkButton. + + + +Toplevel declarations + +An RC file is a text file which is composed of a sequence +of declarations. '#' characters delimit comments and +the portion of a line after a '#' is ignored when parsing +an RC file. + + + +The possible toplevel declarations are: + + + + binding name + { ... } + + Declare a binding set + + + + class pattern + [ style | binding [ : priority ]] + name + + Specify a style or binding set for a particular + branch of the inheritance heirarchy. + + + + include filename + + Parse another file at this point + + + + module_path path> + + Sets a path (a list of directories separated + by colons) that will be searched for theme engines referenced in + RC files. + + + + pixmap_path path> + + Sets a path (a list of directories separated + by colons) that will be searched for pixmaps referenced in + RC files. + + + + style name [ = + parent ] { ... } + + Declare a style + + + + widget pattern + [ style | binding [ : priority ]] + name + + Specify a style or binding set for a particular + group of widgets by matching on the widget pathname. + + + + widget_class pattern + [ style | binding [ : priority ]] + name + + Specify a style or binding set for a particular + group of widgets by matching on the class pathname. + + + + + + +Styles + +A RC style is specified by a style +declaration in a RC file, and then bound to widgets +with a widget, widget_class, +or class declaration. All styles +applying to a particular widget are composited together +with widget declarations overriding +widget_class declarations which, in +turn, override widget declarations. +Within each type of declaration, later declarations override +earlier ones. + + + +Within a style declaration, the possible +elements are: + + + + bg[state] = + color + + + Set color used for the background of most widgets. + + + + + fg[state] = + color + + + Set color used for the foreground of most widgets. + + + + + base[state] = + color + + + Set color used for the background of widgets displaying + editable text. This color is used for the background + of, among others, #GtkText, #GtkEntry, #GtkList, and #GtkClist. + + + + + text[state] = + color + + + Set color used for foreground of widgets using + base for the background color. + + + + + bg_text[state] = + color + + + Set a background pixmap to be used in place of + the bg color (or for #GtkText, + in place of the base color. + + + + + font = font + + + Set the font for a widget. + + + + + fontset = font + + + Set the fontset for a widget. Overrides any + font declarations. + + + + + stock["stock-id"] = { icon source specifications } + + + Defines the icon for a stock item. + + + + + + +The colors and background pixmaps are specified as a function of the +state of the widget. The states are: + + + + NORMAL + + + A color used for a widget in its normal state + + + + + ACTIVE + + + A variant of the NORMAL color used when the + widget is in the %GTK_STATE_ACTIVE state, and also for + the trough of a ScrollBar, tabs of a NoteBook + other than the current tab and similar areas. + Frequently, this should be a darker variant + of the NORMAL color. + + + + + PRELIGHT + + + A color used for widgets in the %GTK_STATE_PRELIGHT state. This + state is the used for Buttons and MenuItems + that have the mouse cursor over them, and for + their children. + + + + + SELECTED + + + A color used to highlight data selected by the user. + for instance, the selected ListItems in a List widget, and the + selection in an Editable widget. + + + + + INSENSITIVE + + + A color used for the background of widgets that have + been set insensitive with gtk_widget_set_sensitive() + + + + + + + +Colors can be specified as a string "&hash;rrrrggggbbbb", +"&hash;rrrgggbbb", "&hash;rrggbb", +or "&hash;rgb", where r +g, and b are +hex digits, or they can be specified as a triplet of floats +{ r, g, +b}. + + + +In a stock definition, icon sources are specified as a +4-tuple of image filename, text direction, widget state, and size, in that +order. Each icon source specifies an image filename to use with a given +direction, state, and size. The * character can be used as a +wildcard, and if direction/state/size are omitted they default to +*. So for example, the following specifies different icons to +use for left-to-right and right-to-left languages: + +stock["my-stock-item"] = +{ + { "itemltr.png", LTR, *, * }, + { "itemrtl.png", RTL, *, * } +} + +This could be abbreviated as follows: + +stock["my-stock-item"] = +{ + { "itemltr.png", LTR }, + { "itemrtl.png", RTL } +} + + + + +You can specify custom icons for specific sizes, as follows: + +stock["my-stock-item"] = +{ + { "itemmenusize.png", *, *, "gtk-menu" }, + { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" } + { "itemgeneric.png" } /* implicit *, *, * as a fallback */ +} + +The sizes that come with GTK+ itself are "gtk-menu", +"gtk-small-toolbar", "gtk-large-toolbar", +"gtk-button", "gtk-dialog". Applications +can define other sizes. + + + +It's also possible to use custom icons for a given state, for example: +You can specify custom icons for specific sizes, as follows: + +stock["my-stock-item"] = +{ + { "itemprelight.png", *, PRELIGHT }, + { "iteminsensitive.png", *, INSENSITIVE }, + { "itemgeneric.png" } /* implicit *, *, * as a fallback */ +} + + + + +When selecting an icon source to use, GTK+ will consider text direction most +important, state second, and size third. It will select the best match based on +those criteria. If an attribute matches exactly (e.g. you specified +PRELIGHT or specified the size), GTK+ won't modify the image; +if the attribute matches with a wildcard, GTK+ will scale or modify the image to +match the state and size the user requested. + + + + +Key bindings + +Key bindings allow the user to specify actions to be +taken on particular key presses. The form of a binding +set declaration is: + + + +binding name { + bind key { + signalname (param, ...) + ... + } + ... +} + + + +key is a string consisting of a +series of modifiers followed by the name of a key. The +modifiers can be: + +<alt> +<control> +<mod1> +<mod2> +<mod3> +<mod4> +<mod5> +<release> +<shft> +<shift> + +<shft> is an alias for +<shift> and +<alt> is an alias for +<mod1>. + + + +The action that is bound to the key is a sequence +of signal names (strings) followed by parameters for +each signal. The signals must be action signals. +(See gtk_signal_new()). Each parameter can be +a float, integer, string, or unquoted string +representing an enumeration value. The types of +the parameters specified must match the types of the +parameters of the signal. + + + +Binding sets are connected to widgets in the +same manner as styles, with one addition. +A priority can be specified for each pattern, +and within each type of pattern, binding sets +override other binding sets first by priority, +and only then by order of specification. (Later +overrides earlier). The priorities that can +be specified are (highest to lowest): + +HIGHEST +RC +APPLICATION +GTK +LOWEST + +RC is the default for bindings +read from an RC file, APPLICATION +should be used for bindings an application sets +up, and GTK is used for bindings +that GTK+ creates internally. + + + + + + + + + + + +Routines for handling resource files + + + +Resource Files + + + + + +The selection mechanism provides the basis for different types +of IPC between processes. In particular, drag and drop and +#GtkClipboard work via selections. You will very seldom or +never need to use most of the functions in this section directly; +#GtkClipboard provides a nicer interface to the same functionality. + + +Some of the datatypes defined this section are used in +the #GtkClipboard and drag-and-drop API's as well. The +#GtkTargetEntry structure and #GtkTargetList objects represent +lists of data types that are supported when sending or +receiving data. The #GtkSelectionData object is used to +store a chunk of data along with the data type and other +associated information. + + + + + + + + +#GtkWidget +Much of the operation of selections happens via + signals for #GtkWidget. In particular, if you are + using the functions in this section, you may need + to pay attention to ::selection_get, + ::selection_received, and :selection_clear_event + signals. + + + + + + + + +Functions for handling inter-process communication via selections. + + + +Selections + + + + +What are signals? + +Signals are a way to get notification when something happens +and to customize object behavior according to the +user's needs. +Every signal is uniquely identified by a name, +"class_name::signal_name", where signal_name might be something like +"clicked" and class_name might be "GtkButton". Note that some other class +may also define a "clicked" callback, so long as it doesn't derive from +#GtkButton. + + +When they are created, they are also assigned a unique positive integer, +the signal id (1 is the first signal id- 0 is used to flag an error). +Each is also tied to an array of types that describes +the prototype of the function pointer(s) (handlers) you may +connect to the signal. Finally, every signal has +a default handler that is given by a function pointer +in its class structure: it is run by default whenever the +signal is emitted. (It is possible that a signal will +be emitted and a user-defined handler will prevent the default handler +from being run.) + + +Signals are used by everyone, but they are only +created on a per class basis-- so you should call +call gtk_signal_new() unless you are writing +a new #GtkObject type. However, if you want to make a new signal +for an existing type, you may use gtk_object_class_user_signal_new() +to create a signal that doesn't correspond to a class's builtin +methods. + + + +How are signals used? + +There are two basic actions in the signal handling game. +If you want notification of an event, you must connect +a function pointer and a data pointer to that signal; the data pointer +will be passed as the last argument to the function (so long as you +are using the default marshalling functions). +You will receive a connection id, a unique positive integer +corresponding to that attachment. + + +Functions that want to notify the user of certain actions, +emit signals. + + + +Basic Terminology + + + +signal +A class method, e.g. GtkButton::clicked. +More precisely it is a unique class-branch/signal-name pair. +This means you may not define a signal handler for a class which +derives from GtkButton that is called clicked, +but it is okay to share signals names if they are separate in +the class tree. + + + + +default handler +The object's internal method which is invoked +when the signal is emitted. + + + + +user-defined handler +A function pointer and data connected +to a signal (for a particular object). +There are really two types: those which are connected +normally, and those which are connected by one +of the connect_after functions. The connect_after handlers +are always run after the default handler. +Many toolkits refer to these as callbacks. + + + + +emission +the whole process of emitting a signal, +including the invocation of all +the different handler types mentioned above. + + + + +signal id +The unique positive (nonzero) integer +used to identify a signal. It can be used instead of +a name to many functions for a slight performance +improvement. + + + + +connection id +The unique positive (nonzero) integer +used to identify the connection of a user-defined handler +to a signal. Notice that it is allowed to connect the +same function-pointer/user-data pair twice, so +there is no guarantee that a function-pointer/user-data +maps to a unique connection id. + + + + + + + +A brief note on how they work. + +The functions responsible for translating an array of #GtkArgs +to your C compiler's normal semantics are called Marshallers. +They are identified by +gtk_marshal_return_value__parameter_list() +for example a C function returning a gboolean and taking a gint +can be invoked by using gtk_marshal_BOOL__INT(). +Not all possibly combinations of return/params are available, +of course, so if you are writing a #GtkObject with parameters +you might have to write a marshaller. + + + + + + + + + +#GtkObject +The base class for things which emit signals. + + + + + + + +Object methods and callbacks. + + + +Signals + + + + + + + + + + + + + + + + + + + +Stock Items + + + + + + + + + + + + + + + + + + + +Styles + + + + + + + + + + + + + + + + + + + +Themes + + + + + + + + + + + + + + + + + + + +GtkModelSimple + + + + + + + + + + + + + + + + + + + +GtkTreeView + + + + +Gtk's type system is extensible. Because of that, types have to be +managed at runtime. + + + + + + + + + + +Handle run-time type creation. + + + +Types + + + + +A button box should be used to provide a consistent layout of buttons +throughout your application. There is one default layout and a default +spacing value that are persistant across all #VButtonBox widgets. + + +The layout/spacing can then be altered by the programmer, or if desired, by +the user to alter the 'feel' of a program to a small degree. + + +A #VButtonBox is created with gtk_vbutton_box_new(). Buttons are packed into +a button box the same way as any other box, using gtk_box_pack_start() or +gtk_box_pack_end(). + + +The default spacing between buttons can be set with +gtk_vbutton_box_set_spacing_default() and queried with +gtk_vbutton_box_get_spacing_default(). + + +The arrangement and layout of the buttons can be changed using +gtk_vbutton_box_set_layout_default() and queried with +gtk_vbutton_box_get_layout_default(). + + + + + + + +#GtkBox +Used to pack widgets into button boxes. + +#GtkButtonBox +Provides functions for controlling button boxes. + + +#GtkHButtonBox +Pack buttons horizontally. + + + + + + +a container for arranging buttons vertically. + + + +GtkVButtonBox + + + + +GtkVBox is a container that organizes child widgets into a single column. + + + +Use the #GtkBox packing interface to determine the arrangement, +spacing, height, and alignment of GtkVBox children. + + + +All children are allocated the same width. + + + + + + + + +#GtkHBox +a sister class that organizes widgets into a row. + + + + + + + +vertical container box + + + +GtkVBox + + + + + + + + + + + + + + + + + + + +GtkViewport + + + + +The VPaned widget is a container widget with two +children arranged vertically. The division between +the two panes is adjustable by the user by dragging +a handle. See #GtkPaned for details. + + + + + + + + + + +A container with two panes arranged vertically. + + + +GtkVPaned + + + + + NOTE this widget is considered too specialized/little-used for + GTK+, and will in the future be moved to some other package. If + your application needs this widget, feel free to use it, as the + widget does work and is useful in some applications; it's just not + of general interest. However, we are not accepting new features for + the widget, and it will eventually move out of the GTK+ + distribution. + + +The VRuler widget is a widget arranged vertically creating a ruler that is +utilized around other widgets such as a text widget. The ruler is used to show +the location of the mouse on the window and to show the size of the window in +specified units. The available units of measurement are GTK_PIXELS, GTK_INCHES +and GTK_CENTIMETERS. GTK_PIXELS is the default. +rulers. + + + + + + + + + + +A vertical ruler. + + + +GtkVRuler + + + + +The #GtkVScale widget is used to allow the user to select a value using +a vertical slider. +A #GtkAdjustment is used to set the initial value, the lower +and upper bounds, and the step and page increments. + + +The position to show the current value, and the number of decimal places +shown can be set using the parent #GtkScale class's functions. + + + + + + + + + + +a vertical slider widget for selecting a value from a range. + + + +GtkVScale + + + + +The VScrollbar widget is a widget arranged vertically creating a scroll bar. See +#GtkScrollbar for details on scrollbars. #GtkAdjustment pointers may be added to +handle the adjustment of the scrollbars or it may be left NULL in which case one +will be created you. See #GtkAdjustment for details. + + + + + + + + + + +A vertical scrollbar + + + +GtkVScrollbar + + + + +The #GtkVSeparator widget is a vertical separator, used to group the +widgets within a window. It displays a vertical line with a shadow to +make it appear sunken into the interface. + + + + + + + +#GtkHSeparator +a horizontal separator. + + + + + + +a vertical separator. + + + +GtkVSeparator + + + + + + + + + + + + + + + + + + + +GtkWidget + + + + + + + + + + + + + + + + + + + +GtkWindow + + + + +A macro to check whether a child widget of the CList +has the focus. + + +@clist: The #GtkCList widget to check. + + + + + + +@obj: + + + + + + + + + + @type: -@type_name: -@object_size: -@class_size: +@action: - + + +Test whether a GtkObject's arguments have been prepared. + + +@obj: the object to examine. + + + +Get the number of signals defined by this object. + + +@obj: the object to query. + + + +Get the array of signals defined for this object. + + +@obj: the object to fetch the signals from. + + -@v: +@wid: - + -@buffer: -@Returns: +@wid: +@flag: - + -@object: -@func: -@func_data: -@args: +@wid: +@flag: - + -A #GtkJustification for the text. This is only used when the tag is -applied to the first character in a paragraph. +A macro that returns a GList that contains the selection of the root tree of @obj. + + +@obj: A pointer to the #GtkTree. @obj will accept any pointer, but it the pointer does not point to a #GtkTree, the results are undefined. + + + +The first "flat" (no struct) enumerated type value. - + -This is currently a hack left in for a scheme wrapper library. -It may be removed. - - -Don't use it. +The last "flat" (no struct) enumerated type value. -@object: The object which emits the signal. -@data: The user data associated with the hook. -@nparams: The number of parameters to the function. -@args: The actual values of the arguments. -@arg_types: The types of the arguments. -@return_type: The type of the return value from the function -or #GTK_TYPE_NONE for no return value. - + -Add an emission hook for a type of signal, for any object. -(with control of what happens when the hook is -destroyed). +Hide the name of gtk_identifier_get_type -@signal_id: the type of signal add the hook for. -@hook_func: the function to invoke to handle the hook. -@data: the user data passed in to hook_func. -@destroy: a function to invoke when the hook is destroyed, -to clean up any allocation done just for this -signal handler. -@Returns: the id (that you may pass as a parameter -to gtk_signal_remove_emission_hook()). - + + +Combine a fundemantal type and a sequence number to create a gtk type. + + +@parent_t: +@seqno: + + + +No idea. + + + + + +Convert a gtk type into its sequence number + + +@type: + + + +The first structured enumerated type value. + + + + + +The last structured enumerated type value. + + + + + +Use to get the value of a GtkArg whose GtkType is GTK_TYPE_ARGS + + +@a: + + + +Use to get the value of a GtkArg whose GtkType is GTK_TYPE_CALLBACK + + +@a: + + + +Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_CALLBACK + + +@a: + + + +Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_FOREIGN + + +@a: + + -@buffer: -@override_location: -@time: -@interactive: -@default_editable: +@obj: - + -@object: -@func: -@func_data: -@args: +@obj: - + -@simple: -@path: -@iter: +@obj: - + -@tree_column: -@size: -@width: +@obj: - + -@textview: the object which received the signal. +@obj: - + -@text_view: -@iter: -@x: -@y: +@obj: - - -Gets an array of argument values from an object. - - -@object: the object to get arguments from. -@n_args: the number of arguments to query. -@args: the arguments to fill in. - - + - - - - - - -@buffer: -@iter: -@Returns: - - - - - - - -Get the type of GtkIdentifier. - - -@Returns: GtkType -- the enumerated type of something. - - - - - - -@name: -@Returns: - - - - - - -@parent: -@stamp: - - - - - - - - - - - - -@simple: -@path: -@iter: - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@engine: - - - - - - -@object: -@func: -@func_data: -@args: +@obj: @@ -525,50 +1986,58 @@ Get the type of GtkIdentifier. @GTK_CELL_RENDERER_PRELIT: @GTK_CELL_RENDERER_INSENSITIVE: - + -@object: -@func: -@func_data: -@args: +@GTK_DEBUG_OBJECTS: +@GTK_DEBUG_MISC: +@GTK_DEBUG_SIGNALS: +@GTK_DEBUG_DND: +@GTK_DEBUG_PLUGSOCKET: - + - - - -@mark: -@Returns: - - - - +Deprecated. - + -Determines if the user can edit the text in the editable -widget or not. This is meant to be overriden by -child classes and should not generally useful to -applications. +Indicates that the user has activated the widget +in some fashion. Generally, this will be done +with a keystroke. (The default binding for this +action is Return for #GtkEntry and +Control-Return for #GtkText.) @editable: the object which received the signal. -@is_editable: %TRUE if the user is allowed to edit the text - in the widget. - + - +Indicates that the user has changed the contents +of the widget. -@simple: -@path: -@iter: +@editable: the object which received the signal. + + + +An action signal. Causes the characters in the current selection to +be copied to the clipboard. + + +@editable: the object which received the signal. + + + +An action signal. Causes the characters in the current +selection to be copied to the clipboard and then deleted from +the widget. + + +@editable: the object which received the signal. @@ -587,12 +2056,33 @@ gtk_editable_delete_text() @start_pos: the starting position. @end_pos: the end position. - + - +This signal is emitted when text is inserted into +the widget by the user. The default handler for +this signal will normally be responsible for inserting +the text, so by connecting to this signal and then +stopping the signal with gtk_signal_emit_stop(), it +is possible to modify the inserted text, or prevent +it from being inserted entirely. -@ruler: the gtkruler +@editable: the object which received the signal. +@new_text: the new text to insert. +@new_text_length: the length of the new text. +@position: the position at which to insert the new text. + this is an in-out paramter. After the signal + emission is finished, it should point after + the newly inserted text. + + + +An action signal. Delete a single character. + + +@editable: the object which received the signal. +@direction: the direction in which to delete. Positive + indicates forward deletion, negative, backwards deletion. @@ -603,380 +2093,104 @@ An action signal. Delete a single line. @direction: the direction in which to delete. Positive indicates forward deletion, negative, backwards deletion. - + - +An action signal. Delete a single word. -@argc: -@argv: +@editable: the object which received the signal. +@direction: the direction in which to delete. Positive + indicates forward deletion, negative, backwards deletion. - + -Register a new set of enum @values and give them the name in -@type_name. +An action signal. Move the cursor position. -@type_name: must not be null. -@values: GtkEnumValue* -@Returns: +@editable: the object which received the signal. +@x: horizontal distance to move the cursor. +@y: vertical distance to move the cursor. - -Menu Factory - - - + - +An action signal. Move the cursor by pages. +@editable: the object which received the signal. +@x: Number of pages to move the cursor horizontally. +@y: Number of pages to move the cursor vertically. - + - +An action signal. Move the cursor to the given column. -@w: -@v: -@widget: -@visual: +@editable: the object which received the signal. +@column: the column to move to. (A negative value indicates + the last column) - + - +An action signal. Move the cursor to the given row. -@widget: -@nargs: -@args: +@editable: the object which received the signal. +@row: the row to move to. (A negative value indicates + the last row) - + - +An action signal. Move the cursor by words. +@editable: the object which received the signal. +@num_words: The number of words to move the +cursor. (Can be negative). - + -Convert a gtk type into its sequence number - - -@type: - - - - - - - - - - - - -@GTK_MENU_FACTORY_MENU: -@GTK_MENU_FACTORY_MENU_BAR: -@GTK_MENU_FACTORY_OPTION_MENU: - - - - - - - - - - - - - - - - - - -@obj: - - - - - - - - - - - - -@iter: -@Returns: - - - - - - - - - - -@textview: the object which received the signal. - - - - - - -@engine: - - - - - - - - - -Deprecated. - - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@tree_store: -@iter: -@var_args: - - - - - - -@buffer: -@time: -@interactive: -@default_editable: - - - -Indicates that the user has activated the widget -in some fashion. Generally, this will be done -with a keystroke. (The default binding for this -action is Return for #GtkEntry and -Control-Return for #GtkText.) +An action signal. Causes the contents of the clipboard to +be pasted into the editable widget at the current cursor +position. @editable: the object which received the signal. - + - - - -@GTK_TEXT_MOVEMENT_CHAR: -@GTK_TEXT_MOVEMENT_POSITIONS: -@GTK_TEXT_MOVEMENT_WORD: -@GTK_TEXT_MOVEMENT_WRAPPED_LINE: -@GTK_TEXT_MOVEMENT_LINE: -@GTK_TEXT_MOVEMENT_LINE_ENDS: -@GTK_TEXT_MOVEMENT_BUFFER_ENDS: - - - - - - -@object: -@func: -@func_data: -@args: - - - -Pixel width of the left margin of the text for lines after the first -line in a wrapped paragraph. - - - - - - - - - - - - - - -@style: -@window: -@state_type: -@shadow_type: -@area: -@widget: -@detail: -@x: -@y: -@width: -@height: - - - - - - -@obj: - - - -An action signal. Causes the characters in the current selection to -be copied to the clipboard. +Determines if the user can edit the text in the editable +widget or not. This is meant to be overriden by +child classes and should not generally useful to +applications. @editable: the object which received the signal. +@is_editable: %TRUE if the user is allowed to edit the text + in the widget. - + -Initializes a previously allocated #GtkCList widget for use. This should not -normally be used to create a #GtkCList widget. Use gtk_clist_new() instead. - - -@clist: A pointer to an uninitialized #GtkCList widget. -@columns: The number of columns the #GtkCList should have. -@titles: An array of strings that should be used as the titles i -of the columns. There should be enough strings in the array for -the number of columns specified. - - - - - - -@factory: -@entries: -@nentries: - - - - - - -@tree_view: -@path: -@column: -@row_align: -@col_align: - - - - - - -@buffer: -@iter: -@str: -@start: -@end: -@Returns: - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@object: -@func: -@func_data: -@args: - - - -Internal function used by #GtkHPaned and #GtkVPaned - - -@paned: -@allocation: -@child1_req: -@child2_req: - - - - +A boolean indicating whether the widget is editable by +the user. - + -Private: print debugging information while doing a gtk_object_ref() or -a gtk_object_unref(). - - -@object: object to reference or unreference. -@func: name of caller's function to print (used within macros). -@dummy: unused. -@line: line number (used within macros). -@do_ref: whether to reference or unreference. - - - -Use to get the value of a GtkArg whose GtkType is GTK_TYPE_CALLBACK - - -@a: - - - - +The position of the cursor. - + -Private: Gets an array of #GtkArgs from a va_list C structure. +A set of bit flags used to specify the filter being set +when calling gtk_font_selection_dialog_set_filter() or +gtk_font_selection_set_filter(). -@object_type: the type of object to collect arguments for. -@arg_list_p: pointer to be filled in with a list of parsed arguments. -@info_list_p: optional pointer for a returned list #GtkArgInfos. -@first_arg_name: name of first argument. -@var_args: value of first argument, followed by more key/value pairs, -terminated by NULL. -@Returns: an error message, or NULL on success. -It is the caller's responsibility to call g_free() in the event of error. +@GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user. +@GTK_FONT_FILTER_USER: the user filter, which can be changed from within the +'Filter' page of the #GtkFontSelection widget. @@ -990,71 +2204,118 @@ gtk_font_selection_set_filter(). @GTK_FONT_SCALABLE_BITMAP: scaled bitmap fonts. @GTK_FONT_ALL: a bitwise combination of all of the above. - - -The last structured enumerated type value. - - - - - -Get the number of signals defined by this object. - - -@obj: the object to query. - - - -Private function to get an argument and argument info from an object. - - -@object: the object whose argument should be retrieved. -@arg: the argument, for the name on input, the rest is filled on output. -@info: a #GtkArgInfo structure to optionally fill in. - - + + + + + +@object: +@tables: +@compose_buffer: +@tentative_match: +@tentative_match_len: + + + +Internal to #GtkLabel. + + + + + + + + +@widget: +@user_data: + + -@factory: -@subfactory: @path: +@accelerator: +@callback: +@callback_data: +@widget: - - -Return the pointer to the type's children's types. - - -@type: GtkType -@Returns: pointer to a GList - - - -An action signal. Move the cursor by pages. - - -@editable: the object which received the signal. -@x: Number of pages to move the cursor horizontally. -@y: Number of pages to move the cursor vertically. - - - -Register a new set of flags @values and give them the name in -@type_name. - - -@type_name: must not be null. -@values: GtkFlagValue* -@Returns: - - + -@textview: the object which received the signal. -@arg1: +@path: +@type: +@accel_group: +@widget: +@subfactories: + + + + + + +@GTK_MENU_FACTORY_MENU: +@GTK_MENU_FACTORY_MENU_BAR: +@GTK_MENU_FACTORY_OPTION_MENU: + + + + + + +@path: +@widget: + + + + + + +@parent: +@stamp: + + + +Setting this with a GtkType of GTK_TYPE_SIGNAL connects +the signal to the object, so that the user data and objects +and swapped when the signal handler is invoked. + + +This is useful for handlers that are primarily notifying +other objects and could just invoke an already existing function +if the parameters were swapped. +See gtk_signal_connect_object() for more details. + + + + + +Setting this with a GtkType of GTK_TYPE_SIGNAL connects +the signal to the object, so that the user data and objects +and swapped when the signal handler is invoked, +and so that the handler is invoked after all others. + + +See gtk_signal_connect_object_after() for more details. + + + + + +Setting this with a GtkType of GTK_TYPE_SIGNAL connects +the signal to the object. + + + + + +Setting this with a GtkType of GTK_TYPE_SIGNAL connects +the signal to the object, so that the signal is always run +after other user handlers and the default handler. + + @@ -1070,33 +2331,40 @@ Register a new set of flags @values and give them the name in @PRIVATE_GTK_DIRECTION_SET: @PRIVATE_GTK_DIRECTION_LTR: - + -Set the mem_chunk size so it will hold @n_chunks of the objects of that @type. +A function which you can use to clean up when the +signal handler is destroyed. + + +For example, if your handler requires a few variables +that you made into a struct and allocated (using g_new() +or something), then you will probably want to free +it as soon as the hook is destroyed. This will +allow you to do that. (For this in particular +it is convenient to pass g_free() as a #GtkSignalDestroy +function). -@type: There must be an unlocked TypeNode associated with this type otherwise nothing happens. -@n_chunks: +@data: The user data associated with the hook that is being +destroyed. - + - - - -@style: -@window: -@state_type: -@shadow_type: -@x: -@y: -@width: -@height: - - - -The first structured enumerated type value. +This is currently a hack left in for a scheme wrapper library. +It may be removed. + + +Don't use it. +@object: The object which emits the signal. +@data: The user data associated with the hook. +@nparams: The number of parameters to the function. +@args: The actual values of the arguments. +@arg_types: The types of the arguments. +@return_type: The type of the return value from the function +or #GTK_TYPE_NONE for no return value. @@ -1114,134 +2382,109 @@ and its unique identifying integer. @nparams: @params: - + -Given a @type, describe all of its children, and their children. Only -show the size if @show_size is true. +Holds the data for a statusbar message. text holds the actual text string. context_id is the context that this message is associated with, and message_id is this particular message's identifier. However, these fields should not be modified directly. -@type: GtkType -@show_size: gboolean +@text: +@context_id: +@message_id: - - - - - -@mark: -@Returns: - - - - - - -@object: -@func: -@func_data: -@args: - - - -An action signal. Delete a single character. - - -@editable: the object which received the signal. -@direction: the direction in which to delete. Positive - indicates forward deletion, negative, backwards deletion. - - + - + -@window: -@xid: +@textbuffer: the object which received the signal. +@arg1: +@arg2: +@arg3: - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@iter: -@pixmap: -@mask: -@Returns: - - - -An action signal. Delete a single word. - - -@editable: the object which received the signal. -@direction: the direction in which to delete. Positive - indicates forward deletion, negative, backwards deletion. - - - - - - -@context_simple: -@data: -@max_seq_len: -@n_seqs: - - + - + -Test whether a GtkObject's arguments have been prepared. + -@obj: the object to examine. - + -Sets one of the two font filters, to limit the fonts shown. +A #GtkJustification for the text. This is only used when the tag is +applied to the first character in a paragraph. -@fsd: a #GtkFontSelectionDialog. -@filter_type: which of the two font filters to set, either -#GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter -can be changed by the user, but the base filter is permanent. -@font_type: the types of font to be shown. This is a bitwise combination of -#GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP, -or #GTK_FONT_ALL to show all three font types. -@foundries: a NULL-terminated array of strings containing foundry names which -will be shown, or NULL to show all foundries. -@weights: a NULL-terminated array of strings containing weight names which -will be shown, or NULL to show all weights. -@slants: a NULL-terminated array of strings containing slant names which -will be shown, or NULL to show all slants. -@setwidths: a NULL-terminated array of strings containing setwidth names which -will be shown, or NULL to show all setwidths. -@spacings: a NULL-terminated array of strings containing spacings which -will be shown, or NULL to show all spacings. -@charsets: a NULL-terminated array of strings containing charset names which -will be shown, or NULL to show all charsets. - + + + + + + + + +Pixel width of the left margin of the text for lines after the first +line in a wrapped paragraph. + + + + + + + + + + + +Pixels to offset the text horizontally or vertically, useful to +produce superscript and subscript. + + + + + + + + + + + + + + + + + + + + + + + + + + +@textview: the object which received the signal. + + + + + + +@textview: the object which received the signal. + + @@ -1250,128 +2493,6 @@ will be shown, or NULL to show all charsets. @arg1: @arg2: - - - - - -@Returns: - - - -No idea. - - - - - -Combine a fundemantal type and a sequence number to create a gtk type. - - -@parent_t: -@seqno: - - -Functions to adapt C structures to native calling convention. - - - - -The last "flat" (no struct) enumerated type value. - - - - - - - - -@selection: -@tree_view: - - - - - - -@mark: - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@object: -@func: -@func_data: -@args: - - - -Destroy all the signal handlers connected to an object. -This is done automatically when the object is destroyed. - - -This function is labeled private. - - -@object: the object whose signal handlers should be destroyed. - - - - - - -@iter: -@start: -@end: -@Returns: - - - -Get the varargs type associated with @foreign_type - - -@foreign_type: GtkType -@Returns: GtkType - - - -Indicates that the user has changed the contents -of the widget. - - -@editable: the object which received the signal. - - - - - - -@tree_column: -@Returns: - - - - - - -@path: -@type: -@accel_group: -@widget: -@subfactories: - @@ -1381,35 +2502,42 @@ of the widget. @arg1: @arg2: - + -Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_FOREIGN + -@a: +@textview: the object which received the signal. +@arg1: +@arg2: - + -Define a signal-handler for a new signal on an already defined -object. - - -See the signal documentation for more general information. + -@klass: the object class to define the signal for. -@name: the name of the signal. -@signal_flags: the default emission behavior for the signal. -See gtk_signal_new(). -@marshaller: a function that will take an array of GtkArgs -and invoke the appropriate handler with the normal calling -conventions. -@return_val: specify the return-value type for the signal -(or GTK_TYPE_NONE for no return-value). -@nparams: specify the number of parameters the signal -receives from the caller of gtk_signal_emit(). -@Varargs: list of nparams #GtkTypes to pass to the signal handlers. -@Returns: the signal id. (See #GtkSignals) +@textview: the object which received the signal. +@arg1: + + + + + + +@textview: the object which received the signal. +@arg1: +@arg2: +@arg3: + + + + + + +@textview: the object which received the signal. +@arg1: +@arg2: +@arg3: @@ -1418,73 +2546,65 @@ receives from the caller of gtk_signal_emit(). @textview: the object which received the signal. - + -@wid: -@flag: +@textview: the object which received the signal. +@arg1: - + -@ruler: the gtkruler +@GTK_TEXT_DELETE_CHAR: +@GTK_TEXT_DELETE_HALF_WORD: +@GTK_TEXT_DELETE_WHOLE_WORD: +@GTK_TEXT_DELETE_HALF_WRAPPED_LINE: +@GTK_TEXT_DELETE_WHOLE_WRAPPED_LINE: +@GTK_TEXT_DELETE_HALF_LINE: +@GTK_TEXT_DELETE_WHOLE_LINE: +@GTK_TEXT_DELETE_WHITESPACE: +@GTK_TEXT_DELETE_WHITESPACE_LEAVE_ONE: - - -Construct an object with an array of arguments. - - -@object_type: the type of the object to create. -@n_args: the number of arguments to set. -@args: an array of n_args arguments (which are name and value pairs). -@Returns: the new GtkObject. - - + -@obj: +@GTK_TEXT_MOVEMENT_CHAR: +@GTK_TEXT_MOVEMENT_POSITIONS: +@GTK_TEXT_MOVEMENT_WORD: +@GTK_TEXT_MOVEMENT_WRAPPED_LINE: +@GTK_TEXT_MOVEMENT_LINE: +@GTK_TEXT_MOVEMENT_LINE_ENDS: +@GTK_TEXT_MOVEMENT_BUFFER_ENDS: - + -@iter: -@Returns: +@GTK_TEXT_SCROLL_TO_TOP: +@GTK_TEXT_SCROLL_TO_BOTTOM: +@GTK_TEXT_SCROLL_PAGE_DOWN: +@GTK_TEXT_SCROLL_PAGE_UP: - + -@GTK_DEBUG_OBJECTS: -@GTK_DEBUG_MISC: -@GTK_DEBUG_SIGNALS: -@GTK_DEBUG_DND: -@GTK_DEBUG_PLUGSOCKET: - + -@factory: -@paths: -@npaths: - - - -Given a type, return various interesting parameters of the type. - - -@type: GtkType -@Returns: GtkTypeQuery* +@GTK_TREE_SELECTION_SINGLE: +@GTK_TREE_SELECTION_MULTI: @@ -1495,309 +2615,6 @@ Given a type, return various interesting parameters of the type. @GTK_TREE_VIEW_COLUMN_AUTOSIZE: @GTK_TREE_VIEW_COLUMN_FIXED: - - - - - - - - -Hide the name of gtk_identifier_get_type - - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - - - -This function is not usually used by users. - - -@ctree: -@columns: -@tree_column: -@titles: - - - - - - -@style: -@window: -@state_type: -@shadow_type: -@x: -@y: -@width: -@height: - - - -Returns whether a connection id is valid (and optionally not blocked). - - -@object: the object to search for the desired handler. -@handler_id: the connection id. -@may_be_blocked: whether it is acceptable to return a blocked -handler. -@Returns: TRUE if the signal exists and wasn't blocked, -unless #may_be_blocked was specified. FALSE otherwise. - - - - - - -@Returns: - - - - - - -@wid: - - - - - - -@Returns: - - - - - - -@object: -@func: -@func_data: -@args: - - - -Given the type of an object and a pointer to it, the object is freed. - - -@type: GtkType -@mem: gpointer to the object - - - - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@path: -@widget: - - - - - - - - - -Holds the data for a statusbar message. text holds the actual text string. context_id is the context that this message is associated with, and message_id is this particular message's identifier. However, these fields should not be modified directly. - - -@text: -@context_id: -@message_id: - - - - - - -@widget: -@stock_id: -@size: -@detail: -@Returns: - - -Private Information - - - - -The position of the cursor. - - - - - - - - -@engine: -@parent_type: -@type_name: -@type_info: -@Returns: - - - - - - -@factory: -@path: -@Returns: - - - - - - -@path: -@accelerator: -@callback: -@callback_data: -@widget: - - - -An action signal. Causes the contents of the clipboard to -be pasted into the editable widget at the current cursor -position. - - -@editable: the object which received the signal. - - - - - - -@window: -@xid: - - - - - - -@tree_column: -@active: - - - -Define a signal-handler for a new signal on an already defined -object. - - -@klass: the object class to define the signal for. -@name: the name of the signal. -@signal_flags: the default emission behavior for the signal. -See gtk_signal_new(). -@marshaller: takes a GtkObject, a #GtkSignalFunc, and an array -of arguments, and invokes the function using the appropriate -calling conventions. Usually just select a function -out of gtkmarshal.h. -@return_val: specify the return-value type for the signal (possibly -#GTK_TYPE_NONE). -@nparams: specify the number of parameters the signal -receives from the caller of gtk_signal_emit(). -@params: array of #GtkTypes the signal handlers for this signal -should have in their prototype (of length nparams). -@Returns: the signal id. (See #GtkSignals) - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@tree_column: -@active: - - - -Controls whether opacity can be set with the #GtkColorSelection. -If this functionality is enabled, the necessary additional widgets -are added to the #GtkColorSelection and the opacity value can be -retrieved via the fourth value in the color array returned by -the gtk_color_selection_get_color() function. - - -@colorsel: a #GtkColorSelection. -@use_opacity: a boolean indicating whether the opacity selection -is enabled. - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -#GtkSignal -The signal handling functions (of which marshallers are -really an implementation detail). - - - - - - - - -An action signal. Move the cursor by words. - - -@editable: the object which received the signal. -@num_words: The number of words to move the -cursor. (Can be negative). - @@ -1830,20 +2647,1486 @@ cursor. (Can be negative). @column: @header_height: - + + +A structure used to return values from @gtk_type_query. + + +@type: +@type_name: +@object_size: +@class_size: + + + +the #GtkAdjustment which sets the range of the scale. + + + + -@obj: - + + + + + +@viewport: the object which received the signal. +@arg1: +@arg2: + + + + + + + + + + + + + + + + + + + + + + + + +@widget: the object which received the signal. +@accel_signal_id: +@accel_group: +@accel_key: +@accel_mods: +@accel_flags: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@message: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@arg1: + + + + + + +@widget: the object which received the signal. +@drag_context: + + + + + + +@widget: the object which received the signal. +@drag_context: + + + + + + +@widget: the object which received the signal. +@drag_context: +@data: +@info: +@time: + + + + + + +@widget: the object which received the signal. +@drag_context: +@x: +@y: +@data: +@info: +@time: + + + + + + +@widget: the object which received the signal. +@drag_context: +@x: +@y: +@time: +@Returns: + + + + + + +@widget: the object which received the signal. +@drag_context: + + + + + + +@widget: the object which received the signal. +@drag_context: +@time: + + + + + + +@widget: the object which received the signal. +@drag_context: +@x: +@y: +@time: +@Returns: + + + + + + +@widget: the object which received the signal. +@area: + + + + + + +@widget: the object which received the signal. + + + + + + +@widget: the object which received the signal. + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. + + + + + + +@widget: the object which received the signal. + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@old_parent: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. + + + + + + +@widget: the object which received the signal. +@accel_group: +@accel_key: +@accel_mods: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@data: +@info: +@time: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. +@data: +@time: + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. + + + + + + +@widget: the object which received the signal. +@allocation: + + + + + + +@widget: the object which received the signal. +@requisition: + + + + + + +@widget: the object which received the signal. +@state: + + + + + + +@widget: the object which received the signal. +@previous_style: + + + + + + +@widget: the object which received the signal. + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + +@widget: the object which received the signal. + + + + + + +@widget: the object which received the signal. +@event: +@Returns: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@window: the object which received the signal. +@event: +@Returns: + + + + + + +@window: the object which received the signal. +@widget: + + + +If the window can be resized to a larger size by the user. + + + + + +If the window can be resized to a smaller size by the user. + + + + + +If the window shrinks automatically when widgets within it shrink. + + + + + + + + + + + + + + + + + + + + + + + +If the window is modal, i.e. it grabs all GTK+ events. + + + + + +The title of the window. + + + + + +The type of the window. + + + + + +The position of the window. + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + +Initializes a previously allocated #GtkCList widget for use. This should not +normally be used to create a #GtkCList widget. Use gtk_clist_new() instead. + + +@clist: A pointer to an uninitialized #GtkCList widget. +@columns: The number of columns the #GtkCList should have. +@titles: An array of strings that should be used as the titles i +of the columns. There should be enough strings in the array for +the number of columns specified. + + + +Controls whether opacity can be set with the #GtkColorSelection. +If this functionality is enabled, the necessary additional widgets +are added to the #GtkColorSelection and the opacity value can be +retrieved via the fourth value in the color array returned by +the gtk_color_selection_get_color() function. + + +@colorsel: a #GtkColorSelection. +@use_opacity: a boolean indicating whether the opacity selection +is enabled. + + + + + + +@Returns: + + + + + + +@container: + + + + + + +@container: + + + +This function is not usually used by users. + + +@ctree: +@columns: +@tree_column: +@titles: + + + + + + + + + + + + +@style: +@window: +@state_type: +@shadow_type: +@x: +@y: +@width: +@height: + + + + + + +@style: +@window: +@state_type: +@shadow_type: +@x: +@y: +@width: +@height: + + + + + + +@style: +@window: +@state_type: +@shadow_type: +@arrow_type: +@x: +@y: +@width: +@height: + + + +Causes the "changed" signal to be emitted. + + +@editable: a #GtkEditable widget. + + + +Claim or disclaim ownership of the PRIMARY X selection. + + +@editable: a #GtkEditable widget. +@claim: if %TRUE, claim the selection, otherwise, disclaim it. +@time: the timestamp for claiming the selection. + + + +Sets one of the two font filters, to limit the fonts shown. + + +@fsd: a #GtkFontSelectionDialog. +@filter_type: which of the two font filters to set, either +#GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter +can be changed by the user, but the base filter is permanent. +@font_type: the types of font to be shown. This is a bitwise combination of +#GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP, +or #GTK_FONT_ALL to show all three font types. +@foundries: a NULL-terminated array of strings containing foundry names which +will be shown, or NULL to show all foundries. +@weights: a NULL-terminated array of strings containing weight names which +will be shown, or NULL to show all weights. +@slants: a NULL-terminated array of strings containing slant names which +will be shown, or NULL to show all slants. +@setwidths: a NULL-terminated array of strings containing setwidth names which +will be shown, or NULL to show all setwidths. +@spacings: a NULL-terminated array of strings containing spacings which +will be shown, or NULL to show all spacings. +@charsets: a NULL-terminated array of strings containing charset names which +will be shown, or NULL to show all charsets. + + + +Sets one of the two font filters, to limit the fonts shown. + + +@fontsel: a #GtkFontSelection. +@filter_type: which of the two font filters to set, either +#GTK_FONT_FILTER_BASE or #GTK_FONT_FILTER_USER. The user filter +can be changed by the user, but the base filter is permanent. +@font_type: the types of font to be shown. This is a bitwise combination of +#GTK_FONT_BITMAP, #GTK_FONT_SCALABLE and #GTK_FONT_SCALABLE_BITMAP, +or #GTK_FONT_ALL to show all three font types. +@foundries: a NULL-terminated array of strings containing foundry names which +will be shown, or NULL to show all foundries. +@weights: a NULL-terminated array of strings containing weight names which +will be shown, or NULL to show all weights. +@slants: a NULL-terminated array of strings containing slant names which +will be shown, or NULL to show all slants. +@setwidths: a NULL-terminated array of strings containing setwidth names which +will be shown, or NULL to show all setwidths. +@spacings: a NULL-terminated array of strings containing spacings which +will be shown, or NULL to show all spacings. +@charsets: a NULL-terminated array of strings containing charset names which +will be shown, or NULL to show all charsets. + + + + + + +@Returns: + + + +Get the type of GtkIdentifier. + + +@Returns: GtkType -- the enumerated type of something. + + + + + + +@context_simple: +@data: +@max_seq_len: +@n_seqs: + + + + + + +@Returns: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + +@object: +@func: +@func_data: +@args: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@factory: +@entries: +@nentries: + + + + + + +@factory: +@subfactory: +@path: + + + + + + +@factory: + + + + + + +@factory: +@path: +@Returns: + + @type: -@action: +@Returns: + + + + + + +@factory: +@entries: +@nentries: + + + + + + +@factory: +@paths: +@npaths: + + + + + + +@factory: +@subfactory: +@path: + + + + + + +@Returns: + + + + + + +@simple: +@path: +@iter: + + + + + + +@simple: +@path: +@iter: + + + + + + +@simple: +@path: +@iter: + + + + + + +@simple: +@path: +@iter: + + + +Private function to get an argument and argument info from an object. + + +@object: the object whose argument should be retrieved. +@arg: the argument, for the name on input, the rest is filled on output. +@info: a #GtkArgInfo structure to optionally fill in. + + + +Query information about an argument type. + + +@object_type: type of object to query about. +@arg_name: name of the argument. +@info_p: pointer to be filled in with a pointer to the GtkArgInfo. +@Returns: an error message, or NULL on success. +It is the caller's responsibility to call g_free() in the event of error. @@ -1854,69 +4137,74 @@ Private function to set an argument and argument info to an object. @arg: the argument. @info: infomation about this type of argument in general. - + - +Private: Gets an array of #GtkArgs from a va_list C structure. -@GTK_TEXT_DELETE_CHAR: -@GTK_TEXT_DELETE_HALF_WORD: -@GTK_TEXT_DELETE_WHOLE_WORD: -@GTK_TEXT_DELETE_HALF_WRAPPED_LINE: -@GTK_TEXT_DELETE_WHOLE_WRAPPED_LINE: -@GTK_TEXT_DELETE_HALF_LINE: -@GTK_TEXT_DELETE_WHOLE_LINE: -@GTK_TEXT_DELETE_WHITESPACE: -@GTK_TEXT_DELETE_WHITESPACE_LEAVE_ONE: +@object_type: the type of object to collect arguments for. +@arg_list_p: pointer to be filled in with a list of parsed arguments. +@info_list_p: optional pointer for a returned list #GtkArgInfos. +@first_arg_name: name of first argument. +@var_args: value of first argument, followed by more key/value pairs, +terminated by NULL. +@Returns: an error message, or NULL on success. +It is the caller's responsibility to call g_free() in the event of error. - + - +Add an array of signals to a #GtkObjectClass. +Usually this is called when registering a new type of object. -@object: -@tables: -@compose_buffer: -@tentative_match: -@tentative_match_len: +@klass: the object class to append signals to. +@signals: the signals to append. +@nsignals: the number of signals being appended. - + -The first "flat" (no struct) enumerated type value. +Define a signal-handler for a new signal on an already defined +object. + + +See the signal documentation for more general information. +@klass: the object class to define the signal for. +@name: the name of the signal. +@signal_flags: the default emission behavior for the signal. +See gtk_signal_new(). +@marshaller: a function that will take an array of GtkArgs +and invoke the appropriate handler with the normal calling +conventions. +@return_val: specify the return-value type for the signal +(or GTK_TYPE_NONE for no return-value). +@nparams: specify the number of parameters the signal +receives from the caller of gtk_signal_emit(). +@Varargs: list of nparams #GtkTypes to pass to the signal handlers. +@Returns: the signal id. (See #GtkSignals) - + - +Define a signal-handler for a new signal on an already defined +object. -@widget: -@nargs: -@args: - - - - - - -@tree_model_sort: - - - - - - -@tree_column: -@Returns: - - - - - - -@type: -@Returns: +@klass: the object class to define the signal for. +@name: the name of the signal. +@signal_flags: the default emission behavior for the signal. +See gtk_signal_new(). +@marshaller: takes a GtkObject, a #GtkSignalFunc, and an array +of arguments, and invokes the function using the appropriate +calling conventions. Usually just select a function +out of gtkmarshal.h. +@return_val: specify the return-value type for the signal (possibly +#GTK_TYPE_NONE). +@nparams: specify the number of parameters the signal +receives from the caller of gtk_signal_emit(). +@params: array of #GtkTypes the signal handlers for this signal +should have in their prototype (of length nparams). +@Returns: the signal id. (See #GtkSignals) @@ -1957,178 +4245,24 @@ be used to bypass it. @object: the object to initialize. - + - +Gets an array of argument values from an object. +@object: the object to get arguments from. +@n_args: the number of arguments to query. +@args: the arguments to fill in. - - -Internal to #GtkLabel. - - - - + - +Construct an object with an array of arguments. -@buffer: - - - - - - - - - -Query information about an argument type. - - -@object_type: type of object to query about. -@arg_name: name of the argument. -@info_p: pointer to be filled in with a pointer to the GtkArgInfo. -@Returns: an error message, or NULL on success. -It is the caller's responsibility to call g_free() in the event of error. - - - - - - -@GTK_TREE_SELECTION_SINGLE: -@GTK_TREE_SELECTION_MULTI: - - - -Setting this with a GtkType of GTK_TYPE_SIGNAL connects -the signal to the object, so that the signal is always run -after other user handlers and the default handler. - - - - - - - - - - - - - - - - - -A macro that returns a GList that contains the selection of the root tree of @obj. - - -@obj: A pointer to the #GtkTree. @obj will accept any pointer, but it the pointer does not point to a #GtkTree, the results are undefined. - - - -Causes the "changed" signal to be emitted. - - -@editable: a #GtkEditable widget. - - - -Set an array of arguments. - - -@object: the object whose arguments should be set. +@object_type: the type of the object to create. @n_args: the number of arguments to set. -@args: the desired values, as an array of #GtkArgs (which contain -the names, types, and values of the arguments). - - - - - - -@textview: the object which received the signal. -@arg1: -@arg2: -@arg3: - - - - - - -@obj: - - - - - - -@buffer: -@time: - - - - - - -@mark: -@Returns: - - - -Pixels to offset the text horizontally or vertically, useful to -produce superscript and subscript. - - - - - -This signal is emitted when text is inserted into -the widget by the user. The default handler for -this signal will normally be responsible for inserting -the text, so by connecting to this signal and then -stopping the signal with gtk_signal_emit_stop(), it -is possible to modify the inserted text, or prevent -it from being inserted entirely. - - -@editable: the object which received the signal. -@new_text: the new text to insert. -@new_text_length: the length of the new text. -@position: the position at which to insert the new text. - this is an in-out paramter. After the signal - emission is finished, it should point after - the newly inserted text. - - - -Claim or disclaim ownership of the PRIMARY X selection. - - -@editable: a #GtkEditable widget. -@claim: if %TRUE, claim the selection, otherwise, disclaim it. -@time: the timestamp for claiming the selection. - - - - - - -@object: -@func: -@func_data: -@args: - - - -Get the array of signals defined for this object. - - -@obj: the object to fetch the signals from. +@args: an array of n_args arguments (which are name and value pairs). +@Returns: the new GtkObject. @@ -2148,121 +4282,49 @@ each argument. You must g_free() this if you request it. @n_args: the number of arguments is returned in this field. @Returns: an array of arguments, that you must deallocate with g_free(). - + -An action signal. Move the cursor to the given column. +Set an array of arguments. -@editable: the object which received the signal. -@column: the column to move to. (A negative value indicates - the last column) +@object: the object whose arguments should be set. +@n_args: the number of arguments to set. +@args: the desired values, as an array of #GtkArgs (which contain +the names, types, and values of the arguments). - -gtkenums.sgml - - - - - - - -@object: -@func: -@func_data: -@args: - - + +@style: +@window: +@state_type: +@shadow_type: +@area: @widget: -@user_data: +@detail: +@x: +@y: +@width: +@height: - - -Given a pointer to a GtkTypeObject @type_object, and a GtkType @cast_type, -make sure that it's okay to cast @type_object into a @cast_type. - - -@type_object: GtkTypeObject* -@cast_type: GtkType -@Returns: the same GtkTypeObject* as @type_object - - + -@tree_model_sort: -@sort_col: - - - - - - -@error_code: - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - - - - - - - - - - -Set the varargs type for a fundamental type @foreign_type. - - -@foreign_type: Must be a GtkType with a sequence number of zero. Must not be a -fundamental type. -@varargs_type: Must be a GtkType which is either structured or flag, or NONE. - - - -Given a GtkTypeClass pointer @klass, and a GtkType @cast_type, make -sure that it's okay to cast something of that @klass into a @cast_type. - - -@klass: GtkTypeClass* -@cast_type: GtkType -@Returns: Always return @klass. - - - -Setting this with a GtkType of GTK_TYPE_SIGNAL connects -the signal to the object, so that the user data and objects -and swapped when the signal handler is invoked, -and so that the handler is invoked after all others. - - -See gtk_signal_connect_object_after() for more details. - - - - - - - - -@factory: +@style: +@window: +@state_type: +@shadow_type: +@area: +@widget: +@detail: +@x: +@y: +@width: +@height: @@ -2282,6 +4344,81 @@ See gtk_signal_connect_object_after() for more details. @width: @height: + + +Internal function used by #GtkHPaned and #GtkVPaned + + +@paned: +@allocation: +@child1_req: +@child2_req: + + + +Internal function. + + + + + + + + +@ruler: the gtkruler + + + + + + +@ruler: the gtkruler + + + +Add an emission hook for a type of signal, for any object. +(with control of what happens when the hook is +destroyed). + + +@signal_id: the type of signal add the hook for. +@hook_func: the function to invoke to handle the hook. +@data: the user data passed in to hook_func. +@destroy: a function to invoke when the hook is destroyed, +to clean up any allocation done just for this +signal handler. +@Returns: the id (that you may pass as a parameter +to gtk_signal_remove_emission_hook()). + + + +Returns whether a connection id is valid (and optionally not blocked). + + +@object: the object to search for the desired handler. +@handler_id: the connection id. +@may_be_blocked: whether it is acceptable to return a blocked +handler. +@Returns: TRUE if the signal exists and wasn't blocked, +unless #may_be_blocked was specified. FALSE otherwise. + + + +Destroy all the signal handlers connected to an object. +This is done automatically when the object is destroyed. + + +This function is labeled private. + + +@object: the object whose signal handlers should be destroyed. + + + + + + + Find out the recursion depth of emissions for a particular type @@ -2301,66 +4438,27 @@ and decreases by one when #gtk_signal_emit() returns. @Returns: the recursion depth of emissions of this signal for this object. - + - +Find out the recursion depth of emissions for a particular type +of signal and object. Just like gtk_signal_n_emissions() +except it will lookup the signal id for you. -@buffer: -@iter: -@pixmap: -@mask: +@object: the object with the signal handler. +@name: the signal name. +@Returns: the recursion depth of emissions of this signal for this +object. - + - +Obtain information about a signal. - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@object: -@func: -@func_data: -@args: - - - -Use to get the value of a GtkArg whose GtkType is GTK_TYPE_ARGS - - -@a: - - - - - - -@factory: -@entries: -@nentries: - - - -An action signal. Move the cursor to the given row. - - -@editable: the object which received the signal. -@row: the row to move to. (A negative value indicates - the last row) +@signal_id: the signal type identifier. +@Returns: a pointer to a GtkSignalQuery structure +which contains all the information, or NULL. +The pointer is allocated just for you: you must g_free() it. @@ -2377,385 +4475,23 @@ isn't a function pointer. May be NULL. @destroy_func: the function to invoke when each hook is destroyed. May be NULL. - - - - - -@Returns: - - - - - - -@style: -@window: -@state_type: -@shadow_type: -@area: -@widget: -@detail: -@x: -@y: -@width: -@height: - - - -Setting this with a GtkType of GTK_TYPE_SIGNAL connects -the signal to the object. - - - - - -Print the types @type inherits from. - - -@type: GtkType - - + @buffer: -@text: +@time: - - -A set of bit flags used to specify the filter being set -when calling gtk_font_selection_dialog_set_filter() or -gtk_font_selection_set_filter(). - - -@GTK_FONT_FILTER_BASE: the base filter, which can't be changed by the user. -@GTK_FONT_FILTER_USER: the user filter, which can be changed from within the -'Filter' page of the #GtkFontSelection widget. - - - -An action signal. Move the cursor position. - - -@editable: the object which received the signal. -@x: horizontal distance to move the cursor. -@y: vertical distance to move the cursor. - - - -Return the class of the parent. Initialize the class if necessary. -Return NULL if anything goes wrong. - - -@type: GtkType -@Returns: gpointer to the klass. - - - -A function which you can use to clean up when the -signal handler is destroyed. - - -For example, if your handler requires a few variables -that you made into a struct and allocated (using g_new() -or something), then you will probably want to free -it as soon as the hook is destroyed. This will -allow you to do that. (For this in particular -it is convenient to pass g_free() as a #GtkSignalDestroy -function). - - -@data: The user data associated with the hook that is being -destroyed. - - + -@window: -@defaultw: - - - - - - -@tree_store: -@iter: -@var_args: - - - - - - -@textbuffer: the object which received the signal. -@arg1: -@arg2: -@arg3: - - - - - - -@tree_view: -@Returns: - - - - - - -@object: -@func: -@func_data: -@args: - - - -Setting this with a GtkType of GTK_TYPE_SIGNAL connects -the signal to the object, so that the user data and objects -and swapped when the signal handler is invoked. - - -This is useful for handlers that are primarily notifying -other objects and could just invoke an already existing function -if the parameters were swapped. -See gtk_signal_connect_object() for more details. - - - - - - - - -@style: -@window: -@state_type: -@shadow_type: -@arrow_type: -@x: -@y: -@width: -@height: - - - - - - -@obj: - - - - - - - - - - - - -@obj: - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@tree_column: -@type: - - - - - - - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@widget: the object which received the signal. -@area: - - - - - - - - - - - - -@object: -@func: -@func_data: -@args: - - - -Internal function. - - - - - -Obtain information about a signal. - - -@signal_id: the signal type identifier. -@Returns: a pointer to a GtkSignalQuery structure -which contains all the information, or NULL. -The pointer is allocated just for you: you must g_free() it. - - - -Find out the recursion depth of emissions for a particular type -of signal and object. Just like gtk_signal_n_emissions() -except it will lookup the signal id for you. - - -@object: the object with the signal handler. -@name: the signal name. -@Returns: the recursion depth of emissions of this signal for this -object. - - - - - - - - - - - - -@textview: the object which received the signal. -@arg1: -@arg2: - - - - - - - - - - - - -@v: -@visual: - - - - - - -@container: - - -GtkIMContextSimple - - - - - - - - - - -Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_CALLBACK - - -@a: - - - - - - -@object: -@func: -@func_data: -@args: - - - - - - -@textview: the object which received the signal. -@arg1: -@arg2: -@arg3: - - - - - - - - - - - - -@tree_view: -@active: +@buffer: +@time: +@interactive: +@default_editable: @@ -2768,24 +4504,98 @@ Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_CALLBACK @end: @Returns: - + -@factory: -@subfactory: -@path: +@buffer: +@iter: +@str: +@start: +@end: +@Returns: - + -@GTK_TEXT_SCROLL_TO_TOP: -@GTK_TEXT_SCROLL_TO_BOTTOM: -@GTK_TEXT_SCROLL_PAGE_DOWN: -@GTK_TEXT_SCROLL_PAGE_UP: +@buffer: +@Returns: + + + + + + +@buffer: +@iter: +@Returns: + + + + + + +@buffer: +@iter: +@pixmap: +@mask: + + + + + + +@buffer: +@override_location: +@time: +@interactive: +@default_editable: + + + + + + +@buffer: +@text: + + + + + + +@buffer: + + + + + + +@iter: +@Returns: + + + + + + +@iter: +@pixmap: +@mask: +@Returns: + + + + + + +@iter: +@start: +@end: +@Returns: @@ -2795,6 +4605,169 @@ Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_CALLBACK @iter: @Returns: + + + + + +@iter: +@Returns: + + + + + + +@mark: +@Returns: + + + + + + +@mark: +@Returns: + + + + + + +@mark: +@Returns: + + + + + + +@mark: + + + + + + +@text_view: +@iter: +@x: +@y: + + + + + + +@engine: +@Returns: + + + + + + +@name: +@Returns: + + + + + + +@engine: + + + + + + +@engine: +@parent_type: +@type_name: +@type_info: +@Returns: + + + + + + +@engine: + + + + + + +@error_code: + + + + + + +@argc: +@argv: + + + +Private: print debugging information while doing a gtk_object_ref() or +a gtk_object_unref(). + + +@object: object to reference or unreference. +@func: name of caller's function to print (used within macros). +@dummy: unused. +@line: line number (used within macros). +@do_ref: whether to reference or unreference. + + + + + + +@tree_model_sort: + + + + + + +@tree_model_sort: +@sort_col: + + + + + + +@Returns: + + + + + + +@tree_view: +@Returns: + + + + + + +@selection: +@tree_view: + + + + + + +@selection: +@type: + @@ -2803,9 +4776,348 @@ Use to get the value of a GtkArg whose GtkType is GTK_TYPE_C_CALLBACK @tree_store: @iter: - + +@tree_store: +@iter: +@var_args: + + + + + + +@n_columns: +@Varargs: +@Returns: + + + + + + +@tree_store: +@iter: +@var_args: + + + + + + +@tree_column: +@Returns: + + + + + + +@tree_column: +@Returns: + + + + + + +@tree_column: +@Returns: + + + + + + +@tree_column: +@Returns: + + + + + + +@tree_column: +@type: + + + + + + +@tree_column: +@active: + + + + + + +@tree_column: +@active: + + + + + + +@tree_column: +@justification: + + + + + + +@tree_column: +@size: +@width: + + + + + + +@tree_view: +@path: +@column: +@row_align: +@col_align: + + + + + + +@tree_view: +@active: + + + +Given a GtkTypeClass pointer @klass, and a GtkType @cast_type, make +sure that it's okay to cast something of that @klass into a @cast_type. + + +@klass: GtkTypeClass* +@cast_type: GtkType +@Returns: Always return @klass. + + + +Given a pointer to a GtkTypeObject @type_object, and a GtkType @cast_type, +make sure that it's okay to cast @type_object into a @cast_type. + + +@type_object: GtkTypeObject* +@cast_type: GtkType +@Returns: the same GtkTypeObject* as @type_object + + + +Return the pointer to the type's children's types. + + +@type: GtkType +@Returns: pointer to a GList + + + +Print the types @type inherits from. + + +@type: GtkType + + + +Given a @type, describe all of its children, and their children. Only +show the size if @show_size is true. + + +@type: GtkType +@show_size: gboolean + + + +Given the type of an object and a pointer to it, the object is freed. + + +@type: GtkType +@mem: gpointer to the object + + + +Get the varargs type associated with @foreign_type + + +@foreign_type: GtkType +@Returns: GtkType + + + +Return the class of the parent. Initialize the class if necessary. +Return NULL if anything goes wrong. + + +@type: GtkType +@Returns: gpointer to the klass. + + + +Given a type, return various interesting parameters of the type. + + +@type: GtkType +@Returns: GtkTypeQuery* + + + +Register a new set of enum @values and give them the name in +@type_name. + + +@type_name: must not be null. +@values: GtkEnumValue* +@Returns: + + + +Register a new set of flags @values and give them the name in +@type_name. + + +@type_name: must not be null. +@values: GtkFlagValue* +@Returns: + + + +Set the mem_chunk size so it will hold @n_chunks of the objects of that @type. + + +@type: There must be an unlocked TypeNode associated with this type otherwise nothing happens. +@n_chunks: + + + +Set the varargs type for a fundamental type @foreign_type. + + +@foreign_type: Must be a GtkType with a sequence number of zero. Must not be a +fundamental type. +@varargs_type: Must be a GtkType which is either structured or flag, or NONE. + + + + + + +@widget: +@arg: + + + + + + +@widget: +@nargs: +@args: + + + + + + +@type: +@nargs: +@args: +@Returns: + + + + + + +@v: + + + + + + +@v: +@visual: + + + + + + +@widget: +@stock_id: +@size: +@detail: +@Returns: + + + + + + +@v: +@visual: + + + + + + +@w: +@v: +@widget: +@visual: + + + + + + +@widget: +@nargs: +@args: + + + + + + +@window: +@xid: + + + + + + +@window: +@xid: + + + + + + +@window: +@defaultw: + + + + + + +@window: +@focus: diff --git a/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml b/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml index 11ebd19021..15a4ee127d 100644 --- a/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml +++ b/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml @@ -30,8 +30,10 @@ GtkTreeViewColumn @tree_view: @button: @child: +@arrow: +@alignment: @window: -@justification: +@xalign: @id: @width: @min_width: @@ -42,9 +44,11 @@ GtkTreeViewColumn @cell: @attributes: @column_type: +@sort_order: @visible: @button_active: @dirty: +@show_sort_indicator: @@ -223,15 +227,6 @@ GtkTreeViewColumn @title: - - - - - -@tree_column: -@Returns: - - @@ -259,24 +254,6 @@ GtkTreeViewColumn @Returns: - - - - - -@tree_column: -@justification: - - - - - - - -@tree_column: -@Returns: - -