diff options
author | Owen Taylor <otaylor@redhat.com> | 2000-04-05 00:57:10 +0000 |
---|---|---|
committer | Owen Taylor <otaylor@src.gnome.org> | 2000-04-05 00:57:10 +0000 |
commit | 184fac9cb3f0146684c0f141ef5d2e480859be06 (patch) | |
tree | bcc26ac9e134dce03a1480b359671b946cbb909e /docs | |
parent | 613302136667231bcefd772b419369516eb3bf45 (diff) | |
download | pango-184fac9cb3f0146684c0f141ef5d2e480859be06.tar.gz |
Doc updates.
Tue Apr 4 20:56:29 2000 Owen Taylor <otaylor@redhat.com>
* docs/tmpl/* docs/Makefile.am docs/pango-sections.txt
pango/pango-attributes.c pango/pangox.c: Doc updates.
Diffstat (limited to 'docs')
-rw-r--r-- | docs/Makefile.am | 4 | ||||
-rw-r--r-- | docs/pango-sections.txt | 20 | ||||
-rw-r--r-- | docs/tmpl/fonts.sgml | 40 | ||||
-rw-r--r-- | docs/tmpl/glyphs.sgml | 11 | ||||
-rw-r--r-- | docs/tmpl/layout.sgml | 28 | ||||
-rw-r--r-- | docs/tmpl/main.sgml | 89 | ||||
-rw-r--r-- | docs/tmpl/pango-unused.sgml | 282 | ||||
-rw-r--r-- | docs/tmpl/text-attributes.sgml | 18 | ||||
-rw-r--r-- | docs/tmpl/x-rendering.sgml | 36 |
9 files changed, 361 insertions, 167 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am index 8144ba54..5a3e6d4c 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -8,8 +8,8 @@ DOC_MODULE=pango # The top-level SGML file. DOC_MAIN_SGML_FILE=pango-docs.sgml -INCLUDE_DIR=../libpango -SOURCE_DIR=../libpango +INCLUDE_DIR=../pango +SOURCE_DIR=../pango scan: gtkdoc-scan --module=$(DOC_MODULE) $(INCLUDE_DIR)/pango*.h diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt index 9c606fa5..d9ade841 100644 --- a/docs/pango-sections.txt +++ b/docs/pango-sections.txt @@ -2,17 +2,23 @@ <TITLE>Text Processing</TITLE> <FILE>main</FILE> <SUBSECTION> -pango_itemize PangoContext PangoItem PangoAnalysis PangoLangRange PangoDirection +<SUBSECTION> +pango_itemize +pango_item_free +pango_item_copy +pango_item_new pango_reorder_items <SUBSECTION> pango_context_new pango_context_ref pango_context_unref +pango_context_get_data +pango_context_set_data pango_context_add_font_map pango_context_get_font_description pango_context_set_font_description @@ -34,6 +40,7 @@ pango_justify <SECTION> <TITLE>Glyph Storage</TITLE> <FILE>glyphs</FILE> +PANGO_SCALE PangoRectangle PANGO_ASCENT PANGO_DESCENT @@ -86,6 +93,7 @@ pango_font_description_to_string <SUBSECTION> PangoFont PangoFontClass +PangoFontMetrics pango_font_init pango_font_ref pango_font_unref @@ -93,6 +101,7 @@ pango_font_find_shaper pango_font_describe pango_font_get_coverage pango_font_get_glyph_extents +pango_font_get_metrics pango_font_get_data pango_font_set_data <SUBSECTION> @@ -132,6 +141,7 @@ pango_attr_foreground_new pango_attr_background_new pango_attr_strikethrough_new pango_attr_underline_new +PangoUnderline pango_attr_rise_new <SUBSECTION> PangoAttrList @@ -157,6 +167,9 @@ pango_layout_new pango_layout_ref pango_layout_unref +pango_layout_get_context +pango_layout_context_changed + pango_layout_set_text pango_layout_set_attributes pango_layout_set_width @@ -169,6 +182,8 @@ pango_layout_set_alignment pango_layout_get_alignment PangoAlignment +pango_layout_get_log_attrs + pango_layout_xy_to_index pango_layout_index_to_pos @@ -209,6 +224,9 @@ script_engine_unload <FILE>x-rendering</FILE> PANGO_RENDER_TYPE_X pango_x_get_context +pango_x_context_set_funcs +PangoGetGCFunc +PangoFreeGCFunc pango_x_render pango_x_render_layout_line pango_x_render_layout diff --git a/docs/tmpl/fonts.sgml b/docs/tmpl/fonts.sgml index 0f20836b..dd6ce068 100644 --- a/docs/tmpl/fonts.sgml +++ b/docs/tmpl/fonts.sgml @@ -155,10 +155,10 @@ which the implementation fills in: <!-- ##### STRUCT PangoFontClass ##### --> <para> -The PangoFontClass structure contains the virtual +The #PangoFontClass structure contains the virtual functions for an implementation of a a PangoFont. -It contains the following member: +It contains the following members: <informaltable pgwide=1 frame="none" role="struct"> <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*"> @@ -177,8 +177,27 @@ It contains the following member: @get_coverage: A function to get a coverage map for the font. See pango_font_get_coverage(). @find_shaper: A function to find the shaper for a particular character - point. See pango_font_find_shaper. -@get_glyph_extents: + point. See pango_font_find_shaper(). +@get_glyph_extents: A function called to find out the logical and ink + extents of a glyph within the fonts. See + pango_font_get_glyph_extents(). +@get_metrics: A function called to find the overall metric information + for the font or the metric information appropriate to + a particular language. See pango_font_get_metrics(). + +<!-- ##### STRUCT PangoFontMetrics ##### --> +<para> +The #PangoFontMetrics structure represents the overall metrics for +a font. It contains the following members: +</para> + +@ascent: the logical extent of the font upwards from the baseline. + The spacing between lines of text should be calculated + as @ascent + @descent. Individual characters may have + extents exceeding this value. +@descent: the logical extent of the font beneath the baseline. + as @ascent + @descent. Individual characters may have + extents exceeding this value. <!-- ##### FUNCTION pango_font_init ##### --> <para> @@ -247,6 +266,16 @@ It contains the following member: @logical_rect: +<!-- ##### FUNCTION pango_font_get_metrics ##### --> +<para> + +</para> + +@font: +@lang: +@metrics: + + <!-- ##### FUNCTION pango_font_get_data ##### --> <para> @@ -298,7 +327,8 @@ a particular #PangoFontMap implementation. @load_font: a function to load a font with a given description. See pango_font_map_load_font() @list_fonts: A function to list available fonts. See pango_font_map_list_fonts() -@list_families: +@list_families: A function to list available font families. See + pango_font_map_list_families(). <!-- ##### FUNCTION pango_font_map_init ##### --> <para> diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml index d98587a5..b5e8b81f 100644 --- a/docs/tmpl/glyphs.sgml +++ b/docs/tmpl/glyphs.sgml @@ -17,6 +17,17 @@ glyphs. </para> +<!-- ##### MACRO PANGO_SCALE ##### --> +<para> +The PANGO_SCALE macro represents the scale between dimensions used +for pango distances and device units. (The definition of device +units is dependent on the output device; it will typically be pixels +for a screen, and points for a printer.) PANGO_SCALE is currently +1000, but this may be changed in the future. +</para> + + + <!-- ##### STRUCT PangoRectangle ##### --> <para> The #PangoRectangle structure represents a rectangle. It is frequently diff --git a/docs/tmpl/layout.sgml b/docs/tmpl/layout.sgml index 7593c90f..66a8dae3 100644 --- a/docs/tmpl/layout.sgml +++ b/docs/tmpl/layout.sgml @@ -47,6 +47,7 @@ The #PangoLayout structure is opaque, and has no user-visible fields. </para> + <!-- ##### FUNCTION pango_layout_new ##### --> <para> @@ -72,6 +73,23 @@ fields. @layout: +<!-- ##### FUNCTION pango_layout_get_context ##### --> +<para> + +</para> + +@layout: +@Returns: + + +<!-- ##### FUNCTION pango_layout_context_changed ##### --> +<para> + +</para> + +@layout: + + <!-- ##### FUNCTION pango_layout_set_text ##### --> <para> @@ -175,6 +193,16 @@ for partial lines. @PANGO_ALIGN_CENTER: Center the line within the available space @PANGO_ALIGN_RIGHT: Put all available space on the left +<!-- ##### FUNCTION pango_layout_get_log_attrs ##### --> +<para> + +</para> + +@layout: +@attrs: +@n_attrs: + + <!-- ##### FUNCTION pango_layout_xy_to_index ##### --> <para> diff --git a/docs/tmpl/main.sgml b/docs/tmpl/main.sgml index b8e8617e..2e54d922 100644 --- a/docs/tmpl/main.sgml +++ b/docs/tmpl/main.sgml @@ -17,21 +17,6 @@ various steps of this process. </para> -<!-- ##### FUNCTION pango_itemize ##### --> -<para> - -</para> - -@context: -@text: -@length: -@attrs: -@Returns: -<!-- # Unused Parameters # --> -@lang_info: -@n_langs: - - <!-- ##### STRUCT PangoContext ##### --> <para> The #PangoContext structure stores global information @@ -95,6 +80,7 @@ a segment of text. It contains the following fields: @offset: @length: @num_chars: +@extra_attrs: @analysis: <!-- ##### STRUCT PangoAnalysis ##### --> @@ -165,12 +151,58 @@ It contains the following fields: <!-- ##### ENUM PangoDirection ##### --> <para> +The #PangoDirection type represents the direction of writing +for text. +</para> + +@PANGO_DIRECTION_LTR: The text is written left-to-right +@PANGO_DIRECTION_RTL: The text is written right-to-left +@PANGO_DIRECTION_TTB_LTR: The text is written vertically + top-to-bottom, with the rows ordered from + left to right. +@PANGO_DIRECTION_TTB_RTL: The text is written vertically + top-to-bottom, with the rows ordered from + right to left. + +<!-- ##### FUNCTION pango_itemize ##### --> +<para> + +</para> + +@context: +@text: +@length: +@attrs: +@Returns: +<!-- # Unused Parameters # --> +@lang_info: +@n_langs: + + +<!-- ##### FUNCTION pango_item_free ##### --> +<para> + +</para> + +@item: + + +<!-- ##### FUNCTION pango_item_copy ##### --> +<para> </para> -@PANGO_DIRECTION_LTR: -@PANGO_DIRECTION_RTL: -@PANGO_DIRECTION_TTB: +@item: +@Returns: + + +<!-- ##### FUNCTION pango_item_new ##### --> +<para> + +</para> + +@Returns: + <!-- ##### FUNCTION pango_reorder_items ##### --> <para> @@ -205,6 +237,27 @@ It contains the following fields: @context: +<!-- ##### FUNCTION pango_context_get_data ##### --> +<para> + +</para> + +@context: +@key: +@Returns: + + +<!-- ##### FUNCTION pango_context_set_data ##### --> +<para> + +</para> + +@context: +@key: +@data: +@destroy_func: + + <!-- ##### FUNCTION pango_context_add_font_map ##### --> <para> diff --git a/docs/tmpl/pango-unused.sgml b/docs/tmpl/pango-unused.sgml index 6c16aa07..ff507979 100644 --- a/docs/tmpl/pango-unused.sgml +++ b/docs/tmpl/pango-unused.sgml @@ -1,10 +1,3 @@ -<!-- ##### FUNCTION pango_cfont_init ##### --> -<para> - -</para> - -@font: - <!-- ##### FUNCTION pango_layout_line_x_to_cp ##### --> <para> @@ -15,39 +8,80 @@ @char_pos: @trailing: -<!-- ##### FUNCTION pango_layout_cp_to_line_x ##### --> +<!-- ##### FUNCTION pango_x_to_cp ##### --> <para> </para> -@layout: +@text: +@length: +@analysis: +@glyphs: +@x_pos: @char_pos: @trailing: -@line: -@x_pos: -<!-- ##### FUNCTION pango_cfont_ref ##### --> +<!-- ##### FUNCTION pango_cfont_init ##### --> <para> </para> @font: -<!-- ##### TYPEDEF PangoGlyphIndex ##### --> +<!-- ##### STRUCT PangoCFont ##### --> <para> -The #PangoGlyphIndex type is an integral type used to store glyph -indices. +The #PangoCFont structure is used to represent a single componenent +of a font n a rendering-system-independent matter. A component of a +font is an opaque object that makes sense only to the rendering +system. A glyph (the #PangoGlyph structure) is stored as a #PangoCFont +and a numeric glyph index. </para> +<para> +To create an implementation of a #PangoCFont, +the rendering-system specific code should malloc +a larger structure that contains a nested +#PangoCFont, fill in the klass member of +the nested #PangoCFont with a pointer to +a appropriate #PangoCFontClass, then call +pango_cfont_init() on the structure. +</para> +<para> +The #PangoCFont structure contains one member +that may be accessed by derived classes: +<informaltable pgwide=1 frame="none" role="struct"> +<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*"> +<tbody> -<!-- ##### FUNCTION pango_context_get_size ##### --> +<row> +<entry>#PangoCFontClass *klass;</entry> +<entry>a pointer to the <firstterm>class structure</firstterm> + for this font.</entry> +</row> +</tbody></tgroup></informaltable> +</para> + +@klass: + +<!-- ##### FUNCTION pango_x_xlfd_get_ranges ##### --> <para> </para> -@context: +@font: +@xlfd: +@ranges: +@n_ranges: @Returns: +<!-- ##### FUNCTION pango_context_set_size ##### --> +<para> + +</para> + +@context: +@size: + <!-- ##### FUNCTION pango_x_glyph_extents ##### --> <para> @@ -63,164 +97,124 @@ indices. @logical_ascent: @logical_descent: -<!-- ##### FUNCTION pango_cp_to_x ##### --> +<!-- ##### TYPEDEF PangoGlyphIndex ##### --> <para> - +The #PangoGlyphIndex type is an integral type used to store glyph +indices. </para> -@text: -@length: -@analysis: -@glyphs: -@char_pos: -@trailing: -@x_pos: -<!-- ##### FUNCTION pango_x_find_cfont ##### --> +<!-- ##### FUNCTION pango_attribute_register_type ##### --> <para> </para> -@font: -@charset: +@name: @Returns: -<!-- ##### FUNCTION g_glyph_string_set_size ##### --> +<!-- ##### SECTION ./tmpl/pango-x.sgml:See_Also ##### --> <para> </para> -@string: -@new_len: -<!-- ##### FUNCTION pango_coverage_destroy ##### --> -<para> - -</para> +<!-- ##### SECTION ./tmpl/pango-x.sgml:Title ##### --> +X Rendering -@coverage: -<!-- ##### FUNCTION pango_x_xlfd_get_ranges ##### --> +<!-- ##### FUNCTION pango_cfont_ref ##### --> <para> </para> @font: -@xlfd: -@ranges: -@n_ranges: -@Returns: -<!-- ##### FUNCTION g_glyph_string_free ##### --> +<!-- ##### FUNCTION pango_cfont_unref ##### --> <para> </para> -@string: +@font: -<!-- ##### FUNCTION pango_x_load_xlfd ##### --> +<!-- ##### FUNCTION pango_layout_set_first_line_width ##### --> <para> </para> -@font: -@xlfd: -@Returns: +@layout: +@width: -<!-- ##### FUNCTION pango_x_to_cp ##### --> +<!-- ##### FUNCTION pango_x_extents ##### --> <para> </para> -@text: -@length: -@analysis: +@font: @glyphs: -@x_pos: -@char_pos: -@trailing: - -<!-- ##### SECTION ./tmpl/pango-x.sgml:Title ##### --> -X Rendering - +@lbearing: +@rbearing: +@width: +@ascent: +@descent: +@logical_ascent: +@logical_descent: -<!-- ##### SECTION ./tmpl/pango-x.sgml:See_Also ##### --> +<!-- ##### FUNCTION pango_coverage_destroy ##### --> <para> </para> +@coverage: -<!-- ##### SECTION ./tmpl/pango-x.sgml:Short_Description ##### --> -Functions for rendering and measuring glyphs on -the X Window system. - - -<!-- ##### FUNCTION pango_context_set_size ##### --> +<!-- ##### FUNCTION pango_cp_to_x ##### --> <para> </para> -@context: -@size: +@text: +@length: +@analysis: +@glyphs: +@char_pos: +@trailing: +@x_pos: -<!-- ##### FUNCTION pango_attribute_register_type ##### --> +<!-- ##### FUNCTION pango_x_list_cfonts ##### --> <para> </para> -@name: -@Returns: +@font: +@charsets: +@n_charsets: +@xlfds: +@n_xlfds: -<!-- ##### FUNCTION g_glyph_string_new ##### --> +<!-- ##### FUNCTION pango_x_load_xlfd ##### --> <para> </para> +@font: +@xlfd: @Returns: -<!-- ##### FUNCTION pango_layout_set_first_line_width ##### --> -<para> - -</para> - -@layout: -@width: - -<!-- ##### SECTION ./tmpl/pango-x.sgml:Long_Description ##### --> +<!-- ##### FUNCTION g_glyph_string_set_size ##### --> <para> </para> +@string: +@new_len: -<!-- ##### FUNCTION pango_x_list_cfonts ##### --> +<!-- ##### FUNCTION pango_x_find_cfont ##### --> <para> </para> @font: -@charsets: -@n_charsets: -@xlfds: -@n_xlfds: - -<!-- ##### STRUCT PangoCFontClass ##### --> -<para> -The PangoCFontClass structure contains the virtual -functions for an implementation of a a PangoCFont. - -It contains the following member: - -<informaltable pgwide=1 frame="none" role="struct"> -<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*"> -<tbody> - -<row> -<entry>void (*destroy) (#PangoFont *font);</entry> -<entry>a function to free the font structure and associated resources.</entry> -</row> -</tbody></tgroup></informaltable> -</para> - +@charset: +@Returns: <!-- ##### STRUCT PangoXCFont ##### --> <para> @@ -248,60 +242,66 @@ has the following publically accessible fields: @display: @font_struct: -<!-- ##### FUNCTION pango_cfont_unref ##### --> +<!-- ##### FUNCTION g_glyph_string_free ##### --> <para> </para> -@font: +@string: -<!-- ##### STRUCT PangoCFont ##### --> +<!-- ##### FUNCTION pango_layout_cp_to_line_x ##### --> <para> -The #PangoCFont structure is used to represent a single componenent -of a font n a rendering-system-independent matter. A component of a -font is an opaque object that makes sense only to the rendering -system. A glyph (the #PangoGlyph structure) is stored as a #PangoCFont -and a numeric glyph index. + </para> + +@layout: +@char_pos: +@trailing: +@line: +@x_pos: + +<!-- ##### SECTION ./tmpl/pango-x.sgml:Short_Description ##### --> +Functions for rendering and measuring glyphs on +the X Window system. + + +<!-- ##### FUNCTION pango_context_get_size ##### --> <para> -To create an implementation of a #PangoCFont, -the rendering-system specific code should malloc -a larger structure that contains a nested -#PangoCFont, fill in the klass member of -the nested #PangoCFont with a pointer to -a appropriate #PangoCFontClass, then call -pango_cfont_init() on the structure. + </para> + +@context: +@Returns: + +<!-- ##### FUNCTION g_glyph_string_new ##### --> <para> -The #PangoCFont structure contains one member -that may be accessed by derived classes: + +</para> + +@Returns: + +<!-- ##### SECTION ./tmpl/pango-x.sgml:Long_Description ##### --> +<para> + +</para> + + +<!-- ##### STRUCT PangoCFontClass ##### --> +<para> +The PangoCFontClass structure contains the virtual +functions for an implementation of a a PangoCFont. + +It contains the following member: <informaltable pgwide=1 frame="none" role="struct"> <tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*"> <tbody> <row> -<entry>#PangoCFontClass *klass;</entry> -<entry>a pointer to the <firstterm>class structure</firstterm> - for this font.</entry> +<entry>void (*destroy) (#PangoFont *font);</entry> +<entry>a function to free the font structure and associated resources.</entry> </row> </tbody></tgroup></informaltable> </para> -@klass: - -<!-- ##### FUNCTION pango_x_extents ##### --> -<para> - -</para> - -@font: -@glyphs: -@lbearing: -@rbearing: -@width: -@ascent: -@descent: -@logical_ascent: -@logical_descent: diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml index ee00cd60..7430f77a 100644 --- a/docs/tmpl/text-attributes.sgml +++ b/docs/tmpl/text-attributes.sgml @@ -235,6 +235,23 @@ a integer or enumeration value. @Returns: +<!-- ##### ENUM PangoUnderline ##### --> +<para> +the #PangoUnderline enumeration is used to specify +whether text should be underlined, and if so, the type +of underlining. +</para> + +@PANGO_UNDERLINE_NONE: no underline should be drawn. +@PANGO_UNDERLINE_SINGLE: a single underline should be drawn. +@PANGO_UNDERLINE_DOUBLE: a double underline should be drawn. +@PANGO_UNDERLINE_LOW: a single underline should be drawn at a position + beneath the ink extents of the text being + underlined. This should be used only for underlining + single characters, such as for keyboard + accelerators. %PANGO_UNDERLINE_SINGLE should + be used for extended portions of text. + <!-- ##### FUNCTION pango_attr_rise_new ##### --> <para> @@ -360,6 +377,7 @@ attributes currently in effect can be queried. @iterator: @base: @current: +@extra_attrs: <!-- ##### FUNCTION pango_attr_iterator_destroy ##### --> diff --git a/docs/tmpl/x-rendering.sgml b/docs/tmpl/x-rendering.sgml index 82f0beea..844e685e 100644 --- a/docs/tmpl/x-rendering.sgml +++ b/docs/tmpl/x-rendering.sgml @@ -33,6 +33,42 @@ X Window System. @Returns: +<!-- ##### FUNCTION pango_x_context_set_funcs ##### --> +<para> + +</para> + +@context: +@get_gc_func: +@free_gc_func: + + +<!-- ##### USER_FUNCTION PangoGetGCFunc ##### --> +<para> +Used to represent a function which is called when a new GC must be +created to draw something other than the default color when rendering +a layout. The function used here will typically retrieve information +from the context with pango_context_get_data(). +</para> + +@context: the #PangoContext +@color: color attribute representing the desired color +@base_gc: default GC used for rendering. The function will typically + copy attributes such as clip region from the GC +@Returns: the new GC + + +<!-- ##### USER_FUNCTION PangoFreeGCFunc ##### --> +<para> +Used to represent a function which is called to free a GC created with +the corresponding PangoGetGCFunc. The function used here will +typically retrieve information from the context with pango_context_set_data(). +</para> + +@context: the #PangoContext +@gc: the GC to free + + <!-- ##### FUNCTION pango_x_render ##### --> <para> |