GeocShapes

GeocShapes — A simple way to draw primitive geographically referenced shapes using stock CrItems.

Synopsis

#define             GEOC_TYPE_POINT
#define             GEOC_TYPE_RECTANGLE
#define             GEOC_TYPE_VECTOR
                    GeocPoint;
                    GeocVector;
                    GeocRectangle;
                    GeocShapes;
void                geoc_shapes_item_request_update     (GeocShapes *shapes,
                                                         CrItem *item);
CrItem*             geoc_shapes_add_line                (GeocShapes *shapes,
                                                         double lon1,
                                                         double lat1,
                                                         double lon2,
                                                         double lat2,
                                                         const gchar *first_arg_name,
                                                         ...);
void                geoc_shapes_update_line             (GeocShapes *shapes,
                                                         CrItem *line,
                                                         double lon1,
                                                         double lat1,
                                                         double lon2,
                                                         double lat2);
CrItem*             geoc_shapes_add_vector              (GeocShapes *shapes,
                                                         GeocVector *vector,
                                                         const gchar *first_arg_name,
                                                         ...);
void                geoc_shapes_update_vector           (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocVector *vector);
CrItem*             geoc_shapes_add_polyline            (GeocShapes *shapes,
                                                         CrPoints *lon_lat_points,
                                                         const gchar *first_arg_name,
                                                         ...);
void                geoc_shapes_update_polyline         (GeocShapes *shapes,
                                                         CrItem *polyline,
                                                         CrPoints *lon_lat_points);
CrItem*             geoc_shapes_add_polygon             (GeocShapes *shapes,
                                                         CrPoints *lon_lat_points,
                                                         const gchar *first_arg_name,
                                                         ...);
void                geoc_shapes_update_polygon          (GeocShapes *shapes,
                                                         CrItem *polygon,
                                                         CrPoints *lon_lat_points);
CrItem*             geoc_shapes_add_rectangle           (GeocShapes *shapes,
                                                         GeocRectangle *rect,
                                                         const gchar *first_arg_name,
                                                         ...);
void                geoc_shapes_update_rectangle        (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocRectangle *rect);
CrItem*             geoc_shapes_add_ellipse             (GeocShapes *shapes,
                                                         GeocRectangle *rect,
                                                         const gchar *first_arg_name,
                                                         ...);
void                geoc_shapes_update_ellipse          (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocRectangle *rect);
CrItem*             geoc_shapes_add_text                (GeocShapes *shapes,
                                                         GeocPoint *point,
                                                         const gchar *first_arg_name,
                                                         ...);
void                geoc_shapes_update_text             (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocPoint *point);
CrItem*             geoc_shapes_add_pixbuf              (GeocShapes *shapes,
                                                         GeocPoint *point,
                                                         const gchar *first_arg_name,
                                                         ...);
void                geoc_shapes_update_pixbuf           (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocPoint *point);
CrItem*             geoc_shapes_add_place               (GeocShapes *shapes,
                                                         GType item_type,
                                                         GeocPoint *point,
                                                         const gchar *first_arg_name,
                                                         ...);
void                geoc_shapes_update_place            (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocPoint *point);
void                geoc_shapes_convert_w2g             (GeocShapes *shapes,
                                                         GeocProjection *projection);
GType               geoc_point_get_type                 (void);
GType               geoc_rectangle_get_type             (void);
GType               geoc_vector_get_type                (void);

Object Hierarchy

  GObject
   +----CrItem
         +----GeocItem
               +----GeocShapes

Properties

  "anchor"                   GtkAnchorType         : Read / Write
  "dash"                     CrDash*               : Read / Write
  "fill-color"               gchar*                : Read / Write
  "fill-color-rgba"          guint                 : Read / Write
  "font"                     gchar*                : Read / Write
  "height"                   gdouble               : Read / Write
  "line-scaleable"           gboolean              : Read / Write
  "line-width"               gdouble               : Read / Write
  "outline-color"            gchar*                : Read / Write
  "outline-color-rgba"       guint                 : Read / Write
  "pattern"                  CrPattern*            : Read / Write
  "pattern-scaleable"        gboolean              : Read / Write
  "pixbuf"                   GObject*              : Read / Write
  "scaleable"                gboolean              : Read / Write
  "test-fill"                gboolean              : Read / Write
  "text"                     gchar*                : Read / Write
  "use-markup"               gboolean              : Read / Write
  "width"                    gdouble               : Read / Write
  "x-offset"                 gdouble               : Read / Write
  "y-offset"                 gdouble               : Read / Write

