GeocCanvas

GeocCanvas — A GTK widget that holds a GeocItem tree.

Synopsis

                    GeocCanvas;
GtkWidget*          geoc_canvas_new                     ();
void                geoc_canvas_set_scroll_region       (GeocCanvas *canvas,
                                                         gdouble scroll_lon1,
                                                         gdouble scroll_lat1,
                                                         gdouble scroll_lon2,
                                                         gdouble scroll_lat2);
void                geoc_canvas_get_scroll_region       (GeocCanvas *canvas,
                                                         gdouble *scroll_lon1,
                                                         gdouble *scroll_lat1,
                                                         gdouble *scroll_lon2,
                                                         gdouble *scroll_lat2);
void                geoc_canvas_scroll_to               (GeocCanvas *canvas,
                                                         gdouble lon,
                                                         gdouble lat);
void                geoc_canvas_get_scroll_offsets      (GeocCanvas *canvas,
                                                         gdouble *lon,
                                                         gdouble *lat);
void                geoc_canvas_center_on               (GeocCanvas *canvas,
                                                         gdouble lon,
                                                         gdouble lat);
void                geoc_canvas_get_center              (GeocCanvas *canvas,
                                                         gdouble *lon,
                                                         gdouble *lat);
void                geoc_canvas_set_viewport            (GeocCanvas *canvas,
                                                         gdouble lon1,
                                                         gdouble lat1,
                                                         gdouble lon2,
                                                         gdouble lat2);
gboolean            geoc_canvas_get_viewport            (GeocCanvas *canvas,
                                                         gdouble *lon1,
                                                         gdouble *lat1,
                                                         gdouble *lon2,
                                                         gdouble *lat2);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----CrCanvas
                           +----GeocCanvas

Implemented Interfaces

GeocCanvas implements AtkImplementorIface and GtkBuildable.

Signals

  "rebuild-g2w"                                    : Run Last

Description

The GeocCanvas widget adds geographically referenced scroll area and viewport management to the CrCanvas. Such functionality becomes relevant when dealing with geography because the 'geo' view is bounded by longitude and latitude coordinates. Any stock CrItem can be represented on the GeocCanvas; however, all items should be made aware of the additional mapping between user corrdinates and geo coordinates. The GeocPlaces, GeocShapes, and GeocLines canvas items will automatically manage the user to geo coordinate mappings.

When the canvas is created, you may set it up for 'infinite world' scrolling or for restricted world scrolling.

This example allows for infinite world. The scrollbars will always be 1/3 the size of the window. In inifinite world mode, the Earth can be panned about as if it were a sphere or a cylinder depending on the type of projection being used:

canvas = geoc_canvas_new();
geoc_set_scroll_factor(GEOC_CANVAS(canvas), 3, 3);

This example forces the map to be restricted to a specific geographic region:

canvas = geoc_canvas_new();
geoc_set_scroll_region(GEOC_CANVAS(canvas), -88, 26, -72, 18);

To convert between geographic and canvas world coordinates, the GeocProjection instance for the canvas can be accessed directly by using the canvas->projection struct variable.

Details

GeocCanvas

typedef struct {
        /* Access this member directly to convert between geographic
         * and canvas coordinates.
         */
        GeocProjection *projection;
        cairo_t *dataset;

        double proj_minx, proj_miny, proj_maxx, proj_maxy;
        double scroll_lon1, scroll_lat1, scroll_lon2, scroll_lat2;
        double center_lon, center_lat;
        gint flags;
} GeocCanvas;


geoc_canvas_new ()

GtkWidget*          geoc_canvas_new                     ();

A convenience function to create a new GeocCanvas widget.

Returns :

A newly created GeocCanvas widget.

geoc_canvas_set_scroll_region ()

void                geoc_canvas_set_scroll_region       (GeocCanvas *canvas,
                                                         gdouble scroll_lon1,
                                                         gdouble scroll_lat1,
                                                         gdouble scroll_lon2,
                                                         gdouble scroll_lat2);

Sets the canvas to a finite geo. Use this procedure if your available maps do not cover the Earth. If you wish to provide scrolling for the whole Earth then use cr_canvas_set_scroll_factor. The scrollbars or adjustments will not allow the canvas to scroll outside the input boundaries. Any scaling may be performed by calling convenience functions provided by GeocCanvas or CrCanvas.

canvas :

scroll_lon1 :

