From f7a50c4dc2c8a901ac0fa40305d1a8dde82cbeac Mon Sep 17 00:00:00 2001 From: Owen Taylor Date: Tue, 17 Aug 1999 09:39:58 +0000 Subject: [PATCH] Added section. (Written a while ago but fell through the cracks) Thu Aug 19 14:43:08 1999 Owen Taylor * gdk/tmpl/gcs.sgml gdk/gdk-sections.txt: Added section. (Written a while ago but fell through the cracks) * gtk/gtk-docs.sgml: Add a &hash; entity here as a temporary hack. (There is no standard entity for '#', and no way of escaping '#' in gtk-doc) * gtk/tmpl/gtkrc.sgml: Use the above to fix up #rrggbb string literals. * gtk/tmpl/gtkdrawingarea.sgml: Fixed a couple of errors in the example. (pointed out by Nick Lamb) --- docs/reference/ChangeLog | 16 + docs/reference/gdk/tmpl/gcs.sgml | 485 ++++++++++++++++---- docs/reference/gtk/gtk-docs.sgml | 1 + docs/reference/gtk/tmpl/gtkdrawingarea.sgml | 5 +- docs/reference/gtk/tmpl/gtkrc.sgml | 6 +- 5 files changed, 427 insertions(+), 86 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index d30e9d31db..d638e36f4b 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,19 @@ +Thu Aug 19 14:43:08 1999 Owen Taylor + + * gdk/tmpl/gcs.sgml gdk/gdk-sections.txt: Added section. + (Written a while ago but fell through the cracks) + + * gtk/gtk-docs.sgml: Add a &hash; entity here as a + temporary hack. (There is no standard entity + for '#', and no way of escaping '#' in gtk-doc) + + * gtk/tmpl/gtkrc.sgml: Use the above to fix up #rrggbb + string literals. + + * gtk/tmpl/gtkdrawingarea.sgml: Fixed a couple + of errors in the example. (pointed out by + Nick Lamb) + Mon Aug 16 6:60:53 1999 Owen Taylor * gdk/tmpl/properties.sgml diff --git a/docs/reference/gdk/tmpl/gcs.sgml b/docs/reference/gdk/tmpl/gcs.sgml index 101e3a3058..e8da61fbc0 100644 --- a/docs/reference/gdk/tmpl/gcs.sgml +++ b/docs/reference/gdk/tmpl/gcs.sgml @@ -2,11 +2,27 @@ Graphics Contexts - +objects to encapsulate drawing properties. - +All drawing operations in GDK take a +graphics context (GC) argument. +A graphics context encapsulates information about +the way things are drawn, such as the foreground +color or line width. By using graphics contexts, +the number of arguments to each drawing call is +greatly reduced, and communication overhead is +minimized, since identical arguments do not need +to be passed repeatedly. + + +Most values of a graphics context can be set at +creation time by using gdk_gc_new_with_values(), +or can be set one-by-one using functions such +as gdk_gc_set_foreground(). A few of the values +in the GC, such as the dash pattern, can only +be set by the latter method. @@ -16,14 +32,113 @@ Graphics Contexts - +The #GdkGC structure represents a graphics context. +It is an opaque structure with no user-visible +elements. @dummy_var: +The #GdkGCValues structure holds a set of values used +to create or modify a graphics context. + + + + + +#GdkColor foreground; +the foreground color. + + + +#GdkColor background; +the background color. + + + +#GdkFont *font; +the default font.. + + + +#GdkFunction function; +the bitwise operation used when drawing. + + + +#GdkFill fill; +the fill style. + + + +#GdkPixmap *tile; +the tile pixmap. + + + +#GdkPixmap *stipple; +the stipple bitmap. + + + +#GdkPixmap *clip_mask; +the clip mask bitmap. + + + +#GdkSubwindowMode subwindow_mode; +the subwindow mode. + + + +#gint ts_x_origin; +the x origin of the tile or stipple. + + + +#gint ts_y_origin; +the y origin of the tile or stipple. + + + +#gint clip_x_origin; +the x origin of the clip mask. + + + +#gint clip_y_origin; +the y origin of the clip mask. + + + +#gint graphics_exposures; +whether graphics exposures are enabled. + + + +#gint line_width; +the line width + + + +#GdkLineStyle line_style; +the way dashed lines are drawn + + + +#GdkCapStyle cap_style; +the way the ends of lines are drawn + + + +#GdkJoinStyle join_style; +the way joins between lines are drawn + + + @foreground: @@ -47,7 +162,8 @@ Graphics Contexts - +A set of bit flags used to indicate which fields +#GdkGCValues structure are set. @GDK_GC_FOREGROUND: @@ -69,9 +185,56 @@ Graphics Contexts @GDK_GC_CAP_STYLE: @GDK_GC_JOIN_STYLE: + + +Determines how primitives are drawn. + + + + + + +GDK_SOLID +draw with the foreground color. + + + +GDK_TILED +draw with a tiled pixmap. + + + +GDK_STIPPLED +draw using the stipple bitmap. Pixels corresponding +to bits in the stipple bitmap that are set will be drawn in the +foreground color; pixels corresponding to bits that are +not set will be left untouched. + + + +GDK_OPAQUE_STIPPLED +draw using the stipple bitmap. Pixels corresponding +to bits in the stipple bitmap that are set will be drawn in the +foreground color; pixels corresponding to bits that are +not set will be drawn with the background color. + + + + + +@GDK_SOLID: +@GDK_TILED: +@GDK_STIPPLED: +@GDK_OPAQUE_STIPPLED: + - +Determines how the bit values for the source pixels are combined with +the bit values for destination pixels to produce the final result. The +sixteen values here correspond to the 16 different possible 2x2 truth +tables. Only a couple of these values are usually useful; for colored +images, only %GDK_COPY, %GDK_XOR and %GDK_INVERT are generally +useful. For bitmaps, %GDK_AND and %GDK_OR are also useful. @GDK_COPY: @@ -90,182 +253,333 @@ Graphics Contexts @GDK_NAND: @GDK_SET: - + +Determines how lines are drawn. + + + + + +GDK_LINE_SOLID +lines are drawn solid. + + + +GDK_LINE_ON_OFF_DASH +even segments are drawn; odd segments are not drawn. + + + +GDK_LINE_DOUBLE_DASH +even segments are normally. Odd segments are drawn +in the background color if the fill style is %GDK_SOLID, +or in the background color masked by the stipple if the +fill style is %GDK_STIPPLED. + + + -@window: -@Returns: +@GDK_LINE_SOLID: +@GDK_LINE_ON_OFF_DASH: +@GDK_LINE_DOUBLE_DASH: + + + +Determines how the end of lines are drawn. + + + + + + +GDK_CAP_NOT_LAST +the same as %GDK_CAP_BUTT for lines of non-zero width. + for zero width lines, the final point on the line + will not be drawn. + + + +GDK_CAP_BUTT +the ends of the lines are drawn squared off and extending + to the coordinates of the end point. + + + +GDK_CAP_ROUND +the ends of the lines are drawn as semicircles with the + diameter equal to the line width and centered at the + end point. + + + +GDK_CAP_PROJECTING +the ends of the lines are drawn squared off and extending + half the width of the line beyond the end point. + + + + +@GDK_CAP_NOT_LAST: +@GDK_CAP_BUTT: +@GDK_CAP_ROUND: +@GDK_CAP_PROJECTING: + + + +Determines how the joins between segments of a polygon are drawn. + + + + + + +GDK_JOIN_MITER +the sides of each line are extended to meet at an angle. + + + +GDK_JOIN_ROUND +the sides of the two lines are joined by a circular arc. + + + +GDK_JOIN_BEVEL +the sides of the two lines are joined by a straight line which + makes an equal angle with each line. + + + + + +@GDK_JOIN_MITER: +@GDK_JOIN_ROUND: +@GDK_JOIN_BEVEL: + + + +Create a new graphics context with default values. + + +@window: a #GdkDrawable. The created GC must always be used + with drawables of the same depth as this one. +@Returns: the new graphics context. - +Create a new GC with the given initial values. -@window: -@values: -@values_mask: -@Returns: +@window: a #GdkDrawable. The created GC must always be used + with drawables of the same depth as this one. +@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. - +Increase the reference count on a graphics context. -@gc: -@Returns: +@gc: a #GdkGC. +@Returns: @gc. - +Decrease the reference count on a graphics context. If +the resulting reference count is zero, the graphics +context will be destroyed. -@gc: +@gc: a #GdkGC. - +Identical to gdk_gc_unref(). This function is obsolete +and should not be used. -@gc: +@gc: a #GdkGC. - +Retrieves the current values from a graphics context. -@gc: -@values: +@gc: a #GdkGC. +@values: the #GdkGCValues structure in which to store the results. - +Sets the foreground color for a graphics context. -@gc: -@color: +@gc: a #GdkGC. +@color: the new foreground color. - +Sets the background color for a graphics context. -@gc: -@color: +@gc: a #GdkGC. +@color: the new background color. - +Sets the font for a graphics context. (Note that +all text-drawing functions in GDK take a @font +argument; the value set here is used when that +argument is %NULL.) -@gc: -@font: +@gc: a #GdkGC. +@font: the new font. - +Determines how the current pixel values and the +pixel values being drawn are combined to produce +the final pixel values. -@gc: +@gc: a #GdkGC. @function: - +Set the fill mode for a graphics context. -@gc: -@fill: +@gc: a #GdkGC. +@fill: the new fill mode. - +Set a tile pixmap for a graphics context. +This will only be used if the fill mode +is %GDK_TILED. -@gc: -@tile: +@gc: a #GdkGC. +@tile: the new tile pixmap. - +Set the stipple bitmap for a graphics context. The +stipple will only be used if the fill mode is +%GDK_STIPPLED or %GDK_OPAQUE_STIPPLED. -@gc: -@stipple: +@gc: a #GdkGC. +@stipple: the new stipple bitmap. - +Set the origin when using tiles or stipples with +the GC. The tile or stipple will be aligned such +that the upper left corner of the tile or stipple +will coincide with this point. -@gc: -@x: -@y: +@gc: a #GdkGC. +@x: the x-coordinate of the origin. +@y: the y-coordinate of the origin. - +Sets the origin of the clip mask. The coordinates are +interpreted relative to the upper-left corner of +the destination drawable of the current operation. -@gc: -@x: -@y: +@gc: a #GdkGC. +@x: the x-coordinate of the origin. +@y: the y-coordinate of the origin. - +Sets the clip mask for a graphics context from a bitmap. +The clip mask is interpreted relative to the clip +origin. (See gdk_gc_set_clip_origin()). -@gc: -@mask: +@gc: the #GdkGC. +@mask: a bitmap. +Sets the clip mask for a graphics context from a +rectangle. The clip mask is interpreted relative to the clip +origin. (See gdk_gc_set_clip_origin()). -@gc: -@rectangle: +@gc: a #GdkGC. +@rectangle: the rectangle to clip to. - +Sets the clip mask for a graphics context from a region structure. +The clip mask is interpreted relative to the clip origin. (See +gdk_gc_set_clip_origin()). -@gc: -@region: +@gc: a #GdkGC. +@region: the #GdkRegion. - +Sets how drawing with this GC on a window will affect child +windows of that window. -@gc: -@mode: +@gc: a #GdkGC. +@mode: the subwindow mode. +Determines how drawing onto a window will affect child +windows of that window. + + + + + + +GDK_CLIP_BY_CHILDREN +only draw onto the window itself. + + + +GDK_INCLUDE_INFERIORS +Draw onto the window and child windows. + + + @GDK_CLIP_BY_CHILDREN: @@ -273,42 +587,51 @@ Graphics Contexts - +Sets whether copying non-visible portions of a drawable +using this graphics context generate exposure events +for the corresponding regions of the destination +drawable. (See gdk_draw_pixmap()). -@gc: -@exposures: +@gc: a #GdkGC. +@exposures: if %TRUE, exposure events will be generated. - +Sets various attributes of how lines are drawn. See +the corresponding members of GdkGCValues for full +explanations of the arguments. -@gc: -@line_width: -@line_style: -@cap_style: -@join_style: +@gc: a #GdkGC. +@line_width: the width of lines. +@line_style: the dash-style for lines. +@cap_style: the manner in which the ends of lines are drawn. +@join_style: the in which lines are joined together. - +Sets the way dashed-lines are drawn. Lines will be +drawn with alternating on and off segments of the +lengths specified in @dash_list. The manner in +which the on and off segments are drawn is determined +by the @line_style value of the GC. (This can +be changed with gdk_gc_set_line_attributes) -@gc: -@dash_offset: -@dash_list: -@n: +@gc: a #GdkGC. +@dash_offset: the +@dash_list: an array of dash lengths. +@n: the number of elements in @dash_list. - +Copy the set of values from one graphics context +onto another graphics context. -@dst_gc: -@src_gc: - - +@dst_gc: the destination graphics context. +@src_gc: the source graphics context. diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index b1586642c9..97afce3121 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -1,4 +1,5 @@ diff --git a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml index b78eae267d..cc9800dec9 100644 --- a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml +++ b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml @@ -60,9 +60,10 @@ expose_event (GdkWidget *widget, GdkEventExpose *event, gpointer data) gdk_draw_arc (widget->window, widget->style->fg_gc[widget->state], TRUE, - 0, 0, widget->allocation->width, widget->allocation.height, + 0, 0, widget->allocation.width, widget->allocation.height, 0, 64 * 360); - gdk_gc_set_clip_rectangle (widget->style->fg_gc[widget->state]); + gdk_gc_set_clip_rectangle (widget->style->fg_gc[widget->state], + NULL); return TRUE; } diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml index 850384c402..381af1ba21 100644 --- a/docs/reference/gtk/tmpl/gtkrc.sgml +++ b/docs/reference/gtk/tmpl/gtkrc.sgml @@ -269,9 +269,9 @@ state of the widget. The states are: -Colors can be specified as a string "#rrrrggggbbbb", -"#rrrgggbbb", "#rrggbb", -or "#rgb", where r +Colors can be specified as a string "&hash;rrrrggggbbbb", +"&hash;rrrgggbbb", "&hash;rrggbb", +or "&hash;rgb", where r g, and b are hex digits, or they can be specified as a triplet of floats { r, g,