AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Use the new snazzy mother-of-all-gtk-doc-makefiles.

Browse Source 
Sun Feb 11 22:16:34 2001  Owen Taylor  <otaylor@redhat.com>

	* */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.
This commit is contained in:
Owen Taylor 2001-02-12 17:50:13 +00:00 committed by Owen Taylor
parent 730a2bdc6b
commit 32abeb4c96
25 changed files with 9093 additions and 3600 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/reference/ChangeLog
View File

@ -1,3 +1,10 @@
Sun Feb 11 22:16:34 2001 Owen Taylor <otaylor@redhat.com>
* */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 <hp@pobox.com>
* gtk/windows.sgml: windows (file is blank)

162
docs/reference/gdk-pixbuf/Makefile.am
View File

@ -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

61
docs/reference/gdk-pixbuf/tmpl/animation.sgml
View File

@ -1,38 +1,52 @@
<!-- ##### SECTION Title ##### -->
animation
Animations
<!-- ##### SECTION Short_Description ##### -->
Animations as multi-frame structures.
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<para>
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.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
#GdkPixbufLoader
</para>
<!-- ##### ENUM GdkPixbufFrameAction ##### -->
<para>
<para>
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.
</para>
</para>
@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.
<!-- ##### STRUCT GdkPixbufFrame ##### -->
<para>
</para>
<para>
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.
</para>
<!-- ##### STRUCT GdkPixbufAnimation ##### -->
<para>
</para>
<para>
This structure describes an animation, which is represented as a
list of #GdkPixbufFrame structures.
</para>
<!-- ##### FUNCTION gdk_pixbuf_animation_new_from_file ##### -->
@ -140,6 +154,11 @@ animation
</para>
@frame:
@Returns:
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

52
docs/reference/gdk-pixbuf/tmpl/creating.sgml
View File

@ -1,18 +1,47 @@
<!-- ##### SECTION Title ##### -->
creating
Image Data in Memory
<!-- ##### SECTION Short_Description ##### -->
Creating a pixbuf from image data that is already in memory.
<!-- ##### SECTION Long_Description ##### -->
<para>
<para>
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.
</para>
</para>
<para>
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.
</para>
<para>
As a special case, you can use the gdk_pixbuf_new_from_xpm_data()
function to create a pixbuf from inline XPM image data.
</para>
<para>
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.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
gdk_pixbuf_finalize().
</para>
<!-- ##### FUNCTION gdk_pixbuf_new ##### -->
<para>
@ -84,8 +113,11 @@ creating
</para>
@pixbuf:
@Returns:
<!-- # Unused Parameters # -->
@src:
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

32
docs/reference/gdk-pixbuf/tmpl/file-loading.sgml
View File

@ -1,18 +1,29 @@
<!-- ##### SECTION Title ##### -->
file-loading
File Loading
<!-- ##### SECTION Short_Description ##### -->
Loading a pixbuf from a file.
<!-- ##### SECTION Long_Description ##### -->
<para>
<para>
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.
</para>
</para>
<para>
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.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
#GdkPixbufLoader.
</para>
<!-- ##### FUNCTION gdk_pixbuf_new_from_file ##### -->
<para>
@ -21,6 +32,11 @@ file-loading
@filename:
@error:
@Returns:
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

1346
docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml
View File

File diff suppressed because it is too large Load Diff

31
docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-xlib-init.sgml
View File

@ -1,18 +1,26 @@
<!-- ##### SECTION Title ##### -->
gdk-pixbuf-xlib-init
&gdk-pixbuf; Xlib initialization
<!-- ##### SECTION Short_Description ##### -->
Initializing the &gdk-pixbuf; Xlib library.
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<para>
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.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
XlibRGB
</para>
<!-- ##### FUNCTION gdk_pixbuf_xlib_init ##### -->
<para>
@ -30,6 +38,11 @@ gdk-pixbuf-xlib-init
@display:
@screen_num:
@prefDepth:
@prefDepth: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

61
docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml
View File

@ -1,18 +1,19 @@
<!-- ##### SECTION Title ##### -->
gdk-pixbuf
The GdkPixbuf Structure
<!-- ##### SECTION Short_Description ##### -->
Information that describes an image.
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<para>
The <structname>GdkPixbuf</structname> structure contains
information that describes an image in memory.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
</para>
<!-- ##### ENUM GdkPixbufError ##### -->
<para>
@ -34,24 +35,39 @@ gdk-pixbuf
<!-- ##### ENUM GdkColorspace ##### -->
<para>
<para>
This enumeration defines the color spaces that are supported by
the &gdk-pixbuf; library. Currently only RGB is supported.
</para>
</para>
@GDK_COLORSPACE_RGB:
@GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
<!-- ##### ENUM GdkPixbufAlphaMode ##### -->
<para>
<para>
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.
</para>
</para>
@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.
<!-- ##### STRUCT GdkPixbuf ##### -->
<para>
</para>
<para>
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.
</para>
<!-- ##### FUNCTION gdk_pixbuf_get_colorspace ##### -->
@ -123,6 +139,11 @@ gdk-pixbuf
</para>
@pixbuf:
@Returns:
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

25
docs/reference/gdk-pixbuf/tmpl/initialization_versions.sgml
View File

@ -14,31 +14,6 @@ Initialization and Versions
</para>
<!-- ##### FUNCTION gdk_pixbuf_init ##### -->
<para>
</para>
<!-- ##### FUNCTION gdk_pixbuf_preinit ##### -->
<para>
</para>
@app:
@modinfo:
<!-- ##### FUNCTION gdk_pixbuf_postinit ##### -->
<para>
</para>
@app:
@modinfo:
<!-- ##### VARIABLE gdk_pixbuf_version ##### -->
<para>

71
docs/reference/gdk-pixbuf/tmpl/refcounting.sgml
View File

@ -1,32 +1,77 @@
<!-- ##### SECTION Title ##### -->
refcounting
Reference Counting and Memory Mangement
<!-- ##### SECTION Short_Description ##### -->
Functions to perform reference counting and memory management on a
#GdkPixbuf.
<!-- ##### SECTION Long_Description ##### -->
<para>
<para>
#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.
</para>
</para>
<para>
<emphasis>Finalizing</emphasis> 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.
</para>
<para>
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.
</para>
<!-- FIXME: link the last sentence above to the relevant section of
the programmer's docs.
-->
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
#GdkPixbuf, gdk_pixbuf_new_from_data().
</para>
<!-- ##### USER_FUNCTION GdkPixbufDestroyNotify ##### -->
<para>
<para>
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.
</para>
</para>
@pixels:
@data:
@pixels: The pixel array of the pixbuf that is being finalized.
@data: User closure data.
<!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
<para>
<para>
</para>
</para>
@pixbuf:
@Returns:

