Graphic context commands

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

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.

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.