Description

This class provides generalized methods for drawing and managing primitive features by acting as a geo to item reference manager for most stock CrItem types. As with other GeocItem implementations, properties set on this object will automatically be transferred to the appropriate child objects.

This class provides a set of commonly used properties for the various primitive canvas types. Properties for primitives that are not instantiated may be safely set without seeing warning messages. Any property that is set in the GeocShapes class may be overridden for a subset of primitives by passing that property directly into the 'add' method variable arguments list.

Details

GEOC_TYPE_POINT

#define GEOC_TYPE_POINT (geoc_point_get_type())


GEOC_TYPE_RECTANGLE

#define GEOC_TYPE_RECTANGLE (geoc_rectangle_get_type())


GEOC_TYPE_VECTOR

#define GEOC_TYPE_VECTOR (geoc_vector_get_type())


GeocPoint

typedef struct {
        double lon, lat;
} GeocPoint;


GeocVector

typedef struct {
        double lon, lat, angle, pixels;
} GeocVector;


GeocRectangle

typedef struct {
        double lon1, lat1, lon2, lat2;
} GeocRectangle;


GeocShapes

typedef struct _GeocShapes GeocShapes;


geoc_shapes_item_request_update ()

void                geoc_shapes_item_request_update     (GeocShapes *shapes,
                                                         CrItem *item);

This needs to be called whenever the "geodata" dataset value changes on a CrItem that was created using one of the geoc_shapes convenience functions. It is normally not necessary to call this function. Calling one any of the GeocShapes "update" or "add" functions will call this implicitly.

shapes :

The shapes group that the item belongs to.

item :

The CrItem that has the "geodata" dataset key.

geoc_shapes_add_line ()

CrItem*             geoc_shapes_add_line                (GeocShapes *shapes,
                                                         double lon1,
                                                         double lat1,
                                                         double lon2,
                                                         double lat2,
                                                         const gchar *first_arg_name,
                                                         ...);

Adds a CrLine to the shapes group as specified by the input points. Takes over responsibility for keeping geo to world references in sync. Use the "geodata" dataset key to retrieve a CrPoints reference later.

shapes :

lon1 :

Longitude of the begin point.

lat1 :

Latitude of the begin point.

lon2 :

Longitude of the end point.

lat2 :

Latitude of the end point.

first_arg_name :

A list of object properties name/value pairs, NULL-terminated.

... :

Returns :

A pointer the newly created CrLine item. Use this object reference to change line specific properties or register callbacks. You must call g_object_ref if you intend to use this reference outside the local scope.

geoc_shapes_update_line ()

void                geoc_shapes_update_line             (GeocShapes *shapes,
                                                         CrItem *line,
                                                         double lon1,
                                                         double lat1,
                                                         double lon2,
                                                         double lat2);

Replaces the item's "geodata" dataset value, then calls geoc_shapes_item_request_update.

shapes :

The shapes group to which the line belongs.

line :

The CrItem reference that was returned by calling geoc_shapes_add_line.

lon1 :

Longitude of the begin point.

lat1 :

Latitude of the begin point.

lon2 :

Longitude of the end point.

lat2 :

Latitude of the end point.

geoc_shapes_add_vector ()

CrItem*             geoc_shapes_add_vector              (GeocShapes *shapes,
                                                         GeocVector *vector,
                                                         const gchar *first_arg_name,
                                                         ...);

Adds a CrLine to the shapes group such that the begin point corresponds to the GeocVector lon and lat points and the end point is always at angle degrees from North with a pixel length as specified regardless of the zoom scale.

shapes :

vector :

The lat, lon, angle, and pixel values. Use the "geodata" dataset key to retrieve this later. Note angle is degrees clockwise from North.

first_arg_name :

A list of object properties name/value pairs, NULL-terminated.

... :

Returns :

A pointer the newly created CrLine item. Use this object reference to change line specific properties or register callbacks. You must call g_object_ref if you intend to use this reference outside the local scope.

geoc_shapes_update_vector ()

void                geoc_shapes_update_vector           (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocVector *vector);

Replaces the old "geodata" dataset value, then calls geoc_shapes_item_request_update.

shapes :

The shapes group to which the vector belongs.

item :

The CrItem reference that was returned by calling geoc_shapes_add_vector.

vector :