107
docs/reference/gdk-pixbuf/tmpl/scaling.sgml
View File

@ -1,28 +1,102 @@
<!-- ##### SECTION Title ##### -->
scaling
Scaling
<!-- ##### SECTION Short_Description ##### -->
Scaling pixbufs and scaling and compositing pixbufs
<!-- ##### SECTION Long_Description ##### -->
<para>
<para>
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.
</para>
</para>
<para>
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.
</para>
<para>
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().
</para>
<programlisting>
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;
}
</programlisting>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
GdkRGB
</para>
<!-- ##### ENUM GdkInterpType ##### -->
<para>
<para>
This enumeration describes the different interpolation modes that
can be used with the scaling functions.
</para>
<note>
<para>
Cubic filtering is missing from the list; hyperbolic
interpolation is just as fast and results in higher quality.
</para>
</note>
</para>
@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).
<!-- ##### FUNCTION gdk_pixbuf_scale ##### -->
<para>
@ -110,6 +184,11 @@ scaling
@check_size:
@color1:
@color2:
@Returns:
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->

26
docs/reference/gdk-pixbuf/tmpl/util.sgml
View File

@ -1,18 +1,21 @@
<!-- ##### SECTION Title ##### -->
util
Utilities
<!-- ##### SECTION Short_Description ##### -->
Utility and miscellaneous convenience functions.
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<para>
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.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<para>
#GdkPixbuf
</para>
<!-- ##### FUNCTION gdk_pixbuf_add_alpha ##### -->
<para>
@ -39,7 +42,12 @@ util
@height:
@dest_pixbuf:
@dest_x:
@dest_y:
@dest_y: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
<!-- ##### FUNCTION gdk_pixbuf_saturate_and_pixelate ##### -->

143
docs/reference/gdk/Makefile.am
View File

@ -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

307
docs/reference/gdk/tmpl/colors.sgml
View File

@ -2,11 +2,40 @@
Colormaps and Colors
<!-- ##### SECTION Short_Description ##### -->
manipulation of colors and colormaps.
<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,7 +45,37 @@ Colormaps and Colors
<!-- ##### STRUCT GdkColor ##### -->
<para>
The #GdkColor structure is used to describe an
allocated or unallocated color.
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry><structfield>pixel</structfield></entry>
<entry>For allocated colors, the value used to
draw this color on the screen.</entry>
</row>
<row>
<entry><structfield>red</structfield></entry>
<entry>The red component of the color. This is
a value between 0 and 65535, with 65535 indicating
full intensitiy.</entry>
</row>
<row>
<entry><structfield>green</structfield></entry>
<entry>the blue component of the color.</entry>
</row>
<row>
<entry><structfield>blue</structfield></entry>
<entry>the green component of the color..</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@pixel:
@ -26,7 +85,28 @@ Colormaps and Colors
<!-- ##### STRUCT GdkColormap ##### -->
<para>
The colormap structure contains the following public
fields.
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry><structfield>size</structfield></entry>
<entry>For pseudo-color colormaps, the number of colors
in the colormap..</entry>
</row>
<row>
<entry><structfield>colors</structfield></entry>
<entry>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.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@parent_instance:
@ -35,219 +115,278 @@ Colormaps and Colors
<!-- ##### FUNCTION gdk_colormap_new ##### -->
<para>
Create a new colormap for the given visual.
</para>
@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.
<!-- ##### FUNCTION gdk_colormap_ref ##### -->
<para>
Increase the reference count of a colormap.
</para>
@cmap:
@Returns:
@cmap: a #GdkColormap.
@Returns: @cmap
<!-- ##### FUNCTION gdk_colormap_unref ##### -->
<para>
Decrease the reference count of a colormap. If the
resulting reference count is zero, destroys the colormap.
</para>
@cmap:
@cmap: a #GdkColormap.
<!-- ##### FUNCTION gdk_colormap_get_system ##### -->
<para>
Returns the system's default colormap.
</para>
@Returns:
@Returns: the default colormap.
<!-- ##### FUNCTION gdk_colormap_get_system_size ##### -->
<para>
Returns the size of the system's default colormap.
(See the description of struct #GdkColormap for an
explanation of the size of a colormap.)
</para>
@Returns:
@Returns: the size of the system's default colormap.
<!-- ##### FUNCTION gdk_colormap_change ##### -->
<para>
Change the value of the first @ncolors in a private colormap
to match the values in the <structfield>colors</structfield>
array in the color map. This function is obsolete and
should not be used. See gdk_color_change().
</para>
@colormap:
@ncolors:
@colormap: a #GdkColormap.
@ncolors: the number of colors to change.
<!-- ##### FUNCTION gdk_colormap_alloc_colors ##### -->
<para>
Allocates colors from a colormap.
</para>
@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.
<!-- ##### FUNCTION gdk_colormap_alloc_color ##### -->
<para>
Allocate a single color from a colormap.
</para>
@colormap:
@color:
@writeable:
@best_match:
@Returns:
@colormap: a #GdkColormap.
@color: the color to allocate. On return the
<structfield>pixel</structfield> 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.
<!-- ##### FUNCTION gdk_colormap_free_colors ##### -->
<para>
Free previously allocated colors.
</para>
@colormap:
@colors:
@ncolors:
@colormap: a #GdkColormap.
@colors: the colors to free.
@ncolors: the number of colors in @colors.
<!-- ##### FUNCTION gdk_colormap_get_visual ##### -->
<para>
Return the visual for which a given colormap was created.
</para>
@colormap:
@Returns:
@colormap: a #GdkColormap.
@Returns: the visual of the colormap.
<!-- ##### FUNCTION gdk_colors_store ##### -->
<para>
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().
</para>
@colormap:
@colors:
@ncolors:
@colormap: a #GdkColormap.
@colors: the new color values.
@ncolors: the number of colors to change.
<!-- ##### FUNCTION gdk_color_copy ##### -->
<para>
Make a copy of a color structure. The result
must be freed using gdk_color_free().
</para>
@color:
@Returns:
@color: a #GdkColor.
@Returns: a copy of @color.
<!-- ##### FUNCTION gdk_color_free ##### -->
<para>
Free a color structure created with
gdk_color_copy().
</para>
@color:
@color: a #GdkColor.
<!-- ##### FUNCTION gdk_colors_alloc ##### -->
<para>
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.
</para>
@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:
<!-- ##### FUNCTION gdk_colors_free ##### -->
<para>
Free colors allocated with gdk_colors_alloc(). This
function is obsolete. See gdk_colormap_free_colors().
</para>
@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.
<!-- ##### FUNCTION gdk_color_white ##### -->
<para>
Return the white color for a given colormap. The resulting
value has already allocated been allocated.
</para>
@colormap:
@color:
@Returns:
@colormap: a #GdkColormap.
@color: the location to store the color.
@Returns: %TRUE if the allocation succeeded.
<!-- ##### FUNCTION gdk_color_black ##### -->
<para>
Return the black color for a given colormap. The resulting
value has already benn allocated.
</para>
@colormap:
@color:
@Returns:
@colormap: a #GdkColormap.
@color: the location to store the color.
@Returns: %TRUE if the allocation succeeded.
<!-- ##### FUNCTION gdk_color_parse ##### -->
<para>
Parse a textual specification of a color and fill in
the <structfield>red</structfield>,
<structfield>green</structfield>, and
<structfield>blue</structfield> fields of a
#GdkColor structure. The color is <emphasis>not</emphasis>
allocated, you must call gdk_colormap_alloc_color() yourself.
The text string can be in any of the forms accepted
by <function>XParseColor</function>; these include
name for a color from <filename>rgb.txt</filename>, such as
<literal>DarkSlateGray</literal>, or a hex specification
such as <literal>305050</literal>.
</para>
@spec:
@color:
@spec: the string specifying the color.
@color: the #GdkColor to fill in
@Returns:
<!-- ##### FUNCTION gdk_color_alloc ##### -->
<para>
Allocate a single color from a colormap.
This function is obsolete. See gdk_colormap_alloc_color().
</para>
@colormap:
@color:
@Returns:
@colormap: a #GdkColormap.
@color: The color to allocate. On return, the
<structfield>pixel</structfield> field will be
filled in.
@Returns: %TRUE if the allocation succeeded.
<!-- ##### FUNCTION gdk_color_change ##### -->
<para>
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.
</para>
@colormap:
@color:
@colormap: a #GdkColormap.
@color: a #GdkColor, with the color to change
in the <structfield>pixel</structfield> field,
and the new value in the remaining fields.
@Returns:
<!-- ##### FUNCTION gdk_color_equal ##### -->
<para>
Compare two colors.
</para>
@colora:
@colorb:
@Returns:
@colora: a #GdkColor.
@colorb: another #GdkColor.
@Returns: %TRUE if the two colors compare equal
<!-- ##### FUNCTION gdk_color_hash ##### -->
<para>
A hash function suitable for using for a hash
table that stores #GdkColor's.
</para>
@colora:
@Returns:
@colora: a #GdkColor.
@Returns: The hash function appled to @colora
<!-- # Unused Parameters # -->
@colorb: NOT USED.

