Graphic context commands

Graphic context commands
Prev	Appendix A. Scalable X Graphics	Next

<sxg>

  <!-- width and height declarations -->

  <pixmap id="pixmap1">
    <size>scaled</size>
    <width>16</width>
    <height>16</height>
    <gc id="pixmap1_gc1" />
  </pixmap>

  <gc id="pixmap1_gc">

    <!-- Graphic context commands -->

  </gc>
</sxg>

After declaring one or more gcs inside their pixmaps, the gc elements execute commands for the graphic context specified by their id attribute. A gc element is a list of commands described below. Each list gets executed in the given order, and the SXG file itself has a list of gc and render elements, which are processed in the order of their appearance. It's possible to have more than one appearance of a gc element referencing the same graphic context id:

<sxg>

    <!-- ... -->

  <gc id="pixmap1_gc">

    <!-- ... -->

  </gc>

  <render id="cell">

    <!-- ... -->

  </render>

  <gc id="pixmap2_gc">

    <!-- ... -->

  </gc>

  <gc id="pixmap1_gc">

    <!-- ... -->

  </gc>

  <render id="main">

    <!-- ... -->

  </render>

</sxg>

This executes some graphic context commands for the graphic context “pixmap1_gc”, followed by RENDER commands for the picture “cell”, then graphic context commands for the graphic context “pixmap2_gc”, then “pixmap1_gc”, and finally some RENDER commands for the “main” picture.

Note

The graphic context state is persistent. If, for example, the first set of “pixmap1_gc” commands included setting the graphic context's function, the second set of “pixmap1_gc” commands starts with the graphic context still having that function set.

`function`

<gc id="pixmap1_gc">

  <!-- -->

  <function>set</function>

  <!-- -->

</gc>

This sets the current “function” component value for the graphic context. The value must be one of the following: “clear”, “and”, “and_reverse”, “copy”, “and_inverted”, “noop”, “xor”, “or”, “nor”, “equiv”, “invert”, “or_reverse”, “copy_inverted”, “or_inverted”, “nand”, or “set”.

`foreground`

<gc id="pixmap1_gc">

  <!-- -->

  <foreground>.5</foreground>

  <!-- -->

</gc>

This sets the “foreground” component value for the graphic context. The X protocol defines this component value as an integer, ranging from 0 and up to the value based on the pixmap's depth. The value specified in foreground ranges from 0 to 1, and gets scaled to the appropriate range of permissible foreground values.

As described previously, the pixmap serves as an alpha channel filter. A value of 0 is a completely transparent pixel value, a value of 1 is a fully opaque pixel value. A pixmap declared with a mask element can only have a value of a 0 or a 1, since it's a 1 bit deep pixmap. A non-mask pixmap is 8 bits deep, and a value between 0 and 1 gets scaled across the entire 8-bit deep pixmap.

`background`

<gc id="pixmap1_gc">

  <!-- -->

  <background>.5</background>

  <!-- -->

</gc>

This sets the “background” component value for the graphic context. The X protocol defines this component value as an integer, ranging from 0 and up to the value based on the pixmap's depth. The value specified in background ranges from 0 to 1, and gets scaled to the appropriate range of permissible background values.

`line_width`

<gc id="pixmap1_gc">

  <!-- -->

  <line_width>1</line_width>

  <!-- -->

</gc>

This sets the “line-width” component value of the graphic context. Specifying the value 0 set line-width to 0. Specifying a non-0 value scales it according to the pixmap's size; and if the result gets rounded off to 0, it gets increased to 1 before setting the line-width.

  <line_width slim="1">1</line_width>
</gc>

An optional slim attribute adds an additional scaling step: line-width gets set 0 if the scaled line width got rounded off to 1. The line-width remains unchanged if the scaled line width got rounded off to 2, or higher.

`line_style`

<gc id="pixmap1_gc">

  <!-- -->

  <line_style>on_off_dash</line_style>

  <!-- -->

</gc>

This sets the “line-style” component value of the graphic context. The value is one of: “solid”, “on_off_dash”, or “double_dash”.

`join_style`

<gc id="pixmap1_gc">

  <!-- -->

  <join_style>bevel</join_style>

  <!-- -->

