Class CMUtilities
CMUtilities Class
General utilities. This includes:
- Color Utilities
- Coordinate conversions (DMS to DD, DD to DMS, and visualizations)
- Functions for managing Bounds objects with "XMin,YMin,XMax,YMax"
- Functions to absolutely position elements over the CanvasMap
- High level GUI map functions such as legends and info boxes
- Settings functions
- Properties functions
- Some simple JavaScript utilities that may move to Spa as soon as needed
Copyright (C) 2020, Humboldt State University, Jim Graham
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation, either version 3 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see
Enumerated Types
CMUtilities.COORDINATE_UNITS_DD=0CMUtilities.COORDINATE_UNITS_DMS=1
CMUtilities.COORDINATE_UNITS_METERS=2
CMUtilities.COORDINATE_UNITS_FEET=3
CMUtilities.COORDINATE_UNITS_PIXELS=4 - displays the pixel level coordinates for debugging
CMUtilities.COORDINATE_UNITS_ZOOM=5 - displays the zoom level for debugging
Static Functions
| Returns | Function | Throws |
|---|---|---|
| Colors | GetColorsFromArrays(FeatureValues, TheColors, Intervals) | |
| AbsolutePosition(TheElement, Left, Top, Width, Height) | ||
| Coordinate | GetElementCoordinate() | |
| TheElement | CreateLabelControl(Text, Position, X, Y) | |
| LegendElement | AddLegend(TheCanvasElement, TheColors, LegendLabels, X,Y,Width,Height) | |
| TheElement | CreateInfoWindow(ID, Left, Top, Width, Height, Text) | |
| CoordinateString | GetCoordinateString(-, -, -, -, -) | |
| Flag | BoundsIncludes(ExteriorBounds, InteriorBounds) | |
| Flag | BoundsOverlap(Bounds1, Bounds2) | |
| ClonedBounds | CloneBounds(TheBounds) | |
| TheBounds | AddToBounds(TheBounds, NewBounds) | |
| ExpandBounds(TheBounds, Amount) | ||
| A | IntersectBounds(TheBounds1, TheBounds2) | |
| true | InBounds(TheBounds, RefX,RefY) | |
| Seconds | GetSeconds() | |
| Flag | IsValid(Value) | |
| ClonedObject | Clone() |
Static Functions
Colors=GetColorsFromArrays(FeatureValues, TheColors, Intervals)
Creates an array of colors from a set of feature values, a set of colors, and defined intervals.
The returned result
Used to create legends.
Parameters:
FeatureValues - array of values for the features, typically from an attribute
TheColors - array of colors for the FeatureValues
Intervals - optional array of intervals that bracket the colors. If not specified, the intervals will be defined to cover the range of FeatureValues
Returns: Colors - { LegendLabels,FeatureColors} where LegendLabels an array of names appropriate for a legend and FeatureColors is an array to colorize each of the features
AbsolutePosition(TheElement, Left, Top, Width, Height)
Make an element be positioned abosolutely
Parameters:
TheElement - the DOM element to position
Left - left position in pixels
Top - Top position in pixels
Width - Width in pixels
Height - Height in pixels
Coordinate=GetElementCoordinate()
Moves the global coordinate to be local with the specified element
Returns: Coordinate - Global coordinate as {x,y}
TheElement=CreateLabelControl(Text, Position, X, Y)
Creates a DOM element at the specified location
Parameters:
Text - the text displayed in the element
Position - CSS position parameter
X - pixel-based horizontal position
Y - pixel-based vertical position
Returns: TheElement - DOM element (DIV)
LegendElement=AddLegend(TheCanvasElement, TheColors, LegendLabels, X,Y,Width,Height)
Adds a legend to a DOM element. This is a basic legend and this function may be expanded in the future.
Parameters:
TheCanvasElement - the element to add the legend to
TheColors - array of colors for the legend
LegendLabels - labels to go next to the legend colors
X,Y,Width,Height - position and dimensions of the legend in pixels
Returns: LegendElement - a new DOM element.
TheElement=CreateInfoWindow(ID, Left, Top, Width, Height, Text)
Dimensions are for the box, the triangle will be placed below it
Parameters:
ID - The name of the balloon element to create (typically each map has a unique ID)
Left - location to tie the tooltip to (typically the X coordinate of the mouse down)
Top - location to tie the tooltip to (typically the Y coordinate of the mouse down)
Width - desired width of the tool tip (in future versions, the tooltip may be smaller
Height - ignored, the tooltip now sizes with it's contents
Text - the HTML to place int he tooltip
Returns: TheElement - DOM element (DIV)
CoordinateString=GetCoordinateString(-, -, -, -, -)
Gets a text string with the specified units for display.
Parameters:
- RefX - East/West coordinate value
- RefY - North/South coordinate value
- CoordinateUnits - The desired coordinate units from CMUtilities.COORDINATE_UNITS
- TheProjector - Optional projector if the coodinates need to be converted.
- TheView - Optional parameter if the zoom level or pixel location is desired.
Returns: CoordinateString - null
Flag=BoundsIncludes(ExteriorBounds, InteriorBounds)
Determines if the second bounds is included within the first bounds.
Parameters:
ExteriorBounds
InteriorBounds
Returns: Flag - true if the interior bounds is inside the exterior bounds (they can touch and this can still be true)
Flag=BoundsOverlap(Bounds1, Bounds2)
Returns true if the two bounds objects overlap
Parameters:
Bounds1
Bounds2
Returns: Flag - true if the bounds overlap, false otherwise
ClonedBounds=CloneBounds(TheBounds)
Returns a clone of the specified bounds object.
Parameters:
TheBounds
Returns: ClonedBounds - null
TheBounds=AddToBounds(TheBounds, NewBounds)
Makes sure that the area of the specified bounds is within the returned bounds.
Parameters:
TheBounds
NewBounds
Returns: TheBounds - Bounds with the NewBounds included
ExpandBounds(TheBounds, Amount)
Expands the bounds by the specified amount
Parameters:
TheBounds
Amount - amount to expand the bounds in each direction
A=IntersectBounds(TheBounds1, TheBounds2)
Find the bounds that is the intersection of the two bounds.
Parameters:
TheBounds1
TheBounds2
Returns: A - bounds that is the intersection of the two or null if there is no intersection
true=InBounds(TheBounds, RefX,RefY)
Checks if the specific point is inside the specific bounding rect.
Parameters:
TheBounds
RefX,RefY - Points to check
Returns: true - if the point is inside (or touching the edge of) the bounds.
Seconds=GetSeconds()
Return the current number of seconds for timing code
Returns: Seconds - number of seconds
Flag=IsValid(Value)
Checks to see if a value is value (i.e. not NaN or null)
(jjg - combine with IsDefined()?)
Parameters:
Value
Returns: Flag - null
ClonedObject=Clone()
Create a clone of the specified object. For non-objects, returns the specified object.
Will do a deep clone on arrays (which are objects in JavaScript) and dictionaries (also objects)
Adapted from: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty
Returns: ClonedObject - null