235
docs/reference/gdk/tmpl/drawing.sgml
View File

@ -2,11 +2,22 @@
Drawing Primitives
<!-- ##### SECTION Short_Description ##### -->
functions for drawing points, lines, arcs, and text.
<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
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
<link linkend="gdk-Graphics-Contexts">Graphics Contexts</link> section for
more information.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -113,111 +124,134 @@ Drawing Primitives
<!-- ##### FUNCTION gdk_draw_point ##### -->
<para>
Draws a point, using the foreground color and other attributes of the #GdkGC.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_points ##### -->
<para>
Draws a number of points, using the foreground color and other attributes of
the #GdkGC.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_line ##### -->
<para>
Draws a line, using the foreground color and other attributes of the #GdkGC.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_lines ##### -->
<para>
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().
</para>
@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.
<!-- ##### FUNCTION gdk_draw_segments ##### -->
<para>
Draws a number of unconnected lines.
</para>
@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.
<!-- ##### STRUCT GdkSegment ##### -->
<para>
Specifies the start and end point of a line for use by the gdk_draw_segments()
function.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_rectangle ##### -->
<para>
Draws a rectangular outline or filled rectangle, using the foreground color
and other attributes of the #GdkGC.
</para>
<note>
<para>
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.
</para>
</note>
@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.
<!-- ##### FUNCTION gdk_draw_arc ##### -->
<para>
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.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_polygon ##### -->
<para>
Draws an outlined or filled polygon.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_glyphs ##### -->
@ -259,50 +293,64 @@ Drawing Primitives
<!-- ##### FUNCTION gdk_draw_string ##### -->
<para>
Draws a string of characters in the given font or fontset.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_text ##### -->
<para>
Draws a number of characters in the given font or fontset.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_text_wc ##### -->
<para>
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.
</para>
@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.
<!-- ##### MACRO gdk_draw_pixmap ##### -->
<para>
Draws a pixmap, or a part of a pixmap, onto another drawable.
</para>
<!-- # Unused Parameters # -->
@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.
<!-- ##### FUNCTION gdk_draw_drawable ##### -->
@ -323,18 +371,21 @@ Drawing Primitives
<!-- ##### FUNCTION gdk_draw_image ##### -->
<para>
Draws a #GdkImage onto a drawable.
The depth of the #GdkImage must match the depth of the #GdkDrawable.
</para>
@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.
<!-- ##### FUNCTION gdk_drawable_get_image ##### -->

576
docs/reference/gdk/tmpl/fonts.sgml
View File