</gc>

This sets the “join-style” component value of the graphic context. The value is one of: “miter” (default value), “round”, or “bevel”.

`cap_style`

<gc id="pixmap1_gc">

  <!-- -->

  <cap_style>round</cap_style>

  <!-- -->

</gc>

This sets the “cap-style” component value of the graphic context. The value is one of: “not_last”, “butt” (default value) “round”, or “projecting”.

`fill_style`

<gc id="pixmap1_gc">

  <!-- -->

    <fill_style />

    <fill_style>
      <tiled>non_mask_pixmap</tiled>
      <x>0</x>
      <y>0</y>
    </fill_style>

    <fill_style>
      <stippled>mask_pixmap</stippled>
      <x>0</x>
      <y>0</y>
    </fill_style>

    <fill_style>
      <opaque_stippled>mask_pixmap</opaque_stippled>
      <x>0</x>
      <y>0</y>
    </fill_style>

  <!-- -->

</gc>

This sets the “fill-style”, “tile-stipple-x-origin”, and “tile-stipple-y-origin” component values of the graphic context. An empty fill_style element sets the “fill-style” component to Solid. Otherwise, the “fill-style” component gets set to Tiled, Stippled, or OpaqueStippled, with either the “tile” or the “stipple” component value set to specified pixmap. The stipple pixmap must be declared with the mask element. The tile pixmap cannot be declared with mask element.

The optional x and y elements set the “tile-stipple-x-origin”, and “tile-stipple-y-origin” component values. The coordinates get scaled according to the pixmap's size. If not specified, they default to actual (0, 0) coordinates.

`clip`

<gc id="pixmap1_gc">

  <!-- -->

    <clip>
      <pixmap>pixmap2</pixmap>
      <x>0</x>
      <y>0</y>

      <clipped>
	<line>

	  <!-- -->

	</line>
      </clipped>
    </clip>

    <clip>
      <rectangle>
	<x>0</x>
	<y>0</y>
	<width>10</width>
	<height><10</height>
      </rectangle>
      <rectangle>
	<x>10</x>
	<y>10</y>
	<width>10</width>
	<height><10</height>
      </rectangle>

      <clipped>
	<line>

	  <!-- -->

	</line>
      </clipped>

    </clip>

    <!-- -->

</gc>

This sets the “clip-mask” component value of the graphic context, in one of two ways:

Using the id label of a pixmap that serves as a clipping mask. This pixmap must be declared with a mask element.
This option sets the graphic context's clip-mask attribute directly.
Using a list of rectangles. Each rectangle's coordinates get scaled according to the underlying pixmap's size.

When a pixmap is specified, the optional x and y elements set the “clip-x-origin”, and “clip-y-origin” component values. The coordinates get scaled according to the pixmap's size. If not specified, they default to actual (0, 0) coordinates.

The pixmap specified by “pixmap” must be declared with a mask element.

The clip must have exactly one clipped inner widget, which contains a list of any widget that can appear in a gc, except for another clip. The elements in clipped get executed with the clip mask in effect, after which point the clip mask is removed.

`dashes`

<gc id="pixmap1_gc">

  <!-- -->

  <dashes>
    <dash>1</dash>
    <dash>2</dash>
  </dashes>

  <!-- -->

</gc>

This executes the SetDashes X protocol command using the dash values.

The offset widget defaults to 0, if not given, and sets the “dash-offset”.

All of these values get scaled according to the pixmap's size.

`line`

<gc id="pixmap1_gc">

  <!-- -->

  <line>
    <point>
      <x>0</x>
      <y>0</y>
    </point>
    <point>
      <x>5</x>
      <y>5</y>
    </point>
    <point>
      <x>0</x>
      <y>10</y>
    </point>
  </line>

  <!-- -->

</gc>

This executes the PolyLine X protocol command using the point coordinates. All of these coordinates get scaled according to the pixmap's size.

<gc id="pixmap1_gc">

  <!-- -->

  <line>
    <fill>convex</fill>
    <point>
      <x>0</x>
      <y>0</y>
    </point>
    <point>
      <x>5</x>
      <y>5</y>
    </point>
    <point>
      <x>0</x>
      <y>10</y>
    </point>
  </line>

  <!-- -->