The lat, lon, angle, and pixel values. Note angle is degrees clockwise from North.

geoc_shapes_add_polyline ()

CrItem*             geoc_shapes_add_polyline            (GeocShapes *shapes,
                                                         CrPoints *lon_lat_points,
                                                         const gchar *first_arg_name,
                                                         ...);

Adds a CrLine to the shapes group as specified by the input lat_lon_points. Takes over responsibility for keeping geo to world references in sync.

shapes :

lon_lat_points :

Array of points in longitude, latitude order. See CrTypes for information on how to build this array. Use the "geodata" dataset key to retrieve this later.

first_arg_name :

A list of object properties name/value pairs, NULL-terminated.

... :

Returns :

A pointer the newly created CrLine item. Use this object to change line specific properties or register callbacks. You must call g_object_ref if you intend to use this reference outside the local scope.

geoc_shapes_update_polyline ()

void                geoc_shapes_update_polyline         (GeocShapes *shapes,
                                                         CrItem *polyline,
                                                         CrPoints *lon_lat_points);

Replaces the array of geographic points with a new array, then calls geoc_shapes_item_request_update.

shapes :

The shapes group to which the polyline belongs.

polyline :

The CrItem reference that was returned by calling geoc_shapes_add_polyline.

lon_lat_points :

Array of points in longitude, latitude order. See CrTypes for information on how to build this array.

geoc_shapes_add_polygon ()

CrItem*             geoc_shapes_add_polygon             (GeocShapes *shapes,
                                                         CrPoints *lon_lat_points,
                                                         const gchar *first_arg_name,
                                                         ...);

Adds a CrLine with the "close" property set to TRUE to the shapes group as specified by the input lat_lon_points. Takes over responsibility for keeping geo to world references in sync.

shapes :

lon_lat_points :

Array of points in longitude, latitude order. See CrTypes for information on how to build this array. Use the "geodata" dataset key to retrieve this later.

first_arg_name :

A list of object properties name/value pairs, NULL-terminated.

... :

Returns :

A pointer the newly created CrLine item. Use this object reference to change polygon specific properties or register callbacks. You must call g_object_ref if you intend to use this reference outside the local scope.

geoc_shapes_update_polygon ()

void                geoc_shapes_update_polygon          (GeocShapes *shapes,
                                                         CrItem *polygon,
                                                         CrPoints *lon_lat_points);

Replaces the array of geographic points with a new array, then calls geoc_shapes_item_request_update.

shapes :

The shapes group to which the polygon belongs.

polygon :

The CrItem reference that was returned by calling geoc_shapes_add_polygon.

lon_lat_points :

Array of points in longitude, latitude order.

geoc_shapes_add_rectangle ()

CrItem*             geoc_shapes_add_rectangle           (GeocShapes *shapes,
                                                         GeocRectangle *rect,
                                                         const gchar *first_arg_name,
                                                         ...);

Adds a CrRectangle to the shapes group as specified by the input struct. Takes over responsibility for keeping geo to world references in sync.

shapes :

rect :

GeocRectangle defines the upper left (lon1, lat1) and lower right (lon2, lat2) coordinate points of the rectangle. Use the "geodata" dataset key to retrieve this later.

first_arg_name :

A list of object properties name/value pairs, NULL-terminated.

... :

Returns :

A pointer the newly created CrRectangle item. Use this object reference to change rectangle specific properties or register callbacks. You must call g_object_ref if you intend to use this reference outside the local scope.

geoc_shapes_update_rectangle ()

void                geoc_shapes_update_rectangle        (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocRectangle *rect);

Replaces the "geodata" dataset value with the the newly provided value, then calls geoc_shapes_item_request_update.

shapes :

The shapes group to which the rectangle belongs.

item :

The CrItem reference that was returned by calling geoc_shapes_add_rectangle.

rect :

GeocRectangle defines the upper left (lon1, lat1) and lower right (lon2, lat2) coordinate points of the rectangle. Use the "geodata" dataset key to retrieve this later.

geoc_shapes_add_ellipse ()

CrItem*             geoc_shapes_add_ellipse             (GeocShapes *shapes,
                                                         GeocRectangle *rect,
                                                         const gchar *first_arg_name,
                                                         ...);

Adds a CrEllipse to the shapes group as specified by the input struct. Takes over responsibility for keeping geo to world references in sync.

shapes :

rect :

Defines the upper left and lower right corners of the rectangle that bounds the ellipse. Use the "geodata" dataset key to retrieve this later.