@ -2,11 +2,260 @@
Fonts
<!-- ##### SECTION Short_Description ##### -->
loading and manipulating fonts
<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
Fonts in X are specified by a
<firstterm>X Logical Font Description</firstterm>.
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:
<programlisting>
"-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1"
</programlisting>
</para>
<para>
The fields in the XLFD are:
<informaltable pgwide=1 frame="none">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>Foundry</entry>
<entry>the company or organization where the font originated.</entry>
</row>
<row>
<entry>Family</entry>
<entry>the font family (a group of related font designs).</entry>
</row>
<row>
<entry>Weight</entry>
<entry>A name for the font's typographic weight
For example, 'bold' or 'medium').</entry>
</row>
<row>
<entry>Slant</entry>
<entry>The slant of the font. Common values are 'R' for Roman,
'I' for italoc, and 'O' for oblique.</entry>
</row>
<row>
<entry>Set Width</entry>
<entry>A name for the width of the font. For example,
'normal' or 'condensed'.</entry>
</row>
<row>
<entry>Add Style</entry>
<entry>Additional information to distinguish a font from
other fonts of the same family.</entry>
</row>
<row>
<entry>Pixel Size</entry>
<entry>The body size of the font in pixels.</entry>
</row>
<row>
<entry>Point Size</entry>
<entry>The body size of the font in 10ths of a point.
(A <firstterm>point</firstterm> is 1/72.27 inch) </entry>
</row>
<row>
<entry>Resolution X</entry>
<entry>The horizontal resolution that the font was designed for.</entry>
</row>
<row>
<entry>Resolution Y</entry>
<entry>The vertical resolution that the font was designed for .</entry>
</row>
<row>
<entry>Spacing</entry>
<entry>The type of spacing for the font - can be 'p' for proportional,
'm' for monospaced or 'c' for charcell.</entry>
</row>
<row>
<entry>Average Width</entry>
<entry>The average width of a glyph in the font. For monospaced
and charcell fonts, all glyphs in the font have this width</entry>
</row>
<row>
<entry>Charset Registry</entry>
<entry>The registration authority that owns the encoding for
the font. Together with the Charset Encoding field, this
defines the character set for the font.</entry>
</row>
<row>
<entry>Charset Encoding</entry>
<entry>An identifier for the particular character set encoding.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
<para>
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
<programlisting>
"-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1"
</programlisting>
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.
</para>
<para>
A <firstterm>fontset</firstterm> 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.
</para>
<para>
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.
</para>
<para>
The functions for determining the metrics of a string
come in several varieties that can take a number
of forms of string input:
<variablelist>
<varlistentry>
<term>8-bit string</term>
<listitem><para>
When using functions like gdk_string_width() that
take a <type>gchar *</type>, if the font is of type
%GDK_FONT_FONT and is an 8-bit font, then each
<type>gchar</type> indexes the glyphs in the font directly.
</para></listitem>
</varlistentry>
<varlistentry>
<term>16-bit string</term>
<listitem><para>
For functions taking a <type>gchar *</type>, if the
font is of type %GDK_FONT_FONT, and is a 16-bit
font, then the <type>gchar *</type> argument is
interpreted as a <type>guint16 *</type> cast to
a <type>gchar *</type> and each <type>guint16</type>
indexes the glyphs in the font directly.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Multibyte string</term>
<listitem><para>
For functions taking a <type>gchar *</type>, if the
font is of type %GDK_FONT_FONTSET, then the input
string is interpreted as a <firstterm>multibyte</firstterm>
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.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Wide character string</term>
<listitem><para>
For a number of the text-measuring functions, GTK+
provides a variant (such as gdk_text_width_wc()) which
takes a <type>GdkWChar *</type> instead of a
<type>gchar *</type>. 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.)
</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
GDK provides functions to determine a number of different
measurements (metrics) for a given string. (Need diagram
here).
<variablelist>
<varlistentry>
<term>ascent</term>
<listitem><para>
The vertical distance from the origin of the drawing
opereration to the top of the drawn character.
</para></listitem>
</varlistentry>
<varlistentry>
<term>descent</term>
<listitem><para>
The vertical distance from the origin of the drawing
opereration to the bottom of the drawn character.
</para></listitem>
</varlistentry>
<varlistentry>
<term>left bearing</term>
<listitem><para>
The horizontal distance from the origin of the drawing
operation to the left-most part of the drawn character.
</para></listitem>
</varlistentry>
<varlistentry>
<term>right bearing</term>
<listitem><para>
The horizontal distance from the origin of the drawing
operation to the right-most part of the drawn character.
</para></listitem>
</varlistentry>
<varlistentry>
<term>width bearing</term>
<listitem><para>
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.
</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,7 +265,34 @@ Fonts
<!-- ##### STRUCT GdkFont ##### -->
<para>
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()
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry><structfield>type</structfield></entry>
<entry>a value of type #GdkFontType which indicates
whether this font is a single font or a fontset.</entry>
</row>
<row>
<entry><structfield>ascent</structfield></entry>
<entry>the maximum distance that the font, when drawn,
ascends above the baseline.</entry>
</row>
<row>
<entry><structfield>descent</structfield></entry>
<entry>the maximum distance that the font, when drawn,
descends below the baseline.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@type:
@ -25,7 +301,24 @@ Fonts
<!-- ##### ENUM GdkFontType ##### -->
<para>
Indicates the type of a font. The possible values
are currently:
<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>GDK_FONT_FONT</entry>
<entry>the font is a single font.</entry>
</row>
<row>
<entry>GDK_FONT_FONT</entry>
<entry>the font is a fontset.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GDK_FONT_FONT:
@ -33,20 +326,34 @@ Fonts
<!-- ##### FUNCTION gdk_font_load ##### -->
<para>
Loads a font.
</para>
@font_name:
@Returns:
<para>
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.
</para>
@font_name: a XLFD describing the font to load.
@Returns: a #GdkFont, or NULL if the font could not be loaded.
<!-- ##### FUNCTION gdk_fontset_load ##### -->
<para>
Loads a fontset.
</para>
<para>
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.
</para>
@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.
<!-- ##### FUNCTION gdk_font_from_description ##### -->
@ -60,196 +367,225 @@ Fonts
<!-- ##### FUNCTION gdk_font_ref ##### -->
<para>
Increase the reference count of a count by one.
</para>
@font:
@Returns:
@font: a #GdkFont
@Returns: @font
<!-- ##### FUNCTION gdk_font_unref ##### -->
<para>
Decrease the reference count of a count by one.
If the result is zero, destroys the font.
</para>
@font:
@font: a #GdkFont
<!-- ##### FUNCTION gdk_font_id ##### -->
<para>
Returns the X Font ID for the given font.
</para>
@font:
@Returns:
@font: a #GdkFont.
@Returns: the numeric X Font ID
<!-- ##### FUNCTION gdk_font_equal ##### -->
<para>
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.
</para>
@fonta:
@fontb:
@Returns:
@fonta: a #GdkFont.
@fontb: another #GdkFont.
@Returns: %TRUE if the fonts are equal.
<!-- ##### FUNCTION gdk_string_extents ##### -->
<para>
Returns the metrics of a NULL-terminated string.
</para>
@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.
<!-- ##### FUNCTION gdk_text_extents ##### -->
<para>
Returns the metrics of a string.
</para>
@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.
<!-- ##### FUNCTION gdk_text_extents_wc ##### -->
<para>
Returns the metrics of a string of wide characters.
</para>
@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.
<!-- ##### FUNCTION gdk_string_width ##### -->
<para>
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)
</para>
@font:
@string:
@Returns:
@font: a #GdkFont
@string: the NULL-terminated string to measure
@Returns: the width of the string in pixels.
<!-- ##### FUNCTION gdk_text_width ##### -->
<para>
Determine the width of a given string.
</para>
@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.
<!-- ##### FUNCTION gdk_text_width_wc ##### -->
<para>
Determine the width of a given wide-character string.
</para>
@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.
<!-- ##### FUNCTION gdk_char_width ##### -->
<para>
Determine the width of a given character.
</para>
@font:
@character:
@Returns:
@font: a #GdkFont
@character: the character to measure.
@Returns: the width of the character in pixels.
<!-- ##### FUNCTION gdk_char_width_wc ##### -->
<para>
Determine the width of a given wide character. (Encoded
in the wide-character encoding of the current locale).
</para>
@font:
@character:
@Returns:
@font: a #GdkFont
@character: the character to measure.
@Returns: the width of the character in pixels.
<!-- ##### FUNCTION gdk_string_measure ##### -->
<para>
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().
</para>
@font:
@string:
@Returns:
@font: a #GdkFont
@string: the NULL-terminated string to measure.
@Returns: the right bearing of the string in pixels.
<!-- ##### FUNCTION gdk_text_measure ##### -->
<para>
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().
</para>
@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.
<!-- ##### FUNCTION gdk_char_measure ##### -->
<para>
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.
</para>
@font:
@character:
@Returns:
@font: a #GdkFont
@character: the character to measure.
@Returns: the right bearing of the character in pixels.
<!-- ##### FUNCTION gdk_string_height ##### -->
<para>
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().
</para>
@font:
@string:
@Returns:
@font: a #GdkFont
@string: the NULL-terminated string to measure.
@Returns: the height of the string in pixels.
<!-- ##### FUNCTION gdk_text_height ##### -->
<para>
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().
</para>
@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.
<!-- ##### FUNCTION gdk_char_height ##### -->
<para>
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().
</para>
@font:
@character:
@Returns:
@font: a #GdkFont
@character: the character to measure.
@Returns: the height of the character in pixels.
<!-- ##### FUNCTION gdk_font_full_name_get ##### -->
@ -271,27 +607,63 @@ Fonts
<!-- ##### TYPEDEF GdkWChar ##### -->
<para>
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).
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
See the 'Extended Characters' section of the GNU C Library Reference Manual
for more detailed information on wide and multi-byte characters.
</para>
<!-- ##### FUNCTION gdk_wcstombs ##### -->
<para>
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').
</para>
@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.
<!-- ##### FUNCTION gdk_mbstowcs ##### -->
<para>
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').
</para>
@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.