The leftmost geographic boundary in degrees.

scroll_lat1 :

The topmost geographic boundary in degrees.

scroll_lon2 :

The rightmost geographic boundary in degrees.

scroll_lat2 :

The bottomost geographic boundary in degrees.

geoc_canvas_get_scroll_region ()

void                geoc_canvas_get_scroll_region       (GeocCanvas *canvas,
                                                         gdouble *scroll_lon1,
                                                         gdouble *scroll_lat1,
                                                         gdouble *scroll_lon2,
                                                         gdouble *scroll_lat2);

Gets the current scrolling area of the canvas. A wrapper over cr_canvas_get_scroll_region.

canvas :

scroll_lon1 :

The leftmost geographic boundary in degrees.

scroll_lat1 :

The topmost geographic boundary in degrees.

scroll_lon2 :

The rightmost geographic boundary in degrees.

scroll_lat2 :

The bottomost geographic boundary in degrees.

geoc_canvas_scroll_to ()

void                geoc_canvas_scroll_to               (GeocCanvas *canvas,
                                                         gdouble lon,
                                                         gdouble lat);

Places the given coordinate in the upper left corner of the current viewport. A wrapper over cr_canvas_scroll_to.

canvas :

lon :

The geographic coordinate for the left border in degrees

lat :

The geographic coordinate for the upper border in degrees

geoc_canvas_get_scroll_offsets ()

void                geoc_canvas_get_scroll_offsets      (GeocCanvas *canvas,
                                                         gdouble *lon,
                                                         gdouble *lat);

A convenience function to get the upper leftmost canvas coordinate in geographic coordinates. A wrapper function over cr_canvas_get_scroll_offsets.

canvas :

lon :

The geographic coordinate of the left border in degrees

lat :

The geographic coordinate of the upper border in degrees

geoc_canvas_center_on ()

void                geoc_canvas_center_on               (GeocCanvas *canvas,
                                                         gdouble lon,
                                                         gdouble lat);

Places the given coordinate in the center of the current viewport. A wrapper for cr_canvas_center_on.

canvas :

lon :

The coordinate to set center to in degrees.

lat :

The coordinate to set center to in degrees.

geoc_canvas_get_center ()

void                geoc_canvas_get_center              (GeocCanvas *canvas,
                                                         gdouble *lon,
                                                         gdouble *lat);

Convenience function to get the center point of the viewport. A wrapper around cr_canvas_get_center:.

canvas :

lon :

The coordinate of the center in degrees.

lat :

The coordinate of the center in degrees.

geoc_canvas_set_viewport ()

void                geoc_canvas_set_viewport            (GeocCanvas *canvas,
                                                         gdouble lon1,
                                                         gdouble lat1,
                                                         gdouble lon2,
                                                         gdouble lat2);

Attempt to set the viewport to show the provided coordinates. The scale request will be honored such that an equal to or larger area will be shown in the viewport. A wrapper for cr_canvas_set_viewport which causes the projection center point to be reset.

canvas :

lon1 :

The leftmost geographic coordinate in degrees.

lat1 :

The topmost geographic coordinate in degrees.

lon2 :

The rightmost geographic coordinate in degrees.

lat2 :

The bottommost geographic coordinate in degrees.

geoc_canvas_get_viewport ()

gboolean            geoc_canvas_get_viewport            (GeocCanvas *canvas,
                                                         gdouble *lon1,
                                                         gdouble *lat1,
                                                         gdouble *lon2,
                                                         gdouble *lat2);

The four corners of the current viewport in geographic coordinates. A wrapper over cr_canvas_get_viewport.

return: FALSE sometimes for hemispheric projections if the corners of the viewport do not correspond to points on the Earth.

canvas :

lon1 :

The leftmost coordinate in degrees.

lat1 :

The topmost coordinate in degrees.

lon2 :

The rightmost coordinate in degrees.

lat2 :

The bottommost coordinate in degrees.

Returns :

Signal Details

The "rebuild-g2w" signal

void                user_function                      (GeocCanvas *canvas,
                                                        gpointer    user_data)      : Run Last

This signal is emitted by the canvas whenever the projection has changed such that it is necessary to re-convert tan items geographic coordinates to world coordinates. Its default behavior is to call geoc_item_invoke_rebuild_g2w on the canvas root item.

canvas :

user_data :

user data set when the signal handler was connected.