first_arg_name :

A list of object properties name/value pairs, NULL-terminated.

... :

Returns :

A pointer the newly created CrEllipse item. Use this object reference to change ellipse specific properties or register callbacks. You must call g_object_ref if you intend to use this reference outside the local scope.

geoc_shapes_update_ellipse ()

void                geoc_shapes_update_ellipse          (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocRectangle *rect);

Replaces the "geodata" dataset value with the the newly provided value, then calls geoc_shapes_item_request_update.

shapes :

The shapes group to which the ellipse belongs.

item :

The CrItem reference that was returned by calling geoc_shapes_add_ellipse.

rect :

Defines the upper left and lower right corners of the rectangle that bounds the ellipse. Use the "geodata" dataset key to retrieve this later.

geoc_shapes_add_text ()

CrItem*             geoc_shapes_add_text                (GeocShapes *shapes,
                                                         GeocPoint *point,
                                                         const gchar *first_arg_name,
                                                         ...);

Adds a CrText to the shapes group as specified by the input struct. Takes over responsibility for keeping geo to world references in sync.

shapes :

point :

The longitude and latitude of the anchor point for the text. Use the "geodata" dataset key to retrieve this later.

first_arg_name :

A list of object properties name/value pairs, NULL-terminated.

... :

Returns :

A pointer the newly created CrText item. Use this object reference to change text specific properties or register callbacks. You must call g_object_ref if you intend to use this reference outside the local scope.

geoc_shapes_update_text ()

void                geoc_shapes_update_text             (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocPoint *point);

Replaces the "geodata" dataset value with the the newly provided value, then calls geoc_shapes_item_request_update.

shapes :

The shapes group to which the text belongs.

item :

The CrItem reference that was returned by calling geoc_shapes_add_text.

point :

The longitude and latitude of the anchor point for the text. Use the "geodata" dataset key to retrieve this later.

geoc_shapes_add_pixbuf ()

CrItem*             geoc_shapes_add_pixbuf              (GeocShapes *shapes,
                                                         GeocPoint *point,
                                                         const gchar *first_arg_name,
                                                         ...);

Adds a CrPixbuf to the shapes group as specified by the input struct. Takes over responsibility for keeping geo to world references in sync.

shapes :

point :

The longitude and latitude of the anchor point for the pixbuf. Use the "geodata" dataset key to retrieve this later.

first_arg_name :

A list of object properties name/value pairs, NULL-terminated.

... :

Returns :

A pointer the newly created CrPixbuf item. Use this object reference to change pixbuf specific properties or register callbacks. You must call g_object_ref if you intend to use this reference outside the local scope.

geoc_shapes_update_pixbuf ()

void                geoc_shapes_update_pixbuf           (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocPoint *point);

Replaces the "geodata" dataset value with the the newly provided value, then calls geoc_shapes_item_request_update.

shapes :

The shapes group to which the pixbuf belongs.

item :

The CrItem reference that was returned by calling geoc_shapes_add_pixbuf.

point :

The longitude and latitude of the anchor point for the pixbuf. Use the "geodata" dataset key to retrieve this later.

geoc_shapes_add_place ()

CrItem*             geoc_shapes_add_place               (GeocShapes *shapes,
                                                         GType item_type,
                                                         GeocPoint *point,
                                                         const gchar *first_arg_name,
                                                         ...);

Adds a CrItem to the shapes group as specified by the item_type. The canvas item type must have 'x' and 'y' coordinate properties. The parent group then over responsibility for keeping geo to world references in sync.

Note that it is not possible to add geographically referenced items as children to a CrItem object although the 0, 0 location of this top level item will be refernced to the coordinates provided by point.

shapes :

item_type :

A CrItem type_id that has x,y properties.

point :

The longitude and latitude of the anchor point for the place. Use the "geodata" dataset key to retrieve this later.

first_arg_name :

A list of object properties name/value pairs, NULL-terminated.

... :

Returns :

A pointer the newly created CrItem item. Use this object reference to change pixbuf specific properties or register callbacks. You must call g_object_ref if you intend to use this reference outside the local scope.

geoc_shapes_update_place ()

void                geoc_shapes_update_place            (GeocShapes *shapes,
                                                         CrItem *item,
                                                         GeocPoint *point);

Replaces the "geodata" dataset value with the the newly provided value, then calls geoc_shapes_item_request_update.

shapes :

The shapes group to which the place belongs.

item :