445
docs/reference/gdk/tmpl/gcs.sgml
View File

@ -2,11 +2,27 @@
Graphics Contexts
<!-- ##### SECTION Short_Description ##### -->
objects to encapsulate drawing properties.
<!-- ##### SECTION Long_Description ##### -->
<para>
All drawing operations in GDK take a
<firstterm>graphics context</firstterm> (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.
</para>
<para>
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.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -16,7 +32,9 @@ Graphics Contexts
<!-- ##### STRUCT GdkGC ##### -->
<para>
The #GdkGC structure represents a graphics context.
It is an opaque structure with no user-visible
elements.
</para>
@parent_instance:
@ -34,7 +52,104 @@ Graphics Contexts
<!-- ##### STRUCT GdkGCValues ##### -->
<para>
The #GdkGCValues structure holds a set of values used
to create or modify a graphics context.
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>#GdkColor foreground;</entry>
<entry>the foreground color.</entry>
</row>
<row>
<entry>#GdkColor background;</entry>
<entry>the background color.</entry>
</row>
<row>
<entry>#GdkFont *font;</entry>
<entry>the default font..</entry>
</row>
<row>
<entry>#GdkFunction function;</entry>
<entry>the bitwise operation used when drawing.</entry>
</row>
<row>
<entry>#GdkFill fill;</entry>
<entry>the fill style.</entry>
</row>
<row>
<entry>#GdkPixmap *tile;</entry>
<entry>the tile pixmap.</entry>
</row>
<row>
<entry>#GdkPixmap *stipple;</entry>
<entry>the stipple bitmap.</entry>
</row>
<row>
<entry>#GdkPixmap *clip_mask;</entry>
<entry>the clip mask bitmap.</entry>
</row>
<row>
<entry>#GdkSubwindowMode subwindow_mode;</entry>
<entry>the subwindow mode.</entry>
</row>
<row>
<entry>#gint ts_x_origin;</entry>
<entry>the x origin of the tile or stipple.</entry>
</row>
<row>
<entry>#gint ts_y_origin;</entry>
<entry>the y origin of the tile or stipple.</entry>
</row>
<row>
<entry>#gint clip_x_origin;</entry>
<entry>the x origin of the clip mask.</entry>
</row>
<row>
<entry>#gint clip_y_origin;</entry>
<entry>the y origin of the clip mask.</entry>
</row>
<row>
<entry>#gint graphics_exposures;</entry>
<entry>whether graphics exposures are enabled.</entry>
</row>
<row>
<entry>#gint line_width;</entry>
<entry>the line width</entry>
</row>
<row>
<entry>#GdkLineStyle line_style;</entry>
<entry>the way dashed lines are drawn</entry>
</row>
<row>
<entry>#GdkCapStyle cap_style;</entry>
<entry>the way the ends of lines are drawn</entry>
</row>
<row>
<entry>#GdkJoinStyle join_style;</entry>
<entry>the way joins between lines are drawn</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@foreground:
@ -58,7 +173,8 @@ Graphics Contexts
<!-- ##### ENUM GdkGCValuesMask ##### -->
<para>
A set of bit flags used to indicate which fields
#GdkGCValues structure are set.
</para>
@GDK_GC_FOREGROUND:
@ -82,7 +198,12 @@ Graphics Contexts
<!-- ##### ENUM GdkFunction ##### -->
<para>
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.
</para>
@GDK_COPY:
@ -104,46 +225,58 @@ Graphics Contexts
<!-- ##### FUNCTION gdk_gc_new ##### -->
<para>
Create a new graphics context with default values.
</para>
@drawable:
@Returns:
@Returns: the new graphics context.
<!-- # Unused Parameters # -->
@window: a #GdkDrawable. The created GC must always be used
with drawables of the same depth as this one.
<!-- ##### FUNCTION gdk_gc_new_with_values ##### -->
<para>
Create a new GC with the given initial values.
</para>
@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.
<!-- # Unused Parameters # -->
@window: a #GdkDrawable. The created GC must always be used
with drawables of the same depth as this one.
<!-- ##### FUNCTION gdk_gc_ref ##### -->
<para>
Increase the reference count on a graphics context.
</para>
@gc:
@Returns:
@gc: a #GdkGC.
@Returns: @gc.
<!-- ##### FUNCTION gdk_gc_unref ##### -->
<para>
Decrease the reference count on a graphics context. If
the resulting reference count is zero, the graphics
context will be destroyed.
</para>
@gc:
@gc: a #GdkGC.
<!-- ##### MACRO gdk_gc_destroy ##### -->
<para>
Identical to gdk_gc_unref(). This function is obsolete
and should not be used.
</para>
<!-- # Unused Parameters # -->
@gc: a #GdkGC.
<!-- ##### FUNCTION gdk_gc_set_values ##### -->
@ -158,29 +291,29 @@ Graphics Contexts
<!-- ##### FUNCTION gdk_gc_get_values ##### -->
<para>
Retrieves the current values from a graphics context.
</para>
@gc:
@values:
@gc: a #GdkGC.
@values: the #GdkGCValues structure in which to store the results.
<!-- ##### FUNCTION gdk_gc_set_foreground ##### -->
<para>
Sets the foreground color for a graphics context.
</para>
@gc:
@color:
@gc: a #GdkGC.
@color: the new foreground color.
<!-- ##### FUNCTION gdk_gc_set_background ##### -->
<para>
Sets the background color for a graphics context.
</para>
@gc:
@color:
@gc: a #GdkGC.
@color: the new background color.
<!-- ##### FUNCTION gdk_gc_set_rgb_fg_color ##### -->
@ -203,34 +336,71 @@ Graphics Contexts
<!-- ##### FUNCTION gdk_gc_set_font ##### -->
<para>
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.)
</para>
@gc:
@font:
@gc: a #GdkGC.
@font: the new font.
<!-- ##### FUNCTION gdk_gc_set_function ##### -->
<para>
Determines how the current pixel values and the
pixel values being drawn are combined to produce
the final pixel values.
</para>
@gc:
@gc: a #GdkGC.
@function:
<!-- ##### FUNCTION gdk_gc_set_fill ##### -->
<para>
Set the fill mode for a graphics context.
</para>
@gc:
@fill:
@gc: a #GdkGC.
@fill: the new fill mode.
<!-- ##### ENUM GdkFill ##### -->
<para>
Determines how primitives are drawn.
<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>GDK_SOLID</entry>
<entry>draw with the foreground color.</entry>
</row>
<row>
<entry>GDK_TILED</entry>
<entry>draw with a tiled pixmap.</entry>
</row>
<row>
<entry>GDK_STIPPLED</entry>
<entry>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.</entry>
</row>
<row>
<entry>GDK_OPAQUE_STIPPLED</entry>
<entry>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.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GDK_SOLID:
@ -240,81 +410,116 @@ Graphics Contexts
<!-- ##### FUNCTION gdk_gc_set_tile ##### -->
<para>
Set a tile pixmap for a graphics context.
This will only be used if the fill mode
is %GDK_TILED.
</para>
@gc:
@tile:
@gc: a #GdkGC.
@tile: the new tile pixmap.
<!-- ##### FUNCTION gdk_gc_set_stipple ##### -->
<para>
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.
</para>
@gc:
@stipple:
@gc: a #GdkGC.
@stipple: the new stipple bitmap.
<!-- ##### FUNCTION gdk_gc_set_ts_origin ##### -->
<para>
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.
</para>
@gc:
@x:
@y:
@gc: a #GdkGC.
@x: the x-coordinate of the origin.
@y: the y-coordinate of the origin.
<!-- ##### FUNCTION gdk_gc_set_clip_origin ##### -->
<para>
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.
</para>
@gc:
@x:
@y:
@gc: a #GdkGC.
@x: the x-coordinate of the origin.
@y: the y-coordinate of the origin.
<!-- ##### FUNCTION gdk_gc_set_clip_mask ##### -->
<para>
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()).
</para>
@gc:
@mask:
@gc: the #GdkGC.
@mask: a bitmap.
<!-- ##### FUNCTION gdk_gc_set_clip_rectangle ##### -->
<para>
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()).
</para>
@gc:
@rectangle:
@gc: a #GdkGC.
@rectangle: the rectangle to clip to.
<!-- ##### FUNCTION gdk_gc_set_clip_region ##### -->
<para>
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()).
</para>
@gc:
@region:
@gc: a #GdkGC.
@region: the #GdkRegion.
<!-- ##### FUNCTION gdk_gc_set_subwindow ##### -->
<para>
Sets how drawing with this GC on a window will affect child
windows of that window.
</para>
@gc:
@mode:
@gc: a #GdkGC.
@mode: the subwindow mode.
<!-- ##### ENUM GdkSubwindowMode ##### -->
<para>
Determines how drawing onto a window will affect child
windows of that window.
<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="3*"><colspec colwidth="7*">
<tbody>
<row>
<entry>GDK_CLIP_BY_CHILDREN</entry>
<entry>only draw onto the window itself.</entry>
</row>
<row>
<entry>GDK_INCLUDE_INFERIORS</entry>
<entry>Draw onto the window and child windows.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GDK_CLIP_BY_CHILDREN:
@ -322,28 +527,57 @@ Graphics Contexts
<!-- ##### FUNCTION gdk_gc_set_exposures ##### -->
<para>
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()).
</para>
@gc:
@exposures:
@gc: a #GdkGC.
@exposures: if %TRUE, exposure events will be generated.
<!-- ##### FUNCTION gdk_gc_set_line_attributes ##### -->
<para>
Sets various attributes of how lines are drawn. See
the corresponding members of GdkGCValues for full
explanations of the arguments.
</para>
@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.
<!-- ##### ENUM GdkLineStyle ##### -->
<para>
Determines how lines are drawn.
<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>GDK_LINE_SOLID</entry>
<entry>lines are drawn solid.</entry>
</row>
<row>
<entry>GDK_LINE_ON_OFF_DASH</entry>
<entry>even segments are drawn; odd segments are not drawn.</entry>
</row>
<row>
<entry>GDK_LINE_DOUBLE_DASH</entry>
<entry>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.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GDK_LINE_SOLID:
@ -352,7 +586,38 @@ Graphics Contexts
<!-- ##### ENUM GdkCapStyle ##### -->
<para>
Determines how the end of lines are drawn.
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>GDK_CAP_NOT_LAST</entry>
<entry>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.</entry>
</row>
<row>
<entry>GDK_CAP_BUTT</entry>
<entry>the ends of the lines are drawn squared off and extending
to the coordinates of the end point.</entry>
</row>
<row>
<entry>GDK_CAP_ROUND</entry>
<entry>the ends of the lines are drawn as semicircles with the
diameter equal to the line width and centered at the
end point.</entry>
</row>
<row>
<entry>GDK_CAP_PROJECTING</entry>
<entry>the ends of the lines are drawn squared off and extending
half the width of the line beyond the end point.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GDK_CAP_NOT_LAST:
@ -362,7 +627,29 @@ Graphics Contexts
<!-- ##### ENUM GdkJoinStyle ##### -->
<para>
Determines how the joins between segments of a polygon are drawn.
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>GDK_JOIN_MITER</entry>
<entry>the sides of each line are extended to meet at an angle.</entry>
</row>
<row>
<entry>GDK_JOIN_ROUND</entry>
<entry>the sides of the two lines are joined by a circular arc.</entry>
</row>
<row>
<entry>GDK_JOIN_BEVEL</entry>
<entry>the sides of the two lines are joined by a straight line which
makes an equal angle with each line.</entry>
</row>
</tbody></tgroup></informaltable>
</para>
@GDK_JOIN_MITER:
@ -371,22 +658,28 @@ Graphics Contexts
<!-- ##### FUNCTION gdk_gc_set_dashes ##### -->
<para>
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)
</para>
@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.
<!-- ##### FUNCTION gdk_gc_copy ##### -->
<para>
Copy the set of values from one graphics context
onto another graphics context.
</para>
@dst_gc:
@src_gc:
@dst_gc: the destination graphics context.
@src_gc: the source graphics context.
<!-- ##### FUNCTION gdk_gc_set_colormap ##### -->