</gc>

An optional fill executes the the FillPoly X protocol instead of PolyLine. The fill specifies either “complex” “nonconvex” or “convex”. This sets the shape command parameter.

`fill` and `clear`

<gc id="pixmap1_gc">

  <!-- -->

  <fill>
    <x>0</x>
    <y>0</y>
    <width>10</width>
    <height>10</height>
  </fill>

  <!-- -->

  <clear />

</gc>

fill executes the PolyFillRectangle X protocol command for one rectangle specified by the coordinates. All of these coordinates get scaled according to the pixmap's size.

clear is a shorthand for a fill that covers the entire pixmap. This is helpful in clearing scaled pixmaps.

Note

Since clear is really a fill, the function must be set to “clear” to actually clear the pixmap.

`fill_arc_mode`

<gc id="pixmap1_gc">

  <!-- -->

  <fill_arc_mode>pie_slice</fill_arc_mode>

  <!-- -->

</gc>

This sets the “arc-mode” component value of the graphic context. The value is either “chord” or “pie_slice”.

`arcs`

<gc id="pixmap1_gc">

  <!-- -->

  <arcs>

    <fill /> <!-- optional -->

    <arc>
      <x>0</x>
      <y>0</y>
      <width>9</width>
      <height>9</height>
      <angle1>45</angle1>
      <angle2>90</angle2>
    </arc>

    <arc>
      <x>5</x>
      <y>5</y>
      <width>9</width>
      <height>9</height>
      <angle1>45</angle1>
      <angle2>90</angle2>
    </arc>
  </arcs>

  <!-- -->

</gc>

This executes either the PolyArc or the PolyFillArc protocol command, depending on whether the <fill/> element exists. Each arc's coordinates get scaled according to the pixmap's size.

Note

The angles are specified in degrees, and SXG takes care of scaling it by 64, as defined by the X protocol.

Note

Without the <fill/> option LibCXX Widget Toolkit calculates coordinates based on the center of virtually-scaled pixels. The <fill/> option interprets the coordinates as a bounding box.

<sxg>
  <width>10</width>
  <height>10</height>

  <!-- -->

  <arcs>

    <arc>
      <x>0</x>
      <y>0</y>
      <width>9</width>
      <height>9</height>
      <angle1>0</angle1>
      <angle2>360</angle2>
    </arc>
  </arcs>

This defines a virtual cartesian coordinate space of 10x10 pixels, and draws a full circle within the coordinates defined by (x, y) and (x+width,w y+height); or (0, 0) through (9, 9), the entire size of the virtual 10x10 cartesian coordinate space.

The arc's coordinates are based on the center of the virtual (0, 0) and (9, 9) pixel, and the default line_width of 1 means that, for example, the sides of the arc extend half a pixel from the center of the virtual coordinate, and fully touch the bounding box. With a 3:1 scale the drawn line becomes three pixels thick; and with the circle boundary is anchored at the centerpoint of the scaled pixel, the drawn circle once again touches the sides of the image.

Filling this arc requires specifying the coordinates as a bounding box:

  <arcs>
    <fill />
    <arc>
      <x>0</x>
      <y>0</y>
      <width>10</width>
      <height>10</height>
      <angle1>0</angle1>
      <angle2>360</angle2>
    </arc>
  </arcs>

This draws the arc within the boundaries of the 10x10 virtual rectangle, anchored at the top-left corner of pixel (0, 0).

Note

LibCXX Widget Toolkit also makes an additional, final adjustment to the size of the drawn arc. The underlying X Protocol's PolyArc and PolyFillArc commands' arcs specify the bounding rectangle of pixels (x,y) through (x+width,x+height) inclusively. So, a circle 50 pixels across and tall gets specified by an actual width and height of 49 (indicating fifty pixels starting with x and ending with pixel x+49, across, same for height).

The SXG image only needs to specify the coordinates based on the centerpoints of virtual pixels, and the scaled adjusted width and height gets calculated accordingly.

Prev	Up	Next
Creating pixmaps	Table Of Contents	Picture render commands