The CrItem reference that was returned by calling geoc_shapes_add_place.

point :

The longitude and latitude of the anchor point for the place. Use the "geodata" dataset key to retrieve this later.

geoc_shapes_convert_w2g ()

void                geoc_shapes_convert_w2g             (GeocShapes *shapes,
                                                         GeocProjection *projection);

Immediately converts the present canvas world coordinates to geographic coordinates and stores them in the "geodata" dataset for each primitive object. The geo coordinates are used henceforth to maintain a consistent geographic position on the canvas. This function should be called each time a shape is manipulated using world coordinates. An example case for manipulating a shape with world coordinates might be a pointer controlled move or resize operation.

shapes :

projection :

The projection to use. This usually comes from the GeocCanvas.

geoc_point_get_type ()

GType               geoc_point_get_type                 (void);

Returns :


geoc_rectangle_get_type ()

GType               geoc_rectangle_get_type             (void);

Returns :


geoc_vector_get_type ()

GType               geoc_vector_get_type                (void);

Returns :

Property Details

The "anchor" property

  "anchor"                   GtkAnchorType         : Read / Write

The part of the pixbuf that is referenced to the item's x, y coordinates.

Default value: GTK_ANCHOR_NORTH_WEST


The "dash" property

  "dash"                     CrDash*               : Read / Write

a boxed array indicating the dash pattern to be used by Cairo. See #cairo_set_dash for more information.


The "fill-color" property

  "fill-color"               gchar*                : Read / Write

A string color such as 'red', or '#123456' to be used to fill the path.

Default value: NULL


The "fill-color-rgba" property

  "fill-color-rgba"          guint                 : Read / Write

Region fill color, red,grn,blue,alpha.

Default value: 0


The "font" property

  "font"                     gchar*                : Read / Write

A pango font description string of the form [FAMILY-LIST] [STYLE-OPTIONS] [SIZE].

Default value: NULL


The "height" property

  "height"                   gdouble               : Read / Write

Height of rectangle in item units. Note this is half above #CrItem:y and half below #CrItem:y.

Default value: 2


The "line-scaleable" property

  "line-scaleable"           gboolean              : Read / Write

If line width should be scaleable.

Default value: TRUE


The "line-width" property

  "line-width"               gdouble               : Read / Write

Path line width in user units when #CrPath:line-scaleable is TRUE. When #CrPath:line-scaleable is FALSE this is in device units.

Default value: 2


The "outline-color" property

  "outline-color"            gchar*                : Read / Write

A string color such as 'red', or '#123456' to be used to sroke the path.

Default value: NULL


The "outline-color-rgba" property

  "outline-color-rgba"       guint                 : Read / Write

Path color, red,grn,blue,alpha.

Default value: 0


The "pattern" property

  "pattern"                  CrPattern*            : Read / Write

Cairo pattern to fill the path region.


The "pattern-scaleable" property

  "pattern-scaleable"        gboolean              : Read / Write

If pattern should scale.

Default value: TRUE


The "pixbuf" property

  "pixbuf"                   GObject*              : Read / Write

The GDK Pixbuf to draw. For images that are in other formats it may be more convenient to use the #CrPixbuf:png or #CrPixbuf:surface properties directly.


The "scaleable" property

  "scaleable"                gboolean              : Read / Write

When True the size of the text is in item units. When False, the size is in device/pixel units. This effects x/y_offset as well. See also @CrInverse for another way to achieve the same effect.

Default value: TRUE


The "test-fill" property

  "test-fill"                gboolean              : Read / Write

If the fill area should be grabbable by the pointer regardless of if it is filled. The most common use for this is as an invisible child of a very small item that would be difficult to grab on its own.

Default value: FALSE


The "text" property

  "text"                     gchar*                : Read / Write

The text to be drawn.

Default value: NULL


The "use-markup" property

  "use-markup"               gboolean              : Read / Write

If html style markup language should be used.

Default value: FALSE


The "width" property

  "width"                    gdouble               : Read / Write

Width of rectangle in item units. Note this is half to the left of #CrItem:x and half to the right of #CrItem:x.

Default value: 2


The "x-offset" property

  "x-offset"                 gdouble               : Read / Write

A device offset from the item's anchor position. Only used when scaleable=FALSE.

Default value: 0


The "y-offset" property

  "y-offset"                 gdouble               : Read / Write

A device offset from the item's anchor position. Only used when scaleable=FALSE.

Default value: 0