1734
docs/reference/gdk/tmpl/gdk-unused.sgml
View File

File diff suppressed because it is too large Load Diff

144
docs/reference/gdk/tmpl/images.sgml
View File

@ -2,79 +2,131 @@
Images
<!-- ##### SECTION Short_Description ##### -->
an area for bit-mapped graphics stored on the X Windows client.
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GdkImage type represents an area for drawing graphics.
It has now been superceded to a large extent by the much more flexible
<link linkend="gdk-GdkRGB">GdkRGB</link> functions.
</para>
<para>
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().
</para>
<para>
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.
</para>
<para>
To draw a #GdkImage in a #GdkWindow or #GdkPixmap use gdk_draw_image().
</para>
<para>
To destroy a #GdkImage use gdk_image_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term><link linkend="gdk-Bitmaps-and-Pixmaps">Bitmaps and Pixmaps</link></term>
<listitem><para>
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 <link linkend="gdk-Drawing-Primitives">Drawing Primitives</link> can be
used to draw on them. Their main disadvantage is that manipulating individual
pixels can be very slow.
</para></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="gdk-GdkRGB">GdkRGB</link></term>
<listitem><para>
Built on top of #GdkImage, this provides much more functionality,
including the dithering of colors to produce better output on low-color
displays.
</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### STRUCT GdkImage ##### -->
<para>
The #GdkImage struct contains information on the image and the pixel data.
</para>
@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:
<!-- ##### FUNCTION gdk_image_new ##### -->
<para>
Creates a new #GdkImage.
</para>
@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.
<!-- ##### ENUM GdkImageType ##### -->
<para>
Specifies the type of a #GdkImage.
</para>
@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.
<!-- ##### FUNCTION gdk_image_new_bitmap ##### -->
<para>
Creates a new #GdkImage with a depth of 1 from the given data.
</para>
@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.
<!-- ##### FUNCTION gdk_image_get ##### -->
<para>
Gets part of a #GdkWindow and stores it in a new #GdkImage.
</para>
@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.
<!-- # Unused Parameters # -->
@window: the #GdkWindow to copy from.
<!-- ##### FUNCTION gdk_image_ref ##### -->
@ -96,30 +148,32 @@ Images
<!-- ##### MACRO gdk_image_destroy ##### -->
<para>
Destroys a #GdkImage, freeing any resources allocated for it.
</para>
<!-- # Unused Parameters # -->
@image: a #GdkImage.
<!-- ##### FUNCTION gdk_image_put_pixel ##### -->
<para>
Sets a pixel in a #GdkImage to a given pixel value.
</para>
@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.
<!-- ##### FUNCTION gdk_image_get_pixel ##### -->
<para>
Gets a pixel value at a specified position in a #GdkImage.
</para>
@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.

38
docs/reference/gdk/tmpl/regions.sgml
View File

@ -35,41 +35,45 @@ It can be intersected to regions by using gdk_region_spans_intersect_foreach().
<!-- ##### STRUCT GdkPoint ##### -->
<para>
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.
</para>
@x:
@y:
@x: the x coordinate of the point.
@y: the y coordinate of the point.
<!-- ##### STRUCT GdkRectangle ##### -->
<para>
Defines the position and size of a rectangle.
</para>
@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.
<!-- ##### FUNCTION gdk_rectangle_intersect ##### -->
<para>
Calculates the intersection of two rectangles.
</para>
@src1:
@src2:
@dest:
@Returns:
@src1: a #GdkRectangle.
@src2: a #GdkRectangle.
@dest: the intersection of @src1 and @src2.
@Returns: TRUE if the rectangles intersect.
<!-- ##### FUNCTION gdk_rectangle_union ##### -->
<para>
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.
</para>
@src1:
@src2:
@dest:
@src1: a #GdkRectangle.
@src2: a #GdkRectangle.
@dest: the union of @src1 and @src2.
<!-- ##### STRUCT GdkRegion ##### -->

403
docs/reference/gdk/tmpl/rgb.sgml
View File

@ -2,106 +2,294 @@
GdkRGB
<!-- ##### SECTION Short_Description ##### -->
displays RGB images (as well as grayscale and colormapped) to
the native window.
<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
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.
</para>
<para>
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:
</para>
<informalexample>
<programlisting>
gdk_rgb_init ();
gtk_widget_set_default_colormap (gdk_rgb_get_cmap ());
gtk_widget_set_default_visual (gdk_rgb_get_visual ());
</programlisting>
</informalexample>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<example>
<title>A simple example program using GdkRGB.</title>
<programlisting>
#include &lt;gtk/gtk.h&gt;
#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 (&amp;argc, &amp;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);
}
</programlisting>
</example>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GdkColor</term>
<listitem><para>The underlying Gdk mechanism for allocating
colors.</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### FUNCTION gdk_rgb_init ##### -->
<para>
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.
</para>
<para>
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.
</para>
<!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
<para>
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.
</para>
@drawable:
@gc:
@x:
@y:
@width:
@height:
@dith:
@rgb_buf:
@rowstride:
<para>
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.
</para>
<para>
In general, for 0 &lt;= i &lt; @width and 0 &lt;= j &lt; 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].
</para>
@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.
<!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### -->
<para>
Draws an RGB image in the drawable, with an adjustment for dither alignment.
</para>
@drawable:
@gc:
@x:
@y:
@width:
@height:
@dith:
@rgb_buf:
@rowstride:
@xdith:
@ydith:
<para>
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.
</para>
<para>
Setting the dither alignment correctly allows updating of small parts
of the screen while avoiding visible "seams" between the different
dither textures.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_indexed_image ##### -->
<para>
Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
actual colors to the color indices.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_gray_image ##### -->
<para>
Draws a grayscale image in the drawable.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_rgb_32_image ##### -->
<para>
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.
</para>
@drawable:
@gc:
@x:
@y:
@width:
@height:
@dith:
@buf:
@rowstride:
<para>
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.
</para>
@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.
<!-- ##### FUNCTION gdk_draw_rgb_32_image_dithalign ##### -->
@ -125,6 +313,36 @@ GdkRGB
<!-- ##### ENUM GdkRgbDither ##### -->
<para>
Selects whether or not GdkRgb applies dithering
to the image on display. There are three values:
</para>
<itemizedlist>
<listitem>
<para>
%GDK_RGB_DITHER_NONE: Never use dithering.
</para>
</listitem>
<listitem>
<para>
%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
only.
</para>
</listitem>
<listitem>
<para>
%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
</para>
</listitem>
</itemizedlist>
<para>
Since GdkRgb currently only handles images with 8 bits per component,
dithering on 24 bit per pixel displays is a moot point.
</para>
@GDK_RGB_DITHER_NONE:
@ -133,25 +351,29 @@ GdkRGB
<!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
<para>
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.
</para>
@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
<!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
<para>
Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
</para>
@cmap:
@cmap: The #GdkRgbCmap to free.
<!-- ##### STRUCT GdkRgbCmap ##### -->
<para>
A private data structure which maps color indices to actual RGB
colors. This is used only for gdk_draw_indexed_image().
</para>
@colors:
@ -159,29 +381,33 @@ GdkRGB
<!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
<para>
Sets the foreground color in @gc to the specified color (or the
closest approximation, in the case of limited visuals).
</para>
@gc:
@rgb:
@gc: The #GdkGC to modify.
@rgb: The color, represented as a 0xRRGGBB integer value.
<!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
<para>
Sets the background color in @gc to the specified color (or the
closest approximation, in the case of limited visuals).
</para>
@gc:
@rgb:
@gc: The #GdkGC to modify.
@rgb: The color, represented as a 0xRRGGBB integer value.
<!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
<para>
Finds the X pixel closest in color to the @rgb color specified. This
value may be used to set the <structfield>pixel</structfield> field of
a #GdkColor struct.
</para>
@rgb:
@Returns:
@rgb: The color, represented as a 0xRRGGBB integer value.
@Returns: The X pixel value.
<!-- ##### FUNCTION gdk_rgb_find_color ##### -->
@ -195,26 +421,38 @@ GdkRGB
<!-- ##### FUNCTION gdk_rgb_set_install ##### -->
<para>
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.
</para>
@install:
<para>
A private colormap has more colors, leading to better quality display,
but also leads to the dreaded "colormap flashing" effect.
</para>
@install: TRUE to set install mode.
<!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
<para>
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.
</para>
@min_colors:
@min_colors: The minimum number of colors accepted.
<!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
<para>
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.
</para>
@Returns:
@Returns: The #GdkVisual chosen by GdkRgb.
<!-- ##### FUNCTION gdk_rgb_get_colormap ##### -->
@ -227,24 +465,29 @@ GdkRGB
<!-- ##### MACRO gdk_rgb_get_cmap ##### -->
<para>
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.
</para>
@Returns: The #GdkColormap set by GdkRgb.
<!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
<para>
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.
</para>
@Returns:
@Returns: TRUE if the visual is ditherable.
<!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
<para>
Sets the "verbose" flag. This is generally only useful for debugging.
</para>
@verbose:
@verbose: TRUE if verbose messages are desired.

10
docs/reference/gdk/tmpl/windows.sgml
View File

@ -871,6 +871,16 @@ Windows
@decorations:
<!-- ##### FUNCTION gdk_window_get_decorations ##### -->
<para>
</para>
@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.
<!-- ##### ENUM GdkWMDecoration ##### -->
<para>

126
docs/reference/gtk/Makefile.am
View File

@ -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

6518
docs/reference/gtk/tmpl/gtk-unused.sgml
View File

File diff suppressed because it is too large Load Diff

33
docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml
View File

@ -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:
<!-- ##### ENUM GtkTreeViewColumnSizing ##### -->
<para>
@ -223,15 +227,6 @@ GtkTreeViewColumn
@title:
<!-- ##### FUNCTION gtk_tree_view_column_get_title ##### -->
<para>
</para>
@tree_column:
@Returns:
<!-- ##### FUNCTION gtk_tree_view_column_set_clickable ##### -->
<para>
@ -259,24 +254,6 @@ GtkTreeViewColumn
@Returns:
<!-- ##### FUNCTION gtk_tree_view_column_set_justification ##### -->
<para>
</para>
@tree_column:
@justification:
<!-- ##### FUNCTION gtk_tree_view_column_get_justification ##### -->
<para>
</para>
@tree_column:
@Returns:
<!-- ##### FUNCTION gtk_tree_view_column_clicked ##### -->
<para>